jason.woltje
13968e9a8b
ci/woodpecker/pr/ci Pipeline failed
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.
152 lines
15 KiB
Markdown
152 lines
15 KiB
Markdown
---
|
||
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 |
|