docs(P00): create phase plans — v1.22 (7 phases, 4 waves)

Vertical-slice plan with wave ordering:
- Wave 1 (P1+P2, parallel): theme CSS + render scripts. Zero file
  overlap. P1 establishes padding/overflow/image budget; P2 fixes
  render pipeline.
- Wave 2 (P3+P4, parallel): mermaid re-layout + deck content. P3
  depends on P2 (2x scale); P4 depends on P1 (padding budget).
- Wave 3 (P5): re-render HTML+PPTX + add layout/aspect-ratio/theme-
  structural tests. Depends on all above.
- Wave 4 (P6): final review + audit + milestone ship.

Tags on v1.21.x line: v1.21.0 (P0) -> v1.21.1..v1.21.5 (P1-P5) ->
v1.21.6 (P6 final = milestone release).

---ci---
project: acdl
phase: 0
milestone: v1.22
status: plan
---/ci---

.ciagent/CHECKPOINT.json

@@ -1,12 +1,12 @@
 {
   "phase": 0,
-  "stage": "clarify",
+  "stage": "research",
   "milestone": "v1.22",
   "phase_role": "pre_execution",
   "attempts": 0,
-  "updated_at": "2026-08-11T14:32:00Z",
+  "updated_at": "2026-08-11T14:35:00Z",
   "milestone_complete": false,
   "tag": null,
   "requirements": ["REQ-254","REQ-255","REQ-256","REQ-257","REQ-258","REQ-259","REQ-260","REQ-261","REQ-262"],
-  "notes": "v1.22 CLARIFY complete. 5 ambiguities auto-resolved at full autonomy (comprehensive scope, full pipeline, re-layout to LR, delete render_deck.sh, split slides 3+8). No human escalation."
+  "notes": "v1.22 RESEARCH complete. 8 findings persisted to RESEARCH.md. Persona roster updated (2 active: lead-developer + backend-engineer; 2 deactivated: frontend + data). D-148, D-149 logged."
 }

.ciagent/PLAN.md

@@ -1098,5 +1098,318 @@ NOT exercised here.
 8. **No new frontend (frontend-engineer deactivated).** v1.18 has no
    frontend; decks are markdown (lead-developer territory); the MCP
    server exposes tools to an AI agent, not a web UI. The
