docs(W4): revert channel-protocol to guide (F withdrawn), stamp docs/README.md as the contract's source of truth (Q1)
ci/woodpecker/pr/ci Pipeline was successful

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.
This commit is contained in:
2026-08-20 20:21:06 -05:00
parent 94a7d5b692
commit ff40794bfe
3 changed files with 63 additions and 1 deletions
@@ -1,5 +1,5 @@
---
kind: spec
kind: guide
status: active
---
+6
View File
@@ -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.
@@ -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.