oh-my-openagent 4.7.2 → 4.7.4

package/packages/omo-codex/plugin/components/rules/test/dynamic-target-fingerprints.test.ts

@@ -0,0 +1,71 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { fingerprintDynamicTargets } from "../src/dynamic-target-fingerprints.js";
+import { defaultConfig } from "../src/rules/engine.js";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+describe("codex rules dynamic target fingerprints", () => {
+	it("#given auto source mode #when an excluded source file changes #then cache key stays stable", () => {
+		// given
+		const { cwd, targetPath } = makeProjectWithDefaultSources();
+		const config = defaultConfig();
+
+		// when
+		const initial = fingerprintDynamicTargets(cwd, [targetPath], config);
+		writeFileSync(
+			path.join(cwd, "AGENTS.md"),
+			[
+				"Always use the exact code style.",
+				"Updated guidance.",
+				"",
+				"This file should be excluded from auto mode.",
+			].join("\n"),
+		);
+		const afterChange = fingerprintDynamicTargets(cwd, [targetPath], config);
+		writeFileSync(
+			path.join(cwd, ".github", "instructions", "workflow.md"),
+			["---", "description: Workflow rules", 'globs: ["**/*.ts"]', "---", "Prefer explicit return types."].join(
+				"\n",
+			),
+		);
+		const afterEnabledChange = fingerprintDynamicTargets(cwd, [targetPath], config);
+		const initialFingerprint = initial[0]?.fingerprint;
+
+		// then
+		expect(afterChange).toHaveLength(1);
+		expect(afterEnabledChange).toHaveLength(1);
+		expect(initialFingerprint).toBeDefined();
+		expect(afterChange[0]?.fingerprint).toBe(initialFingerprint);
+		expect(afterEnabledChange[0]?.fingerprint).not.toBe(initialFingerprint);
+	});
+});
+
+function makeProjectWithDefaultSources(): { cwd: string; targetPath: string } {
+	const root = mkdtempSync(path.join(tmpdir(), "codex-rules-fingerprint-"));
+	const projectRoot = path.join(root, "repo");
+	const instructionPath = path.join(projectRoot, ".github", "instructions");
+	const targetPath = path.join(projectRoot, "src", "app.ts");
+	tempDirectories.push(root);
+
+	mkdirSync(instructionPath, { recursive: true });
+	mkdirSync(path.dirname(targetPath), { recursive: true });
+	writeFileSync(path.join(projectRoot, "package.json"), "{}");
+	writeFileSync(path.join(projectRoot, "AGENTS.md"), "Default project AGENTS file.");
+	writeFileSync(path.join(projectRoot, ".github", "copilot-instructions.md"), "Legacy copilot instruction");
+	writeFileSync(
+		path.join(instructionPath, "workflow.md"),
+		["---", "description: Workflow rules", 'globs: ["**/*.ts"]', "---", "Keep async/await explicit."].join("\n"),
+	);
+	writeFileSync(targetPath, "export const answer = 42;\n");
+	return { cwd: projectRoot, targetPath };
+}

package/packages/omo-codex/plugin/components/rules/test/engine.test.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 
+import { configFromEnvironment } from "../src/config.js";
 import { createEngine, defaultConfig, type EngineDeps } from "../src/rules/engine.js";
 import { matchRule as defaultMatchRule } from "../src/rules/matcher.js";
 import type { RuleCandidate } from "../src/rules/types.js";
@@ -190,3 +191,54 @@ describe("rule engine dynamic matching", () => {
 		expect(matchCalls).toBe(2);
 	});
 });
