docs: ratify PRD rev1 — consolidated bundle, permanent shim, rev0 archived
ci/woodpecker/pr/ci Pipeline failed
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.
This commit is contained in:
@@ -0,0 +1,150 @@
|
||||
---
|
||||
id: GOV.2
|
||||
status: ratified
|
||||
ratified: 2026-09-01 (Jason Woltje; PRD rev1 ratification PR)
|
||||
---
|
||||
|
||||
# GOV.2 — Documentation inventory & supersession triage
|
||||
|
||||
E2 record and, at ratification, the PRD's answer to mandate item 4 (no central
|
||||
location; drift and naming confusion). Verdict vocabulary, per document:
|
||||
**canonical** | **superseded-by <ref>** | **conflict-with <ref>** |
|
||||
**working-notes** | **dead** | **operator-only** (brain corpora: correct home is
|
||||
the operator estate; nothing migrates).
|
||||
|
||||
Full per-file verdict tables live in the lane evidence record
|
||||
`fleet/lanes/control-plane-surfaces/TRIAGE-2026-08-31_e2-verdicts.md`
|
||||
(point-in-time; this section carries the durable conclusions).
|
||||
|
||||
## Corpora
|
||||
|
||||
| # | Corpus | Files | Scanned at |
|
||||
|---|--------|-------|-----------|
|
||||
| 1 | `mosaicstack/stack` `origin/next:docs/` | 346 | commit `9aa4983c`, triaged 2026-08-31 (141 live files per-file; archive dirs swept for orphaned decisions) |
|
||||
| 2 | `~/.mosaic/docs/` (excl. guides/proposed) | ~76 | triaged 2026-08-31 |
|
||||
| 3 | `~/.mosaic/docs/guides/proposed/` | 79 | triaged 2026-08-31 |
|
||||
| 4 | `fleet/lanes/agent-runtime-ng/` + `fleet/lanes/control-plane-surfaces/` | — | live lanes, canonical by definition for their scope |
|
||||
|
||||
## Corpus 1 — stack `origin/next:docs/` — conclusions
|
||||
|
||||
195 of 346 files (56%) were pre-triaged by the repo's own archive structure
|
||||
(`archive/` 135, `_old_structure/` 60). The 141 live files triaged per-file:
|
||||
|
||||
**The healthy core.** The five guide trees (DEVELOPER-GUIDE, ADMIN-GUIDE,
|
||||
USER-GUIDE), `fleet/` (concepts/how-to/reference/operations/migration),
|
||||
`native-kanban-sot/`, `webui/`, `API/`, `tess/`, `release-integrity/`, and the
|
||||
root atlas docs (README, ROADMAP, SITEMAP) are overwhelmingly **canonical** and
|
||||
internally consistent. Load-bearing canonical anchors for this PRD:
|
||||
`requirements/native-kanban-sot.md` (ratified, D13), `KBN-101-DB-ROLE-SPLIT.md`
|
||||
(frozen), `requirements/cli-capability-migration.md` (T78),
|
||||
`fleet/NORTH_STAR.md` + `FLEET-DOCTRINE.md`, `mutator-class-gate.md` and the
|
||||
lease-broker pair (AUTHZ ground truth), `compaction-revocation.md` (SESS ground
|
||||
truth), `sso-providers.md` (D10/AUTHN ground truth),
|
||||
`mos-runtime-portability-m1.md` (the only current PROV identity ADR),
|
||||
`web-dashboard.md` (UI route-by-route ground truth).
|
||||
|
||||
**The prime successor material.** The nine DRAFT "webui-audit S2" contracts in
|
||||
`requirements/` (hierarchy-schema, rbac-grant-model, onboarding-wizard,
|
||||
identity-lifecycle, tool-gateway-mapping, mode-conversion, custody-schema,
|
||||
rollup-projection, api-artifacts) are unratified but decision-traceable per
|
||||
clause to rev0 D-numbers — the most direct feed for DATA/AUTHZ/AUTHN/UI/CLI.
|
||||
`mode-conversion.md` predates D15 and needs reconciliation before it ratifies
|
||||
([[GOV.5-open-questions]] Q-T4). Per-contract extraction completed 2026-08-31
|
||||
(lane `S2-EXTRACTION-2026-08-31.md`): normative cores, dependency edges, and
|
||||
ruling cross-checks pulled into the DATA/AUTHZ/AUTHN/UI/CLI sections; two
|
||||
reconciliation questions raised (Q-T4 sharpened — no S2 file references D15;
|
||||
Q-T5 — projection-rule scope vs authoritative DB settings records).
|
||||
|
||||
**Conflicts requiring a ruling** (all carried in [[GOV.5-open-questions]] Q-T1):
|
||||
|
||||
| Document | Conflict |
|
||||
|---|---|
|
||||
| root `MISSION-MANIFEST.md` (2026-07-14) | makes federated-tier the "canonical MVP deployment topology", Federation v1 top-priority — vs D3 (deferred) and D15 (compose standalone canonical) |
|
||||
| `federation/MISSION-MANIFEST.md` (2026-04-21) | Federation v1 as active in-progress M3 — vs D3 and ROADMAP P5 "deliberately undesigned" |
|
||||
| `guides/deployment.md` | blocks Compose activation pending KBN-101 gates — vs D15's `docker compose up` v1 bar |
|
||||
| `scratchpads/mvp-20260312.md` | records a *completed* Federation M2 milestone (peer certs, grants, ScopeService, Step-CA) — vs D3's "deferred" framing |
|
||||
|
||||
Code reality, verified 2026-08-31 at `9aa4983c` (dossier: lane
|
||||
`FEDERATION-DOSSIER-2026-08-31.md`): federation M1–M3 are shipped and wired
|
||||
behind a `tier === 'federated'` gate — M3 landed 2026-06-24/25, beyond what any
|
||||
doc records — M4–M7 absent, dormant since 2026-06-25, absent from the canonical
|
||||
`docker-compose.yml` (so code topology is consistent with D15), and tracked
|
||||
nowhere since the TASKS.md → NORTH_STAR.yaml supersession. The three stale docs'
|
||||
claims date to 2026-04 by true content edits. **Ruled B ("shipped but
|
||||
frozen"), Jason 2026-09-01** — see [[GOV.5-open-questions]] Q-T1 for the
|
||||
amendment consequences the E6 return carries.
|
||||
|
||||
**Superseded set** (all with explicit in-file or index-level signals): root
|
||||
`TASKS.md`, `fleet/TASKS.md`, `federation/TASKS.md` (→ `fleet/NORTH_STAR.yaml`);
|
||||
`fleet/PRD.md` and `fleet/PRD-fleet-suite.md` (→ root `PRD.md`, per
|
||||
`fleet/README.md`); `native-kanban-sot` initial NO-GO review (→ GO re-review).
|
||||
`plans/`, `reports/`, `scratchpads/` are working-notes/evidence, never spec —
|
||||
consistent with their own README disclaimers.
|
||||
|
||||
**Orphaned decisions found in the archive sweep** (ratified once, absent from
|
||||
D1–D15 and every live doc; disposition on the grill, Q-T2):
|
||||
1. "No Python" monorepo ruling (`archive/planning/monorepo-consolidation/board-review.md:742`).
|
||||
2. Matrix/MACP "exactly three supported modes" install-topology ruling, Mode A
|
||||
split-domain primary; its DNS/domain prerequisite ruling still open
|
||||
(`archive/planning/matrix-macp/rfc-002:133`, `rfc-001:428`).
|
||||
3. OpenBrain cut from WP1/WP2 consolidation scope (`board-review.md:611`).
|
||||
|
||||
## Corpora 2 + 3 — `~/.mosaic/docs/` — conclusions
|
||||
|
||||
The overwhelming majority is **operator-only**: generic engineering standards,
|
||||
fleet role playbooks, SDLC gates, ops pages, fleet Q&A rulings, incident
|
||||
methods, host-specific plans. Correct home is the brain; nothing migrates.
|
||||
Notable verdicts:
|
||||
|
||||
- `docs/PRD.md` — **trap confirmed** (N1): it is the pi `/goal` extension PRD.
|
||||
Superseded in substance by [[GOV.4-workstream-contracts]] §Pi Persistent Goal
|
||||
Loop (#1150).
|
||||
- `docs/guides/proposed/workflows/prd-lifecycle.md` — superseded by
|
||||
[[GOV.1-prd-lifecycle]] (the draft lifecycle this bundle ratified).
|
||||
- `docs/plans/2026-08-25_unified-roadmap.md` (T72 consolidation charter) —
|
||||
superseded by this rev1 consolidation, its successor.
|
||||
- `docs/MOSAIC-CANON.md` vs `docs/STRUCTURE-CANON.md` — mutual conflict: both
|
||||
claim to be "the canonical definition of a mosaic-brain" (653 vs 127 lines,
|
||||
divergent sections); STRUCTURE-CANON is the copy everything links to.
|
||||
Operator-side ruling needed (Q-T3).
|
||||
- Dead: `plans/2026-08-22_config-json-schema.md` (delivered as stack#1382), two
|
||||
closed questions.
|
||||
|
||||
**Migration candidates** — nine working-notes whose product content should feed
|
||||
rev1 sections during refinement (full list with rationale in the lane evidence
|
||||
record): `specs/2026-08-29_mosaic-config-minimal-subset.md` → CLI;
|
||||
`specs/2026-08-28_intended-state-reconciler.md` → DATA;
|
||||
`operations/seat-identity.md` → SEAT; `operations/vault.md` → AUTHN;
|
||||
`runtime/adapter-contract.md` → HARN; `SPECIALIZATION-MODEL.md` → ROLE;
|
||||
`workflows/session-lifecycle.md` → SESS; `operations/prd-registry.md` → GOV;
|
||||
`workflows/configuration-lifecycle.md` → CLI/GOV.
|
||||
|
||||
`COORDINATION-CONTROL-PLANE.md` and `workflows/coordination-lifecycle.md` are
|
||||
product-adjacent but belong to the `agent-runtime-ng` lane's L1/L2 scope, not
|
||||
this bundle (corpus-4 boundary).
|
||||
|
||||
## Corpus 4 — the two lanes
|
||||
|
||||
Canonical for their scope by definition (they are the drafting record).
|
||||
`agent-runtime-ng` owns L1/L2 contract text; `control-plane-surfaces` owns
|
||||
surface/config findings and this bundle. One-way dependency: surfaces cite
|
||||
contracts, never the reverse.
|
||||
|
||||
## Naming defects register (mandate item 4)
|
||||
|
||||
| # | Defect | Fix proposed |
|
||||
|---|--------|--------------|
|
||||
| N1 | `~/.mosaic/docs/PRD.md` is the pi goal-extension PRD wearing the project-PRD name (confirmed 2026-08-31) | rename to a goal-extension-scoped name during return |
|
||||
| N2 | Stack local `main` is a divergent unpushed fork that shadows `next` | already a lane convention; PRD states trunk identity explicitly |
|
||||
| N3 | Pre-2026-08-26 pattern: `docs/PRD.md` overwritten per milestone | retired by [[GOV.1-prd-lifecycle]] shim model |
|
||||
| N4 | Two decision registries share the D-prefix ID space (stack D1–D15 vs operator D01–D65); "D8" is ambiguous without registry name | OD- prefix applied in rev1 (Q-G2 ruled 2026-09-01); collision rule in [[GOV.3-decision-map]] |
|
||||
| N5 | Triple "PRD" collision in the stack tree: root `PRD.md` vs superseded `fleet/PRD.md` and `fleet/PRD-fleet-suite.md`, with no local supersession signal on the latter two | supersession banner in-file; long-term, the GOV.1 rule that the bare name `PRD.md` is reserved for the shim |
|
||||
| N6 | "Tess" and "Ultron" each name two different things: non-authoritative roster-class display aliases (fleet how-tos) vs the named product agent / validator identity (TESS workstream, native-kanban-sot) | rev1 text always qualifies which sense is meant; flag for upstream rename of the aliases |
|
||||
| N7 | Six stack `TASKS.md` files under three authority regimes (banner-superseded / explicitly-not-superseded / silently active) — the filename signals nothing | uniform status frontmatter on every TASKS.md; superseded ones point at NORTH_STAR.yaml |
|
||||
| N8 | Duplicate basenames across stack dirs: `gateway-security-20260313.md` (qa vs code-review, different content), `2026-08-10-docs-catalog-audit.md` (plan vs report), `1099-pipefail-sweep.md` (report vs scratchpad copy) | disambiguate on next touch; prune the unpromoted scratchpad copy |
|
||||
| N9 | `guides/` is outside the canonical tree per `docs/README.md` yet "protected current authority" per `SITEMAP.md` — contract and sitemap disagree | reconcile the documentation contract; likely fold the four guides into the guide trees |
|
||||
| N10 | Two live front-matter schemas (`type`/`status: current…` per docs/README.md vs the newer `kind`/`status: active…` used by most files) — collision documented in the w4 worklist, unresolved | settle the schema in the documentation contract as part of E6 return |
|
||||
| N11 | Three uncross-referenced descriptions of the `/goal` capability: brain `docs/PRD.md`, `operations/goals.md`, and GOV.4 §#1150 | reconcile under the #1150 identity; brain docs cite it |
|
||||
| N12 | Brain-side: `MOSAIC-CANON.md` vs `STRUCTURE-CANON.md` both claim canon status | operator ruling (Q-T3); retire or fold the unreferenced copy |
|
||||
| N13 | Forward-looking: rev0 Part II (RI-N3) rules `docs/PRD.md` "not a peer authority" once `docs/prdy/` lands — a third contender in "which PRD is real" | GOV.1 disambiguation: prdy is tooling-facing storage; the shim + bundle remain the human-facing SOT chain |
|
||||
| N14 | Commit `a480ee83` (2026-08-21) mass-stamped `status: active` frontmatter across stack docs without content review — status metadata rubber-stamps stale docs as current (root MISSION-MANIFEST's "Last Updated: 2026-07-14" is likewise cosmetic; true content edit 2026-04-19) | status/date frontmatter changes only alongside content review; triage dates by git content edits, never frontmatter |
|
||||
Reference in New Issue
Block a user