` commit trailer wins outright, and is the escape hatch when the type cannot express the change. `scripts/release-notes-regroup.py` then renders the plan, refusing unless it covers the body exactly. ### 3. Agent review pass (optional, best-effort) `scripts/release-notes-generate.sh` probes for a reachable agent and, only if one answers, asks it to review the deterministic plan — chiefly the `Other changes` entries and any security-relevant fix committed as a plain `fix`. Its output goes through the same validation and entry-set gate as the deterministic plan. The agent is optional by construction. Missing CLI, absent credentials, failed probe, exhausted quota, blown time budget, unparseable plan, or a plan that fails validation each log a reason and keep the deterministic notes. None of them fail the job. `AGENT_MODEL` is unset by default, so the pipeline ships deterministic-only until a runner provides the CLI and credentials. ## Running It By Hand The job does this automatically for stable releases. Run it yourself to reformat an older release or to recover from a bad edit. Run every command from the repository root, and let the script own its work directory: ```bash export RELEASE_TAG=v0.76.0 # the release to reformat export RELEASE_NOTES_BASE=v0.75.1 # its stable comparison base DRY_RUN=true scripts/release-notes-generate.sh ``` `DRY_RUN=true` renders and gates without touching the release. Publishing from a manual run additionally needs `RELEASE_NOTES_APPROVED=true`, so a hand run cannot edit a published release by accident; the release job sets that variable explicitly in its own definition. The work directory it prints keeps `body.github.md`, exactly as GitHub published it; restore with `gh release edit "$RELEASE_TAG" --notes-file /body.github.md`. To hand-classify instead, keep the scratch files outside the repository but keep running the scripts from the repository root: ```bash WORK="$(mktemp -d)" gh release view "$RELEASE_TAG" --json body -q .body > "$WORK/body.md" python3 scripts/release-notes-regroup.py --body "$WORK/body.md" --list # write "$WORK/plan.json", then: python3 scripts/release-notes-regroup.py \ --body "$WORK/body.md" --plan "$WORK/plan.json" --out "$WORK/new.md" ``` The plan assigns every PR number to a section: ```json { "version": "0.76.0", "date": "2026-09-10", "sections": [ { "title": "Added", "groups": [{ "title": "Serving and inference", "prs": [1228, 1439] }] }, { "title": "Removed", "prs": [1399] } ], "internal": { "summary": "CI, build, test, and repository work with no user-facing behavior change", "groups": [{ "title": "CI and release engineering", "prs": [1244] }] } } ``` A section takes either a flat `prs` list or `groups`. Section titles are a closed set, and headings, version and date are validated before anything is rendered. Section order follows Keep a Changelog, then `Other changes`, then `Internal`. Omit empty sections. Always prove no pull request was dropped, duplicated, or invented. Entry lines are not byte-identical after prefix stripping, so compare the PR set: ```bash diff <(grep -o 'pull/[0-9]*' "$WORK/body.md" | sort) \ <(grep -o 'pull/[0-9]*' "$WORK/new.md" | sort) \ && echo "identical pull-request sets" ``` ## Judgement Calls Conventional-commit prefixes are a strong hint, not the whole answer. When reviewing a plan by hand or as the agent pass: - A `perf:` PR is **Changed**. Keep a Changelog has no performance section, and a speedup changes existing behavior. - A `fix:` PR that closes an exposure is **Security**, not Fixed. Classify by what the change protects. This is the single most valuable correction to make, because the commit type cannot express it. - A `feat:` PR that replaces an existing subsystem is **Changed**, not Added. - A docs PR that documents a removal sits beside the removal; a docs PR that publishes a new reference is **Added**; everything else docs-shaped is **Internal**. - A revert and its later re-land both stay, in the section the change belongs to. The history is the point. - Reviewer follow-up PRs ("address review findings for #1478") sit with the change they fix up. ## Layout - Sub-headings appear automatically in any section past 20 entries, one per scope with at least 4 entries, smaller scopes merged into `Other`. Below that a flat list reads better. - `### Internal` goes last, wrapped in `

` with a `

` stating the count. Keep a blank line after `

` or GitHub will not render the Markdown inside it. ## Improving Coverage Every entry the deterministic pass cannot classify is a commit that did not follow Conventional Commits. `scripts/hooks/commit-msg` rejects those locally (`just hooks-install`), `just check-commits` validates a range, and the `Check commit convention` step in the Quality lane enforces the pull request title in CI, which is the part that binds contributors who never install the hook. Because the repository squash-merges, the PR title becomes the commit subject, so the PR title is what has to be conventional. Coverage is a measurable property of a release: ```bash python3 scripts/release-notes-classify.py --body body.md \ --range v0.75.1..v0.76.0 --version 0.76.0 --date 2026-09-10 --out plan.json # classified 182/272 entries deterministically (90 in 'Other changes') ``` v0.76.0 predates the hook and classifies 182 of 272. Releases made entirely under the hook should approach full coverage, leaving the agent pass with only genuine judgement calls.