oh-my-opencode 4.10.0 → 4.11.0

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

@@ -1,166 +1,258 @@
-import type { UlwLoopItem, UlwLoopPlan, UlwLoopQualityGate } from "./types.js";
-import { UlwLoopError } from "./types.js";
-
-const BLOCKER_FIELD_KEYS = "blocker blockerSignature blockerEvidence blockerOccurrences blockedAt".split(" ");
-const URL_PATTERN = /https?:\/\/\S+/g;
-const PUNCTUATION_PATTERN = /[`"'()[\]{}:,;]/g;
-const WHITESPACE_PATTERN = /\s+/g;
-const AUTH_PATTERN = /\b(auth\w*|credential\w*|token|permission\w*|scope\w*|access|unauthorized|forbidden|401|403)\b/;
-const MISSING_PATTERN =
-	/\b(unset|missing|required|requires|without|omit\w*|not set|not available|no read packages|read packages)\b/;
-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 } });
+import { resolve } from "node:path";
+import {
+	emptyBlockers,
+	invalid,
+	literal,
+	numberField,
+	section,
+	stringArray,
+	textField,
+} from "./quality-gate-fields.js";
+import type {
+	UlwLoopManualQaArtifactKind,
+	UlwLoopManualQaArtifactRef,
+	UlwLoopManualQaSurface,
+	UlwLoopQualityGate,
+} from "./types.js";
+
+const REVIEWER_ROLES = {
+	codeReview: "lazycodex-code-reviewer",
+	manualQa: "lazycodex-qa-executor",
+	gateReview: "lazycodex-gate-reviewer",
+} as const;
+
+export {
+	classifyExternalAuthorizationBlocker,
+	clearGoalBlockerFields,
+	normalizeBlockerEvidence,
+	sameBlockerOccurrences,
+} from "./quality-gate-blockers.js";
+
+export interface QualityGateFs {
+	readonly existsSync: (path: string) => boolean;
+	readonly statSync: (path: string) => { readonly size: number };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+export interface ValidateQualityGateOptions {
+	readonly repoRoot: string;
+	readonly fs: QualityGateFs;
 }
 
-function section(value: unknown, field: string): Record<string, unknown> {
-	return isRecord(value) ? value : invalid(`Final quality gate is missing ${field} evidence.`, field);
+function reviewerRoleField<T extends string>(value: unknown, expected: T, field: string): T {
+	const actual = textField(value, field);
+	if (actual !== expected) invalid(`${field} must be ${expected}.`, field);
+	return expected;
 }
 
-function nonEmptyString(value: unknown, field: string): string {
-	return typeof value === "string" && value.trim() !== ""
-		? value
-		: invalid(`Final quality gate requires non-empty ${field}.`, field);
+function surfaceField(value: unknown, field: string): UlwLoopManualQaSurface {
+	if (
+		value === "cli" ||
+		value === "http" ||
+		value === "tmux" ||
+		value === "browser" ||
+		value === "gui" ||
+		value === "data"
+	)
+		return value;
+	invalid(`${field} must be a supported manual QA surface.`, field);
 }
 
-function numberField(value: unknown, field: string): number {
-	return typeof value === "number" && Number.isFinite(value)
-		? value
-		: invalid(`Final quality gate requires numeric ${field}.`, field);
+function kindField(value: unknown, field: string): UlwLoopManualQaArtifactKind {
+	if (
+		value === "cli-transcript" ||
+		value === "log" ||
+		value === "screenshot" ||
+		value === "image" ||
+		value === "http-dump" ||
+		value === "data-diff"
+	)
+		return value;
+	invalid(`${field} must be a supported artifact kind.`, field);
 }
 
-function stringArray(value: unknown, field: string): string[] {
-	if (!Array.isArray(value) || value.length === 0) return invalid(`Final quality gate requires ${field}.`, field);
-	return value.map((item) => nonEmptyString(item, field));
+function passedVerdict(value: unknown, field: string): "passed" {
+	if (value === "not_applicable") invalid(`${field} must not be not_applicable.`, field);
+	return literal(value, "passed", 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);
+function artifactCompatible(surface: UlwLoopManualQaSurface, kind: UlwLoopManualQaArtifactKind): boolean {
+	switch (surface) {
+		case "cli":
+		case "tmux":
+			return kind === "cli-transcript" || kind === "log";
+		case "http":
+			return kind === "http-dump";
+		case "browser":
+		case "gui":
+			return kind === "screenshot" || kind === "image";
+		case "data":
+			return kind === "data-diff";
+		default:
+			invalid("manualQa.surfaceEvidence has an unsupported surface.", "manualQa.surfaceEvidence.surface");
 	}
-	if (value === undefined) {
-		if (evidenceApproved) return expectedValue;
-		invalid(`${field} must be ${expectedValue} or codeReview.evidence should include UNCONDITIONAL APPROVAL.`, field);
+}
+
+function checkFile(path: string, field: string, opts?: ValidateQualityGateOptions): void {
+	if (opts === undefined) return;
+	const absolute = resolve(opts.repoRoot, path);
+	if (!opts.fs.existsSync(absolute)) invalid(`${field} must point to an existing artifact.`, field);
+	const stat = opts.fs.statSync(absolute);
+	if (stat.size <= 0) invalid(`${field} must point to a non-empty artifact.`, field);
+}
+
+function artifactMap(refs: readonly UlwLoopManualQaArtifactRef[]): Map<string, UlwLoopManualQaArtifactRef> {
+	const byId = new Map<string, UlwLoopManualQaArtifactRef>();
+	for (const ref of refs) {
+		if (byId.has(ref.id)) invalid(`manualQa.artifactRefs contains duplicate ${ref.id}.`, "manualQa.artifactRefs");
+		byId.set(ref.id, ref);
 	}
-	invalid(`${field} must be ${expectedValue}.`, field);
+	return byId;
+}
+
+function parseArtifactRefs(value: unknown, opts?: ValidateQualityGateOptions): readonly UlwLoopManualQaArtifactRef[] {
+	if (!Array.isArray(value) || value.length === 0)
+		invalid("manualQa.artifactRefs must not be empty.", "manualQa.artifactRefs");
+	return value.map((item, index) => {
+		const ref = section(item, `manualQa.artifactRefs[${index}]`);
+		const path = textField(ref["path"], `manualQa.artifactRefs[${index}].path`);
+		checkFile(path, `manualQa.artifactRefs[${index}].path`, opts);
+		return {
+			id: textField(ref["id"], `manualQa.artifactRefs[${index}].id`),
+			kind: kindField(ref["kind"], `manualQa.artifactRefs[${index}].kind`),
+			description: textField(ref["description"], `manualQa.artifactRefs[${index}].description`),
+			path,
+		};
+	});
 }
 
-export function validateQualityGate(input: unknown): UlwLoopQualityGate {
+function referencedArtifacts(
+	value: unknown,
+	field: string,
+	byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>,
+): readonly UlwLoopManualQaArtifactRef[] {
+	return stringArray(value, field).map((id) => {
+		const artifact = byId.get(id);
+		if (artifact === undefined) invalid(`${field} references unknown artifact ${id}.`, field);
+		return artifact;
+	});
+}
+
+export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate {
 	const gate = section(input, "qualityGate");
-	const cleaner = section(gate["aiSlopCleaner"], "aiSlopCleaner");
-	const verification = section(gate["verification"], "verification");
-	const review = section(gate["codeReview"], "codeReview");
+	const codeReview = section(gate["codeReview"], "codeReview");
+	const manualQa = section(gate["manualQa"], "manualQa");
+	const gateReview = section(gate["gateReview"], "gateReview");
+	const iteration = section(gate["iteration"], "iteration");
 	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");
 	const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
 	const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
 	if (passCount < totalCriteria)
 		invalid("criteriaCoverage.passCount must cover totalCriteria.", "criteriaCoverage.passCount");
-	const commands = stringArray(verification["commands"], "verification.commands");
-	const covered = stringArray(coverage["adversarialClassesCovered"], "criteriaCoverage.adversarialClassesCovered");
-	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, architectStatus, evidence: reviewEvidence },
+	const artifactRefs = parseArtifactRefs(manualQa["artifactRefs"], opts);
+	const byId = artifactMap(artifactRefs);
+	const surfaceEvidence = parseSurfaceEvidence(manualQa["surfaceEvidence"], byId);
+	const adversarialCases = parseAdversarialCases(manualQa["adversarialCases"], byId);
+	const codeReportPath = textField(codeReview["reportPath"], "codeReview.reportPath");
+	const gateReportPath = textField(gateReview["reportPath"], "gateReview.reportPath");
+	checkFile(codeReportPath, "codeReview.reportPath", opts);
+	checkFile(gateReportPath, "gateReview.reportPath", opts);
+	return {
+		codeReview: {
+			by: reviewerRoleField(codeReview["by"], REVIEWER_ROLES.codeReview, "codeReview.by"),
+			recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
+			codeQualityStatus: literal(codeReview["codeQualityStatus"], "CLEAR", "codeReview.codeQualityStatus"),
+			reportPath: codeReportPath,
+			evidence: textField(codeReview["evidence"], "codeReview.evidence"),
+			blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
+		},
+		manualQa: {
+			by: reviewerRoleField(manualQa["by"], REVIEWER_ROLES.manualQa, "manualQa.by"),
+			status: literal(manualQa["status"], "passed", "manualQa.status"),
+			evidence: textField(manualQa["evidence"], "manualQa.evidence"),
+			surfaceEvidence,
+			adversarialCases,
+			artifactRefs,
+		},
+		gateReview: {
+			by: reviewerRoleField(gateReview["by"], REVIEWER_ROLES.gateReview, "gateReview.by"),
+			recommendation: literal(gateReview["recommendation"], "APPROVE", "gateReview.recommendation"),
+			reportPath: gateReportPath,
+			evidence: textField(gateReview["evidence"], "gateReview.evidence"),
+			blockers: emptyBlockers(gateReview["blockers"], "gateReview.blockers"),
+		},
+		iteration: {
+			fullRerun: literal(iteration["fullRerun"], true, "iteration.fullRerun"),
+			status: literal(iteration["status"], "passed", "iteration.status"),
+			rerunCommands: stringArray(iteration["rerunCommands"], "iteration.rerunCommands"),
+			evidence: textField(iteration["evidence"], "iteration.evidence"),
+		},
+		criteriaCoverage: {
+			totalCriteria,
+			passCount,
+			originalIntent: textField(coverage["originalIntent"], "criteriaCoverage.originalIntent"),
+			desiredOutcome: textField(coverage["desiredOutcome"], "criteriaCoverage.desiredOutcome"),
+			userOutcomeReview: textField(coverage["userOutcomeReview"], "criteriaCoverage.userOutcomeReview"),
+			adversarialClassesCovered: stringArray(
+				coverage["adversarialClassesCovered"],
+				"criteriaCoverage.adversarialClassesCovered",
+			),
+		},
 	};
-	Object.assign(result, { criteriaCoverage: { totalCriteria, passCount, adversarialClassesCovered: covered } });
-	return result;
-}
-
-export function normalizeBlockerEvidence(evidence: string): string {
-	const withoutUrls = evidence.toLowerCase().replace(URL_PATTERN, " ");
-	const withoutPunctuation = withoutUrls.replace(PUNCTUATION_PATTERN, " ");
-	return withoutPunctuation.replace(WHITESPACE_PATTERN, " ").trim();
-}
-
-export function classifyExternalAuthorizationBlocker(evidence: string): string | null {
-	const normalized = normalizeBlockerEvidence(evidence);
-	if (!normalized || !AUTH_PATTERN.test(normalized) || !MISSING_PATTERN.test(normalized)) return null;
-	if (!GHCR_PATTERN.test(normalized)) return "EXTERNAL_AUTHORIZATION_REQUIRED";
-	const status401 = GHCR_401_PATTERN.test(normalized) ? "HTTP_401_ANONYMOUS" : null;
-	const status403 = GHCR_403_PATTERN.test(normalized) ? "HTTP_403_NO_READ_PACKAGES" : null;
-	const status = [status401, status403].filter((part): part is string => part !== null).join("+");
-	return `GHCR_PULL_ACCESS:${status || "AUTHORIZATION_REQUIRED"}:GHCR_VISIBILITY_OR_CREDENTIAL_REQUIRED`;
-}
-
-function nestedBlockerSignature(goal: UlwLoopItem): string | null {
-	const blocker = Reflect.get(goal, "blocker");
-	const signature = isRecord(blocker) ? blocker["signature"] : null;
-	return typeof signature === "string" ? signature : null;
 }
 
-export function sameBlockerOccurrences(plan: UlwLoopPlan, signature: string): number {
-	return plan.goals.filter((goal) => goal.blockerSignature === signature || nestedBlockerSignature(goal) === signature)
-		.length;
+function parseSurfaceEvidence(
+	value: unknown,
+	byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>,
+): UlwLoopQualityGate["manualQa"]["surfaceEvidence"] {
+	if (!Array.isArray(value) || value.length === 0)
+		invalid("manualQa.surfaceEvidence must not be empty.", "manualQa.surfaceEvidence");
+	return value.map((item, index) => {
+		const row = section(item, `manualQa.surfaceEvidence[${index}]`);
+		const surface = surfaceField(row["surface"], `manualQa.surfaceEvidence[${index}].surface`);
+		const artifacts = referencedArtifacts(
+			row["artifactRefs"],
+			`manualQa.surfaceEvidence[${index}].artifactRefs`,
+			byId,
+		);
+		for (const artifact of artifacts) {
+			if (!artifactCompatible(surface, artifact.kind)) {
+				invalid(
+					`manualQa.surfaceEvidence ${surface} artifact ${artifact.kind} is incompatible.`,
+					"manualQa.surfaceEvidence",
+				);
+			}
+		}
+		return {
+			id: textField(row["id"], `manualQa.surfaceEvidence[${index}].id`),
+			criterionRef: textField(row["criterionRef"], `manualQa.surfaceEvidence[${index}].criterionRef`),
+			surface,
+			invocation: textField(row["invocation"], `manualQa.surfaceEvidence[${index}].invocation`),
+			verdict: passedVerdict(row["verdict"], `manualQa.surfaceEvidence[${index}].verdict`),
+			artifactRefs: artifacts.map((artifact) => artifact.id),
+		};
+	});
 }
 
-export function clearGoalBlockerFields(goal: UlwLoopItem): void {
-	for (const key of BLOCKER_FIELD_KEYS) Reflect.deleteProperty(goal, key);
+function parseAdversarialCases(
+	value: unknown,
+	byId: ReadonlyMap<string, UlwLoopManualQaArtifactRef>,
+): UlwLoopQualityGate["manualQa"]["adversarialCases"] {
+	if (!Array.isArray(value) || value.length === 0)
+		invalid("manualQa.adversarialCases must not be empty.", "manualQa.adversarialCases");
+	return value.map((item, index) => {
+		const row = section(item, `manualQa.adversarialCases[${index}]`);
+		const artifacts = referencedArtifacts(
+			row["artifactRefs"],
+			`manualQa.adversarialCases[${index}].artifactRefs`,
+			byId,
+		);
+		return {
+			id: textField(row["id"], `manualQa.adversarialCases[${index}].id`),
+			criterionRef: textField(row["criterionRef"], `manualQa.adversarialCases[${index}].criterionRef`),
+			scenario: textField(row["scenario"], `manualQa.adversarialCases[${index}].scenario`),
+			expectedBehavior: textField(row["expectedBehavior"], `manualQa.adversarialCases[${index}].expectedBehavior`),
+			verdict: passedVerdict(row["verdict"], `manualQa.adversarialCases[${index}].verdict`),
+			artifactRefs: artifacts.map((artifact) => artifact.id),
+		};
+	});
 }

package/packages/omo-codex/plugin/components/ulw-loop/test/checkpoint-final.test.ts

@@ -0,0 +1,186 @@
+import { writeFile } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+
+import { checkpointUlwLoop } from "../src/checkpoint.js";
+import { ulwLoopBriefPath } from "../src/paths.js";
+import { startNextUlwLoop } from "../src/plan-crud.js";
+import { criterion, expectCode, goal, passGoal, plan, repoWith, snapshot } from "./fixtures/checkpoint-builders.js";
+import { MISSING_ARTIFACT_PATH, qualityGateJson } from "./fixtures/quality-gate-builder.js";
+
+describe("checkpointUlwLoop final story", () => {
+	it("requires quality-gate-json for the final goal complete", async () => {
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+		await expectCode(
+			() =>
+				checkpointUlwLoop(repo, {
+					goalId: "G002",
+					status: "complete",
+					evidence: "final work complete and validation passed",
+					codexGoalJson: snapshot("complete"),
+				}),
+			"ULW_LOOP_QUALITY_GATE_INVALID",
+		);
+	});
+
+	it("accepts final story when quality gate JSON includes valid criteriaCoverage", async () => {
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G002",
+			status: "complete",
+			evidence: "final work complete and validation passed",
+			codexGoalJson: snapshot("complete"),
+			qualityGateJson: await qualityGateJson(repo),
+		});
+
+		expect(result.aggregateCompletion?.status).toBe("complete");
+		expect(result.plan.aggregateCompletion?.status).toBe("complete");
+	});
+
+	it("rejects final story until earlier non-essential criteria pass", async () => {
+		const earlier = goal({
+			id: "G001",
+			status: "complete",
+			successCriteria: [
+				criterion("C001", "pass", { essential: true }),
+				criterion("C002", "pending", { essential: false }),
+			],
+		});
+		const repo = await repoWith(plan([earlier, passGoal("G002")], { activeGoalId: "G002" }));
+		const gateJson = await qualityGateJson(repo);
+
+		await expectCode(
+			() =>
+				checkpointUlwLoop(repo, {
+					goalId: "G002",
+					status: "complete",
+					evidence: "final work complete and validation passed",
+					codexGoalJson: snapshot("complete"),
+					qualityGateJson: gateJson,
+				}),
+			"ulw_loop_criteria_not_all_pass",
+		);
+	});
+
+	it("rejects final story when quality gate references a missing manual QA artifact", async () => {
+		const repo = await repoWith(
+			plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }),
+		);
+		const gateJson = await qualityGateJson(repo, MISSING_ARTIFACT_PATH);
+
+		await expectCode(
+			() =>
+				checkpointUlwLoop(repo, {
+					goalId: "G002",
+					status: "complete",
+					evidence: "final work complete and validation passed",
+					codexGoalJson: snapshot("complete"),
+					qualityGateJson: gateJson,
+				}),
+			"ULW_LOOP_QUALITY_GATE_INVALID",
+		);
+	});
+
+	it("ACCEPTS complete when task-scoped completed Codex objective maps to the ulw-loop brief", async () => {
+		const taskObjective = "Fix ulw-loop objective mismatch and install local ulw";
+		const repo = await repoWith(plan([passGoal("G001")], { activeGoalId: "G001" }));
+		await writeFile(ulwLoopBriefPath(repo), `${taskObjective}\n`, "utf8");
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G001",
+			status: "complete",
+			evidence: "final implementation complete and quality gate passed",
+			codexGoalJson: snapshot("complete", taskObjective),
+			qualityGateJson: await qualityGateJson(repo),
+		});
+
+		expect(result.aggregateCompletion?.status).toBe("complete");
+		expect(result.ledgerEntry.kind).toBe("aggregate_completed");
+	});
+
+	it("ACCEPTS complete when active task-scoped Codex objective maps to the ulw-loop brief", async () => {
+		const taskObjective = "Create only research artifacts with source evidence";
+		const repo = await repoWith(plan([passGoal("G001")], { activeGoalId: "G001" }));
+		await writeFile(ulwLoopBriefPath(repo), `${taskObjective}\n`, "utf8");
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G001",
+			status: "complete",
+			evidence: "final implementation complete and quality gate passed",
+			codexGoalJson: snapshot("active", taskObjective),
+			qualityGateJson: await qualityGateJson(repo),
+		});
+
+		expect(result.aggregateCompletion?.status).toBe("complete");
+		expect(result.ledgerEntry.kind).toBe("aggregate_completed");
+	});
+
+	it("explains final task-scoped objective mapping when completed Codex objective is unrelated", async () => {
+		const repo = await repoWith(plan([passGoal("G001")], { activeGoalId: "G001" }));
+		await writeFile(ulwLoopBriefPath(repo), "Fix ulw-loop objective mismatch and install local ulw\n", "utf8");
+
+		await expect(
+			checkpointUlwLoop(repo, {
+				goalId: "G001",
+				status: "complete",
+				evidence: "final implementation complete and quality gate passed",
+				codexGoalJson: snapshot("complete", "unrelated completed task"),
+				qualityGateJson: await qualityGateJson(repo),
+			}),
+		).rejects.toThrow("Final task-scoped aggregate reconciliation");
+	});
+
+	it("keeps aggregate open when non-final task-scoped Codex completion maps to the brief", async () => {
+		const taskObjective = "Implement first accepted story";
+		const first = goal({
+			id: "G001",
+			status: "in_progress",
+			successCriteria: [
+				criterion("C001", "pass", { essential: true }),
+				criterion("C002", "pending", { essential: false }),
+			],
+		});
+		const second = goal({ id: "G002", status: "pending", objective: "Implement second accepted story" });
+		const repo = await repoWith(plan([first, second], { activeGoalId: "G001" }));
+		await writeFile(ulwLoopBriefPath(repo), `${taskObjective}\n`, "utf8");
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G001",
+			status: "complete",
+			evidence: "G001 updated .omo/ulw-loop/goals.json after implementation completed and validation passed",
+			codexGoalJson: snapshot("complete", taskObjective),
+			qualityGateJson: await qualityGateJson(repo),
+		});
+		const next = await startNextUlwLoop(repo);
+
+		expect(result.aggregateCompletion).toBeUndefined();
+		expect(result.plan.aggregateCompletion).toBeUndefined();
+		expect(result.ledgerEntry.kind).toBe("goal_completed");
+		expect(next).toMatchObject({ goal: { id: "G002", status: "in_progress" } });
+	});
+
+	it("requires all criteria for per-story completion", async () => {
+		const current = goal({
+			successCriteria: [
+				criterion("C001", "pass", { essential: true }),
+				criterion("C002", "pending", { essential: false }),
+			],
+		});
+		const repo = await repoWith(plan([current], { codexGoalMode: "per_story", activeGoalId: "G001" }));
+
+		await expectCode(
+			() =>
+				checkpointUlwLoop(repo, {
+					goalId: "G001",
+					status: "complete",
+					evidence: "per-story implementation complete and validation passed",
+					codexGoalJson: snapshot("complete", current.objective),
+				}),
+			"ulw_loop_criteria_not_all_pass",
+		);
+	});
+});

package/packages/omo-codex/plugin/components/ulw-loop/test/checkpoint-status.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+
+import { checkpointUlwLoop } from "../src/checkpoint.js";
+import { criterion, goal, lastLedger, plan, repoWith } from "./fixtures/checkpoint-builders.js";
+
+describe("checkpointUlwLoop status=failed", () => {
+	it("sets goal.status=failed, goal.failedAt, appends ledger", async () => {
+		const repo = await repoWith(plan([goal({ successCriteria: [criterion("C001", "pending")] })]));
+
+		const result = await checkpointUlwLoop(repo, { goalId: "G001", status: "failed", evidence: "tests failed" });
+
+		expect(result.goal.status).toBe("failed");
+		expect(result.goal.failedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/u);
+		expect((await lastLedger(repo)).kind).toBe("goal_failed");
+	});
+
+	it("classifies external authorization blocker signatures", async () => {
+		const repo = await repoWith(plan([goal()]));
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G001",
+			status: "failed",
+			evidence: "ghcr.io returned 401 authentication required because token missing",
+		});
+
+		expect(result.goal.blockerSignature).toBe(
+			"GHCR_PULL_ACCESS:HTTP_401_ANONYMOUS:GHCR_VISIBILITY_OR_CREDENTIAL_REQUIRED",
+		);
+	});
+
+	it("after 3 same-signature blockers, marks needs_user_decision + nonRetriable", async () => {
+		const repo = await repoWith(
+			plan(
+				[
+					goal({ id: "G001", status: "failed", blockerSignature: "EXTERNAL_AUTHORIZATION_REQUIRED" }),
+					goal({ id: "G002", status: "blocked", blockerSignature: "EXTERNAL_AUTHORIZATION_REQUIRED" }),
+					goal({ id: "G003" }),
+				],
+				{ activeGoalId: "G003" },
+			),
+		);
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G003",
+			status: "failed",
+			evidence: "Registry returned 401 because credentials are missing",
+		});
+
+		expect(result.goal.status).toBe("needs_user_decision");
+		expect(result.goal.nonRetriable).toBe(true);
+	});
+
+	it("skips the criteria gate for failed status", async () => {
+		const repo = await repoWith(plan([goal({ successCriteria: [criterion("C001", "pending")] })]));
+
+		await expect(
+			checkpointUlwLoop(repo, { goalId: "G001", status: "failed", evidence: "not done" }),
+		).resolves.toMatchObject({ goal: { status: "failed" } });
+	});
+});
+
+describe("checkpointUlwLoop status=blocked", () => {
+	it("preserves blocker fields + appends ledger", async () => {
+		const repo = await repoWith(plan([goal()]));
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G001",
+			status: "blocked",
+			evidence: "ghcr.io requires token and credentials are missing",
+		});
+
+		expect(result.goal.status).toBe("blocked");
+		expect(result.goal.blockedReason).toContain("ghcr.io");
+		expect(result.goal.blockerSignature).toContain("GHCR_PULL_ACCESS");
+		expect((await lastLedger(repo)).kind).toBe("goal_blocked");
+	});
+
+	it("skips the criteria gate for blocked status", async () => {
+		const repo = await repoWith(plan([goal({ successCriteria: [criterion("C001", "pending")] })]));
+
+		await expect(
+			checkpointUlwLoop(repo, { goalId: "G001", status: "blocked", evidence: "waiting for approval" }),
+		).resolves.toMatchObject({ goal: { status: "blocked" } });
+	});
+});