changelog: the -dev re-arm should seed Unreleased with all three headings — and the non-empty guard must then count entries, not bytes

[dan-claude-bot]

Routed here by triage from heavy-duty/rig#86, which is being closed as wrong-repo. The proposal below is rig#86's, restated for the post-conversion world; the analysis and the real-batch evidence are its author's.

The proposal

## Unreleased should always carry ### Added, ### Changed and ### Fixed, even when empty — and the -dev re-arm should be what seeds them.

Why it lands here now, not in the product repos

rig#86 was filed on 2026-07-20, when each repo owned its own release flow. ceremony#13's conversion moved the re-arm upstream: .github/workflows/release.yml in this repo is what bumps X.Y.Z → X.Y.(Z+1)-dev and pushes it ("the release re-arms main itself"). A product repo cannot implement the seeding half of this proposal any more — the commit that would carry it is authored here.

The same is true of the guard the proposal breaks. Release notes are extracted between ## <ver> and the next ## ; that extractor is now lib/changelog.sh in this repo, and it is here that a non-empty check would have to learn the difference between bytes and entries.

It was filed in box, rig and cast — three twins of one flow. One issue here replaces all three.

The problem

Every open PR writes under ## Unreleased, which starts with no subsection headings. The first PR needing ### Fixed creates it; any other PR needing ### Fixed creates it too, at the same anchor in the same empty region. Git sees two sides inserting at one anchor and calls it a conflict.

The conflict rate is therefore a function of how many PRs are open, not of whether they are related. Two changes touching entirely different subsystems still collide in CHANGELOG.md. It compounds: each merge re-conflicts every PR still open, so a batch of N PRs costs on the order of N² rebases rather than N.

Evidence from a real batch (rig, seven entries across eight PRs — 1 Added, 3 Changed, 3 Fixed): nearly every rebase hit CHANGELOG.md, and not one conflict was a genuine disagreement about content. Two shapes:

1. Disjoint sections — one side ### Changed, the other ### Fixed. They compose perfectly; the conflict exists only because both had to create their heading. Seeding eliminates these entirely.
2. Same section — two ### Fixed bullets at one anchor. Seeding does not fix these.

The worst case was shape 1 with an ordering twist: a PR adding ### Added conflicted against ### Fixed, and resolving it correctly meant hoisting the new section, because the file orders Added → Changed → Fixed. Concatenating would have produced out-of-order release notes that nothing would have caught. Pre-seeded, that judgment call does not exist.

The shape

## Unreleased

### Added

### Changed

### Fixed

A PR then only ever appends a bullet under an existing heading — never creates a heading, chooses a position, or reorders.

Seeding on the -dev side is what makes it safe: the template only ever exists in ## Unreleased, so a stamped section never contains an empty heading and empty headings never ship into a published release body.

The guard this breaks

The release flow asserts the section it is about to publish is non-empty. Three empty headings are textually non-empty, so a genuinely empty release would sail past.

The check must test for at least one real - entry, not for bytes. Landing the seeding without this is a net loss — it trades a noisy, self-announcing conflict for a silent hole in a release gate. Whoever picks this up should treat the two as one change.

Open questions for this repo

The reason this is a discussion and not a minted issue — three things the product-repo framing never had to answer:

1. Does the seeding apply to every consumer, or is it opt-in? The re-arm is shared. Seeding unconditionally means box, rig and cast all get the template whether or not their maintainers want three headings in a file that may only ever need one.
2. Is the heading set fixed? Added/Changed/Fixed is what the three repos use today. Keep-a-Changelog also defines Deprecated, Removed, Security. Seeding all six would make the empty-heading noise worse; seeding three hardcodes a subset in shared machinery.
3. How does an existing armed main migrate? Consumers are already sitting on a ## Unreleased with no headings; the seeding only takes effect at the next re-arm, so there is a window where the guard change is live and the template is not.

Limits, stated honestly

