Skip to content

fix: README header advertised a stale surface; pin it to the manifest (1.2.3) - #21

Merged
ashbrener merged 1 commit into
mainfrom
fix/readme-version-surface
Aug 12, 2026
Merged

ashbrener merged 1 commit into
mainfrom
fix/readme-version-surface

Conversation

@ashbrener

Copy link
Copy Markdown
Owner

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.md line 7 read:

Version: 1.1.0 · Requires: spec-kit ≥ 0.1.0 · License: MIT · Provides: 5 commands, 3 hooks

…while extension.yml was 1.2.2 with 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

  • README header → 1.2.3, 6 commands, 3 hooks
  • extension.yml 1.2.2 → 1.2.3; CHANGELOG [1.2.3]

The guard (the part that matters)

test_readme_header_matches_the_manifest pins the README header to extension.yml — the same conform-or-fail discipline test_citation_contract.py and test_domain_schema.py already 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.2 archive ships that stale README, so fixing only main would 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)

… (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.
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