A producer that verifies the rework already landed has no transition to say so, so ai:needs-work lies until the vetter catches up

[thedavidmeister]

Ruling

"188 would be really easy to solve, the producer can just put the 'vet' tag on it and take off 'needs work'" — thedavidmeister, 2026-08-17. This is the spec, not a proposal.

The case

rainlanguage/rain.erc4626.words#188 is green, CLEAN, MERGEABLE, and its rework has already landed. The producer verified that itself, in run 20260817T000148Z, and said so in the run summary:

Green + CLEAN + MERGEABLE. The rework had already landed at head; verified independently rather than relayed — branch 0 behind main, pointers genuinely regenerated (both hashes moved, 2-line net diff), copy-artifacts green, soldeer import violation fixed. No push needed.

It is still labelled ai:needs-work. That is a false claim about the PR: it does not need work, it needs vetting.

Why the state does not self-correct

NeedsWorkState::WorkOrder is derived from the LABEL plus a trusted send-back instruction. It never asks whether the work has already been done — a question vettedAtHead (verdict's pinned sha vs current head) already answers, and which unvetted computes for the vetter.

So the producer re-dispatches the PR every run, spends an item reaching the same conclusion, and leaves the state exactly as it found it. #188 cost $0.28 that run to establish a fact nothing recorded.

The label is only retired by the vetter's record_verdict. That is deliberate — a send-back pins its verdict AT the head so vetted_at_head is true and the vetter does not immediately strip the label it just wrote. The intended sequence is: label persists → producer pushes → head moves → vetter re-vets → label clears.

#188 breaks that sequence because the rework landed in an earlier run, so there is no push left to make. The producer has verified the exit condition and has no transition that expresses it.

Scale

Run 20260817T000148Z reported the fleet as 215 open PRs, 78 rework-needs-work, and called that "the largest actionable class". An unknown fraction of those 78 are #188s — already done, needing only a vetter pass. The count as reported overstates the actionable class by that fraction, and every one of them generates a producer item per run until the vetter's own 5-item budget reaches it. At 76 to vet and 5 per run, that window is days, not minutes.

What to build

A producer transition for "verified already done": take ai:needs-work off and put the vet tag on.

Mechanically the removal is what makes the PR vettable — the vetter's state-load has no needs-work skip bucket (skipHumanDecided, skipVettedAtHead, skipOpenThreads, skipBlockedOn, skipArchivedRepo, and no needs-work equivalent), so #188 enters the vet queue as soon as the label is gone. The vet tag is carrying LEGIBILITY: today "is this vettable" requires comparing two shas, so a human reading the queue cannot see why the producer keeps picking a PR up.

Constraints this must satisfy:

• pr-review-report is the only transition function (CLAUDE.md). This is a subcommand, not a prompt instruction to run gh --add-label, which binds to nothing.
• The claim must be checked by the tool, not asserted by the model. "Already done" means the head has moved past the trusted verdict's pinned sha AND the PR is green and mergeable. A producer that could assert it in prose could retire a send-back it had not satisfied.
• The vetter stays the authority. It re-vets the moved head and re-applies ai:needs-work if the work is in fact incomplete. This transition asserts "not the producer's move right now", never "this PR is good".
• Do not mint a second source of truth for vettability. Un-vetted-at-head is derived and cannot drift; if the new tag ever contradicts it, the derived fact wins and the divergence is the bug (QA-GUIDE §7).

Acceptance

• A producer run that verifies a needs-work PR's rework has already landed retires ai:needs-work through a typed transition, and the PR appears in the next vetter state-load.
• The same run does NOT retire the label where the head has not moved past the verdict, or where the PR is red or conflicting.
• #188 specifically: labels move, and the next vetter run records a verdict on it.

[thedavidmeister]

Correcting a constraint in the body — it is wrong and would steer the build.

The body says: "Do not mint a second source of truth for vettability. Un-vetted-at-head is derived and cannot drift." That conflates two facts.

• vettedAtHead == false means the stored verdict no longer describes this code. Derivable, cannot drift.
• "ready to vet" means the producer has finished its move and is handing back.

The first does not imply the second. A producer that pushes a PARTIAL fix moves the head: the verdict is stale and the PR is still mid-rework. Vetting it there spends a vetter item on work in progress and sends it straight back.

So "needs vet" is not derivable — it is a HANDOFF, a claim only the producer can make about its own intent to stop. The machine cannot currently express it, which is why one label has been carrying both "the producer should rework this" and "this has not been re-vetted since".

That makes the vet tag the handoff itself rather than a legibility aid, and it reverses what the body says about the removal being the mechanism:

• ai:needs-work off = the producer is no longer claiming this PR as its move
• vet tag on = the producer is handing it to the vetter

The remaining constraints stand: the transition is a pr-review-report subcommand, the tool checks the claim rather than the model asserting it, and the vetter stays the authority and re-applies ai:needs-work if the work is incomplete.

Open question for whoever builds this, and it should be settled before the tag is minted rather than after: if "needs vet" becomes an explicit handoff, does the vetter's state-load select on THAT rather than on un-vetted-at-head? If it keeps selecting on the derived fact, the tag is decoration and mid-rework PRs still get vetted.

[thedavidmeister]

Ruling (thedavidmeister, 2026-08-17): the vetter works through needs vet. Selection moves from the derived fact to the explicit tag. Settled — build to this.

That answers the open question above and makes this a change to BOTH actors, not a producer-only transition:

• the vetter's state-load selects on the tag rather than on un-vetted-at-head
• vettedAtHead does not disappear — it stays the guard against re-vetting the SAME head twice. Selection is the tag; currency is still the sha.
• record_verdict retires the tag as it writes, the way it retires ai:needs-work today

The queue stops being self-populating, and that is the thing to get right. Today nothing can be missed: any PR whose head moves past its verdict is derivably vettable. Under an explicit tag, a PR nobody tags is invisible for ever. So every route INTO the vettable state has to apply it, and the ones that exist need naming before the switch, not after:

• open_pr — a PR the producer just opened needs vetting
• push — where the producer intends the push as its finished move (and NOT where the push is partial, which is the distinction that made the tag necessary)
• the "verified already done" transition this issue was filed for
• a PR pushed by a human, or opened outside the tooling — today derivation catches these for free; with a tag, something must apply it or they never get vetted

Migration: the 76 PRs currently in the vetter's vet count are queued by derivation alone. They need the tag, or they fall out of the queue the moment selection changes. A one-time backfill that tags every currently-derivable-vettable PR, run as part of the switch rather than left as a follow-up.

Recommended shape: land the backfill and the tagging on every entry route FIRST, with the vetter still selecting on the derived fact, and verify the tag set matches the derived set on a live run. Flip selection to the tag only once those two agree. That way a missing entry route shows up as a mismatch instead of as a PR nobody ever vets.

[thedavidmeister]

Superseded in scope by #329 — one label per state, filed on the ruling that the FSM is simple if every state has a label. This issue's transition ("verified already done") becomes one transition inside that, not a separate design. The evidence and constraints here still stand; the sequencing moves there.