From 12d5258e2047a1ccf4c63da16e003a6521ade7eb Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 19:58:17 -0500 Subject: [PATCH] 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)