---
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`.