docs(P00): research findings — v1.22 deck layout root cause (REQ-254..262)

8 findings (all confidence >= 0.8): - F1 (VERY HIGH): theme CSS has zero section padding (/* @theme */ is a comment, not the directive; no @import of Marp default). - F2 (VERY HIGH): overflow:hidden silently clips dense content (8/19 slides overflow). - F3 (HIGH): image aspect-ratio catastrophe (platform-pipeline 13.52x, telemetry-live-ops 0.63x). - F4 (HIGH): header+footer chrome on every slide (~70px lost). - F5 (MEDIUM-HIGH): render_deck.sh omits --theme (unthemed output). - F6 (HIGH): render_slides.sh missing -s 2 -b transparent (1x PNGs). - F7 (LOW): P5 marp-cli version bump — NOT the cause (theme CSS byte- identical P3->P5). - F8 (VERY HIGH): test coverage gaps — no layout/overflow/aspect-ratio tests; static-file-property tests only. Persona roster (v1.22): lead-developer (theme CSS + deck markdown + mermaid + .ciagent), backend-engineer (render scripts + tests). frontend-engineer + data-engineer deactivated. D-148 (theme CSS is lead-developer, not frontend), D-149 (no new personas). ---ci--- project: acdl phase: 0 milestone: v1.22 status: research ---/ci---
2026-08-11 19:22:45 +00:00
parent dbca694f55
commit 0404988465
3 changed files with 345 additions and 27 deletions
@@ -1,12 +1,12 @@
 {
  "phase": 0,
-  "stage": "specify",
+  "stage": "clarify",
  "milestone": "v1.22",
  "phase_role": "pre_execution",
  "attempts": 0,
-  "updated_at": "2026-08-11T14:30:00Z",
+  "updated_at": "2026-08-11T14:32: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 Nova Deck Layout Fix. SPECIFY complete. 9 requirements (REQ-254..262). NFR milestone, 7 phases (P0 + P1-P5 + P6 final). Tags on v1.21.x line. Root cause: theme CSS zero section padding + overflow:hidden + blunt img max-height + extreme aspect-ratio diagrams. Comprehensive fix across theme CSS, render scripts, mermaid, deck content, tests."
+  "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."
 }
@@ -1,34 +1,128 @@
 ---
 project: acdl
-milestone: v1.18
-generated_at: 2026-08-06
+milestone: v1.22
+generated_at: 2026-08-11
 generator: lead-developer
 verification_toolchain:
-  typecheck: "python3 -m py_compile core/submission_readiness.py mcp/atelier/server.py && python3 -m jsonschema schemas/submission-readiness.schema.json"
-  test: "pytest tests/test_submission_readiness.py tests/test_atelier_mcp.py   # REQ-220 + REQ-225"
-  build: "bash scripts/render_deck.sh docs/presentations/nova-no-humans-platform-marp.md   # HTML + PPTX (D-142)"
+  typecheck: "python3 -m py_compile tests/test_slides_pipeline.py"
+  test: "pytest tests/test_slides_pipeline.py   # REQ-254..262"
+  build: "bash scripts/render_slides.sh nova-autonomous-cloud-delivery   # HTML + PPTX"
  note: |
