continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 128 Wiki Activity

docs(P3): marp deck + talking points + README + theme CSS + tests (REQ-245,251,252)
Nova Slides Render / render (push) Failing after 58s
Details

Browse Source 
Marp deck (nova-autonomous-cloud-delivery-marp.md): synthesize from updated
source-of-truth; 18 main + 1 appendix slides; frontmatter — title 'Nova —
The Autonomous Cloud Delivery Platform', footer without version + without
'Act %{page}/5', title-slide subtitle 'Product Development & Citizen
Developer Overview'; no badges; embedded PNGs.

Talking points (nova-autonomous-cloud-delivery-talking-points.md):
re-distilled to 18-slide + A1 structure.

README.md: update deck title, audience, slide count (18 main + 1 appendix),
directory layout, remove badge docs, update deck table + render commands +
filenames. Document the v1.21 rename + restructure.

Theme CSS (nova-sp-theme.css): fix Appendix A1 table readability — tables
now have explicit white body + black text on any slide background
(including dark/title slides). Item 32.

Tests (test_slides_pipeline.py): add v1.21 assertions — no badges; no
version in footer/title slide; 18 main + 1 appendix slides; no D-###/REQ-
###/.py paths in audience-facing Marp deck or source slide body; old deck
files removed; render script default renamed; README references new deck
name. Update deck path in test_regression_cap023_024.py +
core/regression_verify.py CAP-024 (filename + 18-19 slide range, drop 'Arc
Preview' check per item 3).

attach_release_asset.py: usage example filename updated.

---ci---
project: acdl
phase: 3
milestone: v1.21
status: execute
phase_role: execution
---/ci---
This commit is contained in:
Jon Chery
2026-08-11 14:03:06 +00:00
parent 707a7dbe9b
commit 301aa2c8d8
8 changed files with 523 additions and 581 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/presentations/README.md
+69 -160
View File
@@ -13,17 +13,18 @@ every deck and a presenter-ready cue sheet for delivery.
```
Step 1: full markdown Step 2: Marp deck Step 3: HTML + PPTX Step 4: Talking points
(source of truth) ──► (lean, 10 slides) ──► (rendered) ──► (presenter cues)
(source of truth) ──► (lean, 19 slides) ──► (rendered) ──► (presenter cues)
*.md *-marp.md *.html / *.pptx *-talking-points.md
+ speaker notes + embedded PNG diagrams + 3-6 bullets per slide
+ mermaid code blocks + Marp frontmatter + key takeaway per slide
+ maturity badges + indexed by Marp slide #
+ no speaker notes + content distilled from Step 1
+ no speaker notes + indexed by Marp slide #
+ no maturity badges + content distilled from Step 1
+ no version in footer
```
### Step 1 — Full markdown (source of truth)
**File convention:** `<deck-name>.md` (e.g. `nova-no-humans-platform.md`).
**File convention:** `<deck-name>.md` (e.g. `nova-autonomous-cloud-delivery.md`).
Write the complete deck as a standard markdown file. This is the **source of
truth** — it contains:
@@ -34,9 +35,9 @@ truth** — it contains:
the "who cares and why," and the honesty caveats.
- Mermaid diagrams as ```` ```mermaid ```` fenced code blocks (these render
on GitHub/Pages but not in Marp — Step 2 converts them to images).
- An honest "shipped vs. planned" framing: every "available today" claim is
grounded in shipped/verified work; every "planned" item is explicitly
marked.
- An honest "shipped vs. deferred" framing: every "available today" claim is
grounded in shipped/verified work; every "deferred" item is explicitly
marked with the blocking work in plain language.
**Why this file is the source of truth:** it is reviewable in any markdown
viewer, diffs cleanly in git, and carries the full reasoning (speaker notes)
@@ -45,13 +46,13 @@ fact is wrong, fix it here and re-run Steps 2 and 3.
### Step 2 — Marp deck synthesis
**File convention:** `<deck-name>-marp.md` (e.g. `nova-no-humans-platform-marp.md`).
**File convention:** `<deck-name>-marp.md` (e.g. `nova-autonomous-cloud-delivery-marp.md`).
Synthesize the full markdown into a lean Marp deck:
- **Marp frontmatter** at the top: `marp: true`, `theme: default`,
- **Marp frontmatter** at the top: `marp: true`, `theme: nova-sp`,
`paginate: true`, `size: 16x9`, a header/footer, and an inline `style:`
block for fonts, colors, tables, badges.
block for fonts, colors, tables.
- **No speaker notes.** The Marp deck is what the audience sees; the
speaker notes live only in the Step 1 source of truth.
- **Mermaid diagrams → PNG images.** Marp does not render mermaid fenced
@@ -60,8 +61,10 @@ Synthesize the full markdown into a lean Marp deck:
and embed it with `![w:1000](assets/png/<name>.png)`.
- **`<!-- _class: title -->` + `<!-- _paginate: false -->`** on title and
closing slides for the dark-background title style.
- **Maturity badges** using inline spans:
`<span class="badge planned">Planned</span>`
- **No maturity badges.** The deck no longer uses `<span class="badge">`
spans. Deferred items are named in plain language with their blocking
work, not tagged with a badge.
- **No version in the footer.** The footer carries the deck title only.
- **Tighter prose** than Step 1 — strip the speaker-note nuance; keep the
leadership-relevant selling points.
@@ -69,10 +72,8 @@ Synthesize the full markdown into a lean Marp deck:
Both formats are derived from the Marp deck. **HTML is committed to the repo**
(viewable in any browser, self-contained with base64-embedded images). **PPTX
is uploaded to the release** as a downloadable attachment (binary, not
committed to git).
#### HTML export (committed to repo)
is also committed to the repo** as a first-class binary artifact and is
attached to the phase's release via `scripts/attach_release_asset.py`.
```bash
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
@@ -81,135 +82,67 @@ CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
-o docs/presentations/<deck-name>.html
```
HTML export inlines images as base64 data URIs — no `--allow-local-files`
needed for self-contained output, but it's required when the Marp deck
references local PNG assets. The resulting HTML is a single self-contained
file that renders the full deck with the S&P Global Energy theme.
**Re-render the HTML whenever the Marp source changes.** The HTML files are
committed artifacts, not generated on-the-fly — they must be re-rendered and
re-committed when the Marp deck is updated.
#### PPTX export (uploaded to release)
```bash
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
npx --yes @marp-team/marp-cli@latest --allow-local-files \
docs/presentations/<deck-name>-marp.md \
-o <output-path>.pptx
```
The `--allow-local-files` flag is **required** for PPTX export so the local
PNG diagrams are embedded in the file. As of v1.18 (REQ-228, D-141), PPTX
files **are committed to the repo** as first-class binary artifacts (no LFS)
and are also attached to the phase's release via
`scripts/attach_release_asset.py`. The render + commit + attach pipeline is
automated by `scripts/render_deck.sh`.
HTML export inlines images as base64 data URIs. PPTX export requires
`--allow-local-files` so the local PNG diagrams are embedded in the file.
The render + commit + attach pipeline is automated by `scripts/render_deck.sh`
and `scripts/render_slides.sh`.
### Step 4 — Talking points (presenter cues)
**File convention:** `<deck-name>-talking-points.md` (e.g.
`nova-no-humans-platform-talking-points.md`).
`nova-autonomous-cloud-delivery-talking-points.md`).
Distill the source of truth (Step 1) into presenter-ready cues, indexed by
the Marp deck (Step 2) slide structure:
- **One section per Marp slide** — `## Slide N — Title`, matching the Marp
deck's 11 main + Appendix TOC + appendix slide structure exactly. The Marp deck
provides the indexing and context (what the audience sees); the source
markdown provides the content (the speaker notes, the detail, the nuance).
deck's 18 main + 1 appendix slide structure exactly.
- **3-6 talking point bullets per slide** — punchy, actionable cues distilled
from the source markdown's speaker notes. NOT the speaker notes verbatim
(those are too long and too contextual). These are prompts: "Land this
point," "Contrast with X," "Be honest about Y."
from the source markdown's speaker notes.
- **Key takeaway per slide** — the one memorable thing the audience should
walk away with from that slide.
- **No content duplication** — the talking points reference the Marp slides
for visual context and the source markdown for full detail. They don't
repeat either; they bridge them.
**Why this file exists:** a presenter needs a cue sheet they can glance at
during delivery — not the full speaker notes (too long), not the Marp slides
(no detail). The talking points file is the middle layer: what to say, in
what order, with what emphasis, per slide.
**When to update:** re-distill the talking points whenever the Marp deck
structure changes (slides added, removed, merged, or re-ordered) or whenever
the source markdown's speaker notes are updated. The talking points are a
*derived artifact* — if a fact is wrong, fix it in the source markdown (Step 1)
and re-distill.
for visual context and the source markdown for full detail.
## Directory layout
```
docs/presentations/
├── README.md ← this file
├── nova-no-humans-platform.md ← Step 1: full source of truth (19 main slides + speaker notes)
├── nova-no-humans-platform-marp.md ← Step 2: Marp deck (19 main + 2 appendix = 21 slides)
├── nova-no-humans-platform.html ← Step 3: rendered HTML (committed, S&P-themed)
├── nova-no-humans-platform.pptx ← Step 3: rendered PPTX (committed, S&P-themed)
├── nova-no-humans-platform-talking-points.md ← Step 4: presenter cues (21 sections)
├── nova-autonomous-cloud-delivery.md ← Step 1: full source of truth (18 main slides + speaker notes)
├── nova-autonomous-cloud-delivery-marp.md ← Step 2: Marp deck (18 main + 1 appendix = 19 slides)
├── nova-autonomous-cloud-delivery.html ← Step 3: rendered HTML (committed, S&P-themed)
├── nova-autonomous-cloud-delivery.pptx ← Step 3: rendered PPTX (committed, S&P-themed)
├── nova-autonomous-cloud-delivery-talking-points.md ← Step 4: presenter cues (19 sections)
└── assets/
├── nova-sp-theme.css ← S&P Global Energy Marp theme (all slide chrome)
├── puppeteer-config.json ← no-sandbox config for mmdc
├── mmd/ ← mermaid source files (Step 2 input)
│ ├── sp-theme.json ← S&P Red/Black/White theme (mermaid-cli --configFile)
│ ├── platform-architecture.mmd
│ ├── road-to-north-star.mmd
│ └── ... (per-slide .mmd files)
└── png/ ← rendered mermaid PNGs (committed, S&P-themed)
└── png/ ← rendered PNGs (embedded in Marp)
├── platform-works-01-contract-driven.png
├── platform-works-02-frictions.png
├── platform-works-02-end-to-end-flow.png
├── platform-works-03-north-star.png
├── platform-works-03-scope-boundary.png
├── platform-works-04-confidence-signal.png
├── platform-works-05-attestation-flow.png
├── platform-works-07-zero-trust.png
├── developer-experience-01b-scope-boundary.png
├── developer-experience-02-what-dev-does.png
├── developer-experience-03-no-cloning.png
├── developer-experience-04-promotion-journey.png
├── developer-experience-05-catalog.png
├── developer-experience-07-decommission.png
├── developer-experience-08-semver.png
├── platform-architecture.png ← shared high-level logical architecture (both decks)
└── road-to-north-star.png
```
## Conventions
### Appendix structure
Each Marp deck has **11 main slides + an Appendix TOC + appendix slides**. The
main 11 are the presentation; the appendix is for deep dives and Q&A backup.
The platform-works deck has 8 appendix slides (A1–A8); the developer-experience
deck has 7 appendix slides (A1–A7). Both include an Appendix TOC slide.
Each Marp deck has **18 main slides + 1 appendix slide**. The main 18 are the
presentation; the appendix is for Q&A backup.
- **Main slides** (1-11): the story arc, high-impact, minimal text,
visual-heavy. These are what the audience sees during the talk.
- **Appendix slides** (TOC + A1..An): detail-heavy slides moved out of the
main 10 to preserve the narrative flow. The appendix starts with a TOC
slide listing the contents, followed by detail slides and a glossary.
- **The Road to the North Star** is a required appendix slide in both decks
— a phased timeline from v1.0 demo to the North Star, annotated as
"proposed phasing, not formally planned."
- **The Glossary** is a required appendix slide in both decks — defines
acronyms (OIDC, ABAC, CMK, CMDB, RPO, HITL, VCS, NFR) for the audience.
- **Main slides** (1-18): the story arc — Problem → Solution → Proof →
Roadmap + Ask. These are what the audience sees during the talk.
- **Appendix slide** (A1): the Metrics Glossary — detail-heavy reference for
Q&A.
### Maturity framing
### Honesty framing
Every capability claim in a deck is tagged with a `Planned` badge when the item is on the roadmap but not yet implemented:
| Badge | Meaning |
|---|---|
| `Planned` | On the roadmap, not yet implemented |
This is non-negotiable for a leadership audience: never present a roadmap
item as a current capability, and never bury a tested capability's
availability. When in doubt, check `.ciagent/ROADMAP.md` and the milestone
status in `.ciagent/PROJECT.md`.
Every capability claim in the deck is grounded, derived, or honestly
deferred with its blocking work named in plain language. Internal provenance
(decision IDs, requirement IDs, internal file paths) is kept out of the
audience-facing slides — those live in the `.ciagent/` files only. When in
doubt, check `.ciagent/ROADMAP.md` and the milestone status in
`.ciagent/PROJECT.md`.
### Audience
@@ -221,8 +154,10 @@ Head of Infrastructure, Head of DevOps. The framing rules:
"composition."
- **Selling points forward.** Each slide leads with the leadership-relevant
outcome; the mechanism follows.
- **Zero-trust, security, observability, auditability, DX, citizen
developer** are the themes — not implementation details.
- **Security, remediation velocity, reliability, lead time, observability,
citizen developer** are the themes — not implementation details.
- **"Infrastructure operations become visible"** is the recurring theme across
the deck.
### Diagrams
@@ -232,8 +167,7 @@ style (renders on GitHub/Pages). For the Marp deck (Step 2):
1. Extract the mermaid block into `assets/mmd/<deck>-<slide>-<name>.mmd`.
2. Use **horizontal layouts** (`flowchart LR`) or **subgraph row-wrapping**
for wide diagrams so the PNG fits a 16:9 slide without shrinking to
illegibility. A 9-node sequential `flowchart TD` renders as a tall thin
strip — restructure it as 2-row subgraphs or `flowchart LR`.
illegibility.
3. Render with a 2x scale factor and transparent background for crisp slides.
4. Embed with `![w:1000](assets/png/<name>.png)` (or `h:320` for tall images).
@@ -261,42 +195,16 @@ for f in mmd/*.mmd; do
done
```
The `puppeteer-config.json` passes `--no-sandbox` to the headless browser
(required when running as root in this environment). The `--configFile
mmd/sp-theme.json` applies the S&P Global Red/Black/White theme (dark
`#1B1B1B` accent nodes with `#D6002A` red borders, white supporting nodes,
`#F0F0F0` subgraph backgrounds). Each `.mmd` file also carries the same
theme inline via a `%%{init:...}%%` block so it renders correctly even
without the `--configFile` flag.
### Export a Marp deck to HTML (committed to repo)
### Render a Marp deck to HTML + PPTX (committed artifacts)
```bash
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
npx --yes @marp-team/marp-cli@latest --allow-local-files \
docs/presentations/<deck-name>-marp.md \
-o docs/presentations/<deck-name>.html
bash scripts/render_slides.sh nova-autonomous-cloud-delivery
```
HTML export inlines images as base64 data URIs. The `--allow-local-files`
flag is needed when the Marp deck references local PNG assets (like the
diagram images in `assets/png/`). The resulting HTML is self-contained.
**The HTML files are committed artifacts** — re-render and re-commit whenever
the Marp source changes.
### Export a Marp deck to PPTX (uploaded to release)
```bash
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
npx --yes @marp-team/marp-cli@latest --allow-local-files \
docs/presentations/<deck-name>-marp.md \
-o <output-path>.pptx
```
`--allow-local-files` is **required** for PPTX so local PNG diagrams are
embedded in the file. PPTX files are not committed to git — upload them as
attachments to the release.
This renders all mermaid PNGs, the HTML, and the PPTX, and stages them for
commit. The `--allow-local-files` flag is required so local PNG diagrams are
embedded. Both HTML and PPTX are committed to the repo; the PPTX is also
attached to the phase's release.
## Adding a new presentation
@@ -306,16 +214,14 @@ attachments to the release.
2. **Extract any mermaid diagrams** into `assets/mmd/<deck-name>-<slide>-<name>.mmd`
and render them to `assets/png/` (command above).
3. **Synthesize the Marp deck** as `<deck-name>-marp.md` with frontmatter,
no speaker notes, embedded PNGs, and maturity badges.
4. **Render to HTML** with `--allow-local-files` and commit the HTML to
`docs/presentations/<deck-name>.html`.
5. **Render to PPTX** with `--allow-local-files` and upload to the release
release (do not commit PPTX to git).
6. **Distill the talking points** as `<deck-name>-talking-points.md` — one
no speaker notes, embedded PNGs, and no badges.
4. **Render to HTML + PPTX** via `scripts/render_slides.sh <deck-name>` and
commit both to `docs/presentations/`.
5. **Distill the talking points** as `<deck-name>-talking-points.md` — one
section per Marp slide, 3-6 talking point bullets + key takeaway, content
distilled from the source markdown (Step 1), indexed by the Marp deck
(Step 2) slide structure.
7. **Verify** the PPTX slide count and that media files are embedded:
6. **Verify** the PPTX slide count and that media files are embedded:
```bash
python3 -c "
import zipfile, re
@@ -330,11 +236,14 @@ attachments to the release.
| Deck | Source of truth (Step 1) | Marp deck (Step 2) | Rendered HTML + PPTX (Step 3) | Talking points (Step 4) | Slides | Audience |
|---|---|---|---|---|---|---|
| Nova — The No-Humans Infrastructure Platform | `nova-no-humans-platform.md` | `nova-no-humans-platform-marp.md` | `nova-no-humans-platform.html` + `.pptx` (committed + release-attached) | `nova-no-humans-platform-talking-points.md` | 19 main + 2 appendix (21) | CTO, Head of Cloud, Head of Infra, Head of DevOps |
| Nova — The Autonomous Cloud Delivery Platform | `nova-autonomous-cloud-delivery.md` | `nova-autonomous-cloud-delivery-marp.md` | `nova-autonomous-cloud-delivery.html` + `.pptx` (committed + release-attached) | `nova-autonomous-cloud-delivery-talking-points.md` | 18 main + 1 appendix (19) | CTO, Head of Cloud, Head of Infra, Head of DevOps |
> **v1.18 (D-130):** the two legacy decks (How the Platform Works + The
> Developer Experience) were consolidated into a single unified narrative
> deck with a 5-act arc (Problem → Vision → How → Proof → Roadmap). v1.18
> (REQ-226) adds 3 slides (17 Scope, 18 RACI, 19 Atelier) → 21 total. The
> S&P Global Energy theme is restored (REQ-214, P1). PPTX is committed to
> git + attached to the release (REQ-228, D-141).
> **v1.21:** the deck was renamed from "No-Humans Infrastructure Platform"
> to "Autonomous Cloud Delivery Platform" (professional framing; conveys
> autonomy without the provocative wording). The narrative restructured to
> a 4-beat arc (Problem → Solution → Proof → Roadmap + Ask). Internal
> provenance (decision IDs, requirement IDs, file paths) removed from
> audience-facing slides. Maturity badges removed. The RACI matrix expanded
> to four roles (Quality Engineering + SRE). The Atelier slide split into
> two. The pipeline hardened: Checkov on static code before the plan;
> Wiz-or-Checkov on the plan (never both).