-   frontend-engineer persona stays deactivated (PERSONAS.md v1.18
-   roster). No reactivation trigger in this milestone.
+    frontend-engineer persona stays deactivated (PERSONAS.md v1.18
+    roster). No reactivation trigger in this milestone.
+
+---
+
+# Nova — Phase Plan v1.22 (Nova Deck Layout Fix)
+
+> **Milestone:** v1.22 — Nova Deck Layout Fix
+> **Branch:** `milestone/v1.22-deck-layout-fix` → merge to `main` at P6.
+>   Phase branches: `phase/00-pre-execution`, `phase/01-theme-css`,
+>   `phase/02-render-scripts`, `phase/03-mermaid-relayout`,
+>   `phase/04-deck-content`, `phase/05-render-and-test`,
+>   `phase/06-final-review-ship`.
+> **Tag line:** `v1.21.x` patch line — `v1.21.0` (P0) →
+> `v1.21.1..v1.21.5` (P1–P5) → `v1.21.6` (P6 final = milestone release).
+>   v1.22 is an NFR milestone (all phases are fix/docs/test) →
+>   progressive patches.
+> **Phase count:** 7 (P0 pre-execution + 5 execution + 1 final).
+> **Source of truth for requirements:** `.ciagent/REQUIREMENTS.md` §v1.22
+>   (REQ-254..262, 9 requirements).
+> **Source of truth for research:** `.ciagent/RESEARCH.md` §v1.22 (8
+>   findings, 5 assumptions, 5 CLARIFY decisions).
+> **Source of truth for personas:** `.ciagent/PERSONAS.md` v1.22 roster
+>   (2 active: lead-developer + backend-engineer; 2 deactivated:
+>   frontend + data).
+
+## Wave Ordering
+
+| Wave | Phases | Rationale |
+|------|--------|-----------|
+| Wave 1 | P1, P2 (**parallel**) | P1 (theme CSS: padding, overflow, image, title chrome) + P2 (render scripts: delete render_deck.sh, pin versions, 2x scale). Zero file overlap: P1 touches `docs/presentations/assets/nova-sp-theme.css`; P2 touches `scripts/render_slides.sh` + deletes `scripts/render_deck.sh`. P1 establishes the padding/overflow/image budget that P4's content trimming relies on; P2 fixes the render pipeline that P3's PNG re-render depends on. |
+| Wave 2 | P3, P4 (**parallel**) | P3 (mermaid re-layout: telemetry LR, platform-pipeline 2-row wrap) + P4 (deck content: trim/split 8 overflowing slides, remove header). P3 depends on P2 (2x scale flag); P4 depends on P1 (padding budget). Zero file overlap: P3 touches `docs/presentations/assets/mmd/*.mmd` + PNGs; P4 touches `docs/presentations/nova-autonomous-cloud-delivery-marp.md` + source `.md` + talking-points + README. |
+| Wave 3 | P5 | Re-render HTML + PPTX + add tests. Depends on all above (P1 theme, P2 scripts, P3 diagrams, P4 content). Re-renders via the fixed `render_slides.sh`; adds the layout/aspect-ratio/theme-structural tests (the gap that let this through). |
+| Wave 4 | P6 | Final review + audit + milestone ship. Merge to main, tag `v1.21.6`, create release, attach PPTX. |
+
+## Phase P0 — pre-execution (DONE)
+
+SPECIFY → CLARIFY → RESEARCH → PLAN. Validated v1.22 requirements
+(REQ-254..262). Established `active_milestone: "v1.22"`. Root-cause
+investigation persisted to RESEARCH.md (8 findings). Persona roster
+updated (2 active, 2 deactivated). 5 CLARIFY decisions auto-resolved.
+
+## Phase P1 — theme-css (fix) — lead-developer
+
+**Requirements:** REQ-254, REQ-255, REQ-256
+**Branch:** `phase/01-theme-css`
+**Territory:** `docs/presentations/assets/nova-sp-theme.css`
+
+### Tasks
+
+1. **REQ-254 — section padding + overflow:**
+   - Add `section { padding: 48px 56px 40px; }` (top reserves header
+     space; bottom reserves footer).
+   - Add `section { overflow: auto; }` as an authoring-time signal
+     (dense content scrolls instead of silently clipping). Document
+     that the real fix is content trimming (P4), not runtime scroll.
+2. **REQ-255 — aspect-ratio-aware image rules:**
+   - Replace `img { display: block; margin: 0 auto; max-height: 320px }`
+     with `img { display: block; margin: 0 auto; max-width: 100%;
+     max-height: 380px; object-fit: contain; }`.
+   - Add `.wide` class: `img.wide { max-height: 280px; }` (for ultra-wide
+     diagrams).
+   - Add `.tall` class: `img.tall { max-height: 480px; }` (for tall
+     diagrams that need more vertical room).
+3. **REQ-256 — title chrome + spacing tightening:**
+   - Add `section.title header, section.title footer { display: none; }`.
+   - Add `section h2 + p { margin-top: 0.2em; }`.
+   - Add `section p { margin: 0.4em 0; }`.
+   - Add `ol` styling: `ol { margin-top: 0.3em; }` (match `ul`).
+   - Add `table.dense td, table.dense th { padding: 4px 8px; }` (for
+     tables with ≥8 rows).
+   - Add `@media print { section { overflow: hidden; } }` (PPTX export
+     fidelity — no scrollbars in exported slides).
+
+### Verify (inline)
+- `python3 -c "from pathlib import Path; css = Path('docs/presentations/assets/nova-sp-theme.css').read_text(); assert 'padding:' in css and 'section.title header' in css and 'object-fit' in css and 'table.dense' in css; print('theme CSS OK')"`
+- `pytest tests/test_slides_pipeline.py -k "theme" -q` (existing theme
+  color tests still pass).
+
+### Ship
+- Tag `v1.21.1`, merge `phase/01-theme-css` → `milestone/v1.22-deck-layout-fix`.
+
+## Phase P2 — render-scripts (fix) — backend-engineer
+
+**Requirements:** REQ-257, REQ-258
+**Branch:** `phase/02-render-scripts`
+**Territory:** `scripts/render_slides.sh`, `scripts/render_deck.sh` (DELETE)
+
+### Tasks
+
+1. **REQ-257 — delete render_deck.sh + pin CLI versions:**
+   - `git rm scripts/render_deck.sh` (the README already documents
+     `render_slides.sh` as canonical; `render_deck.sh` omits `--theme`
+     and produces unthemed output).
+   - Pin marp-cli and mermaid-cli versions in `render_slides.sh`:
+     replace `@marp-team/marp-cli@latest` with a pinned version (e.g.
+     `@marp-team/marp-cli@4.0.0` — determine the working version by
+     testing during execution) and `@mermaid-js/mermaid-cli@latest`
+     with a pinned version (e.g. `@mermaid-js/mermaid-cli@10.9.1`).
+   - Remove any references to `render_deck.sh` from
+     `.github/workflows/slides.yml`, `docs/presentations/README.md`,
+     and `tests/test_slides_pipeline.py` (if any test references it).
+2. **REQ-258 — 2x scale + transparent bg for mermaid:**
+   - In `render_slides.sh` lines 51-55, add `-s 2 -b transparent` to
+     the mermaid-cli invocation (matches README line 193 spec).
+
+### Verify (inline)
+- `test ! -f scripts/render_deck.sh && echo "render_deck.sh deleted OK"`
+- `grep -q "marp-cli@" scripts/render_slides.sh && grep -q "mermaid-cli@" scripts/render_slides.sh && echo "versions pinned OK"`
+- `grep -q -- "-s 2" scripts/render_slides.sh && grep -q -- "-b transparent" scripts/render_slides.sh && echo "2x + transparent OK"`
+- `pytest tests/test_slides_pipeline.py -k "render" -q` (existing
+  render-script tests still pass; update if they reference
+  `render_deck.sh`).
+
+### Ship
+- Tag `v1.21.2`, merge `phase/02-render-scripts` → `milestone/v1.22-deck-layout-fix`.
+
+## Phase P3 — mermaid-relayout (fix) — lead-developer
+
+**Requirements:** REQ-259, REQ-260
+**Branch:** `phase/03-mermaid-relayout`
+**Territory:** `docs/presentations/assets/mmd/telemetry-live-ops.mmd`,
+  `docs/presentations/assets/mmd/platform-pipeline.mmd`, PNG re-render
+  (via `render_slides.sh` — backend-engineer co-owns the script
+  invocation).
+
+### Tasks
+
+1. **REQ-259 — telemetry-live-ops.mmd TB → LR:**
+   - Rewrite `docs/presentations/assets/mmd/telemetry-live-ops.mmd` from
+     `flowchart TB` to `flowchart LR` with subgraph row-wrapping (per
+     README line 168). Target aspect ratio ∈ [1.2, 2.5].
+   - Re-render PNG: `bash scripts/render_slides.sh nova-autonomous-cloud-delivery`
+     (now with 2x scale + transparent bg from P2).
+   - Update the Marp deck's `![w:900]` directive on slide 9 to match
+     the new dimensions (or replace with `![h:320]` if the diagram
+     remains taller than wide after re-layout — but LR should produce
+     a wide diagram).
+2. **REQ-260 — platform-pipeline.mmd 2-row wrap:**
+   - Rewrite `docs/presentations/assets/mmd/platform-pipeline.mmd` to
+     wrap the 10-node LR chain into 2 rows via mermaid subgraphs (or
+     split into two stages: static-scan row + runtime-scan row). Target
+     aspect ratio ∈ [1.2, 2.5].
+   - Re-render PNG (same command as above).
+
+### Verify (inline)
+- `python3 -c "from PIL import Image; import os; d='docs/presentations/assets/png'; [print(f, Image.open(os.path.join(d,f)).size) for f in os.listdir(d) if f.endswith('.png')]"` (check aspect ratios — or use a stdlib-only check if PIL unavailable).
+- Verify both re-rendered PNGs have aspect ratio ∈ [1.2, 2.5].
+
+### Ship
+- Tag `v1.21.3`, merge `phase/03-mermaid-relayout` → `milestone/v1.22-deck-layout-fix`.
+
+## Phase P4 — deck-content (fix) — lead-developer
+
+**Requirements:** REQ-261
+**Branch:** `phase/04-deck-content`
+**Territory:** `docs/presentations/nova-autonomous-cloud-delivery-marp.md`,
+  `docs/presentations/nova-autonomous-cloud-delivery.md`,
+  `docs/presentations/nova-autonomous-cloud-delivery-talking-points.md`,
+  `docs/presentations/README.md`.
+
+### Tasks
+
+1. **Split slide 3** (Objectives + Anti-Goals) into:
+   - Slide 3a — Strategic Objectives (4 objectives + nested sub-list).
+   - Slide 3b — Anti-Goals (4 anti-goals + benefit).
+   Main slide count 18 → 19.
+2. **Split slide 8** (Attestation Matrix) into:
+   - Slide 8a — Attestation: QA (3 qa rows + separation-of-duties note).
+   - Slide 8b — Attestation: Prod/DR (7 prod/dr rows + benefit).
+   Main slide count 19 → 20.
+3. **Trim slide 5** (RACI): apply `table.dense` class (from P1) to
+   reduce cell padding; keep 8 rows.
+4. **Trim slide 6** (Pipeline): reduce to 3 bullets (the 4th is covered
+   by the diagram, now legible after P3).
+5. **Trim slide 9** (Telemetry): reduce to 3 bullets; image now legible
+   after P3.
+6. **Trim slide 12** (Deferred): reduce to 6 rows (merge the 3 "Live
+   AWS re-provisioning" blockers into one row).
+7. **Trim slide 15** (Quarter-by-Quarter): drop the "Grounding" column
+   (redundant with strategic objectives); 4 columns fit better.
+8. **Trim Appendix A1** (Glossary): apply `table.dense` class (16px
+   font); keep 13 rows.
+9. **Remove `header:` from frontmatter** (keep `footer:` + `paginate:
+   true` only). The full 51-char deck title in BOTH header and footer
+   is redundant chrome; the footer alone suffices.
+10. **Update talking-points.md** to match the new 20 main + 1 appendix
+    slide structure.
+11. **Update README.md** "18 main + 1 appendix" convention (line 130)
+    → "20 main + 1 appendix".
+12. **Update `test_marp_deck_slide_count`** in
+    `tests/test_slides_pipeline.py` to assert 20 main + 1 appendix
+    (this test is co-owned with backend-engineer per PERSONAS.md, but
+    the assertion value reflects lead-developer's deck structure
+    decision — lead-developer makes the edit here).
+
+### Verify (inline)
+- `pytest tests/test_slides_pipeline.py -k "slide_count" -q` (updated
+  test passes with 20 main + 1 appendix).
+- `grep -c "## Slide " docs/presentations/nova-autonomous-cloud-delivery-marp.md` → 20.
+- `grep -c "## Appendix " docs/presentations/nova-autonomous-cloud-delivery-marp.md` → 1.
+- `grep -q "^header:" docs/presentations/nova-autonomous-cloud-delivery-marp.md && echo "FAIL: header still present" || echo "header removed OK"`.
+
+### Ship
+- Tag `v1.21.4`, merge `phase/04-deck-content` → `milestone/v1.22-deck-layout-fix`.
+
+## Phase P5 — render-and-test (test) — backend-engineer
+
+**Requirements:** REQ-262
+**Branch:** `phase/05-render-and-test`
+**Territory:** `tests/test_slides_pipeline.py` (test code — backend),
+  re-render invocation (backend). Assertions reflect lead-developer's
+  deck/theme decisions (co-owned).
+
+### Tasks
+
+1. **Re-render HTML + PPTX:**
+   - `bash scripts/render_slides.sh nova-autonomous-cloud-delivery` →
+     re-renders all mermaid PNGs (2x transparent) + HTML + PPTX.
+   - Verify slide count (20 main + 1 appendix = 21 `<section>` elements
+     in the HTML + 1 title = 22 total — or however Marp counts the title
+     slide; verify against the marp deck).
+   - Verify media embedding (PPTX has embedded PNGs).
+2. **Add tests to `tests/test_slides_pipeline.py`:**
+   - `test_theme_css_has_section_padding` — assert `section` rule in
+     `nova-sp-theme.css` contains `padding`.
+   - `test_theme_css_suppresses_title_chrome` — assert
+     `section.title header` and `section.title footer` have
+     `display: none`.
+   - `test_png_aspect_ratios_sane` — for every PNG in `assets/png/`,
+     assert aspect ratio ∈ [1.2, 2.5] (catches the 13.52× and 0.63×
+     outliers). Use `struct`/`imghdr` or a minimal PNG header parser
+     (no PIL dependency if possible).
+   - `test_render_slides_has_2x_scale` — assert `render_slides.sh`
+     contains `-s 2` and `-b transparent`.
+   - `test_render_deck_removed` — assert `scripts/render_deck.sh` does
+     not exist.
+   - `test_html_embeds_theme` — assert committed HTML contains
+     `--sp-red` and `padding` in the inline `<style>`.
+   - `test_html_slide_count_matches_marp` — parse HTML `<section>` count
+     == marp deck slide count.
+3. **Run full test suite:**
+   - `pytest tests/test_slides_pipeline.py -q` (all slide tests pass).
+   - `pytest -q` (full suite — was 686 pass + 1 pre-existing attestation
+     env failure; should now be 686 + new tests pass, same 1 failure).
+   - `bash scripts/run_platform.sh --check-only` → exit 0.
+
+### Verify (inline)
+- `pytest tests/test_slides_pipeline.py -q` (all pass, including new
+  layout/aspect-ratio/theme-structural tests).
+- `pytest -q 2>&1 | tail -5` (full suite — confirm no new failures).
+
+### Ship
+- Tag `v1.21.5`, merge `phase/05-render-and-test` → `milestone/v1.22-deck-layout-fix`.
+
+## Phase P6 — final-review-ship (final) — lead-developer
+
+**Requirements:** all (REQ-254..262) — milestone release
+**Branch:** `phase/06-final-review-ship`
+
+### Tasks
+
+1. **Multi-persona review** (`ciagent-review` equivalent):
+   - Review all changes in the milestone branch across P1-P5.
+   - Auto-apply P0 fixes; flag P1+ for post-hoc review.
+   - If P1+ issues found: fix them in this final phase.
+2. **Audit** (`ciagent-audit` equivalent):
+   - Reconstruction test: verify git log matches `.ciagent/` files.
+   - Check `.ciagent/` file discipline and branch hygiene.
+   - Check commit discipline (all commits have `---ci---` blocks).
+   - If audit finds critical issues: fix them in this final phase.
+3. **Milestone ship** (`ciagent-ship` equivalent):
+   - Merge `phase/06-final-review-ship` → `milestone/v1.22-deck-layout-fix`.
+   - Merge `milestone/v1.22-deck-layout-fix` → `main`.
+   - Tag `v1.21.6` (final phase patch = milestone release).
+   - Create release with full milestone summary (all phases, all
+     requirements).
+   - Build and upload PPTX as release asset.
+   - Delete all milestone branches (local + remote).
+4. **Complete the milestone:**
+   - Update `REQUIREMENTS.md` — mark REQ-254..262 as complete.
+   - Update `ROADMAP.md` — mark v1.22 as complete.
+   - Commit: `docs(milestone): complete v1.22 — Nova Deck Layout Fix`.
+
+### Ship
+- Tag `v1.21.6` (milestone release). Merge to `main`. Clear checkpoint.
+
+## Plan-Level Risks + Notes (v1.22)
+
+1. **Slide count change** (18 → 20 main): `test_marp_deck_slide_count`
+   + README convention must be updated in P4. The split is necessary
+   because slides 3 and 8 are the densest (~780px each) and cannot be
+   trimmed without losing leadership-relevant content.
+2. **Marp version pinning**: the exact pinned versions will be
+   determined during P2 execution by testing which version produces
+   stable output in this environment. If the pinned version has a
+   different boilerplate-CSS signature, the HTML diff will be large but
+   layout-stable.
+3. **`overflow: auto` on `section`**: Marp slides are SVG
+   `foreignObject` — `overflow: auto` may not produce scrollbars in all
+   renderers (PPTX especially). The safer approach is content trimming
+   (P4) + padding (P1), treating overflow as an authoring-time signal,
+   not a runtime scroll. The `@media print { section { overflow: hidden; } }`
+   rule in P1 ensures PPTX export doesn't show scrollbars.
+4. **No new frontend** (frontend-engineer deactivated). v1.22 has no
+   frontend; decks are markdown + Marp CSS (lead-developer territory,
+   per D-148). The frontend-engineer persona stays deactivated.
+5. **No data-engineer** (no schema/DB changes). v1.22 is docs + scripts
+   + tests only.
+6. **Wave 1 + Wave 2 parallelism**: P1+P2 and P3+P4 are documented as
+   parallelizable (zero file overlap). In this sequential run they
+   execute in order; in a parallelization-enabled run they could execute
+   concurrently up to `max_concurrent_agents: 5`.
+7. **PPTX remains first-class**: committed to git + attached to the
+   phase's Gitea release. No change to this convention.