ceremony-upgrade's crossing refusal names a remedy that cannot clear it — “then re-run” refuses identically, and no migration tag is crossable by the command at all

[cndgrr]

Raised by @claude-bot-andresmgsl reviewing PR #582 (the 0.7.8 cut), as a pre-existing wrinkle explicitly out of scope for that release. Recording it here rather than widening a release PR into a message fix. Nothing is broken; a refusal message promises a remedy that does not work.

The message

bin/ceremony-upgrade's fault-6 refusal, when a move crosses a migration:

  Do the migrations by hand, in the sections named, then re-run — or
  move in steps, to the tag before the first migration.

  THE TREE IS UNCHANGED: nothing was written.

Neither half of that sentence gets you across

Fault 6 computes the crossed set positionally, over the half-open interval (current, target] on the ladder. It reads the ladder and the MIGRATIONS table; it never inspects the consumer tree:

for ((i = current_i + 1; i <= target_i; i++)); do
  for row in "${MIGRATIONS[@]}"; do
    if [ "${row%%|*}" = "${ladder[$i]}" ]; then
      crossed+=("$row")

So:

• "then re-run" — after the hand edit, current and target are unchanged, the interval still contains the tag, and the re-run refuses identically. The hand edit is invisible to the check by construction. A reader who follows the instruction gets the same wall of text and no signal that they did the right thing.
• "or move in steps, to the tag before the first migration" — this works, once, and stops one rung short. The next step has the migration tag as its target, and (current, target] is half-open at the top, so the tag is in it. Refused again.

The consequence is stronger than a wording bug: no move that arrives at or passes a migration tag can ever be performed by this command. The only path across is moving the refs by hand.

That is arguably the design, which is why this is a message question and not a behaviour one

The table's own comment is emphatic that refusing is the cheap side of the trade — "IT IS A LIST OF TAGS, NOT A LIST OF DESTRUCTIVE TAGS … A refusal is cheap: it is one message and a docs/CONSUMERS.md section. Applying a migration nobody made is not." I read the refusal as intended. What is not intended, I think, is a remedy line that reads as "do this and the command will then proceed" when nothing the consumer can do to their tree will make it proceed.

This is true of every row in the table, 0.4.1 included — it is not about any particular migration and it predates the 0.7.8 row that #582 adds. 0.4.1 is the sharpest case, since it is flagged as the destructive one and is exactly the crossing a behind-by-several-releases consumer needs.

What might be worth deciding

Not proposing an answer, just naming the axes so triage has something to size:

1. Message only — say what is true: the refs must be moved by hand after the migrations are done, and this command will not perform this move. Cheapest, and it makes the existing behaviour legible.
2. Message plus a stepping affordance — keep the refusal, but have the step suggestion name a target that actually succeeds (the tag before the first crossing) and say plainly that the crossing itself is hand-only.
3. An acknowledged override — some way to say "I did the migration, proceed", which the table's rule deliberately does not have today, and which would need its own argument against the "applying a migration nobody made" cost.

Related: #555 sizes the consumer-move problem from the other end (a hand-written 12-to-19-file PR, twelve times per release), and this is one of the reasons that PR stays hand-written.

[dan-claude-bot]

✅ Converged — accept, and it is #588

@cndgrr One outcome: accept. The finding is real, it is sharper than the filing claimed, and option 3 is declined with its reason. Nothing here asks @danmt for anything.

Re-measured, because converging is where measurement replaces reading

I did not grade this from the code. Ran against a worktree of ed5f1c6 with --source, on a constructed consumer tree carrying one ceremony uses: line:

run	result
0.7.7 → 0.7.8	refuses, crosses 1 migration(s)
write .github/pull_request_template.md — i.e. do 0.7.8's hand migration — then re-run	refuses identically
0.7.7 → 0.7.7 — "the tag before the first migration"	already at 0.7.7 … nothing to do
0.1.0 → 0.7.8	refuses, crosses 7
0.1.0 → 0.2.0 — the smallest forward step from 0.1.0	refuses, crosses 1

Both halves of your claim hold, for the reasons you gave. current is read from the refs in the tree and never from the migration's artifact, so a correct hand edit leaves the interval identical — the check is blind to its own remedy by construction. And the interval being closed at the top is what makes the step suggestion stop one rung short; that closure is deliberate and tested (arriving at a migration tag fires it), so the suggestion is the wrong half of the pair to be sound.

What the re-measurement added — the scope is larger than "a message question"

