fix(ci): make Release single-flight and idempotent to end double-trigger 422s

[joshua-temple]

Problem

The Release workflow is triggerable three ways (push: tags: v*, release:, and workflow_dispatch) with no concurrency group. The redundancy is intentional (#86): orchestrate, promote, and auto-promote each dispatch Release explicitly because API-created and CI-skipped tags do not reliably emit push or release events.

When a candidate tag is cut by a real git push (which does emit a push event) and the dispatcher also fires its explicit dispatch, both trigger Release at the same instant. Two parallel runs race GoReleaser; the loser hits 422 already_exists, leaving a red Release run and a stray draft every cycle. This happened for v0.9.1-rc.1 (runs 28800047479 push/success and 28800046933 dispatch/failure, identical createdAt).

Fix

Make the duplicate harmless rather than removing a trigger (the fallback is still required for the inverse failure mode where the push event is suppressed):

• Idempotency guard (primary). A pre-check at the head of the release job skips the build and finishes green when a live, non-draft release already carries its checksums.txt manifest for the tag. A belt after GoReleaser (run under continue-on-error) converts a GoReleaser failure into success only when the tag is already published, and fails the job on any other error. The decision core is .github/scripts/release-idempotency.sh, unit tested in internal/release/release_idempotency_test.go (existing-release-with-checksums to skip, draft/no-checksums/absent to build, and the 422-tolerance predicate).
• Global single-flight group. concurrency: { group: release, cancel-in-progress: false }, a constant group rather than one keyed on the tag, enforces the hard invariant that no two releases are ever in flight together and serialises the double-trigger.

Cancel-pending safety analysis

A shared group with cancel-in-progress: false still cancels all-but-the-latest pending run. Trace for a legitimate final publish:

• The final publish run is single, not doubled: auto-promote pushes the final tag with the default GITHUB_TOKEN, whose pushes do not trigger workflows, then dispatches Release once. It is also temporally far from the rc build runs (a full fleet gate, tens of minutes, sits between them), so it enters the release group alone and is not pending behind anything in the normal flow.
• The rc build double-trigger produces exactly two runs (push + dispatch). One runs, one queues; a pending run is only cancelled when a third trigger arrives, which the serialized pipeline does not produce.
• Even in the worst case where a pending publish is superseded, it is never silently dropped: the release job is idempotent, and every dispatcher watches its Release run (auto-promote's watch step surfaces a cancelled run as a failed promote, not a silent skip) and can redispatch. A redispatch re-runs the idempotent job, which publishes if absent or no-ops if already published.

Conclusion: the global group is safe; a legitimate final publish is either not pending, or is recoverable by the idempotent, watched, redispatchable path. No design change away from the global group is needed.

Per-caller trace

• rc-tag push (build rc): serialised with the dispatch; winner publishes, loser idem-skips green.
• orchestrate explicit dispatch (rc build): the loser of the pair; idem-skips or the 422 belt absorbs a simultaneous publish.
• auto-promote dispatch (final publish): single run, temporally isolated; publishes normally.
• promote.yaml dispatch: same single-flight and idempotent semantics.
• hotfix / manual tag push: enters the release group; publishes or idem-skips if already published.
• release: event fallback: same guards apply; a duplicate no-ops.

Verification

• go build ./..., go test ./... (2448 passed), golangci-lint run ./... (no issues), go vet clean.
• actionlint .github/workflows/release.yaml clean; shellcheck clean on the new script.
• New regression tests fail-shape without the script and pass with it.
• Docs updated (release-orchestration.md, new "Release runs once per tag" section). Local Node is v20.20.2 (below 22.12); CI builds the docs site. The addition is plain prose and will not break the build.

Residual risk

The 422 belt runs GoReleaser under continue-on-error, so a GoReleaser failure is only surfaced by the follow-up confirm step. That step fails the job on any failure other than an already-published tag, so real failures still red the run.