oh-my-opencode 4.10.0 → 4.11.0

package/packages/omo-codex/plugin/components/ulw-loop/src/cli-subcommands.ts

@@ -0,0 +1,250 @@
+import { readFile } from "node:fs/promises";
+
+import { type CheckpointUlwLoopArgs, checkpointUlwLoop } from "./checkpoint.js";
+import {
+	hasFlag,
+	parseCodexGoalJson,
+	parseRecordEvidenceArgs,
+	positionalText,
+	readStdin,
+	readValue,
+} from "./cli-arg-parser.js";
+import { blockedDecisionHandoff, normalizeCodexGoalMode, printJson, printStatus } from "./cli-output.js";
+import { parseSteeringProposal, printSteerResult } from "./cli-steering.js";
+import { buildCodexGoalInstruction } from "./codex-goal-instruction.js";
+import { recordEvidence } from "./evidence.js";
+import { isEssentialCriterion } from "./goal-status.js";
+import type { UlwLoopScope } from "./paths.js";
+import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "./plan-crud.js";
+import { readUlwLoopPlan } from "./plan-io.js";
+import { recordFinalReviewBlockers } from "./review-blockers.js";
+import { steerUlwLoop } from "./steering.js";
+import type { UlwLoopItem } from "./types.js";
+import { UlwLoopError } from "./types.js";
+
+type CheckpointStatus = "complete" | "failed" | "blocked";
+
+export async function createGoals(
+	repoRoot: string,
+	argv: readonly string[],
+	json: boolean,
+	scope?: UlwLoopScope,
+): Promise<number> {
+	const briefFile = readValue(argv, "--brief-file");
+	const brief =
+		readValue(argv, "--brief") ??
+		(briefFile === undefined ? undefined : await readFile(briefFile, "utf8")) ??
+		(hasFlag(argv, "--from-stdin") ? await readStdin() : undefined) ??
+		positionalText(argv);
+	if (!brief.trim()) {
+		throw new UlwLoopError(
+			"Missing brief text. Pass --brief, --brief-file, --from-stdin, or positional text.",
+			"ULW_LOOP_BRIEF_REQUIRED",
+		);
+	}
+	const plan = await createUlwLoopPlan(
+		repoRoot,
+		{
+			brief,
+			codexGoalMode: normalizeCodexGoalMode(readValue(argv, "--codex-goal-mode")),
+			force: hasFlag(argv, "--force"),
+		},
+		scope,
+	);
+	if (json) printJson({ ok: true, plan, summary: summarizeUlwLoopPlan(plan) });
+	else {
+		process.stdout.write(
+			`ulw-loop plan created: ${plan.goals.length} goal(s)\nbrief: ${plan.briefPath}\ngoals: ${plan.goalsPath}\nledger: ${plan.ledgerPath}\n`,
+		);
+	}
+	return 0;
+}
+
+export async function status(repoRoot: string, json: boolean, scope?: UlwLoopScope): Promise<number> {
+	const plan = await readUlwLoopPlan(repoRoot, scope);
+	if (json) printJson({ ok: true, plan, summary: summarizeUlwLoopPlan(plan) });
+	else printStatus(plan);
+	return 0;
+}
+
+export async function completeGoals(
+	repoRoot: string,
+	argv: readonly string[],
+	json: boolean,
+	scope?: UlwLoopScope,
+): Promise<number> {
+	const result = await startNextUlwLoop(repoRoot, { retryFailed: hasFlag(argv, "--retry-failed") }, scope);
+	if ("done" in result) {
+		const handoff = blockedDecisionHandoff(result.plan);
+		if (json) {
+			printJson({
+				ok: true,
+				done: true,
+				blocked: handoff.length > 0,
+				handoff,
+				summary: summarizeUlwLoopPlan(result.plan),
+				plan: result.plan,
+			});
+		} else process.stdout.write(`${handoff || "ulw-loop: all goals complete"}\n`);
+		return 0;
+	}
+	const instruction = buildCodexGoalInstruction({ plan: result.plan, goal: result.goal });
+	if (json) printJson({ ok: true, resumed: result.resumed, goal: result.goal, instruction, plan: result.plan });
+	else process.stdout.write(`${instruction.text}\n`);
+	return 0;
+}
+
+export async function checkpoint(
+	repoRoot: string,
+	argv: readonly string[],
+	json: boolean,
+	scope?: UlwLoopScope,
+): Promise<number> {
+	const goalId = required(argv, "--goal-id");
+	const statusValue = checkpointStatus(required(argv, "--status"));
+	const evidence = required(argv, "--evidence");
+	const codexGoalJson = await parseCodexGoalJson(
+		statusValue === "complete" ? required(argv, "--codex-goal-json") : readValue(argv, "--codex-goal-json"),
+	);
+	if (statusValue === "complete" && codexGoalJson === undefined) {
+		throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
+	}
+	const qualityGateJson = readValue(argv, "--quality-gate-json");
+	const args: CheckpointUlwLoopArgs = {
+		goalId,
+		status: statusValue,
+		evidence,
+		...(codexGoalJson === undefined ? {} : { codexGoalJson }),
+		...(qualityGateJson === undefined ? {} : { qualityGateJson }),
+	};
+	const result = await checkpointUlwLoop(repoRoot, args, scope);
+	if (json) printJson({ ok: true, ...result, summary: summarizeUlwLoopPlan(result.plan) });
+	else process.stdout.write(`ulw-loop checkpoint: ${result.goal.id} -> ${result.goal.status}\n`);
+	return 0;
+}
+
+export async function steer(
+	repoRoot: string,
+	argv: readonly string[],
+	json: boolean,
+	scope?: UlwLoopScope,
+): Promise<number> {
+	const proposal = await parseSteeringProposal(argv);
+	const result = await steerUlwLoop(repoRoot, proposal, scope);
+	printSteerResult(result, json);
+	return result.accepted ? 0 : 1;
+}
+
+export async function addGoal(
+	repoRoot: string,
+	argv: readonly string[],
+	json: boolean,
+	scope?: UlwLoopScope,
+): Promise<number> {
+	const result = await addUlwLoopGoal(
+		repoRoot,
+		{ title: required(argv, "--title"), objective: required(argv, "--objective") },
+		scope,
+	);
+	if (json) printJson({ ok: true, plan: result.plan, goal: result.goal, summary: summarizeUlwLoopPlan(result.plan) });
+	else {
+		process.stdout.write(`ulw-loop added goal: ${result.goal.id}\n`);
+		printStatus(result.plan);
+	}
+	return 0;
+}
+
+export async function criteria(
+	repoRoot: string,
+	argv: readonly string[],
+	json: boolean,
+	scope?: UlwLoopScope,
+): Promise<number> {
+	const goalId = required(argv, "--goal-id");
+	const goal = findGoal(await readUlwLoopPlan(repoRoot, scope), goalId);
+	if (json) printJson({ ok: true, goalId: goal.id, criteria: goal.successCriteria });
+	else {
+		process.stdout.write(`criteria for ${goal.id}:\n${goal.successCriteria.map(formatCriterionForCli).join("\n")}\n`);
+	}
+	return 0;
+}
+
+export async function captureEvidence(
+	repoRoot: string,
+	argv: readonly string[],
+	json: boolean,
+	scope?: UlwLoopScope,
+): Promise<number> {
+	const result = await recordEvidence(repoRoot, parseRecordEvidenceArgs(argv), scope);
+	if (json) printJson({ ok: true, ...result, summary: summarizeUlwLoopPlan(result.plan) });
+	else {
+		process.stdout.write(
+			`ulw-loop evidence recorded: ${result.goal.id}/${result.criterion.id} -> ${result.criterion.status}\n`,
+		);
+	}
+	return 0;
+}
+
+export async function reviewBlockers(
+	repoRoot: string,
+	argv: readonly string[],
+	json: boolean,
+	scope?: UlwLoopScope,
+): Promise<number> {
+	const codexGoalJson = await parseCodexGoalJson(required(argv, "--codex-goal-json"));
+	if (codexGoalJson === undefined) {
+		throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
+	}
+	const result = await recordFinalReviewBlockers(
+		repoRoot,
+		{
+			goalId: required(argv, "--goal-id"),
+			title: required(argv, "--title"),
+			objective: required(argv, "--objective"),
+			evidence: required(argv, "--evidence"),
+			codexGoalJson,
+		},
+		scope,
+	);
+	if (json) {
+		printJson({
+			ok: true,
+			plan: result.plan,
+			blockedGoal: result.blockedGoal,
+			goal: result.newGoal,
+			ledgerEntries: result.ledgerEntries,
+			summary: summarizeUlwLoopPlan(result.plan),
+		});
+	} else {
+		process.stdout.write(
+			`ulw-loop final review blockers recorded: ${result.blockedGoal.id} -> review_blocked; added ${result.newGoal.id}\n`,
+		);
+	}
+	return 0;
+}
+
+function formatCriterionForCli(criterion: UlwLoopItem["successCriteria"][number]): string {
+	const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
+	return `- ${criterion.id} [${criterion.status}] [${marker}] (${criterion.userModel}) ${criterion.scenario} evidence: ${criterion.capturedEvidence ?? "pending"}`;
+}
+
+function required(argv: readonly string[], flag: string): string {
+	const value = readValue(argv, flag)?.trim();
+	if (value) return value;
+	throw new UlwLoopError(`Missing ${flag}.`, "ULW_LOOP_ARGUMENT_MISSING", { details: { flag } });
+}
+
+function checkpointStatus(value: string): CheckpointStatus {
+	if (value === "complete" || value === "failed" || value === "blocked") return value;
+	throw new UlwLoopError(
+		"Missing or invalid --status; expected complete, failed, or blocked.",
+		"ULW_LOOP_STATUS_INVALID",
+		{ details: { status: value } },
+	);
+}
+
+function findGoal(plan: { readonly goals: readonly UlwLoopItem[] }, goalId: string): UlwLoopItem {
+	const goal = plan.goals.find((candidate) => candidate.id === goalId);
+	if (goal !== undefined) return goal;
+	throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
+}

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

