continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 128 Wiki Activity
Files
v
acdl/.ciagent/RESEARCH.md
T
CIAgent 18b403fcd8 docs(P00): research findings + persona assessment 
---ci---
project: acdl
phase: 0
milestone: v1.30
status: research
---/ci---
2026-08-20 13:16:33 +00:00

13 KiB
Raw Permalink Blame History

RESEARCH — v1.30 Single-shot Leadership Deck

Autonomy: full. Research findings load-bearing for v1.30 PLAN. The research scope is narrow: this is a single-shot presentation artifact, not a runtime feature. The research covers (1) the existing render pipeline's behavior + limits, (2) the smoke-test script conventions, (3) the Marp frontmatter/footer/speaker-notes handling, (4) the theme-token enforcement strategy, (5) the python-pptx install path in this environment, (6) the vision document grounding for [1] citations.

R1 — Existing render pipeline (scripts/render_pptx.py)

Source: scripts/render_pptx.py (688 lines, REQ-269 v1.23).

Behavior:

  • Argv: render_pptx.py [deck-name] → reads docs/presentations/{deck}-marp.md, writes docs/presentations/{deck}-python.pptx (lines 677-680). Does not accept a full path or non--marp.md filename.
  • Frontmatter: stripped (lines 62-67) — the Marp footer:, paginate:, theme:, size:, style: directives are NOT read by the python-pptx path. They are source-only (smoke test checks source; the Marp CLI path in render_slides.sh reads them, but that path needs Chromium which is unavailable here).
  • Slide splitting: re.split(r"\n---\s*\n", ...) after frontmatter strip (line 69). Exactly 7 ----delimited slides required.
  • Body parsing (parse_slide, lines 360-498):
    • HTML comments (<!-- ... -->) are skipped entirely (lines 366-379). Speaker notes are NOT embedded in the PPTX. Acceptable for REQ-372.4 (smoke test checks source word counts, not PPTX-embedded notes).
    • Headings #/## → title (first) or lead (subsequent).
    • Bold lead **...** (own line, exactly 2 **) → lead block (red, bold).
    • Blockquotes > → quote block (grey, italic).
    • Unordered list [-*+]\s+... → bullet (level by indent). *italic* (no space after *) does NOT match — safe as plain text.
    • Ordered list \d+\.\s+... → ordered.
    • Tables | ... | + separator → table.
    • →-prefixed lines → plain text (not bullets). Content preserved.
    • _strip_inline_emphasis (lines 209-220): **bold**, *italic*, `code` markers are collapsed to plain text in the PPTX. Content is preserved; emphasis styling is lost (acceptable — the PPTX is an editable comparison artifact; REQ-372.7 content match is by visual review).
  • Theme: hardcoded S&P constants (lines 37-43): RED=#D6002A, BLACK=#1B1B1B, WHITE=#FFFFFF, GREY_HEADER=#F0F0F0, GREY_TEXT=#2E2E2E, BODY_TEXT=#1B1B1B. Note: GREY_TEXT=#2E2E2E is a 5th color used internally for blockquote/body text. This is a renderer-internal color, NOT a source hex color — REQ-372.6 scopes to "color values extracted from the source markdown (Marp directives + inline overrides)", so #2E2E2E in the renderer does not violate REQ-372.6. The smoke test checks the source file for hex colors.
  • Footer: NOT rendered. No footer textbox is added by the existing renderer. D-242 extension required to add a right-aligned footer textbox on every slide.
  • Title slide: render_title_slide (line 501) — black bg, red top bar, white title. Triggered when idx==0 + (title_is_h1 or is_title_class). The leadership deck's slide 1 uses a bold lead (**The friction...**) as the first line — this is an H1 (# The friction...) in the source, so slide 1 renders as a title slide (black bg). Decision for PLAN: author slide 1 with # H1 title (title slide, black bg, red bar — strong opener) OR author as ## H2 (content slide, white bg). The Slide Content Map shows slide 1 with a bold title + italic subtitle + arrows + italic closing — a content-rich slide. Recommend: ## H2 title for all 7 slides → all render as content slides (white bg, red title bar) for visual consistency. Slide 1 as a black-bg title slide would hide the → arrows in white-on-black, which is fine but differs from the map's framing. The map doesn't specify background; visual review accepts either. Final call in PLAN: all ## content slides for consistency + readability of the 3-pattern frame.

Gaps for v1.30 (D-242 extension):

  1. Accept explicit source .md path + --output filename.
  2. Add right-aligned footer textbox on every slide with exact string Nova Platform - Infrastructure & Operations.

