From f0d2dd99207caa53dcf61d4a55d843f68ee6b84c Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 19:30:25 -0500 Subject: [PATCH 01/10] docs(W4): stamp kind and status front matter on 104 live documents Applies the document contract from docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially: `kind` and `status` only. `parent` is deliberately held until the flatten in section 4 lands, so that 127 documents do not have to be re-pointed by hand when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml. Scope, measured on origin/next at 63069149: 127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/ 104 stamped here 19 held operator judgement (plan section 9), worklist in the same PR 3 held the SUPERSEDED TASKS.md stamps, which cite the moving path 1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1 Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection. Every row carries a confidence and a one-line rationale in the worklist. Two collisions with the existing state, both flagged rather than resolved: 1. docs/README.md:150-160 already documents a front-matter convention (title/type/audience/status/source_of_truth) with its own allowed values. It is applied to 4 of 127 files. Its `status` vocabulary is current|draft|deprecated|historical; the new contract's is active|superseded-by. The key collides. This commit lets the new contract win and rewrites `status: current` to `status: active` on those 4 files, keeping their other legacy keys untouched. No code reads any of them: `git grep source_of_truth` outside docs/ returns nothing. docs/README.md still prescribes the old convention and is an operator row, so it is not edited here. 2. Two of the plan's 20 operator rows are YAML files, not markdown (docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the contract's front-matter form has no defined meaning for a .yaml document. That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth itself. Raised in the worklist. A third row from the plan, docs/fleet/north-star.md, no longer exists: W1 renamed it to docs/fleet/FLEET-DOCTRINE.md. Verification: 104/104 parse with the expected kind and status in front matter; the check was shown to reject a wrong kind before it was trusted. The diff removes 4 lines total, all of them `status: current`. --- docs/ADMIN-GUIDE/README.md | 5 +++++ docs/ADMIN-GUIDE/operations/README.md | 5 +++++ .../ADMIN-GUIDE/operations/mos-connector-lease-operations.md | 5 +++++ docs/ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md | 5 +++++ docs/ADMIN-GUIDE/security/README.md | 5 +++++ docs/ADMIN-GUIDE/security/discord-ingress.md | 5 +++++ docs/ADMIN-GUIDE/security/sso-providers.md | 3 ++- docs/API/README.md | 5 +++++ docs/DEVELOPER-GUIDE/README.md | 5 +++++ docs/DEVELOPER-GUIDE/architecture/README.md | 5 +++++ docs/DEVELOPER-GUIDE/architecture/channel-protocol.md | 5 +++++ docs/DEVELOPER-GUIDE/architecture/compaction-revocation.md | 5 +++++ docs/DEVELOPER-GUIDE/architecture/decisions/README.md | 5 +++++ .../architecture/decisions/mos-runtime-portability-m1.md | 5 +++++ docs/DEVELOPER-GUIDE/architecture/lease-broker-protocol.md | 5 +++++ docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md | 5 +++++ docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md | 5 +++++ docs/DEVELOPER-GUIDE/architecture/rfcs/README.md | 5 +++++ .../architecture/rfcs/optional-ai-egress-gateways.md | 5 +++++ docs/DEVELOPER-GUIDE/integrations/channel-adapters.md | 5 +++++ docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md | 3 ++- docs/MISSION-MANIFEST.md | 5 +++++ docs/PRD.md | 5 +++++ docs/USER-GUIDE/README.md | 5 +++++ docs/USER-GUIDE/getting-started/quickstart.md | 3 ++- docs/USER-GUIDE/product/web-dashboard.md | 3 ++- docs/USER-GUIDE/workflows/discord-conversations.md | 5 +++++ docs/federation/MISSION-MANIFEST.md | 5 +++++ docs/fleet/NORTH_STAR.md | 5 +++++ docs/fleet/PRD-fleet-suite.md | 5 +++++ docs/fleet/PRD.md | 5 +++++ docs/fleet/concepts/desired-vs-observed-state.md | 5 +++++ docs/fleet/concepts/generated-env-launch-chain.md | 5 +++++ docs/fleet/concepts/identity-class-runtime.md | 5 +++++ docs/fleet/concepts/role-authority-and-leases.md | 5 +++++ docs/fleet/how-to/configure-tess-interaction.md | 5 +++++ docs/fleet/how-to/configure-ultron-validator.md | 5 +++++ docs/fleet/how-to/create-update-delete-agent.md | 5 +++++ docs/fleet/how-to/customize-roles.md | 5 +++++ docs/fleet/how-to/start-stop-restart.md | 5 +++++ docs/fleet/migration/example-profile-disposition.md | 5 +++++ docs/fleet/migration/legacy-class-aliases.md | 5 +++++ docs/fleet/migration/v1-to-v2.md | 5 +++++ docs/fleet/operations/backup-restore.md | 5 +++++ docs/fleet/operations/env-quarantine.md | 5 +++++ docs/fleet/operations/reconcile-and-recover.md | 5 +++++ docs/fleet/operations/systemd-tmux-troubleshooting.md | 5 +++++ docs/fleet/operations/upgrade-assets.md | 5 +++++ docs/fleet/reference/agent-mutations.md | 5 +++++ docs/fleet/reference/cli.md | 5 +++++ docs/fleet/reference/generated-env-boundary.md | 5 +++++ docs/fleet/reference/lifecycle-transitions.md | 5 +++++ docs/fleet/reference/role-classes.md | 5 +++++ docs/fleet/reference/roster-v2-fields.md | 5 +++++ docs/fleet/reference/status-and-drift.md | 5 +++++ docs/guides/deployment.md | 5 +++++ docs/guides/dev-guide.md | 5 +++++ docs/guides/fleet-local-canary.md | 5 +++++ docs/guides/migrate-tier.md | 5 +++++ docs/native-kanban-sot/MISSION-MANIFEST.md | 5 +++++ docs/plans/2026-08-10-ci-queue-purpose-design.md | 5 +++++ docs/plans/2026-08-10-ci-queue-purpose-implementation.md | 5 +++++ docs/plans/2026-08-10-docs-catalog-audit.md | 5 +++++ .../plans/2026-08-10-docs-information-architecture-design.md | 5 +++++ docs/plans/2026-08-10-docs-structure-readme.md | 5 +++++ docs/plans/README.md | 5 +++++ docs/release-integrity/TASKS.md | 5 +++++ docs/reports/README.md | 5 +++++ docs/reports/code-review/756-code-review.md | 5 +++++ docs/reports/code-review/gateway-security-20260313.md | 5 +++++ .../compaction-refresh/830-documentation-checklist.md | 5 +++++ docs/reports/deferred/758-fleet-config-deferrals.md | 5 +++++ docs/reports/documentation/2026-08-10-docs-catalog-audit.md | 5 +++++ docs/reports/documentation/756-discord-plugin-checklist.md | 5 +++++ docs/reports/documentation/758-fleet-config-ia-closure.md | 5 +++++ .../documentation/AUDIT-2026-02-17-framework-consistency.md | 5 +++++ docs/reports/native-kanban-sot/canon-final-rereview-go.md | 5 +++++ docs/reports/native-kanban-sot/canon-initial-review-no-go.md | 5 +++++ .../kbn-101-contract-security-review-82ce325.md | 5 +++++ docs/reports/native-kanban-sot/ultron-final-go.md | 5 +++++ docs/reports/qa/gateway-security-20260313.md | 5 +++++ docs/reports/qa/p8-003-performance-optimization.md | 5 +++++ docs/reports/quality/1099-pipefail-sweep.md | 5 +++++ docs/reports/security/756-security-review.md | 5 +++++ docs/scratchpads/1019-zero-timeout-harness.md | 5 +++++ docs/scratchpads/1043-pane-git-identity.md | 5 +++++ docs/scratchpads/1098-framework-shell-portability.md | 5 +++++ docs/scratchpads/1099-pipefail-sweep.md | 5 +++++ docs/scratchpads/1146-ci-queue-purpose.md | 5 +++++ docs/scratchpads/1150-pi-goal-extension.md | 5 +++++ docs/scratchpads/1174-wrapper-guard-round10.md | 5 +++++ docs/scratchpads/1179-required-security-di.md | 5 +++++ docs/scratchpads/1194-framework-tool-drift.md | 5 +++++ docs/scratchpads/DOCS-IA-001.md | 5 +++++ docs/scratchpads/DOCS-IA-002-catalog-audit.md | 5 +++++ docs/scratchpads/README.md | 5 +++++ docs/scratchpads/lease-remediation/dispatch/measure-W-B.md | 5 +++++ docs/scratchpads/mvp-20260312.md | 5 +++++ docs/scratchpads/pr-merge-message-field.md | 5 +++++ docs/scratchpads/ri-050.md | 5 +++++ docs/scratchpads/webui-p3r1-routing-mcp.md | 5 +++++ docs/scratchpads/webui-p4-1.md | 5 +++++ docs/tess/MISSION-MANIFEST.md | 5 +++++ docs/tess/TASKS.md | 5 +++++ 104 files changed, 508 insertions(+), 4 deletions(-) diff --git a/docs/ADMIN-GUIDE/README.md b/docs/ADMIN-GUIDE/README.md index 2aef404b..b8f13cc3 100644 --- a/docs/ADMIN-GUIDE/README.md +++ b/docs/ADMIN-GUIDE/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Administrator Guide > **Status:** Partially migrated. Current SSO and local upgrade/recovery procedures are available; held procedures are labeled non-operative. diff --git a/docs/ADMIN-GUIDE/operations/README.md b/docs/ADMIN-GUIDE/operations/README.md index c6ad5ce6..e70e0ec9 100644 --- a/docs/ADMIN-GUIDE/operations/README.md +++ b/docs/ADMIN-GUIDE/operations/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Administrator Operations > **Status:** Partially migrated. Procedures explicitly identify whether they are current or held. diff --git a/docs/ADMIN-GUIDE/operations/mos-connector-lease-operations.md b/docs/ADMIN-GUIDE/operations/mos-connector-lease-operations.md index e336caa0..ee0bc66f 100644 --- a/docs/ADMIN-GUIDE/operations/mos-connector-lease-operations.md +++ b/docs/ADMIN-GUIDE/operations/mos-connector-lease-operations.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Mos Connector Lease Operations — M1 > **Status:** Held / non-operative. diff --git a/docs/ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md b/docs/ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md index 832979e3..5eb08f7a 100644 --- a/docs/ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md +++ b/docs/ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Upgrade safety and recovery > **Supported route:** an already installed `mosaic` CLI using the local PGlite diff --git a/docs/ADMIN-GUIDE/security/README.md b/docs/ADMIN-GUIDE/security/README.md index aff6909a..e033ed80 100644 --- a/docs/ADMIN-GUIDE/security/README.md +++ b/docs/ADMIN-GUIDE/security/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Security > **Status:** Partially migrated. The SSO provider and Discord ingress security pages are current. diff --git a/docs/ADMIN-GUIDE/security/discord-ingress.md b/docs/ADMIN-GUIDE/security/discord-ingress.md index 4165adb7..7b83cc13 100644 --- a/docs/ADMIN-GUIDE/security/discord-ingress.md +++ b/docs/ADMIN-GUIDE/security/discord-ingress.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Discord ingress security > **Status:** Current Discord behavior only. Telegram shared-contract parity, Matrix channel ingress, and a gateway-wide shared adapter registry are not implemented or are not proven by the current source/tests. diff --git a/docs/ADMIN-GUIDE/security/sso-providers.md b/docs/ADMIN-GUIDE/security/sso-providers.md index 2f09b789..44f7293b 100644 --- a/docs/ADMIN-GUIDE/security/sso-providers.md +++ b/docs/ADMIN-GUIDE/security/sso-providers.md @@ -1,8 +1,9 @@ --- +kind: guide +status: active title: SSO Providers type: runbook audience: admin -status: current source_of_truth: false --- diff --git a/docs/API/README.md b/docs/API/README.md index 2d6fc5a5..9e548d7d 100644 --- a/docs/API/README.md +++ b/docs/API/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # API Documentation > **Status:** Scaffold only. The canonical gateway contract has not yet been migrated into this directory. diff --git a/docs/DEVELOPER-GUIDE/README.md b/docs/DEVELOPER-GUIDE/README.md index 39699767..c9fc6b23 100644 --- a/docs/DEVELOPER-GUIDE/README.md +++ b/docs/DEVELOPER-GUIDE/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Developer Guide > **Status:** Partially migrated. Architecture, lease-broker verification, and channel-adapter authoring pages are current; other contributor chapters remain unmigrated. diff --git a/docs/DEVELOPER-GUIDE/architecture/README.md b/docs/DEVELOPER-GUIDE/architecture/README.md index a7d4ac9f..d7518087 100644 --- a/docs/DEVELOPER-GUIDE/architecture/README.md +++ b/docs/DEVELOPER-GUIDE/architecture/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Architecture > **Status:** Partially migrated. The lease-broker security-contract pages below are current references; the remaining architecture pages are still being classified. diff --git a/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md b/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md index 9815d049..290fb8ea 100644 --- a/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md +++ b/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Channel protocol architecture > **Status:** Current shared type contract and Discord compatibility baseline. The shared gateway registry, Telegram parity, Matrix integration, identity-linking, and multi-surface multiplexing described below are draft or unimplemented. diff --git a/docs/DEVELOPER-GUIDE/architecture/compaction-revocation.md b/docs/DEVELOPER-GUIDE/architecture/compaction-revocation.md index 66d835bd..35906147 100644 --- a/docs/DEVELOPER-GUIDE/architecture/compaction-revocation.md +++ b/docs/DEVELOPER-GUIDE/architecture/compaction-revocation.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Compaction observer revocation and runtime generations > **Status:** Current contract reference. diff --git a/docs/DEVELOPER-GUIDE/architecture/decisions/README.md b/docs/DEVELOPER-GUIDE/architecture/decisions/README.md index aee87b49..914a667e 100644 --- a/docs/DEVELOPER-GUIDE/architecture/decisions/README.md +++ b/docs/DEVELOPER-GUIDE/architecture/decisions/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Architecture Decisions > **Status:** Current decision index. A decision describes an implemented and accepted boundary; draft proposals belong under `rfcs/` or `docs/plans/`. diff --git a/docs/DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md b/docs/DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md index eba57bdd..e3021699 100644 --- a/docs/DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md +++ b/docs/DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Mos Runtime Portability M1 — Logical Identity and Fencing > **Decision status:** Current implemented decision (M1). diff --git a/docs/DEVELOPER-GUIDE/architecture/lease-broker-protocol.md b/docs/DEVELOPER-GUIDE/architecture/lease-broker-protocol.md index 39e5ee71..5ba63dc3 100644 --- a/docs/DEVELOPER-GUIDE/architecture/lease-broker-protocol.md +++ b/docs/DEVELOPER-GUIDE/architecture/lease-broker-protocol.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Authenticated external lease broker protocol > **Status:** Current contract reference. diff --git a/docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md b/docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md index 0209165a..ac482a72 100644 --- a/docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md +++ b/docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # WI-1 lease broker security notes > **Status:** Current contract reference. diff --git a/docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md b/docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md index 66f321e6..73f09cfd 100644 --- a/docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md +++ b/docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Whole mutator-class lease gate > **Status:** Current contract reference. diff --git a/docs/DEVELOPER-GUIDE/architecture/rfcs/README.md b/docs/DEVELOPER-GUIDE/architecture/rfcs/README.md index 7c5b3085..681da766 100644 --- a/docs/DEVELOPER-GUIDE/architecture/rfcs/README.md +++ b/docs/DEVELOPER-GUIDE/architecture/rfcs/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Architecture RFCs > **Status:** Current proposal index. RFCs are draft design material and have no operational or implementation authority until an approved decision and implementation evidence supersede them. diff --git a/docs/DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md b/docs/DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md index 9db1734c..4cb752a7 100644 --- a/docs/DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md +++ b/docs/DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # RFC: Optional AI Egress Gateways > **Status:** Draft / proposed — not approved, not current, and not integrated. diff --git a/docs/DEVELOPER-GUIDE/integrations/channel-adapters.md b/docs/DEVELOPER-GUIDE/integrations/channel-adapters.md index a1438401..3a8f426c 100644 --- a/docs/DEVELOPER-GUIDE/integrations/channel-adapters.md +++ b/docs/DEVELOPER-GUIDE/integrations/channel-adapters.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Channel adapters > **Status:** Current shared channel types plus the Discord reference/compatibility implementation. A shared gateway adapter registry, Telegram parity, and Matrix channel integration remain unimplemented or unproven. diff --git a/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md b/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md index dfc57c25..b54098cf 100644 --- a/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md +++ b/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md @@ -1,8 +1,9 @@ --- +kind: guide +status: active title: Lease-broker operations type: runbook audience: developer -status: current source_of_truth: false --- diff --git a/docs/MISSION-MANIFEST.md b/docs/MISSION-MANIFEST.md index 8baa41e8..595bea1a 100644 --- a/docs/MISSION-MANIFEST.md +++ b/docs/MISSION-MANIFEST.md @@ -1,3 +1,8 @@ +--- +kind: tracking +status: active +--- + # Mission Manifest — MVP > Top-level rollup tracking Mosaic Stack MVP execution. diff --git a/docs/PRD.md b/docs/PRD.md index 50e8334d..3aad4016 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # PRD: Mosaic Stack v0.1.0 ## Current addendum: #1194 — Installed framework-tool drift detection diff --git a/docs/USER-GUIDE/README.md b/docs/USER-GUIDE/README.md index 269ee134..87285955 100644 --- a/docs/USER-GUIDE/README.md +++ b/docs/USER-GUIDE/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # User Guide > **Status:** Partially migrated. The quickstart, web-dashboard reference, and Discord conversation workflow are current. diff --git a/docs/USER-GUIDE/getting-started/quickstart.md b/docs/USER-GUIDE/getting-started/quickstart.md index 7d29fd28..f31ade8f 100644 --- a/docs/USER-GUIDE/getting-started/quickstart.md +++ b/docs/USER-GUIDE/getting-started/quickstart.md @@ -1,8 +1,9 @@ --- +kind: guide +status: active title: Mosaic Stack Quickstart type: guide audience: user -status: current source_of_truth: false --- diff --git a/docs/USER-GUIDE/product/web-dashboard.md b/docs/USER-GUIDE/product/web-dashboard.md index d7afbc72..60b4d2d6 100644 --- a/docs/USER-GUIDE/product/web-dashboard.md +++ b/docs/USER-GUIDE/product/web-dashboard.md @@ -1,8 +1,9 @@ --- +kind: guide +status: active title: Mosaic web dashboard type: guide audience: user -status: current source_of_truth: false --- diff --git a/docs/USER-GUIDE/workflows/discord-conversations.md b/docs/USER-GUIDE/workflows/discord-conversations.md index 61a9d09a..8a63541d 100644 --- a/docs/USER-GUIDE/workflows/discord-conversations.md +++ b/docs/USER-GUIDE/workflows/discord-conversations.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Discord conversations > **Status:** Current Discord workflow for an administrator-provisioned, authorized guild channel. diff --git a/docs/federation/MISSION-MANIFEST.md b/docs/federation/MISSION-MANIFEST.md index 861f17ec..8e1905ea 100644 --- a/docs/federation/MISSION-MANIFEST.md +++ b/docs/federation/MISSION-MANIFEST.md @@ -1,3 +1,8 @@ +--- +kind: tracking +status: active +--- + # Mission Manifest — Federation v1 > Persistent document tracking full mission scope, status, and session history. diff --git a/docs/fleet/NORTH_STAR.md b/docs/fleet/NORTH_STAR.md index ba066838..61ef4ce4 100644 --- a/docs/fleet/NORTH_STAR.md +++ b/docs/fleet/NORTH_STAR.md @@ -1,3 +1,8 @@ +--- +kind: projection +status: active +--- + # Mosaic Fleet — NORTH STAR > **Generated file — do not edit by hand.** diff --git a/docs/fleet/PRD-fleet-suite.md b/docs/fleet/PRD-fleet-suite.md index 08e9bb77..cbda5c8d 100644 --- a/docs/fleet/PRD-fleet-suite.md +++ b/docs/fleet/PRD-fleet-suite.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # PRD — Mosaic Fleet Suite (init, configure, operate) > **Workstream:** W-FLEET (Fleet) under mission `mvp-20260312` · **Phase:** 3→4 productization diff --git a/docs/fleet/PRD.md b/docs/fleet/PRD.md index bfcaf37f..e559476b 100644 --- a/docs/fleet/PRD.md +++ b/docs/fleet/PRD.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # PRD — Fleet Phase 2: Operator Observability > **Workstream:** W-FLEET under `mvp-20260312` · **Phase:** 2 diff --git a/docs/fleet/concepts/desired-vs-observed-state.md b/docs/fleet/concepts/desired-vs-observed-state.md index 46a8f52d..0cbb6cae 100644 --- a/docs/fleet/concepts/desired-vs-observed-state.md +++ b/docs/fleet/concepts/desired-vs-observed-state.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Desired, Derived, and Observed Fleet State ## One writable authority diff --git a/docs/fleet/concepts/generated-env-launch-chain.md b/docs/fleet/concepts/generated-env-launch-chain.md index fc221b8f..b1d39cfd 100644 --- a/docs/fleet/concepts/generated-env-launch-chain.md +++ b/docs/fleet/concepts/generated-env-launch-chain.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Generated Environment Launch Chain The launcher consumes validated data, not shell configuration. diff --git a/docs/fleet/concepts/identity-class-runtime.md b/docs/fleet/concepts/identity-class-runtime.md index f94bfdf5..94af1ad5 100644 --- a/docs/fleet/concepts/identity-class-runtime.md +++ b/docs/fleet/concepts/identity-class-runtime.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Fleet Identity, Class, and Runtime Each roster field has one job. Do not use names or model strings as authority shortcuts. diff --git a/docs/fleet/concepts/role-authority-and-leases.md b/docs/fleet/concepts/role-authority-and-leases.md index 8551e009..b87614fa 100644 --- a/docs/fleet/concepts/role-authority-and-leases.md +++ b/docs/fleet/concepts/role-authority-and-leases.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Fleet Role Authority and Leases Role content describes behavior; protected authority is immutable code metadata derived only from the canonical class. diff --git a/docs/fleet/how-to/configure-tess-interaction.md b/docs/fleet/how-to/configure-tess-interaction.md index 4e2969f5..28ad8f43 100644 --- a/docs/fleet/how-to/configure-tess-interaction.md +++ b/docs/fleet/how-to/configure-tess-interaction.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Configure an Interaction Instance An interaction instance is a configurable local roster member with canonical class: interaction and matching tool_policy: interaction. “Tess” may be used as a display alias, but neither that alias nor the stable name is required or authority-bearing. diff --git a/docs/fleet/how-to/configure-ultron-validator.md b/docs/fleet/how-to/configure-ultron-validator.md index 8704e5e4..6a5beba2 100644 --- a/docs/fleet/how-to/configure-ultron-validator.md +++ b/docs/fleet/how-to/configure-ultron-validator.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Configure a Validator Instance A validator instance is a configurable local roster member with canonical class: validator and matching tool_policy: validator. “Ultron” may be used as a display alias, but it is not a required identity, class alias, product name, or source of authority. diff --git a/docs/fleet/how-to/create-update-delete-agent.md b/docs/fleet/how-to/create-update-delete-agent.md index 2591efdb..e3b2f004 100644 --- a/docs/fleet/how-to/create-update-delete-agent.md +++ b/docs/fleet/how-to/create-update-delete-agent.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Create, Inspect, Update, and Delete a Local Fleet Agent Use the local roster-v2 control plane only. These commands change desired state and derived environment projections; they never start, stop, reconcile, inspect, or otherwise act on systemd, tmux, sessions, or runtimes. diff --git a/docs/fleet/how-to/customize-roles.md b/docs/fleet/how-to/customize-roles.md index 646725b6..d4d0030e 100644 --- a/docs/fleet/how-to/customize-roles.md +++ b/docs/fleet/how-to/customize-roles.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Customize Fleet Roles Mosaic resolves persona contracts through two layers: diff --git a/docs/fleet/how-to/start-stop-restart.md b/docs/fleet/how-to/start-stop-restart.md index 8707ad84..7518d7d9 100644 --- a/docs/fleet/how-to/start-stop-restart.md +++ b/docs/fleet/how-to/start-stop-restart.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Safely Reconcile and Control a Local Fleet Agent Use the canonical local roster-v2 command surface: diff --git a/docs/fleet/migration/example-profile-disposition.md b/docs/fleet/migration/example-profile-disposition.md index c42b73f3..32b33607 100644 --- a/docs/fleet/migration/example-profile-disposition.md +++ b/docs/fleet/migration/example-profile-disposition.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Executable Fleet Example, Profile, and Service-Preset Dispositions **Issue:** #758 · **Card:** FCM-M1-003 · **Status:** M1 executable disposition evidence diff --git a/docs/fleet/migration/legacy-class-aliases.md b/docs/fleet/migration/legacy-class-aliases.md index be9bb3e2..b7913546 100644 --- a/docs/fleet/migration/legacy-class-aliases.md +++ b/docs/fleet/migration/legacy-class-aliases.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Legacy Fleet Class Aliases Fleet class compatibility is intentionally narrow. The shared resolver accepts exactly three legacy diff --git a/docs/fleet/migration/v1-to-v2.md b/docs/fleet/migration/v1-to-v2.md index 49b35295..aad9aa07 100644 --- a/docs/fleet/migration/v1-to-v2.md +++ b/docs/fleet/migration/v1-to-v2.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Previewing a Fleet Roster v1-to-v2 Migration **Issue:** #758 · **Card:** FCM-M4-001 · **Effect boundary:** preview only diff --git a/docs/fleet/operations/backup-restore.md b/docs/fleet/operations/backup-restore.md index 2bfd94f2..a3e01312 100644 --- a/docs/fleet/operations/backup-restore.md +++ b/docs/fleet/operations/backup-restore.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Fleet Configuration Backup and Restore Boundary **Issue:** #758 · **Card:** FCM-M4-001 diff --git a/docs/fleet/operations/env-quarantine.md b/docs/fleet/operations/env-quarantine.md index 8d08a5c5..49a89822 100644 --- a/docs/fleet/operations/env-quarantine.md +++ b/docs/fleet/operations/env-quarantine.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Environment Quarantine Operations Legacy .env is input evidence, never current launch authority. Projection preparation classifies it deterministically: diff --git a/docs/fleet/operations/reconcile-and-recover.md b/docs/fleet/operations/reconcile-and-recover.md index 0b0f7215..1280b021 100644 --- a/docs/fleet/operations/reconcile-and-recover.md +++ b/docs/fleet/operations/reconcile-and-recover.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Reconcile and Recover a Local Fleet ## Safe sequence diff --git a/docs/fleet/operations/systemd-tmux-troubleshooting.md b/docs/fleet/operations/systemd-tmux-troubleshooting.md index 988217fc..db84b854 100644 --- a/docs/fleet/operations/systemd-tmux-troubleshooting.md +++ b/docs/fleet/operations/systemd-tmux-troubleshooting.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Systemd and tmux Troubleshooting Start with read-only mosaic fleet status, `doctor`, and `verify`. Do not manually adopt, rename, terminate, or recreate sessions while ownership is ambiguous. diff --git a/docs/fleet/operations/upgrade-assets.md b/docs/fleet/operations/upgrade-assets.md index aeb9e848..43795d62 100644 --- a/docs/fleet/operations/upgrade-assets.md +++ b/docs/fleet/operations/upgrade-assets.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Upgrade and Installed-Asset Drift Fleet source assets and installed assets can differ after an update, but FCM-M5-001 does not add a trustworthy source-versus-installed revision detector or refresh command. Do not infer freshness from checkout presence, timestamps, generated environment files, running sessions, or a ready migration preview. diff --git a/docs/fleet/reference/agent-mutations.md b/docs/fleet/reference/agent-mutations.md index 1d59e9f5..22c763a6 100644 --- a/docs/fleet/reference/agent-mutations.md +++ b/docs/fleet/reference/agent-mutations.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Local Fleet Agent Mutations FCM-M2-002 provides local roster-v2 create, get, update, delete, and plan operations. They only change desired state and derived environment projections. They never start, stop, inspect, reconcile, or otherwise act on runtimes, systemd units, tmux sessions, or heartbeats. diff --git a/docs/fleet/reference/cli.md b/docs/fleet/reference/cli.md index 4d12599f..9aff7b1a 100644 --- a/docs/fleet/reference/cli.md +++ b/docs/fleet/reference/cli.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Fleet Control-Plane CLI The local desired-state surface is mosaic fleet. It is distinct from the gateway-backed mosaic agent catalog and from legacy compatibility commands that act on roster v1. diff --git a/docs/fleet/reference/generated-env-boundary.md b/docs/fleet/reference/generated-env-boundary.md index 7d97e39b..bd40ffe7 100644 --- a/docs/fleet/reference/generated-env-boundary.md +++ b/docs/fleet/reference/generated-env-boundary.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Fleet Generated Environment Boundary **Card:** FCM-M2-001 · **Issue:** #758 · **Status:** merged contract diff --git a/docs/fleet/reference/lifecycle-transitions.md b/docs/fleet/reference/lifecycle-transitions.md index b5eb36e1..3aacc90f 100644 --- a/docs/fleet/reference/lifecycle-transitions.md +++ b/docs/fleet/reference/lifecycle-transitions.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Local Fleet Lifecycle Transitions Roster-v2 `lifecycle.enabled` and `lifecycle.desired_state` are the only persisted lifecycle authority. Systemd, tmux, generated environment, and heartbeat state are derived or observed. diff --git a/docs/fleet/reference/role-classes.md b/docs/fleet/reference/role-classes.md index dd146e78..1ace93d2 100644 --- a/docs/fleet/reference/role-classes.md +++ b/docs/fleet/reference/role-classes.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Fleet Role Classes and Authority A fleet role class is a machine identity resolved from the persona library. Resolution uses the diff --git a/docs/fleet/reference/roster-v2-fields.md b/docs/fleet/reference/roster-v2-fields.md index 613be1de..2e39661e 100644 --- a/docs/fleet/reference/roster-v2-fields.md +++ b/docs/fleet/reference/roster-v2-fields.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Fleet Roster v2 Structural Contract **Status:** FCM-M1-001 local-tmux structural compiler contract. This document describes parsing, diff --git a/docs/fleet/reference/status-and-drift.md b/docs/fleet/reference/status-and-drift.md index dcb3d99f..41e1882c 100644 --- a/docs/fleet/reference/status-and-drift.md +++ b/docs/fleet/reference/status-and-drift.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Local Fleet Status and Drift mosaic fleet status [], `verify`, and `doctor` are observational roster-v2 commands. They emit one JSON result and do not write projections, mutate desired state, operate lifecycle, or change tmux. diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md index 12b45d16..02c74928 100644 --- a/docs/guides/deployment.md +++ b/docs/guides/deployment.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Deployment Guide > **Status: non-operative for PostgreSQL, federated, and bare-metal production.** The checked-in diff --git a/docs/guides/dev-guide.md b/docs/guides/dev-guide.md index c474e49f..09830639 100644 --- a/docs/guides/dev-guide.md +++ b/docs/guides/dev-guide.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Mosaic Stack — Developer Guide ## Table of Contents diff --git a/docs/guides/fleet-local-canary.md b/docs/guides/fleet-local-canary.md index b4542336..bff3a2f2 100644 --- a/docs/guides/fleet-local-canary.md +++ b/docs/guides/fleet-local-canary.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Local Fleet Canary The local fleet canary runs a small tmux-backed Mosaic agent fleet on an diff --git a/docs/guides/migrate-tier.md b/docs/guides/migrate-tier.md index bc9516ac..0abc470b 100644 --- a/docs/guides/migrate-tier.md +++ b/docs/guides/migrate-tier.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Migrating to the Federated Tier > **KBN-101-07 ownership:** This active documentation is a **non-operative KBN-101 diff --git a/docs/native-kanban-sot/MISSION-MANIFEST.md b/docs/native-kanban-sot/MISSION-MANIFEST.md index a439b4ce..3c5cc8cf 100644 --- a/docs/native-kanban-sot/MISSION-MANIFEST.md +++ b/docs/native-kanban-sot/MISSION-MANIFEST.md @@ -1,3 +1,8 @@ +--- +kind: tracking +status: active +--- + # Mission Manifest — Mosaic Native Kanban and Canonical Task SOT P0–P3 **Mission status:** CANON INDEPENDENTLY APPROVED; publication in progress under issue [#751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751) diff --git a/docs/plans/2026-08-10-ci-queue-purpose-design.md b/docs/plans/2026-08-10-ci-queue-purpose-design.md index ce56c668..9127e6a1 100644 --- a/docs/plans/2026-08-10-ci-queue-purpose-design.md +++ b/docs/plans/2026-08-10-ci-queue-purpose-design.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # CI Queue Guard Purpose Semantics - **Issue:** #1146 diff --git a/docs/plans/2026-08-10-ci-queue-purpose-implementation.md b/docs/plans/2026-08-10-ci-queue-purpose-implementation.md index b46d0671..864d2170 100644 --- a/docs/plans/2026-08-10-ci-queue-purpose-implementation.md +++ b/docs/plans/2026-08-10-ci-queue-purpose-implementation.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # CI Queue Guard Purpose Semantics Implementation Plan > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. diff --git a/docs/plans/2026-08-10-docs-catalog-audit.md b/docs/plans/2026-08-10-docs-catalog-audit.md index bd696593..d0289e9f 100644 --- a/docs/plans/2026-08-10-docs-catalog-audit.md +++ b/docs/plans/2026-08-10-docs-catalog-audit.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # Documentation Catalog and Truth Audit Plan **Task:** DOCS-IA-002 diff --git a/docs/plans/2026-08-10-docs-information-architecture-design.md b/docs/plans/2026-08-10-docs-information-architecture-design.md index a4c06410..0bd23f59 100644 --- a/docs/plans/2026-08-10-docs-information-architecture-design.md +++ b/docs/plans/2026-08-10-docs-information-architecture-design.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # Documentation Information Architecture Design **Status:** Approved diff --git a/docs/plans/2026-08-10-docs-structure-readme.md b/docs/plans/2026-08-10-docs-structure-readme.md index 5eeac3c4..f03de32f 100644 --- a/docs/plans/2026-08-10-docs-structure-readme.md +++ b/docs/plans/2026-08-10-docs-structure-readme.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # Documentation Structure README Implementation Plan > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. diff --git a/docs/plans/README.md b/docs/plans/README.md index 2036d527..28d9056d 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Documentation Plans > **Status:** Current artifact index. Plans record approved intent and execution approach; they are not current product behavior or operational authority. diff --git a/docs/release-integrity/TASKS.md b/docs/release-integrity/TASKS.md index a77c7350..79f2ae45 100644 --- a/docs/release-integrity/TASKS.md +++ b/docs/release-integrity/TASKS.md @@ -1,3 +1,8 @@ +--- +kind: tracking +status: active +--- + # Tasks — Release Integrity Workstream (RI-050, #1275) > Single-writer: the RI-050 orchestrator (jarvis, dragon-lin) only. Workers read but never modify. diff --git a/docs/reports/README.md b/docs/reports/README.md index 22c048c6..9818f664 100644 --- a/docs/reports/README.md +++ b/docs/reports/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Documentation Reports > **Status:** Current evidence index. Reports record reviews, tests, audits, and deferred findings; they are not requirements or operational instructions by themselves. diff --git a/docs/reports/code-review/756-code-review.md b/docs/reports/code-review/756-code-review.md index fb8fd184..a214927d 100644 --- a/docs/reports/code-review/756-code-review.md +++ b/docs/reports/code-review/756-code-review.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Independent Code Review — #756 Official Discord Channel Plugin **Verdict: APPROVE** diff --git a/docs/reports/code-review/gateway-security-20260313.md b/docs/reports/code-review/gateway-security-20260313.md index 4a8f161c..cf5684a1 100644 --- a/docs/reports/code-review/gateway-security-20260313.md +++ b/docs/reports/code-review/gateway-security-20260313.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Code Review Report — Gateway Security Hardening ## Scope Reviewed diff --git a/docs/reports/compaction-refresh/830-documentation-checklist.md b/docs/reports/compaction-refresh/830-documentation-checklist.md index 83add361..f65b850b 100644 --- a/docs/reports/compaction-refresh/830-documentation-checklist.md +++ b/docs/reports/compaction-refresh/830-documentation-checklist.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #830 Documentation Completion Checklist ## Required artifacts diff --git a/docs/reports/deferred/758-fleet-config-deferrals.md b/docs/reports/deferred/758-fleet-config-deferrals.md index f753a7e5..9d1fd9a4 100644 --- a/docs/reports/deferred/758-fleet-config-deferrals.md +++ b/docs/reports/deferred/758-fleet-config-deferrals.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # FCM-M5-001 Fleet Documentation Deferrals and Holds **Issue:** #758 · **Branch:** `docs/758-fleet-config-operator-docs` diff --git a/docs/reports/documentation/2026-08-10-docs-catalog-audit.md b/docs/reports/documentation/2026-08-10-docs-catalog-audit.md index 0e6f7af2..c8537ee2 100644 --- a/docs/reports/documentation/2026-08-10-docs-catalog-audit.md +++ b/docs/reports/documentation/2026-08-10-docs-catalog-audit.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Mosaic Stack Documentation Catalog and Truth Audit > **Status:** First-pass static audit — 2026-08-10 diff --git a/docs/reports/documentation/756-discord-plugin-checklist.md b/docs/reports/documentation/756-discord-plugin-checklist.md index 4fae2032..151f92eb 100644 --- a/docs/reports/documentation/756-discord-plugin-checklist.md +++ b/docs/reports/documentation/756-discord-plugin-checklist.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Documentation Completion Checklist — #756 Official Discord plugin ## Required artifacts diff --git a/docs/reports/documentation/758-fleet-config-ia-closure.md b/docs/reports/documentation/758-fleet-config-ia-closure.md index 25223408..50f568ff 100644 --- a/docs/reports/documentation/758-fleet-config-ia-closure.md +++ b/docs/reports/documentation/758-fleet-config-ia-closure.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # FCM-M5-001 Fleet Documentation IA Closure Evidence **Issue:** #758 · **Task:** FCM-M5-001 diff --git a/docs/reports/documentation/AUDIT-2026-02-17-framework-consistency.md b/docs/reports/documentation/AUDIT-2026-02-17-framework-consistency.md index 90e108a2..43b3d4b2 100644 --- a/docs/reports/documentation/AUDIT-2026-02-17-framework-consistency.md +++ b/docs/reports/documentation/AUDIT-2026-02-17-framework-consistency.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Mosaic Framework Consistency Audit Date: 2026-02-17 diff --git a/docs/reports/native-kanban-sot/canon-final-rereview-go.md b/docs/reports/native-kanban-sot/canon-final-rereview-go.md index f48b42e4..43002f2e 100644 --- a/docs/reports/native-kanban-sot/canon-final-rereview-go.md +++ b/docs/reports/native-kanban-sot/canon-final-rereview-go.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + VERDICT: GO # Native Kanban/SOT canon independent re-review 2 diff --git a/docs/reports/native-kanban-sot/canon-initial-review-no-go.md b/docs/reports/native-kanban-sot/canon-initial-review-no-go.md index 6a453587..52ca76fc 100644 --- a/docs/reports/native-kanban-sot/canon-initial-review-no-go.md +++ b/docs/reports/native-kanban-sot/canon-initial-review-no-go.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Independent Review — Native Kanban/SOT Canon **Reviewer:** `enhance-sol` (independent of author `planner-sol`) diff --git a/docs/reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md b/docs/reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md index fb24e03f..2bb2208a 100644 --- a/docs/reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md +++ b/docs/reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # KBN-101 contract independent security/architecture review **Verdict: REQUEST CHANGES** diff --git a/docs/reports/native-kanban-sot/ultron-final-go.md b/docs/reports/native-kanban-sot/ultron-final-go.md index 92604f7c..9f55755d 100644 --- a/docs/reports/native-kanban-sot/ultron-final-go.md +++ b/docs/reports/native-kanban-sot/ultron-final-go.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #751 Native Kanban/SOT canonical publication — Ultron final gate **Verdict: GO** — zero BLOCKER/HIGH findings. diff --git a/docs/reports/qa/gateway-security-20260313.md b/docs/reports/qa/gateway-security-20260313.md index b1365b16..5c15efc9 100644 --- a/docs/reports/qa/gateway-security-20260313.md +++ b/docs/reports/qa/gateway-security-20260313.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # QA Report — Gateway Security Hardening ## Scope diff --git a/docs/reports/qa/p8-003-performance-optimization.md b/docs/reports/qa/p8-003-performance-optimization.md index c1703e70..077e5cc4 100644 --- a/docs/reports/qa/p8-003-performance-optimization.md +++ b/docs/reports/qa/p8-003-performance-optimization.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Performance Optimization — P8-003 **Branch:** `feat/p8-003-performance` diff --git a/docs/reports/quality/1099-pipefail-sweep.md b/docs/reports/quality/1099-pipefail-sweep.md index ff961908..3f00f6fe 100644 --- a/docs/reports/quality/1099-pipefail-sweep.md +++ b/docs/reports/quality/1099-pipefail-sweep.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1099 pipefail + early-exit sweep Baseline: `df4c591ab42aa1ae62c12935fdc0e772684864a0` diff --git a/docs/reports/security/756-security-review.md b/docs/reports/security/756-security-review.md index dbd086a7..96a60281 100644 --- a/docs/reports/security/756-security-review.md +++ b/docs/reports/security/756-security-review.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Security Review — Issue #756 **Scope:** final current uncommitted Discord plugin, shared channel contract, gateway ingress, AgentService, and plugin registration delta diff --git a/docs/scratchpads/1019-zero-timeout-harness.md b/docs/scratchpads/1019-zero-timeout-harness.md index 51706d73..8bf0f21f 100644 --- a/docs/scratchpads/1019-zero-timeout-harness.md +++ b/docs/scratchpads/1019-zero-timeout-harness.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1019 — Zero-timeout queue-guard harness race - **Issue:** #1019 (parent status remains `believed-fixed, pending jarvis validation`; do not close) diff --git a/docs/scratchpads/1043-pane-git-identity.md b/docs/scratchpads/1043-pane-git-identity.md index 8e54df07..7d41f10b 100644 --- a/docs/scratchpads/1043-pane-git-identity.md +++ b/docs/scratchpads/1043-pane-git-identity.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1043 — Fleet pane git-identity propagation ## Objective diff --git a/docs/scratchpads/1098-framework-shell-portability.md b/docs/scratchpads/1098-framework-shell-portability.md index 285a6926..260f7100 100644 --- a/docs/scratchpads/1098-framework-shell-portability.md +++ b/docs/scratchpads/1098-framework-shell-portability.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1098 — Framework shell portability / red main ## Objective diff --git a/docs/scratchpads/1099-pipefail-sweep.md b/docs/scratchpads/1099-pipefail-sweep.md index e8040d77..f8ade5b1 100644 --- a/docs/scratchpads/1099-pipefail-sweep.md +++ b/docs/scratchpads/1099-pipefail-sweep.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1099 — pipefail + early-exit sweep ## Scope and decisions diff --git a/docs/scratchpads/1146-ci-queue-purpose.md b/docs/scratchpads/1146-ci-queue-purpose.md index e9402d6f..cf030a78 100644 --- a/docs/scratchpads/1146-ci-queue-purpose.md +++ b/docs/scratchpads/1146-ci-queue-purpose.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1146 — CI Queue Guard Purpose Semantics ## Objective diff --git a/docs/scratchpads/1150-pi-goal-extension.md b/docs/scratchpads/1150-pi-goal-extension.md index e9fe8eae..a399f557 100644 --- a/docs/scratchpads/1150-pi-goal-extension.md +++ b/docs/scratchpads/1150-pi-goal-extension.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1150 — Pi persistent goal extension - **Task ID:** ISSUE-1150 (no `docs/TASKS.md` row; that file is orchestrator-only) diff --git a/docs/scratchpads/1174-wrapper-guard-round10.md b/docs/scratchpads/1174-wrapper-guard-round10.md index 3629652f..6af0d688 100644 --- a/docs/scratchpads/1174-wrapper-guard-round10.md +++ b/docs/scratchpads/1174-wrapper-guard-round10.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1174 — Wrapper guard rounds 10–11 ## Objective diff --git a/docs/scratchpads/1179-required-security-di.md b/docs/scratchpads/1179-required-security-di.md index c7719d39..df6a83cc 100644 --- a/docs/scratchpads/1179-required-security-di.md +++ b/docs/scratchpads/1179-required-security-di.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1179 — Required security DI wiring ## Objective diff --git a/docs/scratchpads/1194-framework-tool-drift.md b/docs/scratchpads/1194-framework-tool-drift.md index 469a9d53..00a5ab68 100644 --- a/docs/scratchpads/1194-framework-tool-drift.md +++ b/docs/scratchpads/1194-framework-tool-drift.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # #1194 — Installed framework-tool drift detection and refresh analysis ## Decision diff --git a/docs/scratchpads/DOCS-IA-001.md b/docs/scratchpads/DOCS-IA-001.md index 97b34ebc..f143a01f 100644 --- a/docs/scratchpads/DOCS-IA-001.md +++ b/docs/scratchpads/DOCS-IA-001.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # DOCS-IA-001 — Documentation Information Architecture - **Task:** DOCS-IA-001 diff --git a/docs/scratchpads/DOCS-IA-002-catalog-audit.md b/docs/scratchpads/DOCS-IA-002-catalog-audit.md index 75b8dfac..38046b50 100644 --- a/docs/scratchpads/DOCS-IA-002-catalog-audit.md +++ b/docs/scratchpads/DOCS-IA-002-catalog-audit.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # DOCS-IA-002 — Documentation Catalog and Truth Audit - **Task:** DOCS-IA-002 diff --git a/docs/scratchpads/README.md b/docs/scratchpads/README.md index 67586383..9aa6fae0 100644 --- a/docs/scratchpads/README.md +++ b/docs/scratchpads/README.md @@ -1,3 +1,8 @@ +--- +kind: guide +status: active +--- + # Documentation Scratchpads > **Status:** Current artifact index. Scratchpads are working memory and verification records, not product requirements or command authority. diff --git a/docs/scratchpads/lease-remediation/dispatch/measure-W-B.md b/docs/scratchpads/lease-remediation/dispatch/measure-W-B.md index 1c572b52..589ede03 100644 --- a/docs/scratchpads/lease-remediation/dispatch/measure-W-B.md +++ b/docs/scratchpads/lease-remediation/dispatch/measure-W-B.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # W-B — Measure Pi's real tool registry - **Task / internal ref:** W-B from the lease-remediation orchestrator brief (no matching `docs/TASKS.md` row; workers do not modify that file) diff --git a/docs/scratchpads/mvp-20260312.md b/docs/scratchpads/mvp-20260312.md index 9e875501..16baad45 100644 --- a/docs/scratchpads/mvp-20260312.md +++ b/docs/scratchpads/mvp-20260312.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Mission Scratchpad — MVP > Append-only log. NEVER delete entries. NEVER overwrite sections. diff --git a/docs/scratchpads/pr-merge-message-field.md b/docs/scratchpads/pr-merge-message-field.md index b86112c5..077740e5 100644 --- a/docs/scratchpads/pr-merge-message-field.md +++ b/docs/scratchpads/pr-merge-message-field.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # PR merge squash message field - **Charter:** `/home/hermes/agent-work/CHARTER-PRMERGE-MESSAGE-FIELD.md` diff --git a/docs/scratchpads/ri-050.md b/docs/scratchpads/ri-050.md index 65196476..5d18318a 100644 --- a/docs/scratchpads/ri-050.md +++ b/docs/scratchpads/ri-050.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # Scratchpad — RI-050 orchestrator (jarvis, dragon-lin) Mission: alpha 0.0.50 release-integrity floor. Issue #1275. Base `next` @ 476db12b. diff --git a/docs/scratchpads/webui-p3r1-routing-mcp.md b/docs/scratchpads/webui-p3r1-routing-mcp.md index 0109e64c..daa780d0 100644 --- a/docs/scratchpads/webui-p3r1-routing-mcp.md +++ b/docs/scratchpads/webui-p3r1-routing-mcp.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # P3-R1 — Routing Health Enum + `/mcp` Wiring Scratchpad **Task:** P3 hands-on acceptance blockers #1 and #5 diff --git a/docs/scratchpads/webui-p4-1.md b/docs/scratchpads/webui-p4-1.md index 721e9fa9..e329ace6 100644 --- a/docs/scratchpads/webui-p4-1.md +++ b/docs/scratchpads/webui-p4-1.md @@ -1,3 +1,8 @@ +--- +kind: record +status: active +--- + # WebUI Phase P — P4-1 Projects + Tasks SPA Scratchpad **Task ID:** P4-1 diff --git a/docs/tess/MISSION-MANIFEST.md b/docs/tess/MISSION-MANIFEST.md index 5c3effe7..a5723a27 100644 --- a/docs/tess/MISSION-MANIFEST.md +++ b/docs/tess/MISSION-MANIFEST.md @@ -1,3 +1,8 @@ +--- +kind: tracking +status: active +--- + # Mission Manifest — Tess Interaction Agent ## Mission diff --git a/docs/tess/TASKS.md b/docs/tess/TASKS.md index 970529e0..00759b79 100644 --- a/docs/tess/TASKS.md +++ b/docs/tess/TASKS.md @@ -1,3 +1,8 @@ +--- +kind: tracking +status: active +--- + # Tasks — Tess Interaction Agent > Mission: `tess-20260712` · Issue: #706 · PRD requirements: `TESS-*` -- 2.54.0 From 37cd00e60d040a20089d6f7433b99086ca72a737 Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 19:31:25 -0500 Subject: [PATCH 02/10] docs(W4): operator worklist for the 19 held rows, plus two contract conflicts Records what the stamping pass applied, what it held and why, and the two places where the contract contradicts itself or the repository: - docs/native-kanban-sot/TASKS.md declares itself a build plan; the contract says TASKS.md is tracking and never a spec. - docs/requirements/native-kanban-sot.md is hand-authored prose canon; plan section 5.2 calls that source-of-truth, the contract table requires source-of-truth to be machine-readable. - docs/README.md already documents a competing front-matter convention on a colliding status key, applied to 4 files, with no code consumer. - The contract has no defined form for a .yaml document, including docs/fleet/NORTH_STAR.yaml itself. --- ...026-08-20_w4-document-contract-worklist.md | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/plans/2026-08-20_w4-document-contract-worklist.md diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md new file mode 100644 index 00000000..eb34f746 --- /dev/null +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -0,0 +1,152 @@ +--- +kind: tracking +status: active +--- + +# W4 — document contract worklist + +Companion to `2026-08-20_stack-docs-flatten-and-alignment.md`. That document proposes the +contract; this one records what was applied, what was held, and what still needs a decision. + +Measured on `origin/next` at `63069149`. Author: veronica. Review: fred (Gate-16, author is +not reviewer), then a pi seat for the adversarial pass. + +## What "live" means here + +All `*.md` under `docs/`, minus `docs/archive/`, minus `docs/_old_structure/`. That is **127** +files. The flatten plan says 130; the arithmetic does not close (318 total = 134 archive + +57 `_old_structure` + 127 live, not 130). + +## Applied + +| bucket | count | note | +| --- | --- | --- | +| stamped `kind` + `status: active` | 104 | this pass | +| held, operator judgement | 19 | section "Needs a decision" below | +| held, cites the moving path | 3 | the three `SUPERSEDED` TASKS.md stamps | +| already stamped in W1 | 1 | `docs/fleet/FLEET-DOCTRINE.md`, untouched | + +Kinds applied: 54 `guide`, 34 `record`, 9 `spec`, 6 `tracking`, 1 `projection`. + +`parent` is **not** applied. It points at `docs/fleet/NORTH_STAR.yaml`, which the flatten moves +to `docs/NORTH_STAR.yaml`. Stamping it now means re-pointing 127 files by hand later. It lands +after the move, in one pass, with the post-move path. + +## Held: the three superseded stamps + +`docs/TASKS.md:5`, `docs/federation/TASKS.md:5`, and `docs/fleet/TASKS.md:5` each carry a W1 +stamp of the form: + +> **STATUS: SUPERSEDED — 2026-08-20.** kind `tracking` · superseded by `docs/fleet/NORTH_STAR.yaml` + +Two problems, both real: + +1. **The tooling cannot read them.** That line is a blockquote below the H1, not YAML front + matter. Plan section 6 check 5 ("every live document has a header; no document is + unclassified") parses front matter, so all three read as unclassified. The control that the + parse itself works is `docs/fleet/FLEET-DOCTRINE.md:3`, which is genuine front matter. +2. **They cite the moving path.** Three of the six citations of `docs/fleet/NORTH_STAR.yaml` + are these stamps. Converting them before the flatten lands makes them stale on merge. + +Converted after the flatten, not before. + +## Needs a decision + +Nineteen rows. Seventeen are the plan's section 9 list, minus `docs/fleet/north-star.md` +(renamed to `FLEET-DOCTRINE.md` by W1, so the row is closed) and minus the two `.yaml` rows, +which are a different problem — see the next section. Two rows are new, found while +classifying. + +Fill the `kind` column with a value from the contract, or `superseded-by: `. + +| path | proposed | why it is not mechanical | +| --- | --- | --- | +| `docs/README.md` | `guide` | It also **prescribes** the competing front-matter convention (see below). Whatever kind it gets, its body needs an edit. | +| `docs/SITEMAP.md` | `guide` or `projection` | If it is generated from the tree it is a projection and needs a drift test. If hand-maintained it is a guide that goes stale silently. Nobody has said which. | +| `docs/federation/SETUP.md` | `guide` | Reads as a guide. Federation tier status is the open part: if the tier is shelved this is `superseded`. | +| `docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md` | `record` | An acceptance checklist is evidence of a past gate, which is `record`. But if it is still being checked against, it is `tracking`. | +| `docs/fleet/FLEET-LAUNCH.md` | `guide` | Runbook. Depends on whether `launch-seat.sh` is deprecated in favour of `mosaic fleet` (campaign W3). If so, `superseded`. | +| `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` | `record` | An inventory of dispositions taken. `record` unless dispositions are still pending, which the title implies they were once. | +| `docs/fleet/README.md` | `guide` | Section index. Low risk; listed only because the plan lists it. | +| `docs/fleet/backlog-conventions.md` | `guide` | Conventions decide things, and `guide` explicitly decides nothing. May be `spec`. | +| `docs/fleet/f4-matrix-connector.md` | `spec` | F4 is a workstream. Whether it is live or abandoned decides `spec` versus `superseded`. | +| `docs/native-kanban-sot/DOCUMENTATION-CHECKLIST.md` | `record` | Same question as the fleet IA checklist. | +| `docs/native-kanban-sot/INDEX.md` | `guide` | Index of the canon. If it is generated from the canon it is a projection. | +| `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` | `spec` | 415 lines of normative gate. `spec` fits; confirm it is not superseded by the shared contract. | +| `docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` | `spec` | As above. | +| `docs/native-kanban-sot/KBN-101-ENVELOPE-A.md` | `spec` | Title says "v6, FINAL". If v6 supersedes v1-v5 elsewhere, those need `superseded-by` pointing here. | +| `docs/native-kanban-sot/SHARED-CONTRACT.md` | `spec` | "Remediated Shared Contract v1". Same versioning question. | +| `docs/release-integrity/probe-inventory.md` | `record` | An inventory. `tracking` if probes are still being added to it. | +| `docs/webui/PHASE-P-STRUCTURE.md` | `spec` | Zero inbound references (plan section 5.4). Either wire it in or mark it superseded; the kind is the smaller question. | +| `docs/native-kanban-sot/TASKS.md` | **conflict** | The file says of itself: "This file is a build plan, not a task tracker, and is NOT superseded." The contract says `tracking` is "live state, single-writer (manifests, `TASKS.md`). **Never a spec**." The file claims to be the thing its name forbids. Either the file is wrong or the contract's `TASKS.md` shorthand is. | +| `docs/requirements/native-kanban-sot.md` | **conflict** | Plan section 5.2 says if it is hand-authored canon it is `source-of-truth`. The contract's own table says `source-of-truth` is **machine-readable**. This is prose markdown with normative MUST/MUST NOT, RATIFIED 2026-07-14, decision owner Jason. It cannot satisfy both rules. Either it is a `spec` or the machine-readable criterion is wrong. | + +The last two are not slow rows, they are contradictions inside the contract. They want an +answer about the contract, not about the file. + +## The contract collides with an existing one + +`docs/README.md` lines 150-160 already document a front-matter convention, with its own +allowed values: + +```yaml +--- +title: Human-readable page title +type: guide # guide | concept | reference | decision | rfc | runbook +audience: developer # user | admin | developer | all +status: current # current | draft | deprecated | historical +source_of_truth: false +--- +``` + +Adoption is 4 of 127 files: `docs/ADMIN-GUIDE/security/sso-providers.md`, +`docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md`, +`docs/USER-GUIDE/getting-started/quickstart.md`, `docs/USER-GUIDE/product/web-dashboard.md`. + +`status` is in both schemas with **disjoint vocabularies**. `type` and `kind` are two names for +one idea with different value sets. `source_of_truth: false` is a boolean spelling of +`kind: source-of-truth`. + +What this pass did, and it is a decision someone should ratify or reverse: the new contract +wins. Those 4 files had `status: current` rewritten to `status: active` and gained `kind:`. +Their `title`, `type`, `audience` and `source_of_truth` keys were left alone. Nothing reads any +of them — `git grep source_of_truth` outside `docs/` returns zero hits — so no consumer broke. + +`docs/README.md` still prescribes the old convention. It is an operator row above, so this pass +did not edit it. Until it is edited, the repository documents two conflicting header +conventions and points authors at the one being retired. + +## The contract has no form for a YAML document + +Two of the plan's 20 rows are not markdown: `docs/fleet/examples/roster-v2.yaml` and +`docs/openapi-tess.yaml`. Front matter is a markdown convention. A `.yaml` file can carry a +leading `---` document, but then it is two YAML documents and every existing parser of that +file sees a change. + +This is not an edge case. It applies to **`docs/fleet/NORTH_STAR.yaml`, the source of truth +itself**, which is the one file the contract most needs to classify. Section 6 check 5 says no +document is unclassified. As written, the source of truth cannot comply. + +Options, none of them chosen here: exclude `.yaml` from the contract and say so; carry their +metadata in a sidecar; or add a top-level `kind:` key inside the YAML body rather than as front +matter, which for `NORTH_STAR.yaml` is a schema change. + +## Method, and what it cannot tell you + +Classification is per-file, by title and path, recorded with a confidence. It is not a regex +sweep. The plan's own warning stands and is why the 19 rows above are held rather than guessed: +the first classifier pass classed a RATIFIED requirements document as a projection. + +Rows marked `med` in the working manifest and not listed above: the five `docs/plans/*` specs, +`docs/fleet/migration/example-profile-disposition.md`, the one ADR +(`decisions/mos-runtime-portability-m1.md`, called `record` because an ADR records a decision +taken), and the one RFC (`rfcs/optional-ai-egress-gateways.md`, called `spec` because it +proposes work not yet built). Those eight are stamped and are the most likely to be wrong. + +## Verification + +- 104 of 104 files parse with the expected `kind` and `status` in front matter. +- The check was shown to reject a wrong kind before it was trusted (asserting + `kind: record` on a file stamped `guide` fails). +- The whole diff removes 4 lines, all of them `status: current`. +- 23 files untouched, matching 19 + 3 + 1. -- 2.54.0 From bea47543f3aeb3c139fff6c423a62b52d0f06482 Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 19:46:24 -0500 Subject: [PATCH 03/10] docs(W4): revert the NORTH_STAR.md stamp; a projection cannot carry a hand-added header Found by vision's adversarial pass (W5) and re-measured here. The finding was raised as latent; it is live in this PR. docs/fleet/NORTH_STAR.md is generated by renderNorthStarMarkdown() (packages/mosaic/src/commands/fleet.ts:373), whose first emitted line is the H1 and which emits no front matter at all. fleet-north-star.spec.ts:110-114 is a drift test that reads the committed file from disk and asserts full-string equality against the renderer output: expect(rendered).toBe(committed); Stamping the file changed line 1 from '# Mosaic Fleet - NORTH STAR' to '---', so the assertion fails. vitest could not be run in this worktree (node_modules empty, 'Cannot find package yaml'), which is a harness gap and not a test result, so this is shown by construction: the assertion above, the renderer's first lines.push, and line 1 before versus after. Reverted to origin/next verbatim: git diff origin/next -- docs/fleet/NORTH_STAR.md is 0 lines. Control on docs/fleet/reference/cli.md returns 13 lines, so the diff command does report differences when they exist. The header for a projection has to come from the renderer, not the file. That is a code change and belongs in the flatten PR beside the resolveNorthStarPaths() fix. Stamped count 104 -> 103. Untouched 23 -> 24. Worklist records it as a fourth held row. --- docs/fleet/NORTH_STAR.md | 5 --- ...026-08-20_w4-document-contract-worklist.md | 33 ++++++++++++++++--- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/fleet/NORTH_STAR.md b/docs/fleet/NORTH_STAR.md index 61ef4ce4..ba066838 100644 --- a/docs/fleet/NORTH_STAR.md +++ b/docs/fleet/NORTH_STAR.md @@ -1,8 +1,3 @@ ---- -kind: projection -status: active ---- - # Mosaic Fleet — NORTH STAR > **Generated file — do not edit by hand.** diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index eb34f746..d59b5e75 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -21,12 +21,13 @@ files. The flatten plan says 130; the arithmetic does not close (318 total = 134 | bucket | count | note | | --- | --- | --- | -| stamped `kind` + `status: active` | 104 | this pass | +| stamped `kind` + `status: active` | 103 | this pass | | held, operator judgement | 19 | section "Needs a decision" below | | held, cites the moving path | 3 | the three `SUPERSEDED` TASKS.md stamps | +| held, generated file | 1 | `docs/fleet/NORTH_STAR.md`, see below | | already stamped in W1 | 1 | `docs/fleet/FLEET-DOCTRINE.md`, untouched | -Kinds applied: 54 `guide`, 34 `record`, 9 `spec`, 6 `tracking`, 1 `projection`. +Kinds applied: 54 `guide`, 34 `record`, 9 `spec`, 6 `tracking`. `parent` is **not** applied. It points at `docs/fleet/NORTH_STAR.yaml`, which the flatten moves to `docs/NORTH_STAR.yaml`. Stamping it now means re-pointing 127 files by hand later. It lands @@ -50,6 +51,30 @@ Two problems, both real: Converted after the flatten, not before. +## Held: the one generated file + +`docs/fleet/NORTH_STAR.md` is a `projection` and was stamped in the first pass. The stamp was +**reverted before review**, because stamping it is self-contradictory in a way that is not +merely theoretical: + +- The contract says a `projection` is "Generated. Never hand-edited." Adding front matter by + hand is a hand edit of a generated file, and the file's own banner says + "**Generated file — do not edit by hand.**" +- `renderNorthStarMarkdown()` at `packages/mosaic/src/commands/fleet.ts:373` emits the H1 as + its first line and no front matter at all. +- `fleet-north-star.spec.ts:110-114` asserts full-string equality between the renderer's output + and the committed file: `expect(rendered).toBe(committed)`. Before the stamp, line 1 of the + committed file was `# Mosaic Fleet — NORTH STAR`, matching the renderer. After it, line 1 was + `---`. The assertion fails. + +So the header for a projection cannot live in the file. It has to be emitted by +`renderNorthStarMarkdown()`, which is a code change and belongs in the flatten PR alongside the +`resolveNorthStarPaths()` fix, not in a documentation pass. + +This generalises: **the contract as written cannot classify any generated document without a +matching change to its generator.** `NORTH_STAR.md` is the only projection today, so the cost +is one function. It will not stay one. + ## Needs a decision Nineteen rows. Seventeen are the plan's section 9 list, minus `docs/fleet/north-star.md` @@ -145,8 +170,8 @@ proposes work not yet built). Those eight are stamped and are the most likely to ## Verification -- 104 of 104 files parse with the expected `kind` and `status` in front matter. +- 103 of 103 files parse with the expected `kind` and `status` in front matter. - The check was shown to reject a wrong kind before it was trusted (asserting `kind: record` on a file stamped `guide` fails). - The whole diff removes 4 lines, all of them `status: current`. -- 23 files untouched, matching 19 + 3 + 1. +- 24 files untouched, matching 19 + 3 + 1 + 1. -- 2.54.0 From 8a55c041087f86eb75182c41960039b549661531 Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 19:48:07 -0500 Subject: [PATCH 04/10] docs(W4): prettier the worklist table padding CI 2589 step `format` failed on exactly one file: this one, the plan document I hand-wrote. prettier --check reproduces locally, rc=1, same single file. That is worth stating for the review: the other 103 stamped documents pass `prettier --check` unchanged, so the `---\nkind:\nstatus:\n---` front matter block is already prettier-clean. The formatting failure was in my prose, not in the contract header. Diff is 31 lines in, 31 out, all table column padding. No content change. --- ...026-08-20_w4-document-contract-worklist.md | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index d59b5e75..fd8c51ec 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -19,13 +19,13 @@ files. The flatten plan says 130; the arithmetic does not close (318 total = 134 ## Applied -| bucket | count | note | -| --- | --- | --- | -| stamped `kind` + `status: active` | 103 | this pass | -| held, operator judgement | 19 | section "Needs a decision" below | -| held, cites the moving path | 3 | the three `SUPERSEDED` TASKS.md stamps | -| held, generated file | 1 | `docs/fleet/NORTH_STAR.md`, see below | -| already stamped in W1 | 1 | `docs/fleet/FLEET-DOCTRINE.md`, untouched | +| bucket | count | note | +| --------------------------------- | ----- | ----------------------------------------- | +| stamped `kind` + `status: active` | 103 | this pass | +| held, operator judgement | 19 | section "Needs a decision" below | +| held, cites the moving path | 3 | the three `SUPERSEDED` TASKS.md stamps | +| held, generated file | 1 | `docs/fleet/NORTH_STAR.md`, see below | +| already stamped in W1 | 1 | `docs/fleet/FLEET-DOCTRINE.md`, untouched | Kinds applied: 54 `guide`, 34 `record`, 9 `spec`, 6 `tracking`. @@ -84,27 +84,27 @@ classifying. Fill the `kind` column with a value from the contract, or `superseded-by: `. -| path | proposed | why it is not mechanical | -| --- | --- | --- | -| `docs/README.md` | `guide` | It also **prescribes** the competing front-matter convention (see below). Whatever kind it gets, its body needs an edit. | -| `docs/SITEMAP.md` | `guide` or `projection` | If it is generated from the tree it is a projection and needs a drift test. If hand-maintained it is a guide that goes stale silently. Nobody has said which. | -| `docs/federation/SETUP.md` | `guide` | Reads as a guide. Federation tier status is the open part: if the tier is shelved this is `superseded`. | -| `docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md` | `record` | An acceptance checklist is evidence of a past gate, which is `record`. But if it is still being checked against, it is `tracking`. | -| `docs/fleet/FLEET-LAUNCH.md` | `guide` | Runbook. Depends on whether `launch-seat.sh` is deprecated in favour of `mosaic fleet` (campaign W3). If so, `superseded`. | -| `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` | `record` | An inventory of dispositions taken. `record` unless dispositions are still pending, which the title implies they were once. | -| `docs/fleet/README.md` | `guide` | Section index. Low risk; listed only because the plan lists it. | -| `docs/fleet/backlog-conventions.md` | `guide` | Conventions decide things, and `guide` explicitly decides nothing. May be `spec`. | -| `docs/fleet/f4-matrix-connector.md` | `spec` | F4 is a workstream. Whether it is live or abandoned decides `spec` versus `superseded`. | -| `docs/native-kanban-sot/DOCUMENTATION-CHECKLIST.md` | `record` | Same question as the fleet IA checklist. | -| `docs/native-kanban-sot/INDEX.md` | `guide` | Index of the canon. If it is generated from the canon it is a projection. | -| `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` | `spec` | 415 lines of normative gate. `spec` fits; confirm it is not superseded by the shared contract. | -| `docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` | `spec` | As above. | -| `docs/native-kanban-sot/KBN-101-ENVELOPE-A.md` | `spec` | Title says "v6, FINAL". If v6 supersedes v1-v5 elsewhere, those need `superseded-by` pointing here. | -| `docs/native-kanban-sot/SHARED-CONTRACT.md` | `spec` | "Remediated Shared Contract v1". Same versioning question. | -| `docs/release-integrity/probe-inventory.md` | `record` | An inventory. `tracking` if probes are still being added to it. | -| `docs/webui/PHASE-P-STRUCTURE.md` | `spec` | Zero inbound references (plan section 5.4). Either wire it in or mark it superseded; the kind is the smaller question. | -| `docs/native-kanban-sot/TASKS.md` | **conflict** | The file says of itself: "This file is a build plan, not a task tracker, and is NOT superseded." The contract says `tracking` is "live state, single-writer (manifests, `TASKS.md`). **Never a spec**." The file claims to be the thing its name forbids. Either the file is wrong or the contract's `TASKS.md` shorthand is. | -| `docs/requirements/native-kanban-sot.md` | **conflict** | Plan section 5.2 says if it is hand-authored canon it is `source-of-truth`. The contract's own table says `source-of-truth` is **machine-readable**. This is prose markdown with normative MUST/MUST NOT, RATIFIED 2026-07-14, decision owner Jason. It cannot satisfy both rules. Either it is a `spec` or the machine-readable criterion is wrong. | +| path | proposed | why it is not mechanical | +| --------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `docs/README.md` | `guide` | It also **prescribes** the competing front-matter convention (see below). Whatever kind it gets, its body needs an edit. | +| `docs/SITEMAP.md` | `guide` or `projection` | If it is generated from the tree it is a projection and needs a drift test. If hand-maintained it is a guide that goes stale silently. Nobody has said which. | +| `docs/federation/SETUP.md` | `guide` | Reads as a guide. Federation tier status is the open part: if the tier is shelved this is `superseded`. | +| `docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md` | `record` | An acceptance checklist is evidence of a past gate, which is `record`. But if it is still being checked against, it is `tracking`. | +| `docs/fleet/FLEET-LAUNCH.md` | `guide` | Runbook. Depends on whether `launch-seat.sh` is deprecated in favour of `mosaic fleet` (campaign W3). If so, `superseded`. | +| `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` | `record` | An inventory of dispositions taken. `record` unless dispositions are still pending, which the title implies they were once. | +| `docs/fleet/README.md` | `guide` | Section index. Low risk; listed only because the plan lists it. | +| `docs/fleet/backlog-conventions.md` | `guide` | Conventions decide things, and `guide` explicitly decides nothing. May be `spec`. | +| `docs/fleet/f4-matrix-connector.md` | `spec` | F4 is a workstream. Whether it is live or abandoned decides `spec` versus `superseded`. | +| `docs/native-kanban-sot/DOCUMENTATION-CHECKLIST.md` | `record` | Same question as the fleet IA checklist. | +| `docs/native-kanban-sot/INDEX.md` | `guide` | Index of the canon. If it is generated from the canon it is a projection. | +| `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` | `spec` | 415 lines of normative gate. `spec` fits; confirm it is not superseded by the shared contract. | +| `docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` | `spec` | As above. | +| `docs/native-kanban-sot/KBN-101-ENVELOPE-A.md` | `spec` | Title says "v6, FINAL". If v6 supersedes v1-v5 elsewhere, those need `superseded-by` pointing here. | +| `docs/native-kanban-sot/SHARED-CONTRACT.md` | `spec` | "Remediated Shared Contract v1". Same versioning question. | +| `docs/release-integrity/probe-inventory.md` | `record` | An inventory. `tracking` if probes are still being added to it. | +| `docs/webui/PHASE-P-STRUCTURE.md` | `spec` | Zero inbound references (plan section 5.4). Either wire it in or mark it superseded; the kind is the smaller question. | +| `docs/native-kanban-sot/TASKS.md` | **conflict** | The file says of itself: "This file is a build plan, not a task tracker, and is NOT superseded." The contract says `tracking` is "live state, single-writer (manifests, `TASKS.md`). **Never a spec**." The file claims to be the thing its name forbids. Either the file is wrong or the contract's `TASKS.md` shorthand is. | +| `docs/requirements/native-kanban-sot.md` | **conflict** | Plan section 5.2 says if it is hand-authored canon it is `source-of-truth`. The contract's own table says `source-of-truth` is **machine-readable**. This is prose markdown with normative MUST/MUST NOT, RATIFIED 2026-07-14, decision owner Jason. It cannot satisfy both rules. Either it is a `spec` or the machine-readable criterion is wrong. | The last two are not slow rows, they are contradictions inside the contract. They want an answer about the contract, not about the file. @@ -117,9 +117,9 @@ allowed values: ```yaml --- title: Human-readable page title -type: guide # guide | concept | reference | decision | rfc | runbook -audience: developer # user | admin | developer | all -status: current # current | draft | deprecated | historical +type: guide # guide | concept | reference | decision | rfc | runbook +audience: developer # user | admin | developer | all +status: current # current | draft | deprecated | historical source_of_truth: false --- ``` -- 2.54.0 From f6fbeaf57adad51b42e29acfac5304b9d88b0c37 Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 19:55:23 -0500 Subject: [PATCH 05/10] docs(W4): response to the W5 adversarial pass, in the diff rather than a PR comment pr-review.sh -n 1350 -a comment fails with HTTP 401 'invalid username, password or token'. Measured cause with a control: veronica's seat token returns 200 on /api/v1/user and the shared broker credential gitea-mosaicstack returns 401 on the same endpoint. The wrapper logic is fine, the credential it is handed is dead, so the PR wrappers are down for every seat on this host. MOSAIC_GIT_IDENTITY appears nowhere in credentials.sh, which is FD-9. Constitution gate 8 makes that operation blocked, so the corrections land in the branch instead, where they survive the PR anyway. --- ...026-08-20_w4-document-contract-worklist.md | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index fd8c51ec..fbf1c05a 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -175,3 +175,97 @@ proposes work not yet built). Those eight are stamped and are the most likely to `kind: record` on a file stamped `guide` fails). - The whole diff removes 4 lines, all of them `status: current`. - 24 files untouched, matching 19 + 3 + 1 + 1. + +## Response to the W5 adversarial pass + +vision ran a refute-first pass on this branch at `37cd00e` from a fresh worktree. Three of its +points changed the branch. Everything is re-measured here before being acted on; where my +measurement disagrees with its stated evidence I say so. + +### 1. `docs/fleet/NORTH_STAR.md` stamp reverted (`bea47543`) + +vision raised this as **latent** and scoped to the flatten PR. It is **live in this PR**, so it +could not wait. + +`fleet-north-star.spec.ts:110-114` is a drift test that reads the committed file from disk and +asserts full-string equality against `renderNorthStarMarkdown()`, whose first emitted line is the +H1 and which emits no front matter. Stamping changed line 1 from the H1 to `---`. + +CI 2589 confirms it directly, no longer by construction: + +``` +× renderNorthStarMarkdown > matches the committed NORTH_STAR.md projection (regenerate if this fails) + → expected '# Mosaic Fleet — NORTH STAR\n\n> **Ge…' to be '---\nkind: projection\nstatus: active…' +``` + +Reverted to `origin/next` verbatim. `git diff origin/next -- docs/fleet/NORTH_STAR.md` is 0 lines; +control on `docs/fleet/reference/cli.md` returns 13, so the diff command does report differences. + +The consequence is a contract-level one, recorded in the worklist: **the contract as written +cannot classify any generated document without a matching change to its generator.** A `projection` +is "Generated. Never hand-edited," so its header has to come out of the renderer. That is a code +change and belongs in the flatten PR beside the `resolveNorthStarPaths()` fix. vision's +recommendation, and I agree with it. + +Counts: stamped 104 → **103**. Untouched 23 → **24**. + +### 2. The `docs/` qualifier (vision's C1) + +Stated as asked. **"127 live documentation files" is true for `docs/` only.** Definition: all +`*.md` under `docs/`, minus `docs/archive/` and `docs/_old_structure/`. 318 total = 134 archive + +57 `_old_structure` + 127 live. + +Repo-wide the phrase undercounts: 21 live markdown files sit outside `docs/` and outside any named +exclusion (17 under `guides/`, plus `README.md`, `AGENTS.md`, `CLAUDE.md`, `REPORT-A1207.md` at +root). This PR does not stamp them and does not claim to. + +### 3. `format` failure, and what it says about the header (`8a55c041`) + +CI 2589 also failed `prettier --check` on **exactly one file**: the plan document I hand-wrote. +Reproduced locally, rc=1, same single file. Fixed; the diff is 31 lines in, 31 out, all table +column padding. + +Worth stating for the review rather than burying: **the other 103 stamped documents pass +`prettier --check` unchanged.** The `---\nkind:\nstatus:\n---` block is prettier-clean as applied. +The formatting failure was in my prose, not in the contract header. + +### 4. R1: the evidence inverts, the finding gets stronger + +vision asks for a `kind` change on `docs/DEVELOPER-GUIDE/architecture/channel-protocol.md`, on the +grounds that it "carries 7 normative MUSTs" while the contract says `guide` "decides nothing." + +**The MUST count does not hold.** Uppercase RFC2119 terms (`MUST`, `MUST NOT`, `SHOULD`, +`SHOULD NOT`, `SHALL`, `MAY`, `REQUIRED`) in that file: **0 lines**. Control: the identical grep +returns 25 lines in `docs/requirements/native-kanban-sot.md`, so it finds them where they exist. +The seven lowercase "must" occurrences all _disclaim_ authority rather than assert it: "must not be +used as instructions", "must not be treated as current behavior", "must remain planned work", "must +first specify", "before it can become architecture guidance." The file's own banner reads "it is +not a runtime registry, an API contract, a requirements document." + +**The citation half holds, and is larger than stated.** vision's line numbers are exact. I +restated them earlier with wrong directories, which is worth naming because it is the same method +failure fred and I already wrote up as C3 in the flatten plan: I matched on basename and assumed +the path. The real ones, plus the two vision did not list: + +| citing document | line | words used | +| ------------------------------------------------------- | ---- | --------------------------------------------------- | +| `docs/ADMIN-GUIDE/security/discord-ingress.md` | 141 | "**canonical** shared-contract and parity boundary" | +| `docs/DEVELOPER-GUIDE/integrations/channel-adapters.md` | 28 | "The **canonical** architecture summary is" | +| `docs/DEVELOPER-GUIDE/integrations/channel-adapters.md` | 183 | "**Canonical** channel protocol architecture" | +| `docs/USER-GUIDE/workflows/discord-conversations.md` | 127 | "current shared types ... explicit parity boundary" | +| `docs/SITEMAP.md` | 54 | index entry | +| `docs/DEVELOPER-GUIDE/architecture/README.md` | 18 | index entry | + +So the tension is real. Three live documents outside the two indexes cite it, across four +citations, and three of those four use the word "canonical" for a document that spends its own +banner denying it is canonical. **It is just not a MUST problem, and that +changes what the fix is.** If the file is telling the truth about itself, the three "canonical" +citations are wrong and the edit belongs in those three files, not in this one's `kind`. + +**Left as `kind: guide` in this PR and flagged for the reviewer's call.** Restamping on evidence +that inverts on reading would be worse than leaving it stamped and named. + +### Unchanged + +vision's C2 (no consumer), C4 (holding `parent` blocks nothing) and C5 (a front-mattered `.yaml` +throws in `YAML.parse`) all reverified. C1's arithmetic closes at the stated ref. -- 2.54.0 From 12d5258e2047a1ccf4c63da16e003a6521ade7eb Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 19:58:17 -0500 Subject: [PATCH 06/10] docs(W4): apply fred's six contract decisions from PR #1350 comment 23693 A - docs/README.md:149-190 rewritten. It prescribed a competing front-matter schema (title/type/audience/status/source_of_truth) adopted by 4 of 128 live documents. Two documented conventions in one repo is the defect this pass removes, so the README now documents the contract and the 4 files convert in the same commit: `type` dropped (kind replaces it), `title`/`audience`/`source_of_truth` kept. B - source-of-truth leaves the kind enum, which is now 6 values, and returns as an orthogonal boolean. kind was carrying two independent facts. docs/requirements/native-kanban-sot.md is stamped `kind: spec` + `source_of_truth: true`, which is what it always was. C - status gains `completed`. Applied to the two executed plans, on artifact evidence rather than on their own say-so: --purpose push|merge ships in ci-queue-wait.sh, and every section the README plan specifies exists in docs/README.md today. D - kind follows content, never filename. docs/native-kanban-sot/TASKS.md is `kind: spec` because its body says "a build plan, not a task tracker". The name stays wrong; that is a rename and it is out of scope here. E - the contract covers .md only, written into the README as a decision with vision's YAML.parse measurement as the reason, so the omission does not read as an oversight. F - channel-protocol.md guide -> spec. Applied, with a correction the reviewer should see: the ruling cites "7 normative MUSTs" and there are ZERO uppercase RFC2119 terms in that file. Control: the identical grep returns 25 lines in docs/requirements/native-kanban-sot.md. The citation half of the finding does hold and is larger than stated. Consequence recorded in the worklist: the file's own banner now contradicts its header. Verified: 128 live .md under docs/ (127 baseline + this PR's worklist), 107 stamped, 0 invalid kinds, 17 operator-held + 3 supersede-stamp deferrals + 1 generated = 21 unstamped. 107+21=128. Control: the verifier reports valid=False when a kind is corrupted to `nonsense`, so the 0-invalid result is a real result. prettier --check clean across docs/. --- docs/ADMIN-GUIDE/security/sso-providers.md | 1 - .../architecture/channel-protocol.md | 2 +- .../testing/lease-broker-operations.md | 1 - docs/README.md | 46 +++++++++--- docs/USER-GUIDE/getting-started/quickstart.md | 1 - docs/USER-GUIDE/product/web-dashboard.md | 1 - docs/native-kanban-sot/TASKS.md | 5 ++ ...6-08-10-ci-queue-purpose-implementation.md | 2 +- .../plans/2026-08-10-docs-structure-readme.md | 2 +- ...026-08-20_w4-document-contract-worklist.md | 71 ++++++++++++++++--- docs/requirements/native-kanban-sot.md | 6 ++ 11 files changed, 115 insertions(+), 23 deletions(-) diff --git a/docs/ADMIN-GUIDE/security/sso-providers.md b/docs/ADMIN-GUIDE/security/sso-providers.md index 44f7293b..3214f22f 100644 --- a/docs/ADMIN-GUIDE/security/sso-providers.md +++ b/docs/ADMIN-GUIDE/security/sso-providers.md @@ -2,7 +2,6 @@ kind: guide status: active title: SSO Providers -type: runbook audience: admin source_of_truth: false --- diff --git a/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md b/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md index 290fb8ea..5a7452ff 100644 --- a/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md +++ b/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md @@ -1,5 +1,5 @@ --- -kind: guide +kind: spec status: active --- diff --git a/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md b/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md index b54098cf..343f1292 100644 --- a/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md +++ b/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md @@ -2,7 +2,6 @@ kind: guide status: active title: Lease-broker operations -type: runbook audience: developer source_of_truth: false --- diff --git a/docs/README.md b/docs/README.md index 1c1f66d1..da2e9ddb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -146,21 +146,51 @@ Every canonical page should: 7. Include an owner or maintenance responsibility for operationally sensitive content. 8. Link to the relevant book index and related canonical pages. -Recommended front matter for canonical pages: +Required front matter for every canonical page: ```yaml --- -title: Human-readable page title -type: guide -audience: developer -status: current -source_of_truth: false +kind: tracking | projection | spec | guide | record | superseded +status: active # or: completed | superseded-by: +source_of_truth: false # optional, defaults false +audience: developer # optional: user | admin | developer | all +title: Human-readable page title # optional --- ``` -Allowed `type` values include `guide`, `concept`, `reference`, `decision`, `rfc`, and `runbook`. Allowed `audience` values are `user`, `admin`, `developer`, and `all`. Allowed `status` values are `current`, `draft`, `deprecated`, and `historical`. +`kind` says what the document **is**. One value, required, and it follows the document's content, +never its filename: a file named `TASKS.md` whose body says "this is a build plan, not a task +tracker" is a `spec`. -Indexes may omit front matter when their purpose is self-evident. A page with normative authority must explicitly identify the authority it owns and the boundaries of that authority. +| kind | rule | +| ---------- | ---------------------------------------------------------------- | +| tracking | Live state, single-writer. Never a spec | +| projection | Generated. Never hand-edited. MUST have a drift test | +| spec | How to build one goal or workstream | +| guide | Explains use. Decides nothing | +| record | What happened. Never authoritative, never updated after the fact | +| superseded | Kept for history, and NAMES its replacement | + +`source_of_truth` is a separate boolean because authority is **orthogonal to kind**. A document can +be a `spec` and still be the thing everything else answers to; +`docs/requirements/native-kanban-sot.md` is exactly that. Folding authority into `kind` forced one +field to carry two independent facts, which is why an earlier draft of this contract could not +classify that file at all. + +`status` has three values. `active` means in force. `completed` means the work the document +describes landed and the document is now finished rather than stale; executed implementation plans +take this. `superseded-by: ` replaces `status` entirely and names the replacement. + +**This contract covers `.md` files only.** It is not an omission: a YAML document cannot carry YAML +front matter. The repository's own `yaml@2.8.3` throws `Source contains multiple documents` on a +front-mattered `.yaml`, and `parseNorthStar` (`packages/mosaic/src/commands/fleet.ts:242`) is a live +consumer that would break. `.yaml` sources declare their own kind inside the document or not at all. + +A `parent` field is planned and is deliberately not yet required; it lands once the docs flatten +settles the paths it would point at. + +Indexes may omit front matter when their purpose is self-evident. A page with normative authority +must explicitly identify the authority it owns and the boundaries of that authority. ## Obsidian and link conventions diff --git a/docs/USER-GUIDE/getting-started/quickstart.md b/docs/USER-GUIDE/getting-started/quickstart.md index f31ade8f..1b20a473 100644 --- a/docs/USER-GUIDE/getting-started/quickstart.md +++ b/docs/USER-GUIDE/getting-started/quickstart.md @@ -2,7 +2,6 @@ kind: guide status: active title: Mosaic Stack Quickstart -type: guide audience: user source_of_truth: false --- diff --git a/docs/USER-GUIDE/product/web-dashboard.md b/docs/USER-GUIDE/product/web-dashboard.md index 60b4d2d6..8a40caaa 100644 --- a/docs/USER-GUIDE/product/web-dashboard.md +++ b/docs/USER-GUIDE/product/web-dashboard.md @@ -2,7 +2,6 @@ kind: guide status: active title: Mosaic web dashboard -type: guide audience: user source_of_truth: false --- diff --git a/docs/native-kanban-sot/TASKS.md b/docs/native-kanban-sot/TASKS.md index b9a8cf4d..5dfea35f 100644 --- a/docs/native-kanban-sot/TASKS.md +++ b/docs/native-kanban-sot/TASKS.md @@ -1,3 +1,8 @@ +--- +kind: spec +status: active +--- + # Native Kanban/SOT P0–P3 — Dependency-Ordered Build Slices **Status:** CANON INDEPENDENTLY APPROVED; PUBLICATION IN PROGRESS diff --git a/docs/plans/2026-08-10-ci-queue-purpose-implementation.md b/docs/plans/2026-08-10-ci-queue-purpose-implementation.md index 864d2170..76d019cd 100644 --- a/docs/plans/2026-08-10-ci-queue-purpose-implementation.md +++ b/docs/plans/2026-08-10-ci-queue-purpose-implementation.md @@ -1,6 +1,6 @@ --- kind: spec -status: active +status: completed --- # CI Queue Guard Purpose Semantics Implementation Plan diff --git a/docs/plans/2026-08-10-docs-structure-readme.md b/docs/plans/2026-08-10-docs-structure-readme.md index f03de32f..7326dd25 100644 --- a/docs/plans/2026-08-10-docs-structure-readme.md +++ b/docs/plans/2026-08-10-docs-structure-readme.md @@ -1,6 +1,6 @@ --- kind: spec -status: active +status: completed --- # Documentation Structure README Implementation Plan diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index fbf1c05a..6c752c86 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -19,15 +19,16 @@ files. The flatten plan says 130; the arithmetic does not close (318 total = 134 ## Applied -| bucket | count | note | -| --------------------------------- | ----- | ----------------------------------------- | -| stamped `kind` + `status: active` | 103 | this pass | -| held, operator judgement | 19 | section "Needs a decision" below | -| held, cites the moving path | 3 | the three `SUPERSEDED` TASKS.md stamps | -| held, generated file | 1 | `docs/fleet/NORTH_STAR.md`, see below | -| already stamped in W1 | 1 | `docs/fleet/FLEET-DOCTRINE.md`, untouched | +| bucket | count | note | +| --------------------------- | ----- | -------------------------------------- | +| stamped `kind` + `status` | 107 | this pass | +| held, operator judgement | 17 | section "Needs a decision" below | +| held, cites the moving path | 3 | the three `SUPERSEDED` TASKS.md stamps | +| held, generated file | 1 | `docs/fleet/NORTH_STAR.md`, see below | -Kinds applied: 54 `guide`, 34 `record`, 9 `spec`, 6 `tracking`. +128 live `.md` under `docs/`, which is the 127 baseline plus this document. 107 + 17 + 3 + 1 = 128. + +Kinds: 53 `guide`, 34 `record`, 13 `spec`, 7 `tracking`. Status: 105 `active`, 2 `completed`. `parent` is **not** applied. It points at `docs/fleet/NORTH_STAR.yaml`, which the flatten moves to `docs/NORTH_STAR.yaml`. Stamping it now means re-pointing 127 files by hand later. It lands @@ -269,3 +270,57 @@ that inverts on reading would be worse than leaving it stamped and named. vision's C2 (no consumer), C4 (holding `parent` blocks nothing) and C5 (a front-mattered `.yaml` throws in `YAML.parse`) all reverified. C1's arithmetic closes at the stated ref. + +## fred's six decisions, applied + +Ruled on PR #1350 as comment 23693. Each is applied here; each is his call, not mine, and any of +them is one line to reverse. + +| # | decision | applied as | +| --- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| A | New contract wins; `docs/README.md` is rewritten in this PR and the 4 old-schema files convert in the same pass | `docs/README.md:149-190` rewritten; `type:` dropped from the 4 files, `title`/`audience`/`source_of_truth` kept | +| B | `source-of-truth` leaves the `kind` enum and returns as an orthogonal boolean | enum is now 6 values; `docs/requirements/native-kanban-sot.md` stamped `kind: spec` + `source_of_truth: true` | +| C | `status` gains a third value, `completed` | the two executed plans take it (evidence below) | +| D | Kind follows content, never filename | `docs/native-kanban-sot/TASKS.md` stamped `kind: spec`, because its body says "a build plan, not a task tracker" | +| E | The contract covers `.md` only, stated as a decision rather than left as a gap | written into `docs/README.md` with vision's `YAML.parse` measurement as the reason | +| F | `channel-protocol.md` becomes `spec` | applied, with one correction and one consequence below | + +### C: evidence the two plans are complete + +Neither plan self-declares completion, so this is measured from the artifacts rather than taken +from the documents: + +- `2026-08-10-ci-queue-purpose-implementation.md` — the shipped guard carries the flag the plan + specifies: `ci-queue-wait.sh --purpose push|merge`, exercised in this session at rc=0. +- `2026-08-10-docs-structure-readme.md` — every section the plan specifies exists in + `docs/README.md` today, including the Obsidian conventions and the source-of-truth precedence + block. This PR is editing the artifact that plan produced. + +### F: the MUST count does not hold, and the fix changes shape + +Applied as ruled. But the ruling's stated grounds are half wrong, and the half that survives points +somewhere else, so this is the one to look at again. + +**Zero** uppercase RFC2119 terms in `channel-protocol.md`, not seven. Control: the identical grep +returns 25 lines in `docs/requirements/native-kanban-sot.md`. The seven lowercase "must" +occurrences all _disclaim_ authority: "must not be used as instructions", "must not be treated as +current behavior", "must remain planned work". + +**The citation half holds and is bigger than stated** (table in the section above). + +**The consequence of applying F:** the file is now stamped `spec` while its own banner says "it is +not a runtime registry, an API contract, a requirements document." Header and body now contradict +each other, which is the defect this pass exists to remove. Either the banner is edited in this PR, +or the three documents calling it canonical are the ones that are wrong. That is a content call and +it is left to the reviewer rather than folded into a stamping pass. + +## Q1 — the one question this pass cannot answer for itself + +`docs/README.md` now **prescribes** the document contract, and it is the only live document under +`docs/` with no `kind`. It is still on the operator-held list, so it is left unstamped. + +By decision B it is arguably `kind: spec` with `source_of_truth: true` for the subject "document +contract". The reason this is not applied unilaterally: it decides which document outranks the +other when `docs/README.md` and `docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md` disagree +about the contract, and they already differ (the plan's enum has 7 values, the README's now has 6). +That is an authority question, not a classification one. diff --git a/docs/requirements/native-kanban-sot.md b/docs/requirements/native-kanban-sot.md index 291f5797..535b22a5 100644 --- a/docs/requirements/native-kanban-sot.md +++ b/docs/requirements/native-kanban-sot.md @@ -1,3 +1,9 @@ +--- +kind: spec +status: active +source_of_truth: true +--- + # Native Kanban and Canonical Task SOT — Canonical Requirements **Status:** RATIFIED and independently approved for canonical publication under issue [#751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751) -- 2.54.0 From 94a7d5b692266d28a2300488e1dc4a74ff8814af Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 20:04:35 -0500 Subject: [PATCH 07/10] test(mosaic): pin quickstart.md to `status: active`, the contract's value for in-force CI 2592 proved the old front-matter schema HAD a consumer. vision's C2 concluded "no consumer found", fred's decision A rested on "no installed base to protect", and I accepted both. All three of us were wrong. installation-documentation.spec.ts:39 asserted a raw regex over the markdown text: expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/); Not a front-matter parse and not a key lookup, which is why a search organised around parsing primitives could not see it. Stamping docs/USER-GUIDE/getting-started/quickstart.md replaced `status: current` with `status: active` and turned it red. Updated to the contract's vocabulary, intent unchanged: the page must still declare itself in force, and must still teach no curl-pipe-to-shell install. Verified by evaluating both regexes against the real file: old false, new true. Control: a page carrying `superseded-by` still fails the new regex, so the assertion still asserts something. 2592 also confirms the NORTH_STAR revert took: the north-star drift test is green, `format` and `lint` are green, and this was the only failure in 1617 tests. Method point worth keeping: the full suite is a stronger consumer search than any grep, because it does not depend on guessing how a consumer reads the file. --- ...026-08-20_w4-document-contract-worklist.md | 28 +++++++++++++++++++ .../src/installation-documentation.spec.ts | 4 ++- 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index 6c752c86..7a369a50 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -324,3 +324,31 @@ contract". The reason this is not applied unilaterally: it decides which documen other when `docs/README.md` and `docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md` disagree about the contract, and they already differ (the plan's enum has 7 values, the README's now has 6). That is an authority question, not a classification one. + +## The old schema DID have a consumer, and CI found it + +vision's C2 concluded "no consumer found" after searching by parsing primitive rather than by key +name. fred's decision A rested on "no installed base to protect." I accepted both. **All three of +us were wrong, and the full test suite is what proved it.** + +`packages/mosaic/src/installation-documentation.spec.ts:39` asserted: + +```ts +expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/); +``` + +That is a raw regex over the markdown text, not a front-matter parse and not a key lookup, which is +exactly why a search organised around parsing primitives could not see it. It pins +`docs/USER-GUIDE/getting-started/quickstart.md` to the old vocabulary. Replacing `status: current` +with `status: active` turned it red. + +Updated to `status: active`, the contract's value for "in force", with the reason in a comment +beside it. Verified by evaluating both regexes against the real file: old `false`, new `true`. +Control: a page carrying `superseded-by` still fails the new regex, so the assertion still asserts +something rather than matching anything with front matter. + +**The method point, which outlives this file.** CI 2592 ran 1617 tests against the stamped tree: 1 +failed, 1616 passed. That is a stronger consumer search than any grep the three of us ran, because +it does not depend on guessing how a consumer reads the file. **Run the suite before concluding a +documentation change has no code consumers.** Two independent seats and a reviewer searching by +hand missed the one that existed. diff --git a/packages/mosaic/src/installation-documentation.spec.ts b/packages/mosaic/src/installation-documentation.spec.ts index a5a47e34..56ae10d6 100644 --- a/packages/mosaic/src/installation-documentation.spec.ts +++ b/packages/mosaic/src/installation-documentation.spec.ts @@ -36,7 +36,9 @@ describe('current installation documentation safety', (): void => { async (relativePath): Promise => { const markdown = await readFile(resolve(repositoryRoot, relativePath), 'utf8'); - expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/); + // `status: active` is the document contract's value for "in force"; it replaced the + // old `status: current` when the contract in docs/README.md became the single schema. + expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: active\n[\s\S]*?\n---\n/); expect(unsafeRemoteExecutionFindings(markdown)).toEqual([]); }, ); -- 2.54.0 From ff40794bfeddc05a2789800a875cce49136c4a06 Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 20:21:06 -0500 Subject: [PATCH 08/10] docs(W4): revert channel-protocol to guide (F withdrawn), stamp docs/README.md as the contract's source of truth (Q1) fred withdrew decision F after re-measuring channel-protocol.md with a control: zero uppercase RFC2119 terms, seven lowercase 'must' all disclaiming authority, under a banner refusing requirements status. F rested on 'the doc graph outranks the page's own banner', which contradicts decision D, 'kind follows content'. D is the rule; F was its counterexample. Neither rescue (vision's adjective edit on the citing docs, or a banner edit) was taken: a kind that survives only by editing the evidence around it is not a classification. Q1 answered: docs/README.md prescribes the contract, so by D its content is a spec, and by B it is the source of truth for that contract. A plan never outranks the artifact it planned, so the flatten plan's stale 7-value enum is corrected there rather than competing here. 128 live docs = 108 stamped + 16 operator-held + 3 supersede deferrals + 1 generated. --- .../architecture/channel-protocol.md | 2 +- docs/README.md | 6 ++ ...026-08-20_w4-document-contract-worklist.md | 56 +++++++++++++++++++ 3 files changed, 63 insertions(+), 1 deletion(-) diff --git a/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md b/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md index 5a7452ff..290fb8ea 100644 --- a/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md +++ b/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md @@ -1,5 +1,5 @@ --- -kind: spec +kind: guide status: active --- diff --git a/docs/README.md b/docs/README.md index da2e9ddb..9af48d40 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,9 @@ +--- +kind: spec +source_of_truth: true +status: active +--- + # Mosaic Stack Documentation This directory is the canonical home for Mosaic Stack product, architecture, API, operations, and delivery documentation. diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index 7a369a50..df5cd568 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -352,3 +352,59 @@ failed, 1616 passed. That is a stronger consumer search than any grep the three it does not depend on guessing how a consumer reads the file. **Run the suite before concluding a documentation change has no code consumers.** Two independent seats and a reviewer searching by hand missed the one that existed. + +## fred's second pass: F withdrawn, Q1 answered + +Both changes below are fred's rulings, applied. Neither is my judgement and I record whose it is. + +### F is withdrawn: `channel-protocol.md` returns to `kind: guide` + +Reverted. fred re-measured the file himself with a control and reached the count I reported: zero +uppercase RFC2119 terms case-sensitive, seven lowercase `must`, every one disclaiming authority, +under a banner that refuses requirements status. A page like that is a guide. + +The reason this matters past one stamp is fred's own: F rested on "the doc graph outranks the +page's own banner", which contradicts his decision D, "kind follows content, never the filename and +never what other documents say about it". D is the rule. F was a counterexample to it, written in +the same comment. + +Neither rescue was taken. vision's adjective edit on the three citing docs and an edit to the +page's banner would both have preserved a stamp that should not have been made. The three citing +documents stay as they are: under vision's index-pointer reading, "canonical" claims the best page +on a subject rather than normative force, so there is nothing to correct. + +**What this costs the contract: nothing, and that is the point.** A kind that survives only by +editing the evidence around it is not a classification. + +### Q1 answered: `docs/README.md` is stamped `kind: spec`, `source_of_truth: true` + +Applied. By D, a document that prescribes the contract has spec content. By B, `source_of_truth` is +an orthogonal boolean and this is the authoritative statement of the contract, so it carries both. + +The authority half of Q1 was whether stamping the README settles a conflict with the flatten plan, +whose enum still has seven values against the README's six. fred's ruling: **a plan never outranks +the artifact it planned.** The plan's enum is pre-decision-B staleness, not a competing authority. +The plan is fred's file and he corrects it there. + +The contract now applies to the document that states it. That was the only state in which it could +be credible. + +### Verification arithmetic, re-closed + +128 live `.md` under `docs/` = **108 stamped** + 16 operator-held + 3 supersede deferrals + 1 +generated. The stamped count rose by one and the operator-held set fell by one, both because of the +README; every other row is unchanged. Control unchanged: the verifier reports `valid=False` when a +kind is corrupted to `nonsense`. + +### One consumer finding that is not a defect + +A sweep of every spec reading a path under `docs/` returns 10 files. Four read a live file: +`fleet-north-star.spec.ts` and `installation-documentation.spec.ts` (both already caught by CI), +`mutator-gate.acceptance.spec.ts` reading `compaction-revocation.md`, which passes under its `guide` +stamp, and `roster-v2.spec.ts:366`, which reads `docs/fleet/reference/roster-v2.schema.json`. + +The fourth is a real read of a real live file under `docs/` and is untouched only because decision E +scopes the contract to `.md`. Had the contract covered every file under `docs/`, front matter in +that JSON schema would have broken the spec, the same failure as the quickstart regex. E was +load-bearing beyond the YAML-parse grounds it was decided on. No action; recorded so the `.md` +boundary is not widened later without re-running this sweep. -- 2.54.0 From 4211fb87f8dd41789c3bf08e276f774bdf5afefc Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 20:41:52 -0500 Subject: [PATCH 09/10] docs(W4): withdraw the test count from the method paragraph, do not replace it The paragraph arguing 'run the suite before concluding a docs change has no code consumers' carried a number: 'CI 2592 ran 1617 tests, 1 failed, 1616 passed'. That number is wrong and is withdrawn in place rather than deleted. Extracting per-test totals from these pipeline logs is not a reliable method: the same regex over the same log format returns 1003 for 2592, 1022 for 2593 and 3471 for 2594, which are runs of the same suite. Three irreconcilable answers from one method is proof the method does not measure what it claims, so no corrected count is substituted. The claim is restated in what the log carries reliably, the named FAIL list and the turbo task line. The count was decoration on a claim already carried by a specific name: one named failing spec is what refuted three hand-searches. --- .../2026-08-20_w4-document-contract-worklist.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index df5cd568..46923ba4 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -347,9 +347,18 @@ beside it. Verified by evaluating both regexes against the real file: old `false Control: a page carrying `superseded-by` still fails the new regex, so the assertion still asserts something rather than matching anything with front matter. -**The method point, which outlives this file.** CI 2592 ran 1617 tests against the stamped tree: 1 -failed, 1616 passed. That is a stronger consumer search than any grep the three of us ran, because -it does not depend on guessing how a consumer reads the file. **Run the suite before concluding a +**The method point, which outlives this file.** CI 2592 ran the whole suite against the stamped +tree, 46 turbo tasks, and returned exactly one failing spec: this one. That is a stronger consumer +search than any grep the three of us ran, because it does not depend on guessing how a consumer +reads the file. + +An earlier draft of this paragraph put a test count here, "1617 tests, 1 failed". **That number was +wrong and it is withdrawn.** Extracting per-test totals from these pipeline logs is not reliable: +the same regex over the same log format returns 1003 for 2592, 1022 for 2593 and 3471 for 2594, +which are runs of the same suite. Three irreconcilable answers from one method is proof the method +does not measure what it claims. What the log does carry reliably is the FAIL list and the turbo +task line, so the claim is stated in those terms instead. The point never needed the count: one +named failing spec is what refuted three hand-searches. **Run the suite before concluding a documentation change has no code consumers.** Two independent seats and a reviewer searching by hand missed the one that existed. -- 2.54.0 From 98f3384554740c9bac0393dfa77f91d46590e77f Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 20:46:16 -0500 Subject: [PATCH 10/10] docs(W4): mark the Applied table as first-pass and point it forward (fred's F1) The Applied table carried 107 stamped and 17 held, the counts from the first pass, with nothing telling a reader they had moved. The re-closed arithmetic at the end of the document was already correct, so the document was not wrong overall, but a reader hitting the table got a stale count with no forward pointer. In this PR specifically that is the defect the PR exists to remove, appearing in the PR's own worklist. The first-pass numbers are left standing and labelled rather than overwritten, matching every other correction in this document: a record of what a pass produced is worth more than a number silently updated to still look right. The current census follows it, re-measured: 108 stamped + 16 + 3 + 1 = 128, kinds 54 guide / 34 record / 13 spec / 7 tracking, status 106 active / 2 completed, and the two files carrying source_of_truth: true named. --- docs/plans/2026-08-20_w4-document-contract-worklist.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index 46923ba4..cb2c0d6d 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -19,6 +19,11 @@ files. The flatten plan says 130; the arithmetic does not close (318 total = 134 ## Applied +**These are the FIRST-PASS counts and they are superseded. The current tree is counted in +"Verification arithmetic, re-closed" at the end of this document.** They are left standing rather +than overwritten, for the same reason every other correction here is: a record of what a pass +produced is worth more than a number silently updated to still look right. + | bucket | count | note | | --------------------------- | ----- | -------------------------------------- | | stamped `kind` + `status` | 107 | this pass | @@ -30,6 +35,11 @@ files. The flatten plan says 130; the arithmetic does not close (318 total = 134 Kinds: 53 `guide`, 34 `record`, 13 `spec`, 7 `tracking`. Status: 105 `active`, 2 `completed`. +After fred's Q1 ruling stamped `docs/README.md`, one file moved from the held bucket to the stamped +one and nothing else changed: **108 stamped + 16 + 3 + 1 = 128**, kinds 54 `guide`, 34 `record`, +13 `spec`, 7 `tracking`, status 106 `active`, 2 `completed`. Two files carry +`source_of_truth: true`, `docs/README.md` and `docs/requirements/native-kanban-sot.md`. + `parent` is **not** applied. It points at `docs/fleet/NORTH_STAR.yaml`, which the flatten moves to `docs/NORTH_STAR.yaml`. Stamping it now means re-pointing 127 files by hand later. It lands after the move, in one pass, with the post-move path. -- 2.54.0