Changelog fragments: stop concurrent PRs conflicting on CHANGELOG.md #3563

Problem

Every writer of CHANGELOG.md appends at one insertion point (## [Unreleased] / ### Fixed), so any two open PRs conflict as soon as one merges. In clabonte/generator, 385 of the 570 commits on main since 2026-10-01 touch the file.

A merge=union attribute makes local rebases clean, but GitHub's merge button ignores merge drivers. The PR still shows as conflicting, and a conflicted PR gets no CI run. Rebasing each item onto current main (FEAT-2026-0200) only helps the agent at the moment it opens the PR: two PRs open at once still conflict when either merges.

Why upstream

An adopter can't move fully to fragments locally, because the writers and the enforcement live here:

• /fix-bug's changelog step
• close-discipline.md §3
• changelog.py's append_entry and stamp_release
• assert_changelog_entry_for_contract_changes (close-k) and specfuse lint --closing, which require a feature close's entry to be in CHANGELOG.md

This was first raised as a comment on #3451, a closed roadmap PR, so it has no tracking item of its own. This issue is that item.

Proposal

• One entry per file under changelog.d/, carrying its class (added / changed / fixed / breaking) and its trace (FEAT-… or #N). Naming the file after the trace means PRs for different issues can't collide.
• /fix-bug and the close step write a fragment.
• close-k accepts an entry in either a fragment or CHANGELOG.md.
• The release step collates fragments into the version section through the existing write path, deletes them in the same commit, and fails if parse_changelog reports a finding on the result.
• Opt-in per project, so an adopter that keeps a single file sees no change.

Adopter status

clabonte/generator is building an interim hybrid in clabonte/generator#3283: bug PRs write fragments through a local override, feature closes keep appending to CHANGELOG.md to satisfy close-k, and its own release script collates. Once this lands, the local override can go. Design detail and measurements: clabonte/generator#1973, #1958.

Done when

• Two open PRs that each add a changelog entry don't conflict when one merges, whether they come from /fix-bug or a feature close.
• A feature close whose entry exists only as a fragment passes close-k and specfuse lint --closing.
• A released section contains every fragment, parses cleanly, and leaves no consumed fragment behind.

🤖 Generated with Claude Code