diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 9f0b1bd..49136e7 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -19,7 +19,7 @@
 ## Changelog
 
 <!-- CRITICAL: This section is the source of truth for CHANGELOG.md.
-     generate-changelog.sh extracts these categorized bullets verbatim
+     generate-changelog.py extracts these categorized bullets verbatim
      into the release changelog. Write carefully. This IS the changelog.
 
      AUDIENCE: Users and operators. Write from their perspective.
diff --git a/RELEASES-RATIONALE.md b/RELEASES-RATIONALE.md
index beee770..5a96f36 100644
--- a/RELEASES-RATIONALE.md
+++ b/RELEASES-RATIONALE.md
@@ -32,7 +32,7 @@ on both sides with different content. Always branch from `origin/main` and cherr
 
 Branch naming `release/v<version>` or `release/v<version>-<slug>` (e.g. `release/v0.1.0`,
 `release/v0.2.0-python-checks`) makes release branches sortable and unambiguous when multiple cuts are in flight. The
-`v<version>` prefix is required: `scripts/generate-changelog.sh` extracts the version from the branch name. Slug is
+`v<version>` prefix is required: `scripts/generate-changelog.py` extracts the version from the branch name. Slug is
 kebab-case, short, descriptive.
 
 ## PR body conventions
@@ -121,7 +121,7 @@ prior squash, it's a false positive (no action). Otherwise cherry-pick the commi
 
 ### Generated, never hand-written
 
-`scripts/generate-changelog.sh` (with `cliff.toml`) is the only sanctioned way to update `CHANGELOG.md`. The script runs
+`scripts/generate-changelog.py` (with `cliff.toml`) is the only sanctioned way to update `CHANGELOG.md`. The script runs
 `git-cliff` to prepend a versioned entry for commits since the last tag, then walks each squash-merged PR's body to
 extract the `## Changelog → ### Added / Changed / Fixed / Documentation` subsections, replacing the auto-generated
 bullets with the curated PR-body content (with author and PR-link attribution).
@@ -212,7 +212,7 @@ Scrub-before-submit (author in `/tmp/`, scrub there, submit via `--body-file`) a
 edit, scrub again". Every fix lands locally and the public PR sees only clean text. The auto-format hook skips `/tmp/`
 paths so the body keeps its authored shape and no soft-wrapping is injected.
 
-For a `CHANGELOG.md` finding, fix the upstream PR body (which `generate-changelog.sh` re-fetches every run) and
+For a `CHANGELOG.md` finding, fix the upstream PR body (which `generate-changelog.py` re-fetches every run) and
 regenerate. Hand-editing `CHANGELOG.md` directly produces drift the next regeneration overwrites.
 
 ## Branch protection
