fix(release): restore changelog generation, backfill v1.0.0-v1.33.0, detect the gap

[abrichr]

What happened

CHANGELOG.md stopped at v0.26.0 (2026-07-14). The package shipped 1.0.0 through 1.33.0 anyway. The 1.34.0 release dispatch hit the workflow's changelog gate and stopped.

The cause is a one-line behaviour change inside a grouped dependency bump.

time (UTC, 2026-07-14)	event
17:25:25	chore: release 0.26.0 — the last entry the generator ever wrote
17:44:41	#87 merges, python-semantic-release 9.15.2 → 10.6.1
17:47:20	chore: release 1.0.0 — version bumped, no changelog entry

Version 10 changed the default changelog mode from init to update. In update mode the generator inserts each new version after insertion_flag and writes nothing when that flag is absent — exit 0, no warning, no diff. This file was written entirely under version 9, so it had no flag. Confirmed against the pinned 10.6.1: ChangelogConfig().mode is UPDATE and insertion_flag is <!-- version list -->; running semantic-release changelog on the old file changes nothing and exits 0.

The same bump explains the odd 0.26.0 → 1.0.0 jump 22 minutes later.

Did 30+ releases ship past this gate?

No. The gate is newer than every release it would have caught. It was added on 2026-08-26 (ci: require release App tag publication), one day after v1.33.0. The 1.34.0 dispatch is its first evaluation, so its first run was also the first report of the problem. It worked. It just had nothing to compare against for six weeks.

What this does

Restores generation. Adds the insertion flag, and pins mode and insertion_flag explicitly in pyproject.toml — the regression was caused by depending on a default, so the values are now stated rather than inherited.

Backfills v1.0.0 – v1.33.0 mechanically. Not hand-reconstructed: the entries are the output of the same generator re-run over the same tagged commits, and re-running it reproduces them. A note at the top of the file records that the range was reconstructed, when, and why.

A blanket mode = "init" regeneration was rejected. Version 10's default template emits the commit summary line only, so regenerating the whole file would have replaced the 30 detailed v0.x entries with one-liners and discarded their commit bodies. The backfill is spliced in above them instead. All 30 v0.x entries are byte-identical to what was committed at the time; the only other change to that region is blank-line normalisation.

Adds the v1.34.0 entry, which unblocks the release. Its content is generated from the real commits, and covers more than the summary that prompted this work: #399, #400, #401, #404, #405, #406, #407, #408, #409, #410, #411, #414, #415, #416, #417 and the three release-contract CI commits.

Marks v1.13.0 and v1.14.0 as yanked, verified against the PyPI JSON API.

What would have caught it sooner

A comparison of published tags against changelog headings. It would have alerted on 2026-07-14, on the next scheduled run after v1.0.0 shipped.

release-health.yml already exists for exactly this class of gap — a scheduled, look-only detector for things that go wrong quietly — so this adds a fourth detector to it rather than a new workflow. No ci.yml change, so no wheel-hash re-pin.

It is state-based like its siblings: the alarm is "a published version is undocumented", not "a generator run did something unexpected". That matters because this repository has already moved once from generator-written entries to entries prepared in a reviewed PR, and the detector has to survive that. It reuses the lane's publish grace window, warns rather than alerts when the file is unreadable, stays silent for a lane with no changelog_file, and matches the same heading shape the release workflow greps for so the gate and the detector cannot disagree. Tag dates come from the releases already fetched rather than one call per tag.

Verification

• Detector run live against this repository: 52 undocumented versions against the pre-fix changelog, clean against the restored one.
• Simulated a v1.35.0 release against the committed tree: inserts correctly below the flag, note intact, v1.34.0 intact, all 107 v0.x commit bodies intact.
• That simulation caught a real bug in a first draft — the note quoted the insertion flag literally, so the generator inserted into the note and split it. Fixed; the literal appears exactly once.
• Self-test extended with five cases including a replay of the actual 2026-07-14 state. Full suite passes.
• check_release_consistency.py passes; the artifact-hash gate flagged the config edit and the regenerated inventory is a single reviewed hash change.
• ruff check / ruff format --check clean on the changed file. The 9 pre-existing scripts/ lint errors are unchanged from main and outside CI's lint scope (openadapt_flow only).

The changelog gate is untouched.

🤖 Generated with Claude Code