From d048460abf9ebbfbfd73604793329fbad2099a98 Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Thu, 6 Aug 2026 14:54:22 +0000 Subject: [PATCH] =?UTF-8?q?docs(init):=20validate=20specification=20?= =?UTF-8?q?=E2=80=94=20v1.18=20Citizen=20Developer=20&=20Production-Grade?= =?UTF-8?q?=20Guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Establish v1.18 active milestone (was v1.17 complete). Author 15 new requirements (REQ-214..228) across 5 user-directed inputs: S&P Global theme restoration, PDLC-upstream scope, RACI matrix, Nova input contract (submission-readiness schema + validator), Atelier integration (skills + MCP server). Add v1.18 objective to PROJECT.md + ROADMAP.md. Feature milestone; tags run on v1.17.x patch line. ---ci--- project: acdl phase: 0 milestone: v1.18 status: specify ---/ci--- --- .ciagent/PROJECT.md | 84 +++++++++++++++++++ .ciagent/REQUIREMENTS.md | 174 +++++++++++++++++++++++++++++++++++++++ .ciagent/ROADMAP.md | 59 +++++++++++++ .ciagent/config.json | 2 +- 4 files changed, 318 insertions(+), 1 deletion(-) diff --git a/.ciagent/PROJECT.md b/.ciagent/PROJECT.md index 2ffa95a..015417d 100644 --- a/.ciagent/PROJECT.md +++ b/.ciagent/PROJECT.md @@ -598,6 +598,90 @@ utility, unrelated to presentations). No code changes; 494 tests pass; `run_ci.sh` + `run_platform.sh --check-only` green. PPTX files uploaded to Gitea release. +## Objective for Milestone v1.18 (active — Citizen Developer & Production-Grade Guidance) + +v1.18 advances Nova from a platform that governs infrastructure delivery +to one that **instructs the citizen developer on production-grade +engineering** and defines a **clear, machine-checkable contract for what +is acceptable to start**. Five user-directed inputs drive the milestone: + +1. **S&P Global theme restoration.** The v1.17 P5 deck rebuild consolidated + two decks into one unified narrative deck but lost the S&P Global Energy + brand visual identity (introduced v1.9.2 / P45, commit `ae0cb58`). The + Marp `style:` block (red-core `#D6002A`, grey-90 `#1B1B1B`, Akkurat Pro + font, 8px top accent bar) is restored to the unified deck. The mermaid + `sp-theme.json` survived; only the Marp CSS theme was lost. + +2. **PDLC-upstream scope made explicit.** Core Tenet #2 already states the + platform "does not penetrate upstream product/SDLC" and Anti-Goal #1 says + "Not an upstream development platform." v1.18 promotes this from a + buried tenet to a dedicated, unmissable scope statement in PROJECT.md + + `docs/scope.md` + a deck slide: **the PDLC (Product Development + Lifecycle — product backlog, code authorship, IDE) is upstream of Nova; + Nova governs infra + delivery only; integration is through the validated + contract boundary.** + +3. **RACI matrix.** A three-role responsibility matrix clarifies who owns + what: **Citizen Developer** (Responsible for all Functional Requirements + + User Acceptance Testing, via their AI coding agent / upstream agentic + SDLC / upstream development platform — the source does not matter as all + are subject to the same compliance standards), **Platform** (Responsible + for all NFRs + Infrastructure + QA + Production deployments to cloud), + **Release Management** (co-owned: QA + SRE attestations required by the + actual release, performed agentically but overseen & triggered by the + Citizen Developer). Source of truth in PROJECT.md + `docs/raci.md` + a + deck slide. + +4. **Nova input contract — "what is acceptable to start."** A JSON Schema + (`schemas/submission-readiness.schema.json`) defines the + acceptable-to-start gate as a superset *above* contract-schema validity: + schema-valid contract + required Nova tags + per-env mandatory metadata + (per W3.E) + declared policy preconditions + (for L3B) `profile:agentic` + markers + `appSource` pointer. A validator (`core/submission_readiness.py`, + invoked as `contract_ingestor.py --check-readiness`) returns a structured + `ReadinessResult` with reason codes. On fail → citizen-developer-facing + error (not a stack trace); on pass → proceeds to existing ingestion. + +5. **Atelier integration — production-grade guidance + agentic validation.** + Nova consumes `coreci/atelier` (a first-principles docs-as-code + engineering framework — 8 core principles, 19 domains, 190 P-rules) via + two surfaces: **skills** (markdown files under `skills/` keyed to Atelier + domain paths, surfaced to the citizen developer's AI agent, extending the + BA.A 5-skill catalog) and an **MCP server** (`mcp/atelier/server.py`, + plugin-registry architecture, stdio transport, vendored Atelier snapshot + for audit reproducibility) exposing tools for principle-lookup, + domain-listing, matrix-lookup, and agentic validation against the + Atelier agent-checklist — validation that goes beyond deterministic + scanners (Wiz/Checkmarx/Mend) by catching correctness/clarity/simplicity/ + observability gaps. + +**Deck automation (cross-cutting):** any phase modifying +`docs/presentations/*-marp.md` or `docs/presentations/assets/` MUST +re-render HTML + PPTX, **commit the PPTX to git** (binary, no LFS), and +attach it to the phase's Gitea release. New scripts: +`scripts/render_deck.sh` (HTML + PPTX render) and +`scripts/attach_release_asset.py` (Gitea release asset upload). + +**Milestone type:** Feature (P1 S&P theme restoration + P3 readiness +schema/validator + P5 MCP server are new code/features). Tags run on the +**v1.17.x** patch line (previous minor per branch-strategy): `v1.17.0` (P0) +→ `v1.17.1..v1.17.6` (P1–P6) → `v1.17.7` (P7 final = milestone release). + +**Phase count:** 8 (P0 pre-execution + 6 execution + 1 final). + +**Hard constraints:** +- DO NOT make anything up (NORTH_STAR.md honesty model). +- The submission-readiness schema is a superset gate above + `contract.schema.json`, NOT a duplicate — it references but does not + redefine contract fields. +- The MCP server is plugin-registry extensible (future capabilities drop + in as new plugin files, no `server.py` edits). +- Atelier is vendored (pinned tag) for audit reproducibility — an agentic + validation result must be replayable against the exact principles that + produced it. +- PPTX is a first-class artifact: committed (history) + attached (download) + — both always, not optional. + ## Requirements ### v1.0 (Prior milestone — the demo) diff --git a/.ciagent/REQUIREMENTS.md b/.ciagent/REQUIREMENTS.md index 41052c9..a1bc882 100644 --- a/.ciagent/REQUIREMENTS.md +++ b/.ciagent/REQUIREMENTS.md @@ -1180,3 +1180,177 @@ with documented schemas. - A third deck — the two existing decks merge into one; no new standalone metrics deck. - A Nova web UI — dashboards are PowerBI, not a Nova-built frontend. + +--- + +## v1.18 — Citizen Developer & Production-Grade Guidance + +> **Milestone type:** Feature. Tags run on the v1.17.x patch line (previous +> minor per branch-strategy). `v1.17.0` (P0) → `v1.17.1..v1.17.6` (P1–P6) → +> `v1.17.7` (P7 final = milestone release). +> **Active milestone:** v1.18. **Branch:** +> `milestone/v1.18-citizen-developer-guidance`. + +### Requirements + +- **REQ-214** — S&P Global Energy Marp theme restored in the unified deck + (`docs/presentations/nova-no-humans-platform-marp.md`). The `style:` block + from commit `ae0cb58` (v1.9.2 / P45) is ported: H1/H2 `#D6002A` + (S&P red-core), title-slide bg `#1B1B1B` (grey-90) with 8px `#D6002A` top + accent bar, body text `#1B1B1B`, blockquote border `#D6002A`, + table headers `#F0F0F0`, font `'Akkurat Pro'` with web-safe fallbacks. The + current Nova header/footer text is preserved (rebrand is not touched — + only the visual theme is restored). HTML re-rendered with the S&P theme. + +- **REQ-215** — RACI matrix authored in `PROJECT.md` (new `## RACI Matrix` + section) and `docs/raci.md` (citizen-developer-facing copy). Three roles: + **Citizen Developer** (Responsible for all Functional Requirements + User + Acceptance Testing — via their AI coding agent / upstream agentic SDLC / + upstream development platform; the source does not matter as all are + subject to the same compliance standards), **Platform** (Responsible for + all NFRs + Infrastructure + QA + Production deployments to cloud), + **Release Management** (co-owned: QA + SRE attestations required by the + actual release, performed agentically but overseen & triggered by the + Citizen Developer). Rendered as a table: rows = work categories (FRs, UAT, + NFRs, Infra, QA, Prod deploy, Release attestation), columns = R/A/C/I per + role. Includes the compliance-standard-equivalence note. + +- **REQ-216** — PDLC-upstream scope statement made explicit in `PROJECT.md` + (new `## Scope: Nova is Downstream of PDLC` subsection under Domain + Boundaries) and `docs/scope.md`. States that the PDLC (Product Development + Lifecycle — product backlog, code authorship, IDE) is upstream of Nova; + Nova governs infra + delivery only; integration is through the validated + contract boundary. Promotes Core Tenet #2 + Anti-Goal #1 from buried + tenets to a dedicated, unmissable scope statement. + +- **REQ-217** — `schemas/submission-readiness.schema.json` (JSON Schema + draft 2020-12) defines what is acceptable to start — a superset gate + *above* `contract.schema.json` validity. Required fields: `contractId` + (non-empty), `environment` (dev/qa/prod/dr) with the W3.E per-env mandatory + table enforced (dev: stack+environment; qa: +validation.e2eSuite + +validation.loadTest; prod: +runbook+dashboard+oncall; dr: +drDrillRef), + `tags` (the 5 required Nova tags per D-054: `nova:owner`, `nova:contract`, + `nova:environment`, `nova:cost-center`, `nova:ref`), `policyPreconditions` + (declared policy expectations the platform will enforce, e.g., + `public-ingress: false`), `profile` (`developer` or `agentic`; if + `agentic`, requires `naturalLanguageIntent`, `confidenceAtSubmission`, + `agentTrace` per REQ-22 / W3.E), `appSource` (repo + ref pointer for + runtime fetch). + +- **REQ-218** — `core/submission_readiness.py` validator, invoked as + `contract_ingestor.py --check-readiness` subcommand (decision D-133). Returns + a structured `ReadinessResult` (pass/fail per check, with reason codes). + On fail → the ingestor rejects with a citizen-developer-facing error + (not a stack trace). On pass → proceeds to existing contract ingestion. + Calls `contract.schema.json` validation first, then the readiness checks. + Reason codes: `MISSING_TAGS`, `ENV_MISSING_MANDATORY::`, + `AGENTIC_MISSING_INTENT`, `MISSING_APP_SOURCE`, `POLICY_PRECONDITION_MISSING`. + +- **REQ-219** — `docs/submission-readiness.md` citizen-developer-facing doc + explaining what is acceptable to start, with good + rejected examples and + the reason-code catalog. References `schemas/submission-readiness.schema.json` + as the source of truth. + +- **REQ-220** — `tests/test_submission_readiness.py` covers: good contract + passes; missing tags fail with `MISSING_TAGS`; missing env mandatory fails + with `ENV_MISSING_MANDATORY::`; agentic profile missing intent + fails with `AGENTIC_MISSING_INTENT`; missing appSource fails with + `MISSING_APP_SOURCE`. + +- **REQ-221** — `skills/` directory with 9 Atelier-derived skill files mapped + to the BA.A citizen-developer catalog: `skills/api.md` (domains/api/), + `skills/security.md` (domains/security/), `skills/data.md` (domains/data/), + `skills/testing.md` (domains/testing/), `skills/observability.md` + (domains/observability/), `skills/errors.md` (domains/errors/), + `skills/devops.md` (domains/devops/), `skills/infrastructure-as-code.md` + (domains/infrastructure-as-code/), `skills/compliance.md` + (domains/compliance/). Each names the Atelier source path, distills the + first-principles to the citizen-developer-relevant subset, links to + agent-checklist triggers, and maps to the BA.A 5-skill catalog (web API, + worker, scheduled job, static asset, basic observability bootstrap). + +- **REQ-222** — `docs/skills.md` index page listing the skill catalog, the + Atelier provenance, and how the citizen developer's AI agent consumes them + (read before completing a task; run `review/agent-checklist.md` before + finishing). `PROJECT.md` BA.A decision extended with the Atelier-derived + skill catalog reference. + +- **REQ-223** — `mcp/atelier/server.py` MCP server (stdio transport, + decision D-135) with a **plugin-registry architecture** (decision D-140): + `plugins/.py` modules each expose `register(mcp: MCPServer) -> None` + and call `@mcp.tool()` for their tools; `server.py` scans `plugins/` and + calls `register` on each. Initial plugins: `principles.py` + (`atelier.lookup_principle`, `atelier.list_domains`, `atelier.matrix_lookup`) + and `validation.py` (`atelier.validate_against_principles` — agentic + validation against the Atelier agent-checklist, beyond Wiz/Checkmarx/Mend). + Uses the MCP Python SDK v2 (`modelcontextprotocol/python-sdk`). + +- **REQ-224** — `mcp/atelier/vendor/` vendored Atelier snapshot (pinned tag, + decision D-136) for audit reproducibility. `mcp/atelier/vendor/VERSION.md` + records the pinned tag + a `scripts/update_atelier_vendor.sh` helper for + intentional upgrades. `mcp/atelier/README.md` documents the server: how to + run, transport, tool catalog, plugin-authoring guide, vendoring policy. + +- **REQ-225** — `tests/test_atelier_mcp.py` covers: tool registration (all 4 + tools discoverable via `tools/list`), `atelier.lookup_principle` returns + the principle text + core C-rule, `atelier.validate_against_principles` + catches a planted C1 (correctness) + C7 (observability) violation in a + known-bad snippet and passes a known-good snippet, `atelier.matrix_lookup` + returns the domain→core mapping, plugin discovery loads all plugins in + `plugins/`. + +- **REQ-226** — 3 new deck slides added to the unified deck + (`docs/presentations/nova-no-humans-platform-marp.md`) → 21 slides total: + Slide 19 "Scope: Downstream of PDLC", Slide 20 "RACI: Who Owns What", + Slide 21 "Production-Grade Guidance via Atelier". Arc Preview slide + updated to reflect 21-slide count. Talking points + (`nova-no-humans-platform-talking-points.md`) synced for the 3 new slides. + S&P theme preserved (regression check vs P1). CAP-024 deck structure + regression passes. + +- **REQ-227** — `docs/presentations/README.md` slide count + deck table + updated to reflect 21 slides + the 3 new slide titles. + +- **REQ-228** — `scripts/render_deck.sh` (renders HTML + PPTX from a Marp + deck, commits both to git) and `scripts/attach_release_asset.py` (uploads + a file to a Gitea release via the API). Any phase modifying + `docs/presentations/*-marp.md` or `docs/presentations/assets/` MUST + re-render HTML + PPTX, commit the PPTX binary to `docs/presentations/`, + and attach it to the phase's Gitea release. PPTX is stored as a committed + binary (no LFS, decision D-141). + +### Out of Scope (v1.18) + +- **Streamable HTTP transport for the MCP server** — stdio ships now; HTTP + is a future milestone (the SDK supports it on the same server object, so + adding it later is a transport-only change, not a rewrite). +- **A Nova-built frontend / dashboard** — observability stays PowerBI / + external; no Nova web UI. +- **Replacing the existing BA.A 5-skill catalog** — the Atelier-derived + skills extend it, not replace it. +- **Live AWS re-provisioning** (D-096, still deferred) — submission-readiness + validates the contract shape, not a live AWS deployment. +- **A second forge adapter** (GitLab) — BA.F cross-platform evolution is + future work. +- **Atelier live-fetch mode** — vendoring is the only mode this milestone; + live-fetch (with its reproducibility trade-offs) is not implemented. + +### v1.18 Traceability + +| REQ | Phase | Status | +|-----|-------|--------| +| REQ-214 | P1 | pending | +| REQ-215 | P2 | pending | +| REQ-216 | P2 | pending | +| REQ-217 | P3 | pending | +| REQ-218 | P3 | pending | +| REQ-219 | P3 | pending | +| REQ-220 | P3 | pending | +| REQ-221 | P4 | pending | +| REQ-222 | P4 | pending | +| REQ-223 | P5 | pending | +| REQ-224 | P5 | pending | +| REQ-225 | P5 | pending | +| REQ-226 | P6 | pending | +| REQ-227 | P6 | pending | +| REQ-228 | P1/P2/P6 | pending | diff --git a/.ciagent/ROADMAP.md b/.ciagent/ROADMAP.md index 3e0e5fe..0cc3d2b 100644 --- a/.ciagent/ROADMAP.md +++ b/.ciagent/ROADMAP.md @@ -1683,3 +1683,62 @@ deferred (D-113/D-114). Ship tag at milestone COMPLETE: `v1.15.26` (NFR milestone; final patch IS the release). **DONE.** + +## v1.18 (active — Citizen Developer & Production-Grade Guidance, tag line `v1.17.x`) + +Nova advances from a platform that governs infrastructure delivery to one +that **instructs the citizen developer on production-grade engineering** +and defines a **clear, machine-checkable contract for what is acceptable +to start**. Five user-directed inputs drive the milestone: + +1. **S&P Global theme restoration** (P1) — the v1.17 P5 deck rebuild lost + the S&P Global Energy brand visual identity (introduced v1.9.2 / P45). + The Marp `style:` block (`#D6002A` red, `#1B1B1B` grey-90, Akkurat Pro, + 8px accent bar) is restored to the unified deck. +2. **PDLC-upstream scope** (P2) — promotes Core Tenet #2 + Anti-Goal #1 + from buried tenets to a dedicated, unmissable scope statement: the PDLC + is upstream of Nova; Nova governs infra + delivery only. +3. **RACI matrix** (P2) — three-role responsibility matrix (Citizen + Developer / Platform / Release Management co-owned) clarifies who owns + what, with the compliance-standard-equivalence note. +4. **Nova input contract** (P3) — `schemas/submission-readiness.schema.json` + + `core/submission_readiness.py` validator define "what is acceptable to + start" as a superset gate above contract-schema validity. +5. **Atelier integration** (P4+P5) — skills (markdown, extending BA.A) + an + MCP server (plugin-registry, vendored Atelier, agentic validation + beyond Wiz/Checkmarx/Mend). + +**Milestone type:** Feature (P1 theme restoration + P3 schema/validator + +P5 MCP server are new code). Tags run on the v1.17.x patch line: +`v1.17.0` (P0) → `v1.17.1..v1.17.6` (P1–P6) → `v1.17.7` (P7 final = +milestone release). + +**Deck automation (cross-cutting, REQ-228):** any phase modifying +`docs/presentations/*-marp.md` or `docs/presentations/assets/` re-renders +HTML + PPTX, commits the PPTX binary to git, and attaches it to the +phase's Gitea release. + +**Phase count:** 8 (P0 pre-execution + 6 execution + 1 final). + +**Phases:** +- **P1 — sp-theme-restoration** (feat): restore S&P Global Marp theme to + unified deck + HTML re-render + PPTX commit + release attach. REQ-214,228. +- **P2 — pdlc-scope-raci** (docs): PDLC-upstream scope + RACI matrix + + 2 deck slides + HTML/PPTX re-render. REQ-215,216,228. +- **P3 — submission-readiness** (feat): JSON Schema + validator + docs + + tests. REQ-217,218,219,220. +- **P4 — atelier-skills** (docs): 9 Atelier-derived skill files + index + + BA.A extension. REQ-221,222. +- **P5 — atelier-mcp** (feat): plugin-registry MCP server + vendored + Atelier + 4 tools + tests. REQ-223,224,225. +- **P6 — deck-slides-atelier** (docs): 3 new deck slides (scope/RACI/atelier) + → 21 slides + talking points + HTML/PPTX re-render + README. REQ-226,227,228. +- **P7 — final-review-ship** (final): review + audit + milestone ship. + +**Requirements:** REQ-214..228 (15 requirements). See +`.ciagent/REQUIREMENTS.md` §v1.18. + +**Open decisions to lock (CLARIFY/GRILL):** D-133 (validator location), +D-134 (deck slide budget), D-135 (MCP transport), D-136 (Atelier vendoring), +D-137 (MCP server language), D-138 (skill format), D-139 (RACI roles), +D-140 (MCP plugin-registry), D-141 (PPTX storage), D-142 (deck render trigger). diff --git a/.ciagent/config.json b/.ciagent/config.json index ed5f34e..91282dc 100644 --- a/.ciagent/config.json +++ b/.ciagent/config.json @@ -8,7 +8,7 @@ ], "active_project": "acdl", "active_projects": ["acdl"], - "active_milestone": "v1.17", + "active_milestone": "v1.18", "autonomy": { "level": "full", "escalation_hooks": ["deploy", "delete_data", "merge_to_main"],