0.3.0 stops at the assembler — mixed fragment shapes, and a guard that structurally cannot see them

[dan-claude-bot]

Raised at the operator's direction after an attempt to cut 0.3.0 stopped at the assembler. All line references pinned at f168bbf.

The content side is ready: 11 fragments banked, no open PRs, everything the operator wanted in this release has landed (130 131 134 135 137 139 144 145 149 151 154). The release still cannot be assembled. Four concerns below — they surfaced together, but they are probably three or four issues, and which split is triage's call, not mine.

1 — bin/changelog-assemble refuses on main today (blocker)

$ bash bin/changelog-assemble 0.3.0 --check
changelog-assemble: fragment 'changelog.d/151.md' is grouped but
'changelog.d/154.md' is not — a repo is one shape or the other

Ceremony's published shape is flat — neither the ## 0.1.0 nor the ## 0.2.0 section in CHANGELOG.md carries a ### heading. Four of the eleven fragments are grouped:

fragment	heading	landed in
changelog.d/135.md	### Fixed	#147
changelog.d/137.md	### Fixed	#143
changelog.d/144.md	### Fixed	#150
changelog.d/151.md	### Changed	#152

The remaining seven are flat.

The repair looks mechanical: strip the group heading and its following blank line from those four, changing no prose. I applied that in a throwaway local clone and re-ran the assembler — it produced one clean eleven-entry section in canonical order. Nothing was pushed, and I am reporting that as a promising result, not a validated fix: I did not run changelog-armed or changelog-assembled against the repaired tree, and whoever takes this should.

Two things worth deciding rather than assuming: whether flat is genuinely the intended shape (it is what both published sections use, and it is 7 fragments against 4) and whether a repair PR that only touches changelog.d/ writes a fragment of its own or rides the release exemption.

2 — the guard cannot see this class of drift, by construction

This is the concern I would rank above the blocker itself, because the blocker is one afternoon and this is the reason it will recur.

The one-shape rule is cross-fragment — it lives in changelog_assemble (lib/changelog.sh L185-L192), where it compares fragments against each other. But on a development tree changelog-armed validates fragments one at a time, looping changelog_fragment_problem per file (changelog-armed.sh L93). A single fragment carrying ### Fixed is individually legal. Nothing in the per-PR path ever compares it to its neighbours.

So the drift is undetectable on the PR that introduces it, and detectable only by bin/changelog-assemble — which bin/changelog-assemble's own header says is "deliberately not a CI step", run by hand in the release PR. Four PRs (#143, #147, #150, #152) each passed CI with a grouped fragment. bash test/run.sh is green on main right now (18 files, 0 failed) and stays green with the directory in this state.

The consequence is structural: shape drift is always found at release time, by whoever is cutting, never by the change that caused it — and it is found at the single moment when the cost of stopping is highest. That is the same shape as the gap drill-recorded's own header describes (a gate that only fires when someone happens to look).

I am deliberately not specifying the fix — the issue contract is triage's. The obvious direction is for armed to compare a PR's fragments against the shape already established by the directory and the last published section, so the drift fails on the PR that introduces it. Whether that belongs in armed, in a new check, or in the assembler being made a CI step is exactly the design question worth an issue rather than a patch.

3 — 0.3.0 has no drill, and the record must not be written before the rehearsal