+
+describe("rule engine default source selection", () => {
+	it("#given auto source selection #when loading static rules #then Codex-native and Claude-home sources are disabled by default", () => {
+		// given
+		let capturedDisabledSources: ReadonlySet<string> | undefined;
+		const deps = {
+			findProjectRoot: () => projectRoot,
+			findCandidates: (options) => {
+				capturedDisabledSources = options.disabledSources;
+				return [];
+			},
+			readFile: () => null,
+		} satisfies EngineDeps;
+		const engine = createEngine(defaultConfig(), deps);
+
+		// when
+		engine.loadStaticRules(projectRoot);
+
+		// then
+		expect(capturedDisabledSources?.has("AGENTS.md")).toBe(true);
+		expect(capturedDisabledSources?.has("~/.claude/rules")).toBe(true);
+		expect(capturedDisabledSources?.has("~/.claude/CLAUDE.md")).toBe(true);
+		expect(capturedDisabledSources?.has("CLAUDE.md")).toBe(false);
+	});
+
+	it("#given removed agent-doc sources and a real source are requested #when loading static rules #then only real sources are enabled", () => {
+		// given
+		let capturedDisabledSources: ReadonlySet<string> | undefined;
+		const deps = {
+			findProjectRoot: () => projectRoot,
+			findCandidates: (options) => {
+				capturedDisabledSources = options.disabledSources;
+				return [];
+			},
+			readFile: () => null,
+		} satisfies EngineDeps;
+		const engine = createEngine(
+			configFromEnvironment({ CODEX_RULES_ENABLED_SOURCES: "AGENTS.md,~/.claude/CLAUDE.md,plugin-bundled" }),
+			deps,
+		);
+
+		// when
+		engine.loadStaticRules(projectRoot);
+
+		// then
+		expect(capturedDisabledSources?.has("AGENTS.md")).toBe(false);
+		expect(capturedDisabledSources?.has("~/.claude/CLAUDE.md")).toBe(false);
+		expect(capturedDisabledSources?.has("plugin-bundled")).toBe(false);
+		expect(capturedDisabledSources?.has(".omo/rules")).toBe(true);
+	});
+});

package/packages/omo-codex/plugin/components/rules/test/finder.test.ts

@@ -24,6 +24,7 @@ function makeProject(): { projectRoot: string; homeRoot: string; targetPath: str
 	mkdirSync(join(homeRoot, ".config", "opencode"), { recursive: true });
 	writeFileSync(join(projectRoot, "package.json"), JSON.stringify({ name: "fixture" }));
 	writeFileSync(join(projectRoot, "AGENTS.md"), "Project rule\n");
+	writeFileSync(join(projectRoot, "CLAUDE.md"), "Claude rule\n");
 	writeFileSync(join(projectRoot, "src", ".omo", "rules", "local.md"), "Local rule\n");
 	writeFileSync(join(projectRoot, ".omo", "rules", "root.md"), "Root rule\n");
 	writeFileSync(join(homeRoot, ".opencode", "rules", "global.md"), "Global rule\n");
@@ -54,9 +55,7 @@ describe("findRuleCandidates", () => {
 		expect(candidates.map(candidateSummary)).toEqual([
 			".omo/rules:0:src/.omo/rules/local.md",
 			".omo/rules:1:.omo/rules/root.md",
-			"AGENTS.md:1:AGENTS.md",
 			"~/.opencode/rules:9999:.opencode/rules/global.md",
-			"~/.config/opencode/AGENTS.md:9999:.config/opencode/AGENTS.md",
 		]);
 	});
 
@@ -73,10 +72,7 @@ describe("findRuleCandidates", () => {
 		});
 
 		// then
-		expect(candidates.map(candidateSummary)).toEqual([
-			"AGENTS.md:1:AGENTS.md",
-			"~/.config/opencode/AGENTS.md:9999:.config/opencode/AGENTS.md",
-		]);
+		expect(candidates.map(candidateSummary)).toEqual([]);
 	});
 
 	it("#given skip user home #when finding candidates #then only project rules are returned", () => {
@@ -96,7 +92,6 @@ describe("findRuleCandidates", () => {
 		expect(candidates.map(candidateSummary)).toEqual([
 			".omo/rules:0:src/.omo/rules/local.md",
 			".omo/rules:1:.omo/rules/root.md",
-			"AGENTS.md:1:AGENTS.md",
 		]);
 	});
 });

package/packages/omo-codex/plugin/components/rules/test/formatter.test.ts

