Reconcile release docs and fix a release-provenance retry bug

[gitkodak]

Summary

• Reconciled RELEASING.md, CHANGELOG.md and CLAUDE.md against actual repo/Jira/GitHub state:
  • RELEASING.md step 7 still said git push origin main, which now fails outright under the branch protection KAN-192 added; rewrote it to push a branch, open a PR, wait for required checks, then tag.
  • RELEASING.md's closing section claimed GitHub Release artifact-attachment was still undecided, contradicting its own step 9 (which already does it, shipped at 0.10.0).
  • CHANGELOG.md dated 0.11.1 a day ahead of the release commit's local date; regenerated the man page (make docs) since its header date derives from that entry.
  • CLAUDE.md claimed the GitHub repo description matches pyproject.toml; it doesn't (deliberately, per discussion) — rewrote the paragraph to say so.
  • Jira (KAN-114/KAN-144 children) matched TODO.md/CLAUDE.md throughout, so no ticket-status changes were needed.
• Fixed a real bug in release-provenance.yml found by external review: a workflow_dispatch retry against a release that already carries .intoto.jsonl attestation bundles would download those too, attest them, and re-upload them as wheel.intoto.jsonl.intoto.jsonl, growing the release assets on every retry. Fixed by selecting only the three intended artifact types (*.whl, *.tar.gz, unifi-map.1) instead of downloading everything.

Test plan

• make check (ruff format/lint + 681 tests) passes clean
• make docs produces no further changes (man page/flag reference regenerated and committed)
• make build produces a working wheel/sdist, both containing the man page
• Reviewed on validate before this PR
• Two independent reviews of the two commits found no remaining issues

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[greptile-apps]

Greptile Summary

The PR reconciles release documentation and generated man-page metadata with current repository state, and narrows provenance downloads to wheel, sdist, and man-page assets.

• Excludes existing attestation bundles when retrying release provenance generation.
• Updates the protected-branch release procedure and clarifies GitHub Release versus PyPI policy.
• Corrects the 0.11.1 date in the changelog and generated man page.
• Documents the intentional difference between package and GitHub repository descriptions.

Confidence Score: 4/5

The release instructions should be corrected before merging because the documented post-squash pull can fail or place the release tag on a commit outside origin/main.

After a squash merge, the local release commit and remote squash commit are divergent, so pulling before tagging does not reliably put local HEAD at the commit on origin/main.

Files Needing Attention: RELEASING.md

Important Files Changed

Filename	Overview
.github/workflows/release-provenance.yml	Restricts release downloads to the three intended artifact types, preventing recursive attestation of existing bundles.
RELEASING.md	Updates the protected-branch release flow, but the post-squash pull can fail on divergent histories or tag a local merge commit rather than origin/main.
CHANGELOG.md	Corrects the 0.11.1 release date to match the release commit’s local date.
unifi-map.1	Regenerates the man-page header consistently with the corrected changelog date.
CLAUDE.md	Documents the intentional divergence between the GitHub repository description and package-facing descriptions.

_{Reviews (1): Last reviewed commit: "Stop a release-provenance retry from re-..." | Re-trigger Greptile}

[greptile-apps]

Tag targets a divergent local commit

After the release PR is squash-merged, the local release commit and the new squash commit on origin/main have diverged. git pull origin main therefore either stops for a reconciliation strategy or creates a local merge commit, causing the tag to miss the actual commit on origin/main.

Suggested change

	git checkout main && git pull origin main
	git tag -a vX.Y.Z -m "…" # annotated, summarising the headline changes
	git fetch origin main
	git tag -a vX.Y.Z origin/main -m "…" # annotated, summarising the headline changes

Context Used: CLAUDE.md (source)