From 75e9e479dbd435aca0125e73ff422d7aa37cdfd0 Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Tue, 11 Aug 2026 23:49:45 +0000 Subject: [PATCH] =?UTF-8?q?docs(init):=20validate=20specification=20?= =?UTF-8?q?=E2=80=94=20v1.23=20milestone=20(REQ-263..275)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Established active_milestone: v1.23 (Nova Deck Cleanup & Python PPTX). NFR milestone (docs/render/test only; no features). Tags on v1.22.x line (v1.22.0 P0 -> v1.22.6 P6 final = milestone release). Branch: milestone/v1.23-deck-cleanup-python-pptx. Added REQ-263..275 to REQUIREMENTS.md covering: - Consolidate docs: single -marp.md source of truth, delete plain .md, speaker notes/talking points as Marp HTML comments, keep talking-points.md as synced standalone aid (REQ-263,264) - Restore clean style: theme:default + inline style block (S&P palette), retire nova-sp-theme.css from render (keep as reference), benefit callout restyle (REQ-265,266,267) - Inline images: scripts/inline_images.py for self-contained redistributable HTML (REQ-268) - Python PPTX generator: scripts/render_pptx.py structured editable S&P-themed PPTX via python-pptx, both PPTX outputs produced + attached (REQ-269,270) - Trim word count: targeted ~20-30% trim on verbose slides, remove 'penetrate' term (REQ-271,272) - CI/tests/README: workflows install python-pptx, tests updated, README rewritten (REQ-273,274,275) Driven by user feedback: deck looked 'out of whack'; wanted to return to the clean style of the old the-developer-experience.html. Investigation revealed the 'clean' reference was itself MARP output (default theme + inline style); the standalone nova-sp-theme.css approach was fragile. ---ci--- project: acdl phase: 0 milestone: v1.23 status: specify ---/ci--- --- .ciagent/CHECKPOINT.json | 31 ++-------- .ciagent/PROJECT.md | 45 ++++++++++++++ .ciagent/REQUIREMENTS.md | 124 +++++++++++++++++++++++++++++++++++++++ .ciagent/ROADMAP.md | 80 +++++++++++++++++++++++++ .ciagent/config.json | 2 +- 5 files changed, 256 insertions(+), 26 deletions(-) diff --git a/.ciagent/CHECKPOINT.json b/.ciagent/CHECKPOINT.json index 9885774..499b7d6 100644 --- a/.ciagent/CHECKPOINT.json +++ b/.ciagent/CHECKPOINT.json @@ -1,28 +1,9 @@ { - "phase": 6, - "stage": "complete", - "milestone": "v1.22", - "phase_role": "final", + "phase": 0, + "stage": "specify", + "milestone": "v1.23", + "phase_role": "pre_execution", "attempts": 0, - "updated_at": "2026-08-11T15:30:00Z", - "milestone_complete": true, - "tag": "v1.21.6", - "requirements": ["REQ-254","REQ-255","REQ-256","REQ-257","REQ-258","REQ-259","REQ-260","REQ-261","REQ-262"], - "release": { - "forge": "gitea", - "releases_created": true, - "release_ids": { - "v1.21.0": 621, - "v1.21.1": 622, - "v1.21.2": 623, - "v1.21.3": 624, - "v1.21.4": 625, - "v1.21.5": 626, - "v1.21.6": 627 - }, - "milestone_release_id": 627, - "pptx_asset_id": 98, - "pptx_download_url": "https://git.cloudinit.dev/attachments/fe691962-4f4e-4321-ab5d-c2bb8c3fd6ad" - }, - "notes": "v1.22 milestone complete. Tag v1.21.6 (milestone release). Merged to main + pushed to origin. All 7 Gitea releases created (ids 621-627). PPTX attached to milestone release (asset id 98). All milestone branches deleted. 9 requirements complete (REQ-254..262). 32 slide tests pass (23 original + 9 new). 94 key-file tests pass. Pipeline check exit 0. Next milestone starts fresh." + "updated_at": "2026-08-11T23:30:00Z", + "project": "acdl" } \ No newline at end of file diff --git a/.ciagent/PROJECT.md b/.ciagent/PROJECT.md index 04b14a7..d8251b9 100644 --- a/.ciagent/PROJECT.md +++ b/.ciagent/PROJECT.md @@ -1532,3 +1532,48 @@ New requirements REQ-254..REQ-262 — see `REQUIREMENTS.md` §v1.22. Summary: A1) + remove redundant `header:` from frontmatter. - **REQ-262:** Re-render HTML + PPTX + add layout/aspect-ratio/theme- structural tests. + +## v1.23 — Nova Deck Cleanup & Python PPTX + +> **Active milestone.** NFR (docs/render/test only; no features). +> Branch: `milestone/v1.23-deck-cleanup-python-pptx`. Tags run on the +> **v1.22.x** patch line: `v1.22.0` (P0) → `v1.22.1..v1.22.5` (P1–P5) → +> `v1.22.6` (P6 final = milestone release). + +Driven by user feedback that the deck looked "out of whack" and the +desire to return to the clean, well-formatted style of the old +`the-developer-experience.html`. Investigation revealed the "clean" +reference was itself MARP output (using Marp's built-in `default` theme ++ an inline `style:` block); the current deck's standalone +`nova-sp-theme.css` re-derives all base spacing from scratch and had a +zero-padding bug (fixed in v1.22, but the standalone approach is +fragile). The milestone delivers: + +- **Single-document consolidation** — `*-marp.md` becomes the sole + source of truth; the plain `.md` is deleted; speaker notes + talking + points are embedded as Marp HTML comments. +- **Clean style restoration** — revert to `theme: default` + inline + `style:` block (S&P palette); `nova-sp-theme.css` retained as a + reference, retired from render. +- **Self-contained HTML** — base64-inline all images for + redistribution. +- **Parallel python-pptx generator** — structured, editable, S&P-themed + PPTX alongside the MARP image-of-slide PPTX. +- **Targeted word-count trim** + "penetrate" term removal. + +**Phase count:** 7 (P0 pre-execution + 5 execution + 1 final). + +**Hard constraints:** +- DO NOT change the deck narrative or the 4-beat arc (Problem → Solution + → Proof → Roadmap + Ask) — only trim word count. +- DO NOT re-introduce badges, version strings, or internal citations. +- DO NOT remove MARP — it stays for HTML + PPTX; python-pptx runs in + parallel. +- `nova-sp-theme.css` is retained (not deleted) as a styling reference. + +### Requirements + +New requirements REQ-263..REQ-275 — see `REQUIREMENTS.md` §v1.23. +Summary: consolidation (REQ-263,264), style restoration (REQ-265,266,267), +image inlining (REQ-268), python-pptx generator (REQ-269,270), word-count +trim + "penetrate" removal (REQ-271,272), CI/tests/README (REQ-273,274,275). diff --git a/.ciagent/REQUIREMENTS.md b/.ciagent/REQUIREMENTS.md index e04c9a2..72ebb1a 100644 --- a/.ciagent/REQUIREMENTS.md +++ b/.ciagent/REQUIREMENTS.md @@ -1904,3 +1904,127 @@ assert 20 main + 1 appendix. | REQ-260 | P3 | complete | | REQ-261 | P4 | complete | | REQ-262 | P5 | complete | + +## v1.23 — Nova Deck Cleanup & Python PPTX + +> **NFR milestone** (docs/render/test only; no features). Tags run on the +> **v1.22.x** line (milestone v1.23 → tags v1.22.0..v1.22.6). Final patch +> `v1.22.6` = milestone release. +> +> Consolidates the deck to a single source-of-truth markdown document, +> restores the clean S&P visual style (Marp `default` theme + inline +> `style:` block, matching the old `the-developer-experience.html`), +> embeds images as base64 in the HTML for redistribution, builds a +> parallel structured python-pptx PPTX generator, and trims verbose +> slides. `nova-sp-theme.css` is retained as a styling reference but +> retired from the render path. + +### Category: Consolidate Docs +- **REQ-263:** `nova-autonomous-cloud-delivery-marp.md` becomes the sole + source of truth. Speaker notes + talking points from the plain `.md` + are folded into the deck as Marp HTML comments (``, ``). The plain + `nova-autonomous-cloud-delivery.md` is deleted. +- **REQ-264:** `nova-autonomous-cloud-delivery-talking-points.md` is kept + as a standalone presenter aid, synced from the deck's `` comments. Header note documents the mirror relationship. + +### Category: Restore Clean Style +- **REQ-265:** Revert deck frontmatter `theme: nova-sp` → `theme: + default` and add an inline `style:` block porting the S&P visual + language (palette #D6002A/#1B1B1B, Akkurat Pro font, black title slide + with red top border, tables, blockquotes, code, aspect-ratio-aware + images). Keep current structure (H2 + bold-lead, no header, no badges). +- **REQ-266:** `nova-sp-theme.css` is retained as a styling reference + (header comment documents its retired status). `render_slides.sh` + drops the `--theme "$THEME_CSS"` argument; the inline `style:` block in + frontmatter is the sole styling source at render time. +- **REQ-267:** Benefit callouts on every slide are restyled: the + `**Benefit:**` prefix is removed; the callout becomes a styled + element (red top-rule + black italic text; white on title slides) + using a `.benefit` class in the inline style block. + +### Category: Inline Images +- **REQ-268:** New `scripts/inline_images.py` (stdlib only: `base64`, + `re`, `mimetypes`) post-processes the rendered HTML: finds all + `` relative paths, replaces each `src` with a + `data:image/;base64,...` URI. HTML becomes self-contained + (redistributable without the `assets/` folder). `render_slides.sh` + invokes it after the MARP HTML render, before staging. + +### Category: Python PPTX Generator +- **REQ-269:** New `scripts/render_pptx.py` parses the consolidated + `*-marp.md` and produces a structured, editable, S&P-themed PPTX + (`nova-autonomous-cloud-delivery-python.pptx`) using `python-pptx`. + 16:9 slides; title slide (black bg, red top bar, white H1); content + slides (red H2 title, bold lead, bullets, blockquote, embedded PNGs, + native PPTX tables, benefit callouts). HTML-comment speaker + notes/talking points are skipped. `python-pptx` added to + `pyproject.toml`. `render_slides.sh` invokes it as a new step. +- **REQ-270:** Both PPTX outputs (MARP image-of-slide + python + structured) are produced by `render_slides.sh` and staged. CI + workflows install `python-pptx` and commit both. `attach_release_asset.py` + attaches both to the release. + +### Category: Trim Word Count +- **REQ-271:** Targeted word-count trim on ~8 verbose slides (1, 5, 7, + 8, 13, 14, 20, plus the appendix) — ~20-30% reduction on trimmed + slides. Tables and short slides are untouched. The spirit of each + slide is preserved. +- **REQ-272:** The term "penetrate" (and derivatives) is removed from + all presentation files. Slide 5's "Nova never penetrates it" phrase is + removed with no replacement (slide 4 Anti-Goals already excludes the + PDLC from scope). `grep -ri penetrat docs/presentations/` returns + nothing. + +### Category: CI, Tests, README +- **REQ-273:** CI workflows (`workflows-src/slides.yml` + synced + `.github`/`.gitea` copies) install `python-pptx`, run `render_slides.sh` + (which produces HTML + both PPTX + inlined images), and commit all + rendered artifacts. README documents the new pipeline. +- **REQ-274:** `tests/test_slides_pipeline.py` is updated for the + consolidated doc (no plain `.md`), default theme + inline style + assertions (S&P visual properties, not theme filename), + `nova-sp-theme.css` retained-as-reference assertion, image-inlining + assertions (zero `src="assets/` references, ≥1 base64 per image), + python-pptx output existence, benefit callout class, "penetrate" + absence. New `tests/test_pptx_generator.py` asserts slide count, title + colors, table rendering, image embedding. +- **REQ-275:** `docs/presentations/README.md` is rewritten to document + the single-document process (author `*-marp.md` → render HTML + both + PPTX → talking points mirrored), inline `style:` approach, + `nova-sp-theme.css` reference status, image inlining, and dual PPTX + output. + +### Out of Scope (v1.23) + +- **Deck narrative / 4-beat arc changes** — the Problem → Solution → + Proof → Roadmap + Ask structure is unchanged; only word count is + trimmed. +- **Re-introduction of badges, version strings, or internal citations** + — v1.21 removed these; v1.23 does not re-add them. +- **Removal of MARP** — MARP stays for HTML + PPTX; python-pptx runs in + parallel for comparison. +- **Removal of orphaned `developer-experience-*` assets** — deferred to + a future cleanup phase (optional in v1.23 Phase 6 only if time + permits). +- **Mermaid render scoping** — the mermaid render step continues to + render all `.mmd` files; scoping to referenced-only is deferred. + +### v1.23 Traceability + +| REQ | Phase | Status | +|-----|-------|--------| +| REQ-263 | P1 | pending | +| REQ-264 | P1 | pending | +| REQ-265 | P2 | pending | +| REQ-266 | P2 | pending | +| REQ-267 | P2 | pending | +| REQ-268 | P3 | pending | +| REQ-269 | P3 | pending | +| REQ-270 | P3 | pending | +| REQ-271 | P4 | pending | +| REQ-272 | P4 | pending | +| REQ-273 | P5 | pending | +| REQ-274 | P5 | pending | +| REQ-275 | P5 | pending | diff --git a/.ciagent/ROADMAP.md b/.ciagent/ROADMAP.md index 6b31923..cbad3c1 100644 --- a/.ciagent/ROADMAP.md +++ b/.ciagent/ROADMAP.md @@ -2070,3 +2070,83 @@ release). **DONE.** `milestone/v1.22-deck-layout-fix` → `main`. Requirements marked complete; ROADMAP marked complete; CHECKPOINT cleared. - **Requirements:** REQ-254..262 (9 requirements, all complete). + +## v1.23 — Nova Deck Cleanup & Python PPTX (active) + +> **NFR milestone** (docs/render/test only; no features). Tags run on the +> **v1.22.x** line (milestone v1.23 → tags v1.22.0..v1.22.6). Final patch +> `v1.22.6` = milestone release. Branch: `milestone/v1.23-deck-cleanup-python-pptx`. +> +> Driven by the user's feedback that the deck looked "out of whack" and +> the desire to return to the clean, well-formatted style of the old +> `the-developer-experience.html` (which used Marp's built-in `default` +> theme + an inline `style:` block). That investigation revealed: +> (1) the "clean" reference was itself MARP output — MARP is not the +> problem; (2) the current deck uses a standalone `nova-sp-theme.css` +> that re-derives all base spacing from scratch and had a zero-padding +> bug (fixed in v1.22 but the standalone approach is fragile); +> (3) there are two markdown documents (a plain source-of-truth `.md` +> and a manually-synthesized `-marp.md`) that should be consolidated; +> (4) images are referenced as file paths in the HTML, so the HTML +> breaks when redistributed without the `assets/` folder; (5) the deck +> is verbose in places and uses the term "penetrate" which the user +> wants removed. +> +> The milestone delivers: single-document consolidation, clean style +> restoration (Marp `default` + inline `style:`), self-contained HTML +> (base64 images), a parallel structured python-pptx PPTX generator, +> targeted word-count trim, and "penetrate" removal. `nova-sp-theme.css` +> is retained as a styling reference but retired from the render path. + +### Phase P0 — pre-execution (active) +- SPECIFY → CLARIFY → RESEARCH → PLAN → GRILL. Establishes v1.23 + requirements (REQ-263..275). Tag `v1.22.0`. + +### Phase P1 — consolidate-docs (planned, tag v1.22.1) +- REQ-263: fold speaker notes + talking points into `*-marp.md` as Marp + HTML comments; delete the plain `.md`. `-marp.md` becomes the sole + source of truth. +- REQ-264: keep `*-talking-points.md` as a standalone presenter aid, + synced from the deck's `` comments. + +### Phase P2 — restore-clean-style (planned, tag v1.22.2) +- REQ-265: revert frontmatter to `theme: default` + inline `style:` + block (S&P palette). Keep H2 + bold-lead structure, no header, no + badges. +- REQ-266: retain `nova-sp-theme.css` as a styling reference; drop + `--theme` from `render_slides.sh`. +- REQ-267: restyle benefit callouts — remove `**Benefit:**` prefix; use + `.benefit` class (red top-rule + black italic; white on title slides). + +### Phase P3 — inline-images + python-pptx-generator (planned, tag v1.22.3) +- REQ-268: new `scripts/inline_images.py` — base64-embeds all images in + the rendered HTML for redistribution. Invoked after the MARP HTML + render. +- REQ-269: new `scripts/render_pptx.py` — structured, editable, S&P-themed + PPTX via `python-pptx`. 16:9; native tables; embedded PNGs; benefit + callouts. Add `python-pptx` to `pyproject.toml`. +- REQ-270: `render_slides.sh` produces both PPTX outputs; CI installs + `python-pptx`; both attached to release. + +### Phase P4 — trim-wordcount (planned, tag v1.22.4) +- REQ-271: targeted ~20-30% word-count trim on verbose slides (1, 5, 7, + 8, 13, 14, 20, appendix). Tables untouched. Spirit preserved. +- REQ-272: remove "penetrate" (and derivatives) from all presentation + files. Slide 5's phrase removed with no replacement (slide 4 + already excludes the PDLC). + +### Phase P5 — ci-tests-readme (planned, tag v1.22.5) +- REQ-273: CI workflows install `python-pptx`, run `render_slides.sh`, + commit HTML + both PPTX + inlined images. +- REQ-274: update `test_slides_pipeline.py` (consolidated doc, inline + style assertions, image inlining, python-pptx, benefit class, + "penetrate" absence). New `test_pptx_generator.py`. +- REQ-275: rewrite `README.md` for the single-document + dual-PPTX + + image-inlining pipeline. + +### Phase P6 — final-review-ship (Final Phase, planned, tag v1.22.6) +- Multi-persona code review across all phases. +- Audit: git log matches `.ciagent/` discipline. +- Ship: tag `v1.22.6` (final patch = milestone release). Merge + `milestone/v1.23-deck-cleanup-python-pptx` → `main`. +- **Requirements:** REQ-263..275 (13 requirements). diff --git a/.ciagent/config.json b/.ciagent/config.json index 80545a1..8dcb605 100644 --- a/.ciagent/config.json +++ b/.ciagent/config.json @@ -8,7 +8,7 @@ ], "active_project": "acdl", "active_projects": ["acdl"], - "active_milestone": "v1.22", + "active_milestone": "v1.23", "autonomy": { "level": "full", "escalation_hooks": ["deploy", "delete_data", "merge_to_main"],