diff --git a/RELEASES.md b/RELEASES.md
index 524a8ae..e09fdc8 100644
--- a/RELEASES.md
+++ b/RELEASES.md
@@ -79,7 +79,7 @@ Engineering docs (`docs/plans/`, `docs/solutions/`, `docs/brainstorms/`, `docs/r
 isn't `release/*`.
 
 **Branch naming**: `release/v<version>` or `release/v<version>-<slug>` (e.g. `release/v0.1.0`,
-`release/v0.2.0-python-checks`). The `v<version>` prefix is required: `scripts/generate-changelog.sh` extracts the
+`release/v0.2.0-python-checks`). The `v<version>` prefix is required: `scripts/generate-changelog.py` extracts the
 version from the branch name.
 
 ```bash
@@ -121,7 +121,7 @@ git add src/skill_install/skill.json && \
     git commit -m "chore(skill): refresh fixture for v0.2.0" || true
 
 # 8. Generate CHANGELOG.md (auto-detects version from branch name; CI enforces this).
-./scripts/generate-changelog.sh
+./scripts/generate-changelog.py
 
 # 9. Scrub CHANGELOG.md via Vale + LanguageTool + unslop. See § Prose scrubbing.
 #    Fix findings on upstream PR bodies, never by hand-editing CHANGELOG.md. When clean:
@@ -257,7 +257,7 @@ lt_check /tmp/body.md
 
 # 6. Apply the cleaned version.
 gh pr edit <num> --body-file /tmp/body.md     # for PR body edits
-# ./scripts/generate-changelog.sh             # for CHANGELOG.md (re-runs the PR-body fetch from GitHub)
+# ./scripts/generate-changelog.py             # for CHANGELOG.md (re-runs the PR-body fetch from GitHub)
 ```
 
 For a `CHANGELOG.md` finding, fix the upstream PR body and regenerate. Hand-editing `CHANGELOG.md` directly produces
diff --git a/docs/plans/2026-04-02-002-feat-release-infrastructure-plan.md b/docs/plans/2026-04-02-002-feat-release-infrastructure-plan.md
index 2e73d22..d3ddf34 100644
--- a/docs/plans/2026-04-02-002-feat-release-infrastructure-plan.md
+++ b/docs/plans/2026-04-02-002-feat-release-infrastructure-plan.md
@@ -45,7 +45,7 @@ files and channels, and this plan closes every gap.
 
 - `~/.claude/skills/rust-tool-release/SKILL.md` — canonical release standard
 - `~/.claude/skills/rust-tool-release/scripts/generate-completions.sh` — generates `completions/` directory
-- `~/.claude/skills/rust-tool-release/scripts/generate-changelog.sh` — generates `CHANGELOG.md` from git-cliff + PR body
+- `~/.claude/skills/rust-tool-release/scripts/generate-changelog.py` — generates `CHANGELOG.md` from git-cliff + PR body
   expansion
 - `~/dev/bird/RELEASING.md` — reference RELEASING.md
 - `~/dev/bird/README.md` — reference README with all 5 install channels
@@ -68,7 +68,7 @@ files and channels, and this plan closes every gap.
   this.
 - **Generate completions locally, commit to repo**: Per `rust-tool-release` standard, completions are
   platform-independent text files committed to `completions/`. Not generated in CI.
-- **CHANGELOG via generate-changelog.sh**: Uses git-cliff + PR body `## Changelog` section expansion. This is the
+- **CHANGELOG via generate-changelog.py**: Uses git-cliff + PR body `## Changelog` section expansion. This is the
   standard tooling, not manual editing.
 - **Release branch from main, not dev**: Per the release branch pattern, `guard-main-docs.yml` blocks docs paths. The
   release branch cherry-picks non-docs commits from dev.
@@ -82,7 +82,7 @@ files and channels, and this plan closes every gap.
 
 ### Deferred to Implementation
 
-- **Exact CHANGELOG content**: `generate-changelog.sh` will produce the content from PR bodies. The quality depends on
+- **Exact CHANGELOG content**: `generate-changelog.py` will produce the content from PR bodies. The quality depends on
   how well the PR `## Changelog` sections were written.
 
 ## Implementation Units
@@ -135,8 +135,8 @@ Unblocks the release archive step.
 
 **Dependencies:** None
 
-**Status:** Shipped as `RELEASES.md` (canonical template renamed from `RELEASING.md` — see bird commit
-`da19ad5 docs: rename RELEASING.md to RELEASES.md and align with canonical template`).
+**Status:** Shipped as `RELEASES.md` (canonical template renamed from `RELEASING.md` — see bird commit `da19ad5 docs:
+rename RELEASING.md to RELEASES.md and align with canonical template`).
 
 **Files:**
 
@@ -169,9 +169,9 @@ Unblocks the release archive step.
 
 **Dependencies:** None
 
-**Status:** Shipped with 4 of 5 channels (Homebrew, `cargo install`, `cargo binstall`, pre-built binaries from
-GitHub Releases). "From source" (`git clone && cargo build --release`) is omitted — trivial for Rust users and implicit.
-If strict 5-channel coverage is required, add a one-line bullet in a follow-up.
+**Status:** Shipped with 4 of 5 channels (Homebrew, `cargo install`, `cargo binstall`, pre-built binaries from GitHub
+Releases). "From source" (`git clone && cargo build --release`) is omitted — trivial for Rust users and implicit. If
+strict 5-channel coverage is required, add a one-line bullet in a follow-up.
 
 **Files:**
 
@@ -271,7 +271,7 @@ If strict 5-channel coverage is required, add a one-line bullet in a follow-up.
 
 - [x] **Unit 6: Generate CHANGELOG.md for v0.1.0 (on release branch)**
 
-**Goal:** Populate CHANGELOG.md with v0.1.0 release notes using `generate-changelog.sh`.
+**Goal:** Populate CHANGELOG.md with v0.1.0 release notes using `generate-changelog.py`.
 
 **Requirements:** R3, R7
 
@@ -286,7 +286,7 @@ If strict 5-channel coverage is required, add a one-line bullet in a follow-up.
 - This happens on the release branch during release prep, NOT on dev
 - Create `release/v0.1.0` from `origin/main`
 - Cherry-pick non-docs commits from dev
-- Run `~/.claude/skills/rust-tool-release/scripts/generate-changelog.sh`
+- Run `~/.claude/skills/rust-tool-release/scripts/generate-changelog.py`
 - The script auto-detects version from branch name
 - Commit CHANGELOG.md as part of the release PR to main
 - After PR merges: `git tag v0.1.0 && git push origin main --tags`
@@ -297,7 +297,7 @@ If strict 5-channel coverage is required, add a one-line bullet in a follow-up.
 
 **Test scenarios:**
 
-- Happy path: `generate-changelog.sh` produces a CHANGELOG.md with a `## [0.1.0]` section
+- Happy path: `generate-changelog.py` produces a CHANGELOG.md with a `## [0.1.0]` section
 - Happy path: CHANGELOG.md content includes PR links and author attribution
 - Error path: script fails if `cliff.toml` is misconfigured — verify `[remote.github]` section exists
 
@@ -318,12 +318,12 @@ If strict 5-channel coverage is required, add a one-line bullet in a follow-up.
 
 ## Risks & Dependencies
 
-| Risk | Mitigation |
-| --- | --- |
-| `generate-completions.sh` doesn't support the crate/bin name split | Crate ships a single `anc` bin; run the script once against `anc` |
-| `generate-changelog.sh` produces empty output (squash-merge history) | The script uses git-cliff on cherry-picked commits (which are individual conventional commits), not squash-merged ones |
-| Homebrew formula pre-seed conflicts with first real release | Use `v0.0.0` placeholder per documented pattern |
-| `cargo publish` fails on first run (Trusted Publishing not configured) | First publish must be manual with `CARGO_REGISTRY_TOKEN` |
+| Risk                                                                   | Mitigation                                                                                                             |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `generate-completions.sh` doesn't support the crate/bin name split     | Crate ships a single `anc` bin; run the script once against `anc`                                                      |
+| `generate-changelog.py` produces empty output (squash-merge history)   | The script uses git-cliff on cherry-picked commits (which are individual conventional commits), not squash-merged ones |
+| Homebrew formula pre-seed conflicts with first real release            | Use `v0.0.0` placeholder per documented pattern                                                                        |
+| `cargo publish` fails on first run (Trusted Publishing not configured) | First publish must be manual with `CARGO_REGISTRY_TOKEN`                                                               |
 
 ## Sources & References
 
@@ -346,8 +346,8 @@ Plan audited against repo state. Resolved: Units 1, 2, 3. Remaining: Units 4, 5,
 - Unit 5 (stale branch cleanup) — NOT done; 6 stale `origin/*` branches remain (enumerated in Unit 5 body).
 - Unit 6 (CHANGELOG v0.1.0) — NOT done; `CHANGELOG.md` is a 1-line header. No `v0.1.0` tag exists.
 
-Next action: Unit 4 (Homebrew formula pre-seed) is the smallest independent piece. Unit 6 blocks the actual release
-and must happen on a `release/v0.1.0` branch, not on `dev`. Unit 5 is trivial housekeeping.
+Next action: Unit 4 (Homebrew formula pre-seed) is the smallest independent piece. Unit 6 blocks the actual release and
+must happen on a `release/v0.1.0` branch, not on `dev`. Unit 5 is trivial housekeeping.
 
 ### 2026-04-16
 
@@ -384,7 +384,7 @@ All 6 units complete. v0.1.0 released successfully through the full pipeline:
 
 - Release branch cherry-picked 13 commits from dev, excluding guarded docs/plans/ paths
 - Cargo.toml already at 0.1.0, completions already fresh -- no bump or regen needed
-- CHANGELOG.md generated via generate-changelog.sh with PR body expansion
+- CHANGELOG.md generated via generate-changelog.py with PR body expansion
 - PR #18 merged to main, all 9 CI checks passed
 - Alpha v0.1.0-alpha.1 published manually to establish crate on crates.io
 - Trusted Publishing configured, then annotated tag pushed
@@ -392,5 +392,5 @@ All 6 units complete. v0.1.0 released successfully through the full pipeline:
 - homebrew-tap: formula update PR, bottle builds (3 platforms), publish, finalize-release all succeeded
 - make_latest flipped to true. All channels live.
 
-Post-release: two CE todos filed for monorepo discovery (006) and multi-language support (007),
-discovered during RC testing against bird, xr, and markitdown.
+Post-release: two CE todos filed for monorepo discovery (006) and multi-language support (007), discovered during RC
+testing against bird, xr, and markitdown.
diff --git a/docs/plans/2026-04-28-001-feat-show-hn-launch-readiness-plan.md b/docs/plans/2026-04-28-001-feat-show-hn-launch-readiness-plan.md
index a956cc6..f69663f 100644
--- a/docs/plans/2026-04-28-001-feat-show-hn-launch-readiness-plan.md
+++ b/docs/plans/2026-04-28-001-feat-show-hn-launch-readiness-plan.md
@@ -258,7 +258,7 @@ None applicable — this is repo-internal release choreography.
 **Approach:**
 
 - Resolve Q-CLI1 first (MINOR vs PATCH). Recommendation MINOR (`v0.2.0`).
-- Run `scripts/generate-changelog.sh` if the project uses it for changelog generation, otherwise hand-edit per the
+- Run `scripts/generate-changelog.py` if the project uses it for changelog generation, otherwise hand-edit per the
   existing CHANGELOG voice.
 - The version-string-on-`dev` note: `Cargo.toml` shows `version = "0.1.0"` even though tags `v0.1.1`/`v0.1.2`/`v0.1.3`
   exist. This is consistent with prior release branches doing the bump on the `release/*` branch rather than `dev`.
@@ -641,7 +641,7 @@ Run in order. The first three steps are HARD GATES — do not advance past a fai
 1. ☐ Cut `release/launch` from `dev` HEAD: `git switch -c release/launch dev`.
 2. ☐ On `release/launch`: bump `Cargo.toml` version `0.1.0 → 0.2.0`; `cargo build` regenerates `Cargo.lock`; commit as
    `chore: bump version to 0.2.0` per the established pattern (`a1b3bfd` for v0.1.3).
-3. ☐ Generate CHANGELOG entry for `v0.2.0`: `scripts/generate-changelog.sh` (or `git cliff --tag v0.2.0 --unreleased`
+3. ☐ Generate CHANGELOG entry for `v0.2.0`: `scripts/generate-changelog.py` (or `git cliff --tag v0.2.0 --unreleased`
    per `cliff.toml`); commit as `docs(changelog): v0.2.0`.
 4. ☐ Open PR `release/launch` → `main` titled `release: v0.2.0` (mirror `release: v0.1.3 (#28)`). Body uses
    `.github/pull_request_template.md` cascade per global CLAUDE.md.
diff --git a/docs/plans/2026-05-07-001-feat-v0.4.0-spec-sync-plan.md b/docs/plans/2026-05-07-001-feat-v0.4.0-spec-sync-plan.md
index 5e4ff8d..c773d9f 100644
--- a/docs/plans/2026-05-07-001-feat-v0.4.0-spec-sync-plan.md
+++ b/docs/plans/2026-05-07-001-feat-v0.4.0-spec-sync-plan.md
@@ -584,7 +584,7 @@ CLI version, and prepare the PR body's `## Changelog` section.
 
 - Prior coverage-matrix regen commits (search `git log --oneline -- coverage/matrix.json` for the shape).
 - Existing CHANGELOG entries — `## [Unreleased]` block accepts the verbatim `## Changelog` body via
-  `generate-changelog.sh` at release time. Do not hand-edit `CHANGELOG.md`.
+  `generate-changelog.py` at release time. Do not hand-edit `CHANGELOG.md`.
 
 **Test scenarios:**
 
diff --git a/docs/plans/2026-06-01-001-feat-p0-mirror-skill-pr25-sync-preconditions-and-changelog-dry-run-plan.md b/docs/plans/2026-06-01-001-feat-p0-mirror-skill-pr25-sync-preconditions-and-changelog-dry-run-plan.md
index 5e2c86f..172c3d9 100644
--- a/docs/plans/2026-06-01-001-feat-p0-mirror-skill-pr25-sync-preconditions-and-changelog-dry-run-plan.md
+++ b/docs/plans/2026-06-01-001-feat-p0-mirror-skill-pr25-sync-preconditions-and-changelog-dry-run-plan.md
@@ -12,20 +12,20 @@ origin: "cross-repo mirror of brettdavies/agentnative-skill PR #25 (merged 2026-
 ## Summary
 
 `agentnative-skill` PR #25 hardened its release flow with two changes to `scripts/sync-dev-after-release.sh` and two
-changes to `scripts/generate-changelog.sh`. The duplicate-section guard from PR #25 already shipped in this repo via
-[CLI PR #68](https://github.com/brettdavies/agentnative-cli/pull/68); the remaining three items still need to land
-here. A follow-up skill PR ([#26](https://github.com/brettdavies/agentnative-skill/pull/26)) fixed a regression the
+changes to `scripts/generate-changelog.py`. The duplicate-section guard from PR #25 already shipped in this repo via
+[CLI PR #68](https://github.com/brettdavies/agentnative-cli/pull/68); the remaining three items still need to land here.
+A follow-up skill PR ([#26](https://github.com/brettdavies/agentnative-skill/pull/26)) fixed a regression the
 `--dry-run` work surfaced in the PR-number extraction regex; mirror that here too.
 
-Reference PRs (read the exact diffs before implementing): <https://github.com/brettdavies/agentnative-skill/pull/25>
-and <https://github.com/brettdavies/agentnative-skill/pull/26>.
+Reference PRs (read the exact diffs before implementing): <https://github.com/brettdavies/agentnative-skill/pull/25> and
+<https://github.com/brettdavies/agentnative-skill/pull/26>.
 
 ## Scope
 
 ### In scope (five items)
 
-1. **`scripts/sync-dev-after-release.sh` — GitHub Release published-state precondition.** Before the existing
-   `tag reachable from origin/main` check, verify the GitHub Release artifact for `$VERSION` exists and is
+1. **`scripts/sync-dev-after-release.sh` — GitHub Release published-state precondition.** Before the existing `tag
+   reachable from origin/main` check, verify the GitHub Release artifact for `$VERSION` exists and is
    published-not-draft:
 
    ```bash
@@ -36,59 +36,57 @@ and <https://github.com/brettdavies/agentnative-skill/pull/26>.
    reachable from `main` is necessary but not sufficient — consumers discover the release via `gh release`, so the
    release artifact must actually exist before the dev-backport commit can claim it does.
 
-2. **`scripts/sync-dev-after-release.sh` — post-sync regen-idempotency check.** After the backport commit is written
-   to `dev`, run:
+2. **`scripts/sync-dev-after-release.sh` — post-sync regen-idempotency check.** After the backport commit is written to
+   `dev`, run:
 
    ```bash
-   scripts/generate-changelog.sh --dry-run --tag "$VERSION"
+   scripts/generate-changelog.py --dry-run --tag "$VERSION"
    ```
 
    Warn (do not fail) when PR bodies have drifted from `main`'s `CHANGELOG.md`. The backport itself is still correct
    against current `main`; drift is a signal that a follow-up release branch should regenerate cleanly, not a reason
    to block the sync.
 
-3. **`scripts/generate-changelog.sh --dry-run` flag.** Stash `CHANGELOG.md`, run the normal generation flow in place,
+3. **`scripts/generate-changelog.py --dry-run` flag.** Stash `CHANGELOG.md`, run the normal generation flow in place,
    print a unified diff to stderr if the regenerated content differs from the stashed copy, restore the original via
-   `trap … EXIT`, exit 0 when idempotent and exit 1 on drift. The `--tag` flag is the existing release-version
-   selector. `--dry-run` is what item 2 above depends on, so land it in the same PR or land it first.
-
-4. **`scripts/generate-changelog.sh` — PR-number extraction regex fix.** Mirror of
-   [skill PR #26](https://github.com/brettdavies/agentnative-skill/pull/26). The current extraction uses
-   `grep -oP '\(#\K\d+'`, which only matches the parenthesized `(#14)` form git-cliff emits on the initial prepend.
-   The script's own Python expansion step rewrites those to markdown-link form `[#14](https://github.com/.../pull/14)`.
-   A second run (e.g. `--dry-run` against an already-processed `CHANGELOG.md`, which is exactly the
-   `sync-dev-after-release.sh` regen-idempotency check's mode of operation — item 2 above) extracts zero PR numbers;
-   with `set -euo pipefail`, grep's exit-1-on-no-match aborts the script with empty output before
-   `summarize_and_exit` can run. Change the regex to `[\(\[]#\K\d+` (accepts both forms) and append `|| true` so the
-   downstream `[[ -z "$PR_NUMBERS" ]]` branch handles the empty case via `summarize_and_exit`. Land this together
-   with item 3 — without it, item 2's `--dry-run` invocation will produce opaque empty-output failures the first time
-   anyone runs the sync script after a release.
-
-5. **`scripts/generate-changelog.sh --dry-run` — wrap-tolerant comparison.** Known follow-up that the skill repo did
-   *not* ship in PR #26. The dry-run comparison uses byte-exact `cmp -s`. The on-disk `CHANGELOG.md` is line-wrapped
-   by the repo's markdownlint / `md-wrap` hook; the script's direct writes are unwrapped. Even after item 4, the
-   dry-run will false-positive "drift" on every release until the comparison is made wrap-tolerant. The
-   regen-idempotency check in item 2 is "warn, do not fail", so this does not block the sync — but the warning will
-   fire on every release until fixed, training maintainers to ignore it. Fix it in the same pass that ports item 3.
-   Suggested approach: run both files through `fmt -w 9999` (or an equivalent paragraph-flatten) before diffing,
-   then use `diff --ignore-all-space --ignore-blank-lines`.
+   `trap … EXIT`, exit 0 when idempotent and exit 1 on drift. The `--tag` flag is the existing release-version selector.
+   `--dry-run` is what item 2 above depends on, so land it in the same PR or land it first.
+
+4. **`scripts/generate-changelog.py` — PR-number extraction regex fix.** Mirror of
+   [skill PR #26](https://github.com/brettdavies/agentnative-skill/pull/26). The current extraction uses `grep -oP
+   '\(#\K\d+'`, which only matches the parenthesized `(#14)` form git-cliff emits on the initial prepend. The script's
+   own Python expansion step rewrites those to markdown-link form `[#14](https://github.com/.../pull/14)`. A second run
+   (e.g. `--dry-run` against an already-processed `CHANGELOG.md`, which is exactly the `sync-dev-after-release.sh`
+   regen-idempotency check's mode of operation — item 2 above) extracts zero PR numbers; with `set -euo pipefail`,
+   grep's exit-1-on-no-match aborts the script with empty output before `summarize_and_exit` can run. Change the regex
+   to `[\(\[]#\K\d+` (accepts both forms) and append `|| true` so the downstream `[[ -z "$PR_NUMBERS" ]]` branch handles
+   the empty case via `summarize_and_exit`. Land this together with item 3 — without it, item 2's `--dry-run` invocation
+   will produce opaque empty-output failures the first time anyone runs the sync script after a release.
+
+5. **`scripts/generate-changelog.py --dry-run` — wrap-tolerant comparison.** Known follow-up that the skill repo did
+   *not* ship in PR #26. The dry-run comparison uses byte-exact `cmp -s`. The on-disk `CHANGELOG.md` is line-wrapped by
+   the repo's markdownlint / `md-wrap` hook; the script's direct writes are unwrapped. Even after item 4, the dry-run
+   will false-positive "drift" on every release until the comparison is made wrap-tolerant. The regen-idempotency check
+   in item 2 is "warn, do not fail", so this does not block the sync — but the warning will fire on every release until
+   fixed, training maintainers to ignore it. Fix it in the same pass that ports item 3. Suggested approach: run both
+   files through `fmt -w 9999` (or an equivalent paragraph-flatten) before diffing, then use `diff --ignore-all-space
+   --ignore-blank-lines`.
 
 ### Already shipped here
 
-- **Duplicate-section guard** — `scripts/generate-changelog.sh` already refuses to prepend a `## [X.Y.Z]` section when
+- **Duplicate-section guard** — `scripts/generate-changelog.py` already refuses to prepend a `## [X.Y.Z]` section when
   one exists for the current tag (CLI PR #68). No action needed.
 
 ## Acceptance
 
-- `scripts/sync-dev-after-release.sh vX.Y.Z` exits `67` with a clear error message when the GitHub Release for
-  `vX.Y.Z` is missing or `isDraft=true`. Existing exit codes (`64` usage, `65` dirty tree, `66` tag-not-reachable) are
-  unchanged.
-- After a successful backport commit, the script invokes `generate-changelog.sh --dry-run --tag $VERSION` and prints a
+- `scripts/sync-dev-after-release.sh vX.Y.Z` exits `67` with a clear error message when the GitHub Release for `vX.Y.Z`
+  is missing or `isDraft=true`. Existing exit codes (`64` usage, `65` dirty tree, `66` tag-not-reachable) are unchanged.
+- After a successful backport commit, the script invokes `generate-changelog.py --dry-run --tag $VERSION` and prints a
   warning (stderr, non-fatal) when the regen-idempotency check reports drift; exits 0 either way.
-- `scripts/generate-changelog.sh --dry-run --tag vX.Y.Z` exits 0 on idempotent regeneration and exits 1 with a unified
+- `scripts/generate-changelog.py --dry-run --tag vX.Y.Z` exits 0 on idempotent regeneration and exits 1 with a unified
   diff on stderr when PR bodies have drifted.
-- `CHANGELOG.md` is restored byte-for-byte after every `--dry-run` run, including the failure path (verified by the
-  EXIT trap).
+- `CHANGELOG.md` is restored byte-for-byte after every `--dry-run` run, including the failure path (verified by the EXIT
+  trap).
 - PR-number extraction handles both `(#X)` and `[#X]` forms, and the script no longer aborts via `set -euo pipefail`
   when an already-processed `CHANGELOG.md` yields zero matches — the empty case flows through `summarize_and_exit`
   cleanly.
@@ -98,11 +96,11 @@ and <https://github.com/brettdavies/agentnative-skill/pull/26>.
 
 ## Notes for the implementer
 
-- Read the exact diffs in the skill repo's PRs #25 and #26 before touching anything here — the precondition
-  placement, exit codes, EXIT-trap mechanics, regex-with-`|| true` shape, and warn-vs-fail split are load-bearing.
+- Read the exact diffs in the skill repo's PRs #25 and #26 before touching anything here — the precondition placement,
+  exit codes, EXIT-trap mechanics, regex-with-`|| true` shape, and warn-vs-fail split are load-bearing.
 - The existing `sync-dev-after-release.sh` already does `git fetch origin --tags --quiet`; add the `gh release view`
   check after that fetch but before the tag-reachable-from-main check, so all release-state preconditions cluster.
-- The script's existing exit codes are `64` (usage), `65` (dirty tree), `66` (tag missing or not reachable). Pick
-  `67` for the new release-state precondition to keep them monotonic.
-- Conventional Commit style: `feat(scripts): harden sync-dev-after-release.sh with two preconditions` (matches the
-  skill repo's commit verb). Open the PR against `dev`, not `main`.
+- The script's existing exit codes are `64` (usage), `65` (dirty tree), `66` (tag missing or not reachable). Pick `67`
+  for the new release-state precondition to keep them monotonic.
+- Conventional Commit style: `feat(scripts): harden sync-dev-after-release.sh with two preconditions` (matches the skill
+  repo's commit verb). Open the PR against `dev`, not `main`.
diff --git a/scripts/generate-changelog.py b/scripts/generate-changelog.py
new file mode 100755
index 0000000..da700cc
--- /dev/null
+++ b/scripts/generate-changelog.py
@@ -0,0 +1,422 @@
+#!/usr/bin/env -S PYTHONDONTWRITEBYTECODE=1 uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""Generate or update CHANGELOG.md using git-cliff with PR body expansion.
+
+Usage:
+    generate-changelog.py [--tag vX.Y.Z] [repo-path]
+    generate-changelog.py --check [repo-path]
+    generate-changelog.py --dry-run [--tag vX.Y.Z] [repo-path]
+
+Options:
+    --tag vX.Y.Z   Override version tag (default: extracted from branch name).
+    --check        Verify CHANGELOG.md has a versioned section
+                   (exit 1 if only [Unreleased]).
+    --dry-run      Run the regen flow against the current CHANGELOG.md and
+                   restore the original on exit. Exit 0 if regeneration
+                   produces identical content (idempotent), exit 1 with a
+                   unified diff if it would drift. Requires an existing
+                   CHANGELOG.md.
+
+Version detection: the branch name must match release/vN.N.N (with optional
+suffix like release/v1.0.5-ci-migration). Pass --tag when not on a release
+branch.
+
+Pipeline:
+    1. git-cliff emits a versioned section from commits since the last tag
+       (prepended onto CHANGELOG.md, or created if missing).
+    2. PR numbers in that section are fetched from GitHub; each PR body's
+       ## Changelog section is parsed for ### Added / ### Changed / ### Fixed /
+       ### Documentation bullets.
+    3. The version section in CHANGELOG.md is rewritten with the aggregated,
+       attributed bullets and a Full Changelog compare link.
+
+Falls back to a flat ## Changes list when a PR uses the older template shape.
+
+Run on a release/vX.Y.Z branch before opening the PR to main.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import os
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+CATEGORIES = ["Added", "Changed", "Fixed", "Documentation"]
+
+
+def fail(msg: str) -> None:
+    print(f"error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def run(cmd: list[str], **kw) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(cmd, text=True, capture_output=True, **kw)
+
+
+def have(cmd: str) -> bool:
+    return run(["bash", "-c", f"command -v {cmd}"]).returncode == 0
+
+
+def detect_tag_from_branch() -> str:
+    proc = run(["git", "branch", "--show-current"])
+    branch = proc.stdout.strip() if proc.returncode == 0 else ""
+    m = re.match(r"^release/v(\d+\.\d+\.\d+)", branch)
+    if not m:
+        fail(
+            f"could not detect version from branch '{branch}'\n"
+            "Either use a release/vX.Y.Z branch or pass --tag vX.Y.Z"
+        )
+    tag = f"v{m.group(1)}"
+    print(f"Detected version {tag} from branch {branch}")
+    return tag
+
+
+def check_mode(changelog: Path) -> int:
+    if not changelog.exists():
+        print("FAIL: CHANGELOG.md does not exist", file=sys.stderr)
+        return 1
+    for line in changelog.read_text().splitlines():
+        if line.startswith("## ["):
+            if "[Unreleased]" in line:
+                print(
+                    "FAIL: CHANGELOG.md has [Unreleased] instead of a versioned section",
+                    file=sys.stderr,
+                )
+                print(
+                    "Run: generate-changelog.py (on a release/vX.Y.Z branch)",
+                    file=sys.stderr,
+                )
+                return 1
+            print("OK: CHANGELOG.md has versioned section")
+            return 0
+    print("FAIL: CHANGELOG.md has no versioned section", file=sys.stderr)
+    return 1
+
+
+def ensure_github_token() -> None:
+    if os.environ.get("GITHUB_TOKEN"):
+        return
+    if not have("gh"):
+        return
+    if run(["gh", "auth", "status"]).returncode != 0:
+        return
+    token = run(["gh", "auth", "token"]).stdout.strip()
+    if token:
+        os.environ["GITHUB_TOKEN"] = token
+
+
+def run_git_cliff(tag: str, changelog: Path) -> None:
+    args = ["git", "cliff", "--unreleased", "--tag", tag]
+    if changelog.exists():
+        args += ["--prepend", str(changelog)]
+    else:
+        args += ["-o", str(changelog)]
+    if subprocess.run(args).returncode != 0:
+        sys.exit(1)
+
+
+def read_remote_github(cliff_toml: Path) -> tuple[str | None, str | None]:
+    data = tomllib.loads(cliff_toml.read_text())
+    remote = data.get("remote", {}).get("github", {})
+    return remote.get("owner"), remote.get("repo")
+
+
+def extract_version_section(content: str, version: str) -> str:
+    out: list[str] = []
+    in_section = False
+    needle = f"[{version}]"
+    for line in content.splitlines():
+        if line.startswith("## ["):
+            if in_section:
+                break
+            if needle in line:
+                in_section = True
+        if in_section:
+            out.append(line)
+    return "\n".join(out)
+
+
+def pr_numbers_from_section(section: str) -> list[int]:
+    seen: dict[int, None] = {}
+    for m in re.finditer(r"\(#(\d+)\)", section):
+        seen[int(m.group(1))] = None
+    return sorted(seen)
+
+
+def fetch_pr(owner: str, repo: str, num: int) -> dict | None:
+    proc = run(
+        [
+            "gh",
+            "api",
+            f"repos/{owner}/{repo}/pulls/{num}",
+            "--jq",
+            "{body: .body, author: .user.login}",
+        ],
+        timeout=10,
+    )
+    if proc.returncode != 0:
+        return None
+    try:
+        return json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def slice_below(body: str, header_pattern: str) -> str | None:
+    match = re.search(header_pattern, body, re.MULTILINE)
+    if not match:
+        return None
+    rest = body[match.end() :]
+    next_h2 = re.search(r"^## ", rest, re.MULTILINE)
+    return rest[: next_h2.start()] if next_h2 else rest
+
+
+def extract_changelog_sections(body: str) -> dict[str, list[str]]:
+    sections: dict[str, list[str]] = {}
+    content = slice_below(body, r"^## Changelog\s*$")
+    if content is None:
+        return sections
+    current: str | None = None
+    for line in content.split("\n"):
+        h3 = re.match(r"^### (.+)", line)
+        if h3:
+            current = h3.group(1).strip()
+            sections.setdefault(current, [])
+        elif current and re.match(r"^- ", line):
+            sections[current].append(line)
+        elif current and sections.get(current) and re.match(r"^  \S", line):
+            sections[current][-1] = sections[current][-1].rstrip() + " " + line.strip()
+    return sections
+
+
+def extract_flat_changes(body: str) -> list[str]:
+    bullets: list[str] = []
+    content = slice_below(body, r"^## Changes\s*$")
+    if content is None:
+        return bullets
+    for line in content.split("\n"):
+        if re.match(r"^- ", line):
+            bullets.append(line)
+        elif bullets and re.match(r"^  \S", line):
+            bullets[-1] = bullets[-1].rstrip() + " " + line.strip()
+    return bullets
+
+
+def collect_entries(
+    owner: str, repo: str, pr_numbers: list[int]
+) -> dict[str, list[str]]:
+    aggregated: dict[str, list[str]] = {}
+    for num in pr_numbers:
+        pr = fetch_pr(owner, repo, num)
+        if not pr:
+            continue
+        body = pr.get("body") or ""
+        author = pr.get("author") or ""
+        attrib = (
+            f" by @{author} in [#{num}](https://github.com/{owner}/{repo}/pull/{num})"
+            if author
+            else ""
+        )
+
+        sections = extract_changelog_sections(body)
+        if sections:
+            for category, bullets in sections.items():
+                if not bullets:
+                    continue
+                aggregated.setdefault(category, [])
+                first = True
+                for bullet in bullets:
+                    if first and " by @" not in bullet:
+                        aggregated[category].append(bullet + attrib)
+                    else:
+                        aggregated[category].append(bullet)
+                    first = False
+            continue
+
+        flat = extract_flat_changes(body)
+        if flat:
+            aggregated.setdefault("Changed", [])
+            first = True
+            for bullet in flat:
+                if first and " by @" not in bullet:
+                    aggregated["Changed"].append(bullet + attrib)
+                else:
+                    aggregated["Changed"].append(bullet)
+                first = False
+    return aggregated
+
+
+def rewrite_version_section(
+    changelog: Path,
+    version: str,
+    tag: str,
+    owner: str,
+    repo: str,
+    entries: dict[str, list[str]],
+) -> None:
+    content = changelog.read_text()
+    header_re = re.compile(rf"^## \[{re.escape(version)}\].*$", re.MULTILINE)
+    header_match = header_re.search(content)
+    if not header_match:
+        return
+
+    pieces: list[str] = [header_match.group(0)]
+    seen: set[str] = set()
+    for cat in CATEGORIES:
+        bullets = entries.get(cat)
+        if bullets:
+            pieces.append(f"\n### {cat}\n")
+            pieces.extend(bullets)
+            seen.add(cat)
+    for cat, bullets in entries.items():
+        if cat in seen or not bullets:
+            continue
+        pieces.append(f"\n### {cat}\n")
+        pieces.extend(bullets)
+
+    new_section = "\n".join(pieces) + "\n"
+
+    tag_prefix = "v" if tag.startswith("v") else ""
+    prev_match = re.search(
+        rf"## \[{re.escape(version)}\].*?\n## \[([^\]]+)\]", content, re.DOTALL
+    )
+    if prev_match:
+        prev = prev_match.group(1)
+        new_section += (
+            f"\n**Full Changelog**: "
+            f"[{tag_prefix}{prev}...{tag_prefix}{version}]"
+            f"(https://github.com/{owner}/{repo}/compare/"
+            f"{tag_prefix}{prev}...{tag_prefix}{version})\n"
+        )
+
+    section_re = re.compile(
+        rf"## \[{re.escape(version)}\].*?(?=\n## \[|\Z)", re.DOTALL
+    )
+    new_content = section_re.sub(new_section.rstrip() + "\n", content, count=1)
+    changelog.write_text(new_content)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Run regen against the current CHANGELOG.md and restore the original on exit. "
+            "Exit 0 if idempotent, 1 with a unified diff if it would drift."
+        ),
+    )
+    parser.add_argument("--tag")
+    parser.add_argument("repo_path", nargs="?", default=".")
+    args = parser.parse_args()
+
+    repo = Path(args.repo_path).resolve()
+    cliff_toml = repo / "cliff.toml"
+    changelog = repo / "CHANGELOG.md"
+
+    if not cliff_toml.exists():
+        fail(f"cliff.toml not found in {repo}")
+
+    if args.check:
+        return check_mode(changelog)
+
+    if not have("git-cliff"):
+        print("error: git-cliff is not installed", file=sys.stderr)
+        print("  Install: cargo install git-cliff", file=sys.stderr)
+        print("  Or:      brew install git-cliff", file=sys.stderr)
+        return 1
+
+    tag = args.tag or detect_tag_from_branch()
+    version = tag[1:] if tag.startswith("v") else tag
+
+    ensure_github_token()
+
+    dry_run_original: str | None = None
+    if args.dry_run:
+        if not changelog.exists():
+            fail("--dry-run requires an existing CHANGELOG.md to compare against")
+        dry_run_original = changelog.read_text()
+
+    # Duplicate-section guard: skip the git-cliff prepend when a section for
+    # this tag already exists, so re-running against an already-released tag
+    # doesn't append a second copy of the same version. In dry-run mode we
+    # still need the PR-body expansion below to run so it can compare against
+    # the current file.
+    section_header_re = re.compile(
+        rf"^## \[{re.escape(version)}\]", re.MULTILINE
+    )
+    duplicate_section = (
+        changelog.exists() and bool(section_header_re.search(changelog.read_text()))
+    )
+    if duplicate_section and not args.dry_run:
+        print(f"CHANGELOG.md already has a [{version}] section; skipping prepend")
+        return 0
+
+    try:
+        if not duplicate_section:
+            cwd = os.getcwd()
+            try:
+                os.chdir(repo)
+                run_git_cliff(tag, changelog)
+            finally:
+                os.chdir(cwd)
+
+        owner, repo_name = read_remote_github(cliff_toml)
+        has_gh_integration = bool(owner and repo_name and have("gh"))
+
+        if has_gh_integration:
+            section = extract_version_section(changelog.read_text(), version)
+            pr_nums = pr_numbers_from_section(section)
+            if pr_nums:
+                entries = collect_entries(owner, repo_name, pr_nums)
+                if entries:
+                    rewrite_version_section(
+                        changelog, version, tag, owner, repo_name, entries
+                    )
+
+        if dry_run_original is not None:
+            new_content = changelog.read_text()
+            if new_content == dry_run_original:
+                print("DRY RUN: CHANGELOG.md is current (no regen drift)")
+                return 0
+            print(
+                "DRY RUN: CHANGELOG.md would change (regen drift detected)",
+                file=sys.stderr,
+            )
+            sys.stderr.writelines(
+                difflib.unified_diff(
+                    dry_run_original.splitlines(keepends=True),
+                    new_content.splitlines(keepends=True),
+                    fromfile="CHANGELOG.md (current)",
+                    tofile="CHANGELOG.md (regenerated)",
+                )
+            )
+            return 1
+
+        if has_gh_integration:
+            print("Updated CHANGELOG.md")
+        else:
+            print(
+                "Updated CHANGELOG.md (skipping PR expansion — missing [remote.github] or gh CLI)"
+            )
+        print("\nNext steps:")
+        print("  git add CHANGELOG.md")
+        print("  git commit -m 'docs: update CHANGELOG.md'")
+        return 0
+    finally:
+        if dry_run_original is not None:
+            changelog.write_text(dry_run_original)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh
deleted file mode 100755
index 3873f48..0000000
--- a/scripts/generate-changelog.sh
+++ /dev/null
@@ -1,329 +0,0 @@
-#!/usr/bin/env bash
-# Generate or update CHANGELOG.md using git-cliff with PR body expansion.
-#
-# Usage:
-#   generate-changelog.sh [--tag vX.Y.Z] [repo-path]
-#   generate-changelog.sh --check [repo-path]
-#
-# Options:
-#   --tag vX.Y.Z   Override version tag (default: extracted from branch name)
-#   --check        Verify CHANGELOG.md has a versioned section (exit 1 if only [Unreleased])
-#
-# The version tag is extracted from the branch name by matching the pattern
-# release/vN.N.N (with optional suffix like release/v1.0.5:ci-migration).
-# Use --tag to override when not on a release branch.
-#
-# Generates entries for commits since the last tag, prepends to existing
-# CHANGELOG.md, then expands squash commit entries by fetching categorized
-# changelog sections (### Added, ### Changed, ### Fixed, ### Documentation)
-# from each PR body's ## Changelog section.
-#
-# Falls back to ## Changes (flat list) for PRs using the old template.
-#
-# Run this on a release branch before opening a PR to main.
-
-set -euo pipefail
-
-CHECK_MODE=false
-REPO_PATH="."
-TAG=""
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --check)
-      CHECK_MODE=true
-      shift
-      ;;
-    --tag)
-      TAG="$2"
-      shift 2
-      ;;
-    *)
-      REPO_PATH="$1"
-      shift
-      ;;
-  esac
-done
-
-cd "$REPO_PATH"
-
-# Verify prerequisites
-if [[ ! -f cliff.toml ]]; then
-  echo "error: cliff.toml not found in $(pwd)" >&2
-  exit 1
-fi
-
-if ! command -v git-cliff &>/dev/null; then
-  echo "error: git-cliff is not installed" >&2
-  echo "  Install: cargo install git-cliff" >&2
-  echo "  Or:      brew install git-cliff" >&2
-  exit 1
-fi
-
-if $CHECK_MODE; then
-  if [[ ! -f CHANGELOG.md ]]; then
-    echo "FAIL: CHANGELOG.md does not exist" >&2
-    exit 1
-  fi
-
-  # Check for a versioned section (not just [Unreleased])
-  LATEST_SECTION=$(awk '/^## \[/{print; exit}' CHANGELOG.md)
-  if echo "$LATEST_SECTION" | grep -q '\[Unreleased\]'; then
-    echo "FAIL: CHANGELOG.md has [Unreleased] instead of a versioned section" >&2
-    echo "Run: generate-changelog.sh (on a release/vX.Y.Z branch)" >&2
-    exit 1
-  fi
-
-  echo "OK: CHANGELOG.md has versioned section"
-  exit 0
-fi
-
-# Extract version from branch name if --tag not provided
-if [[ -z "$TAG" ]]; then
-  BRANCH=$(git branch --show-current 2>/dev/null || true)
-  if [[ "$BRANCH" =~ ^release/v([0-9]+\.[0-9]+\.[0-9]+) ]]; then
-    TAG="v${BASH_REMATCH[1]}"
-    echo "Detected version $TAG from branch $BRANCH"
-  else
-    echo "error: could not detect version from branch '$BRANCH'" >&2
-    echo "Either use a release/vX.Y.Z branch or pass --tag vX.Y.Z" >&2
-    exit 1
-  fi
-fi
-
-# Ensure GitHub token is available for remote integration (PR links, authors)
-if [[ -z "${GITHUB_TOKEN:-}" ]]; then
-  if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
-    export GITHUB_TOKEN
-    GITHUB_TOKEN=$(gh auth token)
-  fi
-fi
-
-# Guard against duplicate version sections: if CHANGELOG.md already has a section for
-# this version, refuse rather than prepend a second copy. Re-running with an
-# already-present --tag makes git-cliff emit an empty vX.Y.Z...vX.Y.Z compare range and a
-# spurious duplicate section. To regenerate a section, delete the existing one first.
-RELEASE_VER="${TAG#v}"
-if [[ -f CHANGELOG.md ]] && grep -qE "^## \[${RELEASE_VER//./\\.}\]" CHANGELOG.md; then
-  echo "error: CHANGELOG.md already has a [${RELEASE_VER}] section, refusing to prepend a duplicate." >&2
-  echo "  To regenerate it, remove the existing [${RELEASE_VER}] section first, then re-run." >&2
-  exit 1
-fi
-
-# Step 1: Run git-cliff to prepend entries tagged with the release version
-CLIFF_ARGS=(--unreleased --tag "$TAG")
-if [[ -f CHANGELOG.md ]]; then
-  CLIFF_ARGS+=(--prepend CHANGELOG.md)
-else
-  CLIFF_ARGS+=(-o CHANGELOG.md)
-fi
-git cliff "${CLIFF_ARGS[@]}"
-
-# Step 2: Expand squash commit entries using PR body changelog sections
-OWNER=$(awk -F'"' '/^\[remote\.github\]/{found=1} found && /^owner/{print $2; exit}' cliff.toml)
-REPO=$(awk -F'"' '/^\[remote\.github\]/{found=1} found && /^repo/{print $2; exit}' cliff.toml)
-
-# Strip leading v for version matching in the changelog
-VERSION="${TAG#v}"
-
-if [[ -z "$OWNER" || -z "$REPO" ]] || ! command -v gh &>/dev/null; then
-  echo "Updated CHANGELOG.md (skipping PR expansion — missing [remote.github] or gh CLI)"
-  echo ""
-  echo "Next steps:"
-  echo "  git add CHANGELOG.md"
-  echo "  git commit -m 'docs: update CHANGELOG.md'"
-  exit 0
-fi
-
-# Extract PR numbers from the new version section only
-VERSION_SECTION=$(awk -v ver="$VERSION" '
-  /^## \[/{
-    if (found) exit
-    if (index($0, "[" ver "]")) found=1
-  }
-  found{print}
-' CHANGELOG.md)
-PR_NUMBERS=$(echo "$VERSION_SECTION" | grep -oP '\(#\K\d+' | sort -un)
-
-if [[ -z "$PR_NUMBERS" ]]; then
-  echo "Updated CHANGELOG.md"
-  echo ""
-  echo "Next steps:"
-  echo "  git add CHANGELOG.md"
-  echo "  git commit -m 'docs: update CHANGELOG.md'"
-  exit 0
-fi
-
-# Pass PR numbers as comma-separated arg to python
-PR_LIST=$(echo "$PR_NUMBERS" | tr '\n' ',' | sed 's/,$//')
-
-python3 - "$OWNER" "$REPO" "$PR_LIST" "CHANGELOG.md" "$VERSION" "$TAG" << 'PYEOF'
-import json, re, subprocess, sys
-
-owner = sys.argv[1]
-repo = sys.argv[2]
-pr_numbers = [int(n) for n in sys.argv[3].split(',')]
-changelog_path = sys.argv[4]
-version = sys.argv[5]
-tag = sys.argv[6] if len(sys.argv) > 6 else f'v{version}'
-tag_prefix = 'v' if tag.startswith('v') else ''
-
-CATEGORIES = ['Added', 'Changed', 'Fixed', 'Documentation']
-
-def fetch_pr(num):
-    """Fetch PR body and author from GitHub API."""
-    try:
-        result = subprocess.run(
-            ['gh', 'api', f'repos/{owner}/{repo}/pulls/{num}',
-             '--jq', '{body: .body, author: .user.login}'],
-            capture_output=True, text=True, timeout=10
-        )
-        if result.returncode == 0:
-            return json.loads(result.stdout)
-    except Exception:
-        pass
-    return None
-
-def extract_changelog_sections(body):
-    """Extract categorized bullets from ## Changelog section with ### subsections."""
-    sections = {}
-    if not body:
-        return sections
-
-    changelog_match = re.search(r'^## Changelog\s*$', body, re.MULTILINE)
-    if not changelog_match:
-        return sections
-
-    rest = body[changelog_match.end():]
-    next_h2 = re.search(r'^## ', rest, re.MULTILINE)
-    changelog_content = rest[:next_h2.start()] if next_h2 else rest
-
-    current_section = None
-    for line in changelog_content.split('\n'):
-        h3_match = re.match(r'^### (.+)', line)
-        if h3_match:
-            current_section = h3_match.group(1).strip()
-            if current_section not in sections:
-                sections[current_section] = []
-        elif current_section and re.match(r'^- ', line):
-            sections[current_section].append(line)
-        elif current_section and sections.get(current_section) and re.match(r'^  \S', line):
-            # Continuation line (indented, part of previous bullet) — join to last bullet
-            sections[current_section][-1] = sections[current_section][-1].rstrip() + ' ' + line.strip()
-
-    return sections
-
-def extract_flat_changes(body):
-    """Fallback: extract flat bullet list from ## Changes section."""
-    bullets = []
-    if not body:
-        return bullets
-
-    changes_match = re.search(r'^## Changes\s*$', body, re.MULTILINE)
-    if not changes_match:
-        return bullets
-
-    rest = body[changes_match.end():]
-    next_h2 = re.search(r'^## ', rest, re.MULTILINE)
-    changes_content = rest[:next_h2.start()] if next_h2 else rest
-
-    for line in changes_content.split('\n'):
-        if re.match(r'^- ', line):
-            bullets.append(line)
-        elif bullets and re.match(r'^  \S', line):
-            # Continuation line (indented, part of previous bullet) — join to last bullet
-            bullets[-1] = bullets[-1].rstrip() + ' ' + line.strip()
-
-    return bullets
-
-# Collect all categorized entries from PR bodies
-all_entries = {}  # category -> list of bullets
-for num in pr_numbers:
-    pr_data = fetch_pr(num)
-    if not pr_data:
-        continue
-
-    body = pr_data.get('body', '') or ''
-    author = pr_data.get('author', '')
-    attrib = f' by @{author} in [#{num}](https://github.com/{owner}/{repo}/pull/{num})' if author else ''
-
-    # Try new template format first (## Changelog with ### subsections)
-    sections = extract_changelog_sections(body)
-
-    if sections:
-        for category, bullets in sections.items():
-            if not bullets:
-                continue
-            if category not in all_entries:
-                all_entries[category] = []
-            first = True
-            for bullet in bullets:
-                if first and ' by @' not in bullet:
-                    all_entries[category].append(bullet + attrib)
-                else:
-                    all_entries[category].append(bullet)
-                first = False
-    else:
-        # Fallback: flat ## Changes section
-        flat = extract_flat_changes(body)
-        if flat:
-            category = 'Changed'
-            if category not in all_entries:
-                all_entries[category] = []
-            first = True
-            for bullet in flat:
-                if first and ' by @' not in bullet:
-                    all_entries[category].append(bullet + attrib)
-                else:
-                    all_entries[category].append(bullet)
-                first = False
-
-if not all_entries:
-    sys.exit(0)
-
-# Read the changelog
-with open(changelog_path, 'r') as f:
-    content = f.read()
-
-# Find the version section header line (preserve it with the date)
-header_pattern = rf'^## \[{re.escape(version)}\].*$'
-header_match = re.search(header_pattern, content, re.MULTILINE)
-if not header_match:
-    sys.exit(0)
-
-header_line = header_match.group(0)
-
-# Build the new version section content
-new_section = header_line + '\n'
-for cat in CATEGORIES:
-    if cat in all_entries and all_entries[cat]:
-        new_section += f'\n### {cat}\n\n'
-        for bullet in all_entries[cat]:
-            new_section += bullet + '\n'
-
-# Include any categories not in the standard list
-for cat in all_entries:
-    if cat not in CATEGORIES and all_entries[cat]:
-        new_section += f'\n### {cat}\n\n'
-        for bullet in all_entries[cat]:
-            new_section += bullet + '\n'
-
-# Find the previous version tag for the Full Changelog link
-prev_match = re.search(rf'## \[{re.escape(version)}\].*?\n## \[([^\]]+)\]', content, re.DOTALL)
-if prev_match:
-    prev_version = prev_match.group(1)
-    new_section += f'\n**Full Changelog**: [{tag_prefix}{prev_version}...{tag_prefix}{version}](https://github.com/{owner}/{repo}/compare/{tag_prefix}{prev_version}...{tag_prefix}{version})\n'
-
-# Replace the version section in the file
-section_pattern = rf'## \[{re.escape(version)}\].*?(?=\n## \[|\Z)'
-new_content = re.sub(section_pattern, new_section.rstrip() + '\n', content, count=1, flags=re.DOTALL)
-
-with open(changelog_path, 'w') as f:
-    f.write(new_content)
-PYEOF
-
-echo "Updated CHANGELOG.md"
-echo ""
-echo "Next steps:"
-echo "  git add CHANGELOG.md"
-echo "  git commit -m 'docs: update CHANGELOG.md'"