jason.woltje
ad21ad7ac5
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.
11 KiB
id, status, ratified
| id | status | ratified |
|---|---|---|
| GOV.2 | 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 | conflict-with | 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):
- "No Python" monorepo ruling (
archive/planning/monorepo-consolidation/board-review.md:742). - 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). - 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/goalextension 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.mdvsdocs/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 |