acdl/.ciagent/PLAN.md

PLAN — v1.30 Single-shot Leadership Deck

Milestone: v1.30 (feature — single-shot PPTX leadership deck). Tags on the v1.29.x line: v1.29.1 (P0) → v1.29.2 (P1 execution) → v1.29.3 (P2 final = milestone release). The final phase's patch IS the milestone release. Branch: milestone/v1.30-leadership-deck. Phase branches: phase/00-pre-execution, phase/01-leadership-deck, phase/02-final-review-ship.

Tags: v1.29.1 (P0) → v1.29.2 (P1) → v1.29.3 (P2 final = milestone release). 1 execution phase (P1) — this is a single-shot artifact, not a multi-phase build.

Milestone goal

A single-shot, 7-slide PPTX leadership deck for Infrastructure & Operations leadership (CTO + VP Technology + Product Management), presented live in August 2026, securing architecture endorsement and a November 2026 runway. Authored as Marp markdown, rendered via the existing scripts/render_pptx.py (narrowly extended per D-242), verified by scripts/check_leadership_deck.sh. The deck is discrete from the existing citizen-developer pitch (D-241: NOT a compression).

Requirements

12 requirements: REQ-372.1..REQ-372.12 (full text in .ciagent/REQUIREMENTS.md §v1.30). 1 capability: CAP-042. 3 decisions: D-241..D-243 (CLARIFY). Vision grounding: [1] → docs/vision.md.

Phase breakdown

Phase P1 — leadership-deck (REQ-372.1..REQ-372.12)

Goal: Author the Marp markdown deck source, extend the render pipeline, render the PPTX, author the smoke test, and append the ship-wave records (CAP-042, D-241). The deck is a single-shot artifact; all 12 REQs ship in this one phase.

Personas: lead-developer, backend-engineer, ci-doc-writer (phase-specific), ci-cli-engineer.

Territory: docs/presentations/nova-leadership-deck-marp.md (ci-doc-writer), scripts/render_pptx.py + docs/presentations/nova-leadership-deck.pptx (backend-engineer), scripts/check_leadership_deck.sh (ci-cli-engineer), .ciagent/STATE.md + .ciagent/PROJECT.md (lead-developer).

Wave 1 — render pipeline prerequisite (backend-engineer)

Task P1.W1.T1: Extend scripts/render_pptx.py per D-242:

• Accept an explicit source .md path as argv[1] (if it ends in .md and contains a /, treat as a path; else treat as a deck name per the existing convention — backward compatible).
• Accept --output <path> for the custom output filename. Default: derive from the source name (strip -marp.md → add .pptx) for backward compatibility.
• Add a _add_footer(slide, text) helper that adds a right-aligned textbox at the bottom of every slide with the exact string Nova Platform - Infrastructure & Operations (grey, small). Call it in both render_title_slide and render_content_slide.
• The footer text is read from the Marp frontmatter footer: directive if present; else default to the existing deck's footer (backward compatible). Parse the frontmatter to extract the footer: value (the existing code strips frontmatter without reading it — add a frontmatter parser).
• No other renderer change. Speaker notes remain skipped (acceptable per RESEARCH R1).

Must-haves:

• python3 scripts/render_pptx.py docs/presentations/nova-leadership-deck-marp.md --output docs/presentations/nova-leadership-deck.pptx works.
• python3 scripts/render_pptx.py nova-autonomous-cloud-delivery still works (backward compatible — renders {deck}-marp.md → {deck}-python.pptx).
• Every rendered slide has a right-aligned footer textbox.
• python3 -m py_compile scripts/render_pptx.py exits 0.

REQs covered: (prerequisite, not REQ-372 directly — per spec §3.3 Edge 2 + D-242).

Wave 2 — deck source (ci-doc-writer)

Task P1.W2.T1: Author docs/presentations/nova-leadership-deck-marp.md:

