Skip to content

Give the protocol example and vocabulary one owner - #751

Merged
MongLong0214 merged 2 commits into
mainfrom
docs-protocol-ownership
Aug 18, 2026
Merged

Give the protocol example and vocabulary one owner#751
MongLong0214 merged 2 commits into
mainfrom
docs-protocol-ownership

Conversation

@MongLong0214

Copy link
Copy Markdown
Owner

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.md stated the situation itself:

The worked example that uses the full vocabulary stays in the README, in every language, because it is also a conformance fixture.

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.

spec/verify.sh                       README.md + README.*.md  →  docs/protocol.md
spec/schema/readme-vocab-check.mjs   →  protocol-doc-vocab-check.mjs, same target

The fixture is found by a marker, not by position. The old rule took the last ```text block in the file:

const m = [...md.matchAll(/```text\n([\s\S]*?)\n```/g)].at(-1);

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:

<!-- SPEC-FIXTURE:11-readme-example -->

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.

README.md      648 → 616 lines
README.ko.md   546 → 514
README.ja.md   552 → 520
README.zh-CN   532 → 500

Verification — three negative controls at the new owner

Each was applied to docs/protocol.md, spec/verify.sh run, then restored:

mutation result
Certainty: firmCertainty: high FAIL: 대표 예제가 픽스처와 다르다 — and high is a value our own rejection fixtures carry
delete the Expires: row FAIL: SPEC에 있으나 표에 없음: Expires
delete the marker FAIL: no <!-- SPEC-FIXTURE:11-readme-example --> marker
restore OK: 32 fixtures + protocol example sync + vocab table

Also: 101 tests across readme, release-publish-prerequisites and release-tag-binding; check-readme-numbers.mjs exit 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.mjs still 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.

`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
@github-actions

github-actions Bot commented Aug 18, 2026

Copy link
Copy Markdown

CommitLore — record lint

Trailers: clean — 2 commits in origin/main..65721f64600fcb91733f8694913713d469852f77
Active constraints: not read — commitlore: git log --follow accepts exactly one pathspec, so renames are not followed for 9 paths; query one path at a time to follow its rename chain (9 changed paths)

Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR.

@MongLong0214
MongLong0214 merged commit cac5cde into main Aug 18, 2026
12 checks passed
@MongLong0214
MongLong0214 deleted the docs-protocol-ownership branch August 18, 2026 02:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant