@code-yeongyu/lazycodex 0.1.1

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

@@ -0,0 +1,129 @@
+import { codexGoalMode, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
+import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
+
+export interface CodexCreateGoalPayload {
+	readonly objective: string;
+	readonly status: "active";
+}
+
+export interface UlwLoopGoalInstruction {
+	readonly text: string;
+	readonly json: CodexCreateGoalPayload;
+}
+
+export function buildCodexGoalInstruction(args: {
+	readonly plan: UlwLoopPlan;
+	readonly goal: UlwLoopItem;
+	readonly isFinal?: boolean;
+}): UlwLoopGoalInstruction {
+	const mode = codexGoalMode(args.plan);
+	const createGoal = buildCreateGoalPayload(args.plan, args.goal);
+	const isFinal = args.isFinal ?? isFinalRunCompletionCandidate(args.plan, args.goal);
+	return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal), json: createGoal };
+}
+
+function buildCreateGoalPayload(plan: UlwLoopPlan, goal: UlwLoopItem): CodexCreateGoalPayload {
+	return { objective: expectedCodexObjective(plan, goal), status: "active" };
+}
+
+function buildText(
+	mode: UlwLoopCodexGoalMode,
+	plan: UlwLoopPlan,
+	goal: UlwLoopItem,
+	createGoal: CodexCreateGoalPayload,
+	isFinal: boolean,
+): string {
+	return joinLines([
+		mode === "aggregate" ? "UlwLoop aggregate-goal handoff" : "UlwLoop active-goal handoff",
+		`Mode: ${mode}`,
+		`Plan: ${plan.goalsPath}`,
+		`Ledger: ${plan.ledgerPath}`,
+		`Goal: ${goal.id} — ${goal.title}`,
+		"",
+		...activeGoalLines(goal),
+		"",
+		...successCriteriaLines(goal.successCriteria),
+		"",
+		"Codex goal integration constraints:",
+		"- Use the create_goal payload exactly as rendered: objective and status only.",
+		"- Goals are unlimited. Do not add numeric limits.",
+		...modeConstraintLines(mode, isFinal),
+		finalSection(plan, goal, isFinal, mode === "aggregate"),
+		...checkpointLines(plan, mode),
+		"",
+		"create_goal payload:",
+		JSON.stringify(createGoal, null, 2),
+	]);
+}
+
+function modeConstraintLines(mode: UlwLoopCodexGoalMode, isFinal: boolean): readonly string[] {
+	if (mode === "per_story") {
+		return [
+			"- First call get_goal. If no active goal exists, call create_goal with the payload below.",
+			"- If a different active Codex goal exists, finish/checkpoint that goal before starting this ulw-loop.",
+			"- Work only this goal until its completion audit passes.",
+		];
+	}
+	return [
+		"- Codex goal = the whole omo ulw-loop run; OMO G001/G002/etc. = ledger stories.",
+		"- First call get_goal. If no active goal exists, call create_goal with the aggregate payload below.",
+		"- If get_goal reports the same aggregate objective as active, continue this OMO story without creating a new Codex goal.",
+		"- 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.",
+	];
+}
+
+function checkpointLines(plan: UlwLoopPlan, mode: UlwLoopCodexGoalMode): readonly string[] {
+	const failureLine = `- If blocked or failed, checkpoint with --status failed and the failure evidence; rerun complete-goals${sessionOption(plan)} --retry-failed to resume.`;
+	if (mode === "per_story") return [failureLine];
+	return [
+		"- Checkpoint this OMO story with a fresh get_goal snapshot whose objective matches the aggregate payload.",
+		failureLine,
+	];
+}
+
+function activeGoalLines(goal: UlwLoopItem): readonly string[] {
+	return ["Active goal:", `- id: ${goal.id}`, `- title: ${goal.title}`, `- objective: ${goal.objective}`];
+}
+
+function successCriteriaLines(criteria: readonly UlwLoopSuccessCriterion[]): readonly string[] {
+	if (criteria.length === 0) return ["Success criteria:", "- No success criteria recorded for this goal."];
+	return ["Success criteria:", ...criteria.map(formatCriterionLine)];
+}
+
+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}`;
+}
+
+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.";
+	const option = sessionOption(plan);
+	const blockerCommand = `omo ulw-loop record-review-blockers${option} --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`;
+	const checkpointCommand = `omo ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`;
+	return joinLines([
+		"Final story — run mandatory quality gate before update_goal:",
+		"- Run ai-slop-cleaner on changed files even when it is a no-op, rerun verification, then run $code-review.",
+		"- If final $code-review is not APPROVE with architect status CLEAR, do not call update_goal. Record blocker work first:",
+		`  ${blockerCommand}`,
+		aggregate
+			? '- If final $code-review is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story:'
+			: '- If final $code-review is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint:',
+		`  ${checkpointCommand}`,
+	]);
+}
+
+function sessionOption(plan: UlwLoopPlan): string {
+	const prefix = ".omo/ulw-loop/";
+	const suffix = "/goals.json";
+	if (!plan.goalsPath.startsWith(prefix) || !plan.goalsPath.endsWith(suffix)) return "";
+	const sessionId = plan.goalsPath.slice(prefix.length, -suffix.length);
+	return sessionId.length === 0 ? "" : ` --session-id ${sessionId}`;
+}
+
+function joinLines(lines: readonly string[]): string {
+	return lines.join("\n");
+}

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

@@ -0,0 +1,139 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export type CodexGoalSnapshotStatus = "active" | "complete" | "cancelled" | "failed" | "unknown";
+
+export interface CodexGoalSnapshot {
+	available: boolean;
+	objective?: string;
+	status?: CodexGoalSnapshotStatus;
+	raw: unknown;
+}
+
+export interface CodexGoalReconciliation {
+	ok: boolean;
+	snapshot: CodexGoalSnapshot;
+	warnings: string[];
+	errors: string[];
+}
+
+export interface ReconcileCodexGoalOptions {
+	expectedObjective: string;
+	acceptedObjectives?: readonly string[];
+	allowedStatuses?: readonly CodexGoalSnapshotStatus[];
+	requireSnapshot?: boolean;
+	requireComplete?: boolean;
+}
+
+export class CodexGoalSnapshotError extends Error {}
+function safeObject(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function safeString(value: unknown): string {
+	return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeStatus(value: unknown): CodexGoalSnapshotStatus {
+	const status = safeString(value).toLowerCase();
+	if (status === "complete" || status === "completed" || status === "done") return "complete";
+	if (status === "cancelled" || status === "canceled") return "cancelled";
+	if (status === "failed" || status === "failure") return "failed";
+	if (status === "active" || status === "in_progress" || status === "pending" || status === "running") return "active";
+	return "unknown";
+}
+
+function normalizeObjective(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}
+
+export function parseCodexGoalSnapshot(value: unknown): CodexGoalSnapshot {
+	const root = safeObject(value);
+	const goalValue = Object.hasOwn(root, "goal") ? root["goal"] : value;
+	if (goalValue === null || goalValue === undefined || goalValue === false) {
+		return { available: false, raw: value };
+	}
+
+	const goal = safeObject(goalValue);
+	const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? root["objective"]);
+	const status = normalizeStatus(goal["status"] ?? root["status"]);
+
+	return {
+		available: Boolean(objective || status !== "unknown"),
+		...(objective ? { objective } : {}),
+		status,
+		raw: value,
+	};
+}
+
+export async function readCodexGoalSnapshotInput(
+	raw: string | undefined,
+	cwd = process.cwd(),
+): Promise<CodexGoalSnapshot | null> {
+	if (!raw?.trim()) return null;
+	const trimmed = raw.trim();
+	try {
+		return parseCodexGoalSnapshot(JSON.parse(trimmed));
+	} catch {
+		const path = resolve(cwd, trimmed);
+		if (!existsSync(path)) {
+			throw new CodexGoalSnapshotError(`Codex goal snapshot is neither valid JSON nor a readable path: ${trimmed}`);
+		}
+		try {
+			return parseCodexGoalSnapshot(JSON.parse(await readFile(path, "utf-8")));
+		} catch (error) {
+			throw new CodexGoalSnapshotError(
+				`Codex goal snapshot path does not contain valid JSON: ${trimmed}${error instanceof Error ? ` (${error.message})` : ""}`,
+			);
+		}
+	}
+}
+
+export function reconcileCodexGoalSnapshot(
+	snapshot: CodexGoalSnapshot | null | undefined,
+	options: ReconcileCodexGoalOptions,
+): CodexGoalReconciliation {
+	const effectiveSnapshot = snapshot ?? { available: false, raw: null };
+	const errors: string[] = [];
+	const warnings: string[] = [];
+
+	if (!effectiveSnapshot.available) {
+		const message =
+			"Codex goal snapshot is absent or reports no active goal; call get_goal and pass its JSON with --codex-goal-json.";
+		if (options.requireSnapshot) errors.push(message);
+		else warnings.push(message);
+		return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
+	}
+
+	const expected = normalizeObjective(options.expectedObjective);
+	const accepted = new Set(
+		[expected, ...(options.acceptedObjectives ?? []).map((objective) => normalizeObjective(objective))].filter(
+			Boolean,
+		),
+	);
+	const actual = normalizeObjective(effectiveSnapshot.objective ?? "");
+	if (!actual) {
+		errors.push("Codex goal snapshot is missing objective text.");
+	} else if (!accepted.has(actual)) {
+		errors.push(`Codex goal objective mismatch: expected "${expected}", got "${actual}".`);
+	}
+
+	const allowed = options.allowedStatuses ?? (options.requireComplete ? ["complete"] : ["active", "complete"]);
+	const actualStatus = effectiveSnapshot.status ?? "unknown";
+	if (!allowed.includes(actualStatus)) {
+		errors.push(`Codex goal status mismatch: expected ${allowed.join(" or ")}, got ${actualStatus}.`);
+	}
+	if (options.requireComplete && actualStatus !== "complete") {
+		errors.push(
+			'Codex goal is not complete; call update_goal({status: "complete"}) only after the objective is actually complete, then pass the fresh get_goal JSON.',
+		);
+	}
+
+	return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
+}
+
+export function formatCodexGoalReconciliation(reconciliation: CodexGoalReconciliation): string {
+	const parts = [...reconciliation.errors, ...reconciliation.warnings];
+	return parts.join(" ");
+}

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

@@ -0,0 +1,177 @@
+import type { UlwLoopScope } from "./paths.js";
+import { parseUlwLoopSteeringDirective, steerUlwLoop } from "./steering.js";
+
+export interface UserPromptSubmitPayload {
+	readonly cwd: string;
+	readonly hook_event_name: "UserPromptSubmit";
+	readonly model?: string;
+	readonly permission_mode?: string;
+	readonly prompt: string;
+	readonly session_id: string;
+	readonly transcript_path?: string;
+	readonly turn_id?: string;
+}
+
+export interface PreToolUsePayload {
+	readonly cwd: string;
+	readonly hook_event_name: "PreToolUse";
+	readonly model: string;
+	readonly permission_mode: string;
+	readonly session_id: string;
+	readonly tool_input: unknown;
+	readonly tool_name: string;
+	readonly tool_use_id: string;
+	readonly transcript_path: string | null;
+	readonly turn_id: string;
+}
+
+interface PreToolUseHookOutput {
+	readonly hookSpecificOutput: {
+		readonly hookEventName: "PreToolUse";
+		readonly permissionDecision: "deny";
+		readonly permissionDecisionReason: string;
+		readonly additionalContext: string;
+	};
+}
+
+const CREATE_GOAL_TOOL_NAME = "create_goal";
+const GOAL_BUDGET_WARNING =
+	"Do not set token_budget on create_goal. Omit the budget field so the goal stays unlimited; ultrawork and ulw-loop runs must always use unlimited goals.";
+
+export function parseUserPromptSubmitPayload(raw: string): UserPromptSubmitPayload | null {
+	if (raw.trim().length === 0) return null;
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		return isUserPromptSubmitPayload(parsed) ? parsed : null;
+	} catch (error) {
+		if (error instanceof SyntaxError) return null;
+		return null;
+	}
+}
+
+export function parsePreToolUsePayload(raw: string): PreToolUsePayload | null {
+	if (raw.trim().length === 0) return null;
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		return isPreToolUsePayload(parsed) ? parsed : null;
+	} catch (error) {
+		if (error instanceof SyntaxError) return null;
+		return null;
+	}
+}
+
+export async function applyUserPromptUlwLoopSteering(payload: UserPromptSubmitPayload): Promise<string> {
+	try {
+		if (payload.hook_event_name !== "UserPromptSubmit") return "";
+		const proposal = parseUlwLoopSteeringDirective(payload.prompt);
+		if (proposal === null) return "";
+		const result = await steerUlwLoop(payload.cwd, proposal, payloadScope(payload));
+		if (!result.accepted) return "";
+		return JSON.stringify({
+			status: "accepted",
+			kind: result.audit.kind,
+			source: result.audit.source,
+			deduped: result.deduped,
+		});
+	} catch (error) {
+		if (error instanceof Error) return "";
+		return "";
+	}
+}
+
+function payloadScope(payload: UserPromptSubmitPayload): UlwLoopScope {
+	return { sessionId: payload.session_id };
+}
+
+export function applyPreToolUseGoalBudgetGuard(payload: PreToolUsePayload): string {
+	if (payload.hook_event_name !== "PreToolUse") return "";
+	if (payload.tool_name !== CREATE_GOAL_TOOL_NAME) return "";
+	if (!hasGoalBudgetInput(payload.tool_input)) return "";
+	const output: PreToolUseHookOutput = {
+		hookSpecificOutput: {
+			hookEventName: "PreToolUse",
+			permissionDecision: "deny",
+			permissionDecisionReason: GOAL_BUDGET_WARNING,
+			additionalContext: GOAL_BUDGET_WARNING,
+		},
+	};
+	return `${JSON.stringify(output)}\n`;
+}
+
+export async function runUlwLoopHookCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void> {
+	try {
+		const payload = parseUserPromptSubmitPayload(await readAll(stdin));
+		if (payload === null) return;
+		const output = await applyUserPromptUlwLoopSteering(payload);
+		if (output.length > 0) stdout.write(output);
+	} catch (error) {
+		if (error instanceof Error) return;
+		return;
+	}
+}
+
+export async function runPreToolUseGoalBudgetGuardCli(
+	stdin: NodeJS.ReadableStream,
+	stdout: NodeJS.WritableStream,
+): Promise<void> {
+	try {
+		const payload = parsePreToolUsePayload(await readAll(stdin));
+		if (payload === null) return;
+		const output = applyPreToolUseGoalBudgetGuard(payload);
+		if (output.length > 0) stdout.write(output);
+	} catch (error) {
+		if (error instanceof Error) return;
+		return;
+	}
+}
+
+function isUserPromptSubmitPayload(value: unknown): value is UserPromptSubmitPayload {
+	if (!isRecord(value)) return false;
+	return (
+		value["hook_event_name"] === "UserPromptSubmit" &&
+		typeof value["cwd"] === "string" &&
+		typeof value["prompt"] === "string" &&
+		typeof value["session_id"] === "string" &&
+		["model", "permission_mode", "transcript_path", "turn_id"].every((key) => optionalString(value[key]))
+	);
+}
+
+function isPreToolUsePayload(value: unknown): value is PreToolUsePayload {
+	if (!isRecord(value)) return false;
+	return (
+		value["hook_event_name"] === "PreToolUse" &&
+		typeof value["cwd"] === "string" &&
+		typeof value["model"] === "string" &&
+		typeof value["permission_mode"] === "string" &&
+		typeof value["session_id"] === "string" &&
+		typeof value["tool_name"] === "string" &&
+		typeof value["tool_use_id"] === "string" &&
+		(value["transcript_path"] === null || typeof value["transcript_path"] === "string") &&
+		typeof value["turn_id"] === "string" &&
+		Object.hasOwn(value, "tool_input")
+	);
+}
+
+function hasGoalBudgetInput(value: unknown): boolean {
+	return isRecord(value) && (Object.hasOwn(value, "token_budget") || Object.hasOwn(value, "tokenBudget"));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function optionalString(value: unknown): boolean {
+	return value === undefined || typeof value === "string";
+}
+
+function readAll(stdin: NodeJS.ReadableStream): Promise<string> {
+	return new Promise((resolve, reject) => {
+		let data = "";
+		stdin.setEncoding("utf8");
+		stdin.on("data", (chunk: unknown) => {
+			data += chunk instanceof Buffer ? chunk.toString() : String(chunk);
+		});
+		stdin.once("error", reject);
+		stdin.once("end", () => resolve(data));
+	});
+}

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

@@ -0,0 +1,122 @@
+// biome-ignore-all format: keep this module under the mandated pure LOC budget.
+import { hasAllCriteriaPass } 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 };
+
+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) {
+		case "pass":
+			return "evidence_captured";
+		case "fail":
+			return "criterion_failed";
+		case "blocked":
+			return "criterion_blocked";
+		default:
+			return ulwLoopFail("Invalid criterion status.", "ULW_LOOP_CRITERION_STATUS_INVALID", { status });
+	}
+}
+
+function findGoal(plan: UlwLoopPlan, goalId: string): UlwLoopItem {
+	const goal = plan.goals.find((candidate) => candidate.id === goalId);
+	return goal ?? ulwLoopFail(`UlwLoop goal not found: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { goalId });
+}
+
+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 });
+}
+
+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 }> {
+	return withUlwLoopMutationLock(repoRoot, scope, async () => {
+		const plan = await readUlwLoopPlan(repoRoot, scope);
+		const goal = findGoal(plan, args.goalId);
+		const criterion = findCriterion(goal, args.criterionId);
+		const evidence = nonEmptyEvidence(args.evidence);
+		const kind = ledgerKind(args.status);
+		const prevStatus = criterion.status;
+		const capturedAt = iso();
+		criterion.status = args.status;
+		criterion.capturedEvidence = evidence;
+		criterion.capturedAt = capturedAt;
+		if (args.notes !== undefined) criterion.notes = args.notes;
+		goal.updatedAt = capturedAt;
+		plan.updatedAt = capturedAt;
+		await writePlan(repoRoot, plan, scope);
+		const ledgerEntry: UlwLoopLedgerEntry = {
+			at: capturedAt,
+			kind,
+			goalId: goal.id,
+			criterionId: criterion.id,
+			criterionStatus: args.status,
+			evidence,
+			capturedEvidence: evidence,
+			before: { status: prevStatus },
+			after: { goalId: goal.id, criterionId: criterion.id, status: args.status, evidence, capturedAt, prevStatus },
+		};
+		await appendLedger(repoRoot, ledgerEntry, scope);
+		return { plan, goal, criterion, ledgerEntry };
+	});
+}
+
+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 }));
+		for (const criterion of goal.successCriteria) {
+			criterion.status = "pending";
+			criterion.capturedEvidence = null;
+			delete criterion.capturedAt;
+			delete criterion.notes;
+		}
+		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);
+		return { plan, resetCount: goal.successCriteria.length };
+	});
+}
+
+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;
+	let failCount = 0;
+	let blockedCount = 0;
+	const goalsWithUnresolvedCriteria: string[] = [];
+	for (const goal of plan.goals) {
+		let unresolved = false;
+		for (const criterion of goal.successCriteria) {
+			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 });
+			}
+		}
+		if (unresolved) goalsWithUnresolvedCriteria.push(goal.id);
+	}
+	return { totalCriteria, passCount, pendingCount, failCount, blockedCount, goalsWithUnresolvedCriteria };
+}
+
+export function unresolvedCriteriaOf(goal: UlwLoopItem): UlwLoopSuccessCriterion[] { return goal.successCriteria.filter((criterion) => 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 })) },
+	});
+}

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

