orb(ledger): a hold records reason_code 'success', so the manual-review surface cannot be split by cause

[JSONbored]

Prerequisite for #9729's clearance run, and a defect in its own right.

The ledger says a PR was held for reason "success"

Measured on the Orb: 1,679 of 2,429 verdicts are holds (69%), and the single largest bucket is reason_code = 'success' — 518 holds over 146 pull requests, 31% of all manual load.

That value is not informative, it is an artifact. deriveDecisionReasonCode is:

blockerClass !== "none" ? blockerClass : policyCloseKind != null ? `policy_close:${policyCloseKind}` : conclusion

For a hold with no blocker and no policy close, it falls through to the gate conclusion — which for these is success. So the record states that a pull request was held for the reason "success", which is not a reason at all. A reader of the public proof page's sample records sees the same thing.

Why it blocks #9729

#9729 must loosen only what clears a backtest, per path. success is not a path — it is at least seven of them. MERGE_HOLD_INPUTS (src/settings/pr-disposition.ts) enumerates every input that suppresses a would-merge:

guardrailHit, migrationCollisionHold, unlinkedIssueMatchHold, advisoryCheckHold, priorityEligibilityHold, screenshotEvidenceHold, unlinkedIssueMatchCloseWithoutCloseActing

derivePrDisposition already computes which of them fired — heldForManualReview is a .some(...) over exactly that set — and then discards the answer. A clearance run against a bucket conflating seven mechanisms would not mean anything.

The table's own comment anticipates this: "the value documents WHY the input holds; nothing reads it as text today, and it is the natural place for a ledger reason to come from when one is wanted." It is wanted now.

Do NOT fix this by changing reason_code

replayDecision recomputes reasonCode through the same function and reports a divergence when it does not match the recorded value (decision-replay.ts:168). Changing the derivation would make all 518 existing hold records replay as unreproducible — a false "this decision cannot be re-derived" on records that are fine. It would also change a value published in the proof page's sample records.

The reason belongs in a new nullable column, written alongside, outside record_json so record digests and the replay contract are untouched. Historical rows stay null, which is honest: we genuinely do not know why those 518 were held.

Acceptance

• derivePrDisposition exposes which hold inputs fired, deterministically ordered.
• A hold's cause is persisted per decision record, without altering reason_code, record_json, or any record digest.
• Replay of an existing record still verifies.
• The manual-review surface becomes splittable by cause, so orb(gate): next guardrail-loosening tranche — backtest-cleared paths only #9729 can pick candidates per path.

[linear-code]

JSO-6966

[JSONbored]

Implementation note: where this actually blocks, from an attempt

I started this and stopped deliberately. Recording what I found so the next attempt does not rediscover it.

The three easy parts are genuinely easy. All verified locally before I reverted:

1. derivePrDisposition can expose heldBy: MergeHoldInput[] as a one-line change — heldForManualReview is already MERGE_HOLD_INPUT_KEYS.some(...), so the filtered list is the same expression. Derived from the table, so a newly added hold is enumerated automatically.
2. A nullable hold_cause TEXT column on decision_records is clean, and db:migrations:check / db:schema-drift:check both pass with it.
3. persistDecisionRecord takes it as an optional argument and writes it outside record_json, leaving every digest and the replay contract untouched.

The blocker is the data flow, and it is wider than it looks.

The hold cause is computed in planAgentMaintenanceActions (src/settings/agent-actions.ts:1154), used at line 1171, and then discarded — the function returns a bare PlannedAgentAction[].

The decision record is written much later, at the finalize site in processors.ts, from agentDispositionLabels(holdoutOnPlan, …). That derives actionClass: "hold" purely from the absence of a merge or close action in the plan:

const actionClass = breakerOnPlan.some(a => a.actionClass === "merge") ? "merge"
  : breakerOnPlan.some(a => a.actionClass === "close") ? "close"
  : "hold";

And processors.ts's own comment names the shape these 518 records take: "an empty breakerOnPlan (the most common hold shape: nothing was ever planned)". So at the point of the write there is no action, no disposition object, and nothing carrying the reason — the cause exists only inside the planner, several frames up.

Threading it out means changing planAgentMaintenanceActions' return type from an array to an object, which touches processors.ts, github/backfill.ts and their test suites. That is a wide refactor of the gate decision path rather than the small additive change the rest of this issue is, and it deserves its own careful pass rather than being tacked on.

Also worth confirming for whoever picks this up: neutralHoldReasonCode already recovers a nameable reason from gate.warnings, but only for a neutral conclusion. These 518 have conclusion success, so it returns null and blockerClass falls through to "none" — which is exactly why the reason code ends up as the bare conclusion. Any fix that only widens neutralHoldReasonCode will not reach this bucket.