drill-recorded requires drills/0.3.0.md to exist and be non-blank the moment VERSION goes bare. Per drills/README.md that record stands for a live end-to-end rehearsal on a disposable private repo: both doors, one probe at a time, the consumer stubs pinned to a fork ref with CEREMONY_SELF_REF rewritten to a candidate SHA, ending in an archive (the delete is the operator's step and no fleet identity can perform it).

Flagging it explicitly because the guard is trivially satisfiable without the rehearsal — a non-blank file makes it green. That is precisely the failure it exists to prevent: its header records three box releases that shipped through the same gap, and #135 records a 0.2.0 drill whose written record asserted a delete that had never run. I did not run the drill and did not write a record, and whoever takes the release issue should treat running it as the work rather than the paperwork.

Open question for triage: is the drill part of the release issue's acceptance criteria, or its own issue that the release depends on?

4 — the release has no authorizing issue, and some mechanics to carry

0.2.0 rode a triage-minted issue (#128 carried Closes #118). There is no 0.3.0 equivalent open, and per CONTRIBUTING's line issues are minted only by triage.

Mechanics that issue's contract should carry, from #128's worked example:

• VERSION → 0.3.0 (bare).
• bin/changelog-assemble 0.3.0, consuming all eleven fragments.
• CEREMONY_SELF_REF stamped to 0.3.0 in both carriers — release.yml L132 and labels.yml L28 — with self-ref-check green.
• drills/0.3.0.md, per §3.
• No changelog fragment for the release PR itself (The changelog rule has one exception it never states: the release PR cannot write a fragment #131/docs: state the release PR changelog exemption #141's exemption).

Dependency worth stating on the issue: §1 blocks the release PR, because the assembler will not run until the directory is one shape.

Why this matters beyond ceremony

The operator's stated goal for 0.3.0 is the pin bump into the other governed repos. That bump is also what carries the attention label bootstrap into each of them — the remaining half of #83's operator items, now that the label exists in ceremony and heavy-duty/crew#13 has wired the box-side wake. So 0.3.0 is on the critical path for closing #83, and §1 is currently the first domino.

Provenance

Filed by dan-claude-bot from an advisory session at the operator's direction, not from a triage duty tick.

What I ran: bin/changelog-assemble 0.3.0 --check against main (the refusal in §1); the same after a local-only shape repair (the clean section); bash test/run.sh on main (18 files, 0 failed); and the source reads behind §2's claim.

What I did not run: the drill, changelog-armed/changelog-assembled against a repaired or bare tree, and anything at all against a 0.3.0 tree — no such tree exists. Nothing was pushed to this repository; I hold pull + triage here, so anything from me would arrive as a fork PR anyway.

[danmt]

@dan-claude-bot please take care of this

[dan-claude-bot]

Minted. The split is three issues under one epic — #157 holds the decisions; PRs implement them, they don't reopen them.

• §1 → changelog.d — strip the grouped headings from the four drifted fragments #158 (ready, blocked on nothing): strip the heading and its following blank line from the four fragments, prose byte-identical. Both open questions are closed: flat is not a decision to make — changelog.d — one fragment per PR, assembled at release #112 D3 already names ceremony flat, so the four grouped fragments are drift from a settled ruling. And the repair writes no fragment of its own — not via the release exemption, but because the changelog rule keys the fragment on a behavior change (CONTRIBUTING L43) and a diff entirely inside changelog.d/ has none.
• §2 → lib/changelog.sh + changelog-armed — the one-shape rule fails the PR that introduces the drift #159 (blocked by changelog.d — strip the grouped headings from the four drifted fragments #158): the cross-fragment check moves out of changelog_assemble into one shared changelog_shape_problem that changelog-armed and bin/changelog-assemble both call, plus an anchor rule — the set's shape must match the newest published section's — so an all-grouped set on a flat repo is red too, which neighbour-comparison alone can never see. The assembler stays not-a-CI-step; armed is the enforcement point. Blocked by changelog.d — strip the grouped headings from the four drifted fragments #158 because armed self-consumes from the PR's own tree: the new check would refuse its own PR while the directory is mixed.
• §3 → inside Release 0.3.0 — the second assembled tag, carrying the shape guard and eleven issues of prose #160, not its own issue (0.3.0 — repair the fragment shape, move the one-shape rule onto the PR, cut the tag #157 D4): the Release 0.2.0 — the first tag carrying fragment mode, and the first section the assembler wrote #118 worked example — the run is the work, the record is evidence, the waiver is the operator's and still a record. A separate drill issue would let the release ride while the drill sits unclaimed.
• §4 → Release 0.3.0 — the second assembled tag, carrying the shape guard and eleven issues of prose #160 (blocked by changelog.d — strip the grouped headings from the four drifted fragments #158 and lib/changelog.sh + changelog-armed — the one-shape rule fails the PR that introduces the drift #159): Release 0.2.0 — the first tag carrying fragment mode, and the first section the assembler wrote #118's shape with 0.3.0 mechanics, Refs #160 per BUILDER/TRIAGE/REVIEWER — a post-merge acceptance criterion needs Refs #N, not Closes #N #151's post-merge rule, triage owns the close.

One call worth @danmt's eyes because it delays the tag by one small PR: #160 waits for the guard (#157 D6). The tag that repairs this drift should carry the thing that prevents its recurrence into every consumer at the pin bump it already owes them — otherwise each repo inherits fragment mode with the same release-time trap armed for its first cut. Overturn it by merging the release without #159; the dependency line is all that changes.

The consumer pin bumps are deliberately not minted yet — rig and incubator are still mid-0.2.0-adoption, and a bump issue against a tag that doesn't exist would sit unbuildable. They get minted when the tag lands, each carrying its repo's labels dispatch (#102's attention bootstrap).

Closing as resolved — the work is on the board.