@@ -12,8 +12,8 @@ describe("rules formatter hook context", () => {
 	it("#given multiline dynamic rules #when formatting PostToolUse context #then labels and bodies render on separate lines", () => {
 		// given
 		const rule = loadedRule({
-			path: "/repo/packages/AGENTS.md",
-			relativePath: "packages/AGENTS.md",
+			path: "/repo/packages/CONTEXT.md",
+			relativePath: "packages/CONTEXT.md",
 			body: ["# packages", "", "## OVERVIEW", "23 sibling packages.", "", "## CONVENTIONS", "Use npm."].join("\n"),
 		});
 
@@ -29,7 +29,7 @@ describe("rules formatter hook context", () => {
 			[
 				"Additional project instructions matched for packages/omo-codex/plugin/components/ulw-loop/src/paths.ts:",
 				"",
-				"Instructions from: /repo/packages/AGENTS.md",
+				"Instructions from: /repo/packages/CONTEXT.md",
 				"",
 				"# packages",
 				"",
@@ -45,8 +45,8 @@ describe("rules formatter hook context", () => {
 	it("#given static rules #when formatting SessionStart context #then it avoids leading blank lines", () => {
 		// given
 		const rule = loadedRule({
-			path: "/repo/AGENTS.md",
-			relativePath: "AGENTS.md",
+			path: "/repo/CONTEXT.md",
+			relativePath: "CONTEXT.md",
 			body: "Keep generated hook context readable.",
 		});
 
@@ -58,7 +58,7 @@ describe("rules formatter hook context", () => {
 			[
 				"## Project Instructions",
 				"",
-				"Instructions from: /repo/AGENTS.md",
+				"Instructions from: /repo/CONTEXT.md",
 				"",
 				"Keep generated hook context readable.",
 			].join("\n"),
@@ -82,13 +82,13 @@ describe("rules formatter hook context", () => {
 	it("#given duplicate static rules with different line endings #when formatting context #then it renders one copy", () => {
 		// given
 		const lfRule = loadedRule({
-			path: "/repo/AGENTS.md",
-			relativePath: "AGENTS.md",
+			path: "/repo/CONTEXT.md",
+			relativePath: "CONTEXT.md",
 			body: "Shared rule\nKeep one copy.",
 		});
 		const crlfRule = loadedRule({
-			path: "/repo/packages/AGENTS.md",
-			relativePath: "packages/AGENTS.md",
+			path: "/repo/packages/CONTEXT.md",
+			relativePath: "packages/CONTEXT.md",
 			body: "Shared rule\r\nKeep one copy.",
 		});
 
@@ -97,7 +97,7 @@ describe("rules formatter hook context", () => {
 
 		// then
 		expect(occurrenceCount(block, "Shared rule\nKeep one copy.")).toBe(1);
-		expect(block).not.toContain("/repo/packages/AGENTS.md");
+		expect(block).not.toContain("/repo/packages/CONTEXT.md");
 	});
 
 	it("#given multiple oversized rules #when formatting under a tight result budget #then every rule receives a fair truncated share with a read-full guide", () => {
@@ -145,9 +145,9 @@ function loadedRule(input: {
 	readonly source?: RuleSource;
 	readonly matchReason?: MatchReason;
 }): LoadedRule {
-	const path = input.path ?? "/repo/AGENTS.md";
-	const relativePath = input.relativePath ?? "AGENTS.md";
-	const source = input.source ?? "AGENTS.md";
+	const path = input.path ?? "/repo/CONTEXT.md";
+	const relativePath = input.relativePath ?? "CONTEXT.md";
+	const source = input.source ?? "CONTEXT.md";
 	return {
 		path,
 		realPath: path,

package/packages/omo-codex/plugin/components/rules/test/post-compact-test-fixture.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 import type { CodexPostCompactInput, CodexSessionStartInput, CodexUserPromptSubmitInput } from "../src/codex-hook.js";
 
 export const PROJECT_RULES_ENV = {
-	CODEX_RULES_ENABLED_SOURCES: "AGENTS.md,.omo/rules",
+	CODEX_RULES_ENABLED_SOURCES: "CONTEXT.md,.omo/rules",
 	CODEX_RULES_MAX_RESULT_CHARS: "50000",
 	CODEX_RULES_MAX_RULE_CHARS: "30000",
 };
@@ -30,7 +30,9 @@ export function makeOversizedProject(prefix = "budget"): { root: string; pluginD
 	const pluginData = mkdtempSync(path.join(tmpdir(), `codex-rules-post-compact-${prefix}-data-`));
 	tempDirectories.push(root, pluginData);
 	writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "fixture" }));
-	writeFileSync(path.join(root, "AGENTS.md"), `Project rule\n${"A".repeat(30_000)}`);
+	writeFileSync(path.join(root, "AGENTS.md"), "Project AGENTS.md should stay Codex-native.");
+	writeFileSync(path.join(root, "CLAUDE.md"), "Project CLAUDE.md should stay outside rules hook context.");
+	writeFileSync(path.join(root, "CONTEXT.md"), `Project rule\n${"A".repeat(30_000)}`);
 	mkdirSync(path.join(root, ".omo", "rules"), { recursive: true });
 	writeFileSync(
 		path.join(root, ".omo", "rules", "typescript.md"),

package/packages/omo-codex/plugin/components/rules/test/sources.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+
+import { SOURCE_PRIORITY } from "../src/rules/constants.js";
+import { defaultConfig } from "../src/rules/engine.js";
+import { disabledSourcesFromConfig } from "../src/rules/sources.js";
+import type { PiRulesConfig } from "../src/rules/types.js";
+
+describe("rules source selection", () => {
+	it("#given default config #when disabled sources are derived #then opt-out sources stay disabled", () => {
+		// given
+		const config = defaultConfig();
+		const expected = new Set(["AGENTS.md", "~/.claude/rules", "~/.claude/CLAUDE.md"]);
+
+		// when
+		const disabledSources = disabledSourcesFromConfig(config);
+		expect(disabledSources).toBeDefined();
+		if (disabledSources === undefined) return;
+
+		// then
+		expect(disabledSources).toEqual(expected);
+	});
+
+	it("#given explicit enabled sources #when disabled source set is derived #then all other known sources are omitted", () => {
+		// given
+		const config: PiRulesConfig = {
+			...defaultConfig(),
+			enabledSources: [".omo/rules", "plugin-bundled"],
+		};
+
+		// when
+		const disabledSources = disabledSourcesFromConfig(config);
+		expect(disabledSources).toBeDefined();
+		if (disabledSources === undefined) return;
+
+		// then
+		for (const source of [".omo/rules", "plugin-bundled"]) {
+			expect(disabledSources.has(source)).toBe(false);
+		}
+		expect(disabledSources.has("~/.claude/rules")).toBe(true);
+		expect(disabledSources).toEqual(
+			new Set(
+				[...SOURCE_PRIORITY.keys()].filter((source) => source !== ".omo/rules" && source !== "plugin-bundled"),
+			),
+		);
+	});
+});

package/packages/omo-codex/plugin/components/ultrawork/README.md

@@ -35,6 +35,8 @@ node ${PLUGIN_ROOT}/dist/cli.js hook user-prompt-submit
 
 Codex passes the prompt payload on stdin. When the pattern `\b(?:ultrawork|ulw)\b` (case-insensitive) matches, the hook writes the directive to stdout — Codex injects non-JSON stdout as `additional_context` for the next turn. Otherwise the hook writes nothing and exits 0. Malformed input also exits 0 to never block the turn.
 
+If a prior `UserPromptSubmit` hook output in transcript JSONL already contains `<ultrawork-mode>`, the hook suppresses itself so the same directive is not injected repeatedly. Plain transcript text containing `<ultrawork-mode>` is ignored unless it comes from hook output.
+
 Bundled agent role TOMLs in `agents/` ship to `CODEX_HOME/agents/` at install time, not via a runtime hook. The installer creates a symlink on Linux / macOS and a file copy on Windows (because symlinks require admin privileges or Developer Mode). For the public marketplace, the source is the stable installed-marketplace snapshot, not the versioned plugin cache, so agent role configs remain valid when Codex replaces `~/.codex/plugins/cache/sisyphuslabs/omo/<version>/` during auto-update. Both code paths overwrite stale files and write a `.installed-agents.json` manifest next to the source root for clean uninstall tracking.
 
 ## Smoke test

package/packages/omo-codex/plugin/components/ultrawork/src/codex-hook.ts

@@ -3,6 +3,8 @@ import { readFileSync } from "node:fs";
 import { ULTRAWORK_DIRECTIVE } from "./directive.js";
 
 const ULTRAWORK_PATTERN = /\b(?:ultrawork|ulw)\b/i;
+const ULTRAWORK_DIRECTIVE_MARKER = "<ultrawork-mode>";
+const TRANSCRIPT_SEARCH_BYTES = 512_000;
 const CONTEXT_PRESSURE_MARKERS = [
 	"context compacted",
 	"context_length_exceeded",
@@ -29,10 +31,54 @@ interface UserPromptSubmitHookOutput {
 export function runUserPromptSubmitHook(input: unknown): string {
 	if (!isCodexUserPromptSubmitInput(input)) return "";
 	if (isContextPressureRecoveryPrompt(input.prompt)) return "";
+	if (hasUltraworkDirectiveAlreadyInTranscript(input.transcript_path)) return "";
 	if (isContextPressureTranscript(input.transcript_path)) return "";
 	return isUltraworkPrompt(input.prompt) ? formatAdditionalContextOutput(ULTRAWORK_DIRECTIVE) : "";
 }
 
+function hasUltraworkDirectiveAlreadyInTranscript(transcriptPath: string | null | undefined): boolean {
+	if (transcriptPath === undefined || transcriptPath === null) return false;
+	try {
+		const rawTranscript = readTranscriptTail(transcriptPath);
+		for (const line of rawTranscript.split(/\r?\n/)) {
+			const parsed = parseJsonLine(line);
+			if (parsed === null) {
+				continue;
+			}
+
+			if (!isRecord(parsed)) {
+				continue;
+			}
+
+			const hookSpecificOutput = parsed["hookSpecificOutput"];
+			if (!isRecord(hookSpecificOutput)) {
+				continue;
+			}
+
+			if (hookSpecificOutput["hookEventName"] !== "UserPromptSubmit") {
+				continue;
+			}
+
+			if (
+				typeof hookSpecificOutput["additionalContext"] === "string" &&
+				hookSpecificOutput["additionalContext"].includes(ULTRAWORK_DIRECTIVE_MARKER)
+			) {
+				return true;
+			}
+		}
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+
+	return false;
+}
+
+function readTranscriptTail(transcriptPath: string): string {
+	const rawTranscript = readFileSync(transcriptPath);
+	return rawTranscript.subarray(Math.max(0, rawTranscript.byteLength - TRANSCRIPT_SEARCH_BYTES)).toString("utf8");
+}
+
 export function isUltraworkPrompt(prompt: string): boolean {
 	return ULTRAWORK_PATTERN.test(prompt);
 }
@@ -68,6 +114,22 @@ function normalizeAdditionalContext(additionalContext: string): string {
 	return additionalContext.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
 }
 
+function parseJsonLine(line: string): unknown | null {
+	if (line.trim().length === 0) {
+		return null;
+	}
+
+	try {
+		const parsed: unknown = JSON.parse(line);
+		return parsed;
+	} catch (error) {
+		if (error instanceof Error) {
+			return null;
+		}
+		throw error;
+	}
+}
+
 function isCodexUserPromptSubmitInput(value: unknown): value is CodexUserPromptSubmitInput {
 	return (
 		isRecord(value) &&

package/packages/omo-codex/plugin/components/ultrawork/test/codex-hook.test.ts

@@ -31,6 +31,49 @@ describe("codex ultrawork hook", () => {
 		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/First user-visible line this turn MUST be exactly:/);
 	});
 
+	it("#given transcript already contains ultrawork directive #when hook sees ultrawork prompt #then it does not repeat directive", () => {
+		// given
+		const payload = {
+			hook_event_name: "UserPromptSubmit",
+			prompt: "please ulw this change",
+			transcript_path: writeTranscript(
+				JSON.stringify({
+					hookSpecificOutput: {
+						hookEventName: "UserPromptSubmit",
+						additionalContext: "<ultrawork-mode>\nexisting directive",
+					},
+				}),
+			),
+		};
+
+		// when
+		const output = runUserPromptSubmitHook(payload);
+
+		// then
+		expect(output).toBe("");
+	});
+
+	it("#given transcript only mentions ultrawork marker in user content #when hook sees first ultrawork prompt #then it emits directive", () => {
+		// given
+		const payload = {
+			hook_event_name: "UserPromptSubmit",
+			prompt: "please ulw this change",
+			transcript_path: writeTranscript(
+				JSON.stringify({
+					role: "user",
+					content: "Please inspect text containing <ultrawork-mode> but do not activate yet.",
+				}),
+			),
+		};
+
+		// when
+		const output = runUserPromptSubmitHook(payload);
+		const parsed = parseHookOutput(output);
+
+		// then
+		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/^<ultrawork-mode>/);
+	});
+
 	it("#given identifier-like ulw #when hook runs #then does not emit directive", () => {
 		// given
 		const payload = {
@@ -244,6 +287,14 @@ function writeContextPressureTranscript(): string {
 	return transcriptPath;
 }
 
+function writeTranscript(...lines: string[]): string {
+	const root = mkdtempSync(path.join(tmpdir(), "codex-ultrawork-transcript-"));
+	tempDirectories.push(root);
+	const transcriptPath = path.join(root, "transcript.jsonl");
+	writeFileSync(transcriptPath, `${lines.join("\n")}\n`);
+	return transcriptPath;
+}
+
 function writeCodexContextWindowTranscript(): string {
 	const root = mkdtempSync(path.join(tmpdir(), "codex-ultrawork-context-window-"));
 	tempDirectories.push(root);

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/full-workflow.md

@@ -172,7 +172,7 @@ Trigger only when one goal remains and all its criteria are passing.
 1. Run targeted verification for changed behavior.
 2. Run `ai-slop-cleaner` on changed files. If no relevant edits exist, record a passed no-op cleaner report.
 3. Rerun verification after cleanup.
-4. Run `$code-review`.
+4. Judge the change size. Spawn the `codex-ultrawork-reviewer` agent (`spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)`; fall back to `agent_type="worker"` with a scoped reviewer assignment if unavailable) only when the work is large or risky (multi-file, cross-cutting, new architecture, security/data surfaces, or you are unsure it is sound); for a small, local, low-risk change, do the review yourself and record `codeReview` with `evidence` starting `UNCONDITIONAL APPROVAL` plus a one-line justification of why the change was small enough to self-review.
 5. Clean review means `codeReview.recommendation == "APPROVE"` and `codeReview.architectStatus == "CLEAR"`.
 6. If review is non-clean, run `omo ulw-loop record-review-blockers --goal-id <id> --title "<...>" --objective "<...>" --evidence "<review findings>" --codex-goal-json <snapshot> --json`.
 7. If clean, checkpoint final completion:

package/packages/omo-codex/plugin/components/ulw-loop/src/codex-goal-instruction.ts

@@ -100,18 +100,18 @@ function formatCriterionLine(criterion: UlwLoopSuccessCriterion): string {
 
 function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, aggregate: boolean): string {
 	if (!isFinal)
-		return "- This is not the final ulw-loop story; do not run the final ai-slop-cleaner/$code-review gate yet.";
+		return "- This is not the final ulw-loop story; do not run the final ai-slop-cleaner/code-review gate yet.";
 	const option = sessionOption(plan);
 	const blockerCommand = `omo ulw-loop record-review-blockers${option} --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`;
 	const checkpointCommand = `omo ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`;
 	return joinLines([
 		"Final story — run mandatory quality gate before update_goal:",
-		"- Run ai-slop-cleaner on changed files even when it is a no-op, rerun verification, then run $code-review.",
-		"- If final $code-review is not APPROVE with architect status CLEAR, do not call update_goal. Record blocker work first:",
+		"- Run ai-slop-cleaner on changed files even when it is a no-op, rerun verification, then run the code review (spawn_agent(agent_type=\"codex-ultrawork-reviewer\", fork_turns=\"none\", ...); fall back to agent_type=\"worker\" with a scoped reviewer assignment if unavailable).",
+		"- If the final review is not APPROVE with architect status CLEAR, do not call update_goal. Record blocker work first:",
 		`  ${blockerCommand}`,
 		aggregate
-			? '- If final $code-review is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story:'
-			: '- If final $code-review is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint:',
+			? '- If the final review is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story:'
+			: '- If the final review is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint:',
 		`  ${checkpointCommand}`,
 	]);
 }

package/packages/omo-codex/plugin/components/ulw-loop/src/quality-gate.ts

@@ -12,6 +12,7 @@ const GHCR_PATTERN =
 	/\b(ghcr|github container registry|read packages|imagepullsecret|package api|anonymous|container image)\b/;
 const GHCR_401_PATTERN = /\b(401|unauthorized|anonymous pull|authentication required)\b/;
 const GHCR_403_PATTERN = /\b(403|forbidden|read packages|package api)\b/;
+const UNCONDITIONAL_APPROVAL_PATTERN = /\bUNCONDITIONAL\s+APPROVAL\b/i;
 
 function invalid(message: string, field: string): never {
 	throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });
@@ -42,6 +43,58 @@ function stringArray(value: unknown, field: string): string[] {
 	return value.map((item) => nonEmptyString(item, field));
 }
 
+function normalizeReviewerField({
+	value,
+	field,
+	expectedValue,
+	evidenceApproved,
+}: {
+	value: unknown;
+	field: string;
+	expectedValue: "APPROVE";
+	evidenceApproved: boolean;
+}): "APPROVE";
+function normalizeReviewerField({
+	value,
+	field,
+	expectedValue,
+	evidenceApproved,
+}: {
+	value: unknown;
+	field: string;
+	expectedValue: "CLEAR";
+	evidenceApproved: boolean;
+}): "CLEAR";
+function normalizeReviewerField({
+	value,
+	field,
+	expectedValue,
+	evidenceApproved,
+}: {
+	value: unknown;
+	field: string;
+	expectedValue: "APPROVE" | "CLEAR";
+	evidenceApproved: boolean;
+}): "APPROVE" | "CLEAR" {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed === "") {
+			if (evidenceApproved) return expectedValue;
+			invalid(
+				`${field} must be ${expectedValue} or codeReview.evidence should include UNCONDITIONAL APPROVAL.`,
+				field,
+			);
+		}
+		if (trimmed === expectedValue) return expectedValue;
+		invalid(`${field} must be ${expectedValue}.`, field);
+	}
+	if (value === undefined) {
+		if (evidenceApproved) return expectedValue;
+		invalid(`${field} must be ${expectedValue} or codeReview.evidence should include UNCONDITIONAL APPROVAL.`, field);
+	}
+	invalid(`${field} must be ${expectedValue}.`, field);
+}
+
 export function validateQualityGate(input: unknown): UlwLoopQualityGate {
 	const gate = section(input, "qualityGate");
 	const cleaner = section(gate["aiSlopCleaner"], "aiSlopCleaner");
@@ -50,8 +103,6 @@ export function validateQualityGate(input: unknown): UlwLoopQualityGate {
 	const coverage = section(gate["criteriaCoverage"], "criteriaCoverage");
 	if (cleaner["status"] !== "passed") invalid("aiSlopCleaner.status must be passed.", "aiSlopCleaner.status");
 	if (verification["status"] !== "passed") invalid("verification.status must be passed.", "verification.status");
-	if (review["recommendation"] !== "APPROVE") invalid("recommendation must be APPROVE.", "codeReview.recommendation");
-	if (review["architectStatus"] !== "CLEAR") invalid("architectStatus must be CLEAR.", "codeReview.architectStatus");
 	const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
 	const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
 	if (passCount < totalCriteria)
@@ -61,10 +112,23 @@ export function validateQualityGate(input: unknown): UlwLoopQualityGate {
 	const cleanerEvidence = nonEmptyString(cleaner["evidence"], "aiSlopCleaner.evidence");
 	const verificationEvidence = nonEmptyString(verification["evidence"], "verification.evidence");
 	const reviewEvidence = nonEmptyString(review["evidence"], "codeReview.evidence");
+	const approvalEvidence = UNCONDITIONAL_APPROVAL_PATTERN.test(reviewEvidence);
+	const recommendation = normalizeReviewerField({
+		value: review["recommendation"],
+		field: "codeReview.recommendation",
+		expectedValue: "APPROVE",
+		evidenceApproved: approvalEvidence,
+	});
+	const architectStatus = normalizeReviewerField({
+		value: review["architectStatus"],
+		field: "codeReview.architectStatus",
+		expectedValue: "CLEAR",
+		evidenceApproved: approvalEvidence,
+	});
 	const result: UlwLoopQualityGate = {
 		aiSlopCleaner: { status: "passed", evidence: cleanerEvidence },
 		verification: { status: "passed", commands, evidence: verificationEvidence },
-		codeReview: { recommendation: "APPROVE", architectStatus: "CLEAR", evidence: reviewEvidence },
+		codeReview: { recommendation, architectStatus, evidence: reviewEvidence },
 	};
 	Object.assign(result, { criteriaCoverage: { totalCriteria, passCount, adversarialClassesCovered: covered } });
 	return result;