@gajae-code/coding-agent 0.5.0 → 0.5.2

package/src/gjc-runtime/ultragoal-runtime.ts

@@ -1,9 +1,12 @@
 import * as crypto from "node:crypto";
 import * as path from "node:path";
+import { inflateSync } from "node:zlib";
+
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildUltragoalHudSummary as buildWorkflowUltragoalHudSummary } from "../skill-state/workflow-hud";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
+import { latestUltragoalLedgerEventFromText } from "./ledger-event-renderer";
 import { renderUltragoalStatusMarkdown } from "./state-renderer";
 import { reconcileWorkflowSkillState } from "./state-runtime";
 import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
@@ -92,6 +95,8 @@ export interface UltragoalStatusSummary {
 }
 
 export interface UltragoalCommandResult {
+	reviewBlockerGoalIds?: string[];
+	createdReviewPlan?: boolean;
 	status: number;
 	stdout?: string;
 	stderr?: string;
@@ -794,16 +799,37 @@ function evidenceKindMatches(kind: string, words: string[]): boolean {
 	return words.some(word => kind.includes(word));
 }
 
+type SurfaceFamily = "web" | "cli" | "native" | "api-package" | "algorithm-math" | "unknown";
+
+export function normalizeSurfaceToken(value: string): string {
+	return value.toLowerCase().replaceAll("_", "-").trim();
+}
+
+export function surfaceFamily(value: string): SurfaceFamily {
+	const normalized = normalizeSurfaceToken(value);
+	if (["native", "desktop", "tui"].some(word => normalized.includes(word))) return "native";
+	if (["gui", "web", "browser", "ui", "visual"].some(word => normalized.includes(word))) return "web";
+	if (["cli", "terminal", "command"].some(word => normalized.includes(word))) return "cli";
+	if (["api", "package", "library", "sdk"].some(word => normalized.includes(word))) return "api-package";
+	if (["algorithm", "math", "mathematical", "equation"].some(word => normalized.includes(word))) {
+		return "algorithm-math";
+	}
+	return "unknown";
+}
+
+function isLiveSurfaceFamily(family: SurfaceFamily): boolean {
+	return family === "web" || family === "cli" || family === "native";
+}
+
 function validateSurfaceArtifactCompatibility(
 	surface: string,
 	artifactIds: string[],
 	artifactRefs: Map<string, JsonObject>,
 	fieldName: string,
 ): void {
-	const normalizedSurface = surface.toLowerCase().replaceAll("_", "-");
+	const family = surfaceFamily(surface);
 	const kinds = artifactIds.map(id => normalizedEvidenceKind(artifactRefs.get(id)!));
-	const isGuiOrWeb = ["gui", "web", "browser", "ui", "visual"].some(word => normalizedSurface.includes(word));
-	if (isGuiOrWeb) {
+	if (family === "web") {
 		const hasBrowser = kinds.some(kind =>
 			evidenceKindMatches(kind, ["browser", "playwright", "pandawright", "automation"]),
 		);
@@ -815,31 +841,30 @@ function validateSurfaceArtifactCompatibility(
 		}
 		return;
 	}
-	const surfaceFamilies: Array<{ surface: string[]; evidence: string[]; label: string }> = [
-		{
-			surface: ["cli", "terminal", "command"],
+	const surfaceFamilies: Record<Exclude<SurfaceFamily, "web" | "unknown">, { evidence: string[]; label: string }> = {
+		cli: {
 			evidence: ["cli", "log", "transcript", "terminal", "command", "test-report"],
 			label: "CLI",
 		},
-		{
-			surface: ["api", "package", "library", "sdk"],
+		native: {
+			evidence: ["native", "desktop", "tui", "terminal", "pty", "transcript", "screenshot", "image", "automation"],
+			label: "native",
+		},
+		"api-package": {
 			evidence: ["api", "package", "consumer", "black-box", "test-report"],
 			label: "API/package",
 		},
-		{
-			surface: ["algorithm", "math", "mathematical", "equation"],
+		"algorithm-math": {
 			evidence: ["property", "boundary", "edge", "adversarial", "failure", "math", "algorithm", "test-report"],
 			label: "algorithm/math",
 		},
-	];
-	for (const family of surfaceFamilies) {
-		if (family.surface.some(word => normalizedSurface.includes(word))) {
-			if (!kinds.some(kind => evidenceKindMatches(kind, family.evidence))) {
-				throw new Error(
-					`qualityGate ${fieldName} for ${family.label} surfaces must reference compatible artifact kinds`,
-				);
-			}
-			return;
+	};
+	if (family !== "unknown") {
+		const expected = surfaceFamilies[family];
+		if (!kinds.some(kind => evidenceKindMatches(kind, expected.evidence))) {
+			throw new Error(
+				`qualityGate ${fieldName} for ${expected.label} surfaces must reference compatible artifact kinds`,
+			);
 		}
 	}
 }
@@ -876,31 +901,850 @@ async function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise
 	}
 }
 
-async function requireSubstantiveArtifactEvidence(cwd: string, row: JsonObject, fieldName: string): Promise<void> {
-	if (isSubstantiveEvidence(row.inlineEvidence) || isSubstantiveEvidence(row.evidence)) return;
-	if (hasTypedVerifiedReceipt(row.verifiedReceipt) || hasTypedVerifiedReceipt(row.receipt)) return;
-	if (await hasExistingNonEmptyArtifact(cwd, row.path)) return;
+async function readArtifactBytes(cwd: string, row: JsonObject, fieldName: string): Promise<Buffer | null> {
+	const artifactPath = nonEmptyString(row.path);
+	if (!artifactPath) return null;
+	const resolved = path.resolve(cwd, artifactPath);
+	try {
+		const file = Bun.file(resolved);
+		if (!(await file.exists())) return null;
+		return Buffer.from(await file.arrayBuffer());
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw new Error(`qualityGate ${fieldName} artifact could not be read: ${String(error)}`);
+	}
+}
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_START_OF_IMAGE = 0xd8;
+const JPEG_END_OF_IMAGE = 0xd9;
+const JPEG_START_OF_SCAN = 0xda;
+const JPEG_STANDALONE_MARKERS = new Set([0x01, 0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7]);
+const PNG_CRC_TABLE = new Uint32Array(256).map((_, index) => {
+	let crc = index;
+	for (let bit = 0; bit < 8; bit++) crc = crc & 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+	return crc >>> 0;
+});
+
+function pngCrc32(bytes: Buffer): number {
+	let crc = 0xffffffff;
+	for (const byte of bytes) crc = PNG_CRC_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+	return (crc ^ 0xffffffff) >>> 0;
+}
+
+function parsePngDimensions(
+	bytes: Buffer,
+): { width: number; height: number; headerBytes: number; sampleBytes?: Buffer } | null {
+	if (bytes.length < 45) return null;
+	if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+	let offset = 8;
+	let width = 0;
+	let height = 0;
+	let sawIhdr = false;
+	let sawIdat = false;
+	const idatChunks: Buffer[] = [];
+	while (offset + 12 <= bytes.length) {
+		const chunkStart = offset;
+		const length = bytes.readUInt32BE(offset);
+		offset += 4;
+		const type = bytes.toString("ascii", offset, offset + 4);
+		offset += 4;
+		if (offset + length + 4 > bytes.length) return null;
+		const data = bytes.subarray(offset, offset + length);
+		offset += length;
+		const expectedCrc = bytes.readUInt32BE(offset);
+		offset += 4;
+		if (pngCrc32(bytes.subarray(chunkStart + 4, offset - 4)) !== expectedCrc) return null;
+		if (!sawIhdr) {
+			if (type !== "IHDR" || length !== 13) return null;
+			width = data.readUInt32BE(0);
+			height = data.readUInt32BE(4);
+			if (
+				width === 0 ||
+				height === 0 ||
+				data[8] !== 8 ||
+				![2, 6].includes(data[9]!) ||
+				data[10] !== 0 ||
+				data[11] !== 0 ||
+				data[12] !== 0
+			)
+				return null;
+			sawIhdr = true;
+		} else if (type === "IHDR") return null;
+		if (type === "IDAT") {
+			if (!sawIhdr || length === 0) return null;
+			sawIdat = true;
+			idatChunks.push(data);
+		}
+		if (type === "IEND") {
+			if (length !== 0 || !sawIhdr || !sawIdat || offset !== bytes.length) return null;
+			try {
+				return { width, height, headerBytes: 8, sampleBytes: inflateSync(Buffer.concat(idatChunks)) };
+			} catch {
+				return null;
+			}
+		}
+	}
+	return null;
+}
+
+function parseJpegDimensions(
+	bytes: Buffer,
+): { width: number; height: number; headerBytes: number; sampleBytes?: Buffer } | null {
+	if (bytes.length < 8 || bytes[0] !== 0xff || bytes[1] !== JPEG_START_OF_IMAGE) return null;
+	let offset = 2;
+	let dimensions: { width: number; height: number; headerBytes: number } | null = null;
+	let sawStartOfScan = false;
+	let scanStart = -1;
+	while (offset < bytes.length) {
+		if (bytes[offset] !== 0xff) return null;
+		while (offset < bytes.length && bytes[offset] === 0xff) offset++;
+		if (offset >= bytes.length) return null;
+		const marker = bytes[offset++];
+		if (marker === 0x00) return null;
+		if (marker === JPEG_END_OF_IMAGE) return null;
+		if (JPEG_STANDALONE_MARKERS.has(marker)) continue;
+		if (offset + 2 > bytes.length) return null;
+		const segmentLength = bytes.readUInt16BE(offset);
+		if (segmentLength < 2 || offset + segmentLength > bytes.length) return null;
+		const segmentDataEnd = offset + segmentLength;
+		if (marker === 0xc0 || marker === 0xc1 || marker === 0xc2) {
+			if (segmentLength < 8) return null;
+			dimensions = {
+				width: bytes.readUInt16BE(offset + 5),
+				height: bytes.readUInt16BE(offset + 3),
+				headerBytes: offset + segmentLength,
+			};
+		}
+		if (marker === JPEG_START_OF_SCAN) {
+			if (!dimensions || segmentDataEnd >= bytes.length) return null;
+			sawStartOfScan = true;
+			scanStart = segmentDataEnd;
+			break;
+		}
+		offset += segmentLength;
+	}
+	if (!dimensions || !sawStartOfScan || scanStart < 0) return null;
+	let scanOffset = scanStart;
+	let entropyBytes = 0;
+	while (scanOffset < bytes.length) {
+		const byte = bytes[scanOffset++]!;
+		if (byte !== 0xff) {
+			entropyBytes++;
+			continue;
+		}
+		if (scanOffset >= bytes.length) return null;
+		const marker = bytes[scanOffset++]!;
+		if (marker === 0x00) {
+			entropyBytes++;
+			continue;
+		}
+		if (JPEG_STANDALONE_MARKERS.has(marker)) continue;
+		if (marker === JPEG_END_OF_IMAGE) {
+			if (scanOffset !== bytes.length || entropyBytes < 32) return null;
+			return { ...dimensions, sampleBytes: bytes.subarray(scanStart, scanOffset - 2) };
+		}
+		return null;
+	}
+	return null;
+}
+
+function unsupportedScreenshotFormat(bytes: Buffer): string | null {
+	if (bytes.toString("ascii", 0, 6) === "GIF87a" || bytes.toString("ascii", 0, 6) === "GIF89a") return "GIF";
+	if (bytes.toString("ascii", 0, 2) === "BM") return "BMP";
+	if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP")
+		return "WebP";
+	return null;
+}
+
+function parseImageDimensions(
+	bytes: Buffer,
+): { width: number; height: number; headerBytes: number; sampleBytes?: Buffer } | null {
+	return parsePngDimensions(bytes) ?? parseJpegDimensions(bytes);
+}
+
+function hasNonUniformImageBytes(bytes: Buffer, headerBytes: number, sampleBytes?: Buffer): boolean {
+	const source = sampleBytes ?? bytes;
+	const sampleStart = sampleBytes ? 0 : Math.min(Math.max(headerBytes, 0), source.length);
+	const sampleLength = source.length - sampleStart;
+	if (sampleLength < 32) return false;
+	const windows: Buffer[] = [];
+	for (let index = 0; index < 64; index++) {
+		const offset = sampleStart + Math.floor(((sampleLength - 32) * index) / 63);
+		windows.push(source.subarray(offset, offset + 32));
+	}
+	const byteCounts = new Map<number, number>();
+	let total = 0;
+	for (const window of windows) {
+		for (const byte of window) {
+			byteCounts.set(byte, (byteCounts.get(byte) ?? 0) + 1);
+			total++;
+		}
+	}
+	const first = windows[0]!;
+	const differingWindows = windows.slice(1).filter(window => !window.equals(first)).length;
+	const maxCount = Math.max(...byteCounts.values());
+	return byteCounts.size >= 16 && differingWindows >= 8 && maxCount / total <= 0.95;
+}
+
+async function validateScreenshotArtifact(cwd: string, row: JsonObject, fieldName: string): Promise<boolean> {
+	const bytes = await readArtifactBytes(cwd, row, fieldName);
+	if (!bytes) throw new Error(`qualityGate ${fieldName} screenshot artifact path must resolve to an existing file`);
+	if (bytes.length < 4096) throw new Error(`qualityGate ${fieldName} screenshot artifact must be at least 4096 bytes`);
+	const unsupportedFormat = unsupportedScreenshotFormat(bytes);
+	if (unsupportedFormat) {
+		throw new Error(
+			`qualityGate ${fieldName} unsupported/undecodable screenshot format ${unsupportedFormat}; use PNG or fully marker-validated JPEG`,
+		);
+	}
+	const dimensions = parseImageDimensions(bytes);
+	if (!dimensions)
+		throw new Error(`qualityGate ${fieldName} screenshot artifact must be a decodable PNG or JPEG image`);
+	if (dimensions.width < 320 || dimensions.height < 180) {
+		throw new Error(`qualityGate ${fieldName} screenshot artifact must be at least 320x180 pixels`);
+	}
+	if (!hasNonUniformImageBytes(bytes, dimensions.headerBytes, dimensions.sampleBytes)) {
+		throw new Error(
+			`qualityGate ${fieldName} screenshot artifact must be non-uniform, not blank, solid, tiny, or placeholder imagery`,
+		);
+	}
+	return true;
+}
+
+function normalizeTranscriptTimestamp(value: unknown): number | null {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value !== "string" || value.trim().length === 0) return null;
+	const numeric = Number(value);
+	if (Number.isFinite(numeric)) return numeric;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : null;
+}
+
+function transcriptSurfaceCompatible(value: unknown, family: SurfaceFamily): boolean {
+	const surface = nonEmptyString(value);
+	return !surface || family === "unknown" || surfaceFamily(surface) === family;
+}
+
+function actionSelectorRequired(type: string): boolean {
+	return ["click", "fill", "press", "assert", "screenshot", "observe"].includes(type);
+}
+
+async function validateAutomationTranscriptArtifact(
+	cwd: string,
+	row: JsonObject,
+	fieldName: string,
+	options: { surfaceFamily: SurfaceFamily },
+): Promise<boolean> {
+	const bytes = await readArtifactBytes(cwd, row, fieldName);
+	if (!bytes) throw new Error(`qualityGate ${fieldName} automation transcript path must resolve to an existing file`);
+	let transcript: JsonObject;
+	try {
+		const parsed = JSON.parse(bytes.toString("utf8"));
+		transcript = requireQualityGateObject(parsed, `${fieldName}.transcript`);
+	} catch (error) {
+		throw new Error(`qualityGate ${fieldName} automation transcript must be valid JSON: ${String(error)}`);
+	}
+	if (transcript.schemaVersion !== 1)
+		throw new Error(`qualityGate ${fieldName} automation transcript schemaVersion must be 1`);
+	if (!transcriptSurfaceCompatible(transcript.surface, options.surfaceFamily)) {
+		throw new Error(
+			`qualityGate ${fieldName} automation transcript surface is not compatible with ${options.surfaceFamily}`,
+		);
+	}
+	if (!nonEmptyString(transcript.tool))
+		throw new Error(`qualityGate ${fieldName} automation transcript tool must be non-empty`);
+	const actions = requireObjectArray(transcript.actions, `${fieldName}.actions`);
+	if (actions.length < 1) throw new Error(`qualityGate ${fieldName} automation transcript actions must be non-empty`);
+	const assertionsValue = transcript.assertions;
+	const assertions =
+		assertionsValue === undefined ? [] : requireObjectArray(assertionsValue, `${fieldName}.assertions`);
+	const timestamps: number[] = [];
+	let hasSelectorBearingEntry = false;
+	for (const [index, action] of actions.entries()) {
+		const actionField = `${fieldName}.actions[${index}]`;
+		const type = requiredStringField(action, "type", actionField).toLowerCase();
+		const timestamp = normalizeTranscriptTimestamp(action.timestamp);
+		if (timestamp === null) throw new Error(`qualityGate ${actionField}.timestamp must be present and parseable`);
+		timestamps.push(timestamp);
+		const selector = nonEmptyString(action.selector);
+		if (actionSelectorRequired(type) && !selector)
+			throw new Error(`qualityGate ${actionField}.selector must be non-empty`);
+		if (type === "goto" && !nonEmptyString(action.url))
+			throw new Error(`qualityGate ${actionField}.url must be non-empty`);
+		if (type === "custom" && !selector && !nonEmptyString(action.target)) {
+			throw new Error(`qualityGate ${actionField}.selector or target must be non-empty`);
+		}
+		if (selector) hasSelectorBearingEntry = true;
+	}
+	for (const [index, assertion] of assertions.entries()) {
+		const assertionField = `${fieldName}.assertions[${index}]`;
+		const timestamp = normalizeTranscriptTimestamp(assertion.timestamp);
+		if (timestamp === null) throw new Error(`qualityGate ${assertionField}.timestamp must be present and parseable`);
+		timestamps.push(timestamp);
+		if (nonEmptyString(assertion.status)?.toLowerCase() !== PASSED_STATUS) {
+			throw new Error(`qualityGate ${assertionField}.status must be passed`);
+		}
+		if (nonEmptyString(assertion.selector)) hasSelectorBearingEntry = true;
+	}
+	for (let index = 1; index < timestamps.length; index++) {
+		if (timestamps[index]! < timestamps[index - 1]!) {
+			throw new Error(`qualityGate ${fieldName} automation transcript timestamps must be monotonic non-decreasing`);
+		}
+	}
+	if (!hasSelectorBearingEntry) {
+		throw new Error(
+			`qualityGate ${fieldName} automation transcript must include at least one selector-bearing action or assertion`,
+		);
+	}
+	return true;
+}
+
+async function validatePtyCaptureArtifact(cwd: string, row: JsonObject, fieldName: string): Promise<boolean> {
+	const bytes = await readArtifactBytes(cwd, row, fieldName);
+	if (!bytes) throw new Error(`qualityGate ${fieldName} PTY capture path must resolve to an existing file`);
+	if (bytes.length < 512) throw new Error(`qualityGate ${fieldName} PTY capture must be at least 512 bytes`);
+	const text = bytes.toString("utf8");
+	const hasCsi = /\x1b\[[0-?]*[ -/]*[@-~]/.test(text);
+	const hasOsc = /\x1b\][^\x07]*(?:\x07|\x1b\\)/.test(text);
+	const hasAltOrCursor = /\x1b\[\?1049[hl]|\x1b\[H|\x1b\[2J/.test(text);
+	const hasRedraw = /[\r\b]/.test(text) && hasCsi;
+	if (!hasCsi && !hasOsc && !hasAltOrCursor && !hasRedraw) {
+		throw new Error(`qualityGate ${fieldName} PTY capture must contain terminal control sequences`);
+	}
+	if (!/[\x20-\x7e]{10,}/.test(text)) {
+		throw new Error(
+			`qualityGate ${fieldName} PTY capture must contain a printable text run of at least 10 characters`,
+		);
+	}
+	return true;
+}
+
+function structuralArtifactKind(row: JsonObject): "screenshot" | "automation" | "pty" | null {
+	const kind = normalizedEvidenceKind(row);
+	if (evidenceKindMatches(kind, ["screenshot", "image", "visual"])) return "screenshot";
+	if (evidenceKindMatches(kind, ["browser", "playwright", "pandawright", "automation", "app-automation"]))
+		return "automation";
+	if (evidenceKindMatches(kind, ["pty", "tui", "terminal-capture"])) return "pty";
+	return null;
+}
+
+async function validateStructuralArtifact(
+	cwd: string,
+	row: JsonObject,
+	fieldName: string,
+	options: { surfaceFamily: SurfaceFamily; live: boolean },
+): Promise<boolean> {
+	void options.live;
+	const kind = structuralArtifactKind(row);
+	if (!kind) return false;
+	if (kind === "screenshot") return validateScreenshotArtifact(cwd, row, fieldName);
+	if (kind === "automation") return validateAutomationTranscriptArtifact(cwd, row, fieldName, options);
+	if (kind === "pty") return validatePtyCaptureArtifact(cwd, row, fieldName);
+	return false;
+}
+
+const CLI_REPLAY_MAX_OUTPUT_BYTES = 1024 * 1024;
+const CLI_REPLAY_DEFAULT_TIMEOUT_MS = 10_000;
+const CLI_REPLAY_MIN_TIMEOUT_MS = 1_000;
+const CLI_REPLAY_MAX_TIMEOUT_MS = 30_000;
+const CLI_REPLAY_EXEMPT_REASON_CODES = new Set([
+	"unsafe_side_effect",
+	"requires_credentials",
+	"requires_network",
+	"non_deterministic_external",
+	"destructive",
+	"interactive_only",
+	"platform_unavailable",
+]);
+const CLI_REPLAY_ENV_BASE: Record<string, string> = { CI: "1", NO_COLOR: "1", GJC_ULTRAGOAL_REPLAY: "1" };
+const CLI_REPLAY_SAFE_ENV_NAMES = new Set(["LANG", "LC_ALL", "LC_CTYPE", "TZ"]);
+const CLI_REPLAY_DANGEROUS_ENV_NAME_PATTERN =
+	/^(?:NODE_OPTIONS|GIT_EXTERNAL_DIFF|GIT_SSH|GIT_SSH_COMMAND|GIT_PAGER|PATH|LD_PRELOAD|LD_LIBRARY_PATH)$|^(?:GIT_CONFIG|DYLD_|BUN_|NPM_CONFIG_)|(?:^|_)OPTIONS$|PRELOAD$/;
+const ANSI_ESCAPE_PATTERN = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\)|[@-Z\\-_])/g;
+
+function clampCliReplayTimeout(value: unknown): number {
+	if (value === undefined) return CLI_REPLAY_DEFAULT_TIMEOUT_MS;
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		throw new Error("qualityGate CLI replay timeoutMs must be a finite number");
+	}
+	return Math.min(CLI_REPLAY_MAX_TIMEOUT_MS, Math.max(CLI_REPLAY_MIN_TIMEOUT_MS, Math.trunc(value)));
+}
+
+function basenameCommand(value: string): string {
+	return path.basename(value).toLowerCase();
+}
+
+function isDeterministicConsoleLogReplay(code: string): boolean {
+	let remaining = code.trim();
+	if (remaining.length === 0) return false;
+	let matched = false;
+	while (remaining.length > 0) {
+		const match =
+			/^console\.log\(\s*("(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\$])*`)\s*\)\s*;?\s*/.exec(
+				remaining,
+			);
+		if (!match) return false;
+		const statement = match[0]!;
+		const literal = match[1]!;
+		if (literal.startsWith("`") && literal.includes("${")) return false;
+		matched = true;
+		remaining = remaining.slice(statement.length);
+	}
+	return matched;
+}
+
+function hasShellRedirectionToken(value: string): boolean {
+	return /^(?:[<>]|\d?[<>]|\d?>&\d|\|\|?|&&|;)$/.test(value) || /(?:^|[^\w])-?>/.test(value);
+}
+
+function isSafeRefOrPathspec(value: string): boolean {
+	return value.length > 0 && !value.startsWith("-") && !/[\0\n\r]/.test(value) && !hasShellRedirectionToken(value);
+}
+
+function isAllowedGitReplayCommand(args: readonly string[]): boolean {
+	const subcommand = args[0];
+	const rest = args.slice(1);
+	if (subcommand === "status") return rest.every(arg => ["--short", "--porcelain", "--branch"].includes(arg));
+	if (subcommand === "rev-parse" || subcommand === "merge-base")
+		return rest.length > 0 && rest.every(isSafeRefOrPathspec);
+	if (subcommand !== "diff" && subcommand !== "show" && subcommand !== "log") return false;
+	let pathspecMode = false;
+	for (const arg of rest) {
+		if (arg === "--") {
+			pathspecMode = true;
+			continue;
+		}
+		if (pathspecMode) {
+			if (!isSafeRefOrPathspec(arg)) return false;
+			continue;
+		}
+		if (["--stat", "--name-only", "--oneline", "--no-ext-diff"].includes(arg)) continue;
+		if (!isSafeRefOrPathspec(arg)) return false;
+	}
+	return true;
+}
+
+function isBareExecutableName(value: string): boolean {
+	// The allowlist is keyed on the basename, but the raw command[0] is what gets spawned.
+	// Reject path-qualified or case-spoofed executables (e.g. ./git, /tmp/npm, scripts/node, GIT)
+	// so an attacker-controlled binary cannot impersonate a trusted tool.
+	return (
+		value.length > 0 &&
+		!value.includes("/") &&
+		!value.includes("\\") &&
+		value === path.basename(value) &&
+		value === value.toLowerCase()
+	);
+}
+
+function isAllowedCliReplayCommand(command: readonly string[]): boolean {
+	if (
+		command.length === 0 ||
+		command.some(arg => arg.trim() !== arg || arg.length === 0 || hasShellRedirectionToken(arg))
+	)
+		return false;
+	if (!isBareExecutableName(command[0]!)) return false;
+	const executable = basenameCommand(command[0]!);
+	const args = command.slice(1);
+	if (executable === "bun" || executable === "node") {
+		if (args.length === 1 && args[0] === "--version") return true;
+		return args.length === 2 && args[0] === "-e" && isDeterministicConsoleLogReplay(args[1]!);
+	}
+	if (executable === "npm" || executable === "pnpm" || executable === "yarn") {
+		return (args.length === 1 && args[0] === "--version") || (args.length === 1 && args[0] === "list");
+	}
+	if (executable === "git") return isAllowedGitReplayCommand(args);
+	if (executable === "gjc") return args.length === 1 && ["read", "status"].includes(args[0] ?? "");
+	return false;
+}
+
+function resolveCliReplayCommand(command: string[]): string[] {
+	if (basenameCommand(command[0]!) === "bun") return [process.execPath, ...command.slice(1)];
+	return command;
+}
+
+function resolveUnderCwd(cwd: string, replayCwd: unknown, fieldName: string): string {
+	const relative = replayCwd === undefined ? "." : nonEmptyString(replayCwd);
+	if (!relative) throw new Error(`qualityGate ${fieldName}.cwd must be a non-empty string when provided`);
+	const root = path.resolve(cwd);
+	const resolved = path.resolve(root, relative);
+	const relativeToRoot = path.relative(root, resolved);
+	if (relativeToRoot === ".." || relativeToRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeToRoot)) {
+		throw new Error(`qualityGate ${fieldName}.cwd must resolve under the repository cwd`);
+	}
+	return resolved;
+}
+
+function buildCliReplayEnv(value: unknown, fieldName: string): Record<string, string> {
+	const env: Record<string, string> = { ...CLI_REPLAY_ENV_BASE };
+	if (value === undefined) return env;
+	const object = requireQualityGateObject(value, `${fieldName}.env`);
+	for (const [key, envValue] of Object.entries(object)) {
+		if (!/^[A-Z_][A-Z0-9_]*$/.test(key))
+			throw new Error(`qualityGate ${fieldName}.env.${key} must be an uppercase environment key`);
+		if (CLI_REPLAY_DANGEROUS_ENV_NAME_PATTERN.test(key) || !CLI_REPLAY_SAFE_ENV_NAMES.has(key)) {
+			throw new Error(`qualityGate ${fieldName}.env.${key} is not in the CLI replay safe environment allowlist`);
+		}
+		if (typeof envValue !== "string") throw new Error(`qualityGate ${fieldName}.env.${key} must be a string`);
+		env[key] = envValue;
+	}
+	return env;
+}
+
+function normalizeCliReplayOutput(value: string, cwd: string): string {
+	let normalized = value.replace(ANSI_ESCAPE_PATTERN, "").replace(/\r\n?/g, "\n");
+	const home = process.env.HOME;
+	const replacements: Array<[RegExp, string]> = [
+		[/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\b/g, "<TIMESTAMP>"],
+		[/\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi, "<UUID>"],
+		[/\b[0-9a-f]{7,}\b/gi, "<HASH>"],
+		[/(?:\/private)?\/var\/folders\/[^\s"']+|\/tmp\/[^\s"']+|\/var\/tmp\/[^\s"']+/g, "<TMP>"],
+	];
+	for (const candidate of [path.resolve(cwd), home]) {
+		if (!candidate) continue;
+		const escaped = candidate.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		normalized = normalized.replace(new RegExp(escaped, "g"), candidate === home ? "<HOME>" : "<CWD>");
+	}
+	for (const [pattern, replacement] of replacements) normalized = normalized.replace(pattern, replacement);
+	const lines = normalized.split("\n").map(line => line.replace(/[ \t]+$/g, ""));
+	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines.join("\n");
+}
+
+async function readCliReplayRecord(cwd: string, row: JsonObject, fieldName: string): Promise<JsonObject | null> {
+	const inline = qualityGateObject(row.replay) ?? (row.kind === "cli-replay" ? row : null);
+	if (inline) return inline;
+	if (!evidenceKindMatches(normalizedEvidenceKind(row), ["cli-replay", "command-replay"])) return null;
+	const bytes = await readArtifactBytes(cwd, row, fieldName);
+	if (!bytes) return null;
+	try {
+		return requireQualityGateObject(JSON.parse(bytes.toString("utf8")), `${fieldName}.replay`);
+	} catch (error) {
+		throw new Error(`qualityGate ${fieldName} CLI replay artifact must be valid JSON: ${String(error)}`);
+	}
+}
+
+function parseCliReplayRecord(
+	record: JsonObject,
+	fieldName: string,
+): {
+	command: string[];
+	replayCwd: unknown;
+	env: Record<string, string>;
+	timeoutMs: number;
+	expectedExitCode: number;
+	recordedStdout: string;
+	invariants: JsonObject[];
+} {
+	if (record.schemaVersion !== 1) throw new Error(`qualityGate ${fieldName}.schemaVersion must be 1`);
+	if (record.kind !== "cli-replay") throw new Error(`qualityGate ${fieldName}.kind must be cli-replay`);
+	if (record.command !== undefined && typeof record.command === "string") {
+		throw new Error(`qualityGate ${fieldName}.command must be an argv string array, not a shell string`);
+	}
+	const command = nonEmptyStringArray(record.command);
+	if (!command) throw new Error(`qualityGate ${fieldName}.command must be a non-empty string array`);
+	if (record.replaySafe !== true)
+		throw new Error(`qualityGate ${fieldName}.replaySafe must be true before CLI replay executes`);
+	if (!isAllowedCliReplayCommand(command))
+		throw new Error(`qualityGate ${fieldName}.command is not in the conservative CLI replay allowlist`);
+	if (record.normalization !== undefined && record.normalization !== "default") {
+		throw new Error(`qualityGate ${fieldName}.normalization must be default when provided`);
+	}
+	if (typeof record.recordedStdout !== "string")
+		throw new Error(`qualityGate ${fieldName}.recordedStdout must be a string`);
+	if (record.recordedStderr !== undefined && typeof record.recordedStderr !== "string") {
+		throw new Error(`qualityGate ${fieldName}.recordedStderr must be a string when provided`);
+	}
+	const expectedExitCode = record.expectedExitCode === undefined ? 0 : record.expectedExitCode;
+	if (typeof expectedExitCode !== "number" || !Number.isInteger(expectedExitCode)) {
+		throw new Error(`qualityGate ${fieldName}.expectedExitCode must be an integer`);
+	}
+	const invariants =
+		record.invariants === undefined ? [] : requireObjectArray(record.invariants, `${fieldName}.invariants`);
+	return {
+		command: command.map(item => item.trim()),
+		replayCwd: record.cwd,
+		env: buildCliReplayEnv(record.env, fieldName),
+		timeoutMs: clampCliReplayTimeout(record.timeoutMs),
+		expectedExitCode,
+		recordedStdout: record.recordedStdout,
+		invariants,
+	};
+}
+
+function validateCliReplayInvariants(invariants: JsonObject[], stdout: string, fieldName: string): void {
+	for (const [index, invariant] of invariants.entries()) {
+		const invariantField = `${fieldName}.invariants[${index}]`;
+		const type = requiredStringField(invariant, "type", invariantField);
+		const value = requiredStringField(invariant, "value", invariantField);
+		if (type === "substring" && !stdout.includes(value))
+			throw new Error(`qualityGate ${invariantField} substring invariant did not match stdout`);
+		else if (type === "not_substring" && stdout.includes(value))
+			throw new Error(`qualityGate ${invariantField} not_substring invariant matched stdout`);
+		else if (type === "regex") {
+			const flags = invariant.flags === undefined ? "" : requiredStringField(invariant, "flags", invariantField);
+			if (!/^[im]*$/.test(flags)) throw new Error(`qualityGate ${invariantField}.flags may only contain i and m`);
+			if (!new RegExp(value, flags).test(stdout))
+				throw new Error(`qualityGate ${invariantField} regex invariant did not match stdout`);
+		} else if (type !== "substring" && type !== "not_substring") {
+			throw new Error(`qualityGate ${invariantField}.type must be substring, regex, or not_substring`);
+		}
+	}
+}
+
+async function collectCliReplayOutput(
+	stream: ReadableStream<Uint8Array> | null,
+): Promise<{ text: string; truncated: boolean }> {
+	if (!stream) return { text: "", truncated: false };
+	const reader = stream.getReader();
+	const chunks: Buffer[] = [];
+	let size = 0;
+	let truncated = false;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (size < CLI_REPLAY_MAX_OUTPUT_BYTES) {
+				const remaining = CLI_REPLAY_MAX_OUTPUT_BYTES - size;
+				const chunk = Buffer.from(value.subarray(0, remaining));
+				chunks.push(chunk);
+				size += chunk.length;
+			}
+			if (value.length > 0 && size >= CLI_REPLAY_MAX_OUTPUT_BYTES) {
+				truncated = true;
+				await reader.cancel().catch(() => undefined);
+				break;
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return { text: Buffer.concat(chunks).toString("utf8"), truncated };
+}
+
+export interface ReplayProcessHandle {
+	readonly exited: Promise<number>;
+	kill(signal?: number | NodeJS.Signals): void;
+}
+
+export async function waitForReplayProcessWithTimeout(
+	process: ReplayProcessHandle,
+	timeoutMs: number,
+	graceMs = 2000,
+): Promise<number> {
+	let timeoutTimer: NodeJS.Timeout | undefined;
+	let graceTimer: NodeJS.Timeout | undefined;
+	const timedOut = Symbol("timedOut");
+	const timeout = new Promise<typeof timedOut>(resolve => {
+		timeoutTimer = setTimeout(() => resolve(timedOut), timeoutMs);
+	});
+	const first = await Promise.race([process.exited, timeout]);
+	if (first !== timedOut) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		return first;
+	}
+	process.kill("SIGTERM");
+	const killed = Symbol("killed");
+	const grace = new Promise<typeof killed>(resolve => {
+		graceTimer = setTimeout(() => {
+			process.kill("SIGKILL");
+			resolve(killed);
+		}, graceMs);
+	});
+	await Promise.race([process.exited, grace]);
+	await process.exited.catch(() => undefined);
+	if (timeoutTimer) clearTimeout(timeoutTimer);
+	if (graceTimer) clearTimeout(graceTimer);
+	throw new Error("timeout");
+}
+
+async function validateReplayExemptFallback(
+	cwd: string,
+	record: JsonObject,
+	fieldName: string,
+	artifactRefs: Map<string, JsonObject>,
+	options: { surfaceFamily: SurfaceFamily; live: boolean },
+): Promise<boolean> {
+	const exempt = qualityGateObject(record.replayExempt);
+	if (!exempt) return false;
+	const reasonCode = requiredStringField(exempt, "reasonCode", `${fieldName}.replayExempt`);
+	if (!CLI_REPLAY_EXEMPT_REASON_CODES.has(reasonCode))
+		throw new Error(`qualityGate ${fieldName}.replayExempt.reasonCode is not recognized`);
+	const reason = requiredStringField(exempt, "reason", `${fieldName}.replayExempt`);
+	if (!isSubstantiveEvidence(reason) || reason.length < 30)
+		throw new Error(`qualityGate ${fieldName}.replayExempt.reason must be audited and substantive`);
+	requiredStringField(exempt, "approvedBy", `${fieldName}.replayExempt`);
+	const fallbackRefs = requireStringLinks(
+		exempt.fallbackArtifactRefs,
+		`${fieldName}.replayExempt.fallbackArtifactRefs`,
+	);
+	requireResolvedLinks(fallbackRefs, artifactRefs, `${fieldName}.replayExempt.fallbackArtifactRefs`);
+	let validFallback = false;
+	for (const fallbackRef of fallbackRefs) {
+		if (fallbackRef === requiredStringField(record, "id", fieldName)) {
+			throw new Error(`qualityGate ${fieldName}.replayExempt fallback must not reference the replay record itself`);
+		}
+		const fallback = artifactRefs.get(fallbackRef)!;
+		if (await validateStructuralArtifact(cwd, fallback, `executorQa.artifactRefs.${fallbackRef}`, options))
+			validFallback = true;
+	}
+	if (!validFallback)
+		throw new Error(
+			`qualityGate ${fieldName}.replayExempt requires at least one structurally-valid fallback artifact`,
+		);
+	return true;
+}
+async function validateCliReplay(
+	cwd: string,
+	row: JsonObject,
+	fieldName: string,
+	options: { live: boolean },
+): Promise<boolean> {
+	const record = await readCliReplayRecord(cwd, row, fieldName);
+	if (!record) return false;
+	if (record.replayExempt !== undefined) {
+		throw new Error(
+			`qualityGate ${fieldName}.replayExempt can only be validated from surfaceEvidence with fallback context`,
+		);
+	}
+	void options.live;
+	const replay = parseCliReplayRecord(record, fieldName);
+	const replayCwd = resolveUnderCwd(cwd, replay.replayCwd, fieldName);
+	const process = Bun.spawn(resolveCliReplayCommand(replay.command), {
+		cwd: replayCwd,
+		env: replay.env,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	try {
+		const [stdout, stderr, exitCode] = await Promise.all([
+			collectCliReplayOutput(process.stdout),
+			collectCliReplayOutput(process.stderr),
+			waitForReplayProcessWithTimeout(process, replay.timeoutMs),
+		]);
+		if (stdout.truncated || stderr.truncated)
+			throw new Error(`qualityGate ${fieldName} CLI replay output exceeded 1 MiB buffer cap`);
+		if (exitCode !== replay.expectedExitCode) {
+			throw new Error(
+				`qualityGate ${fieldName} CLI replay exit code ${exitCode} did not match expected ${replay.expectedExitCode}`,
+			);
+		}
+		const actualStdout = normalizeCliReplayOutput(stdout.text, cwd);
+		const recordedStdout = normalizeCliReplayOutput(replay.recordedStdout, cwd);
+		if (replay.invariants.length > 0) {
+			validateCliReplayInvariants(replay.invariants, actualStdout, fieldName);
+		} else if (actualStdout !== recordedStdout) {
+			throw new Error(`qualityGate ${fieldName} CLI replay stdout did not match recordedStdout after normalization`);
+		}
+		return true;
+	} catch (error) {
+		if (error instanceof Error && error.message === "timeout") {
+			throw new Error(`qualityGate ${fieldName} CLI replay timed out after ${replay.timeoutMs}ms`);
+		}
+		throw error;
+	}
+}
+
+async function hasLiveProofPresence(
+	cwd: string,
+	row: JsonObject,
+	fieldName: string,
+	family: SurfaceFamily,
+): Promise<boolean> {
+	if (await hasExistingNonEmptyArtifact(cwd, row.path)) return true;
+	if (family === "cli") {
+		const record = await readCliReplayRecord(cwd, row, fieldName);
+		if (record) return true;
+	}
+	return false;
+}
+
+async function validateLiveSurfaceProofPresence(
+	cwd: string,
+	family: SurfaceFamily,
+	artifactIds: string[],
+	artifactRefs: Map<string, JsonObject>,
+): Promise<void> {
+	if (!isLiveSurfaceFamily(family)) return;
+	for (const artifactId of artifactIds) {
+		if (
+			await hasLiveProofPresence(cwd, artifactRefs.get(artifactId)!, `executorQa.artifactRefs.${artifactId}`, family)
+		)
+			return;
+	}
 	throw new Error(
-		`qualityGate ${fieldName} must reference an existing non-empty artifact path, substantive inlineEvidence, or a typed verifiedReceipt`,
+		`qualityGate ${artifactIds.map(id => `executorQa.artifactRefs.${id}`).join(", ")} must reference a live proof artifact, structural capture, or CLI replay; inlineEvidence and typed verifiedReceipt do not prove live surfaces`,
 	);
 }
+async function validateSurfaceStructuralRequirement(
+	cwd: string,
+	family: SurfaceFamily,
+	artifactIds: string[],
+	artifactRefs: Map<string, JsonObject>,
+	fieldName: string,
+): Promise<void> {
+	if (family !== "web" && family !== "native") return;
+	let hasScreenshot = false;
+	let hasAutomation = false;
+	let hasPty = false;
+	for (const artifactId of artifactIds) {
+		const artifact = artifactRefs.get(artifactId)!;
+		const kind = structuralArtifactKind(artifact);
+		if (!kind) continue;
+		const valid = await validateStructuralArtifact(cwd, artifact, `executorQa.artifactRefs.${artifactId}`, {
+			surfaceFamily: family,
+			live: true,
+		});
+		if (kind === "screenshot" && valid) hasScreenshot = true;
+		if (kind === "automation" && valid) hasAutomation = true;
+		if (kind === "pty" && valid) hasPty = true;
+	}
+	if (family === "web" && (!hasScreenshot || !hasAutomation)) {
+		throw new Error(
+			`qualityGate ${fieldName} for GUI/web surfaces must include a valid automation transcript and non-uniform screenshot`,
+		);
+	}
+	if (family === "native" && !hasScreenshot && !hasAutomation && !hasPty) {
+		throw new Error(
+			`qualityGate ${fieldName} for native surfaces must include a valid screenshot, PTY capture, or app-automation transcript`,
+		);
+	}
+}
+
+async function validateArtifactProof(
+	cwd: string,
+	row: JsonObject,
+	fieldName: string,
+	options: { surfaceFamily: SurfaceFamily; live: boolean },
+): Promise<void> {
+	if (await hasExistingNonEmptyArtifact(cwd, row.path)) return;
+	if (await validateStructuralArtifact(cwd, row, fieldName, options)) return;
+	if (options.surfaceFamily === "cli" && (await validateCliReplay(cwd, row, fieldName, { live: options.live })))
+		return;
+	if (!options.live && (hasTypedVerifiedReceipt(row.verifiedReceipt) || hasTypedVerifiedReceipt(row.receipt))) return;
+	const proofLabel = options.live
+		? "a live proof artifact, structural capture, or CLI replay; inlineEvidence and typed verifiedReceipt do not prove live surfaces"
+		: "an existing non-empty artifact path or a typed verifiedReceipt; inlineEvidence alone is not sufficient";
+	throw new Error(`qualityGate ${fieldName} must reference ${proofLabel}`);
+}
 
 async function validateArtifactRefs(cwd: string, executorQa: JsonObject): Promise<Map<string, JsonObject>> {
+	void cwd;
 	const rows = requireObjectArray(executorQa.artifactRefs, "executorQa.artifactRefs");
 	const idMap = buildRowIdMap(rows, "executorQa.artifactRefs");
 	for (const [index, row] of rows.entries()) {
 		const fieldName = `executorQa.artifactRefs[${index}]`;
 		requiredStringField(row, "kind", fieldName);
 		requiredStringField(row, "description", fieldName);
-		await requireSubstantiveArtifactEvidence(cwd, row, fieldName);
 	}
 	return idMap;
 }
 
-function validateSurfaceEvidence(
+async function validateSurfaceEvidence(
+	cwd: string,
 	executorQa: JsonObject,
 	artifactRefs: Map<string, JsonObject>,
-): Map<string, JsonObject> {
+): Promise<Map<string, JsonObject>> {
 	const rows = requireObjectArray(executorQa.surfaceEvidence, "executorQa.surfaceEvidence");
 	const idMap = buildRowIdMap(rows, "executorQa.surfaceEvidence");
 	for (const [index, row] of rows.entries()) {
@@ -912,6 +1756,7 @@ function validateSurfaceEvidence(
 			continue;
 		}
 		const surface = requiredStringField(row, "surface", fieldName);
+		const family = surfaceFamily(surface);
 		requireSuccessfulRowOutcome(row, fieldName);
 		requiredStringField(row, "invocation", fieldName);
 		if (typeof row.verdict !== "string" || row.verdict.trim().length === 0) {
@@ -919,7 +1764,49 @@ function validateSurfaceEvidence(
 		}
 		const artifactIds = requireStringLinks(row.artifactRefs, `${fieldName}.artifactRefs`);
 		requireResolvedLinks(artifactIds, artifactRefs, `${fieldName}.artifactRefs`);
+		await validateLiveSurfaceProofPresence(cwd, family, artifactIds, artifactRefs);
 		validateSurfaceArtifactCompatibility(surface, artifactIds, artifactRefs, `${fieldName}.artifactRefs`);
+		await validateSurfaceStructuralRequirement(cwd, family, artifactIds, artifactRefs, `${fieldName}.artifactRefs`);
+		if (family === "cli") {
+			let hasPassingReplay = false;
+			for (const artifactId of artifactIds) {
+				const artifact = artifactRefs.get(artifactId)!;
+				const artifactField = `executorQa.artifactRefs.${artifactId}`;
+				const record = await readCliReplayRecord(cwd, artifact, artifactField);
+				if (!record) continue;
+				if (record.replayExempt !== undefined) {
+					if (
+						await validateReplayExemptFallback(cwd, { ...record, id: artifactId }, artifactField, artifactRefs, {
+							surfaceFamily: family,
+							live: true,
+						})
+					) {
+						hasPassingReplay = true;
+					}
+				} else if (await validateCliReplay(cwd, artifact, artifactField, { live: true })) {
+					hasPassingReplay = true;
+				}
+			}
+			if (!hasPassingReplay) {
+				throw new Error(
+					`qualityGate ${fieldName} for CLI surfaces must include a passing argv CLI replay or valid replayExempt fallback`,
+				);
+			}
+		}
+		for (const artifactId of artifactIds) {
+			if (family === "cli") {
+				const record = await readCliReplayRecord(
+					cwd,
+					artifactRefs.get(artifactId)!,
+					`executorQa.artifactRefs.${artifactId}`,
+				);
+				if (record?.replayExempt !== undefined) continue;
+			}
+			await validateArtifactProof(cwd, artifactRefs.get(artifactId)!, `executorQa.artifactRefs.${artifactId}`, {
+				surfaceFamily: family,
+				live: isLiveSurfaceFamily(family),
+			});
+		}
 	}
 	return idMap;
 }
@@ -1007,13 +1894,29 @@ function validateContractCoverage(
 	}
 }
 
-async function validateExecutorQaRedTeamEvidence(cwd: string, executorQa: JsonObject): Promise<void> {
+async function validateExecutorQaRedTeamEvidenceInternal(
+	cwd: string,
+	executorQa: JsonObject,
+	_options: { mode?: "checkpoint" | "review" } = {},
+): Promise<void> {
 	const artifactRefs = await validateArtifactRefs(cwd, executorQa);
-	const surfaceEvidence = validateSurfaceEvidence(executorQa, artifactRefs);
+	const surfaceEvidence = await validateSurfaceEvidence(cwd, executorQa, artifactRefs);
 	const adversarialCases = validateAdversarialCases(executorQa, artifactRefs);
 	validateContractCoverage(executorQa, surfaceEvidence, adversarialCases, artifactRefs);
 }
 
+async function validateExecutorQaRedTeamEvidence(cwd: string, executorQa: JsonObject): Promise<void> {
+	await validateExecutorQaRedTeamEvidenceInternal(cwd, executorQa, { mode: "checkpoint" });
+}
+
+export async function validateExecutorQaRedTeamEvidenceForReview(
+	cwd: string,
+	executorQa: Record<string, unknown>,
+	options: { mode?: "review" } = {},
+): Promise<void> {
+	await validateExecutorQaRedTeamEvidenceInternal(cwd, executorQa as JsonObject, options);
+}
+
 async function validateCompletionQualityGate(cwd: string, gate: JsonObject): Promise<void> {
 	const codeReview = qualityGateObject(gate.codeReview);
 	if (codeReview) {
@@ -1162,6 +2065,26 @@ export async function checkpointUltragoalGoal(input: {
 	if (!goal) throw new Error(`No ultragoal goal found for ${input.goalId}.`);
 	const evidence = input.evidence.trim();
 	if (!evidence) throw new Error("checkpoint evidence is required");
+	const ledgerBefore = await readUltragoalLedger(input.cwd);
+	if (
+		goal.status === input.status &&
+		goal.evidence === evidence &&
+		ledgerBefore.some(
+			event =>
+				event.event === "goal_checkpointed" &&
+				event.goalId === goal.id &&
+				event.status === input.status &&
+				event.evidence === evidence,
+		)
+	) {
+		// Idempotent re-checkpoint: this goal is already recorded in the target status with the same
+		// evidence, so skip the plan rewrite and ledger append to avoid duplicate goal_checkpointed
+		// events. The ledger is the dedup source of truth because it is exactly what a duplicate write
+		// would corrupt (mirrors the ralplan #638 guard). Requiring a matching ledger row means an
+		// interrupted prior write (plan persisted, ledger append lost) still re-appends the event
+		// instead of silently dropping it.
+		return plan;
+	}
 	const qualityGateJson =
 		input.status === "complete"
 			? await readRequiredCompletionQualityGate(input.cwd, input.qualityGateJson)
@@ -1169,7 +2092,6 @@ export async function checkpointUltragoalGoal(input: {
 				? await readStructuredValue(input.cwd, input.qualityGateJson)
 				: undefined;
 	const now = new Date().toISOString();
-	const ledgerBefore = await readUltragoalLedger(input.cwd);
 	const beforeStatus = goal.status;
 	if (input.status === "complete") {
 		const blockedGoalId =
@@ -1689,6 +2611,244 @@ export async function recordUltragoalReviewBlockers(input: {
 	return plan;
 }
 
+type UltragoalReviewMode = "review-only" | "review-start";
+type UltragoalReviewContractStrength = "strong" | "thin-derived";
+
+interface UltragoalReviewFinding extends JsonObject {
+	severity: "blocker";
+	message: string;
+}
+
+interface UltragoalReviewResult extends JsonObject {
+	verdict: "pass" | "fail" | "inconclusive: weak-contract";
+	contractStrength: UltragoalReviewContractStrength;
+	cleanPassEligible: boolean;
+	source: JsonObject;
+	findings: UltragoalReviewFinding[];
+	artifactValidationSummary: JsonObject;
+	weakContractCapApplied: boolean;
+	blockerGoalIds?: string[];
+}
+
+function parseReviewMode(value: string | undefined): UltragoalReviewMode {
+	if (value === undefined || value === "review-only") return "review-only";
+	if (value === "review-start") return "review-start";
+	throw new Error("review --mode must be review-only or review-start");
+}
+
+async function readOptionalExecutorQa(cwd: string, value: string | undefined): Promise<JsonObject> {
+	if (!value) {
+		return {
+			status: "passed",
+			e2eStatus: "passed",
+			redTeamStatus: "passed",
+			evidence: "review evidence bundle was not supplied; runtime reports this as a finding",
+			e2eCommands: ["gjc ultragoal review"],
+			redTeamCommands: ["gjc ultragoal review"],
+			artifactRefs: [],
+			contractCoverage: [],
+			surfaceEvidence: [],
+			adversarialCases: [],
+			blockers: [],
+		};
+	}
+	const structured = await readStructuredValue(cwd, value);
+	if (typeof structured !== "object" || structured === null || Array.isArray(structured)) {
+		throw new Error("review --executor-qa-json must resolve to an executorQa object");
+	}
+	return structured as JsonObject;
+}
+
+async function spawnText(
+	command: string[],
+	options: { cwd: string; timeoutMs?: number },
+): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+	try {
+		const proc = Bun.spawn(command, { cwd: options.cwd, stdout: "pipe", stderr: "pipe" });
+		const timeout = setTimeout(() => proc.kill(), options.timeoutMs ?? 5000);
+		const [stdout, stderr, exitCode] = await Promise.all([
+			new Response(proc.stdout).text(),
+			new Response(proc.stderr).text(),
+			proc.exited,
+		]);
+		clearTimeout(timeout);
+		return { ok: exitCode === 0, stdout, stderr };
+	} catch (error) {
+		return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+async function resolveGitBase(cwd: string, branch?: string): Promise<string> {
+	const candidates = branch ? [branch] : ["origin/main", "origin/master", "main", "master"];
+	for (const candidate of candidates) {
+		const exists = await spawnText(["git", "rev-parse", "--verify", candidate], { cwd, timeoutMs: 3000 });
+		if (exists.ok) return candidate;
+	}
+	const mergeBase = await spawnText(["git", "merge-base", "HEAD", "origin/main"], { cwd, timeoutMs: 3000 });
+	if (mergeBase.ok && mergeBase.stdout.trim()) return mergeBase.stdout.trim();
+	return "HEAD";
+}
+
+async function localDiffSource(cwd: string, sourceKind: string, branch?: string): Promise<JsonObject> {
+	if (sourceKind === "worktree") {
+		const [status, diff] = await Promise.all([
+			spawnText(["git", "status", "--short"], { cwd, timeoutMs: 5000 }),
+			spawnText(["git", "diff", "--stat"], { cwd, timeoutMs: 5000 }),
+		]);
+		return { kind: "worktree", status: status.stdout, diffStat: diff.stdout };
+	}
+	const base = await resolveGitBase(cwd, branch);
+	const diff = await spawnText(["git", "diff", "--stat", `${base}...HEAD`], { cwd, timeoutMs: 5000 });
+	return { kind: sourceKind, base, branch, diffStat: diff.stdout };
+}
+
+async function resolveReviewSource(
+	cwd: string,
+	args: readonly string[],
+	specPath: string | undefined,
+): Promise<{ contractStrength: UltragoalReviewContractStrength; source: JsonObject }> {
+	if (specPath) {
+		const absolute = path.resolve(cwd, specPath);
+		return {
+			contractStrength: "strong",
+			source: { kind: "spec", path: specPath, contract: await Bun.file(absolute).text() },
+		};
+	}
+	const pr = flagValue(args, "--pr");
+	if (pr) {
+		const [view, diff] = await Promise.all([
+			spawnText(["gh", "pr", "view", pr, "--json", "title,body,baseRefName"], { cwd, timeoutMs: 5000 }),
+			spawnText(["gh", "pr", "diff", pr], { cwd, timeoutMs: 5000 }),
+		]);
+		if (view.ok && diff.ok)
+			return {
+				contractStrength: "thin-derived",
+				source: { kind: "pr", pr, prSource: "gh", metadata: view.stdout, diff: diff.stdout },
+			};
+		return {
+			contractStrength: "thin-derived",
+			source: {
+				kind: "pr",
+				pr,
+				prSource: "gh-unavailable",
+				ghError: `${view.stderr}${diff.stderr}`.trim(),
+				local: await localDiffSource(cwd, "pr-fallback"),
+			},
+		};
+	}
+	const branch = flagValue(args, "--branch");
+	if (branch) return { contractStrength: "thin-derived", source: await localDiffSource(cwd, "branch", branch) };
+	return { contractStrength: "thin-derived", source: await localDiffSource(cwd, "worktree") };
+}
+
+function findingFromError(error: unknown): UltragoalReviewFinding {
+	return { severity: "blocker", message: error instanceof Error ? error.message : String(error) };
+}
+
+function executorQaBlockers(executorQa: JsonObject): UltragoalReviewFinding[] {
+	const blockers = nonEmptyStringArray(executorQa.blockers);
+	return (blockers ?? []).map(message => ({ severity: "blocker", message: `executorQa.blockers: ${message}` }));
+}
+
+const RESOLVED_REVIEW_BLOCKER_STATUSES = new Set<UltragoalGoalStatus>(["complete", "superseded"]);
+
+function findOpenReviewBlockerGoal(plan: UltragoalPlan, message: string): UltragoalGoal | undefined {
+	const objective = message.trim();
+	return plan.goals.find(
+		goal =>
+			goal.steering?.kind === "review_blocker" &&
+			goal.objective.trim() === objective &&
+			!RESOLVED_REVIEW_BLOCKER_STATUSES.has(goal.status),
+	);
+}
+
+async function recordReviewFindingGoals(cwd: string, findings: readonly UltragoalReviewFinding[]): Promise<string[]> {
+	let plan = await readUltragoalPlan(cwd);
+	const now = new Date().toISOString();
+	if (!plan) {
+		plan = {
+			version: 1,
+			gjcObjective: DEFAULT_ULTRAGOAL_OBJECTIVE,
+			brief: "Ultragoal review-start findings",
+			gjcGoalMode: "aggregate",
+			createdAt: now,
+			updatedAt: now,
+			goals: [],
+		};
+	}
+	const blockerGoalIds: string[] = [];
+	const createdGoalIds: string[] = [];
+	for (const finding of findings) {
+		const existing = findOpenReviewBlockerGoal(plan, finding.message);
+		if (existing) {
+			if (!blockerGoalIds.includes(existing.id)) blockerGoalIds.push(existing.id);
+			continue;
+		}
+		const id = nextUltragoalGoalId(plan);
+		plan.goals.push({
+			id,
+			title: "Resolve ultragoal review finding",
+			objective: finding.message,
+			status: "pending",
+			createdAt: now,
+			updatedAt: now,
+			steering: { kind: "review_blocker" },
+		});
+		blockerGoalIds.push(id);
+		createdGoalIds.push(id);
+	}
+	if (createdGoalIds.length > 0) {
+		plan.updatedAt = now;
+		await writePlan(cwd, plan);
+		await appendLedger(cwd, {
+			event: "review_blockers_recorded",
+			blockerGoalIds: createdGoalIds,
+			findings: findings.map(finding => finding.message),
+		});
+	}
+	return blockerGoalIds;
+}
+
+export async function runUltragoalReview(cwd: string, args: readonly string[]): Promise<UltragoalReviewResult> {
+	const mode = parseReviewMode(flagValue(args, "--mode"));
+	const specPath = flagValue(args, "--spec");
+	const { contractStrength, source } = await resolveReviewSource(cwd, args, specPath);
+	const executorQa = await readOptionalExecutorQa(
+		cwd,
+		flagValue(args, "--executor-qa-json") ?? flagValue(args, "--executor-qa"),
+	);
+	const findings: UltragoalReviewFinding[] = [];
+	try {
+		await validateExecutorQaRedTeamEvidenceForReview(cwd, executorQa, { mode: "review" });
+	} catch (error) {
+		findings.push(findingFromError(error));
+	}
+	findings.push(...executorQaBlockers(executorQa));
+	const weakContractCapApplied = contractStrength === "thin-derived";
+	const cleanPassEligible = contractStrength === "strong" && findings.length === 0;
+	const result: UltragoalReviewResult = {
+		verdict: cleanPassEligible
+			? "pass"
+			: weakContractCapApplied && findings.length === 0
+				? "inconclusive: weak-contract"
+				: "fail",
+		contractStrength,
+		cleanPassEligible,
+		source,
+		findings,
+		artifactValidationSummary: {
+			validator: "validateExecutorQaRedTeamEvidenceForReview",
+			mode: "review",
+			passed: findings.length === 0,
+			findingCount: findings.length,
+		},
+		weakContractCapApplied,
+	};
+	if (mode === "review-start" && findings.length > 0)
+		result.blockerGoalIds = await recordReviewFindingGoals(cwd, findings);
+	return result;
+}
+
 function flagValue(args: readonly string[], flag: string): string | undefined {
 	const index = args.indexOf(flag);
 	if (index < 0) return undefined;
@@ -1710,6 +2870,12 @@ const FLAGS_WITH_VALUES = new Set([
 	"--evidence",
 	"--gjc-goal-json",
 	"--quality-gate-json",
+	"--executor-qa-json",
+	"--executor-qa",
+	"--pr",
+	"--branch",
+	"--spec",
+	"--mode",
 	"--kind",
 	"--title",
 	"--objective",
@@ -1770,6 +2936,26 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 			"",
 		].join("\n");
 	}
+	if (subject === "review") {
+		return [
+			"Run native GJC Ultragoal workflow commands",
+			"",
+			"USAGE",
+			"  $ gjc ultragoal review [--pr <n> | --branch <ref>] [--spec <path>] [--executor-qa-json <json-or-path>] [FLAGS]",
+			"",
+			"FLAGS",
+			"      --pr=<value>                  Review a GitHub PR; falls back to local diff when gh is unavailable",
+			"      --branch=<value>              Review the current branch against a base ref",
+			"      --spec=<value>                Contract/spec override; enables strong-contract clean PASS eligibility",
+			"      --executor-qa-json=<value>    executorQa JSON string or path using checkpoint qualityGate.executorQa shape",
+			"      --mode=<value>                review-only|review-start (default review-only)",
+			"      --json                        Output the machine-readable verdict report",
+			"",
+			"OUTPUT",
+			"  JSON includes verdict, contractStrength, cleanPassEligible, source, findings, artifactValidationSummary, and weakContractCapApplied.",
+			"",
+		].join("\n");
+	}
 	return [
 		"Run native GJC Ultragoal workflow commands",
 		"",
@@ -1781,10 +2967,11 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 		"  create-goals",
 		"  complete-goals",
 		"  checkpoint",
+		"  review",
 		"  steer",
 		"  record-review-blockers",
 		"",
-		"Run `gjc ultragoal checkpoint --help` for complete checkpoint receipt requirements.",
+		"Run `gjc ultragoal checkpoint --help` or `gjc ultragoal review --help` for command-specific requirements.",
 		"",
 	].join("\n");
 }
@@ -2056,6 +3243,15 @@ async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<Ul
 					stdout: renderCheckpointContinuation(result, status, json, cwd),
 				};
 			}
+			case "review": {
+				const result = await runUltragoalReview(cwd, args);
+				return {
+					status: 0,
+					stdout: json ? `${JSON.stringify(result, null, 2)}\n` : `${result.verdict}\n`,
+					reviewBlockerGoalIds: result.blockerGoalIds,
+					createdReviewPlan: (result.blockerGoalIds?.length ?? 0) > 0,
+				};
+			}
 			case "steer": {
 				const result = await executeUltragoalSteeringCommand(args, cwd);
 				return {
@@ -2096,6 +3292,7 @@ const RECONCILE_COMMANDS = new Set([
 	"checkpoint",
 	"steer",
 	"record-review-blockers",
+	"review",
 ]);
 
 /**
@@ -2127,6 +3324,17 @@ async function reconcileUltragoalState(cwd: string): Promise<void> {
 			goals_path: summary.paths.goalsPath,
 		};
 		if (summary.gjcObjective) payload.gjc_objective = summary.gjcObjective;
+		const ledgerText = await Bun.file(summary.paths.ledgerPath)
+			.text()
+			.catch(() => "");
+		const latestLedger = latestUltragoalLedgerEventFromText(ledgerText);
+		if (latestLedger) {
+			payload.latestLedgerEvent = {
+				event: latestLedger.event,
+				...(latestLedger.goalId ? { goalId: latestLedger.goalId } : {}),
+				...(latestLedger.timestamp ? { timestamp: latestLedger.timestamp } : {}),
+			};
+		}
 		await reconcileWorkflowSkillState({ cwd, mode: "ultragoal", sessionId, active, phase: status, payload });
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);