R2 — Smoke-test script conventions

Source: scripts/check_north_star_diff.sh (REQ-204), other scripts/check_*.sh / scripts/run_*.sh.

Conventions:

  • Shebang #!/usr/bin/env bash
  • Header comment with purpose + Usage + Returns
  • set -euo pipefail
  • Exit 0 on pass, non-zero (1) on fail
  • echo "WARN: ..." / echo "ERROR: ..." to stderr
  • Runnable from repo root: bash scripts/check_*.sh

v1.30 smoke test (scripts/check_leadership_deck.sh) assertions (REQ-372.8 a–f):

  • (a) docs/presentations/nova-leadership-deck-marp.md exists
  • (b) slide count = 7 (count --- separators on own line, excluding frontmatter)
  • (c) per-slide speaker-note word counts in band (extract HTML comments per slide; slides 1/2/4/6: 150–300; 3/5: 250–400; 7: 200–300)
  • (d) footer string Nova Platform - Infrastructure & Operations present in source (frontmatter footer: directive)
  • (e) only S&P hex colors #D6002A, #1B1B1B, #FFFFFF, #F0F0F0 in source (grep for #[0-9A-Fa-f]{6} and diff against the allow- list)
  • (f) docs/presentations/nova-leadership-deck.pptx exists (hard fail per Q-M4)

Implementation approach: pure bash + grep/awk/wc. No python dependency for the smoke test (keeps it runnable on demand without the python-pptx install). Slide count: count lines matching ^---\s*$ after the frontmatter, +1. Speaker notes: per slide, extract content between <!-- and -->, strip HTML comment markers, wc -w. Color scan: grep -oiE '#[0-9A-Fa-f]{6}' on the source, sort -u, compare to allow-list.

R3 — Marp frontmatter / footer / speaker-notes handling

Source: docs/presentations/nova-autonomous-cloud-delivery-marp.md (lines 1-27), Marp CLI v4.5.0 (available via npx).

Existing deck frontmatter:

