Repository navigation
fix: README header advertised a stale surface; pin it to the manifest (1.2.3) - #21
Merged
Merged
Conversation
… (1.2.3) Caught in review of the community-catalog submission: README.md read "Version: 1.1.0 · Provides: 5 commands, 3 hooks" while the manifest was 1.2.2 with 6 commands. The body already documented all six — only the header lied — but that header is what a catalog reviewer reads at the documentation URL, so the published docs understated the extension by a version and a command. - README header -> 1.2.3, 6 commands, 3 hooks - extension.yml 1.2.2 -> 1.2.3; CHANGELOG [1.2.3] - NEW GUARD: test_readme_header_matches_the_manifest pins the header to extension.yml, the same conform-or-fail discipline the vocabulary and domain-schema conformance tests already apply. Verified red-first: it fails on a deliberately stale header and passes on the corrected one. Cut as a new patch release rather than re-pointing v1.2.2: a published tag is an immutable artifact, and silently moving one is exactly the drift this extension exists to detect.
11 tasks done
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.
Raised by a spec-kit maintainer while reviewing the community-catalog submission (github/spec-kit#4084 → PR #4085). Blocks publication until fixed.
The defect
README.mdline 7 read:…while
extension.ymlwas1.2.2with 6 commands. The README body already documented all six commands and all six checks correctly — only the header lied. But that header is what a catalog reviewer reads at the documentation URL, so the published docs understated the extension by a version and a whole command (issues).Their reviewer's framing is fair: it "conflicts with the submission's claim that documentation is complete and accurate and gives catalog users stale compatibility/surface information."
The fix
1.2.3,6 commands, 3 hooksextension.yml1.2.2→1.2.3; CHANGELOG[1.2.3]The guard (the part that matters)
test_readme_header_matches_the_manifestpins the README header toextension.yml— the same conform-or-fail disciplinetest_citation_contract.pyandtest_domain_schema.pyalready apply to the published vocabulary and domain schema. A repo whose whole purpose is detecting drift between a published artifact and the truth had an undetected drift in its own front page.Verified red-first: fails on a deliberately stale header, passes on the corrected one.
Why a new version rather than re-tagging
The
v1.2.2archive ships that stale README, so fixing onlymainwould leave anyone installing the tagged release with wrong docs. A published tag is an immutable artifact and silently moving one is precisely the drift this extension exists to detect — so this is a fresh patch release.Checks
uv run pytest -q→ 316 passed (315 + the new guard)