jason.woltje
13968e9a8b
ci/woodpecker/pr/ci Pipeline failed
Addresses CPS-PRD-REV1-REVIEW-Q90 findings F1 and F3 on PR #1491: F1 (format gate): `prettier --write` on the 18 rev1 bundle documents. Whitespace, table padding, list markers and emphasis delimiters only — a normalized token comparison of every file before/after shows zero content difference, so the ratified text is unchanged and no re-ratification applies. F3 (rev0 relative links): the archived rev0 PRD stays byte-identical (sha256 60cc2f98...36afdf verified) per GOV.1 archive-never-edit. A sibling docs/PRDs/2026-08-26_PRD_rev0/README.md records the digest, the original location, the owner disposition that the in-file links are intentionally historical, and a resolution table for all 9 targets (11 occurrences), each verified to exist. Future relocated archives ship the same README instead of edited bytes. F2 (test step) is investigated separately against the CI log.
108 lines
4.7 KiB
Markdown
108 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`.
|