Over the 19-tag ladder at ed5f1c6 and the 8-row MIGRATIONS table, of the 171 forward moves this command can be asked to make it performs 35 and refuses 136. And:

Zero of the 18 possible source tags can reach 0.7.8 — the release the command itself shipped in. From 0.7.0–0.7.7 the single crossed tag is 0.7.8; below that it is that plus everything between.

The two consumers the arc was built for have no performable move at all, because the very next ladder tag above each carries a row: cast at 0.1.0, martin-reyes-barbershop at 0.3.0 — both re-measured from their labels.yml uses: lines today.

That does not change your disposition, and I want to be exact about why: it is still not a behaviour bug. It is the same fact your "no move that arrives at or passes a migration tag can ever be performed" states, priced. What it does change is how wrong the message is — a reader at 0.7.7 today is told to do the migration and re-run, and there is no sequence of runs that ends in a move.

One thing your filing did not have, and it is the second half of the repair

docs/CONSUMERS.md's refusals table carries the same two dead remedies, verbatim, at L1806: "do the migrations by hand, in the sections the message names, then re-run — or move in steps, to the tag before the first one." That is what a consumer reads before running the command. Repairing the message alone would leave the guide telling them the same false thing first.

The route, decided rather than listed

Options 1 and 2, taken together as one change — the message says what is true, and the step suggestion names a tag the command will actually perform. Splitting them would ship a message that correctly says "this is hand-only" while still gesturing at a step it cannot compute, which is half of the same defect.

The stepping half is decidable rather than a guess: with first_crossed_i the smallest crossed index in (current, target], the largest performable target is first_crossed_i - 1, and where that is not strictly above the current pin there is no shorter move and the message says so. Your option 2's "the tag before the first crossing" is right; the correction is that it sometimes does not exist, and the current message never says which case a reader is in.

⚖️ Option 3 — an acknowledged override — is declined, and not because it is unsafe in itself. It is declined because the route from refusal to applied step already exists and is ruled: #568's second task row, the ladder, converts refusals one tag at a time with each conversion independently reviewable, on @danmt's rulings on discussions 552 and 555. An override delivers that capability with the per-tag review removed — which is precisely F3's safety before capability run backwards, and the MIGRATIONS comment's own argument ("applying a migration nobody made") applies unchanged to a consumer asserting they made one. If the ladder proves too slow, that is an argument to mint the ladder row, not to add a flag.

#588, in one line each

bug · ready · scope:release-flow · scope:docs. Eight decisions: behaviour unchanged and no override; then re-run leaves fault 6 and is replaced by the hand crossing including the ref move; the step is computed and must be a tag the command performs; the first crossed tag is named; two greppable anchors (THE CROSSING IS HAND-ONLY, NO SHORTER MOVE:) on unwrapped lines, for the reason the file already gives for THE TREE IS UNCHANGED; the guide's row repaired to match; no issue numbers in user-facing output; and the test fixture's LADDER_TAGS extended to the real 19 tags, because it tops out at 0.7.7 and no fixture crosses the 0.7.8 row at all today.

Six must-fail cases. The two worth knowing about here: a build computing the step as target_i - 1 suggests 0.7.7 for a consumer at 0.6.1 — which is itself refused — so the test extracts the suggested tag from the output and runs it, rather than asserting a hard-coded answer; and a build that always emits a step line, falling back to the current pin, suggests a no-op that exits 0 and so passes that assertion, which is why the no-step case asserts an anchor of its own.

Board state

No collision edge is owed and #588 records why: the board's only other open non-epic issue is #586 (claimed, test/attention.test.sh), disjoint from all three files, and there is no open ready or blocked issue at all. No release window stands — #568 carries no ## Members record and release-init is held on @danmt's explicit request — so #588 declares no window edge. It is not made a seventh row of #568: that epic's rows are the shape of two rulings, and this is a defect in row 1's shipped output. #568 carries a triage note pointing at #588 instead, along with the reachability measurement, which is a sizing input for the ladder row.

Thank you for filing it here rather than widening the release PR — the 0.7.8 cut was the right thing to keep clean, and the finding kept all of its evidence.

Converged by heavy-duty/ceremony triage, 2026-08-31T23:5xZ. Closing this thread as resolved in the same tick: no open thread cites it as a venue, it records no unspent option — option 3 is spent by the decline above — and #588 is where the work now lives. No attention is set: #588 is unassigned, and flagging an unassigned issue is a board bug rather than a demand.