Story 4: Guard the released version against its git tag (#363)

[Polichinel]

Part of #421. Closes #363 when done.

Context

#363, filed earlier and standing alone, is a fails-green defect and belongs in this epic:

Release version can drift from the git tag with no guard (same gap views-faoapi hit at go-live)

Nothing enforces that [project].version in pyproject.toml equals the tag it was released under. The failure is silent in the worst way: PyPI would carry a package whose metadata says one version while the git history says another, and the mismatch is only discoverable by someone comparing them by hand.

The publish workflow has a version guard, but it only checks that the version beats what is on PyPI — not that it matches the tag being released.

Today this holds by discipline. It has held so far because the release ritual is followed carefully, which is exactly the kind of assurance this epic exists to replace.

Work

Two layers, because they catch it at different moments:

1. A test — tests/test_falsification_deploy_v160.py already has TestF1VersionBumped. Add a sibling: when HEAD is exactly on a v* tag, [project].version must equal that tag minus the v. When HEAD is not on a tag, skip with a reason (per this file's C-320 idiom — do not guess).

2. A workflow check — in publish_package.yml, before the build: assert github.ref_name (the tag that triggered the release) matches [project].version. Fail loudly with both values in the message. This is the last moment before an immutable artifact is published, and unlike the test it cannot be skipped.

WET. Two checks, two places, deliberately. They answer the same question at different times — one during development, one at the point of no return. Do not factor them into a shared helper.

Acceptance criteria

• Test asserts tag ↔ version equality when on a tag; skips with a reason otherwise
• publish_package.yml fails before build on mismatch, printing both values
• Neither can be satisfied by editing only one of the two sources
• Full suite green; workflow YAML parses

Validation — drill both

• With HEAD on v1.11.0 and pyproject.toml temporarily set to 1.11.1 → test fails. Revert.
• With HEAD not on a tag → test skips, with a readable reason
• Simulate the workflow check locally with github.ref_name=v9.9.9 against the real version → fails, printing both

Record all three in the PR.

Files

tests/test_falsification_deploy_v160.py · .github/workflows/publish_package.yml · docs/guides/publishing_to_pypi.md (note the guard in §C)

Dependencies

None. Independent of Stories 1–3.

Note

The tag ruleset makes v* tags immutable — no deletion, no update, no bypass. That is precisely why the workflow check matters more than the test: after the tag exists, a mismatch cannot be corrected, only superseded by a new version.

[Polichinel]

Done — merged as a7e8e49 (#436).

TestF1VersionBumped could not fail in any state (XFAIL when the version is tagged, XPASS when it is not, exit 0 either way), because version is bumped only at release time — so between releases the version is always a tag that exists. Deleted, and replaced by:

• TestVersionMatchesItsTag — if HEAD is on a v* tag, the version must equal it. Drilled to a real rc=1 failure in a worktree at v1.11.0.
• A guard in publish_package.yml comparing github.ref_name to the version before the build. Unskippable, and drilled both directions.

C-341 resolved — this gate was its last residue.

Two findings beyond the issue's scope, both recorded: four surviving copies of the same assertion use a conditional xfail that is circular (runs only when the version is untagged, then asserts it is untagged) — registered as C-346. And the publish guard's first version read the version with bare python3 -c "import tomllib", which needs Python ≥3.11; pinned to uv run --no-project --python 3.12. That one would have surfaced at a release, against an immutable tag.

Review also caught a fails-green in the replacement: git describe --exact-match returns one tag and a commit can carry several, so a stray non-v tag would hide the release tag and make the test skip exactly when a mismatch was present. Switched to git tag --points-at.