docs(P00): clarify — 6 ambiguities auto-resolved (full autonomy)
---ci--- project: acdl phase: 0 milestone: v1.24 status: clarify ---/ci---
This commit is contained in:
Jon Chery
@@ -1,12 +1,14 @@
|
||||
{
|
||||
"phase": 0,
|
||||
"stage": "specify",
|
||||
"stage": "clarify",
|
||||
"milestone": "v1.24",
|
||||
"phase_role": "pre_execution",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-12T02:00:00Z",
|
||||
"updated_at": "2026-08-12T02:05:00Z",
|
||||
"project": "acdl",
|
||||
"milestone_complete": false,
|
||||
"tag_line": "v1.23.x",
|
||||
"requirements": ["REQ-276","REQ-277","REQ-278","REQ-279","REQ-280","REQ-281","REQ-282","REQ-283","REQ-284","REQ-285","REQ-286","REQ-287","REQ-288","REQ-289","REQ-290"]
|
||||
"requirements": ["REQ-276","REQ-277","REQ-278","REQ-279","REQ-280","REQ-281","REQ-282","REQ-283","REQ-284","REQ-285","REQ-286","REQ-287","REQ-288","REQ-289","REQ-290"],
|
||||
"clarify_resolutions": 6,
|
||||
"clarify_escalations": 0
|
||||
}
|
||||
+100
-68
@@ -1,77 +1,109 @@
|
||||
# CLARIFY — v1.23 (auto-resolved, full autonomy)
|
||||
# CLARIFY — v1.24 Consumer Guide Accuracy & Env-Promotion Lifecycle Enforcement
|
||||
|
||||
8 ambiguities identified, all auto-resolved at confidence ≥ 0.6.
|
||||
No human escalation (full autonomy). All decisions logged below.
|
||||
> **Autonomy:** full. Ambiguities are auto-resolved with assumption logging
|
||||
> per `config.json autonomy.level: "full"`. No human escalation.
|
||||
|
||||
## C1 — Speaker notes source for HTML comments (conf 0.95)
|
||||
**Ambiguity:** The plain `.md` has `> **Speaker notes:**` and
|
||||
`> **Transition:**` blocks per slide; talking points live in a separate
|
||||
file. Which content goes into the `<!-- ... -->` comments?
|
||||
**Resolution:** Extract `> **Speaker notes:**` and `> **Transition:**`
|
||||
blocks from the plain `.md` and embed each slide's as
|
||||
`<!-- Speaker notes: ... -->` before the next `---` separator. Talking
|
||||
points come from `talking-points.md` (the 3-6 bullets per slide)
|
||||
embedded as `<!-- Talking points: ... -->`. Both are Marp HTML comments
|
||||
(excluded from slide rendering; the `talking-points.md` stays as the
|
||||
standalone synced aid).
|
||||
## Ambiguities Identified
|
||||
|
||||
## C2 — python-pptx dependency placement (conf 0.9)
|
||||
**Ambiguity:** `pyproject.toml` has `[project.optional-dependencies]`
|
||||
`test`. Where does `python-pptx` go?
|
||||
**Resolution:** Add a new optional-dependency group
|
||||
`slides = ["python-pptx>=0.6.23"]`. Keeps the base `dependencies`
|
||||
minimal (the render script is a docs-only concern, not a runtime
|
||||
dep). CI installs via `pip install -e .[slides]`. The `render_pptx.py`
|
||||
script imports `pptx` at module load (not a hard failure if absent —
|
||||
the script prints a clear "pip install -e .[slides]" message and exits
|
||||
1).
|
||||
### A1 — Step 8 "change environment" vs Per-env section "no field editing"
|
||||
|
||||
## C3 — Benefit callout markdown representation (conf 0.9)
|
||||
**Ambiguity:** Marp markdown can't natively produce arbitrary `<div>`.
|
||||
How is the `.benefit` class applied?
|
||||
**Resolution:** Use Marp's HTML-in-markdown support — write benefit
|
||||
lines as `<div class="benefit">text</div>` directly in the markdown
|
||||
(Marp passes through HTML blocks). The inline `style:` block targets
|
||||
`.benefit`. The `**Benefit:**` prefix is removed.
|
||||
**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.
|
||||
|
||||
## C4 — Image inlining MIME types (conf 0.95)
|
||||
**Ambiguity:** What MIME types does `inline_images.py` handle?
|
||||
**Resolution:** The deck references `.png` files only (mermaid
|
||||
renders). `inline_images.py` MIME-sniffs by extension:
|
||||
`.png`→`image/png`, `.svg`→`image/svg+xml`, `.jpg/.jpeg`→`image/jpeg`,
|
||||
`.gif`→`image/gif`; fallback `application/octet-stream`. Only relative
|
||||
`src="assets/..."` paths are inlined (absolute/`http(s)://` URLs are
|
||||
left alone).
|
||||
**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.
|
||||
|
||||
## C5 — render_slides.sh step ordering (conf 0.9)
|
||||
**Ambiguity:** Where do the new inline-images + python-pptx steps go?
|
||||
**Resolution:** Step 1 mermaid → PNG (unchanged); Step 2 MARP → HTML +
|
||||
PPTX (drop `--theme`); Step 3 inline images into HTML; Step 4
|
||||
python-pptx → `*-python.pptx`; Step 5 stage all. The inline step runs
|
||||
only on the HTML (not the PPTX — both PPTX formats embed media in
|
||||
their zip by construction).
|
||||
**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.
|
||||
|
||||
## C6 — absence-of-loaded-term test scope (conf 0.95)
|
||||
**Ambiguity:** How is absence of the purged loaded term asserted?
|
||||
**Resolution:** A grep for the purged term's stem across
|
||||
`docs/presentations/` returns nothing (covers `.md`, `-marp.md`,
|
||||
`talking-points.md`, `.html`; `.pptx` is binary so excluded). A new test
|
||||
`test_no_purged_loaded_term` asserts this.
|
||||
### A2 — Prior-env source of truth: DynamoDB vs state-bucket scan vs SSM
|
||||
|
||||
## C7 — attach_release_asset.py dual-PPTX (conf 0.85)
|
||||
**Ambiguity:** Does the release attach both PPTX files?
|
||||
**Resolution:** Yes — attach both `.pptx` (MARP image-of-slide) and
|
||||
`-python.pptx` (structured). Minimal change: loop over both filenames.
|
||||
The MARP PPTX remains the "primary" attachment (first); the python
|
||||
PPTX is secondary (comparison artifact).
|
||||
**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.
|
||||
|
||||
## C8 — Wave ordering (conf 0.85)
|
||||
**Ambiguity:** Can P1 (consolidate) and P2 (style) parallelize?
|
||||
**Resolution:** No — both edit `-marp.md` with a serial dependency: P1
|
||||
establishes the single doc (deletes the plain `.md`, adds HTML-comment
|
||||
speaker notes); P2 edits that single doc's frontmatter + benefit
|
||||
callouts. Order: P1 → P2 → (P3 + P4 parallel: P3 edits
|
||||
`scripts/inline_images.py` + `render_pptx.py` + `render_slides.sh` +
|
||||
`pyproject`; P4 edits the deck markdown — zero file overlap) → P5 →
|
||||
P6. P3 depends on P2's render-script `--theme` drop. P4 depends on
|
||||
P1's consolidated doc.
|
||||
**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.
|
||||
Reference in New Issue
Block a user