From ff40794bfeddc05a2789800a875cce49136c4a06 Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 20:21:06 -0500 Subject: [PATCH] docs(W4): revert channel-protocol to guide (F withdrawn), stamp docs/README.md as the contract's source of truth (Q1) fred withdrew decision F after re-measuring channel-protocol.md with a control: zero uppercase RFC2119 terms, seven lowercase 'must' all disclaiming authority, under a banner refusing requirements status. F rested on 'the doc graph outranks the page's own banner', which contradicts decision D, 'kind follows content'. D is the rule; F was its counterexample. Neither rescue (vision's adjective edit on the citing docs, or a banner edit) was taken: a kind that survives only by editing the evidence around it is not a classification. Q1 answered: docs/README.md prescribes the contract, so by D its content is a spec, and by B it is the source of truth for that contract. A plan never outranks the artifact it planned, so the flatten plan's stale 7-value enum is corrected there rather than competing here. 128 live docs = 108 stamped + 16 operator-held + 3 supersede deferrals + 1 generated. --- .../architecture/channel-protocol.md | 2 +- docs/README.md | 6 ++ ...026-08-20_w4-document-contract-worklist.md | 56 +++++++++++++++++++ 3 files changed, 63 insertions(+), 1 deletion(-) diff --git a/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md b/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md index 5a7452ff..290fb8ea 100644 --- a/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md +++ b/docs/DEVELOPER-GUIDE/architecture/channel-protocol.md @@ -1,5 +1,5 @@ --- -kind: spec +kind: guide status: active --- diff --git a/docs/README.md b/docs/README.md index da2e9ddb..9af48d40 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,9 @@ +--- +kind: spec +source_of_truth: true +status: active +--- + # Mosaic Stack Documentation This directory is the canonical home for Mosaic Stack product, architecture, API, operations, and delivery documentation. diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index 7a369a50..df5cd568 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -352,3 +352,59 @@ failed, 1616 passed. That is a stronger consumer search than any grep the three it does not depend on guessing how a consumer reads the file. **Run the suite before concluding a documentation change has no code consumers.** Two independent seats and a reviewer searching by hand missed the one that existed. + +## fred's second pass: F withdrawn, Q1 answered + +Both changes below are fred's rulings, applied. Neither is my judgement and I record whose it is. + +### F is withdrawn: `channel-protocol.md` returns to `kind: guide` + +Reverted. fred re-measured the file himself with a control and reached the count I reported: zero +uppercase RFC2119 terms case-sensitive, seven lowercase `must`, every one disclaiming authority, +under a banner that refuses requirements status. A page like that is a guide. + +The reason this matters past one stamp is fred's own: F rested on "the doc graph outranks the +page's own banner", which contradicts his decision D, "kind follows content, never the filename and +never what other documents say about it". D is the rule. F was a counterexample to it, written in +the same comment. + +Neither rescue was taken. vision's adjective edit on the three citing docs and an edit to the +page's banner would both have preserved a stamp that should not have been made. The three citing +documents stay as they are: under vision's index-pointer reading, "canonical" claims the best page +on a subject rather than normative force, so there is nothing to correct. + +**What this costs the contract: nothing, and that is the point.** A kind that survives only by +editing the evidence around it is not a classification. + +### Q1 answered: `docs/README.md` is stamped `kind: spec`, `source_of_truth: true` + +Applied. By D, a document that prescribes the contract has spec content. By B, `source_of_truth` is +an orthogonal boolean and this is the authoritative statement of the contract, so it carries both. + +The authority half of Q1 was whether stamping the README settles a conflict with the flatten plan, +whose enum still has seven values against the README's six. fred's ruling: **a plan never outranks +the artifact it planned.** The plan's enum is pre-decision-B staleness, not a competing authority. +The plan is fred's file and he corrects it there. + +The contract now applies to the document that states it. That was the only state in which it could +be credible. + +### Verification arithmetic, re-closed + +128 live `.md` under `docs/` = **108 stamped** + 16 operator-held + 3 supersede deferrals + 1 +generated. The stamped count rose by one and the operator-held set fell by one, both because of the +README; every other row is unchanged. Control unchanged: the verifier reports `valid=False` when a +kind is corrupted to `nonsense`. + +### One consumer finding that is not a defect + +A sweep of every spec reading a path under `docs/` returns 10 files. Four read a live file: +`fleet-north-star.spec.ts` and `installation-documentation.spec.ts` (both already caught by CI), +`mutator-gate.acceptance.spec.ts` reading `compaction-revocation.md`, which passes under its `guide` +stamp, and `roster-v2.spec.ts:366`, which reads `docs/fleet/reference/roster-v2.schema.json`. + +The fourth is a real read of a real live file under `docs/` and is untouched only because decision E +scopes the contract to `.md`. Had the contract covered every file under `docs/`, front matter in +that JSON schema would have broken the spec, the same failure as the quickstart regex. E was +load-bearing beyond the YAML-parse grounds it was decided on. No action; recorded so the `.md` +boundary is not widened later without re-running this sweep.