Files

T

ci/woodpecker/pr/ci Pipeline failed

Details

docs: PRD rev1 review Q90 — Prettier-format the bundle, add rev0 archive README

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.

2026-09-02 09:40:46 -05:00

4.7 KiB

Raw Blame History

id, status, ratified

id	status	ratified
GOV.1	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). 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.

4.7 KiB Raw Blame History Unescape Escape