the merge-before-finalize warning only reaches operators who run the verb that prints it

[0xLeif]

I merged a PR without finalizing its change today. The warning that exists to prevent exactly that never appeared, because it is printed by ship and I never ran ship.

What happened

PR #710 was verified, pushed, CI-green, and merged. change review and change ship were never run. The deliverable was fine — the docs landed — but the lifecycle record stayed verifying on main, and when the next PR moved project_input_digest its evidence went stale.

change audit --strict then failed on main, and nobody noticed. It was found incidentally by an agent establishing a baseline for unrelated work, some hours later.

Why the existing warning could not help

#687 improved this text and it is accurate:

do not merge the PR before finalize — merging first orphans its verification evidence AND blocks every earlier accepted change sharing a delivery input from archiving

It is emitted by ship / ship-status / finalize. Every one of those is a verb you run when you are already doing the right thing. The operator who is about to make this mistake is, by definition, not running them.

Nothing on the merge path asks the question. There is no check that fails when a PR carrying an active change is merged, and audit — which does detect the result — runs only when someone chooses to run it.

So the guidance is well-worded and unreachable. That is the same shape as several defects this release has already fixed: a signal that exists but cannot arrive at the moment it is needed.

Options, none obviously right

1. A CI check on the PR. If the head commit carries an active change workspace whose state is not archived, fail — or warn on the PR itself. This puts the signal where the merge decision is made. Cost: it must not fire on legitimately multi-change PRs mid-sequence, and it needs to distinguish "not finalized yet" from "finalized in a later commit on this branch".
2. Make audit part of the required gate, so a stale or unfinalized workspace blocks the merge button rather than being discovered later. Bluntest, and it would have caught this — but it turns every mid-flight PR red until its last change ships.
3. Detect it after the fact and say so loudly. A post-merge job that runs audit --strict on main and opens an issue or fails the branch. Does not prevent the mistake; does bound how long main stays quietly red.

Option 3 is worth doing regardless of the others. main was red for hours and the only reason it surfaced is that an unrelated agent happened to run audit first.

What this is not

Not an argument for weakening the warning — it is correct and #687's second-order cost is real. The problem is placement, not wording.

Filed against myself: I have quoted this warning repeatedly today and then walked into it. If the operator most steeped in it can skip two verbs and merge with nothing objecting, the mechanism is not doing the work the wording implies.

Related: #687 (the wording), #703 (a fold-back step that also depends on the operator following next_action).

[0xLeif]

The machine-readable path carries the pre-#687 wording

Verified on main. #687 extracted merge_before_finalize_warning (src/commands/change.rs:1260) so the second-order cost would be stated once, and its closing comment says "All four sites now name the second-order cost." They do not. Two call it; three carry hand-written paraphrases, and one of those is the structured output.

site	text	names the second-order cost?
commands/change.rs:886	merge_before_finalize_warning(false)	yes
commands/change.rs:908	merge_before_finalize_warning(true)	yes
cli.rs:519	hand-written doc comment	yes, but drops the exits
commands/change.rs:781	hand-written next-action line	yes, but drops the exits
commands/change.rs:1366	"action" in the stages JSON	no

The helper says:

do not merge the PR before finalize — merging first orphans its verification evidence AND blocks every earlier accepted change sharing a delivery input from archiving, until this one is finalized or those are reopened

The JSON merge stage says:

merge only after finalize — merging an unfinalized change orphans verification evidence

That is the pre-#687 wording, unchanged, in the payload a program reads. #687's whole subject was that the cost is not one stranded record but an unbounded set of older changes, and the one consumer that cannot infer the rest from context is the one still being told the old thing.

The two paraphrases at cli.rs:519 and change.rs:781 also drop "until this one is finalized or those are reopened" — the clause naming the way out. A warning that states a cost without its exit is what makes an operator route around it.

Why this sharpens the issue rather than duplicating it

This issue says the warning reaches only operators who run the verb that prints it. The JSON case is worse in kind: an agent driving the lifecycle programmatically reads stages, gets a complete-looking action string, and has no signal that a fuller warning exists on a text path it never renders. It is not an absent warning, it is a confidently incomplete one — which is the harder failure, because nothing looks wrong.

I hit this personally on #710: merged before running review/ship, left main red for hours, and it was found incidentally by someone else. The pinning test (change.rs:2740-2741) asserts only that the helper's output contains "before finalize" and "still active" — it says nothing about the second-order cost, so it would not have caught any of the three divergences above.

Suggested shape

Route all five through the helper, and give the JSON stage a structured cost rather than a prose sentence — blocks_predecessors: true alongside the human string — so a consumer can act on it without parsing English. Then strengthen the pinning test to assert the second-order clause and the exit clause, which is what would have kept the three paraphrases honest.

Related: #687 (the extraction), #710 (where the gap actually bit).