feat(gate): guardrailEscalation.onCleanReview — release the guardrail hold when the escalated review is clean

The second half of #9808, as an explicit MODE rather than a policy flip.

#9821 shipped the escalation knobs, so a guarded PR now gets a high-effort
review -- but the disposition still held it unconditionally: guardrailHit sat
in heldForManualReview regardless of what the escalated review found. The 74
held PRs / 14 days kept landing on the maintainer, just with better reviews
attached.

gate.guardrailEscalation.onCleanReview:
  hold     (default) today's behavior exactly -- human-in-the-loop
  proceed  a clean escalated review releases the guardrail hold and the normal
           approve/merge path continues -- full-autonomy mode

Because it is a manifest field it layers global -> per-repo like everything
else, so repos can be flipped one at a time and the mode is reversible without
a deploy.

Fail-closed on every axis:
 - `proceed` is inert unless at least one escalation knob is actually SET: the
   release is justified by extra scrutiny, so absent scrutiny nothing vouches.
 - the release requires reviewGood -- gate success (which folds in the AI
   verdict's blockers) AND green CI -- and the disposition re-checks that
   independently of the caller's flag.
 - only the guardrail term is released: migration collisions, unlinked-issue
   holds, advisory-check holds, and unstable merge states all still hold.
 - the manual-hold reason no longer claims "guarded path -> manual review" for
   a cleared PR.

Author: JSONbored

.loopover.yml.example

@@ -289,6 +289,14 @@ gate:
     selfConsistencyRuns: 3
     # provider: anthropic
     # model: claude-opus-5
+    # What a CLEAN escalated review buys (#9808). `hold` (default): the PR still waits for a human even when
+    # the escalated review found nothing — human-in-the-loop mode. `proceed`: a clean escalated review
+    # (gate success + green CI) RELEASES the guardrail hold and the normal approve/merge path continues —
+    # full-autonomy mode, where the guarded path is protected by the escalated review instead of a queue.
+    # Fail-closed: `proceed` is inert unless at least one escalation knob above is actually set, so the hold
+    # can never be released without the extra scrutiny that justifies releasing it. Layered like every other
+    # manifest field (global -> per-repo), so repos can be flipped to full-auto one at a time.
+    # onCleanReview: proceed
 
   advisoryCheckRuns:
     - name: Contributor trust

apps/loopover-ui/public/openapi.json

@@ -10191,6 +10191,15 @@
           "guardrailEscalationSelfConsistencyRuns": {
             "type": "number",
             "nullable": true
+          },
+          "guardrailEscalationOnCleanReview": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "hold",
+              "proceed",
+              null
+            ]
           }
         },
         "required": [

config/examples/loopover.full.yml

@@ -303,6 +303,14 @@ gate:
     selfConsistencyRuns: 3
     # provider: anthropic
     # model: claude-opus-5
+    # What a CLEAN escalated review buys (#9808). `hold` (default): the PR still waits for a human even when
+    # the escalated review found nothing — human-in-the-loop mode. `proceed`: a clean escalated review
+    # (gate success + green CI) RELEASES the guardrail hold and the normal approve/merge path continues —
+    # full-autonomy mode, where the guarded path is protected by the escalated review instead of a queue.
+    # Fail-closed: `proceed` is inert unless at least one escalation knob above is actually set, so the hold
+    # can never be released without the extra scrutiny that justifies releasing it. Layered like every other
+    # manifest field (global -> per-repo), so repos can be flipped to full-auto one at a time.
+    # onCleanReview: proceed
 
   advisoryCheckRuns:
     - name: Contributor trust

packages/loopover-contract/src/api-schemas.ts

@@ -459,6 +459,7 @@ export const RepositorySettingsSchema = z
     guardrailEscalationModel: z.string().nullable().optional(),
     guardrailEscalationEffort: z.enum(["low", "medium", "high", "xhigh", "max"]).nullable().optional(),
     guardrailEscalationSelfConsistencyRuns: z.number().nullable().optional(),
+    guardrailEscalationOnCleanReview: z.enum(["hold", "proceed"]).nullable().optional(),
     copycatGateMode: z.enum(["off", "warn", "label", "block"]).optional(),
     copycatGateMinScore: z.number().nullable().optional(),
     gateDryRun: z.boolean().optional(),

packages/loopover-engine/src/focus-manifest.ts

@@ -130,6 +130,13 @@ export type FocusManifestGateConfig = {
   guardrailEscalationModel: string | null;
   guardrailEscalationEffort: "low" | "medium" | "high" | "xhigh" | "max" | null;
   guardrailEscalationSelfConsistencyRuns: number | null;
+  /** `gate.guardrailEscalation.onCleanReview` (#9808 second half): what a CLEAN escalated review buys.
+   *  `hold` (default) keeps today's behavior -- the PR still waits for a human even when the escalated
+   *  review found nothing. `proceed` releases the guardrail hold when the gate passed and CI is green, so a
+   *  guarded path is protected by the ESCALATED REVIEW rather than by a human queue -- the full-autonomy
+   *  mode. Fail-closed: `proceed` does nothing unless at least one escalation knob is actually set, so the
+   *  hold can never be released without the extra scrutiny that justifies releasing it. */
+  guardrailEscalationOnCleanReview: "hold" | "proceed" | null;
   aiReviewAllAuthors: boolean | null;
   /** `gate.aiReview.closeConfidence` (#7): minimum calibrated AI-reviewer confidence (0-1) for an AI defect to BLOCK
    *  under `aiReview.mode: block`. null (unset) ⇒ the gate's 0.93 default. Clamped to [0,1] at parse time. */
@@ -653,6 +660,7 @@ export type FocusManifestSettings = Partial<
     | "guardrailEscalationModel"
     | "guardrailEscalationEffort"
     | "guardrailEscalationSelfConsistencyRuns"
+    | "guardrailEscalationOnCleanReview"
     | "aiReviewAllAuthors"
     | "aiReviewConfirmedContributorsOnly"
     | "closeOwnerAuthors"
@@ -1370,6 +1378,7 @@ const EMPTY_GATE_CONFIG: FocusManifestGateConfig = {
   guardrailEscalationModel: null,
   guardrailEscalationEffort: null,
   guardrailEscalationSelfConsistencyRuns: null,
+  guardrailEscalationOnCleanReview: null,
   aiReviewAllAuthors: null,
   aiReviewCloseConfidence: null,
   aiReviewSalvageabilityMinScore: null,
@@ -1920,6 +1929,7 @@ function parseGateConfig(value: JsonValue | undefined, warnings: string[]): Focu
     guardrailEscalationModel: normalizeOptionalString(escalationRecord?.model, "gate.guardrailEscalation.model", warnings),
     guardrailEscalationEffort: normalizeOptionalEnum(escalationRecord?.effort, "gate.guardrailEscalation.effort", ["low", "medium", "high", "xhigh", "max"] as const, warnings),
     guardrailEscalationSelfConsistencyRuns: normalizeOptionalNonNegativeInt(escalationRecord?.selfConsistencyRuns, "gate.guardrailEscalation.selfConsistencyRuns", warnings),
+    guardrailEscalationOnCleanReview: normalizeOptionalEnum(escalationRecord?.onCleanReview, "gate.guardrailEscalation.onCleanReview", ["hold", "proceed"] as const, warnings),
     aiReviewAllAuthors: normalizeOptionalBoolean(aiReviewRecord?.allAuthors, "gate.aiReview.allAuthors", warnings),
     aiReviewCloseConfidence: normalizeOptionalConfidence(aiReviewRecord?.closeConfidence, "gate.aiReview.closeConfidence", warnings),
     aiReviewSalvageabilityMinScore: normalizeOptionalScore(aiReviewRecord?.salvageabilityMinScore, "gate.aiReview.salvageabilityMinScore", warnings),
@@ -2017,6 +2027,7 @@ function parseGateConfig(value: JsonValue | undefined, warnings: string[]): Focu
     gate.guardrailEscalationModel !== null ||
     gate.guardrailEscalationEffort !== null ||
     gate.guardrailEscalationSelfConsistencyRuns !== null ||
+    gate.guardrailEscalationOnCleanReview !== null ||
     gate.ignoredCheckRuns !== null ||
     gate.aiJudgmentBlockersMode !== null ||
     gate.copycatMode !== null ||
@@ -2105,13 +2116,15 @@ export function gateConfigToJson(gate: FocusManifestGateConfig): JsonValue {
     gate.guardrailEscalationProvider !== null ||
     gate.guardrailEscalationModel !== null ||
     gate.guardrailEscalationEffort !== null ||
-    gate.guardrailEscalationSelfConsistencyRuns !== null
+    gate.guardrailEscalationSelfConsistencyRuns !== null ||
+    gate.guardrailEscalationOnCleanReview !== null
   ) {
     const escalation: Record<string, JsonValue> = {};
     if (gate.guardrailEscalationProvider !== null) escalation.provider = gate.guardrailEscalationProvider;
     if (gate.guardrailEscalationModel !== null) escalation.model = gate.guardrailEscalationModel;
     if (gate.guardrailEscalationEffort !== null) escalation.effort = gate.guardrailEscalationEffort;
     if (gate.guardrailEscalationSelfConsistencyRuns !== null) escalation.selfConsistencyRuns = gate.guardrailEscalationSelfConsistencyRuns;
+    if (gate.guardrailEscalationOnCleanReview !== null) escalation.onCleanReview = gate.guardrailEscalationOnCleanReview;
     out.guardrailEscalation = escalation;
   }
   if (gate.mergeReadiness !== null) out.mergeReadiness = gate.mergeReadiness;

packages/loopover-engine/src/types/manifest-deps-types.ts

@@ -309,6 +309,10 @@ export type RepositorySettings = {
   guardrailEscalationModel?: string | null | undefined;
   guardrailEscalationEffort?: "low" | "medium" | "high" | "xhigh" | "max" | null | undefined;
   guardrailEscalationSelfConsistencyRuns?: number | null | undefined;
+  /** `gate.guardrailEscalation.onCleanReview` (#9808 second half): `proceed` releases the guardrail hold
+   *  when the escalated review came back clean (gate success + CI green); `hold` (default) keeps a human in
+   *  the loop even then. Fail-closed: `proceed` is inert unless an escalation knob is actually set. */
+  guardrailEscalationOnCleanReview?: "hold" | "proceed" | null | undefined;
   /** Review EVERY PR's author, not only confirmed Gittensor contributors. Only meaningful when
    *  {@link aiReviewConfirmedContributorsOnly} is also `true` (that field opts INTO confirmed-only
    *  scoping in the first place — see its own doc comment for the full invariant: AI review runs for

packages/loopover-engine/test/focus-manifest-review-knobs.test.ts

@@ -88,3 +88,18 @@ test("a non-mapping guardrailEscalation is ignored wholesale, and absence leaves
   const json = gateConfigToJson(absent.gate) as Record<string, unknown>;
   assert.equal(json.guardrailEscalation, undefined);
 });
+
+test("onCleanReview parses, round-trips, makes the gate present alone, and rejects junk (#9808)", () => {
+  const parsed = parseFocusManifest({ gate: { guardrailEscalation: { onCleanReview: "proceed" } } });
+  assert.equal(parsed.gate.present, true);
+  assert.equal(parsed.gate.guardrailEscalationOnCleanReview, "proceed");
+  assert.deepEqual(parseFocusManifest({ gate: gateConfigToJson(parsed.gate) }).gate, parsed.gate);
+
+  const hold = parseFocusManifest({ gate: { guardrailEscalation: { onCleanReview: "hold", effort: "high" } } });
+  assert.equal(hold.gate.guardrailEscalationOnCleanReview, "hold");
+  assert.deepEqual(parseFocusManifest({ gate: gateConfigToJson(hold.gate) }).gate, hold.gate);
+
+  const junk = parseFocusManifest({ gate: { guardrailEscalation: { onCleanReview: "yolo" } } });
+  assert.equal(junk.gate.guardrailEscalationOnCleanReview, null);
+  assert.ok(junk.warnings.some((w) => /guardrailEscalation\.onCleanReview/.test(w)));
+});

scripts/check-docs-drift.ts

@@ -182,6 +182,7 @@ export const SETTINGS_ALIAS_MANIFEST: AliasManifestRow[] = [
   { field: "guardrailEscalationModel", aliases: ["guardrailEscalation:"] },
   { field: "guardrailEscalationEffort", aliases: ["guardrailEscalation:"] },
   { field: "guardrailEscalationSelfConsistencyRuns", aliases: ["guardrailEscalation:"] },
+  { field: "guardrailEscalationOnCleanReview", aliases: ["guardrailEscalation:"] },
   { field: "aiReviewAllAuthors", aliases: ["allAuthors"] },
   { field: "aiReviewCloseConfidence", aliases: ["closeConfidence"] },
   { field: "aiReviewSalvageabilityMinScore", aliases: ["salvageabilityMinScore"] },

src/openapi/schemas.ts

@@ -754,6 +754,7 @@ export const RepositorySettingsSchema = z
     guardrailEscalationModel: z.string().nullable().optional(),
     guardrailEscalationEffort: z.enum(["low", "medium", "high", "xhigh", "max"]).nullable().optional(),
     guardrailEscalationSelfConsistencyRuns: z.number().nullable().optional(),
+    guardrailEscalationOnCleanReview: z.enum(["hold", "proceed"]).nullable().optional(),
     copycatGateMode: z.enum(["off", "warn", "label", "block"]).optional(),
     copycatGateMinScore: z.number().nullable().optional(),
     gateDryRun: z.boolean().optional(),

src/queue/processors.ts

@@ -2865,6 +2865,13 @@ function buildAgentMaintenancePlanInput(args: {
     slopGateMinScore: settings.slopGateMinScore,
     changedPaths,
     hardGuardrailGlobs,
+    // #9808 second half: the escalation settings ride with the globs they modify, so the planner can release
+    // the guardrail hold when a clean escalated review has vouched for the guarded path.
+    guardrailEscalationOnCleanReview: settings.guardrailEscalationOnCleanReview ?? null,
+    guardrailEscalationEffort: settings.guardrailEscalationEffort ?? null,
+    guardrailEscalationSelfConsistencyRuns: settings.guardrailEscalationSelfConsistencyRuns ?? null,
+    guardrailEscalationModel: settings.guardrailEscalationModel ?? null,
+    guardrailEscalationProvider: settings.guardrailEscalationProvider ?? null,
     manualReviewLabel: settings.manualReviewLabel,
     readyToMergeLabel: settings.readyToMergeLabel,
     changesRequestedLabel: settings.changesRequestedLabel,