oh-my-opencode 4.9.2 → 4.11.0

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-commands.test.ts

@@ -1,10 +1,9 @@
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { ulwLoopCommand } from "../src/cli-commands.ts";
-import { ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE } from "../src/goal-status.js";
 
 let testDir: string;
 let out: string[];
@@ -52,17 +51,6 @@ function resetOutput(): void {
 function stdoutJson(): Record<string, unknown> {
 	return JSON.parse(out.join(""));
 }
-function codexSnapshot(status: "active" | "complete" = "active"): string {
-	return JSON.stringify({ goal: { objective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE, status } });
-}
-function qualityGate(): string {
-	return JSON.stringify({
-		aiSlopCleaner: { status: "passed", evidence: "no-op" },
-		verification: { status: "passed", commands: ["vitest"], evidence: "green" },
-		codeReview: { recommendation: "APPROVE", architectStatus: "CLEAR", evidence: "small test fixture" },
-		criteriaCoverage: { totalCriteria: 3, passCount: 3, adversarialClassesCovered: ["stale_state"] },
-	});
-}
 
 async function createPlan(brief = "- Goal A\n- Goal B"): Promise<Record<string, unknown>> {
 	resetOutput();
@@ -72,23 +60,6 @@ async function createPlan(brief = "- Goal A\n- Goal B"): Promise<Record<string,
 	return parsed;
 }
 
-async function passCriterion(goalId: string, criterionId: string): Promise<void> {
-	expect(
-		await ulwLoopCommand([
-			"record-evidence",
-			"--goal-id",
-			goalId,
-			"--criterion-id",
-			criterionId,
-			"--status",
-			"pass",
-			"--evidence",
-			`${criterionId} observable proof`,
-		]),
-	).toBe(0);
-	resetOutput();
-}
-
 describe("ulwLoopCommand help", () => {
 	it("prints usage when no subcommand", async () => {
 		expect(await ulwLoopCommand([])).toBe(0);
@@ -96,89 +67,6 @@ describe("ulwLoopCommand help", () => {
 	});
 });
 
-describe("ulwLoopCommand create-goals", () => {
-	it("creates plan + writes 3 artifacts + seeds criteria per goal", async () => {
-		const code = await ulwLoopCommand(["create-goals", "--brief", "- Goal A\n- Goal B", "--json"]);
-
-		expect(code).toBe(0);
-		const parsed = stdoutJson();
-		expect(parsed).toMatchObject({ ok: true });
-		expect(parsed).toHaveProperty("plan.goals.0.successCriteria.0.id", "C001");
-		expect(await readFile(join(testDir, ".omo/ulw-loop/brief.md"), "utf8")).toContain("Goal A");
-		expect(await readFile(join(testDir, ".omo/ulw-loop/goals.json"), "utf8")).toContain("successCriteria");
-		expect(await readFile(join(testDir, ".omo/ulw-loop/ledger.jsonl"), "utf8")).toContain("plan_created");
-	});
-
-	it("#given completed default aggregate #when creating another default plan #then guides to a fresh session", async () => {
-		await createPlan("- Finished");
-		for (const criterionId of ["C001", "C002", "C003"]) await passCriterion("G001-finished", criterionId);
-		expect(
-			await ulwLoopCommand([
-				"checkpoint",
-				"--goal-id",
-				"G001-finished",
-				"--status",
-				"complete",
-				"--evidence",
-				"done",
-				"--codex-goal-json",
-				codexSnapshot("complete"),
-				"--quality-gate-json",
-				qualityGate(),
-			]),
-		).toBe(0);
-		resetOutput();
-
-		expect(await ulwLoopCommand(["create-goals", "--brief", "- New task"])).toBe(1);
-
-		expect(err.join("")).toContain("Existing ulw-loop aggregate is already complete");
-		expect(err.join("")).toContain("create-goals --session-id <new-id>");
-		expect(err.join("")).toContain("--force only");
-	});
-
-	it("#given two session ids #when creating goals #then writes isolated session-scoped plans", async () => {
-		expect(await ulwLoopCommand(["create-goals", "--session-id", "session-A", "--brief", "- Alpha", "--json"])).toBe(
-			0,
-		);
-		resetOutput();
-
-		expect(await ulwLoopCommand(["create-goals", "--session-id", "session-B", "--brief", "- Beta", "--json"])).toBe(
-			0,
-		);
-		resetOutput();
-
-		expect(await readFile(join(testDir, ".omo/ulw-loop/session-A/goals.json"), "utf8")).toContain("Alpha");
-		expect(await readFile(join(testDir, ".omo/ulw-loop/session-B/goals.json"), "utf8")).toContain("Beta");
-
-		expect(await ulwLoopCommand(["status", "--session-id", "session-A", "--json"])).toBe(0);
-		expect(stdoutJson()).toMatchObject({
-			plan: { goalsPath: ".omo/ulw-loop/session-A/goals.json", goals: [{ title: "Alpha" }] },
-		});
-		expect(out.join("")).not.toContain("Beta");
-	});
-
-	it("#given Codex thread env #when creating goals #then uses the thread as the session scope", async () => {
-		process.env["CODEX_THREAD_ID"] = "thread-123";
-
-		expect(await ulwLoopCommand(["create-goals", "--brief", "- Thread scoped", "--json"])).toBe(0);
-		resetOutput();
-
-		expect(await readFile(join(testDir, ".omo/ulw-loop/thread-123/goals.json"), "utf8")).toContain("Thread scoped");
-		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
-		expect(stdoutJson()).toHaveProperty("plan.goalsPath", ".omo/ulw-loop/thread-123/goals.json");
-	});
-
-	it("#given Codex thread env and explicit session id #when creating goals #then the explicit session wins", async () => {
-		process.env["CODEX_THREAD_ID"] = "thread-123";
-
-		expect(
-			await ulwLoopCommand(["create-goals", "--session-id", "manual-456", "--brief", "- Manual scoped", "--json"]),
-		).toBe(0);
-
-		expect(await readFile(join(testDir, ".omo/ulw-loop/manual-456/goals.json"), "utf8")).toContain("Manual scoped");
-	});
-});
-
 describe("ulwLoopCommand status", () => {
 	it("prints plan summary including criteria counts", async () => {
 		await createPlan();
@@ -257,88 +145,6 @@ describe("ulwLoopCommand criteria", () => {
 	});
 });
 
-describe("ulwLoopCommand checkpoint", () => {
-	it("REJECTS status=complete when criteria pending", async () => {
-		await createPlan();
-
-		expect(
-			await ulwLoopCommand([
-				"checkpoint",
-				"--goal-id",
-				"G001-goal-a",
-				"--status",
-				"complete",
-				"--evidence",
-				"x",
-				"--codex-goal-json",
-				codexSnapshot(),
-			]),
-		).toBe(1);
-		expect(err.join("").toLowerCase()).toContain("criteria");
-	});
-
-	it("ACCEPTS when all criteria pass", async () => {
-		await createPlan();
-		await passCriterion("G001-goal-a", "C001");
-		await passCriterion("G001-goal-a", "C002");
-		await passCriterion("G001-goal-a", "C003");
-
-		expect(
-			await ulwLoopCommand([
-				"checkpoint",
-				"--goal-id",
-				"G001-goal-a",
-				"--status",
-				"complete",
-				"--evidence",
-				"implementation done and validation passed",
-				"--codex-goal-json",
-				codexSnapshot(),
-				"--json",
-			]),
-		).toBe(0);
-		expect(stdoutJson()).toHaveProperty("goal.status", "complete");
-	});
-
-	it("#given failed checkpoint without codex goal json #when recorded through CLI #then marks the goal failed", async () => {
-		await createPlan();
-
-		expect(
-			await ulwLoopCommand([
-				"checkpoint",
-				"--goal-id",
-				"G001-goal-a",
-				"--status",
-				"failed",
-				"--evidence",
-				"implementation failed and validation captured",
-				"--json",
-			]),
-		).toBe(0);
-
-		expect(stdoutJson()).toMatchObject({ ok: true, goal: { id: "G001-goal-a", status: "failed" } });
-	});
-
-	it("#given blocked checkpoint without codex goal json #when recorded through CLI #then marks the goal blocked", async () => {
-		await createPlan();
-
-		expect(
-			await ulwLoopCommand([
-				"checkpoint",
-				"--goal-id",
-				"G002-goal-b",
-				"--status",
-				"blocked",
-				"--evidence",
-				"waiting for external approval",
-				"--json",
-			]),
-		).toBe(0);
-
-		expect(stdoutJson()).toMatchObject({ ok: true, goal: { id: "G002-goal-b", status: "blocked" } });
-	});
-});
-
 describe("ulwLoopCommand steer", () => {
 	it("dispatches to the steering engine", async () => {
 		await createPlan();
@@ -394,4 +200,10 @@ describe("ulwLoopCommand error handling", () => {
 		expect(await ulwLoopCommand(["status"])).toBe(1);
 		expect(err.join("")).toContain("[ulw-loop]");
 	});
+
+	it("#given no --json #when an error occurs #then writes only to stderr and leaves stdout empty", async () => {
+		expect(await ulwLoopCommand(["status"])).toBe(1);
+		expect(out.join("")).toBe("");
+		expect(err.join("")).toContain("[ulw-loop]");
+	});
 });

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-complete-goals.test.ts

@@ -1,16 +1,26 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { ulwLoopCommand } from "../src/cli-commands.ts";
+import { ulwLoopLedgerPath } from "../src/paths.ts";
 
 let testDir: string;
 let out: string[];
+let originalCodexSessionId: string | undefined;
+let originalCodexThreadId: string | undefined;
+let originalOmoSessionId: string | undefined;
 
 beforeEach(async () => {
 	testDir = await mkdtemp(join(tmpdir(), "ug-cli-complete-"));
 	out = [];
+	originalCodexSessionId = process.env["CODEX_SESSION_ID"];
+	originalCodexThreadId = process.env["CODEX_THREAD_ID"];
+	originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
+	delete process.env["CODEX_SESSION_ID"];
+	delete process.env["CODEX_THREAD_ID"];
+	delete process.env["OMO_ULW_LOOP_SESSION_ID"];
 	vi.spyOn(process, "cwd").mockReturnValue(testDir);
 	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
 		out.push(chunk.toString());
@@ -20,6 +30,12 @@ beforeEach(async () => {
 
 afterEach(async () => {
 	vi.restoreAllMocks();
+	if (originalCodexSessionId === undefined) delete process.env["CODEX_SESSION_ID"];
+	else process.env["CODEX_SESSION_ID"] = originalCodexSessionId;
+	if (originalCodexThreadId === undefined) delete process.env["CODEX_THREAD_ID"];
+	else process.env["CODEX_THREAD_ID"] = originalCodexThreadId;
+	if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
 	await rm(testDir, { recursive: true, force: true });
 });
 
@@ -31,6 +47,14 @@ function stdoutJson(): Record<string, unknown> {
 	return JSON.parse(out.join(""));
 }
 
+async function ledgerKinds(): Promise<string[]> {
+	const raw = await readFile(ulwLoopLedgerPath(testDir), "utf8");
+	return raw
+		.split(/\r?\n/)
+		.filter(Boolean)
+		.map((line) => (JSON.parse(line) as { kind: string }).kind);
+}
+
 async function createPlan(): Promise<void> {
 	expect(await ulwLoopCommand(["create-goals", "--brief", "- Goal A\n- Goal B", "--json"])).toBe(0);
 	resetOutput();
@@ -49,4 +73,20 @@ describe("ulwLoopCommand complete-goals", () => {
 		});
 		expect(JSON.stringify(stdoutJson())).not.toContain('"status":"active"');
 	});
+
+	it("#given an in-progress goal #when complete-goals is called again #then it resumes without appending to the ledger", async () => {
+		// given
+		await createPlan();
+		expect(await ulwLoopCommand(["complete-goals", "--json"])).toBe(0);
+		expect(stdoutJson()).toMatchObject({ ok: true, resumed: false, goal: { status: "in_progress" } });
+		expect(await ledgerKinds()).toEqual(["plan_created", "goal_started"]);
+		resetOutput();
+
+		// when
+		expect(await ulwLoopCommand(["complete-goals", "--json"])).toBe(0);
+
+		// then
+		expect(stdoutJson()).toMatchObject({ ok: true, resumed: true, goal: { status: "in_progress" } });
+		expect(await ledgerKinds()).toEqual(["plan_created", "goal_started"]);
+	});
 });

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-create-goals.test.ts

@@ -0,0 +1,172 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ulwLoopCommand } from "../src/cli-commands.ts";
+import { ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE } from "../src/goal-status.js";
+import { qualityGateJson } from "./fixtures/quality-gate-builder.js";
+
+let testDir: string;
+let out: string[];
+let err: string[];
+let originalCodexSessionId: string | undefined;
+let originalCodexThreadId: string | undefined;
+let originalOmoSessionId: string | undefined;
+
+beforeEach(async () => {
+	testDir = await mkdtemp(join(tmpdir(), "ug-cli-create-goals-"));
+	out = [];
+	err = [];
+	originalCodexSessionId = process.env["CODEX_SESSION_ID"];
+	originalCodexThreadId = process.env["CODEX_THREAD_ID"];
+	originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
+	delete process.env["CODEX_SESSION_ID"];
+	delete process.env["CODEX_THREAD_ID"];
+	delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	vi.spyOn(process, "cwd").mockReturnValue(testDir);
+	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		out.push(chunk.toString());
+		return true;
+	});
+	vi.spyOn(process.stderr, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		err.push(chunk.toString());
+		return true;
+	});
+});
+
+afterEach(async () => {
+	vi.restoreAllMocks();
+	if (originalCodexSessionId === undefined) delete process.env["CODEX_SESSION_ID"];
+	else process.env["CODEX_SESSION_ID"] = originalCodexSessionId;
+	if (originalCodexThreadId === undefined) delete process.env["CODEX_THREAD_ID"];
+	else process.env["CODEX_THREAD_ID"] = originalCodexThreadId;
+	if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
+	await rm(testDir, { recursive: true, force: true });
+});
+
+function resetOutput(): void {
+	out = [];
+	err = [];
+}
+
+function stdoutJson(): Record<string, unknown> {
+	return JSON.parse(out.join(""));
+}
+
+function codexSnapshot(status: "active" | "complete" = "active"): string {
+	return JSON.stringify({ goal: { objective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE, status } });
+}
+
+async function qualityGate(): Promise<string> {
+	return qualityGateJson(testDir);
+}
+
+async function createPlan(brief = "- Goal A\n- Goal B"): Promise<Record<string, unknown>> {
+	resetOutput();
+	expect(await ulwLoopCommand(["create-goals", "--brief", brief, "--json"])).toBe(0);
+	const parsed = stdoutJson();
+	resetOutput();
+	return parsed;
+}
+
+async function passCriterion(goalId: string, criterionId: string): Promise<void> {
+	expect(
+		await ulwLoopCommand([
+			"record-evidence",
+			"--goal-id",
+			goalId,
+			"--criterion-id",
+			criterionId,
+			"--status",
+			"pass",
+			"--evidence",
+			`${criterionId} observable proof`,
+		]),
+	).toBe(0);
+	resetOutput();
+}
+
+describe("ulwLoopCommand create-goals", () => {
+	it("creates plan + writes 3 artifacts + seeds criteria per goal", async () => {
+		const code = await ulwLoopCommand(["create-goals", "--brief", "- Goal A\n- Goal B", "--json"]);
+
+		expect(code).toBe(0);
+		const parsed = stdoutJson();
+		expect(parsed).toMatchObject({ ok: true });
+		expect(parsed).toHaveProperty("plan.goals.0.successCriteria.0.id", "C001");
+		expect(await readFile(join(testDir, ".omo/ulw-loop/brief.md"), "utf8")).toContain("Goal A");
+		expect(await readFile(join(testDir, ".omo/ulw-loop/goals.json"), "utf8")).toContain("successCriteria");
+		expect(await readFile(join(testDir, ".omo/ulw-loop/ledger.jsonl"), "utf8")).toContain("plan_created");
+	});
+
+	it("#given completed default aggregate #when creating another default plan #then guides to a fresh session", async () => {
+		await createPlan("- Finished");
+		for (const criterionId of ["C001", "C002", "C003"]) await passCriterion("G001-finished", criterionId);
+		expect(
+			await ulwLoopCommand([
+				"checkpoint",
+				"--goal-id",
+				"G001-finished",
+				"--status",
+				"complete",
+				"--evidence",
+				"done",
+				"--codex-goal-json",
+				codexSnapshot("complete"),
+				"--quality-gate-json",
+				await qualityGate(),
+			]),
+		).toBe(0);
+		resetOutput();
+
+		expect(await ulwLoopCommand(["create-goals", "--brief", "- New task"])).toBe(1);
+
+		expect(err.join("")).toContain("Existing ulw-loop aggregate is already complete");
+		expect(err.join("")).toContain("create-goals --session-id <new-id>");
+		expect(err.join("")).toContain("--force only");
+	});
+
+	it("#given two session ids #when creating goals #then writes isolated session-scoped plans", async () => {
+		expect(await ulwLoopCommand(["create-goals", "--session-id", "session-A", "--brief", "- Alpha", "--json"])).toBe(
+			0,
+		);
+		resetOutput();
+
+		expect(await ulwLoopCommand(["create-goals", "--session-id", "session-B", "--brief", "- Beta", "--json"])).toBe(
+			0,
+		);
+		resetOutput();
+
+		expect(await readFile(join(testDir, ".omo/ulw-loop/session-A/goals.json"), "utf8")).toContain("Alpha");
+		expect(await readFile(join(testDir, ".omo/ulw-loop/session-B/goals.json"), "utf8")).toContain("Beta");
+
+		expect(await ulwLoopCommand(["status", "--session-id", "session-A", "--json"])).toBe(0);
+		expect(stdoutJson()).toMatchObject({
+			plan: { goalsPath: ".omo/ulw-loop/session-A/goals.json", goals: [{ title: "Alpha" }] },
+		});
+		expect(out.join("")).not.toContain("Beta");
+	});
+
+	it("#given Codex thread env #when creating goals #then uses the thread as the session scope", async () => {
+		process.env["CODEX_THREAD_ID"] = "thread-123";
+
+		expect(await ulwLoopCommand(["create-goals", "--brief", "- Thread scoped", "--json"])).toBe(0);
+		resetOutput();
+
+		expect(await readFile(join(testDir, ".omo/ulw-loop/thread-123/goals.json"), "utf8")).toContain("Thread scoped");
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		expect(stdoutJson()).toHaveProperty("plan.goalsPath", ".omo/ulw-loop/thread-123/goals.json");
+	});
+
+	it("#given Codex thread env and explicit session id #when creating goals #then the explicit session wins", async () => {
+		process.env["CODEX_THREAD_ID"] = "thread-123";
+
+		expect(
+			await ulwLoopCommand(["create-goals", "--session-id", "manual-456", "--brief", "- Manual scoped", "--json"]),
+		).toBe(0);
+
+		expect(await readFile(join(testDir, ".omo/ulw-loop/manual-456/goals.json"), "utf8")).toContain("Manual scoped");
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-helpers.test.ts

@@ -210,12 +210,6 @@ describe("ULW_LOOP_HELP", () => {
 		expect(ULW_LOOP_HELP).toContain("add-goal");
 		expect(ULW_LOOP_HELP).toContain("record-review-blockers");
 	});
-
-	it("never mentions the legacy typo", () => {
-		const typo = ["o", "m", "x"].join("");
-
-		expect(ULW_LOOP_HELP).not.toMatch(new RegExp(typo, "i"));
-	});
 });
 
 describe("printStatus", () => {

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-json-errors.test.ts

@@ -0,0 +1,89 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ulwLoopCommand } from "../src/cli-commands.ts";
+
+let testDir: string;
+let out: string[];
+let err: string[];
+let originalCodexSessionId: string | undefined;
+let originalCodexThreadId: string | undefined;
+let originalOmoSessionId: string | undefined;
+
+beforeEach(async () => {
+	testDir = await mkdtemp(join(tmpdir(), "ug-cli-json-err-"));
+	out = [];
+	err = [];
+	originalCodexSessionId = process.env["CODEX_SESSION_ID"];
+	originalCodexThreadId = process.env["CODEX_THREAD_ID"];
+	originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
+	delete process.env["CODEX_SESSION_ID"];
+	delete process.env["CODEX_THREAD_ID"];
+	delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	vi.spyOn(process, "cwd").mockReturnValue(testDir);
+	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		out.push(chunk.toString());
+		return true;
+	});
+	vi.spyOn(process.stderr, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		err.push(chunk.toString());
+		return true;
+	});
+});
+
+afterEach(async () => {
+	vi.restoreAllMocks();
+	if (originalCodexSessionId === undefined) delete process.env["CODEX_SESSION_ID"];
+	else process.env["CODEX_SESSION_ID"] = originalCodexSessionId;
+	if (originalCodexThreadId === undefined) delete process.env["CODEX_THREAD_ID"];
+	else process.env["CODEX_THREAD_ID"] = originalCodexThreadId;
+	if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
+	await rm(testDir, { recursive: true, force: true });
+});
+
+function stdoutJson(): Record<string, unknown> {
+	return JSON.parse(out.join(""));
+}
+
+describe("ulwLoopCommand --json error contract", () => {
+	it("#given no plan #when status --json #then emits JSON error on stdout, nothing on stderr, exit 1", async () => {
+		const code = await ulwLoopCommand(["status", "--json"]);
+
+		expect(code).toBe(1);
+		expect(err.join("")).toBe("");
+		expect(stdoutJson()).toMatchObject({
+			ok: false,
+			error: { code: "ULW_LOOP_PLAN_MISSING", message: expect.stringContaining("No ulw-loop plan") },
+		});
+	});
+
+	it("#given no plan #when complete-goals --json #then emits JSON error on stdout, exit 1", async () => {
+		const code = await ulwLoopCommand(["complete-goals", "--json"]);
+
+		expect(code).toBe(1);
+		expect(err.join("")).toBe("");
+		expect(stdoutJson()).toMatchObject({ ok: false, error: { code: "ULW_LOOP_PLAN_MISSING" } });
+	});
+
+	it("#given an unknown subcommand #when --json #then emits a JSON error (not help text), exit 1", async () => {
+		const code = await ulwLoopCommand(["wat", "--json"]);
+
+		expect(code).toBe(1);
+		expect(out.join("")).not.toContain("Usage:");
+		expect(stdoutJson()).toMatchObject({ ok: false, error: { code: expect.any(String) } });
+	});
+
+	it("#given a malformed required flag #when --json #then surfaces the UlwLoopError code with details on stdout", async () => {
+		const code = await ulwLoopCommand(["criteria", "--json"]);
+
+		expect(code).toBe(1);
+		expect(err.join("")).toBe("");
+		expect(stdoutJson()).toMatchObject({
+			ok: false,
+			error: { code: "ULW_LOOP_ARGUMENT_MISSING", details: { flag: "--goal-id" } },
+		});
+	});
+});

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

@@ -5,6 +5,8 @@ import { ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE } from "../src/goal-status.js";
 import type { UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "../src/types.js";
 
 const NOW = "2026-05-23T00:00:00.000Z";
+const FINAL_REVIEW_ROLES = ["lazycodex-code-reviewer", "lazycodex-qa-executor", "lazycodex-gate-reviewer"] as const;
+const QUALITY_GATE_SECTIONS = ["codeReview", "manualQa", "gateReview", "iteration", "criteriaCoverage"] as const;
 
 function makeCriterion(overrides: Partial<UlwLoopSuccessCriterion> = {}): UlwLoopSuccessCriterion {
 	return {
@@ -45,6 +47,10 @@ function makePlan(overrides: Partial<UlwLoopPlan> = {}): UlwLoopPlan {
 	};
 }
 
+function expectTextToContainAll(text: string, terms: readonly string[]): void {
+	for (const term of terms) expect(text).toContain(term);
+}
+
 describe("buildCodexGoalInstruction aggregate mode", () => {
 	it("references the aggregate handoff and the .omo/ulw-loop/goals.json artifact", () => {
 		const { text } = buildCodexGoalInstruction({ plan: makePlan({ codexGoalMode: "aggregate" }), goal: makeGoal() });
@@ -72,7 +78,21 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 			goal: makeGoal(),
 			isFinal: false,
 		});
-		expect(text).toMatch(/do not.*update_goal/i);
+		expect(text).toContain("do not call update_goal mid-aggregate");
+		expect(text).toContain("checkpoint this OMO ledger story");
+		expect(text).toContain("update_goal is reserved for the final story after the mandatory quality gate passes");
+	});
+
+	it("#given a non-final aggregate story #when rendering instructions #then defers the current final quality gate", () => {
+		const { text } = buildCodexGoalInstruction({
+			plan: makePlan({ codexGoalMode: "aggregate" }),
+			goal: makeGoal(),
+			isFinal: false,
+		});
+
+		expect(text).toMatch(/not the final .*do not run .*quality gate/i);
+		expect(text).toContain("checkpoint this OMO ledger story");
+		expect(text).toContain("continue the remaining stories");
 	});
 
 	it("includes quality gate instruction when isFinal", () => {
@@ -84,6 +104,23 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 		expect(text).toMatch(/quality gate/i);
 	});
 
+	it("#given a final aggregate story #when rendering instructions #then requires the current LazyCodex quality gate", () => {
+		const { text } = buildCodexGoalInstruction({
+			plan: makePlan({ codexGoalMode: "aggregate" }),
+			goal: makeGoal(),
+			isFinal: true,
+		});
+
+		expectTextToContainAll(text, FINAL_REVIEW_ROLES);
+		expectTextToContainAll(text, QUALITY_GATE_SECTIONS);
+		expect(text).toMatch(/targeted verification/i);
+		expect(text).toMatch(/artifact path.*non-zero size/i);
+		expectTextToContainAll(text, ["original brief", "desired user-visible outcome", "userOutcomeReview"]);
+		expect(text).toMatch(/not clean.*do not call update_goal/i);
+		expect(text).toContain("record-review-blockers");
+		expect(text).toContain("checkpoint");
+	});
+
 	it("#given a scoped plan #when rendering final commands #then includes the session id option", () => {
 		const { text } = buildCodexGoalInstruction({
 			plan: makePlan({
@@ -155,13 +192,7 @@ describe("buildCodexGoalInstruction criteria section", () => {
 	});
 });
 
-describe("buildCodexGoalInstruction rebrand audit", () => {
-	it("emits no legacy brand references in any rendered string", () => {
-		const legacyBrand = ["o", "m", "x"].join("");
-		const { text } = buildCodexGoalInstruction({ plan: makePlan(), goal: makeGoal() });
-		expect(text).not.toMatch(new RegExp(legacyBrand, "i"));
-	});
-
+describe("buildCodexGoalInstruction artifact guidance", () => {
 	it("references .omo/ulw-loop in artifact paths", () => {
 		const { text } = buildCodexGoalInstruction({ plan: makePlan({ codexGoalMode: "aggregate" }), goal: makeGoal() });
 		expect(text).toContain(".omo/ulw-loop");