-    v1.18 adds the Citizen Developer & Production-Grade Guidance surface:
-    submission-readiness gate, Atelier-derived skills, the Atelier MCP server
-    (plugin-registry, stdio), and PPTX-as-first-class-artifact deck automation.
-    Three active personas: lead-developer (coordination + decks + RACI/scope
-    docs), backend-engineer (MCP server + submission-readiness validator +
-    render/attach scripts), data-engineer (submission-readiness schema if it
-    touches contract storage / DynamoDB shape). frontend-engineer stays
-    deactivated (v1.18 has no frontend; decks are markdown = lead-developer
-    territory). The MCP plugin-registry is a backend pattern, so a separate
-    mcp-engineer persona is NOT added — it folds into backend-engineer.
+    v1.22 is the Nova Deck Layout Fix — a docs-only NFR milestone. Two
+    active personas: lead-developer (theme CSS + deck markdown + talking
+    points + README + .ciagent metadata), backend-engineer (render scripts
+    + tests). frontend-engineer stays deactivated (decks are markdown =
+    lead-developer territory, per v1.17/v1.18 precedent). No data-engineer
+    (no schema/DB changes). No new personas (the work is CSS + bash +
+    markdown + pytest, all within the two active personas' range).
 ---

-# ACDL — Persona Roster (v1.18 Citizen Developer & Production-Grade Guidance)
+# ACDL — Persona Roster (v1.22 Nova Deck Layout Fix)

-> v1.18 roster. Three active personas + one deactivated. The MCP server
-> plugin-registry (D-140) is a backend pattern, not a new persona — it
-> folds into backend-engineer. v1.17 precedent (frontend-engineer
-> deactivated, decks are markdown = lead-developer territory) is upheld.
+> v1.22 roster. Two active personas + one deactivated. This is a docs-
+> only NFR milestone: the work is theme CSS, render scripts, mermaid
+> diagrams, deck markdown, and tests. frontend-engineer stays
+> deactivated (decks are markdown = lead-developer territory, per
+> v1.17/v1.18 precedent). No data-engineer (no schema/DB changes).

 ## Active personas

+### lead-developer
+- **Domain:** coordination + deck content
+- **Active:** true
+- **Phase-specific:** false
+- **Frameworks:** [] (no framework — owns process + narrative + CSS + markdown)
+- **Constraints:** ["pragmatic", "battle-tested defaults", "no fabrication (NORTH_STAR honesty model)", "do not change the 4-beat arc", "do not re-introduce badges/version/internal citations"]
+- **Territory:**
+  - `docs/presentations/assets/nova-sp-theme.css` (REQ-254,255,256 — theme CSS)
+  - `docs/presentations/nova-autonomous-cloud-delivery-marp.md` (REQ-261 — deck content)
+  - `docs/presentations/nova-autonomous-cloud-delivery.md` (REQ-261 — source of truth)
+  - `docs/presentations/nova-autonomous-cloud-delivery-talking-points.md` (REQ-261)
+  - `docs/presentations/README.md` (REQ-261 — slide-count convention)
+  - `docs/presentations/assets/mmd/*.mmd` (REQ-259,260 — mermaid re-layout)
+  - `.ciagent/**` (PROJECT, ROADMAP, REQUIREMENTS, RESEARCH, PLAN, GRILL, PERSONAS, REVIEW, CHECKPOINT)
+- **Reason:** Owns the theme CSS (the root cause), the deck markdown
+  (trim/split overflowing slides), the mermaid re-layout, the talking
+  points, the README, and all CIAgent metadata. Is the only persona
+  that touches `.ciagent/**` and the deck markdown/CSS.
+- **Phase-specific flag:** none (active for all of P0–P6).
+
+### backend-engineer
+- **Domain:** render scripts + tests
+- **Active:** true
+- **Phase-specific:** false
+- **Frameworks:** ["bash", "pytest", "marp-cli", "mermaid-cli"]
+- **Constraints:** ["pin CLI versions (no @latest)", "2x scale + transparent bg for mermaid", "tests must catch layout regressions", "no raw curl with shell-env tokens"]
+- **Territory:**
+  - `scripts/render_slides.sh` (REQ-257,258 — pin versions, 2x scale)
+  - `scripts/render_deck.sh` (REQ-257 — DELETE)
+  - `tests/test_slides_pipeline.py` (REQ-262 — layout/aspect-ratio/theme-structural tests)
+  - `.github/workflows/slides.yml` (if references to render_deck.sh need removal)
+- **Reason:** Owns the render pipeline (bash scripts) and the test
+  suite. The layout/aspect-ratio/theme-structural tests (REQ-262) are
+  the gap that let this regression through — backend-engineer owns
+  closing that gap. Pinning CLI versions and adding 2x scale are
+  backend/scripting tasks.
+- **Phase-specific flag:** none (active for P2, P5; light touch on P0/P6).
+
+## Deactivated personas
+
+### frontend-engineer
+- **Active:** false
+- **Domain:** frontend
+- **Frameworks:** ["react", "next.js"] (inert — no territory)
+- **Constraints:** ["component-first", "server-components", "minimal-client-js"] (inert)
+- **Territory:** [] (no territory in v1.22)
+- **Reason:** v1.22 has no frontend; decks are markdown (lead-developer
+  territory); deactivated per PERSONAS.md v1.17/v1.18 precedent. The
+  theme CSS is a Marp stylesheet, not a React/Next.js component system
+  — it stays lead-developer territory. No reactivation trigger.
+
+### data-engineer
+- **Active:** false
+- **Domain:** data
+- **Frameworks:** [] (inert)
+- **Constraints:** [] (inert)
+- **Territory:** [] (no territory in v1.22)
+- **Reason:** v1.22 has no schema/DB/ORM changes. The milestone is
+  docs + scripts + tests only. No reactivation trigger.
+
+## Roster decisions
+
+### D-148 (0.95): Theme CSS is lead-developer territory, not frontend-engineer
+The `nova-sp-theme.css` is a Marp stylesheet (CSS for a markdown-to-
+slide renderer), not a React/Next.js component system. The v1.17/v1.18
+precedent (decks are markdown = lead-developer territory) extends to
+the deck's CSS theme. frontend-engineer's frameworks (react, next.js)
+are irrelevant to Marp CSS. **Decision:** theme CSS stays lead-developer
+territory. Confidence 0.95 — the only counter-argument is that CSS is
+"frontend," but Marp CSS is a static stylesheet, not a component system.
+
+### D-149 (0.9): No new personas for v1.22
+The work is CSS + bash + markdown + mermaid + pytest. All of this is
+within the two active personas' range (lead-developer: CSS + markdown +
+mermaid; backend-engineer: bash + pytest). Creating a separate "css-
+engineer" or "slides-engineer" persona would fragment ownership of the
+theme CSS + deck markdown (both lead-developer) and the render scripts
+ tests (both backend-engineer). **Decision:** no new personas.
+Confidence 0.9.
+
+### Territory-overlap resolution (co-ownership)
+
+| Path | Primary | Co-owner | Why |
+|------|---------|----------|-----|
+| `docs/presentations/assets/mmd/*.mmd` | lead-developer (mermaid re-layout) | backend-engineer (re-render via render_slides.sh) | The .mmd content is lead-developer (diagram narrative); the PNG re-render is backend-engineer (script invocation). |
+| `tests/test_slides_pipeline.py` | backend-engineer (test code) | lead-developer (assertions reflect deck structure) | The test code is backend; the assertions (slide count, theme rules, aspect ratios) reflect lead-developer's deck/theme decisions. |
+
+---
+
+## Historical rosters
+
+<details>
+<summary>v1.18 roster (Citizen Developer & Production-Grade Guidance) — superseded by v1.22</summary>
+
+### Active personas (v1.18)
+
 ### lead-developer
 - **Domain:** coordination
 - **Active:** true
