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/.
This commit is contained in:
@@ -2,7 +2,6 @@
|
||||
kind: guide
|
||||
status: active
|
||||
title: SSO Providers
|
||||
type: runbook
|
||||
audience: admin
|
||||
source_of_truth: false
|
||||
---
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
kind: guide
|
||||
kind: spec
|
||||
status: active
|
||||
---
|
||||
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
kind: guide
|
||||
status: active
|
||||
title: Lease-broker operations
|
||||
type: runbook
|
||||
audience: developer
|
||||
source_of_truth: false
|
||||
---
|
||||
|
||||
+38
-8
@@ -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: <path>
|
||||
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: <path>` 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 `[email protected]` 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
|
||||
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
kind: guide
|
||||
status: active
|
||||
title: Mosaic Stack Quickstart
|
||||
type: guide
|
||||
audience: user
|
||||
source_of_truth: false
|
||||
---
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
kind: guide
|
||||
status: active
|
||||
title: Mosaic web dashboard
|
||||
type: guide
|
||||
audience: user
|
||||
source_of_truth: false
|
||||
---
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
kind: spec
|
||||
status: active
|
||||
---
|
||||
|
||||
# Native Kanban/SOT P0–P3 — Dependency-Ordered Build Slices
|
||||
|
||||
**Status:** CANON INDEPENDENTLY APPROVED; PUBLICATION IN PROGRESS
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
kind: spec
|
||||
status: active
|
||||
status: completed
|
||||
---
|
||||
|
||||
# CI Queue Guard Purpose Semantics Implementation Plan
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
kind: spec
|
||||
status: active
|
||||
status: completed
|
||||
---
|
||||
|
||||
# Documentation Structure README Implementation Plan
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user