Files

T

ci/woodpecker/pr/ci Pipeline failed

Details

docs: ratify PRD rev1 — consolidated bundle, permanent shim, rev0 archived

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.

2026-09-01 18:32:14 -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