marp: true
theme: default
paginate: true
size: 16x9
footer: 'Nova — The Autonomous Cloud Delivery Platform'
style: |
  section { ... color: #1B1B1B; ... }
  h1 { color: #D6002A; ... }
  ...

v1.30 leadership deck frontmatter (per cover note + spec):

marp: true
theme: default
footer: "Nova Platform - Infrastructure & Operations"
paginate: false
size: 16x9
style: |
  section { font-family: "Akkurat Pro", "Helvetica Neue", "Arial", sans-serif; font-size: 22px; color: #1B1B1B; padding: 48px 56px 40px; overflow: auto; }
  h1 { color: #D6002A; font-size: 34px; margin-bottom: 0.3em; }
  h2 { color: #D6002A; font-size: 26px; margin-bottom: 0.2em; }
  blockquote { border-left: 4px solid #D6002A; color: #1B1B1B; font-size: 20px; padding-left: 12px; }
  strong { color: #D6002A; }
  ...

Key differences from the existing deck:

  • paginate: false (existing: true) — per cover note.
  • footer: "Nova Platform - Infrastructure & Operations" (existing: different string) — per cover note + REQ-372.5.
  • The style: block uses only the 4 S&P tokens. The existing deck's style: uses #2E2E2E for blockquote color — this must be changed to #1B1B1B in the leadership deck's style: block to satisfy REQ-372.6 (only 4 hex colors in source). The renderer's internal GREY_TEXT=#2E2E2E is not in the source, so it doesn't violate REQ-372.6 — but the source style: block must not contain #2E2E2E.

Speaker notes: HTML comments <!-- ... --> within the slide body, before the next ---. The Marp CLI renders these as speaker notes in the HTML/PPTX; the python-pptx path skips them. The smoke test extracts them from the source for word-count checking.

R4 — Theme-token enforcement strategy

REQ-372.6: only #D6002A, #1B1B1B, #FFFFFF, #F0F0F0 as hex colors in the source.

Enforcement:

  1. Source style: block: use only the 4 tokens. Replace the existing deck's #2E2E2E (blockquote color) with #1B1B1B.
  2. No inline color: overrides in slide bodies — the slides use no inline HTML/color spans.
  3. Smoke test (8e): grep -oiE '#[0-9A-Fa-f]{6}' on the source, sort -u, compare to the 4-token allow-list. Any other hex color → fail.

R5 — python-pptx install path (this environment)

Environment: Debian/Ubuntu, Python 3.11.2, no system pip, no root, no python3-venv/python3-pip packages, no ensurepip.

Resolved install path:

  1. curl -sS https://bootstrap.pypa.io/get-pip.py -o /home/opencode/tmp/get-pip.py
  2. python3 get-pip.py --user --break-system-packages
  3. /home/opencode/.local/bin/pip install --user --break-system-packages "python-pptx>=0.6.23"
  4. pip install --user --break-system-packages "pytest>=8.0" (for verify stage)

Result: python-pptx 1.0.2 + pytest 9.1.1 installed to user-site. python3 -c "import pptx" succeeds. No Chromium needed (python-pptx is the render path, not Marp CLI PPTX).

Confirmed in RESEARCH execution: all commands ran successfully in this session.

R6 — Vision document grounding for [1] citations

Source: docs/vision.md (the spec's acdl-vision.md / [1] reference).

Key tenets for slide grounding:

  • §1 The Friction (slide 1): "Software delivery scales with the coordination surface around it, not the engineering inside it." Grounds the three-pattern problem frame + binding-constraint claim.
  • §3 Core Tenets (slides 3, 5, 7):
    • "The Delivery Lifecycle is a Sovereign Boundary" — grounds slide 3's Sovereign boundary tenet + slide 5's boundary discipline + slide 7's "Nova stays in its lane."
    • "Lower Environments are Autonomous; Higher Environments are Attested" — grounds slide 3's Lower autonomous · higher attested tenet + slide 4's HITL discipline.
    • "Infrastructure is Consumed, Not Maintained" — grounds slide 5's "VM, bare-metal, OS lifecycles" exclusion.
  • §4 Domain Boundaries (slides 2, 5, 6): "The platform begins where the artifact is compiled and ends where it runs in production." "Out of scope: Application business logic, IDE workflows, product backlog management, sprint planning, compute requiring node-level or OS-level management." Grounds slide 5's in-lane/out-of-lane split + slide 6's "Nova absorbs no IDE, no editor, no sprint tool, no agent harness."

Citation convention: [1] in speaker notes, resolving to docs/vision.md. The spec §citation-references confirms [1] → acdl-vision.md (vision document, source [1]).

R7 — CAP-024 regression policy (collision check)

Source: adapters/kyverno-json/policies/regression/cap-024-deck-structure.json

  • tests/test_regression_policies.py.

Finding: CAP-024 validates the citizen-developer deck's 4-beat arc (Problem/Solution/Proof/Roadmap+Ask) against fixture files (clean.json/drifted.json in tests/fixtures/), NOT against the actual deck markdown files. The leadership deck (nova-leadership-deck-marp.md) does NOT pass through this policy. No collision risk. The leadership deck's 7-slide structure is a different artifact (CAP-042, not CAP-024).

R8 — slides.yml CI (non-interference check)

Source: workflows-src/slides.yml.

Finding: The CI workflow triggers on docs/presentations/** path changes, but scripts/render_slides.sh defaults to DECK="nova-autonomous-cloud-delivery" and only renders that one deck. Adding nova-leadership-deck-marp.md to docs/presentations/ will trigger the CI, but it will only re- render the citizen-developer deck (no-op if that deck is unchanged). The leadership deck is NOT rendered by CI (per spec: no CI gate, no publish.yml integration). No interference. The bot commit from CI (if any) will be a no-op re-render of the unchanged citizen- developer deck.

Persona assessment (lead-developer)

Active personas for v1.30:

  • lead-developer (coordination) — owns STATE.md CAP-042, PROJECT.md D-241, milestone coordination. Territory: .ciagent/STATE.md, .ciagent/PROJECT.md.
  • backend-engineer (backend) — owns scripts/render_pptx.py extension + PPTX render + python-pptx install. Territory: scripts/render_pptx.py, docs/presentations/nova-leadership-deck.pptx. Framework override: python-pptx (not fastify/hono — the default frameworks don't match this project's Python stack).
  • ci-doc-writer (custom, phase-specific) — owns the Marp markdown deck source. Territory: docs/presentations/nova-leadership-deck-marp.md. Created for this phase (presentation authoring); removed after P1.
  • ci-cli-engineer (custom) — owns the smoke-test script. Territory: scripts/check_leadership_deck.sh.

Deactivated personas:

  • frontend-engineer — already active: false in config (no UI). Confirmed.
  • data-engineer — no schema/migration work in this milestone. Deactivate for v1.30.

Territory enforcement: warn (per config).

Reference in New Issue View Git Blame Copy Permalink