@@ -97,7 +191,7 @@ verification_toolchain:
  is backend; the schema it validates against is data).
 - **Phase-specific flag:** none (active for P3 schema + ingestor wiring).

-## Deactivated personas
+### Deactivated personas (v1.18)

 ### frontend-engineer
 - **Active:** false
@@ -111,7 +205,7 @@ verification_toolchain:
  frontend / dashboard"). The MCP server exposes tools to an AI agent,
  not a web UI. No reactivation trigger in this milestone.

-## Roster decisions
+### Roster decisions (v1.18)

 ### D-143 (0.90): Fold mcp-engineer into backend-engineer
 The MCP plugin-registry (D-140: `plugins/<name>.py register(mcp)`) is a
@@ -127,10 +221,12 @@ that MCP is a distinct protocol skill, but the SDK v2 API surface
 range (it's the same Pydantic/FastAPI-style pattern the persona already
 knows).

-### Territory-overlap resolution (co-ownership)
+### Territory-overlap resolution (v1.18)

 | Path | Primary | Co-owner | Why |
 |------|---------|----------|-----|
 | `docs/submission-readiness.md` | lead-developer (narrative + examples) | backend-engineer (reason-code catalog, REQ-218 codes) | The doc is citizen-developer-facing copy (lead) but the reason-code catalog (MISSING_TAGS, ENV_MISSING_MANDATORY, AGENTIC_MISSING_INTENT, MISSING_APP_SOURCE, POLICY_PRECONDITION_MISSING) is backend (it mirrors the validator's return codes). |
 | `core/lambda/contract_ingestor.py` | backend-engineer (dispatch wiring) | data-engineer (the schema it validates against) | D-133 places the `--check-readiness` subcommand on the ingestor (backend dispatch), but the readiness schema it loads is data-engineer territory. |
-| `schemas/submission-readiness.schema.json` | data-engineer (schema artifact) | backend-engineer (the validator must match it) | The schema is data-engineer's; the validator (REQ-218) is backend-engineer's and must stay in sync with it. |
+| `schemas/submission-readiness.schema.json` | data-engineer (schema artifact) | backend-engineer (the validator must match it) | The schema is data-engineer's; the validator (REQ-218) is backend-engineer's and must stay in sync with it. |
+
+</details>
@@ -2346,3 +2346,225 @@ committed directly).
  backend pattern (decorators, type hints, stdio, urllib). The SDK v2
  API surface is small and FastAPI/Pydantic-style (already in
  backend-engineer's range). D-143 logged in PERSONAS.md records this.
+
+---
+
+# v1.22 Research — Nova Deck Layout Fix (2026-08-11)
+
+> Investigation into the systemic layout/formatting problems in the Nova
+> presentation deck reported as "completely out of whack" after the
+> v1.21 P5 re-render. This research IS the investigation — the findings
+> below are the empirical root-cause analysis that drives the v1.22
+> requirements (REQ-254..262).
+
+## Background — why v1.22 exists
+
+The v1.21 milestone shipped a refined deck (renamed to "Autonomous Cloud
+Delivery Platform", 4-beat arc, 18 main + 1 appendix slides). The P5
+phase re-rendered the HTML + PPTX and added two new mermaid diagrams
+(`platform-pipeline.png`, `telemetry-live-ops.png`). After P5, the user
+reported that the layout is "completely out of whack" and that "they all
+have layout issues." This research identifies the root cause and the fix
+scope.
+
+## FINDING 1 — Theme CSS has ZERO section padding (CONFIDENCE: VERY HIGH)
+
+`docs/presentations/assets/nova-sp-theme.css` line 1 is
+`/* @theme nova-sp */` — a **comment**, not the `@theme` directive that
+Marp uses to register a theme name. The theme does **not `@import`**
+Marp's default theme. Marp's built-in default theme applies
+`section { padding: 56px 64px; }`. Because this custom theme neither
+imports the default nor sets its own `padding`, the rendered `<section>`
+has **zero padding**.
+
+**Verification:** grep for `padding:56px` / `padding:64px` /
+`padding:96px` in the rendered HTML returns **zero matches**. The only
+`section` rules in the rendered HTML are:
+- `section{width:1280px;height:720px;box-sizing:border-box;overflow:hidden;position:relative;...}`
+  (marpit base — no padding)
+- `section{font-family:...;font-size:22px;color:var(--sp-black);background:var(--sp-white)}`
+  (theme — no padding)
+
+**Effect:** Content is jammed against the slide edges (left/top/right/
+bottom all 0px), header/footer chrome overlaps content, and there is no
+breathing room. This alone makes every slide look "out of whack."
+
+## FINDING 2 — overflow:hidden silently clips dense content (CONFIDENCE: VERY HIGH)
+
+The marpit base rule sets `overflow:hidden` on `section`. The theme adds
+no `overflow` override, no scaling, no shrink-to-fit. Any slide whose
+content exceeds 720px is **clipped with no visual indication**. Combined
+with zero padding, content-dense slides (tables, image+bullets) lose
+their bottom rows / benefit paragraphs.
+
+**Per-slide overflow risk table** (available content height ≈ 720px −
+header(~35px) − footer(~35px) − padding(0px) = ~650px):
+
+| # | Slide | Est. height | Fits? | Issue |
+|---|---|---|---|---|
+| 3 | Objectives + Anti-Goals | ~780px | NO | Densest text slide; nested list |
+| 5 | RACI (8-row × 5-col) | ~700px | NO | Cell text wraps to 2 lines |
+| 6 | Pipeline (image + 4 bullets) | ~750px | NO | Image + bullets overflow |
+| 8 | Attestation (10-row × 4-col) | ~780px | NO | Description column wraps |
+| 9 | Telemetry (image + 4 bullets) | ~720px | NO | Image + bullets overflow |
+| 12 | Deferred (8-row table) | ~720px | NO | Blocking-work column wraps |
+| 15 | Quarter-by-Quarter (5-col) | ~720px | NO | Wide table, long text |
+| A1 | Glossary (13-row × 3-col) | ~700px | NO | On title-class (dark bg) |
+| 1,4,10,11,13,16,17,18 | various | ~620px | TIGHT | Cramped with 0 padding |
+| 2,7,14 | various | ~520px | YES | Manageable density |
+
+**8 of 19 slides overflow; 8 more are cramped.**
+
+## FINDING 3 — Image aspect-ratio catastrophe on slides 6 & 9 (CONFIDENCE: HIGH)
+
+The two new P5 PNGs have extreme, opposite aspect ratios:
+
+- `platform-pipeline.png` = **1568×116** (aspect 13.52, ultra-wide/short).
+  The deck uses `![w:1000]`. At width=1000px, height = 1000/13.52 =
+  **74px**. The `max-height:320px` rule never engages. The image renders
+  as a 1000×74 thin strip — text in nodes is nearly unreadable, and the
+  10-node LR flowchart is squashed.
+
+- `telemetry-live-ops.png` = **1024×1628** (aspect 0.63, tall). The deck
+  uses `![w:900]`. At width=900px the natural height would be **1428px**
+  — but `max-height:320px` clamps it, so the image actually renders at
+  **~201×320**. The `w:900` directive is **completely overridden** by
+  `max-height:320px`. The image is tiny and the explicit width is
+  ignored. The `.mmd` uses `flowchart TB` (top-bottom) — exactly the
+  failure mode the README (line 168) warns against.
+
+## FINDING 4 — Header+footer chrome on every slide (CONFIDENCE: HIGH)
+
+The frontmatter sets both `header:` and `footer:` to the full 51-char
+deck title "Nova — The Autonomous Cloud Delivery Platform" on **every**
+slide (including the title slide, which has `data-header`/`data-footer`
+attributes present but `_paginate: false` only suppresses the page
+number, not the header/footer). The theme gives header a `border-bottom`
+and footer a `border-top`, each consuming ~30-40px of vertical chrome.
+With zero section padding, the header text sits at the very top edge and
+the footer at the very bottom edge, visually colliding with slide
+content. This reduces the effective content area from 720px to roughly
+640-650px on every slide.
+
+## FINDING 5 — render_deck.sh produces unthemed output (CONFIDENCE: MEDIUM-HIGH)
+
+`scripts/render_deck.sh` (line 44) runs marp-cli **without `--theme`**,
+relying on the frontmatter `theme: nova-sp`. But `nova-sp` is **not a
+built-in Marp theme** — it's a custom CSS file. Marp resolves `theme:`
+frontmatter against its built-in theme registry (default, gaia, uncover)
+and registered custom themes via `--theme-set`. Without `--theme <file>`
+or `--theme-set`, Marp cannot resolve `nova-sp` and **falls back to the
+default theme** (or errors). The committed HTML was rendered by
+`render_slides.sh` (which correctly passes `--theme`), so the committed
+artifact is fine — but `render_deck.sh` is a stale, dangerous script
+that would produce an unthemed/default-themed deck if anyone ran it.
+The README (line 201) documents `render_slides.sh` as canonical;
+`render_deck.sh` is not mentioned in the build-commands section.
+
+## FINDING 6 — render_slides.sh missing 2x scale + transparent bg (CONFIDENCE: HIGH)
+
+`render_slides.sh` mermaid invocation (lines 51-55) does **NOT** pass
+`-s 2` (2x scale) or `-b transparent`, despite the README (line 193)
+documenting both as required. This is why `platform-pipeline.png` is
+only 1568px wide (1x) instead of 3136px (2x) — the rendered PNGs are
+lower resolution than the README specifies, contributing to illegibility
+when scaled.
+
+## FINDING 7 — P5 marp-cli version bump (CONFIDENCE: LOW — not the cause)
+
+The P3→P5 HTML diff is 831 changed lines, but the **theme CSS portion
+is byte-identical** (verified: `font-size:22px`, `max-height:320px`,
+`marpit-root-font-size:22px`, `--sp-red:#D6002A` all match; `sp-red`
+appears exactly once in both). The large diff is:
+- (a) marp-cli boilerplate (bespoke-marp presenter/overview/transition
+  CSS) changed due to a marp-cli version bump (neither script pins a
+  version — both use `@latest`), and
+- (b) content changes: title "No-Humans Infrastructure Platform" →
+  "Autonomous Cloud Delivery Platform", footer "Act %{page}/5 — v1.20"
+  → deck title, slide count 20 → 19.
+
+The version bump did **not** alter the slide layout engine or the theme
+rules. **This is not the regression source.** The layout problems are
+inherent to the theme CSS (zero padding, no overflow handling, blunt
+image rule) which has been unchanged. P5 made the content denser (new
+diagrams with extreme aspect ratios, longer deck-title header/footer)
+which made the pre-existing theme flaws more visible.
+
+## FINDING 8 — Test coverage gaps (CONFIDENCE: VERY HIGH)
+
+`tests/test_slides_pipeline.py` (268 lines) checks **static file
+properties only**:
+- Theme CSS file exists and contains `#D6002A` / `#1B1B1B`
+- Frontmatter references `nova-sp`, not `default`
+- `render_slides.sh` exists, is executable, invokes mermaid-cli + marp-cli
+- Every `.mmd` has a `.png`
+- No maturity badges, no version in footer, slide count = 18+1
+- No D-###/REQ-###/internal `.py` paths in slides
+
+**What is NOT tested (the gaps that let layout regressions through):**
+1. NO rendered-dimension / overflow test — no test renders the HTML and
+   checks that each slide's content height ≤ 720px.
+2. NO theme-CSS structural test — no test asserts `section` has
+   `padding`, that `overflow` is handled, or that `img` rules don't
+   conflict with `w:`/`h:` directives.
+3. NO image aspect-ratio / legibility test — no test checks that PNG
+   dimensions are reasonable for a 16:9 slide.
+4. NO render-script theme-flag test — no test asserts `render_deck.sh`
+   passes `--theme` (it doesn't), so the broken script passes CI.
+5. NO rendered-HTML structural assertion — no test parses the committed
+   HTML to verify the theme is actually embedded.
+6. NO mermaid render-scale test — no test verifies PNGs are 2x scale.
+
+**Conclusion:** A layout regression — including the current zero-padding,
+image-clamping, and table-overflow problems — would pass every existing
+test. This is why the user's "completely out of whack" report was not
+caught.
+
+## Theme CSS gaps (summary)
+
+1. NO `padding` on `section` (lines 21-26 set font/color/bg only).
+2. NO `overflow` handling on `section`.
+3. NO `@import` of a base theme (line 1 is a comment, not `@theme`).
+4. NO rule for the `h2` + bold-lead-paragraph pattern (default `<p>`
+   margins waste ~44px each).
+5. Table cell padding `6px 10px` too generous for 10-13 row tables.
+6. `img { max-height: 320px }` is a blunt instrument that breaks `w:`
+   directives on tall images and does nothing for ultra-wide images.
+7. Header/footer have no padding/margin — collide with content at 0
+   section padding.
+8. `section.title` does not suppress header/footer.
+9. NO rule for `ol` (only `ul`/`li` styled).
+10. NO `@media print` overrides for PPTX export fidelity.
+
+## Assumptions logged (v1.22)
+
+- **A1 (0.95):** The theme CSS is the primary root cause. Adding
+  `section { padding: 48px 56px 40px; }` alone would fix the "jammed
+  against edges" look on all 19 slides. Confidence grounded in the
+  grep verification (zero padding matches in rendered HTML).
+- **A2 (0.9):** The P5 re-render is NOT a regression — the theme CSS is
+  byte-identical P3→P5. P5's denser content (new diagrams, longer
+  header/footer) made pre-existing flaws visible. Grounded in the
+  byte-level diff comparison.
+- **A3 (0.9):** `render_deck.sh` should be deleted, not fixed. The
+  README already documents `render_slides.sh` as canonical; keeping a
+  second broken script is a footgun. Grounded in the README build-
+  commands section (line 201) which does not mention `render_deck.sh`.
+- **A4 (0.85):** Splitting slides 3 and 8 (18 → 20 main) is preferable
+  to trimming content, because the content is leadership-relevant and
+  should not be lost. The slide-count test + README convention are
+  updated to match. Grounded in the overflow estimates (slides 3 and 8
+  are the densest at ~780px).
+- **A5 (0.8):** Pinning marp-cli/mermaid-cli versions is necessary to
+  prevent uncontrolled boilerplate-CSS drift. The exact pinned versions
+  will be determined during P2 execution by testing which version
+  produces stable output in this environment.
+
+## Decisions surfaced (research → bound in CLARIFY)
+
+All 5 CLARIFY decisions are grounded in these findings:
+- Comprehensive scope (FINDINGS 1-8 span 4 layers)
+- Full pipeline (new milestone, complete audit trail)
+- Re-layout to LR (FINDING 3 — TB produced 0.63 aspect)
+- Delete render_deck.sh (FINDING 5 — stale, unthemed)
+- Split slides 3+8 (FINDING 2 — densest overflow)