feat(release_library): aggregate prerelease notes into graduated Lerna releases

[mathieudi]

Adapter B of the graduation release-notes mechanism (design: github-repo-alignment/12-graduation-notes-design.md §3). Adapter A covers the 11 semantic-release libraries via @side/semantic-config-base; this covers the Lerna path.

The Lerna path is worse than semantic-release, not better. --conventional-graduate starts conventional-changelog's range at the last prerelease tag, so a graduation's range is empty and lerna writes **Note:** Version bump only for package <pkg> — the stable release body isn't collapsed, it's empty. That already shipped a real major with its BREAKING CHANGES note missing (@side-eng/test-monorepo-hello@10.0.0).

What this does

A composite action run once after publish, gated on main && IS_MONOREPO && ENABLE_GRADUATION_NOTES, using the App token the job already mints (contents:write — no permission change). It reads the tags at HEAD, finds the ones whose release body is the bump-only sentinel, aggregates that package's in-range prerelease releases via the shared engine, and PATCHes the release body.

Release bodies only — no commit, no push, no bypass actor, no re-trigger loop. Lerna's CHANGELOG.md is a committed file, so the prerelease entries already survive the squash there; only the release body needed repair.

It re-reads every release it patched and asserts the marker, the entry count and a byte-identical round-trip (design §4 guard 2), failing loudly otherwise. Idempotent twice over: the sentinel is gone after the first patch, and the engine's marker would no-op anyway.

Engine delivery

Installed from the registry at release time (@side/graduation-notes@^1), deliberately not vendored — the design made the engine a package precisely so the two adapters can't drift. Until reside-eng/release-config#205 publishes it, the step warns and skips; verified live (npm returns E404 today, adapter exits 0, releases untouched). Same for a missing token, no tags at HEAD, or an API failure — the engine's policy is never to block a release on an unknown.

Validation (local only, no mutations)

Mock releases API seeded from read-only dumps of all four Lerna repos, plus a throwaway git repo carrying the tags lerna would have created, run against the real adapter and real engine.

• Sweep of 133 real releases across platform-tools / lint-config / test-monorepo / release-config: 0 crashes, 8 real graduations repaired, everything else a clean no-op.
• Exercised: multi-package single run (4 patched in one pass), ordinary release no-op, dependency-bump-only no-op, all-bump-only-prereleases no-op, mixed noise, idempotency (3 runs → 1 PATCH), engine-unpublished degrade, no tags at HEAD, no token, transport failure, unrenderable sources → exit 1, tampered published body → assertion fails loudly.

⚠️ Design correction found in real data

The design specified detection as "sentinel AND compare-from is a prerelease". That second condition produces false negatives on real losses and is now advisory only: @side/fastify-pubsub@0.12.1 carries the sentinel with a stable compare-from, yet 0.12.1-alpha.0 in that range published a real Bug Fix (#501). The broader rule — sentinel plus at least one in-range prerelease that isn't itself bump-only — is a strict superset and cannot false-positive, since a sentinel body states nothing and the sources are in-range ancestors of that exact package version by construction.

Coverage

Covers 3 of 4 Lerna repos (platform-tools, lint-config, test-monorepo). release-config is NOT covered — it runs an inline release.yml rather than this template. Cost of leaving it is currently zero (all its prerelease bodies are themselves bump-only, so there's nothing to aggregate), but migrating it onto the template is worth doing for its four other drifts, including the missing --conventional-graduate.

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 1.18.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