jason.woltje
ad21ad7ac5
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.
107 lines
4.7 KiB
Markdown
107 lines
4.7 KiB
Markdown
---
|
||
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`.
|