[HowardBraham]

References

• This is part of the release-changelog automation, splitting it into smaller reviewable PRs.
• Stacked on feat(release/auto-changelog): preserve finalized changelog history when merging previous releases #300

Explanation

Current state

The release changelog generator (auto-changelog) produces a ## [version] section with an ### Uncategorized bucket, terse or implementation-level wording, and commits that were only labeled. Someone has to clean it up by hand before release.

Solution

A new clean-release-changelog.mts proofreads that section with an LLM, and writes it back only when the result passes validation. It does the following:

• It gives the LLM only the section and each PR's title and body as evidence. Local git log evidence is used first, with GitHub as a fallback.
• It keeps the generator's categories as input, removes ### Uncategorized, and rewrites entries in concise, user-facing, past tense. The prompt is .github/prompts/auto-changelog-clean-room.md.
• It splits the section into chunks per category. It throws if one PR has two differing entries, so nothing is silently dropped.
• It validates the rewrite before writing. Every entry must end with its PR reference. The set of PR numbers must match the input exactly, with none added, removed or invented. PR references are read from the first line of each entry the same way auto-changelog parses them.
• If validation fails, it retries the request before giving up.
• A model failure, a rejected key, a timeout, or a response that fails validation leaves the changelog untouched and is recorded in a report. It never fails the release.

Other changes

• Shared helpers: release-section.mts, shared/environment.mts, shared/report.mts and shared/retry.mts hold the section extract/replace, PR parsing, environment, report and retry code. merge-previous-release-changelog.mts now imports the section helpers instead of repeating them. The oldest section now ends before the link references instead of swallowing them.
• tsconfig: it allows .ts/.mts import extensions, which Node's native TypeScript support requires, and adds the DOM lib for fetch and AbortController.
• apply-changes.ts: the DOM lib makes Document a global, so segment-schema-draft-pr/apply-changes.ts imports yaml's Document as YamlDocument.
• ESLint: .github/scripts/**/*.mts are CLI scripts, so an override lets them read process.env.
• Tests: clean-release-changelog.test.mts covers chunking, validation, evidence, retry and timeouts, and runs the script end to end in a subprocess with a throwaway git repo. release-section.test.mts and retry.test.mts cover the helpers.

Testing

• Local: tsc, lint:eslint and node --test pass.
• Real model: ran against a real generated metamask-extension 13.54.0/13.55.0 section (29 entries). Four of four runs passed validation after the retry change.
• Not tested: nothing wires this script into a workflow in this PR. The updater PR does that. Jest has 3 failures in src/segment-schema-draft-pr/apply-changes.test.ts, which also fail on main.

---

Note

Medium Risk
Touches release changelog content via external LLM and GitHub/git evidence, but writes only after validation and preserves the file on failure; credential scrubbing for child processes reduces leak risk.

Overview
Adds an LLM-based clean-room proofreader for generated ## [version] changelog sections: clean-release-changelog.mts chunks entries, gathers PR evidence (local mainline squash commits first, then gh api), calls LiteLLM with .github/prompts/auto-changelog-clean-room.md, and only replaces the section when output passes strict validation (Keep a Changelog categories, no Uncategorized, exact PR reference set). Failures write a JSON report and leave CHANGELOG.md unchanged.

Shared release tooling: new release-section.mts (extract/replace sections, PR parsing) plus shared/environment.mts, report.mts, and retry.mts; merge-previous-release-changelog.mts now uses those helpers and stops oldest sections at link references.

Build/lint: tsconfig includes .github/scripts/**/*.mts, enables allowImportingTsExtensions and DOM lib for fetch; ESLint allows process.env on CLI scripts; apply-changes.ts aliases yaml Document as YamlDocument after DOM lib added.

Tests: large coverage for chunking, validation, evidence, retries, and end-to-end subprocess runs; shared git-test-environment.mts for git fixtures.

Workflow integration is not in this PR (script is standalone).

^{Reviewed by Cursor Bugbot for commit b8974d5. Bugbot is set up for automated code reviews on this repo. Configure here.}