THE ROOT CAUSE WAS A MISSING DOCUMENT, NOT A MISSING CHECK. Nothing in this repo
said "bump the version before you tag": release.yml is cargo-dist's autogenerated
mechanism, README's Installation section describes the result, and plan.md
Phase 3 carries one-time SETUP instructions from the launch plan. So the
preflight added in the previous commits is the second half of the fix. RELEASING.md
is the first, and it is a checklist rather than an explanation -- the reasoning
stays in context/code/tooling.md section 4, because a checklist followed at 2am
is not read for its argument and one carrying it does not get followed. Its own
file rather than a README section because README Installation addresses someone
INSTALLING and this addresses the one person PUBLISHING.
THE DIAGNOSIS WAS UNDERSTATED AND IS NOW CORRECTED AT THE SOURCE. The earlier
passage rested on a local `dist plan` run, which is the weaker half. v0.1.0-rc1
and v0.1.0-rc2 both carry COMPLETE published GitHub Releases from 2026-04-11 --
all four targets, .sha256 files, sha256.sum, dist-manifest.json, source.tar.gz
and improvise-installer.sh. The workflow is not merely expected to work; it
demonstrably ran end to end the last time a tag and the version agreed.
Nearly the opposite was concluded from an empty `gh run list`: Actions logs age
out at 90 days and those tags are five months old. An empty log is a statement
about RETENTION, not about history -- the artefact a run published outlives the
run, so ask the releases before asking the runs.
AND THE MISTAKE IS RECURRENT, which is the real argument for writing a procedure
down. `gh run list --workflow=release.yml --event=push` keeps the whole tag
history: rc1 FAILED TWICE (14s each) before succeeding on the third push
(3m25s), rc2 succeeded first time (3m9s), rc3 failed (21s). Three occurrences
across two releases, all the same version/tag disagreement. A one-off justifies
a note; a third justifies a document and a check before the irreversible step.
The failure signature is recorded because it is cheap to read and easy to
misread: `plan` fails in ~20s with the four jobs behind it skipped -- verified
on the rc3 run, where plan is `failure` and build-local-artifacts,
build-global-artifacts, host and announce are all `skipped` -- against ~3
minutes for a real build. The workflow ALSO triggers on pull_request, where it
plans without a tag and passes in ~20s, so a green 20s run on a PR and a failed
20s run on a tag look alike at a glance and mean opposite things.
Every claim above was read off `gh`, not inferred. Step 5 of RELEASING.md said
"if plan succeeds and the four jobs skip" in a first draft; the run says plan
FAILS, and it was corrected rather than kept as a plausible-sounding shape.
No version bumped, no tag cut, no tag deleted, the rc1/rc2 releases untouched.
Whether the stale rc tags are ever removed is left as the user's call and
deliberately not made a step: it is not part of cutting a release, and the
principle that covers it -- a published tag is not moved -- is stated.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Edward Langley