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
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:
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
kind: spec
|
kind: guide
|
||||||
status: active
|
status: active
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,3 +1,9 @@
|
|||||||
|
---
|
||||||
|
kind: spec
|
||||||
|
source_of_truth: true
|
||||||
|
status: active
|
||||||
|
---
|
||||||
|
|
||||||
# Mosaic Stack Documentation
|
# Mosaic Stack Documentation
|
||||||
|
|
||||||
This directory is the canonical home for Mosaic Stack product, architecture, API, operations, and delivery 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
|
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
|
documentation change has no code consumers.** Two independent seats and a reviewer searching by
|
||||||
hand missed the one that existed.
|
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.
|
||||||
|
|||||||
Reference in New Issue
Block a user