@@ -1,4 +1,9 @@
-import { codexGoalMode, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
+import {
+	codexGoalMode,
+	expectedCodexObjective,
+	isEssentialCriterion,
+	isFinalRunCompletionCandidate,
+} from "./goal-status.js";
 import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
 
 export interface CodexCreateGoalPayload {
@@ -70,7 +75,7 @@ function modeConstraintLines(mode: UlwLoopCodexGoalMode, isFinal: boolean): read
 		"- If a different active or incomplete Codex goal exists, finish/checkpoint that goal before starting this ulw-loop.",
 		isFinal
 			? "- This is the final story; update_goal is allowed only after the mandatory quality gate passes."
-			: "- This is not the final story: do not call update_goal yet; the aggregate Codex goal must remain active while later OMO stories remain.",
+			: "- This is not the final story: do not call update_goal mid-aggregate; checkpoint this OMO ledger story and continue the remaining stories. update_goal is reserved for the final story after the mandatory quality gate passes.",
 	];
 }
 
@@ -94,23 +99,27 @@ function successCriteriaLines(criteria: readonly UlwLoopSuccessCriterion[]): rea
 
 function formatCriterionLine(criterion: UlwLoopSuccessCriterion): string {
 	const remainingWork = criterion.status === "pending" ? " remaining work:" : "";
-	return `-${remainingWork} [${criterion.id}] (${criterion.userModel}) ${criterion.scenario} — expect: ${criterion.expectedEvidence} — status: ${criterion.status}`;
+	const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
+	return `-${remainingWork} [${criterion.id}] [${marker}] (${criterion.userModel}) ${criterion.scenario} — expect: ${criterion.expectedEvidence} — status: ${criterion.status}`;
 }
 
 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 reviewer/manual-QA/gate-review quality 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>"`;
