pi-crew 0.11.11 → 0.11.13

package/src/runtime/verification/classifier-pre-gate.ts

@@ -0,0 +1,262 @@
+/**
+ * U6B (upgrade spec 2026-10-09, §U6 Phase B): classifier VERIFIER PRE-GATE —
+ * the third consumer of the P2-1 host classifier seam, alongside retry-triage
+ * (child-executor.ts) and the ambient-noise gate (ambient-noise-gate.ts).
+ *
+ * Semantics: BEFORE an LLM verifier is spawned, the already-produced
+ * STRUCTURED verdict state is scored by the cheap host classifier — ONE
+ * `score` question (classifyScore, the graded sibling of classifyBool added
+ * by U6B) over JSON state ONLY:
+ *     { verdict, evidenceLines, changedFiles }
+ * The classifier NEVER sees a diff, file contents, or prose transcripts — it
+ * judges whether the structured state alone is decisive enough to skip the
+ * LLM verifier spawn ("verdict được pre-gate chặn"). Every other outcome
+ * escalates to the LLM verifier, exactly the pre-U6B spawn decision.
+ *
+ * ESCALATION POLICY (spec §U6 Phase B, mandatory — "escalate LLM khi
+ * confidence thấp hoặc verdict FAILED"):
+ *   - verdict failure-shaped (FAILED/error/blocked/...) or not clearly
+ *     pass-shaped (INCONCLUSIVE/blank) → escalate (a cheap classifier may
+ *     never rubber-stamp a failure or an ambiguous verdict);
+ *   - provider confidence below BLOCK_CONFIDENCE_THRESHOLD (or unreported)
+ *     → escalate;
+ *   - score below BLOCK_SCORE_THRESHOLD (or outside 0..1) → escalate;
+ *   - EVERY classifier failure mode (registry missing, `opencode` provider
+ *     unconfigured → getAvailableOfType("classifier") = [], classify threw,
+ *     stopReason error, answer missing) → escalate, soft.
+ *
+ * SOFT-BRANCH CONTRACT (spec caveat, mandatory):
+ *   - `opencode` provider is sometimes unconfigured on this host — the
+ *     pre-gate then degrades to "always escalate" (identical to pre-U6B
+ *     behavior);
+ *   - a WRONG classifier verdict can only cost ONE extra escalate (the LLM
+ *     verifier runs anyway) or skip one spawn whose structured state showed a
+ *     high-confidence unambiguous pass — it can NEVER fail a task. This
+ *     module never throws up to the caller.
+ *
+ * Metrics (spec acceptance: % verdicts blocked by the pre-gate, % escalate,
+ * zero task-fail due to classifier — flag OFF by default until data exists):
+ *   - crew.classifier.calls_total{consumer="verifier_pre_gate",outcome} +
+ *     crew.classifier.confidence via classifyScore (service level);
+ *   - crew.classifier.decisions_total{consumer="verifier_pre_gate",
+ *     decision=<action>} + a `task.verifier_pre_gate` diagnostic event ONLY
+ *     when a real classifier answer informed the decision (fallback paths are
+ *     already counted by the service's calls_total and must not double-report
+ *     a decision they did not make). Percentages derive from decisions_total.
+ *     NOTE: `task.verifier_pre_gate` is NOT yet in TEAM_EVENT_TYPES
+ *     (src/state/contracts.ts) — src/state/** is outside U6B's file
+ *     ownership, so registration is deferred to the U13 mount commit (see
+ *     MOUNT POINT below); scripts/check-event-types-registry.mjs runs
+ *     report-only today.
+ *
+ * Concurrency: the seam caps host classify at 4 parallel calls; each consumer
+ * (retry-triage, ambient-noise gate, this pre-gate) issues at most ONE
+ * concurrent call, so the aggregate stays within the budget.
+ *
+ * ── MOUNT POINT (U13 lane — this module is intentionally NOT wired yet) ──
+ * The verifier spawn path stays UNTOUCHED by U6B per lane ownership:
+ *   - verification-gates.ts command-gate spawn logic: NOT modified here
+ *     (U13 owns the mount, spec §U13);
+ *   - goal-loop judge spawn (goal-evaluator.ts evaluateGoal → runWorker):
+ *     NOT modified here.
+ * When U13 mounts the deterministic ctx.executeTool gates, insert this
+ * pre-gate in the decision flow:
+ *   1. run the deterministic gates (U13: typecheck / test:critical / grep
+ *      evidence via ctx.executeTool) and build the structured verdict state:
+ *        { verdict: "PASS"|"FAILED"|..., evidenceLines: [...], changedFiles: [...] };
+ *   2. BEFORE spawning the LLM verifier:
+ *        const preGate = await classifyVerifierPreGate({
+ *            enabled: resolveClassifierEnabled(runtime.classifierEnabled), // default false
+ *            modelRegistry: ctx.modelRegistry,
+ *            classifierModel: resolveClassifierModel(runtime.classifierModel),
+ *            verdict, eventsPath, runId, metricRegistry,
+ *        });
+ *      — preGate.blockVerifier === true → SKIP the LLM verifier spawn (the
+ *        structured pass stands; mark the verdict's evaluator/model provenance
+ *        e.g. "classifier-pre-gate/<model>" so consumers can tell);
+ *      — otherwise → spawn the LLM verifier as today (optionally attach the
+ *        pre-gate score/confidence to the verifier's prompt context).
+ * The args/result interfaces below are the stable contract for that mount;
+ * changes need both lanes' review.
+ */
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import { appendEventAsync } from "../../state/event-log/event-log.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { classifyScore } from "../classifier/classifier-service.ts";
+
+/** Structured verdict state the classifier reasons over — JSON state ONLY
+ *  (spec: "chỉ JSON state, KHÔNG phán diff"). Built by the deterministic
+ *  gates (U13) / the verdict-producing step; never diffs, never file
+ *  contents — only labels, evidence lines and file NAMES. */
+export interface VerifierPreGateVerdictState {
+	/** Short structured verdict label, e.g. "PASS", "FAILED", "INCONCLUSIVE". */
+	verdict: string;
+	/** Structured evidence lines (command exit codes, artifact refs). Capped before classify. */
+	evidenceLines: string[];
+	/** Changed-file paths (names only). Capped before classify. */
+	changedFiles: string[];
+}
+
+export type VerifierPreGateAction =
+	| "disabled"
+	| "blocked"
+	| "escalate_verdict_failed"
+	| "escalate_low_confidence"
+	| "escalate_low_score"
+	| "escalate_fallback";
+
+/** Default score at/above which a pass-shaped verdict blocks the LLM verifier spawn. */
+export const VERIFIER_PRE_GATE_BLOCK_SCORE_THRESHOLD = 0.9;
+/** Default provider confidence at/above which blocking is allowed. An
+ *  unreported confidence NEVER blocks (defensive: block is the risky branch). */
+export const VERIFIER_PRE_GATE_BLOCK_CONFIDENCE_THRESHOLD = 0.8;
+
+const VERDICT_MAX_CHARS = 200;
+const EVIDENCE_MAX_LINES = 8;
+const EVIDENCE_LINE_MAX_CHARS = 200;
+const CHANGED_FILES_MAX = 16;
+
+const VERDICT_FAIL_RE = /\b(fail(?:ed|ure)?|error(?:ed)?|blocked|fatal|timeout|timed[- ]out|red)\b/i;
+const VERDICT_PASS_RE = /\b(pass(?:ed)?|green|succeed(?:ed)?|success(?:ful)?|ok|achieved|complete(?:d)?)\b/i;
+
+/** A verdict reaches the block path ONLY when unambiguously pass-shaped:
+ *  matches PASS vocabulary AND carries no failure vocabulary. Explicit
+ *  failures and ambiguous labels ("INCONCLUSIVE", blank) both escalate. */
+function isPassShapedVerdict(verdict: string): boolean {
+	return VERDICT_PASS_RE.test(verdict) && !VERDICT_FAIL_RE.test(verdict);
+}
+
+/** Cap the classifier state — classifiers reason over small low-cardinality
+ *  JSON; the verdict fields are worker-influenced and can be arbitrarily
+ *  long, so every string is bounded before it reaches the classify call. */
+function capVerdictState(verdict: VerifierPreGateVerdictState): Record<string, unknown> {
+	return {
+		verdict: verdict.verdict.slice(0, VERDICT_MAX_CHARS),
+		evidenceLines: verdict.evidenceLines.slice(0, EVIDENCE_MAX_LINES).map((line) => line.slice(0, EVIDENCE_LINE_MAX_CHARS)),
+		changedFiles: verdict.changedFiles.slice(0, CHANGED_FILES_MAX).map((file) => file.slice(0, EVIDENCE_LINE_MAX_CHARS)),
+	};
+}
+
+export interface VerifierPreGateArgs {
+	/** Pre-resolved gate (resolveClassifierEnabled) — false short-circuits before ANY registry touch (dormant default). */
+	enabled: boolean;
+	/** Host-process model registry (ctx.modelRegistry, threaded unknown). */
+	modelRegistry: unknown;
+	/** Pre-resolved classifier model id (resolveClassifierModel). */
+	classifierModel: string;
+	/** Structured verdict state (JSON state only — never diffs). */
+	verdict: VerifierPreGateVerdictState;
+	/** Score at/above which a pass-shaped verdict blocks the spawn (default VERIFIER_PRE_GATE_BLOCK_SCORE_THRESHOLD). */
+	blockScoreThreshold?: number;
+	/** Confidence at/above which blocking is allowed (default VERIFIER_PRE_GATE_BLOCK_CONFIDENCE_THRESHOLD). */
+	blockConfidenceThreshold?: number;
+	/** Event-log identity for the task.verifier_pre_gate diagnostic event. */
+	eventsPath: string;
+	runId: string;
+	/** Optional task id (the goal-loop judge is not a task — omit there). */
+	taskId?: string;
+	/** Optional host metric registry (crew.classifier.* counters/histograms). */
+	metricRegistry?: MetricRegistry;
+}
+
+export interface VerifierPreGateResult {
+	/** true → skip the LLM verifier spawn: the structured verdict stands as a pass. */
+	blockVerifier: boolean;
+	/** true ONLY when a real classifier answer informed the decision (event + decision metric emitted). */
+	consulted: boolean;
+	/** Which branch produced the outcome (metric label + event data). */
+	action: VerifierPreGateAction;
+	/** Classifier score reading, when consulted. */
+	score: number | undefined;
+	/** Provider-reported confidence, when consulted and reported. */
+	confidence: number | undefined;
+}
+
+/**
+ * Ask the verifier pre-gate. NEVER REJECTS and never throws up to the
+ * caller — the disabled path returns without touching the registry (zero
+ * behavior change: flag off by default), every classifier failure mode falls
+ * back to "spawn the LLM verifier" (blockVerifier false).
+ */
+export async function classifyVerifierPreGate(args: VerifierPreGateArgs): Promise<VerifierPreGateResult> {
+	if (!args.enabled) {
+		return { blockVerifier: false, consulted: false, action: "disabled", score: undefined, confidence: undefined };
+	}
+	const scoreThreshold = args.blockScoreThreshold ?? VERIFIER_PRE_GATE_BLOCK_SCORE_THRESHOLD;
+	const confidenceThreshold = args.blockConfidenceThreshold ?? VERIFIER_PRE_GATE_BLOCK_CONFIDENCE_THRESHOLD;
+	const result = await classifyScore({
+		modelRegistry: args.modelRegistry,
+		classifierModel: args.classifierModel,
+		questionKey: "decisive",
+		question: {
+			type: "score",
+			instructions:
+				"A unit of work reports a STRUCTURED verification verdict (JSON state only — you see no diffs and no file contents). Spawning an expensive LLM verifier is being considered. Score how DECISIVELY the structured state ALONE establishes that the work genuinely PASSED verification.",
+			criteria: [
+				"1.0 — the evidence lines conclusively prove the pass (explicit passing command exits, concrete artifact refs) and the changed-files list matches the work's expected scope",
+				"0.75 — evidence is strong but at least one line is a claim rather than an artifact",
+				"0.5 — evidence is mixed: some lines pass, others are inconclusive",
+				"0.25 — evidence is thin, generic, or mostly absent",
+				"0.0 — the state proves nothing usable, or any line already indicates a failure",
+			],
+		},
+		state: capVerdictState(args.verdict),
+		fallback: 0,
+		metricRegistry: args.metricRegistry,
+		metricLabels: { consumer: "verifier_pre_gate" },
+	});
+	if (!result.fromClassifier) {
+		// Soft: every classifier failure mode (provider unconfigured, thrown
+		// call, malformed answer) escalates — identical to the pre-U6B spawn
+		// decision. The service's calls_total already counted the outcome; no
+		// decision was made, so no decision metric/event (noise-gate pattern).
+		return { blockVerifier: false, consulted: false, action: "escalate_fallback", score: undefined, confidence: undefined };
+	}
+	let action: VerifierPreGateAction;
+	if (!isPassShapedVerdict(args.verdict.verdict)) {
+		// Spec: escalate when verdict FAILED — and defensively for anything not
+		// unambiguously pass-shaped. Ordered FIRST: a cheap classifier may
+		// never rubber-stamp a failure, whatever its score/confidence.
+		action = "escalate_verdict_failed";
+	} else if (result.confidence === undefined || result.confidence < confidenceThreshold) {
+		// Spec: escalate when confidence thấp. An unreported confidence counts
+		// as low — blocking is the risky branch and needs positive certainty.
+		action = "escalate_low_confidence";
+	} else if (!Number.isFinite(result.score) || result.score < 0 || result.score > 1 || result.score < scoreThreshold) {
+		// Spec: block only on a decisively high score. Out-of-range scores are
+		// treated as non-decisive (defensive) — malformed can only escalate.
+		action = "escalate_low_score";
+	} else {
+		action = "blocked";
+	}
+	const blockVerifier = action === "blocked";
+	try {
+		args.metricRegistry
+			?.counter("crew.classifier.decisions_total", "Classifier-informed decisions by consumer and verdict")
+			.inc({ consumer: "verifier_pre_gate", decision: action });
+	} catch (metricError) {
+		logInternalError("classifier-pre-gate.metric", metricError, `decision=${action}`, "warn");
+	}
+	void appendEventAsync(args.eventsPath, {
+		type: "task.verifier_pre_gate",
+		runId: args.runId,
+		...(args.taskId !== undefined ? { taskId: args.taskId } : {}),
+		message: blockVerifier
+			? "Verifier pre-gate BLOCKED the LLM verifier spawn (structured pass stands)"
+			: `Verifier pre-gate escalated to the LLM verifier (${action})`,
+		data: {
+			action,
+			verdict: args.verdict.verdict.slice(0, VERDICT_MAX_CHARS),
+			score: result.score,
+			confidence: result.confidence,
+			classifierModel: result.usedModel,
+			configuredModel: args.classifierModel,
+			stopReason: result.stopReason,
+			evidenceLineCount: args.verdict.evidenceLines.length,
+			changedFileCount: args.verdict.changedFiles.length,
+		},
+	}).catch(() => {
+		/* no-op: best-effort diagnostic append, ignore delivery errors */
+	});
+	return { blockVerifier, consulted: true, action, score: result.score, confidence: result.confidence };
+}

