jason.woltje
13968e9a8b
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.
15 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 |