docs: ratify PRD rev1 — consolidated bundle, permanent shim, rev0 archived
ci/woodpecker/pr/ci Pipeline failed
ci/woodpecker/pr/ci Pipeline failed
Ratifies the Mosaic Stack PRD rev1 (Jason Woltje, 2026-09-01) as project source of truth and installs the GOV.1 lifecycle model: - docs/PRD.md becomes a permanent shim (kind: shim, current_rev -> docs/PRDs/2026-08-31_PRD_rev1/). Its path never changes again. - docs/PRDs/2026-08-26_PRD_rev0/PRD.md archives the 2026-08-26 North Star verbatim (sha256 60cc2f98...36afdf unchanged). Archive, never delete. - docs/PRDs/2026-08-31_PRD_rev1/ is the frozen rev1 bundle: 18 sectioned documents (VIS, DATA, AUTHN, AUTHZ, SEAT, ROLE, HARN, PROV, SESS, UI, CLI, GOV.1-5) consolidating rev0 D1-D15, the fleet north star, the agent-runtime L1/L2 contracts and the control-plane-surfaces lane findings, with a single decision map (GOV.3) and a closed open-questions frontier (GOV.5, grill rounds 1-8). Drafting inputs (_source-* snapshots) are not shipped. Consequences of the ratified rulings carried in the same change: - Q-T1 (ruling B, "shipped but frozen"): D3 amended in GOV.3/VIS.1; federation M1-M3 acknowledged as shipped behind tier === 'federated', excluded from the v1 bar and frozen, with a security re-audit gate before any resumption. docs/MISSION-MANIFEST.md, docs/federation/MISSION-MANIFEST.md and docs/scratchpads/mvp-20260312.md get status: superseded + banners (content preserved verbatim); docs/guides/deployment.md gains a "Relationship to the PRD (D15)" section. NORTH_STAR.yaml adds dormant workstream M (projects no goals by design); NORTH_STAR.md regenerated. - Q-G2 (distinct registry prefixes): every citation of the operator DECISION-REGISTER in the bundle reads OD-nn; the stack registry stays D1-D15; L1-Dnn/L2-Dnn untouched. Prefix rule recorded in GOV.1. Follow-ups (not in this PR): CI parity drift-gate witness (Q-C1); brain-side DECISION-REGISTER rename to OD- with redirect table on its next touch.
This commit is contained in:
@@ -0,0 +1,106 @@
|
||||
---
|
||||
id: GOV.1
|
||||
status: ratified
|
||||
ratified: 2026-09-01 (Jason Woltje; PRD rev1 ratification PR)
|
||||
---
|
||||
|
||||
# GOV.1 — PRD lifecycle: SOT, shim, revisions, archival
|
||||
|
||||
Ratified structurally by Jason, 2026-08-31 (this lane's grill session). Applies
|
||||
to the Mosaic Stack PRD in `mosaicstack/stack` (integration trunk `next`).
|
||||
|
||||
## The PRD is the project SOT
|
||||
|
||||
The PRD is the source of truth for the entire project, independent of any
|
||||
mission. It is not linked to a current mission and is never overwritten by
|
||||
milestone work — the pre-2026-08-26 pattern of repurposing `docs/PRD.md` per
|
||||
milestone is retired. Mission documents are separate: they **reference** the
|
||||
PRD; they never usurp it. This maintains alignment over time.
|
||||
|
||||
## Shim
|
||||
|
||||
`docs/PRD.md` is a permanent shim, not the PRD body:
|
||||
|
||||
- Frontmatter: `kind: shim`, `current_rev:` pointing at the live revision
|
||||
bundle.
|
||||
- Body: one-paragraph summary and a link into `docs/PRDs/`.
|
||||
- Updating the PRD means ratifying a new revision bundle and repointing the
|
||||
shim. The shim's path never changes, so every external reference to
|
||||
`docs/PRD.md` stays valid forever.
|
||||
|
||||
## Revision bundles
|
||||
|
||||
Each ratified revision is a **frozen bundle directory**:
|
||||
|
||||
```
|
||||
docs/PRDs/YYYY-MM-DD_PRD_revN/
|
||||
PRD.md # the assembled PRD for this revision
|
||||
PRD.0-index.md # order authority + domain registry as of this revision
|
||||
<DOMAIN>.<n>-*.md # every section document, frozen with the PRD
|
||||
```
|
||||
|
||||
The PRD and its supporting sections freeze **as a set** — a revision whose
|
||||
sections keep moving underneath it is not a revision. Live editing never
|
||||
happens in `docs/PRDs/`; the next revision is drafted in a lane
|
||||
(class‑2 draft-natives per the lane's `proposed/README.md`) and lands as a new
|
||||
bundle.
|
||||
|
||||
## Archival, never deletion
|
||||
|
||||
A superseded revision is never deleted and never edited. Versioning is
|
||||
maintained: every revision that was ever current remains in `docs/PRDs/`
|
||||
verbatim. Supersession is expressed only from outside the bundle: the shim
|
||||
points elsewhere, and the dated directory names plus the shim's git history are
|
||||
the supersession record. The frozen bundle itself is never touched — not even
|
||||
to add a `superseded_by:` marker.
|
||||
|
||||
## Immutability is convention, not enforcement
|
||||
|
||||
No hook or CI guard protects `docs/PRDs/` today. If teeth are wanted later, a
|
||||
CI check that files under `docs/PRDs/` never change after merge is cheap; that
|
||||
is a separate, future decision.
|
||||
|
||||
## Lineage
|
||||
|
||||
- rev0 = the 2026-08-26 "North Star" PRD currently at `origin/next:docs/PRD.md`
|
||||
(commit `9aa4983c`, sha256 `60cc2f98…36afdf`; lane snapshot
|
||||
[rev0 PRD](../2026-08-26_PRD_rev0/PRD.md)). On ratification of rev1 it archives as
|
||||
`docs/PRDs/2026-08-26_PRD_rev0/PRD.md` — a one-file bundle, so every revision
|
||||
has the same shape.
|
||||
- rev1 = this lane's draft bundle (`proposed/docs/PRDs/2026-08-31_PRD_rev1/`),
|
||||
combining rev0 with the control-plane-surfaces and agent-runtime-ng lane
|
||||
findings and the reconciled docs corpus.
|
||||
|
||||
Related: [[PRD.0-index]] for naming and ordering; the lane `proposed/README.md`
|
||||
for draft-stage conventions.
|
||||
## Registry mechanics (pulled 2026-08-31 from the prd-registry draft)
|
||||
|
||||
The operator draft `operations/prd-registry.md` independently specifies the
|
||||
same lifecycle and adds mechanics this doc adopts:
|
||||
|
||||
- **The registry, not the shim, is authoritative.** The shim is generated,
|
||||
regenerated on every acceptance and amendment; a missing or ambiguous shim
|
||||
entry is a generation defect, never an authority question.
|
||||
- Registered versions carry: stable PRD ID, canonical filename/slug, version +
|
||||
status, acceptance timestamp **and actor**, lineage, content digest,
|
||||
requirement IDs. Anonymous or inferred acceptance is invalid.
|
||||
- Missions pin PRD ID + version + digest + in-scope requirement IDs; a digest
|
||||
mismatch between pin and artifact **blocks the readiness transition** (both
|
||||
digests shown as evidence).
|
||||
- Amendment creates a new immutable version; superseded versions remain
|
||||
queryable as lineage; **requirement IDs are never reused**.
|
||||
- Agents read and resolve; they never register versions, rewrite artifacts, or
|
||||
select an implicit latest.
|
||||
|
||||
## Registry prefixes (Q-G2, 2026-09-01)
|
||||
|
||||
Every decision-bearing document declares a unique registry prefix; file-local
|
||||
bare D-numbering is prohibited. Three registries are live: the stack PRD
|
||||
registry (**D1–D15**, and successors **Dn** as new stack decisions ratify),
|
||||
the operator DECISION-REGISTER (**OD-01…OD-65**, renamed from its former
|
||||
zero-padded `D01`–`D65` form per this ruling), and the agent-runtime-ng
|
||||
contract decisions (**L1-Dnn**/**L2-Dnn**) — three distinct namespaces that
|
||||
must never be conflated. Any new decision-bearing document must declare its
|
||||
own unique prefix in its header before citing decisions. In text written
|
||||
before 2026-09-01, a zero-padded bare `Dnn` reads as the operator register's
|
||||
`OD-nn`.
|
||||
Reference in New Issue
Block a user