+	const checkpointCommand = `omo ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<targeted verification/manualQa/gateReview 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 the code review (multi_agent_v1.spawn_agent(agent_type=\"codex-ultrawork-reviewer\", fork_context=false, ...); 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:",
+		"- Run targeted verification for changed behavior.",
+		"- Confirm every manualQa artifact path exists and has non-zero size.",
+		"- Spawn final reviewers with fork_context=false: lazycodex-code-reviewer, lazycodex-qa-executor, and lazycodex-gate-reviewer. Include the original brief, goal objectives, desired user-visible outcome, diff, and evidence.",
+		"- Require clean codeReview, manualQa, gateReview, iteration, and criteriaCoverage. criteriaCoverage must summarize originalIntent, desiredOutcome, and userOutcomeReview; counts alone are not approval.",
+		"- If any reviewer is blocked/inconclusive or the quality gate is not clean, do not call update_goal. Record blocker work first:",
 		`  ${blockerCommand}`,
 		aggregate
-			? '- 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:',
+			? '- If the quality gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story:'
+			: '- If the quality gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint:',
 		`  ${checkpointCommand}`,
 	]);
 }

package/packages/omo-codex/plugin/components/ulw-loop/src/domain-types.ts

@@ -14,6 +14,7 @@ export interface UlwLoopSuccessCriterion {
 	readonly scenario: string;
 	readonly userModel: UlwLoopSuccessCriterionUserModel;
 	readonly expectedEvidence: string;
+	readonly essential?: boolean;
 	capturedEvidence: string | null;
 	status: UlwLoopCriterionStatus;
 	capturedAt?: string;
@@ -69,10 +70,72 @@ export interface UlwLoopPlan {
 	goals: UlwLoopItem[];
 }
 
+export type UlwLoopManualQaSurface = "cli" | "http" | "tmux" | "browser" | "gui" | "data";
+export type UlwLoopManualQaArtifactKind = "cli-transcript" | "log" | "screenshot" | "image" | "http-dump" | "data-diff";
+
+export interface UlwLoopManualQaArtifactRef {
+	readonly id: string;
+	readonly kind: UlwLoopManualQaArtifactKind;
+	readonly description: string;
+	readonly path: string;
+}
+
+export interface UlwLoopManualQaSurfaceEvidence {
+	readonly id: string;
+	readonly criterionRef: string;
+	readonly surface: UlwLoopManualQaSurface;
+	readonly invocation: string;
+	readonly verdict: "passed";
+	readonly artifactRefs: readonly string[];
+}
+
+export interface UlwLoopManualQaAdversarialCase {
+	readonly id: string;
+	readonly criterionRef: string;
+	readonly scenario: string;
+	readonly expectedBehavior: string;
+	readonly verdict: "passed";
+	readonly artifactRefs: readonly string[];
+}
+
 export interface UlwLoopQualityGate {
-	aiSlopCleaner: { status: "passed"; evidence: string };
-	verification: { status: "passed"; commands: string[]; evidence: string };
-	codeReview: { recommendation: "APPROVE"; architectStatus: "CLEAR"; evidence: string };
+	readonly codeReview: {
+		readonly by: string;
+		readonly recommendation: "APPROVE";
+		readonly codeQualityStatus: "CLEAR";
+		readonly reportPath: string;
+		readonly evidence: string;
+		readonly blockers: readonly [];
+	};
+	readonly manualQa: {
+		readonly by: string;
+		readonly status: "passed";
+		readonly evidence: string;
+		readonly surfaceEvidence: readonly UlwLoopManualQaSurfaceEvidence[];
+		readonly adversarialCases: readonly UlwLoopManualQaAdversarialCase[];
+		readonly artifactRefs: readonly UlwLoopManualQaArtifactRef[];
+	};
+	readonly gateReview: {
+		readonly by: string;
+		readonly recommendation: "APPROVE";
+		readonly reportPath: string;
+		readonly evidence: string;
+		readonly blockers: readonly [];
+	};
+	readonly iteration: {
+		readonly fullRerun: true;
+		readonly status: "passed";
+		readonly rerunCommands: readonly string[];
+		readonly evidence: string;
+	};
+	readonly criteriaCoverage: {
+		readonly totalCriteria: number;
+		readonly passCount: number;
+		readonly originalIntent: string;
+		readonly desiredOutcome: string;
+		readonly userOutcomeReview: string;
+		readonly adversarialClassesCovered: readonly string[];
+	};
 }
 
 export interface UlwLoopLedgerEntry {
@@ -86,7 +149,7 @@ export interface UlwLoopLedgerEntry {
 	codexGoal?: unknown;
 	evidence?: string;
 	capturedEvidence?: string;
-	qualityGate?: UlwLoopQualityGate;
+	qualityGate?: unknown;
 	steering?: UlwLoopSteeringAudit;
 	before?: unknown;
 	after?: unknown;

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

@@ -1,14 +1,21 @@
-// biome-ignore-all format: keep this module under the mandated pure LOC budget.
-import { hasAllCriteriaPass } from "./goal-status.js";
+import { essentialCriteriaOf, hasAllCriteriaPass, hasEssentialCriteriaPass } from "./goal-status.js";
 import type { UlwLoopScope } from "./paths.js";
 import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
 import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
 import { iso, UlwLoopError } from "./types.js";
 
 type EvidenceStatus = "pass" | "fail" | "blocked";
-type RecordEvidenceArgs = { readonly goalId: string; readonly criterionId: string; readonly status: EvidenceStatus; readonly evidence: string; readonly notes?: string };
+type RecordEvidenceArgs = {
+	readonly goalId: string;
+	readonly criterionId: string;
+	readonly status: EvidenceStatus;
+	readonly evidence: string;
+	readonly notes?: string;
+};
 
-function ulwLoopFail(message: string, code: string, details: Record<string, unknown>): never { throw new UlwLoopError(message, code, { details }); }
+function ulwLoopFail(message: string, code: string, details: Record<string, unknown>): never {
+	throw new UlwLoopError(message, code, { details });
+}
 
 function ledgerKind(status: EvidenceStatus): UlwLoopLedgerEntry["kind"] {
 	switch (status) {
@@ -30,12 +37,30 @@ function findGoal(plan: UlwLoopPlan, goalId: string): UlwLoopItem {
 
 function findCriterion(goal: UlwLoopItem, criterionId: string): UlwLoopSuccessCriterion {
 	const criterion = goal.successCriteria.find((candidate) => candidate.id === criterionId);
-	return criterion ?? ulwLoopFail(`Success criterion not found: ${criterionId}.`, "ULW_LOOP_CRITERION_NOT_FOUND", { goalId: goal.id, criterionId });
+	return (
+		criterion ??
+		ulwLoopFail(`Success criterion not found: ${criterionId}.`, "ULW_LOOP_CRITERION_NOT_FOUND", {
+			goalId: goal.id,
+			criterionId,
+		})
+	);
 }
 
-function nonEmptyEvidence(evidence: string): string { const trimmed = evidence.trim(); return trimmed || ulwLoopFail("Evidence must be a non-empty string.", "ULW_LOOP_EVIDENCE_REQUIRED", {}); }
+function nonEmptyEvidence(evidence: string): string {
+	const trimmed = evidence.trim();
+	return trimmed || ulwLoopFail("Evidence must be a non-empty string.", "ULW_LOOP_EVIDENCE_REQUIRED", {});
+}
 
-export async function recordEvidence(repoRoot: string, args: RecordEvidenceArgs, scope?: UlwLoopScope): Promise<{ plan: UlwLoopPlan; goal: UlwLoopItem; criterion: UlwLoopSuccessCriterion; ledgerEntry: UlwLoopLedgerEntry }> {
+export async function recordEvidence(
+	repoRoot: string,
+	args: RecordEvidenceArgs,
+	scope?: UlwLoopScope,
+): Promise<{
+	plan: UlwLoopPlan;
+	goal: UlwLoopItem;
+	criterion: UlwLoopSuccessCriterion;
+	ledgerEntry: UlwLoopLedgerEntry;
+}> {
 	return withUlwLoopMutationLock(repoRoot, scope, async () => {
 		const plan = await readUlwLoopPlan(repoRoot, scope);
 		const goal = findGoal(plan, args.goalId);
@@ -67,12 +92,21 @@ export async function recordEvidence(repoRoot: string, args: RecordEvidenceArgs,
 	});
 }
 
-export async function markCriteriaPendingResetForGoal(repoRoot: string, goalId: string, scope?: UlwLoopScope): Promise<{ plan: UlwLoopPlan; resetCount: number }> {
+export async function markCriteriaPendingResetForGoal(
+	repoRoot: string,
+	goalId: string,
+	scope?: UlwLoopScope,
+): Promise<{ plan: UlwLoopPlan; resetCount: number }> {
 	return withUlwLoopMutationLock(repoRoot, scope, async () => {
 		const plan = await readUlwLoopPlan(repoRoot, scope);
 		const goal = findGoal(plan, goalId);
 		const now = iso();
-		const before = goal.successCriteria.map((criterion) => ({ id: criterion.id, status: criterion.status, capturedEvidence: criterion.capturedEvidence, capturedAt: criterion.capturedAt ?? null }));
+		const before = goal.successCriteria.map((criterion) => ({
+			id: criterion.id,
+			status: criterion.status,
+			capturedEvidence: criterion.capturedEvidence,
+			capturedAt: criterion.capturedAt ?? null,
+		}));
 		for (const criterion of goal.successCriteria) {
 			criterion.status = "pending";
 			criterion.capturedEvidence = null;
@@ -82,12 +116,30 @@ export async function markCriteriaPendingResetForGoal(repoRoot: string, goalId:
 		goal.updatedAt = now;
 		plan.updatedAt = now;
 		await writePlan(repoRoot, plan, scope);
-		await appendLedger(repoRoot, { at: now, kind: "criteria_revised", goalId, message: `Reset ${goal.successCriteria.length} criteria to pending.`, before, after: { resetCount: goal.successCriteria.length } }, scope);
+		await appendLedger(
+			repoRoot,
+			{
+				at: now,
+				kind: "criteria_revised",
+				goalId,
+				message: `Reset ${goal.successCriteria.length} criteria to pending.`,
+				before,
+				after: { resetCount: goal.successCriteria.length },
+			},
+			scope,
+		);
 		return { plan, resetCount: goal.successCriteria.length };
 	});
 }
 
-export function criteriaSummary(plan: UlwLoopPlan): { totalCriteria: number; passCount: number; pendingCount: number; failCount: number; blockedCount: number; goalsWithUnresolvedCriteria: string[] } {
+export function criteriaSummary(plan: UlwLoopPlan): {
+	totalCriteria: number;
+	passCount: number;
+	pendingCount: number;
+	failCount: number;
+	blockedCount: number;
+	goalsWithUnresolvedCriteria: string[];
+} {
 	let totalCriteria = 0;
 	let passCount = 0;
 	let pendingCount = 0;
@@ -100,11 +152,22 @@ export function criteriaSummary(plan: UlwLoopPlan): { totalCriteria: number; pas
 			totalCriteria += 1;
 			if (criterion.status !== "pass") unresolved = true;
 			switch (criterion.status) {
-				case "pass": passCount += 1; break;
-				case "pending": pendingCount += 1; break;
-				case "fail": failCount += 1; break;
-				case "blocked": blockedCount += 1; break;
-				default: ulwLoopFail("Invalid criterion status.", "ULW_LOOP_CRITERION_STATUS_INVALID", { status: criterion.status });
+				case "pass":
+					passCount += 1;
+					break;
+				case "pending":
+					pendingCount += 1;
+					break;
+				case "fail":
+					failCount += 1;
+					break;
+				case "blocked":
+					blockedCount += 1;
+					break;
+				default:
+					ulwLoopFail("Invalid criterion status.", "ULW_LOOP_CRITERION_STATUS_INVALID", {
+						status: criterion.status,
+					});
 			}
 		}
 		if (unresolved) goalsWithUnresolvedCriteria.push(goal.id);
@@ -112,11 +175,54 @@ export function criteriaSummary(plan: UlwLoopPlan): { totalCriteria: number; pas
 	return { totalCriteria, passCount, pendingCount, failCount, blockedCount, goalsWithUnresolvedCriteria };
 }
 
-export function unresolvedCriteriaOf(goal: UlwLoopItem): UlwLoopSuccessCriterion[] { return goal.successCriteria.filter((criterion) => criterion.status !== "pass"); }
+export function unresolvedCriteriaOf(goal: UlwLoopItem): UlwLoopSuccessCriterion[] {
+	return goal.successCriteria.filter((criterion) => criterion.status !== "pass");
+}
+
+export function unresolvedEssentialCriteriaOf(goal: UlwLoopItem): readonly UlwLoopSuccessCriterion[] {
+	const essentialCriteria = new Set(essentialCriteriaOf(goal).map((criterion) => criterion.id));
+	return goal.successCriteria.filter(
+		(criterion) => essentialCriteria.has(criterion.id) && criterion.status !== "pass",
+	);
+}
 
 export function requireAllCriteriaPass(goal: UlwLoopItem): void {
 	if (hasAllCriteriaPass(goal)) return;
 	throw new UlwLoopError(`Goal ${goal.id} has unresolved success criteria.`, "ulw_loop_criteria_not_all_pass", {
-		details: { goalId: goal.id, unresolved: unresolvedCriteriaOf(goal).map((criterion) => ({ id: criterion.id, status: criterion.status })) },
+		details: {
+			goalId: goal.id,
+			unresolved: unresolvedCriteriaOf(goal).map((criterion) => ({ id: criterion.id, status: criterion.status })),
+		},
 	});
 }
+
+export function requireAllPlanCriteriaPass(plan: UlwLoopPlan): void {
+	const unresolved = plan.goals.flatMap((goal) =>
+		unresolvedCriteriaOf(goal).map((criterion) => ({
+			goalId: goal.id,
+			id: criterion.id,
+			status: criterion.status,
+		})),
+	);
+	if (unresolved.length === 0) return;
+	throw new UlwLoopError("Ulw-loop aggregate has unresolved success criteria.", "ulw_loop_criteria_not_all_pass", {
+		details: { unresolved },
+	});
+}
+
+export function requireEssentialCriteriaPass(goal: UlwLoopItem): void {
+	if (hasEssentialCriteriaPass(goal)) return;
+	throw new UlwLoopError(
+		`Goal ${goal.id} has unresolved essential success criteria.`,
+		"ulw_loop_criteria_not_all_pass",
+		{
+			details: {
+				goalId: goal.id,
+				unresolved: unresolvedEssentialCriteriaOf(goal).map((criterion) => ({
+					id: criterion.id,
+					status: criterion.status,
+				})),
+			},
+		},
+	);
+}

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

@@ -83,6 +83,22 @@ export function hasAllCriteriaPass(goal: UlwLoopItem): boolean {
 	return goal.successCriteria.length > 0 && goal.successCriteria.every((criterion) => criterion.status === "pass");
 }
 
+export function isEssentialCriterion(criterion: UlwLoopSuccessCriterion): boolean {
+	return criterion.essential ?? true;
+}
+
+export function essentialCriteriaOf(goal: UlwLoopItem): readonly UlwLoopSuccessCriterion[] {
+	const explicit = goal.successCriteria.filter(isEssentialCriterion);
+	if (explicit.length > 0) return explicit;
+	const happy = goal.successCriteria.find((criterion) => criterion.userModel === "happy");
+	return happy === undefined ? [] : [happy];
+}
+
+export function hasEssentialCriteriaPass(goal: UlwLoopItem): boolean {
+	const criteria = essentialCriteriaOf(goal);
+	return criteria.length > 0 && criteria.every((criterion) => criterion.status === "pass");
+}
+
 export function firstUnresolvedCriterion(goal: UlwLoopItem): UlwLoopSuccessCriterion | undefined {
 	return goal.successCriteria.find((criterion) => criterion.status !== "pass");
 }