package/src/runtime/verification/verification-gates.ts

@@ -239,7 +239,11 @@ function validateGateCommand(command: string): void {
 	validateAllowedGateCommands(normalized, command);
 }
 
-async function executeCommand(
+/** U13 (upgrade spec 2026-10-09): exported so the deterministic verify_gate
+ *  engine (verify-gate.ts) reuses the SAME hardened command runner the
+ *  verifier flow already uses — command validation, sanitized env, process-
+ *  group kill, output cap, timeout. Additive export, no behavior change. */
+export async function executeCommand(
 	command: string,
 	cwd: string,
 	timeoutMs: number = 120000,

package/src/runtime/verification/verify-gate.ts

@@ -0,0 +1,394 @@
+/**
+ * U13 (upgrade spec 2026-10-09 §U13): DETERMINISTIC VERIFIER PRE-GATE ENGINE.
+ *
+ * The spec's probe (round 10, 13/13 checks) proved extension tools can run
+ * other tools deterministically in the host process via
+ * `ctx.executeTool("bash", ...)` — the 5th parameter of ToolDefinition.execute
+ * (nested id `<parent>/1`, errors arrive as isError VALUES not throws,
+ * `exit_code` readable in structuredContent; limits 256 nested calls / 8KB
+ * per call / 32KB total args). That unlocks running the verifier's
+ * deterministic checks (typecheck / test:critical / grep evidence lines) for
+ * FREE before deciding whether the expensive LLM verifier worker must spawn.
+ *
+ * TWO ENTRY POINTS share this pure engine:
+ *   1. the `verify_gate` TOOL (src/extension/registration/verify-gate-tool.ts)
+ *      — runs checks via ctx.executeTool("bash", ...) in the host process,
+ *      exposure "codemode" (hidden from the model, callable by other tools);
+ *   2. the verifier SPAWN SITE (task-runner.ts runTeamTask) — runs the same
+ *      engine through the hardened subprocess runner already exported by
+ *      verification-gates.ts (executeCommand: command validation, sanitized
+ *      env, process-group kill, output cap, timeout).
+ *
+ * TWO-LAYER DECISION (spec: "kết hợp classifier pre-gate U6-B — deterministic
+ * trước, classifier sau"):
+ *   - Layer 1 (deterministic, this module): gate PASS → SKIP the LLM verifier
+ *     (U13 acceptance: "một run verification với gate xanh không spawn LLM
+ *     verifier"); gate FAILED → spawn the LLM verifier WITH the gate results
+ *     in its prompt (it must diagnose/report, not re-derive exit codes).
+ *   - Layer 2 (classifier, U6B classifier-pre-gate.ts): consulted ONLY when
+ *     layer 1 is INCONCLUSIVE (no checks resolved — e.g. a repo without
+ *     typecheck/test:critical scripts). A decisively-high classifier score
+ *     over the STRUCTURED verdict state may block the spawn; every other
+ *     outcome escalates. A FAILED gate never reaches the classifier — a cheap
+ *     classifier may never rubber-stamp a failure (U6B escalation policy),
+ *     so consulting it there would only burn a call.
+ *
+ * SAFETY: a gate that cannot run (disabled by env, no checks resolved,
+ * executor failure) degrades to "spawn the LLM verifier as today" — the
+ * pre-gate can only SAVE a spawn on positive deterministic evidence, never
+ * fail a task on its own.
+ *
+ * Metrics (spec acceptance: "metrics số verifier job tiết kiệm"):
+ *   - crew.verification.verify_gate_runs_total{verdict} — gate executions;
+ *   - crew.verification.verifier_spawns_skipped_total{reason} — LLM verifier
+ *     spawns saved (the "tiết kiệm" counter);
+ *   - crew.verification.verifier_spawns_total{reason} — spawns that still
+ *     happened, labeled by which layer let them through.
+ */
+import * as fs from "node:fs";
+import { getCrewEnvBool, getCrewEnvInt } from "../../config/env-vars.ts";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import type { VerifierPreGateResult } from "./classifier-pre-gate.ts";
+import { classifyVerifierPreGate } from "./classifier-pre-gate.ts";
+import { executeCommand } from "./verification-gates.ts";
+
+/** One deterministic check to run. Mirrors the phase-gate shape
+ *  (verification-gates.ts) but kept local so the tool schema can reuse it. */
+export interface VerifyGateCheck {
+	/** Short check name (metrics/events/evidence lines). */
+	name: string;
+	/** Shell command; exit code 0 = pass. */
+	command: string;
+	/** Stop the gate on the first failure of this check (default true). */
+	critical?: boolean;
+}
+
+/** Result of one executed check. */
+export interface VerifyGateCheckResult {
+	name: string;
+	command: string;
+	exitCode: number | null;
+	passed: boolean;
+	durationMs: number;
+	/** Tail of the command output (bounded) — evidence for humans/LLM. */
+	outputTail: string;
+	skipped?: boolean;
+	error?: string;
+}
+
+/** Overall gate verdict. */
+export type VerifyGateVerdict = "PASS" | "FAILED" | "INCONCLUSIVE";
+
+export interface VerifyGateOutcome {
+	verdict: VerifyGateVerdict;
+	checks: VerifyGateCheckResult[];
+	/** Compact structured evidence lines (exit codes + commands). */
+	evidenceLines: string[];
+	allPassed: boolean;
+	totalDurationMs: number;
+}
+
+/** Injected command executor. The TOOL path wraps ctx.executeTool("bash");
+ *  the spawn-site path wraps verification-gates executeCommand (subprocess).
+ *  Must resolve (never reject) — failures come back as exitCode null/error. */
+export type VerifyGateExecutor = (command: string, opts: VerifyGateExecutorOpts) => Promise<VerifyGateExecutorResult>;
+
+export interface VerifyGateExecutorOpts {
+	cwd: string;
+	timeoutMs: number;
+	signal?: AbortSignal;
+}
+
+export interface VerifyGateExecutorResult {
+	exitCode: number | null;
+	output: string;
+	error?: string;
+}
+
+/** Default per-check timeout — mirrors runPhaseGates (verification-gates.ts). */
+export const DEFAULT_VERIFY_GATE_TIMEOUT_MS = 120_000;
+/** Evidence tail budget per check (chars). */
+const OUTPUT_TAIL_MAX_CHARS = 2_000;
+
+/** U13 gate enable resolution: PI_CREW_VERIFY_GATE beats default ON. */
+export function resolveVerifyGateEnabled(explicit?: boolean): boolean {
+	const env = getCrewEnvBool("PI_CREW_VERIFY_GATE");
+	if (env !== undefined) return env;
+	return explicit ?? true;
+}
+
+/** U13 per-check timeout resolution: PI_CREW_VERIFY_GATE_TIMEOUT_MS beats
+ *  default 120000 (mirrors runPhaseGates). Invalid/≤0 → default. */
+export function resolveVerifyGateTimeoutMs(explicit?: number): number {
+	const env = getCrewEnvInt("PI_CREW_VERIFY_GATE_TIMEOUT_MS");
+	const raw = env ?? explicit ?? DEFAULT_VERIFY_GATE_TIMEOUT_MS;
+	return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_VERIFY_GATE_TIMEOUT_MS;
+}
+
+/**
+ * Default check preset — the spec's "check cấu hình" set, resolved from the
+ * target repo's package.json scripts so the gate adapts instead of failing:
+ *   - `typecheck` script present → `npm run --silent typecheck` (critical);
+ *   - `test:critical` script present → `npm run --silent test:critical`
+ *     (critical);
+ *   - grep evidence lines: no universal marker exists, so they are provided
+ *     explicitly via the tool's `checks` param (e.g. the bundle-marker rule
+ *     `grep -c "<marker>" dist/index.mjs`) rather than defaulted.
+ * Repos without either script resolve ZERO checks → INCONCLUSIVE → the
+ * classifier layer (when enabled) or the LLM verifier spawn runs as today.
+ */
+export function defaultVerifyGateChecks(dir: string): VerifyGateCheck[] {
+	let scripts: Record<string, unknown> = {};
+	try {
+		const raw = fs.readFileSync(`${dir}/package.json`, "utf8");
+		const parsed = raw ? (JSON.parse(raw) as { scripts?: Record<string, unknown> }) : undefined;
+		scripts = parsed?.scripts ?? {};
+	} catch {
+		scripts = {};
+	}
+	const checks: VerifyGateCheck[] = [];
+	if (typeof scripts.typecheck === "string") {
+		checks.push({ name: "typecheck", command: "npm run --silent typecheck", critical: true });
+	}
+	if (typeof scripts["test:critical"] === "string") {
+		checks.push({ name: "test-critical", command: "npm run --silent test:critical", critical: true });
+	}
+	return checks;
+}
+
+function tailOutput(output: string): string {
+	if (output.length <= OUTPUT_TAIL_MAX_CHARS) return output;
+	return `…${output.slice(-OUTPUT_TAIL_MAX_CHARS)}`;
+}
+
+/** Cap the number of evidence lines (prompt/metric hygiene). */
+const EVIDENCE_MAX_LINES = 12;
+
+export function evaluateVerifyGateResults(checks: VerifyGateCheckResult[]): VerifyGateOutcome {
+	const ran = checks.filter((c) => !c.skipped);
+	const allPassed = ran.length > 0 && ran.every((c) => c.passed);
+	const verdict: VerifyGateVerdict = ran.length === 0 ? "INCONCLUSIVE" : allPassed ? "PASS" : "FAILED";
+	const evidenceLines = checks
+		.slice(0, EVIDENCE_MAX_LINES)
+		.map((c) =>
+			c.skipped
+				? `${c.name}: SKIPPED — ${c.command}`
+				: `${c.name}: exit=${c.exitCode ?? "err"} ${c.passed ? "PASS" : "FAIL"} — ${c.command}${c.error ? ` (error: ${c.error})` : ""}`,
+		);
+	return {
+		verdict,
+		checks,
+		evidenceLines,
+		allPassed,
+		totalDurationMs: checks.reduce((sum, c) => sum + c.durationMs, 0),
+	};
+}
+
+/** Run the gate checks sequentially through the injected executor.
+ *  Mirrors runPhaseGates semantics: stop on first critical failure; abort
+ *  signal between checks marks the rest skipped. NEVER rejects. */
+export async function runVerifyGate(
+	checks: VerifyGateCheck[],
+	exec: VerifyGateExecutor,
+	opts: { cwd: string; signal?: AbortSignal; timeoutMs?: number },
+): Promise<VerifyGateOutcome> {
+	const timeoutMs = resolveVerifyGateTimeoutMs(opts.timeoutMs);
+	const results: VerifyGateCheckResult[] = [];
+	for (const check of checks) {
+		if (opts.signal?.aborted) {
+			results.push({
+				name: check.name,
+				command: check.command,
+				exitCode: null,
+				passed: false,
+				durationMs: 0,
+				outputTail: "",
+				skipped: true,
+				error: "Aborted",
+			});
+			continue;
+		}
+		const start = Date.now();
+		let execResult: VerifyGateExecutorResult;
+		try {
+			execResult = await exec(check.command, { cwd: opts.cwd, timeoutMs, signal: opts.signal });
+		} catch (error) {
+			// Executor contract says never-reject; defend anyway — an executor
+			// blowup must degrade the CHECK, not the host.
+			execResult = { exitCode: null, output: "", error: error instanceof Error ? error.message : String(error) };
+		}
+		results.push({
+			name: check.name,
+			command: check.command,
+			exitCode: execResult.exitCode,
+			passed: execResult.exitCode === 0,
+			durationMs: Date.now() - start,
+			outputTail: tailOutput(execResult.output ?? ""),
+			...(execResult.error ? { error: execResult.error } : {}),
+		});
+		// Stop on critical failure (default critical) — mirrors runPhaseGates.
+		if (execResult.exitCode !== 0 && check.critical !== false) break;
+	}
+	return evaluateVerifyGateResults(results);
+}
+
+/** Spawn-site executor: the hardened subprocess runner the verifier flow
+ *  already uses (validateGateCommand + sanitized env + group kill + caps). */
+export function createSubprocessVerifyGateExecutor(): VerifyGateExecutor {
+	return async (command, opts) => {
+		if (opts.signal?.aborted) return { exitCode: null, output: "", error: "Aborted" };
+		const { exitCode, output } = await executeCommand(command, opts.cwd, opts.timeoutMs);
+		return { exitCode, output };
+	};
+}
+
+export interface VerifierSpawnDecision {
+	/** true → do NOT spawn the LLM verifier; the gate verdict stands. */
+	skipVerifier: boolean;
+	/** Which layer + branch decided (metric label). */
+	reason: string;
+	/** true → append the gate outcome block to the verifier's prompt. */
+	attachGateContext: boolean;
+}
+
+/** TWO-LAYER decision (deterministic first, classifier second). */
+export function resolveVerifierSpawnDecision(outcome: VerifyGateOutcome, preGate?: VerifierPreGateResult): VerifierSpawnDecision {
+	if (outcome.verdict === "PASS") {
+		return { skipVerifier: true, reason: "deterministic_pass", attachGateContext: false };
+	}
+	if (outcome.verdict === "FAILED") {
+		// The LLM verifier gets the failing evidence in its prompt — it must
+		// diagnose/report the failure, not re-derive exit codes.
+		return { skipVerifier: false, reason: "deterministic_failed", attachGateContext: true };
+	}
+	// INCONCLUSIVE: classifier layer (U6B) may block on a decisively good
+	// structured state; disabled/soft-fail/low-confidence all escalate.
+	if (preGate?.blockVerifier) {
+		return { skipVerifier: true, reason: "classifier_blocked", attachGateContext: false };
+	}
+	return {
+		skipVerifier: false,
+		reason: preGate ? `classifier_${preGate.action}` : "inconclusive_no_classifier",
+		attachGateContext: false,
+	};
+}
+
+/** Render the gate outcome as a compact prompt block for the LLM verifier. */
+export function renderVerifyGateContext(outcome: VerifyGateOutcome): string {
+	const lines = [
+		"## Deterministic verify_gate results (U13 pre-gate)",
+		`Gate verdict: ${outcome.verdict}`,
+		...outcome.evidenceLines.map((line) => `- ${line}`),
+	];
+	for (const check of outcome.checks) {
+		if (!check.skipped && !check.passed && check.outputTail.trim().length > 0) {
+			const tail = check.outputTail.trim().split("\n").slice(-5).join("\n");
+			lines.push(`### ${check.name} output tail`, "```", tail, "```");
+		}
+	}
+	lines.push(
+		"",
+		"The deterministic gate already ran these commands — do NOT re-run them; verify the WORK (diff, files, acceptance), using these results as ground truth for build/test state.",
+	);
+	return lines.join("\n");
+}
+
+/** Human/one-line summary used for the skip path's synthetic result artifact. */
+export function renderVerifyGateSummary(outcome: VerifyGateOutcome, reason: string): string {
+	return [`verify_gate: ${outcome.verdict} (skip reason: ${reason})`, ...outcome.evidenceLines].join("\n");
+}
+
+export interface VerifierGatePreGateInput {
+	cwd: string;
+	/** Explicit checks override the default preset (tool path / tests). */
+	checks?: VerifyGateCheck[];
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	/** U6B classifier layer args — consulted ONLY on INCONCLUSIVE. */
+	classifier?: {
+		enabled: boolean;
+		modelRegistry: unknown;
+		classifierModel: string;
+		eventsPath: string;
+		runId: string;
+		taskId?: string;
+	};
+	metricRegistry?: MetricRegistry;
+}
+
+export interface VerifierGatePreGateResult {
+	outcome: VerifyGateOutcome;
+	decision: VerifierSpawnDecision;
+	preGate?: VerifierPreGateResult;
+	/** Prompt block to append when the verifier still spawns ("" otherwise). */
+	promptContext: string;
+}
+
+function incMetric(registry: MetricRegistry | undefined, name: string, help: string, labels: Record<string, string>): void {
+	try {
+		registry?.counter(name, help).inc(labels);
+	} catch {
+		/* metrics are best-effort; never break the gate */
+	}
+}
+
+/**
+ * Spawn-site orchestration: run the deterministic gate, consult the U6B
+ * classifier layer when inconclusive, resolve the two-layer spawn decision,
+ * and emit the acceptance metrics. NEVER rejects — executor failures degrade
+ * to INCONCLUSIVE checks, which escalate to the LLM verifier.
+ */
+export async function runVerifierGatePreGate(input: VerifierGatePreGateInput): Promise<VerifierGatePreGateResult> {
+	const checks = input.checks ?? defaultVerifyGateChecks(input.cwd);
+	const outcome = await runVerifyGate(checks, createSubprocessVerifyGateExecutor(), {
+		cwd: input.cwd,
+		signal: input.signal,
+		timeoutMs: input.timeoutMs,
+	});
+	let preGate: VerifierPreGateResult | undefined;
+	if (outcome.verdict === "INCONCLUSIVE" && input.classifier?.enabled) {
+		try {
+			preGate = await classifyVerifierPreGate({
+				enabled: true,
+				modelRegistry: input.classifier.modelRegistry,
+				classifierModel: input.classifier.classifierModel,
+				verdict: {
+					verdict: outcome.verdict,
+					evidenceLines: outcome.evidenceLines,
+					changedFiles: [],
+				},
+				eventsPath: input.classifier.eventsPath,
+				runId: input.classifier.runId,
+				...(input.classifier.taskId !== undefined ? { taskId: input.classifier.taskId } : {}),
+				metricRegistry: input.metricRegistry,
+			});
+		} catch {
+			preGate = undefined; // soft: escalate to the LLM verifier
+		}
+	}
+	const decision = resolveVerifierSpawnDecision(outcome, preGate);
+	incMetric(input.metricRegistry, "crew.verification.verify_gate_runs_total", "Deterministic verify_gate executions by verdict", {
+		verdict: outcome.verdict,
+	});
+	if (decision.skipVerifier) {
+		incMetric(
+			input.metricRegistry,
+			"crew.verification.verifier_spawns_skipped_total",
+			"LLM verifier spawns saved by the U13 deterministic pre-gate",
+			{ reason: decision.reason },
+		);
+	} else {
+		incMetric(
+			input.metricRegistry,
+			"crew.verification.verifier_spawns_total",
+			"LLM verifier spawns that still ran, labeled by the deciding layer",
+			{ reason: decision.reason },
+		);
+	}
+	return {
+		outcome,
+		decision,
+		...(preGate ? { preGate } : {}),
+		promptContext: decision.attachGateContext ? renderVerifyGateContext(outcome) : "",
+	};
+}