feat: derive versions from git tags and cut releases from CI

[bandrel]

Adds tag-driven release versioning, a --version flag, and opt-in update checking.

What this does

• tools/next_version.py owns the entire version policy, in Python where it can be unit-tested rather than in YAML where it cannot. Any feat: commit (or a ! subject / BREAKING CHANGE: footer) since the last final tag takes the batch to X.(Y+1).0; a batch of only fixes, docs and chores takes it to X.Y.(Z+1). The major is never bumped automatically — a breaking marker counts as a feature, because an automatic major is an irreversible published mistake one mistyped subject line away. Push a major by hand and release.yml publishes it.
• A tag job in ci.yml cuts vX.Y.ZrcN candidates on nightly and promotes the same target to vX.Y.Z plus a GitHub release on main. Aiming candidates one version forward is what makes them sort correctly: 0.0.0 < 0.1.0rc1 < 0.1.0 < 0.2.0rc1 < 0.2.0.
• hatch-vcs replaces the static version = "0.1.0", so the package version is whatever tag the artifact was built from and there is no second copy to drift.
• --version reads installed distribution metadata, printing unknown (running from source) from a checkout.
• --check-update is an on-demand check. The launch-time check is off unless explicitly enabled via check_for_updates in config.json, and an absent key means off.

Two deliberate departures from hate_crack

Update checking defaults to off. hate_crack's check_for_updates defaults to True and calls api.github.com on every launch. SpooNMAP runs from jumpboxes inside client networks, where that is an unauthorised outbound beacon from an engagement host. A test patches the gate and asserts it is never called under a default config, so this cannot regress silently.

Tagging lives inside ci.yml, not in workflow_run-triggered workflows. That was the original design and it was rejected: zizmor — already a required job here — rates workflow_run an error-level dangerous trigger and exits 14, and this repo does not silence findings with ignore comments. A needs-gated job buys the same "only tag what passed CI" guarantee without the trigger, and drops two footguns along the way (the head_sha checkout dance, and the rule that the workflow had to live on the default branch).

What is guarded, and why

tests/test_release_versioning.py exists because this wiring fails silently — no error, tags just stop appearing or appear wrong. Mutation testing during development found seven guards that did not guard, including two that would have shipped:

• Swapping the channel branches would have cut final releases on nightly and published them, with all 20 tests passing.
• Renaming a $GITHUB_OUTPUT key would have produced a permanent green check with zero tags, forever.

Both now fail loudly, as do a reverted fetch-depth, a dropped needs entry, a missing nightly push trigger, a widened if:, and a push that moves anything other than the one computed tag. The behavioural guards extract the step script from the YAML and run it against a real git repo and a real bare remote, because substring assertions on YAML proved defeatable.

First run

The repo has no tags and this history contains feat: subjects, so the first push to nightly treats the whole history as one batch and cuts v0.1.0rc1; the first merge to main then cuts v0.1.0.

Verification

1160 passed, 8 skipped, 100% coverage. ruff, bandit (33 findings, unchanged — the one addition is a reviewed B310 on a hardcoded-https urlopen, baseline regenerated deliberately rather than suppressed inline), uv lock --check, actionlint and zizmor all exit 0. No inline suppressions were added anywhere.

🤖 Generated with Claude Code