docs(init): validate specification — v1.18 Citizen Developer & Production-Grade Guidance
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---
This commit is contained in:
Jon Chery
@@ -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:<env>:<field>`,
|
||||
`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:<env>:<field>`; 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/<name>.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 |
|
||||
|
||||
Reference in New Issue
Block a user