CIAgent
275 lines
13 KiB
Markdown
275 lines
13 KiB
Markdown
# 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. | |