acdl/.ciagent/CLARIFY.md

CLARIFY — v1.23 (auto-resolved, full autonomy)

8 ambiguities identified, all auto-resolved at confidence ≥ 0.6. No human escalation (full autonomy). All decisions logged below.

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).

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).

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.

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).

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).

C6 — "penetrate" absence test scope (conf 0.95)

Ambiguity: How is "penetrate" absence asserted? Resolution: grep -ri penetrat docs/presentations/ returns nothing (covers .md, -marp.md, talking-points.md, .html; .pptx is binary so excluded). A new test test_no_penetrate_term asserts this.

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).

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.