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..3214f22f 100644 --- a/docs/ADMIN-GUIDE/security/sso-providers.md +++ b/docs/ADMIN-GUIDE/security/sso-providers.md @@ -1,8 +1,8 @@ --- +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..343f1292 100644 --- a/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md +++ b/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md @@ -1,8 +1,8 @@ --- +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/README.md b/docs/README.md index 1c1f66d1..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. @@ -146,21 +152,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/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..1b20a473 100644 --- a/docs/USER-GUIDE/getting-started/quickstart.md +++ b/docs/USER-GUIDE/getting-started/quickstart.md @@ -1,8 +1,8 @@ --- +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..8a40caaa 100644 --- a/docs/USER-GUIDE/product/web-dashboard.md +++ b/docs/USER-GUIDE/product/web-dashboard.md @@ -1,8 +1,8 @@ --- +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/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/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-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..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,3 +1,8 @@ +--- +kind: spec +status: completed +--- + # 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..7326dd25 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: completed +--- + # 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/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..cb2c0d6d --- /dev/null +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -0,0 +1,429 @@ +--- +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 + +**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 | +| 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 | + +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`. + +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. + +## 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. + +## 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` +(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 + +- 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`. +- 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. + +## 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. + +## 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 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. + +## 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. 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/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) 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-*` 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([]); }, );