• Same-section collisions still conflict. This converts "conflicts between nearly every pair" into "conflicts only within a section", leaving the trivial resolution shape (keep both bullets, no ordering decision).
• It is not the complete fix. That would be per-PR fragment files (changelog.d/, one file per PR, assembled at release time), which makes conflicts structurally impossible. Bigger change, deserves its own discussion if the cheap fix proves insufficient.

Refs: heavy-duty/rig#86 (origin, closed as wrong-repo), ceremony#4 (lib/changelog.sh), ceremony#13 (the conversion that moved the re-arm here)

[dan-claude-bot]

Triage outcome: accepted — minted as #98, with one premise corrected and all three open questions closed here rather than passed to a builder.

The premise correction, because it changes the shape of the work

This discussion says the seeding belongs to the -dev re-arm, and that a product repo can no longer implement it because that commit is authored here. The first half is not true, and the second half follows from it.

The -dev re-arm (release.yml L266–L291) writes only the version file — git add VERSION / git add package.json package-lock.json, under a comment that forbids git add -A outright — and has never touched CHANGELOG.md. The changelog's re-arm, putting an empty ## Unreleased back above the stamped section, is and always was the second hand edit of the ceremony PR (README, "two edits, not one") — the edit changelog-armed exists to catch when it is forgotten.

So the two halves land in different places: the seeding is doctrine (README, docs/CONSUMERS.md, the vendored BUILDER.md), and the guard is the only machinery. What ceremony#13 centralized was the version bump, not the changelog re-arm.

The three open questions, answered

1. Every consumer, or opt-in? Neither, as posed — there is no shared machinery to impose it. Doctrine states it as the family floor, conditional on the repo grouping its entries under ### headings: box, rig, cast and incubator do, so they seed; this repo's own changelog is a flat bullet list and has nothing to seed. Each repo picks it up when it bumps its ceremony pin, which is the same deliberate, per-repo, reviewed step every other process change takes.
2. Is the heading set fixed? Three — Added, Changed, Fixed — the set every grouped consumer actually uses. Deprecated / Removed / Security are typed by hand when a PR needs one: a rare heading-creating edit is an acceptable conflict, six standing empty headings are noise on every read. docs/CONSUMERS.md lists four kinds today and says nothing about seeding; lib/changelog.sh — a publishable section is counted in entries, not bytes, and the re-arm seeds Added/Changed/Fixed #98 gives it the split.
3. How does an armed main migrate? It does not have to. Nothing in the machinery depends on the template being present, so there is no window: the template arrives at each repo's next re-arm, on a section that is empty anyway, and lib/changelog.sh — a publishable section is counted in entries, not bytes, and the re-arm seeds Added/Changed/Fixed #98 asks for no retroactive edit to any existing ## Unreleased. The guard change is independent of the template in both directions.

One thing added, because the proposal opens a hole of its own

Counting entries instead of bytes catches a wholly empty release. It does not catch the stamp that carries an unused empty heading into the published body — ### Added with nothing under it, in a release body, and nothing that says so. That is box#108's exact shape: a hand edit whose omission leaves no signal. So #98's rule is stricter than this discussion asked for: a version section must carry at least one entry and have no heading without entries, while ## Unreleased is exempt from both — the seeded template is precisely what it should look like when empty. The refusal fires in the ceremony PR's own CI, where the fix is deleting a line, not on main after the merge.

What is not in #98

• Per-PR fragment files (changelog.d/, assembled at release time). This discussion is right that it is the structural fix and right that it deserves its own discussion — open one if the cheap fix proves insufficient. lib/changelog.sh — a publishable section is counted in entries, not bytes, and the re-arm seeds Added/Changed/Fixed #98 records same-section collisions as its honest, remaining limit.
• Consumer adoption. No cross-repo issue is minted: the pin bump is how doctrine and machinery reach box, rig, cast and incubator together, tracked on One ceremony for the whole family — the approach #1's standing item.

Credit where it is due: the analysis and the eight-PR batch evidence are heavy-duty/rig#86's author's. One live confirmation to add to it — box's ## Unreleased carries ### Changed above ### Added right now, which is the ordering hazard rig#86 predicted, sitting in the family's oldest consumer.

Closing as resolved; the work is #98, ready and unclaimed.