Give the protocol example and vocabulary one owner - #751
Merged
Conversation
`docs/protocol.md` said it plainly: the complete record and the vocabulary table "stay in the README, in every language, because it is also a conformance fixture." That sentence is why the README is a specification summary rather than a product page — the gate lived on four translated copies, so the content had to live there too. The gate moves; the content follows it. `spec/verify.sh` now compares `docs/protocol.md` against `spec/fixtures/valid/11-readme-example.txt`, and `spec/schema/readme-vocab-check.mjs` becomes `protocol-doc-vocab-check.mjs` reading the same file. Four drift points become one. The fixture is found by an explicit marker rather than by position. The old rule took the last ```text block in the file, which cannot say what it owns: adding an example anywhere below it silently moved the contract onto a different block. `<!-- SPEC-FIXTURE:11-readme-example -->` says which block is the one under contract, and a missing marker is a failure rather than a quiet retarget. Each README keeps a small record example and a link. The example there is illustrative, not the fixture, so the four translations no longer have to hold the same forty lines byte for byte. Limit: the evidence block is the other four-way duplicate and is untouched here -- `check-readme-numbers.mjs` still owns it in all four READMEs, and moving it is its own change with its own negative control Blast: system Undo: easy Certainty: firm Record-Id: r-protoown Provenance: authored Verified: three negative controls fail at the new owner and pass after restore -- a changed Certainty value, a deleted Expires row, and a removed marker; `spec/verify.sh` reports OK, and 101 tests across readme, release-prerequisite and tag-binding suites pass with the workflow digest re-locked CommitLore-Version: 2.0.0
CommitLore — record lintTrailers: clean — 2 commits in Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First step of the README/canonical-docs restructure: move the fact ownership before touching the README's shape, so no gate is lost on the way.
Why this was the blocker
docs/protocol.mdstated the situation itself:That is the direct reason the README reads as a specification summary rather than a product page. The gate lived on four translated copies, so the content had to live there too — 44 lines of complete record and vocabulary table, repeated per language, each a place for it to drift.
What changed
The gate moves, and the content follows it.
The fixture is found by a marker, not by position. The old rule took the last ```text block in the file:
A positional rule cannot say what it owns. Adding an example anywhere below it silently moves the contract onto a different block, and the check keeps passing. Now:
A missing marker is a failure, not a quiet retarget.
Each README keeps a small record example and a link. That example is illustrative rather than the fixture, so the four translations no longer have to carry the same forty lines byte for byte.
Verification — three negative controls at the new owner
Each was applied to
docs/protocol.md,spec/verify.shrun, then restored:Certainty: firm→Certainty: highFAIL: 대표 예제가 픽스처와 다르다— andhighis a value our own rejection fixtures carryExpires:rowFAIL: SPEC에 있으나 표에 없음: ExpiresFAIL: no <!-- SPEC-FIXTURE:11-readme-example --> markerOK: 32 fixtures + protocol example sync + vocab tableAlso: 101 tests across
readme,release-publish-prerequisitesandrelease-tag-binding;check-readme-numbers.mjsexit 0; the CI workflow digest re-locked after the comment edit.Scope
The evidence block is the other four-way duplicate and is untouched here.
check-readme-numbers.mjsstill owns it across all four READMEs; moving it is its own change with its own negative control, and mixing the two would blur which gate is proving what.No product behaviour changes.