docs(P00): research findings — v1.24 env-transition detect-and-destroy
---ci--- project: acdl phase: 0 milestone: v1.24 status: research ---/ci---
This commit is contained in:
Jon Chery
+57
-238
@@ -1,264 +1,83 @@
|
||||
---
|
||||
project: acdl
|
||||
milestone: v1.23
|
||||
generated_at: 2026-08-11
|
||||
milestone: v1.24
|
||||
generated_at: 2026-08-12
|
||||
generator: lead-developer
|
||||
verification_toolchain:
|
||||
typecheck: "python3 -m py_compile scripts/inline_images.py scripts/render_pptx.py tests/test_slides_pipeline.py"
|
||||
test: "pytest tests/test_slides_pipeline.py # REQ-263..275"
|
||||
build: "bash scripts/render_slides.sh nova-autonomous-cloud-delivery # HTML + Marp PPTX; then python3 scripts/render_pptx.py # structured PPTX"
|
||||
typecheck: "python3 -m py_compile core/env_transition.py tests/test_env_transition.py tests/test_run_platform_env_transition.py"
|
||||
test: "pytest tests/test_env_transition.py tests/test_run_platform_env_transition.py tests/test_consumer_guide_per_env_section.py tests/test_adapter.py tests/test_contract_resolver.py tests/test_deploy_workflow_env_input.py tests/test_pipeline.py -v"
|
||||
lint: "ruff check core/env_transition.py tests/test_env_transition.py tests/test_run_platform_env_transition.py 2>/dev/null || python3 -m py_compile core/env_transition.py"
|
||||
note: |
|
||||
v1.23 is the Nova Deck Cleanup & Python PPTX — a docs/render/test
|
||||
NFR milestone. Two active personas: lead-developer (deck markdown
|
||||
consolidation + inline Marp style CSS + README + .ciagent metadata),
|
||||
backend-engineer (Python scripts inline_images.py + render_pptx.py
|
||||
via python-pptx + render_slides.sh updates + tests + CI YAML +
|
||||
attach_release_asset.py extension). frontend-engineer stays
|
||||
deactivated (decks are markdown + Marp CSS = lead-developer
|
||||
territory, per v1.17/v1.18/v1.22 precedent). No data-engineer (no
|
||||
schema/DB changes). No new personas (the work splits cleanly into
|
||||
narrative+CSS+docs and Python+bash+tests+CI).
|
||||
v1.24 is the Consumer Guide Accuracy & Env-Promotion Lifecycle
|
||||
Enforcement milestone — a mixed docs+feat+test milestone. Two active
|
||||
personas: lead-developer (consumer-guide.md edits + guide test
|
||||
updates), backend-engineer (core/env_transition.py + run_platform.sh
|
||||
Step 0b + deploy.yml + adapter doc comment + env_transition tests +
|
||||
pipeline tests). frontend-engineer stays deactivated (no UI). No
|
||||
data-engineer (no schema changes — the nova-contracts table already
|
||||
exists). No new personas.
|
||||
---
|
||||
|
||||
# ACDL — Persona Roster (v1.23 Nova Deck Cleanup & Python PPTX)
|
||||
# ACDL — Persona Roster (v1.24 Consumer Guide Accuracy & Env-Promotion Lifecycle Enforcement)
|
||||
|
||||
> v1.23 roster. Two active personas + two deactivated. This is a
|
||||
> docs/render/test NFR milestone: the work is deck markdown
|
||||
> consolidation, Marp inline `style:` CSS (reverting from the standalone
|
||||
> `nova-sp-theme.css` to `theme: default` + inline block), two Python
|
||||
> render scripts (`inline_images.py` stdlib image inlining +
|
||||
> `render_pptx.py` structured PPTX via python-pptx), test updates, CI
|
||||
> YAML, README rewrite, and the `attach_release_asset.py` extension to
|
||||
> dual-PPTX. frontend-engineer stays deactivated (Marp CSS is a static
|
||||
> stylesheet, not a React/Next.js component system — D-148 precedent).
|
||||
> No data-engineer (no schema/DB/ORM changes).
|
||||
> v1.24 roster. Two active personas + two deactivated. This is a mixed
|
||||
> docs+feat+test milestone: the work is consumer-guide accuracy fixes
|
||||
> (lead-developer), a new env-transition detect-and-destroy platform
|
||||
> feature (backend-engineer), and test coverage for both (split).
|
||||
|
||||
## Active personas
|
||||
|
||||
### lead-developer
|
||||
- **Domain:** coordination + deck content + inline CSS
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** [] (no framework — owns process + narrative + Marp inline CSS + markdown + README)
|
||||
- **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", "port the reference deck's exact inline style CSS (the clean look)"]
|
||||
- **Domain:** coordination + docs
|
||||
- **Frameworks:** []
|
||||
- **Constraints:** ["pragmatic", "battle-tested defaults", "docs match code"]
|
||||
- **Territory:**
|
||||
- `docs/presentations/nova-autonomous-cloud-delivery-marp.md` (REQ-263..275 — deck consolidation: merge plain .md into -marp.md, trim word count, remove "penetrate")
|
||||
- `docs/presentations/nova-autonomous-cloud-delivery.md` (DELETE — consolidated into -marp.md)
|
||||
- `docs/presentations/nova-autonomous-cloud-delivery-talking-points.md` (sync to final slide structure)
|
||||
- `docs/presentations/README.md` (rewrite 4-step → 3-step process for single-document + dual-PPTX pipeline)
|
||||
- `docs/presentations/assets/nova-sp-theme.css` (RETIRE from render; keep as reference file)
|
||||
- `.ciagent/**` (PROJECT, ROADMAP, REQUIREMENTS, RESEARCH, PLAN, GRILL, PERSONAS, REVIEW, CHECKPOINT)
|
||||
- **Reason:** Owns the deck markdown consolidation (plain `.md` +
|
||||
`-marp.md` → single `-marp.md` with speaker notes as HTML comments),
|
||||
the inline `style:` CSS block (porting the reference deck's exact
|
||||
CSS — the "clean look"), the word-count trim, the "penetrate"
|
||||
removal, the talking-points sync, the README rewrite, and all
|
||||
CIAgent metadata. Is the only persona that touches `.ciagent/**` and
|
||||
the deck markdown/CSS. The inline `style:` block is a Marp
|
||||
frontmatter stylesheet, not a frontend component system (D-148
|
||||
precedent from v1.22).
|
||||
- **Phase-specific flag:** none (active for all of P0–P-final).
|
||||
- `docs/consumer-guide.md`
|
||||
- `tests/test_consumer_guide_per_env_section.py`
|
||||
- `.ciagent/*.md` (PLAN.md, RESEARCH.md, etc.)
|
||||
- **Reason:** Owns the consumer guide narrative — the 5 accuracy fixes
|
||||
(stale fields table, inconsistent caller, "dev only" phrasing, Step 8
|
||||
rewrite with destroy semantics, reference table wording) and the
|
||||
consumer-guide test updates (rename + new destroy-on-env-change test).
|
||||
No UI work (frontend-engineer deactivated). No Python/bash platform
|
||||
code (backend-engineer territory).
|
||||
|
||||
### backend-engineer
|
||||
- **Domain:** Python render scripts + bash + tests + CI
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** ["python-pptx", "bash", "pytest", "marp-cli", "mermaid-cli", "base64/re/mimetypes (stdlib)"]
|
||||
- **Constraints:** ["pin CLI versions (no @latest in workflows-src/slides.yml — currently unpinned, must fix)", "python-pptx>=0.6.23 minimum", "stdlib-only for inline_images.py (no external image lib)", "tests must catch the theme-default + inline-style regression (the gap that let v1.22's standalone-theme drift through)", "no raw curl with shell-env tokens"]
|
||||
- **Domain:** backend (Python + bash + YAML)
|
||||
- **Frameworks:** ["boto3", "terraform"]
|
||||
- **Constraints:** ["api-first", "fail-closed", "no orphan paths", "state-key determinism"]
|
||||
- **Territory:**
|
||||
- `scripts/inline_images.py` (NEW — stdlib base64 image inlining into rendered HTML)
|
||||
- `scripts/render_pptx.py` (NEW — structured editable PPTX via python-pptx)
|
||||
- `scripts/render_slides.sh` (update: drop --theme nova-sp-theme.css; add inline_images.py + render_pptx.py invocations)
|
||||
- `scripts/attach_release_asset.py` (extend to accept multiple file paths: both .pptx + -python.pptx)
|
||||
- `tests/test_slides_pipeline.py` (REQ-262 successor — invert theme tests, retarget CSS tests to inline style block, delete source-md tests, update slide count)
|
||||
- `workflows-src/slides.yml` (add python-pptx install step; pin @latest → @4.5.0/@11.16.0; add -python.pptx to commit list)
|
||||
- `pyproject.toml` (add python-pptx>=0.6.23 to [project.optional-dependencies] test)
|
||||
- **Reason:** Owns the Python render scripts (`inline_images.py` is
|
||||
stdlib regex + base64; `render_pptx.py` is python-pptx — a backend
|
||||
Python library, not a frontend framework). The render_slides.sh
|
||||
updates (drop `--theme`, add the two Python script invocations) and
|
||||
the CI YAML (add python-pptx install, pin versions, add
|
||||
-python.pptx to commit list) are backend/scripting tasks. The test
|
||||
suite updates (invert the theme-default test, retarget CSS tests to
|
||||
the inline `style:` block, delete the source-md tests) are the gap
|
||||
that let v1.22's standalone-theme drift through — backend-engineer
|
||||
owns closing it. python-pptx is new to v1.23; backend-engineer's
|
||||
frameworks list gains it.
|
||||
- **Phase-specific flag:** none (active for P2 scripts, P5 tests; light
|
||||
touch on P0/P-final).
|
||||
- `core/env_transition.py` (NEW)
|
||||
- `scripts/run_platform.sh` (Step 0b insert + record-applied-env)
|
||||
- `.github/workflows/deploy.yml` (NOVA_CONSUMER_REPO env)
|
||||
- `adapters/terraform/adapter.py` (doc comment only)
|
||||
- `tests/test_env_transition.py` (NEW)
|
||||
- `tests/test_run_platform_env_transition.py` (NEW)
|
||||
- **Reason:** Owns the env-transition detect-and-destroy feature: the new
|
||||
`core/env_transition.py` module (DynamoDB query + record), the
|
||||
`run_platform.sh` Step 0b orchestrator (re-resolve + terraform destroy +
|
||||
evidence event + fail-closed), the deploy.yml env var passthrough, and
|
||||
the two new test files. Uses boto3 (DynamoDB) + terraform (destroy) +
|
||||
bash (pipeline orchestration).
|
||||
|
||||
## 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.23)
|
||||
- **Reason:** v1.23 has no frontend; decks are markdown + Marp inline
|
||||
CSS (lead-developer territory); deactivated per PERSONAS.md
|
||||
v1.17/v1.18/v1.22 precedent. The inline `style:` block is a Marp
|
||||
frontmatter stylesheet (CSS rules in the markdown frontmatter), not
|
||||
a React/Next.js component system — it stays lead-developer
|
||||
territory. No reactivation trigger.
|
||||
- **Reason:** No UI work in v1.24. The consumer guide is markdown docs
|
||||
(lead-developer territory). Deactivated per v1.17/v1.18/v1.22/v1.23
|
||||
precedent.
|
||||
|
||||
### data-engineer
|
||||
- **Active:** false
|
||||
- **Domain:** data
|
||||
- **Frameworks:** [] (inert)
|
||||
- **Constraints:** [] (inert)
|
||||
- **Territory:** [] (no territory in v1.23)
|
||||
- **Reason:** v1.23 has no schema/DB/ORM changes. The milestone is
|
||||
docs + Python scripts + bash + tests + CI only. No reactivation
|
||||
trigger.
|
||||
- **Reason:** No schema changes in v1.24. The `nova-contracts` DynamoDB
|
||||
table already exists with the right shape (PK `consumerRepo`, SK
|
||||
`contractId#submittedAt`). The env-transition module only adds a new
|
||||
`#LAST_APPLIED` SK suffix — no schema migration, no ORM, no new tables.
|
||||
The backend-engineer handles the boto3 queries.
|
||||
|
||||
## Roster decisions
|
||||
## Phase-specific notes
|
||||
|
||||
### D-163 (0.95): Inline Marp `style:` block is lead-developer territory, not frontend-engineer
|
||||
The inline `style:` block in the Marp frontmatter is a static CSS
|
||||
stylesheet (a block of CSS rules in the markdown frontmatter, applied
|
||||
by Marp to the rendered slides), not a React/Next.js component system.
|
||||
The v1.17/v1.18/v1.22 precedent (decks are markdown = lead-developer
|
||||
territory; the theme CSS is a Marp stylesheet, not a frontend framework
|
||||
— D-148) extends to the inline `style:` block. frontend-engineer's
|
||||
frameworks (react, next.js) are irrelevant to Marp frontmatter CSS.
|
||||
**Decision:** inline `style:` block stays lead-developer territory.
|
||||
Confidence 0.95 — the only counter-argument is that CSS is "frontend,"
|
||||
but Marp frontmatter CSS is a static stylesheet authored in the
|
||||
markdown source, not a component system.
|
||||
|
||||
### D-164 (0.90): No new personas for v1.23
|
||||
The work is markdown + inline CSS + Python scripts + bash + tests + CI
|
||||
YAML + README. All of this is within the two active personas' range
|
||||
(lead-developer: markdown + CSS + README + metadata; backend-engineer:
|
||||
Python + bash + tests + CI). Creating a separate "slides-engineer" or
|
||||
"pptx-engineer" persona would fragment ownership of the deck markdown
|
||||
(lead) and the render scripts (backend). The python-pptx work is
|
||||
unambiguously backend (a Python library + script), even though the
|
||||
slide layout decisions within `render_pptx.py` are co-owned with lead-
|
||||
developer. **Decision:** no new personas. Confidence 0.90 — follows
|
||||
v1.22 D-149 precedent.
|
||||
|
||||
### Territory-overlap resolution (co-ownership)
|
||||
|
||||
| Path | Primary | Co-owner | Why |
|
||||
|------|---------|----------|-----|
|
||||
| `scripts/render_pptx.py` | backend-engineer (Python code + python-pptx API) | lead-developer (slide layout decisions: which image where, font sizes, bullet structure) | The script is backend (Python); the slide-by-slide layout decisions within it are design decisions that reflect lead-developer's deck ownership. `warn` enforcement — cross-territory edits logged, not blocked. |
|
||||
| `scripts/render_slides.sh` | backend-engineer (bash script) | lead-developer (the inline `style:` block content it renders) | The script is backend; the CSS it renders is lead-developer's. |
|
||||
| `tests/test_slides_pipeline.py` | backend-engineer (test code) | lead-developer (assertions reflect deck structure + inline CSS) | The test code is backend; the assertions (slide count, inline style rules, theme-default) reflect lead-developer's deck/CSS decisions. |
|
||||
| `docs/presentations/README.md` | lead-developer (process narrative) | backend-engineer (build commands + render script invocations) | The process narrative is lead; the build commands + script names are backend. |
|
||||
|
||||
## Domain priority (v1.23)
|
||||
|
||||
`lead-developer → backend-engineer`
|
||||
|
||||
Rationale: the deck markdown consolidation + inline CSS (lead) is the
|
||||
binding constraint — the render scripts (backend) can't be finalized
|
||||
until the deck structure is stable (slide count, inline style). The
|
||||
inline `style:` block must be ported + verified before the render
|
||||
pipeline (HTML + PPTX) is re-run. Backend (scripts + tests + CI)
|
||||
follows once the deck + CSS are settled. The dual-PPTX pipeline is
|
||||
wired last, once the deck renders clean with the inline style.
|
||||
|
||||
---
|
||||
|
||||
## Historical rosters
|
||||
|
||||
<details>
|
||||
<summary>v1.22 roster (Nova Deck Layout Fix) — superseded by v1.23</summary>
|
||||
|
||||
### Active personas (v1.22)
|
||||
|
||||
### 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).
|
||||
|
||||
### D-148 (v1.22): Theme CSS is lead-developer territory, not frontend-engineer
|
||||
### D-149 (v1.22): No new personas for v1.22
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>v1.18 roster (Citizen Developer & Production-Grade Guidance) — superseded</summary>
|
||||
|
||||
### Active personas (v1.18)
|
||||
|
||||
### lead-developer
|
||||
- **Domain:** coordination
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** [] (no framework — owns process + narrative, not code)
|
||||
- **Constraints:** ["pragmatic", "battle-tested defaults", "no fabrication (NORTH_STAR honesty model)"]
|
||||
- **Territory:**
|
||||
- `docs/presentations/**` (Step 1/2/4 markdown + the deck automation trigger)
|
||||
- `.ciagent/**` (PROJECT, ROADMAP, REQUIREMENTS, RESEARCH, PLAN, GRILL, PERSONAS, REVIEW, CHECKPOINT)
|
||||
- `PROJECT.md` (RACI matrix + PDLC-scope statement, REQ-215/216)
|
||||
- `ROADMAP.md`
|
||||
- `REQUIREMENTS.md`
|
||||
- `docs/raci.md` (REQ-215)
|
||||
- `docs/scope.md` (REQ-216)
|
||||
- `docs/skills.md` (REQ-222 — the index page, not the skill files themselves)
|
||||
- `docs/submission-readiness.md` (REQ-219 — citizen-developer-facing copy; co-owned with backend-engineer for the reason-code catalog)
|
||||
|
||||
### backend-engineer
|
||||
- **Domain:** backend
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** ["mcp (Python SDK v2)", "pydantic", "jsonschema", "urllib"]
|
||||
- **Territory:**
|
||||
- `mcp/atelier/server.py` (REQ-223)
|
||||
- `mcp/atelier/plugins/**/*.py` (REQ-223 — principles.py, validation.py)
|
||||
- `mcp/atelier/vendor/**` (REQ-224 — vendored Atelier snapshot)
|
||||
- `mcp/atelier/VERSION.md` + `mcp/atelier/README.md` (REQ-224)
|
||||
- `scripts/update_atelier_vendor.sh` (REQ-224)
|
||||
- `core/submission_readiness.py` (REQ-218)
|
||||
- `scripts/render_deck.sh` (REQ-228)
|
||||
- `scripts/attach_release_asset.py` (REQ-228)
|
||||
- `tests/test_atelier_mcp.py` (REQ-225)
|
||||
- `tests/test_submission_readiness.py` (REQ-220)
|
||||
|
||||
### data-engineer
|
||||
- **Domain:** data
|
||||
- **Active:** true
|
||||
- **Frameworks:** ["jsonschema", "dynamodb (item shape)"]
|
||||
- **Territory:**
|
||||
- `schemas/**` (REQ-217)
|
||||
- `core/lambda/contract_ingestor.py` (co-owned with backend-engineer)
|
||||
|
||||
### D-143 (v1.18): Fold mcp-engineer into backend-engineer
|
||||
|
||||
</details>
|
||||
- No phase-specific personas. Both active personas span P1-P3.
|
||||
- P4 (final review + audit + ship) is lead-developer territory
|
||||
(orchestration + docs completion).
|
||||
Reference in New Issue
Block a user