acdl/.ciagent/CLARIFY.md

CLARIFY — v1.24 Consumer Guide Accuracy & Env-Promotion Lifecycle Enforcement

Autonomy: full. Ambiguities are auto-resolved with assumption logging per config.json autonomy.level: "full". No human escalation.

Ambiguities Identified

A1 — Step 8 "change environment" vs Per-env section "no field editing"

Ambiguity: The consumer guide contains two mutually-exclusive promotion models. Step 8 (line 290) says "Change environment in your contract." The "Per-environment deployment" section (line 398) says "you do not edit the environment: field… Promotion = running the matching job." The test test_consumer_guide_states_no_field_editing asserts the no-editing model.

User directive (binding): Both shapes are supported. Shape A (edit environment in-place) is valid AND must trigger a destroy of the prior env. Shape B (per-env caller workflows) is the alternative. The test must be updated to assert both shapes.

Resolution (auto, confidence 0.95): Adopt the user's directive. Step 8 is rewritten to document Shape A with destroy-then-rebuild semantics. The per-env section is preserved as Shape B with a lead sentence distinguishing it. The test is renamed and a new test asserts the destroy semantics. This is already captured in REQ-279, REQ-280, REQ-290.

A2 — Prior-env source of truth: DynamoDB vs state-bucket scan vs SSM

Ambiguity: Three options for detecting the prior environment: (a) query the nova-contracts DynamoDB table, (b) scan the state bucket for other env prefixes, (c) record last-applied env in an SSM parameter.

Resolution (auto, confidence 0.85): DynamoDB nova-contracts table (user-selected). It already exists, is written by the contract ingestor Lambda (core/lambda/contract_ingestor.py:160-170), and has the right shape (PK consumerRepo, SK contractId#submittedAt, environment attribute). A new #LAST_APPLIED SK suffix is added for the record-applied-env step (REQ-283). This avoids coupling the platform to a specific state-bucket layout (which differs across envs/accounts) and avoids a new SSM dependency.

Assumption: The nova-contracts table is accessible from the deploy role via the same ABAC scoping that the contract ingestor uses. If the table is not accessible (e.g., local/CI mode without DynamoDB), the detect step logs a warning and returns None (conservative — no prior env assumed). This is documented in REQ-282.

A3 — Cross-account destroy

Ambiguity: If the prior env (e.g., dev) and new env (e.g., qa) are in different AWS accounts, the destroy step needs the prior env's role credentials. The current scaffold uses one account.

Resolution (auto, confidence 0.80): v1.24 targets the same-account case. Cross-account destroy is explicitly out of scope (documented in the Out of Scope section). The run_platform.sh Step 0b notes this limitation. A future milestone handles cross-account destroy via a pre-step that assumes the prior env's role. This is the pragmatic path — the scaffold (core/environments/dev.json) is single-account today.

A4 — Version tag in docs: @v1.19 vs ref: v1.9

Ambiguity: The consumer guide says uses: nova/.github/workflows/deploy.yml@v1.19 but the actual .github/workflows/deploy.yml checks out the platform repo at ref: v1.9. The reference table says sample contracts "use @v1.19" but the sample contracts don't carry uses: (they're contracts, not workflows).

Resolution (auto, confidence 0.90): REQ-281 corrects the reference table wording to "used with caller workflow @v1.19" (the version pin lives in the caller workflow, not the contract). The @v1.19 tag in the consumer-facing docs is the documented current version; the ref: v1.9 in deploy.yml is the platform-internal checkout ref. These are two different references (consumer → platform workflow tag; platform workflow → platform repo ref). The guide's @v1.19 stays as the consumer-facing version. No change to deploy.yml's ref: v1.9 (that's an internal platform concern, out of scope for this milestone).

A5 — Should Shape A destroy go through the HITL decommission pipeline?

Ambiguity: The decommission pipeline (2-step, HITL SRE gates) exists for stack teardown. Should env-transition destroy use it?

Resolution (auto, confidence 0.85): No. Env-transition is an automated lifecycle step, not an explicit decommission. The destroy runs as a direct terraform destroy -auto-approve against the prior env's state (REQ-284). The decommission pipeline remains for explicit stack teardown with SRE gates. This is documented in the Out of Scope section. Rationale: the consumer already has HITL attestation on the new env (qa/prod/dr gates); requiring a second SRE gate for the prior env's destroy would block autonomous dev→qa promotion, contradicting the "lower environments are autonomous" tenet.

A6 — Phase count and ordering

Ambiguity: The requirements traceability table shows 3 phases (P1: docs, P2: feat, P3: test) but the roadmap entry says "4 phases."

Resolution (auto, confidence 0.90): 4 phases = P0 (pre-execution) + P1 (docs fixes) + P2 (env-transition feat) + P3 (tests) + P4 (final review/ship). The "4 phases" in the roadmap counts execution phases (P1-P3)

• final (P4). This matches the run.md phase model (P0 pre-execution, P1..PN execution, P N+1 final). The traceability table lists P1-P3 (execution); P4 is the final phase (review + audit + ship, no new requirements).

Clarification Commit

No changes to REQUIREMENTS.md or PROJECT.md from clarify — the ambiguities are resolved and already captured in the requirements (REQ-276..290) and the Out of Scope section. The resolutions above are logged for traceability.