feat: auto-update CHANGELOG.md on each release (option A)

[fiunchinho]

Summary

PoC for option A from the CHANGELOG-auto-update design discussion: extend the push-based auto-release workflow to also keep CHANGELOG.md in sync with each release. After gh release create succeeds, the workflow splices the rendered release notes into CHANGELOG.md and pushes the resulting commit back to the branch.

Validates the design before propagating to muster (#795 in muster repo) and the other migration repos.

Base branch: this PR targets polish-auto-release-template (PR #17 in this repo) so the diff stays focused on the changelog work. Once #17 merges, the base will roll up to main automatically.

Design

Splice, not regenerate. Pre-existing history in CHANGELOG.md (v1.0.0 and earlier) is preserved verbatim — a full git-cliff --output regenerate would only see commits back to where conventional commits started, losing older release-please entries. So we use an insertion-marker approach:

# Changelog

All notable changes to this project will be documented in this file.
...

<!-- auto-release: insert below -->        <-- new sentinel

## 1.0.0 (2026-06-01)                      <-- pre-existing history below, untouched
...

On each release, the workflow:

1. Renders the new release section (version header + the same Added / Fixed / Changed / Security bullets that go into the GitHub Release) into a temp file.
2. awk-splices it into CHANGELOG.md directly under the marker, so newest releases land at the top.
3. Commits with chore: update CHANGELOG.md for vX.Y.Z [skip ci] and pushes.

Loop protection (two layers):

• [skip ci] in the commit message prevents the auto-release workflow (and CircleCI) from running on the chore commit itself.
• A new cliff.toml commit_parsers rule (^chore: update CHANGELOG\.md -> skip) ensures that even if the chore commit ends up inside a future --unreleased range, git-cliff filters it out of both the version bump computation and the rendered notes. Placed before the general ^chore rule (first match wins).

Race protection: The concurrency group serializes auto-release jobs against each other but not against human pushes. The commit-back step does git pull --rebase origin "$BRANCH" before git push to handle the narrow window between job start and push. If rebase fails (genuine conflict on CHANGELOG.md, exotic), the step errors out — the release tag and GitHub Release are already created, so nothing is half-finished; the next release re-splices.

Validation plan (the whole point of this PR)

This is the PoC for the muster PR (giantswarm/muster#795). The intent is to land this here first, then validate end-to-end by:

1. Branch protection: confirm github-actions[bot] is in the bypass list (or adjust as needed) so the push step doesn't 403.
2. Merge this PR.
3. Land a conventional commit (feat: / fix:) on main.
4. Watch the workflow:
   • new tag + GitHub Release created
   • new section appears in CHANGELOG.md directly under the marker
   • chore commit lands with [skip ci] and DOESN'T trigger another auto-release run
5. Land a second conventional commit.
6. Confirm the previous release's chore commit is NOT in the new release's notes or version bump (validates the cliff.toml skip rule).

If all green, propagate the same fix to giantswarm/muster#795 status as "tested upstream" and unblock its review.

Required: branch-protection bypass for github-actions[bot]

This repo's main branch protection (from the release-please-approver work) requires PR review — the bot is currently allowed via the app's bypass entitlement, so this should Just Work here. If not, the symptom will be a 403 at git push origin HEAD:main in the commit-back step.

Out of scope

• Once validated, the workflow + cliff.toml changes become the new source-of-truth template that gets propagated to muster, mcp-kubernetes, klaus-operator, klausctl, and eventually devctl.