release

/release — cut one clean, signed release

Releases are tag-driven: the version comes from git describe --tags, and pushing a v* tag fires .github/workflows/release.yml → GoReleaser builds every OS/arch and publishes a public, cosign-signed GitHub Release (binaries + checksums.txt + build provenance) that install.sh serves. The tag push is the point of no return — everything before it is local and reversible; after it, the artifacts are public. Don't poke at the Makefile/workflow each time — this is the contract; follow it.

1. Pre-flight — is there anything real to ship?

• On main, clean tree, not behind origin/main (the only ahead commits should be your own release prep). Broad free gate green for the executable candidate: make check. A later changelog-only finalization/reopening uses the actual notes/docs checks; do not repeat unchanged local broad proof. The exact-tag release workflow still runs all free CI checks.
• The gate is free and deterministic. Live-provider suites run on demand and are not release permission; do not request a waiver or run paid models to finalize a version.
• Identify the latest published, non-draft, non-prerelease version with gh release list --limit 100 --json tagName,isDraft,isPrerelease,publishedAt before comparing changes. A local or failed tag is not a published release.
• Refuse a no-op. git diff --stat <latest-published-tag>..main — if it touches only CHANGELOG.md/docs (no code), STOP: the binary would be byte-identical to the last release. The fix is almost always changelog attribution, not a new version — move the entry under the release where the code actually shipped (git tag --contains <commit> shows which one already has it). Cutting a version for unchanged code misdates the feature.
• The ## Unreleased entries ARE the release. Empty ⇒ nothing to cut; say so and stop.
• Write the GitHub release body in .github/release-notes.md, under ## <version>: a short summary of the most important changes in plain English, not every changelog item. Explain user benefits, keep essential upgrade warnings, and end with the full-changelog compare link against the previous published release. The release workflow publishes that section as is, so the page is never edited by hand afterwards. Preserve every detailed entry since 10.1.2 in CHANGELOG.md; older releases are kept at the v11.3.0 tag, which its last line links.
• Public notes describe product changes, compatibility and user actions. Operator approvals, waivers, test/review diaries, spend details and CI troubleshooting belong in gitignored task records, never the public changelog or release body. Keep real functional limits accurate; removing process narration must not invent validation or capabilities. Follow .agent/kb/rules/public-release-notes-are-product-focused.md.
• Optional dry-run: make snapshot (GoReleaser --snapshot --clean --skip=sign, no publish; signing is CI-only keyless OIDC) to catch config breakage before any tag exists.

2. Pick the version (semver — or take the user's)

• Latest: the published version established in pre-flight, not the highest local Git tag.
• Bump by what's in Unreleased: new functionality → minor x.Y.0; fixes/hardening only → patch x.y.Z; a breaking change → major. A version the user named wins.
• Guard: the tag must not already exist and must sort after the latest.
• Move all unpublished attempt entries into Unreleased before finalizing; preserve their change descriptions, correcting only behavior superseded before publication. Only the version that actually ships gets a numbered release entry. Release notes and full-changelog links compare against the previous published release; do not let GitHub choose an unpublished tag as baseline.

3. Finalize + tag (all local, still reversible)

• Rename ## Unreleased → ## <version> (NO date — house format is a bare ## X.Y.Z) and delete the placeholder comment under it; it lives only under ## Unreleased. Keep entries as - **Bold headline.** explanation.
• Replace .github/release-notes.md's section with the new ## <version> summary (keep the comment at its top).
• Commit only those two files: changelog: finalize <version> (<one-line summary>).
• Annotated tag on THAT finalize commit: git tag -a "v<version>" -m "v<version>" (tags are annotated and point at the finalize commit, never the re-open commit).
• Still on that commit, run the release workflow's own check: go run ./tools/releasenotes notes "v<version>" prints the summary it will publish, or refuses as the workflow would (tag not at HEAD; the changelog section or the summary unfinalized, for another version, empty or malformed). Fix and re-tag locally rather than push a tag that fails publication.
• Re-open: add a fresh ## Unreleased + the placeholder comment back; commit changelog: open an Unreleased section after v<version>.

4. Push — public, irreversible: CONFIRM FIRST

• Show the user the version, the one-line summary, and that this publishes a public signed release. Get an explicit go-ahead — this is the one outward-facing, hard-to-undo step.
• Then: git push origin main && git push origin "v<version>".
• Watch it land: gh run watch (or gh run list --workflow=release.yml), then gh release view "v<version>" to confirm the assets + checksums.txt uploaded.

5. If it breaks

• Failed before publishing? Delete the tag both sides (git tag -d "v<version>", git push origin ":v<version>"), restore its changes under Unreleased, fix, retry. Verify no public release/assets exist first and retain the exact tag identity in task artifacts.
• Already published? Never rewrite a public tag — roll forward with a follow-up patch.