oh-my-opencode 4.5.1 → 4.5.12

package/packages/omo-codex/plugin/components/ulw-loop/test/plan-crud.test.ts

@@ -0,0 +1,256 @@
+import { mkdir, mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { ulwLoopBriefPath, ulwLoopGoalsPath, ulwLoopLedgerPath } from "../src/paths.js";
+import {
+	addUlwLoopGoal,
+	createUlwLoopPlan,
+	deriveGoalCandidates,
+	seedDefaultSuccessCriteria,
+	startNextUlwLoop,
+	summarizeUlwLoopPlan,
+} from "../src/plan-crud.js";
+import { writePlan } from "../src/plan-io.js";
+import type { UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "../src/types.js";
+import { UlwLoopError } from "../src/types.js";
+
+const NOW = "2026-05-23T00:00:00.000Z";
+
+async function makeRepo(): Promise<string> {
+	return mkdtemp(join(tmpdir(), "ug-crud-"));
+}
+
+async function readBriefFixture(): Promise<string> {
+	return readFile(join(process.cwd(), "test", "fixtures", "sample-brief.md"), "utf8");
+}
+
+async function ledgerKinds(repoRoot: string): Promise<string[]> {
+	const raw = await readFile(ulwLoopLedgerPath(repoRoot), "utf8");
+	return raw
+		.split(/\r?\n/)
+		.filter(Boolean)
+		.map((line) => JSON.parse(line).kind);
+}
+
+function criterion(status: UlwLoopSuccessCriterion["status"]): UlwLoopSuccessCriterion {
+	const [base] = seedDefaultSuccessCriteria(0, "Implement auth endpoint");
+	if (base === undefined) throw new Error("expected seeded criterion");
+	return { ...base, status };
+}
+
+function makeGoal(overrides: Partial<UlwLoopItem> = {}): UlwLoopItem {
+	return {
+		id: "G001",
+		title: "Build auth service",
+		objective: "Implement JWT auth endpoint",
+		status: "pending",
+		successCriteria: seedDefaultSuccessCriteria(0, "Implement JWT auth endpoint"),
+		attempt: 0,
+		createdAt: NOW,
+		updatedAt: NOW,
+		...overrides,
+	};
+}
+
+function makePlan(goals: UlwLoopItem[]): UlwLoopPlan {
+	return {
+		version: 1,
+		createdAt: NOW,
+		updatedAt: NOW,
+		briefPath: ".omo/ulw-loop/brief.md",
+		goalsPath: ".omo/ulw-loop/goals.json",
+		ledgerPath: ".omo/ulw-loop/ledger.jsonl",
+		codexGoalMode: "aggregate",
+		goals,
+	};
+}
+
+function scheduled(result: Awaited<ReturnType<typeof startNextUlwLoop>>) {
+	if ("done" in result) throw new Error("expected scheduled goal");
+	return result;
+}
+
+describe("seedDefaultSuccessCriteria", () => {
+	it("produces 3 criteria with C001/C002/C003 ids", () => {
+		const cs = seedDefaultSuccessCriteria(0, "Implement auth endpoint");
+		expect(cs).toHaveLength(3);
+		expect(cs.map((c) => c.id)).toEqual(["C001", "C002", "C003"]);
+	});
+
+	it("covers happy + edge + regression user models", () => {
+		const cs = seedDefaultSuccessCriteria(0, "Implement auth endpoint");
+		expect(cs.map((c) => c.userModel).sort()).toEqual(["edge", "happy", "regression"]);
+	});
+
+	it("seeds all criteria as pending with null capturedEvidence", () => {
+		const cs = seedDefaultSuccessCriteria(0, "Implement auth endpoint");
+		for (const c of cs) {
+			expect(c.status).toBe("pending");
+			expect(c.capturedEvidence).toBeNull();
+		}
+	});
+});
+
+describe("createUlwLoopPlan", () => {
+	it("creates .omo/ulw-loop/{brief.md, goals.json, ledger.jsonl} in repoRoot", async () => {
+		const repoRoot = await makeRepo();
+		const brief = await readBriefFixture();
+
+		await createUlwLoopPlan(repoRoot, { brief });
+
+		expect(await readFile(ulwLoopBriefPath(repoRoot), "utf8")).toBe(brief.endsWith("\n") ? brief : `${brief}\n`);
+		expect(await readFile(ulwLoopGoalsPath(repoRoot), "utf8")).toContain("G001-build-the-jwt-auth-endpoint");
+		expect(await ledgerKinds(repoRoot)).toEqual(["plan_created"]);
+	});
+
+	it("seeds at least 3 successCriteria per goal", async () => {
+		const plan = await createUlwLoopPlan(await makeRepo(), { brief: await readBriefFixture() });
+
+		expect(plan.goals).toHaveLength(3);
+		expect(plan.goals.every((goal) => goal.successCriteria.length >= 3)).toBe(true);
+	});
+
+	it("refuses overwrite of an existing plan without --force", async () => {
+		const repoRoot = await makeRepo();
+		await createUlwLoopPlan(repoRoot, { brief: "first" });
+
+		await expect(createUlwLoopPlan(repoRoot, { brief: "second" })).rejects.toThrow(UlwLoopError);
+		await expect(createUlwLoopPlan(repoRoot, { brief: "second" })).rejects.toThrow("Refusing to overwrite");
+	});
+
+	it("aggregate is the default codexGoalMode", async () => {
+		const plan = await createUlwLoopPlan(await makeRepo(), { brief: "Ship the feature" });
+
+		expect(plan.codexGoalMode).toBe("aggregate");
+		expect(plan.codexObjective).toContain(".omo/ulw-loop/goals.json");
+	});
+});
+
+describe("deriveGoalCandidates", () => {
+	it("extracts bullets as goals", () => {
+		expect(deriveGoalCandidates("# Brief\n\n- Build auth\n- Add tests")).toEqual([
+			{ title: "Build auth", objective: "Build auth" },
+			{ title: "Add tests", objective: "Add tests" },
+		]);
+	});
+
+	it("falls back to paragraph parsing when no bullets", () => {
+		expect(deriveGoalCandidates("First objective.\n\nSecond objective.").map((goal) => goal.objective)).toEqual([
+			"First objective.",
+			"Second objective.",
+		]);
+	});
+
+	it("returns single default goal for empty/whitespace brief", () => {
+		expect(deriveGoalCandidates(" \n\t ")).toEqual([
+			{ title: "Complete the requested project objective.", objective: "Complete the requested project objective." },
+		]);
+	});
+});
+
+describe("addUlwLoopGoal", () => {
+	it("appends a new goal to plan with seeded successCriteria", async () => {
+		const repoRoot = await makeRepo();
+		await createUlwLoopPlan(repoRoot, { brief: "Build auth" });
+
+		const { plan, goal } = await addUlwLoopGoal(repoRoot, { title: "Add rate limit", objective: "Throttle login" });
+
+		expect(plan.goals).toHaveLength(2);
+		expect(goal.id).toBe("G002-add-rate-limit");
+		expect(goal.successCriteria).toHaveLength(3);
+	});
+
+	it("appends a ledger entry for goal_added", async () => {
+		const repoRoot = await makeRepo();
+		await createUlwLoopPlan(repoRoot, { brief: "Build auth" });
+
+		await addUlwLoopGoal(repoRoot, { title: "Add rate limit", objective: "Throttle login" });
+
+		expect(await ledgerKinds(repoRoot)).toEqual(["plan_created", "goal_added"]);
+	});
+});
+
+describe("startNextUlwLoop", () => {
+	it("picks the first pending goal", async () => {
+		const repoRoot = await makeRepo();
+		await createUlwLoopPlan(repoRoot, { brief: "- First\n- Second" });
+
+		const result = scheduled(await startNextUlwLoop(repoRoot, {}));
+
+		expect(result.goal.id).toBe("G001-first");
+		expect(result.goal.status).toBe("in_progress");
+		expect(result.resumed).toBe(false);
+	});
+
+	it("resumes the in_progress goal when one exists", async () => {
+		const repoRoot = await makeRepo();
+		const plan = await createUlwLoopPlan(repoRoot, { brief: "- First\n- Second" });
+		const active = makeGoal({ ...plan.goals[1], status: "in_progress" });
+		await writePlan(repoRoot, { ...plan, goals: [makeGoal({ ...plan.goals[0] }), active], activeGoalId: active.id });
+
+		const result = scheduled(await startNextUlwLoop(repoRoot, {}));
+
+		expect(result.goal.id).toBe(active.id);
+		expect(result.resumed).toBe(true);
+	});
+
+	it("with retryFailed picks first failed (non-blocked) goal", async () => {
+		const repoRoot = await makeRepo();
+		const failed = makeGoal({ status: "failed", failureReason: "flake" });
+		await mkdir(join(repoRoot, ".omo", "ulw-loop"), { recursive: true });
+		await writePlan(repoRoot, makePlan([failed]));
+
+		const result = scheduled(await startNextUlwLoop(repoRoot, { retryFailed: true }));
+
+		expect(result.goal.id).toBe("G001");
+		expect(result.goal.attempt).toBe(1);
+		expect(await ledgerKinds(repoRoot)).toEqual(["goal_retried", "goal_started"]);
+	});
+
+	it("returns { done: true } when no eligible goals remain", async () => {
+		const repoRoot = await makeRepo();
+		await mkdir(join(repoRoot, ".omo", "ulw-loop"), { recursive: true });
+		await writePlan(repoRoot, makePlan([makeGoal({ status: "complete" })]));
+
+		const result = await startNextUlwLoop(repoRoot, {});
+
+		expect(result).toMatchObject({ done: true });
+	});
+});
+
+describe("summarizeUlwLoopPlan", () => {
+	it("counts goals by status", () => {
+		const plan = makePlan([
+			makeGoal({ id: "G001", status: "pending" }),
+			makeGoal({ id: "G002", status: "in_progress" }),
+			makeGoal({ id: "G003", status: "complete" }),
+			makeGoal({ id: "G004", status: "failed" }),
+			makeGoal({ id: "G005", status: "blocked", steeringStatus: "blocked" }),
+			makeGoal({ id: "G006", status: "review_blocked" }),
+			makeGoal({ id: "G007", status: "needs_user_decision", steeringStatus: "superseded" }),
+		]);
+
+		expect(summarizeUlwLoopPlan(plan)).toMatchObject({
+			total: 7,
+			pending: 1,
+			in_progress: 1,
+			complete: 1,
+			failed: 1,
+			blocked: 1,
+			review_blocked: 1,
+			needs_user_decision: 1,
+			superseded: 1,
+		});
+	});
+
+	it("aggregates criteria pass/pending/fail/blocked across all goals", () => {
+		const plan = makePlan([
+			makeGoal({ successCriteria: [criterion("pass"), criterion("pending")] }),
+			makeGoal({ id: "G002", successCriteria: [criterion("fail"), criterion("blocked"), criterion("pending")] }),
+		]);
+
+		expect(summarizeUlwLoopPlan(plan).criteria).toEqual({ total: 5, pass: 1, pending: 2, fail: 1, blocked: 1 });
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/plan-io.test.ts

@@ -0,0 +1,239 @@
+import { copyFile, mkdir, mkdtemp, readdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it } from "vitest";
+import { ulwLoopDir, ulwLoopGoalsPath, ulwLoopLedgerPath } from "../src/paths.js";
+import {
+	appendLedger,
+	readSteeringLedgerEntries,
+	readUlwLoopPlan,
+	withUlwLoopMutationLock,
+	writePlan,
+} from "../src/plan-io.js";
+import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan } from "../src/types.js";
+import { UlwLoopError } from "../src/types.js";
+
+const NOW = "2026-05-23T00:00:00.000Z";
+const STABLE_OBJECTIVE =
+	"Complete the durable ulw-loop plan in .omo/ulw-loop/goals.json, including later accepted/appended stories, under the original brief constraints; use .omo/ulw-loop/ledger.jsonl as the audit trail.";
+
+function makeGoal(overrides: Partial<UlwLoopItem> = {}): UlwLoopItem {
+	return {
+		id: "G001",
+		title: "Build auth service",
+		objective: "Implement JWT auth endpoint",
+		status: "pending",
+		successCriteria: [],
+		attempt: 1,
+		createdAt: NOW,
+		updatedAt: NOW,
+		...overrides,
+	};
+}
+
+function makePlan(overrides: Partial<UlwLoopPlan> = {}): UlwLoopPlan {
+	return {
+		version: 1,
+		createdAt: NOW,
+		updatedAt: NOW,
+		briefPath: ".omo/ulw-loop/brief.md",
+		goalsPath: ".omo/ulw-loop/goals.json",
+		ledgerPath: ".omo/ulw-loop/ledger.jsonl",
+		codexGoalMode: "aggregate",
+		codexObjective: STABLE_OBJECTIVE,
+		codexObjectiveAliases: [],
+		goals: [makeGoal()],
+		...overrides,
+	};
+}
+
+function entry(kind: UlwLoopLedgerEntry["kind"], goalId = "G001"): UlwLoopLedgerEntry {
+	return { at: NOW, kind, goalId };
+}
+
+async function makeRepo(): Promise<string> {
+	return mkdtemp(join(tmpdir(), "ug-io-"));
+}
+
+async function writeRawPlan(repoRoot: string, plan: UlwLoopPlan): Promise<void> {
+	await mkdir(ulwLoopDir(repoRoot), { recursive: true });
+	await writeFile(ulwLoopGoalsPath(repoRoot), `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+}
+
+async function readLedgerLines(repoRoot: string): Promise<string[]> {
+	const raw = await readFile(ulwLoopLedgerPath(repoRoot), "utf8");
+	return raw.split(/\r?\n/).filter(Boolean);
+}
+
+describe("readUlwLoopPlan", () => {
+	let repoRoot = "";
+
+	beforeEach(async () => {
+		// given
+		repoRoot = await makeRepo();
+	});
+
+	it("throws UlwLoopError when goals.json is missing", async () => {
+		// when/then
+		await expect(readUlwLoopPlan(repoRoot)).rejects.toThrow(UlwLoopError);
+		await expect(readUlwLoopPlan(repoRoot)).rejects.toThrow("omo ulw-loop create-goals");
+	});
+
+	it("returns parsed plan when fixture is present", async () => {
+		// given
+		await mkdir(ulwLoopDir(repoRoot), { recursive: true });
+		await copyFile(join(process.cwd(), "test", "fixtures", "sample-plan.json"), ulwLoopGoalsPath(repoRoot));
+
+		// when
+		const plan = await readUlwLoopPlan(repoRoot);
+
+		// then
+		expect(plan.version).toBe(1);
+		expect(plan.codexGoalMode).toBe("aggregate");
+		expect(plan.goals).toHaveLength(3);
+		expect(plan.goals[0]?.successCriteria).toHaveLength(3);
+	});
+
+	it("migrates legacy aggregate objective on read + writes aggregate_objective_migrated ledger entry + retains alias", async () => {
+		// given
+		const legacyObjective = "Complete all ulw-loop stories in .omo/ulw-loop/goals.json: G001 Build auth service";
+		await writeRawPlan(repoRoot, makePlan({ codexObjective: legacyObjective }));
+
+		// when
+		const plan = await readUlwLoopPlan(repoRoot);
+
+		// then
+		expect(plan.codexObjective).toBe(STABLE_OBJECTIVE);
+		expect(plan.codexObjectiveAliases).toContain(legacyObjective);
+		const persisted = JSON.parse(await readFile(ulwLoopGoalsPath(repoRoot), "utf8"));
+		expect(persisted).toMatchObject({ codexObjective: STABLE_OBJECTIVE, codexObjectiveAliases: [legacyObjective] });
+		const lines = await readLedgerLines(repoRoot);
+		expect(lines).toHaveLength(1);
+		expect(JSON.parse(lines[0] ?? "{}")).toMatchObject({
+			kind: "aggregate_objective_migrated",
+			before: { codexObjective: legacyObjective },
+		});
+	});
+});
+
+describe("writePlan", () => {
+	it("writes goals.json atomically with no temp file left behind", async () => {
+		// given
+		const repoRoot = await makeRepo();
+
+		// when
+		await writePlan(repoRoot, makePlan());
+
+		// then
+		const raw = await readFile(ulwLoopGoalsPath(repoRoot), "utf8");
+		expect(JSON.parse(raw)).toMatchObject({ version: 1, goals: [{ id: "G001" }] });
+		expect((await readdir(ulwLoopDir(repoRoot))).filter((name) => name.endsWith(".tmp"))).toEqual([]);
+	});
+
+	it("overwrites existing file", async () => {
+		// given
+		const repoRoot = await makeRepo();
+		await writePlan(repoRoot, makePlan({ codexObjective: "first" }));
+
+		// when
+		await writePlan(repoRoot, makePlan({ codexObjective: "second" }));
+
+		// then
+		expect(JSON.parse(await readFile(ulwLoopGoalsPath(repoRoot), "utf8"))).toMatchObject({
+			codexObjective: "second",
+		});
+	});
+});
+
+describe("appendLedger", () => {
+	it("appends a single JSONL line to ledger.jsonl", async () => {
+		// given
+		const repoRoot = await makeRepo();
+		const ledgerEntry = entry("goal_started");
+
+		// when
+		await appendLedger(repoRoot, ledgerEntry);
+
+		// then
+		expect(await readLedgerLines(repoRoot)).toEqual([JSON.stringify(ledgerEntry)]);
+	});
+
+	it("creates ledger.jsonl if missing", async () => {
+		// given
+		const repoRoot = await makeRepo();
+
+		// when
+		await appendLedger(repoRoot, entry("goal_completed"));
+
+		// then
+		expect(await readFile(ulwLoopLedgerPath(repoRoot), "utf8")).toContain("goal_completed");
+	});
+
+	it("preserves prior entries", async () => {
+		// given
+		const repoRoot = await makeRepo();
+		const first = entry("goal_started");
+		const second = entry("goal_completed");
+
+		// when
+		await appendLedger(repoRoot, first);
+		await appendLedger(repoRoot, second);
+
+		// then
+		expect(await readLedgerLines(repoRoot)).toEqual([JSON.stringify(first), JSON.stringify(second)]);
+	});
+});
+
+describe("readSteeringLedgerEntries", () => {
+	it("returns only steering-related event kinds", async () => {
+		// given
+		const repoRoot = await makeRepo();
+		await appendLedger(repoRoot, entry("steering_accepted"));
+		await appendLedger(repoRoot, entry("goal_started"));
+		await appendLedger(repoRoot, entry("steering_rejected"));
+		await appendLedger(repoRoot, entry("criteria_revised"));
+
+		// when
+		const entries = await readSteeringLedgerEntries(repoRoot);
+
+		// then
+		expect(entries.map((item) => item.kind)).toEqual(["steering_accepted", "steering_rejected", "criteria_revised"]);
+	});
+
+	it("returns empty array when ledger missing", async () => {
+		// given
+		const repoRoot = await makeRepo();
+
+		// when/then
+		await expect(readSteeringLedgerEntries(repoRoot)).resolves.toEqual([]);
+	});
+});
+
+describe("withUlwLoopMutationLock", () => {
+	it("serializes concurrent invocations", async () => {
+		// given
+		const repoRoot = await makeRepo();
+		const counterPath = join(repoRoot, "counter.txt");
+		let active = 0;
+		let maxActive = 0;
+		await writeFile(counterPath, "0", "utf8");
+
+		// when
+		await Promise.all(
+			[1, 2, 3].map((_) =>
+				withUlwLoopMutationLock(repoRoot, async () => {
+					active += 1;
+					maxActive = Math.max(maxActive, active);
+					const current = Number(await readFile(counterPath, "utf8"));
+					await Promise.resolve();
+					await writeFile(counterPath, String(current + 1), "utf8");
+					active -= 1;
+				}),
+			),
+		);
+
+		// then
+		expect(maxActive).toBe(1);
+		expect(await readFile(counterPath, "utf8")).toBe("3");
+	});
+});

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

@@ -0,0 +1,203 @@
+import { readFile } from "node:fs/promises";
+
+import { describe, expect, it } from "vitest";
+
+import {
+	classifyExternalAuthorizationBlocker,
+	clearGoalBlockerFields,
+	normalizeBlockerEvidence,
+	sameBlockerOccurrences,
+	validateQualityGate,
+} from "../src/quality-gate.js";
+import type { UlwLoopItem, UlwLoopPlan } from "../src/types.js";
+import { UlwLoopError } from "../src/types.js";
+
+const NOW = "2026-05-23T00:00:00.000Z";
+const VALID_GATE = {
+	aiSlopCleaner: { status: "passed", evidence: "no slop detected after cleaner run" },
+	verification: { status: "passed", commands: ["npm test"], evidence: "all tests pass" },
+	codeReview: { recommendation: "APPROVE", architectStatus: "CLEAR", evidence: "ship it" },
+	criteriaCoverage: { totalCriteria: 2, passCount: 2, adversarialClassesCovered: ["malformed_input"] },
+} as const;
+
+interface GoalWithBlocker extends UlwLoopItem {
+	blocker?: { readonly signature: string };
+	blockerEvidence?: string;
+	blockerOccurrences?: number;
+	blockedAt?: string;
+}
+
+function makeGate(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+	return { ...VALID_GATE, ...overrides };
+}
+
+function getQualityGateError(input: unknown): UlwLoopError {
+	try {
+		validateQualityGate(input);
+	} catch (error) {
+		if (error instanceof UlwLoopError) return error;
+		throw error;
+	}
+	throw new Error("Expected UlwLoopError");
+}
+
+function makeGoal(overrides: Partial<UlwLoopItem> = {}): UlwLoopItem {
+	return {
+		id: "G001",
+		title: "Goal one",
+		objective: "Complete goal one",
+		status: "pending",
+		successCriteria: [],
+		attempt: 1,
+		createdAt: NOW,
+		updatedAt: NOW,
+		...overrides,
+	};
+}
+
+function makePlan(goals: UlwLoopItem[]): UlwLoopPlan {
+	return {
+		version: 1,
+		createdAt: NOW,
+		updatedAt: NOW,
+		briefPath: ".omo/ulw-loop/brief.md",
+		goalsPath: ".omo/ulw-loop/goals.json",
+		ledgerPath: ".omo/ulw-loop/ledger.jsonl",
+		goals,
+	};
+}
+
+describe("validateQualityGate", () => {
+	it("accepts valid quality gate from fixture", async () => {
+		// given
+		const raw = await readFile(new URL("./fixtures/sample-quality-gate.json", import.meta.url), "utf8");
+		const parsed: unknown = JSON.parse(raw);
+
+		// when
+		const gate = validateQualityGate(parsed);
+
+		// then
+		expect(gate.aiSlopCleaner.status).toBe("passed");
+		expect(gate).toMatchObject({ criteriaCoverage: { totalCriteria: 9, passCount: 9 } });
+	});
+
+	it("throws UlwLoopError when aiSlopCleaner missing", () => {
+		// when
+		const error = getQualityGateError(makeGate({ aiSlopCleaner: undefined }));
+
+		// then
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+	});
+
+	it("throws UlwLoopError when verification missing", () => {
+		// when
+		const error = getQualityGateError(makeGate({ verification: undefined }));
+
+		// then
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+	});
+
+	it("throws UlwLoopError when codeReview missing", () => {
+		// when
+		const error = getQualityGateError(makeGate({ codeReview: undefined }));
+
+		// then
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+	});
+
+	it("throws UlwLoopError when criteriaCoverage missing (NEW)", () => {
+		// when
+		const error = getQualityGateError(makeGate({ criteriaCoverage: undefined }));
+
+		// then
+		expect(error.code).toBe("ULW_LOOP_QUALITY_GATE_INVALID");
+	});
+
+	it("throws UlwLoopError when criteriaCoverage.passCount < totalCriteria (NEW)", () => {
+		// when
+		const error = getQualityGateError(
+			makeGate({ criteriaCoverage: { totalCriteria: 3, passCount: 2, adversarialClassesCovered: [] } }),
+		);
+
+		// then
+		expect(error.message).toContain("criteriaCoverage.passCount");
+	});
+
+	it("throws UlwLoopError when codeReview.recommendation is not APPROVE", () => {
+		// when
+		const error = getQualityGateError(
+			makeGate({ codeReview: { ...VALID_GATE.codeReview, recommendation: "COMMENT" } }),
+		);
+
+		// then
+		expect(error.message).toContain("recommendation");
+	});
+
+	it("throws UlwLoopError when architectStatus is not CLEAR", () => {
+		// when
+		const error = getQualityGateError(
+			makeGate({ codeReview: { ...VALID_GATE.codeReview, architectStatus: "WATCH" } }),
+		);
+
+		// then
+		expect(error.message).toContain("architectStatus");
+	});
+});
+
+describe("classifyExternalAuthorizationBlocker", () => {
+	it("returns GHCR signature when evidence mentions ghcr.io auth failure", () => {
+		expect(
+			classifyExternalAuthorizationBlocker("ghcr.io returned 401 authentication required for package pull"),
+		).toBe("GHCR_PULL_ACCESS:HTTP_401_ANONYMOUS:GHCR_VISIBILITY_OR_CREDENTIAL_REQUIRED");
+	});
+
+	it("returns generic auth signature for generic 401 evidence", () => {
+		expect(classifyExternalAuthorizationBlocker("Registry returned 401 because credentials are missing")).toBe(
+			"EXTERNAL_AUTHORIZATION_REQUIRED",
+		);
+	});
+
+	it("returns null when no auth keywords", () => {
+		expect(classifyExternalAuthorizationBlocker("build failed because tests failed")).toBeNull();
+	});
+});
+
+describe("normalizeBlockerEvidence", () => {
+	it("collapses whitespace + lowercases", () => {
+		expect(normalizeBlockerEvidence(" GHCR.IO\n\tNeeds   TOKEN ")).toBe("ghcr.io needs token");
+	});
+});
+
+describe("sameBlockerOccurrences", () => {
+	it("counts goals matching signature", () => {
+		// given
+		const nested: GoalWithBlocker = { ...makeGoal({ id: "G002" }), blocker: { signature: "AUTH" } };
+		const plan = makePlan([makeGoal({ blockerSignature: "AUTH" }), nested, makeGoal({ id: "G003" })]);
+
+		// when/then
+		expect(sameBlockerOccurrences(plan, "AUTH")).toBe(2);
+	});
+});
+
+describe("clearGoalBlockerFields", () => {
+	it("clears all 5 blocker fields", () => {
+		// given
+		const goal: GoalWithBlocker = {
+			...makeGoal({ blockerSignature: "AUTH" }),
+			blocker: { signature: "AUTH" },
+			blockerEvidence: "401 unauthorized",
+			blockerOccurrences: 2,
+			blockedAt: NOW,
+		};
+
+		// when
+		clearGoalBlockerFields(goal);
+
+		// then
+		expect(goal).not.toHaveProperty("blocker");
+		expect(goal).not.toHaveProperty("blockerSignature");
+		expect(goal).not.toHaveProperty("blockerEvidence");
+		expect(goal).not.toHaveProperty("blockerOccurrences");
+		expect(goal).not.toHaveProperty("blockedAt");
+	});
+});