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.