@@ -0,0 +1,88 @@
+import { type UlwLoopScope, ulwLoopGoalsRelativePath, ulwLoopLedgerRelativePath } from "./paths.js";
+import type {
+	UlwLoopCodexGoalMode,
+	UlwLoopItem,
+	UlwLoopPlan,
+	UlwLoopStatus,
+	UlwLoopSuccessCriterion,
+} from "./types.js";
+
+export const ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE: string = aggregateCodexObjectiveForScope();
+
+export function aggregateCodexObjectiveForScope(scope?: UlwLoopScope): string {
+	return `Complete the durable ulw-loop plan in ${ulwLoopGoalsRelativePath(scope)}, including later accepted/appended stories, under the original brief constraints; use ${ulwLoopLedgerRelativePath(scope)} as the audit trail.`;
+}
+
+export function codexGoalMode(plan: UlwLoopPlan): UlwLoopCodexGoalMode {
+	return plan.codexGoalMode ?? "per_story";
+}
+
+function isResolvedStatus(status: UlwLoopStatus): boolean {
+	return status === "complete";
+}
+
+function isSupersededResolved(goal: UlwLoopItem, plan: UlwLoopPlan): boolean {
+	if (goal.steeringStatus !== "superseded") return false;
+	const replacements = goal.supersededBy ?? [];
+	if (replacements.length === 0) return false;
+	return replacements.every((id) => {
+		const replacement = plan.goals.find((candidate) => candidate.id === id);
+		return replacement !== undefined && isResolvedStatus(replacement.status);
+	});
+}
+
+function isCompletionBlocking(goal: UlwLoopItem, plan: UlwLoopPlan): boolean {
+	if (goal.steeringStatus === "superseded") return !isSupersededResolved(goal, plan);
+	if (goal.steeringStatus === "blocked") return true;
+	return !isResolvedStatus(goal.status);
+}
+
+function isCompletionBlockingForFinalCandidate(
+	candidate: UlwLoopItem,
+	finalCandidate: UlwLoopItem,
+	plan: UlwLoopPlan,
+): boolean {
+	if (candidate.id === finalCandidate.id) return false;
+	if (candidate.steeringStatus === "superseded") {
+		const replacements = candidate.supersededBy ?? [];
+		if (replacements.length === 0) return true;
+		return !replacements.every((id) => {
+			if (id === finalCandidate.id) return true;
+			const replacement = plan.goals.find((goal) => goal.id === id);
+			return replacement !== undefined && isResolvedStatus(replacement.status);
+		});
+	}
+	return isCompletionBlocking(candidate, plan);
+}
+
+export function isUlwLoopDone(plan: UlwLoopPlan): boolean {
+	if (plan.aggregateCompletion?.status === "complete") return true;
+	return plan.goals.every((goal) => !isCompletionBlocking(goal, plan));
+}
+
+export function isFinalRunCompletionCandidate(plan: UlwLoopPlan, goal: UlwLoopItem): boolean {
+	return (
+		isCompletionBlocking(goal, plan) &&
+		plan.goals.every((candidate) => !isCompletionBlockingForFinalCandidate(candidate, goal, plan))
+	);
+}
+
+export function aggregateCodexObjective(plan: UlwLoopPlan): string {
+	return plan.codexObjective ?? ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE;
+}
+
+export function expectedCodexObjective(plan: UlwLoopPlan, goal: UlwLoopItem): string {
+	return codexGoalMode(plan) === "aggregate" ? aggregateCodexObjective(plan) : goal.objective;
+}
+
+export function compatibleCodexObjectives(plan: UlwLoopPlan): readonly string[] {
+	return [aggregateCodexObjective(plan), ...(plan.codexObjectiveAliases ?? [])];
+}
+
+export function hasAllCriteriaPass(goal: UlwLoopItem): boolean {
+	return goal.successCriteria.length > 0 && goal.successCriteria.every((criterion) => criterion.status === "pass");
+}
+
+export function firstUnresolvedCriterion(goal: UlwLoopItem): UlwLoopSuccessCriterion | undefined {
+	return goal.successCriteria.find((criterion) => criterion.status !== "pass");
+}