design: verdict-stability backoff guards the whole pass instead of the verdict derivation, so every bounded retry chain needs an exemption

[JSONbored]

The bug class, stated once

#10204 placed two halves of the verdict-stability backoff (#10184) in two different kinds of place, and only one of them was right.

half	placement	consequence
record	inside runAgentMaintenancePlanAndExecute, immediately after persistDecisionRecord — the single ledger write every verdict passes through	correct, and its own comment says why: "so no caller can bypass it"
skip	at the entry of the whole publish-and-maintain pass	wrong: suppresses everything the pass owed, not just the redundant re-derivation

Guarding the pass entry means backoff cancels work that has nothing to do with re-deriving a verdict:

• the one-shot panel-retrigger marker (fix(review): a manual re-run request loses its forceAiReview intent when deferred for pending CI #7626) — consumed, then discarded
• onReachedReadiness → regatePullRequest's bounded repair budget — charged for a pass that never ran
• the screenshot-table recapture chain (visual(capture): bound the render-failure retry chain with a durable per-head budget #10061) — truncated from 5 attempts to 3, measured
• an operator's manual force re-gate — silently suppressed

#10222 fixes the first, second and fourth by relocating the guard and adding an explicitlyRequested escape hatch. It does not fix the class.

Why the current shape cannot be made safe by adding cases

The escape hatch is an allowlist of exemptions:

explicitlyRequested: options.force === true || previewPollAttempt !== undefined

Every bounded retry chain in the system must remember to add itself. The default for anything not listed is "suppress me." So:

• The webhook path guard had to be abandoned in fix(queue): the verdict-stability backoff misses the webhook path, eats a manual retrigger, and ignores force #10222 — adding it truncated visual(capture): bound the render-failure retry chain with a durable per-head budget #10061's recapture budget, and there was no way to exempt that chain without weakening its test. The dominant churn source is therefore still unguarded: 293 of 344 repeat evaluations in a 24h Orb window carried upstream_state_change, the reason mapped to a raw GitHub delivery — the webhook path.
• Any future retry chain is silently truncated the day it ships, with no failing test, because the failure mode is "fewer passes than budgeted" and nothing asserts a budget it does not know about.

That is the same shape as the audit finding in #10170's comment: a rule whose correctness depends on every future author remembering an unwritten obligation.

Proposed redesign: guard the derivation, not the pass

Move the skip to the same kind of place the record half already occupies — the single choke point where the verdict is derived and published — and let everything else in the pass run unconditionally.

Then, by construction:

• retry chains, markers, counters and budgets always advance, because they sit outside the guarded region
• the expensive part (AI review, GitHub reads, publish, ledger write) is what gets skipped, which is the entire point of perf: no backoff for a PR whose verdict never changes — 56 identical evaluations of one commit in 47 minutes #10184
• a new retry chain needs no registration and cannot be truncated
• explicitlyRequested shrinks to its honest meaning — "a human asked for a fresh verdict" (force) — instead of a grab-bag of unrelated subsystems

This restores the symmetry #10204 intended: one place every verdict passes through, for both writing it and deciding whether to re-derive it.

Scope

In:

1. Identify the single choke point where a pass derives-and-publishes a verdict (start from maybePublishPrPublicSurface, and confirm maybeRunAgentMaintenance cannot reach a verdict independently of it).
2. Move the skip there. Delete the pass-entry guard added by perf(queue): back off re-evaluating a PR whose verdict never changes #10204/fix(queue): the verdict-stability backoff misses the webhook path, eats a manual retrigger, and ignores force #10222.
3. Reduce explicitlyRequested to options.force only; drop the previewPollAttempt exemption if the poll's bookkeeping now sits outside the guard (verify, don't assume).
4. Wire the webhook path (handlePullRequestWebhookEvent) — the whole reason this matters, and currently unguarded. Confirm visual(capture): bound the render-failure retry chain with a durable per-head budget #10061's recapture chain still spends its full MAX_CAPTURE_RETRY_ATTEMPTS budget with the guard live.
5. A mechanical drift check in the scripts/check-*.ts family: fail the build if a publish-and-maintain entry point exists that does not route its verdict derivation through the guarded choke point. Same idiom as checkers-wired:check / dead-source-files:check.
6. A property test per bounded retry chain: with backoff engaged on a settled verdict, each chain still completes its full attempt budget. This is the regression proof that generalises to chains not yet written.

Out:

• Changing the backoff policy — the fingerprint, VERDICT_BACKOFF_* constants, head-SHA keying and fail-open posture are all correct and stay as they are.
• The record half. It is already in the right place.

Acceptance criteria

• grep -c stableVerdictBackoffEngaged shows the guard at exactly one choke point, not per entry point.
• The webhook path is covered by the backoff, and visual(capture): bound the render-failure retry chain with a durable per-head budget #10061's recapture test still asserts MAX_CAPTURE_RETRY_ATTEMPTS unmodified.
• A drift check fails when a new entry point bypasses the choke point.
• records_per_head on the Orb measurably falls for the upstream_state_change population — the metric perf: no backoff for a PR whose verdict never changes — 56 identical evaluations of one commit in 47 minutes #10184 was after, which is currently unmoved because the dominant path is unguarded.

Note on how this was found

#10204 shipped the wiring with no test at all (grep -rn "review_skipped_stable_verdict" test/ returned nothing before #10222). The three defects were found by reading the merged diff and reproducing against the Orb, not by CI. Whatever lands here should leave behind the tests that would have caught them.

[linear-code]

JSO-7138

[JSONbored]

Design questions from the issue body, now answered against the code — recording so the implementation doesn't have to rediscover them.

1. An undefined gate is already the correct "no verdict this pass" signal.

maybeRunAgentMaintenance (src/queue/processors.ts:2683) early-returns on if (!gate) return;, alongside its other no-op guards (!isAgentConfigured, !pr, pr.state !== "open", head mismatch, draft). And the webhook path's own comment already states the contract: "gate stays undefined so the reputation/RAG steps below no-op until the terminal decision."

So the choke point does not need a new return shape or a sentinel. A backed-off pass returns undefined from maybePublishPrPublicSurface and maintenance no-ops by the path that already exists.

2. The choke point is inside maybePublishPrPublicSurface (src/queue/processors.ts:10186), not at either call site.

3. The non-obvious constraint — and the trap that will bite whoever implements this.

The guard cannot go at the top of maybePublishPrPublicSurface. The screenshot-table recapture chain (#10061) is scheduled from inside that function, so a guard placed ahead of it truncates the retry budget from MAX_CAPTURE_RETRY_ATTEMPTS (5) to 3 — the exact failure that forced the webhook guard to be abandoned in #10229, reproduced twice while working on it.

The guard must sit after the visual-capture scheduling and before the AI review / gate evaluation. Identifying that boundary precisely is the first task, and test/unit/queue-3.test.ts's two screenshot-table gate (#10061) cases are the canary — they fail loudly and immediately if it is placed wrong. Do not adjust them to pass.

4. Once it is there, explicitlyRequested should reduce to options.force alone.

previewPollAttempt only needs exempting today because the guard sits at pass entry. With the guard at the derivation, the poll's bookkeeping is outside the guarded region and needs no exemption — verify this rather than assume it, but that is the expected outcome, and it is the signal that the redesign actually worked: the allowlist should shrink to one entry, not grow.

5. Ordering of work. Move the choke point and confirm the sweep path still passes before wiring the webhook path. The webhook path is the payoff (293 of 344 repeat evaluations in 24h), but it is also the one that exposed the #10061 conflict, so it should land on a guard that is already proven correct on the quieter path.