Changelog without headings

[danmt]

Why is it that our changelog has no typical headings (adding, fixed, breaking changes, etc..)? i know we removed it but im not really sure why. I thought it was breaking the grouping when arming the changelog but codex told me it handles headings fine, so i was wondering is codex wrong or we could use groupings in the changelog of this repo?

[dan-claude-bot]

Outcome: answer — codex is right, the assembler handles headings fine. The removal was drift-repair, not a capability limit.

Three facts:

1. Ceremony's changelog has been flat since 0.1.0 — every published section is bare bullets. When changelog.d was designed, changelog.d — one fragment per PR, assembled at release #112 D3 recorded each repo's existing shape: flat here, grouped (### Added/### Changed/### Fixed) in box, rig, cast, incubator. Grouped mode is first-class — canonical group order, per-group sorting (changelog.d — one fragment per PR, assembled at release #112 D5). The epic's context even says it outright: the merge-conflict problem changelog.d solved was never the headings.

2. What got removed on 2026-07-24 was headings on four fragments, not a policy. fix: review_requested wakes the labels sweep — blocker:unrequested clears when the ask lands #143, docs: the drill's delete is the operator's step — the builder archives #147, fix: the CONSUMERS.md stub's issues: types match the caller's, parity-tested #150 and docs: a post-merge acceptance criterion rides Refs #N — triage closes on the evidence #152 each landed a fragment carrying ### Fixed/### Changed on this flat repo. Each passed CI — the per-PR check validated fragments one at a time, so a lone grouped fragment was individually legal — but together they made changelog.d/ mixed-shape, and the assembler refuses a mix rather than silently dropping prose (changelog.d — one fragment per PR, assembled at release #112 D4). The 0.3.0 cut hit that refusal on main; changelog.d — strip the grouped headings from the four drifted fragments #158 stripped the four headings with every bullet byte-identical.

3. "Breaking the grouping when arming" is almost the story, inverted: arming was exactly the check that couldn't see it. The break only surfaced at assembly, at release time, on whoever was cutting. That gap is what lib/changelog.sh + changelog-armed — the one-shape rule fails the PR that introduces the drift #159 closed — the one-shape check now runs on the PR that introduces the drift, anchored to the newest published section's shape.

Could ceremony go grouped? Yes, but as a deliberate flip, not by writing headings again: since #163 the fragment set must match the newest published section's shape, so grouped fragments over the flat 0.3.0 section go red on every PR by design. A switch needs the decision plus a small transition mechanism in the guard/assembler. If you want it, say so here and I'll mint the issue; otherwise flat stands as the recorded shape.

[danmt]

Honestly I'd rather make the change here, because otherwise me or someone else will reach the same conclusion thinking that if ceremony has no headings, consumers shouldn't either. It's probably written somewhere but examples are always better

[dan-claude-bot]

Minted: #182 — the shape anchor becomes declarable (changelog.d/shape sentinel), and ceremony flips to grouped in the same PR: the five pending fragments gain headings with every bullet byte-identical, docs follow.

One mechanism note: the sentinel is the door for a deliberate flip only. Without it, a grouped fragment over the flat 0.3.0 section stays red on its own PR — the #159 drift guard is untouched, so the four-drifted-fragments episode cannot recur by accident. Consumers see zero behavior change unless they opt in.

Closing as resolved; the issue carries the spec from here.