• Header comment (REQ-372.9): an HTML comment at the top (before frontmatter) naming this deck as the leadership artifact for Infrastructure & Operations, August 2026 presentation date, and naming nova-autonomous-cloud-delivery-marp.md as a related-but- distinct artifact that this deck does not compress or modify.
• Frontmatter (cover note): marp: true; theme: default; footer: "Nova Platform - Infrastructure & Operations"; paginate: false; size: 16:9 + a style: block using ONLY the 4 S&P tokens (#D6002A, #1B1B1B, #FFFFFF, #F0F0F0). Replace the existing deck's #2E2E2E blockquote color with #1B1B1B to satisfy REQ-372.6.
• 7 slides delimited by --- on its own line (REQ-372.3). All slides use ## H2 titles (content slides, white bg, red title bar — per RESEARCH R1 final call for visual consistency).
• On-slide body per the Slide Content Map in PROJECT.md §v1.30 (REQ-372.7). Use > blockquotes for the italic callouts, **...** bold lead for the slide titles' sub-headings, - bullets with → prefix for the arrow lines (so they render as proper bullets).
• Speaker notes per slide as HTML comments <!-- ... --> within the slide body before the next --- (REQ-372.4). Word counts: slides 1/2/4/6 in 150–300; slides 3/5 in 250–400; slide 7 in 200–300.
• [1] citations (REQ-372.12): at least one [1] in speaker notes of slides 3, 5, 7 (the architecture-load slides), grounding to docs/vision.md tenets/anti-goals/boundaries.
• No hex colors outside the 4 S&P tokens anywhere in the source (REQ-372.6).

Must-haves:

• File exists, parses as valid Marp, exactly 7 ----delimited slides.
• Header comment present with all 3 elements (REQ-372.9).
• Frontmatter has the exact footer string + paginate: false.
• Per-slide speaker-note word counts in band.
• [1] present in slides 3, 5, 7 speaker notes.
• grep -oiE '#[0-9A-Fa-f]{6}' returns only the 4 S&P tokens.

REQs covered: REQ-372.1, REQ-372.3, REQ-372.4, REQ-372.6, REQ-372.7, REQ-372.9, REQ-372.12.

Wave 3 — smoke test (ci-cli-engineer)

Task P1.W3.T1: Author scripts/check_leadership_deck.sh:

• Shebang #!/usr/bin/env bash, set -euo pipefail, header comment with Usage + Returns.
• Assertions (REQ-372.8 a–f):
  • (a) docs/presentations/nova-leadership-deck-marp.md exists.
  • (b) slide count = 7 (count ^---\s*$ lines after frontmatter end, +1; or count --- separators — careful with frontmatter).
  • (c) per-slide speaker-note word counts in band (extract <!-- ... --> content per slide, wc -w; slides 1/2/4/6: 150–300; 3/5: 250–400; 7: 200–300). Exit non-zero on violation.
  • (d) footer string Nova Platform - Infrastructure & Operations present in source (frontmatter footer: directive).
  • (e) only S&P hex colors in source (grep -oiE '#[0-9A-Fa-f]{6}', sort -u, compare to 4-token allow-list).
  • (f) docs/presentations/nova-leadership-deck.pptx exists (hard fail per Q-M4).
• Exit 0 on pass, non-zero (1) on fail. Runnable from repo root.
• NOT wired as a CI gate (no .github/workflows/ or workflows-src/ integration).

Must-haves:

• bash scripts/check_leadership_deck.sh exits 0 after the deck + PPTX are authored/rendered.
• Exits non-zero if any assertion fails (test by temporary mutation).

REQs covered: REQ-372.8.

Wave 4 — render + ship-wave records (backend-engineer + lead-developer)

Task P1.W4.T1 (backend-engineer): Render the PPTX:

• python3 scripts/render_pptx.py docs/presentations/nova-leadership-deck-marp.md --output docs/presentations/nova-leadership-deck.pptx
• Verify: PPTX written with 7 slides, python-pptx raised no exceptions, footer textbox present on every slide.
• Run bash scripts/check_leadership_deck.sh → exits 0.

Task P1.W4.T2 (lead-developer): Append CAP-042 to STATE.md:

• CAP-042 row in the capability table: artifact paths (nova-leadership-deck-marp.md, nova-leadership-deck.pptx), audience (Infrastructure & Operations leadership), single-shot intent, presentation month (August 2026), milestone v1.30 / tag v1.29.3.

Task P1.W4.T3 (lead-developer): Record D-241 in PROJECT.md:

• D-241 entry in the decisions section: single-shot nature, audience, August 2026 anchor + November 2026 runway, explicit decision not to compress the existing citizen-developer deck.

Must-haves:

• PPTX exists with 7 slides.
• Smoke test exits 0.
• CAP-042 row in STATE.md.
• D-241 record in PROJECT.md.

REQs covered: REQ-372.2, REQ-372.5, REQ-372.8, REQ-372.10, REQ-372.11.

Phase P2 — final-review-ship (review + audit + milestone ship)

Goal: Multi-persona review of the milestone changes, project- health audit, and milestone ship (merge to main, tag v1.29.3 = milestone release, delete milestone branches).

Personas: lead-developer (review + audit + ship coordination).

Tasks:

• Review all v1.30 changes (deck source, render extension, smoke test, STATE.md/PROJECT.md records). Auto-apply P0 fixes; flag P1+ for post-hoc review.
• Audit: reconstruction test (git log matches .ciagent/ files), file discipline, branch hygiene, commit discipline.
• Ship: merge phase/02 → milestone/v1.30-leadership-deck → main, tag v1.29.3, create release, delete milestone branches.
• Complete: mark REQ-372.1..12 complete in REQUIREMENTS.md, mark v1.30 complete in ROADMAP.md.

Wave dependency graph

W1 (render_pptx.py extension) ─┐
                               ├─→ W4.T1 (render PPTX) ─→ W4.T2/T3 (records)
W2 (deck source) ──────────────┤                              │
                               │                              ↓
W3 (smoke test) ───────────────┴────────────────────────→ P1 VERIFY
                                                              │
                                                              ↓
                                                          P1 SHIP (v1.29.2)
                                                              │
                                                              ↓
                                                          P2 (v1.29.3)

W1, W2, W3 are independent (no cross-dependencies at author time). W4 depends on W1 + W2 (render needs the extension + the source) + W3 (smoke test validates the render). W4.T2/T3 (records) depend on W4.T1 (render confirms ship readiness).

User-Facing Surface

• The PPTX deck (docs/presentations/nova-leadership-deck.pptx) — the primary leadership-facing artifact, presented live in August 2026.
• The Marp markdown source (docs/presentations/nova-leadership-deck-marp.md) — the source- of-truth, reproducible via scripts/render_pptx.py.
• The smoke test (scripts/check_leadership_deck.sh) — runnable on demand by the PO/presenter to verify deck integrity before presentation.

Happy Path

J1 — PO presents the deck live (from spec §3.2):

1. PO authors nova-leadership-deck-marp.md against the Slide Content Map; bash scripts/check_leadership_deck.sh exits 0 (verifies content). (REQ-372.1, .4, .6, .7, .8, .12.)
2. PO renders the markdown to PPTX via python3 scripts/render_pptx.py docs/presentations/nova-leadership-deck-marp.md --output docs/presentations/nova-leadership-deck.pptx; visual inspection confirms 7 slides + footer. (REQ-372.2, .5.)
3. PO presents live to Infrastructure & Operations leadership; speaker notes carry architecture depth. (REQ-372.4.)
4. PO updates STATE.md with CAP-042 and PROJECT.md with D-241 at the v1.30 ship wave. (REQ-372.10, .11.)

UX Acceptance Criteria

1. bash scripts/check_leadership_deck.sh exits 0 (all 6 assertions a–f pass).
2. docs/presentations/nova-leadership-deck.pptx exists, has 7 slides, and python-pptx raised no exceptions during render.
3. Visual review: each slide N (1–7) matches the Slide Content Map in PROJECT.md §v1.30 (on-slide body + speaker notes fingerprint).
4. Footer Nova Platform - Infrastructure & Operations is visible (right-aligned) on every rendered slide.
5. Only S&P theme colors appear in the source markdown.
6. [1] citations present in slides 3, 5, 7 speaker notes.
7. CAP-042 row in STATE.md; D-241 record in PROJECT.md.
8. nova-autonomous-cloud-delivery-marp.md is unmodified (D-241 discrete-artifact constraint).

Risks (from RESEARCH + GRILL)

Risk	Mitigation
python-pptx render fails on the new frontmatter/style block	The python-pptx path strips frontmatter without reading it; the style: block is source-only (Marp CLI). No render risk.
Footer textbox overlaps content	Place footer at SLIDE_H - 0.3" (bottom margin); content area tops out at ~6.5". No overlap.
Speaker notes word-count band violation	ci-doc-writer counts words per slide during authoring; smoke test (8c) is the gate.
→ lines render as plain text (not bullets)	Use - → ... bullets so the renderer treats them as bullet blocks with the arrow in the text.
*italic* in source matches unordered-list regex	Verified in RESEARCH R1: *italic* (no space after *) does NOT match [-*+]\s+. Safe.
CAP-024 regression policy collides	Verified in RESEARCH R7: CAP-024 validates fixtures, not deck files. No collision.
slides.yml CI interferes	Verified in RESEARCH R8: CI only renders the citizen-developer deck (hardcoded DECK). No interference.