feat(gate): guardrail escalation — guarded paths get a stronger, multi-run AI review instead of a manual hold

[JSONbored]

Problem

hardGuardrailGlobs converts every otherwise merge-ready PR touching a guarded path into a manual-review hold. Measured on the production ORB (14 days): 252 guardrail holds across 79 distinct PRs — ~6/day of maintainer attention. metagraphed's apps/ui/** alone accounts for 68 PRs; the configs have already been through two narrowing passes and still fire constantly. This defeats the automation's purpose, and per-PR human discretion is also a fairness concern for contributors.

agent-actions.ts's own doc comment states the intent this feature restores: "Manual review is the RARE exception (the operator's minimize-manual goal)."

Design: escalate scrutiny instead of summoning a human

settings:
  hardGuardrailGlobs: [...]        # unchanged
  guardrailMode: escalate          # default: hold (today's behavior — self-hoster safe)
  guardrailEscalation:
    model: claude-opus-5           # stronger reviewer, guarded paths only
    selfConsistencyRuns: 3         # reuses #8834's run planner
    requireUnanimous: true         # all runs find zero blockers
    minConfidence: 0.9
    fallback: hold                 # ANY criterion short → exactly today's hold

A guardrail hit on a review-good PR triggers an escalated review — stronger model, N independent self-consistency runs, unanimity + confidence floor. All pass → auto-merge proceeds, with the panel and decision record stating explicitly which guarded paths were covered and the escalation verdict ("escalated review: 3/3 clean @ opus — .github/workflows/ci.yml"). Anything less → today's hold, unchanged. Manual review becomes what it was designed to be: the rare exception for genuine AI uncertainty on a guarded path.

Why this is cheap to build here

Every hard part already shipped:

• gate: per-decision confidence signal via rotated-exemplar self-consistency #8834 — self-consistency runs, rotated exemplars, run planning
• AI_REVIEW_PLAN — per-reviewer model is already a parameter
• Verdict-flip fingerprints (migration 0197) — model-disagreement signal
• Decision records + hash-chained ledger + anchoring — "an escalated AI approved this" is fully auditable
• Reputation trusted signal (fix(reputation): never cadence-downgrade a trusted submitter, and never claim a review was skipped when it ran #9800) — optional extra gate on escalation eligibility

Phases

1. Schema + plumbing: manifest fields, parse + defaults (hold = byte-identical today), FOCUS_MANIFEST_TOP_LEVEL_FIELDS registration, docs drift-checks, settings threading into agent-actions.ts.
2. Escalated runner: orchestration override (model + runs), unanimity/confidence evaluation, disposition consumes the escalation result, panel + decision-record surfacing.
3. Path-class analyzers (optional): deterministic workflow-diff audit (new run: steps, unpinned action SHAs, secret references) — the one class a semantic review can miss.
4. Rollout: metagraphed apps/ui/** first (largest hold source), watch the weekly gate-precision report, then loopover + awesome-claude.

Cost

~6 escalations/day × N stronger-model runs — modest, and it directly replaces maintainer review time. Escalations only fire on the guardrail-hit ∩ review-good intersection, which is exactly today's hold volume.

[linear-code]

JSO-6842

[JSONbored]

Shipped and enabled in production.

Implementation: #9821 — gate.aiReview.effort / .selfConsistencyRuns (per-repo parity with the env vars, which were previously the only place either could be set) plus gate.guardrailEscalation.{provider,model,effort,selfConsistencyRuns}, resolving escalation > per-repo > global per field independently.

Live on all three repos as of orb-v3.6.0-beta.8:

gate:
  guardrailEscalation:
    effort: high
    selfConsistencyRuns: 3

model and provider are deliberately unset so they inherit — this is "same claude-sonnet-5, think harder and check itself", not a model swap.

A guarded path now buys higher reasoning effort plus 3 agreement-measured runs instead of an automatic manual-review hold. Manual review remains the fallback: a non-clean escalated review still holds, and the escalation block is inert when no changed file hits a guardrail glob.

For the record, the baseline this replaces: 74 distinct PRs held in 14 days on lists that had already been narrowed twice, with the guardrail adding zero extra analysis — a guarded PR got the same single-pass, same-model, same-effort review as a README typo.

Escalations log ai_review_guardrail_escalated with the fields that changed.

One config trap worth recording: the block belongs under gate:, not settings: — placed under settings: it parses to nothing, silently. Caught during rollout by verifying the parsed value rather than trusting the write.

[JSONbored]

Reopening: I closed this when only HALF shipped. #9821 delivered the escalation knobs (a guarded PR gets the high-effort review), but the disposition still held every guarded PR unconditionally — the manual-review queue this issue exists to eliminate was unchanged, just with better reviews attached. The release-on-clean half is #9869 (guardrailEscalation.onCleanReview: proceed, fail-closed, mode-switchable per repo), which links this issue and will close it on merge.