@code-yeongyu/lazycodex 0.1.1

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

@@ -0,0 +1,155 @@
+// biome-ignore-all format: keep checkpoint orchestration below the pure LOC budget.
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { formatCodexGoalReconciliation, readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
+import { requireAllCriteriaPass } from "./evidence.js";
+import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { type UlwLoopScope, ulwLoopBriefPath } from "./paths.js";
+import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { classifyExternalAuthorizationBlocker, clearGoalBlockerFields, sameBlockerOccurrences, validateQualityGate } from "./quality-gate.js";
+import type { UlwLoopAggregateCompletion, UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopQualityGate } from "./types.js";
+import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
+
+export interface CheckpointUlwLoopArgs { readonly goalId: string; readonly status: "complete" | "failed" | "blocked"; readonly evidence: string; readonly codexGoalJson?: string; readonly qualityGateJson?: string }
+export interface CheckpointUlwLoopResult { readonly plan: UlwLoopPlan; readonly goal: UlwLoopItem; readonly ledgerEntry: UlwLoopLedgerEntry; readonly aggregateCompletion?: UlwLoopAggregateCompletion }
+
+function ulwLoopFail(message: string, code: string): never { throw new UlwLoopError(message, code); }
+function normalizeObjective(value: string): string { return value.replace(/\s+/g, " ").trim(); }
+function nonEmptyEvidence(value: string): string { const trimmed = value.trim(); return trimmed || ulwLoopFail("Evidence must be a non-empty string.", "ulw_loop_evidence_required"); }
+function findGoal(plan: UlwLoopPlan, goalId: string): UlwLoopItem { const goal = plan.goals.find((candidate) => candidate.id === goalId); return goal ?? ulwLoopFail(`Unknown ulw-loop id: ${goalId}.`, "ulw_loop_goal_not_found"); }
+
+function textMentionsUlwLoopPlanArtifact(value: string | undefined): boolean {
+	const normalized = (value ?? "").toLowerCase();
+	return normalized.includes(ULW_LOOP_DIR.toLowerCase()) || normalized.includes(ULW_LOOP_GOALS.toLowerCase()) || normalized.includes(ULW_LOOP_LEDGER.toLowerCase());
+}
+function textMentionsGoalId(value: string | undefined, goalId: string): boolean { return (value ?? "").toLowerCase().includes(goalId.toLowerCase()); }
+function textHasCompletionValidationEvidence(value: string | undefined): boolean {
+	const normalized = (value ?? "").toLowerCase();
+	const done = /\b(?:planned work|implementation|deliverables?|scope|task|work)\b/.test(normalized) && /\b(?:done|complete|completed|finished|shipped)\b/.test(normalized);
+	const verified = /\b(?:validation|verification|tests?|build|lint|review|quality gate|code-review)\b/.test(normalized) && /\b(?:passed|complete|completed|clean|green|approve|approved|clear)\b/.test(normalized);
+	return done && verified;
+}
+
+async function snapshotObjectiveMapsToUlwLoopPlan(repoRoot: string, snapshotObjective: string, scope?: UlwLoopScope): Promise<boolean> {
+	const actual = normalizeObjective(snapshotObjective).toLowerCase();
+	if (textMentionsUlwLoopPlanArtifact(actual)) return true;
+	if (actual.length < 24 || !existsSync(ulwLoopBriefPath(repoRoot, scope))) return false;
+	try {
+		const brief = normalizeObjective(await readFile(ulwLoopBriefPath(repoRoot, scope), "utf8")).toLowerCase();
+		return brief.length >= 24 && (brief.includes(actual) || actual.includes(brief));
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+
+async function canReconcileCompletedTaskScopedAggregateSnapshot(repoRoot: string, plan: UlwLoopPlan, goal: UlwLoopItem, snapshotObjective: string, evidence: string, scope?: UlwLoopScope): Promise<boolean> {
+	if (codexGoalMode(plan) !== "aggregate") return false;
+	if (goal.status !== "in_progress" || plan.activeGoalId !== goal.id) return false;
+	if (isFinalRunCompletionCandidate(plan, goal)) return snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope);
+	if (!textMentionsUlwLoopPlanArtifact(evidence) || !textMentionsGoalId(evidence, goal.id)) return false;
+	if (!textHasCompletionValidationEvidence(evidence)) return false;
+	return snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope);
+}
+
+function buildCompletedLegacyGoalRemediation(goal: UlwLoopItem): string {
+	return [
+		"If get_goal returns a different completed legacy/thread objective, do not repeat --status complete in this thread.",
+		`Record a non-terminal blocker with: omo ulw-loop checkpoint --goal-id ${goal.id} --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json "<different completed get_goal JSON or path>".`,
+		"Then continue only from a Codex goal context with no active/completed conflicting goal, in the same repo/worktree, and create the intended goal there.",
+	].join(" ");
+}
+
+function buildTaskScopedAggregateReconciliationHint(goal: UlwLoopItem, final: boolean): string {
+	if (final) {
+		return ` Final task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress final OMO goal and the completed get_goal objective to map to the ulw-loop brief or artifact. ${buildCompletedLegacyGoalRemediation(goal)}`;
+	}
+	return ` Completed task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress OMO goal, evidence that names that active OMO goal id, names .omo/ulw-loop/goals.json or ledger.jsonl, includes completed implementation plus validation/review evidence, and a get_goal objective that maps to the ulw-loop brief/artifact. ${buildCompletedLegacyGoalRemediation(goal)}`;
+}
+
+async function readJsonInput(raw: string | undefined, repoRoot: string): Promise<unknown> {
+	if (raw === undefined || raw.trim() === "") return undefined;
+	const trimmed = raw.trim();
+	try { return JSON.parse(trimmed); } catch (error) { if (!(error instanceof SyntaxError)) throw error; }
+	const path = resolve(repoRoot, trimmed);
+	if (!existsSync(path)) return ulwLoopFail("Quality gate JSON is neither valid JSON nor a readable path.", "ulw_loop_json_input_invalid");
+	try { return JSON.parse(await readFile(path, "utf8")); } catch (error) { return ulwLoopFail(`Quality gate path does not contain valid JSON${error instanceof Error ? `: ${error.message}` : "."}`, "ulw_loop_json_input_invalid"); }
+}
+
+function makeAggregateCompletion(now: string, evidence: string, codexGoal: unknown): UlwLoopAggregateCompletion {
+	return { status: "complete", completedAt: now, evidence, codexGoal };
+}
+
+function applyBlockedOrFailed(goal: UlwLoopItem, plan: UlwLoopPlan, status: "failed" | "blocked", evidence: string, now: string): void {
+	const signature = classifyExternalAuthorizationBlocker(evidence);
+	const occurrences = signature === null ? 0 : sameBlockerOccurrences(plan, signature) + 1;
+	const needsDecision = signature !== null && occurrences >= 3;
+	goal.status = needsDecision ? "needs_user_decision" : status;
+	goal.updatedAt = now;
+	if (status === "failed" || needsDecision) { goal.failedAt = now; goal.failureReason = evidence; }
+	if (status === "blocked" || needsDecision) goal.blockedReason = evidence;
+	if (signature !== null) { goal.blockerSignature = signature; goal.blockerOccurrenceCount = occurrences; goal.requiredExternalDecision = `Resolve external authorization: ${signature}`; }
+	if (needsDecision) goal.nonRetriable = true;
+	if (plan.activeGoalId === goal.id) delete plan.activeGoalId;
+}
+
+function ledgerKind(status: CheckpointUlwLoopArgs["status"], goal: UlwLoopItem, aggregateCompletion: UlwLoopAggregateCompletion | undefined): UlwLoopLedgerEntry["kind"] {
+	if (aggregateCompletion !== undefined) return "aggregate_completed";
+	if (status === "complete") return "goal_completed";
+	if (goal.status === "needs_user_decision") return "goal_needs_user_decision";
+	return status === "blocked" ? "goal_blocked" : "goal_failed";
+}
+
+function buildLedger(now: string, args: CheckpointUlwLoopArgs, goal: UlwLoopItem, qualityGate: UlwLoopQualityGate | undefined, codexGoal: unknown, aggregateCompletion: UlwLoopAggregateCompletion | undefined): UlwLoopLedgerEntry {
+	const entry: UlwLoopLedgerEntry = { at: now, kind: ledgerKind(args.status, goal, aggregateCompletion), goalId: goal.id, status: goal.status, evidence: args.evidence };
+	if (codexGoal !== undefined) entry.codexGoal = codexGoal;
+	if (qualityGate !== undefined) entry.qualityGate = qualityGate;
+	if (goal.blockerSignature !== undefined) entry.blockerSignature = goal.blockerSignature;
+	if (goal.blockerOccurrenceCount !== undefined) entry.blockerOccurrenceCount = goal.blockerOccurrenceCount;
+	if (goal.requiredExternalDecision !== undefined) entry.requiredExternalDecision = goal.requiredExternalDecision;
+	return entry;
+}
+
+export async function checkpointUlwLoop(repoRoot: string, args: CheckpointUlwLoopArgs, scope?: UlwLoopScope): Promise<CheckpointUlwLoopResult> {
+	return withUlwLoopMutationLock(repoRoot, scope, async () => {
+		const plan = await readUlwLoopPlan(repoRoot, scope);
+		const goal = findGoal(plan, args.goalId);
+		if (args.status === "complete") requireAllCriteriaPass(goal);
+		const evidence = nonEmptyEvidence(args.evidence);
+		const now = iso();
+		let aggregateCompletion: UlwLoopAggregateCompletion | undefined;
+		let qualityGate: UlwLoopQualityGate | undefined;
+		let codexGoal: unknown;
+		if (args.status === "complete") {
+			const aggregate = codexGoalMode(plan) === "aggregate";
+			const final = isFinalRunCompletionCandidate(plan, goal);
+			const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
+			const reconciliation = reconcileCodexGoalSnapshot(snapshot, { expectedObjective: expectedCodexObjective(plan, goal), ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}), allowedStatuses: aggregate ? (final ? ["complete"] : ["active"]) : ["complete"], requireSnapshot: true, requireComplete: !aggregate || final });
+			codexGoal = reconciliation.snapshot.raw;
+			if (!reconciliation.ok) {
+				const objective = snapshot?.objective;
+				const taskScoped = snapshot?.available === true && snapshot.status === "complete" && objective !== undefined && normalizeObjective(objective) !== normalizeObjective(expectedCodexObjective(plan, goal)) && await canReconcileCompletedTaskScopedAggregateSnapshot(repoRoot, plan, goal, objective, evidence, scope);
+				if (!taskScoped) throw new UlwLoopError(`${formatCodexGoalReconciliation(reconciliation)}${aggregate && snapshot?.status === "complete" && objective !== undefined ? buildTaskScopedAggregateReconciliationHint(goal, final) : ""}`, "ulw_loop_codex_snapshot_mismatch");
+				aggregateCompletion = makeAggregateCompletion(now, evidence, codexGoal);
+			}
+			if (final) aggregateCompletion = makeAggregateCompletion(now, evidence, codexGoal);
+			if (final || aggregateCompletion !== undefined) qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot));
+			goal.status = "complete";
+			goal.completedAt = now;
+			goal.evidence = evidence;
+			delete goal.failedAt;
+			delete goal.failureReason;
+			clearGoalBlockerFields(goal);
+			if (plan.activeGoalId === goal.id) delete plan.activeGoalId;
+		} else applyBlockedOrFailed(goal, plan, args.status, evidence, now);
+		goal.updatedAt = now;
+		if (aggregateCompletion !== undefined) plan.aggregateCompletion = aggregateCompletion;
+		plan.updatedAt = now;
+		await writePlan(repoRoot, plan, scope);
+		const ledgerEntry = buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion);
+		await appendLedger(repoRoot, ledgerEntry, scope);
+		return aggregateCompletion === undefined ? { plan, goal, ledgerEntry } : { plan, goal, ledgerEntry, aggregateCompletion };
+	});
+}

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

@@ -0,0 +1,95 @@
+// biome-ignore-all format: keep this module under the mandated pure LOC budget.
+import { readFile } from "node:fs/promises";
+
+import { UlwLoopError } from "./types.js";
+
+type RecordEvidenceCliArgs = { readonly goalId: string; readonly criterionId: string; readonly status: "pass" | "fail" | "blocked"; readonly evidence: string; readonly notes?: string };
+
+const VALUE_FLAGS = new Set("--brief --brief-file --session-id --codex-goal-mode --goal --goal-id --criterion-id --status --evidence --notes --codex-goal-json --quality-gate-json --kind --rationale --title --objective --target-goal-id --source --after-json --directive-json --directive-file --idempotency-key".split(" "));
+const SUBCOMMANDS = new Set("create-goals status complete-goals criteria record-evidence checkpoint steer add-goal record-review-blockers".split(" "));
+
+export function hasFlag(argv: readonly string[], flag: string): boolean { return argv.includes(flag); }
+
+export function readValue(argv: readonly string[], flag: string): string | undefined {
+	const index = argv.indexOf(flag);
+	if (index >= 0) {
+		const next = argv[index + 1];
+		return next === undefined || next.startsWith("--") ? undefined : next;
+	}
+	const prefix = `${flag}=`;
+	return argv.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+}
+
+export function readRepeated(argv: readonly string[], flag: string): string[] {
+	const values: string[] = [];
+	const prefix = `${flag}=`;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		const next = argv[index + 1];
+		if (arg === flag && next !== undefined && !next.startsWith("--")) { values.push(next); index += 1; }
+		else if (arg?.startsWith(prefix)) values.push(arg.slice(prefix.length));
+	}
+	return values;
+}
+
+export function parseGoalArg(argv: readonly string[]): string | undefined { return readValue(argv, "--goal-id") ?? readValue(argv, "--goal"); }
+
+export async function readStdin(): Promise<string> {
+	const chunks: Buffer[] = [];
+	for await (const chunk of process.stdin) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	return Buffer.concat(chunks).toString("utf8");
+}
+
+export function positionalText(argv: readonly string[]): string {
+	const words: string[] = [];
+	for (let index = SUBCOMMANDS.has(argv[0] ?? "") ? 1 : 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === undefined) continue;
+		if (VALUE_FLAGS.has(arg)) { index += 1; continue; }
+		if (arg.startsWith("--")) continue;
+		words.push(arg);
+	}
+	return words.join(" ").trim();
+}
+
+function looksLikeJson(value: string): boolean { const trimmed = value.trim(); return trimmed.startsWith("{") || trimmed.startsWith("["); }
+
+export async function readJsonInput(value: string | undefined): Promise<unknown | undefined> {
+	if (value === undefined) return undefined;
+	try { return JSON.parse(looksLikeJson(value) ? value : await readFile(value, "utf8")); }
+	catch (error) {
+		const message = error instanceof Error ? error.message : "unknown error";
+		throw new UlwLoopError(`Invalid JSON input: ${message}`, "ULW_LOOP_JSON_INPUT_INVALID", { cause: error });
+	}
+}
+
+export async function parseCodexGoalJson(value: string | undefined): Promise<string | undefined> {
+	if (value === undefined) return undefined;
+	const raw = looksLikeJson(value) ? value : await readFile(value, "utf8");
+	try { JSON.parse(raw); return raw; }
+	catch (error) {
+		const message = error instanceof Error ? error.message : "unknown error";
+		throw new UlwLoopError(`Invalid --codex-goal-json: ${message}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
+	}
+}
+
+function required(argv: readonly string[], flag: string, code: string): string {
+	const value = readValue(argv, flag)?.trim();
+	if (value) return value;
+	throw new UlwLoopError(`Missing ${flag}.`, code, { details: { flag } });
+}
+
+function evidenceStatus(value: string): RecordEvidenceCliArgs["status"] {
+	switch (value) {
+		case "pass": return "pass";
+		case "fail": return "fail";
+		case "blocked": return "blocked";
+		default: throw new UlwLoopError("Invalid --status; expected pass, fail, or blocked.", "ULW_LOOP_EVIDENCE_STATUS_INVALID", { details: { status: value } });
+	}
+}
+
+export function parseRecordEvidenceArgs(argv: readonly string[]): RecordEvidenceCliArgs {
+	const result = { goalId: required(argv, "--goal-id", "ULW_LOOP_GOAL_ID_REQUIRED"), criterionId: required(argv, "--criterion-id", "ULW_LOOP_CRITERION_ID_REQUIRED"), status: evidenceStatus(required(argv, "--status", "ULW_LOOP_EVIDENCE_STATUS_REQUIRED")), evidence: required(argv, "--evidence", "ULW_LOOP_EVIDENCE_REQUIRED") };
+	const notes = readValue(argv, "--notes")?.trim();
+	return notes ? { ...result, notes } : result;
+}

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

@@ -0,0 +1,156 @@
+// biome-ignore-all format: keep cli-commands dispatcher under the 200 pure LOC budget.
+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, ULW_LOOP_HELP } from "./cli-output.js";
+import { parseSteeringProposal, printSteerResult } from "./cli-steering.js";
+import { buildCodexGoalInstruction } from "./codex-goal-instruction.js";
+import { recordEvidence } from "./evidence.js";
+import { resolveUlwLoopSessionIdFromEnv, 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 ulwLoopCommand(argv: readonly string[]): Promise<number> {
+	const command = argv[0] ?? "help";
+	const rest = argv.slice(1);
+	const repoRoot = process.cwd();
+	const json = hasFlag(rest, "--json");
+	const scope = commandScope(rest);
+	try {
+		switch (command) {
+			case "help": case "--help": case "-h": process.stdout.write(`${ULW_LOOP_HELP}\n`); return 0;
+			case "create-goals": return await createGoals(repoRoot, rest, json, scope);
+			case "status": return await status(repoRoot, json, scope);
+			case "complete-goals": return await completeGoals(repoRoot, rest, json, scope);
+			case "checkpoint": return await checkpoint(repoRoot, rest, json, scope);
+			case "steer": return await steer(repoRoot, rest, json, scope);
+			case "add-goal": return await addGoal(repoRoot, rest, json, scope);
+			case "criteria": return await criteria(repoRoot, rest, json, scope);
+			case "record-evidence": return await captureEvidence(repoRoot, rest, json, scope);
+			case "record-review-blockers": return await reviewBlockers(repoRoot, rest, json, scope);
+			default: process.stdout.write(`${ULW_LOOP_HELP}\n`); return 1;
+		}
+	} catch (error) {
+		if (error instanceof UlwLoopError) process.stderr.write(`[ulw-loop] ${error.message}\n`);
+		else if (error instanceof Error) process.stderr.write(`[ulw-loop] unexpected: ${error.message}\n`);
+		else process.stderr.write("[ulw-loop] unknown error\n");
+		return 1;
+	}
+}
+
+function commandScope(argv: readonly string[]): UlwLoopScope | undefined {
+	const sessionId = readValue(argv, "--session-id") ?? resolveUlwLoopSessionIdFromEnv();
+	return sessionId === null ? undefined : { sessionId };
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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((c) => `- ${c.id} [${c.status}] (${c.userModel}) ${c.scenario} evidence: ${c.capturedEvidence ?? "pending"}`).join("\n")}\n`);
+	return 0;
+}
+
+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;
+}
+
+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 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/cli-output.ts

@@ -0,0 +1,63 @@
+import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan } from "./types.js";
+import { UlwLoopError } from "./types.js";
+
+export const ULW_LOOP_HELP = `Usage:
+  omo ulw-loop create-goals --brief "..." [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--force] [--json]
+  omo ulw-loop status [--json]
+  omo ulw-loop complete-goals [--retry-failed] [--json]
+  omo ulw-loop criteria --goal-id <id> [--json]
+  omo ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence "..." [--notes "..."] [--json]
+  omo ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence "..." --codex-goal-json <...> [--quality-gate-json <...>] [--json]
+  omo ulw-loop steer --kind <kind> ... --evidence "..." --rationale "..." [--json]
+  omo ulw-loop add-goal --title "..." --objective "..." [--json]
+  omo ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
+
+All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.`;
+
+type CriteriaCounts = { readonly pass: number; readonly total: number };
+
+export function printJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function criteriaCounts(goal: UlwLoopItem): CriteriaCounts {
+	let pass = 0;
+	for (const criterion of goal.successCriteria) if (criterion.status === "pass") pass += 1;
+	return { pass, total: goal.successCriteria.length };
+}
+
+export function printStatus(plan: UlwLoopPlan): void {
+	let totalCriteria = 0;
+	let passCriteria = 0;
+	const lines = ["ulw-loop status", "", "goals:"];
+	for (const goal of plan.goals) {
+		const counts = criteriaCounts(goal);
+		totalCriteria += counts.total;
+		passCriteria += counts.pass;
+		const marker = goal.id === plan.activeGoalId ? "*" : "-";
+		lines.push(`${marker} ${goal.id} [${goal.status}] ${goal.title} (criteria: ${counts.pass}/${counts.total})`);
+	}
+	lines.push("", "summary:", `total goals: ${plan.goals.length}`, `criteria: ${passCriteria}/${totalCriteria} pass`);
+	process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+export function blockedDecisionHandoff(plan: UlwLoopPlan): string {
+	const blocked = plan.goals.find((goal) => goal.status === "needs_user_decision" && goal.nonRetriable);
+	if (blocked === undefined) return "";
+	return [
+		"ulw-loop: blocked on repeated external authorization; no retryable failed goals remain.",
+		`Goal: ${blocked.id} - ${blocked.title}`,
+		`Required external decision: ${blocked.requiredExternalDecision ?? "provide the missing authorization or choose a different unblock path"}.`,
+		"Do not run complete-goals --retry-failed again until external state changes or the user authorizes an unblock path.",
+	].join("\n");
+}
+
+export function normalizeCodexGoalMode(value: string | undefined): UlwLoopCodexGoalMode {
+	if (value === undefined) return "aggregate";
+	if (value === "aggregate" || value === "per_story") return value;
+	throw new UlwLoopError(
+		"Invalid --codex-goal-mode; expected aggregate or per_story.",
+		"ULW_LOOP_CODEX_GOAL_MODE_INVALID",
+		{ details: { value } },
+	);
+}

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

@@ -0,0 +1,94 @@
+// biome-ignore-all format: keep this module under the mandated pure LOC budget.
+import { parseGoalArg, readJsonInput, readValue } from "./cli-arg-parser.js";
+import { printJson, printStatus } from "./cli-output.js";
+import type { SteerUlwLoopResult, UlwLoopSteeringChildGoal, UlwLoopSteeringMutationKind, UlwLoopSteeringProposal, UlwLoopSteeringSource, UlwLoopSuccessCriterionUserModel } from "./types.js";
+import { ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS, UlwLoopError } from "./types.js";
+
+const SOURCES = ["user_prompt_submit", "finding", "cli"] as const satisfies readonly UlwLoopSteeringSource[];
+
+export type CliSteeringProposal = UlwLoopSteeringProposal & { readonly goalId?: string; readonly scenario?: string; readonly expectedEvidence?: string; readonly userModel?: UlwLoopSuccessCriterionUserModel };
+
+function isKind(value: string | undefined): value is UlwLoopSteeringMutationKind { return value !== undefined && ULW_LOOP_STEERING_MUTATION_KINDS.some((kind) => kind === value); }
+function isSource(value: string | undefined): value is UlwLoopSteeringSource { return value !== undefined && SOURCES.some((source) => source === value); }
+function isModel(value: string): value is UlwLoopSuccessCriterionUserModel { return ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value); }
+function fail(message: string, code: string, details: Record<string, unknown>): never { throw new UlwLoopError(message, code, { details }); }
+function text(value: string | undefined, field: string): string | undefined { if (value === undefined) return undefined; const trimmed = value.trim(); if (trimmed.length > 0) return trimmed; return fail(`Empty ${field}.`, "ULW_LOOP_STEERING_FIELD_EMPTY", { field }); }
+function required(argv: readonly string[], flag: string): string { const value = text(readValue(argv, flag), flag); return value ?? fail(`Missing ${flag}.`, "ULW_LOOP_STEERING_FIELD_REQUIRED", { flag }); }
+function requiredGoal(argv: readonly string[]): string { const value = text(parseGoalArg(argv), "--goal-id"); return value ?? fail("Missing --goal-id.", "ULW_LOOP_GOAL_ID_REQUIRED", { flag: "--goal-id" }); }
+function readObject(value: object, key: string): unknown { return Object.entries(value).find(([name]) => name === key)?.[1]; }
+function isPlain(value: unknown): value is object { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function objectText(value: object, key: string): string | undefined { const candidate = readObject(value, key); return typeof candidate === "string" ? candidate : undefined; }
+
+export function parseSteeringKind(argv: readonly string[]): UlwLoopSteeringMutationKind {
+	const value = readValue(argv, "--kind");
+	if (isKind(value)) return value;
+	return value === undefined ? fail("Missing --kind.", "ULW_LOOP_STEERING_KIND_REQUIRED", { flag: "--kind" }) : fail(`Invalid --kind: ${value}.`, "ULW_LOOP_STEERING_KIND_INVALID", { value, expected: ULW_LOOP_STEERING_MUTATION_KINDS });
+}
+
+export function parseSteeringSource(argv: readonly string[]): UlwLoopSteeringSource {
+	const value = readValue(argv, "--source");
+	if (value === undefined) return "cli";
+	return isSource(value) ? value : fail(`Invalid --source: ${value}.`, "ULW_LOOP_STEERING_SOURCE_INVALID", { value, expected: SOURCES });
+}
+
+function child(value: unknown): UlwLoopSteeringChildGoal | null {
+	if (!isPlain(value)) return null;
+	const title = text(objectText(value, "title"), "title"); const objective = text(objectText(value, "objective"), "objective");
+	if (title === undefined || objective === undefined) return null;
+	return { title, objective };
+}
+
+async function children(argv: readonly string[], flag: string, needed: boolean): Promise<UlwLoopSteeringChildGoal[]> {
+	const input = needed ? required(argv, flag) : text(readValue(argv, flag), flag);
+	if (input === undefined) return [];
+	const raw = await readJsonInput(input);
+	if (!Array.isArray(raw)) return fail(`${flag} must be a JSON array.`, "ULW_LOOP_STEERING_JSON_ARRAY_REQUIRED", { flag });
+	const parsed: UlwLoopSteeringChildGoal[] = [];
+	for (const item of raw) { const next = child(item); if (next === null) return fail(`${flag} entries require title/objective.`, "ULW_LOOP_STEERING_CHILD_INVALID", { flag }); parsed.push(next); }
+	return parsed;
+}
+
+async function stringArray(argv: readonly string[], flag: string): Promise<string[]> {
+	const raw = await readJsonInput(required(argv, flag));
+	if (!Array.isArray(raw)) return fail(`${flag} must be a JSON array.`, "ULW_LOOP_STEERING_JSON_ARRAY_REQUIRED", { flag });
+	const values: string[] = [];
+	for (const item of raw) { if (typeof item !== "string") return fail(`${flag} entries must be strings.`, "ULW_LOOP_STEERING_STRING_ARRAY_REQUIRED", { flag }); values.push(text(item, flag) ?? ""); }
+	return values;
+}
+
+function model(value: string | undefined): UlwLoopSuccessCriterionUserModel | undefined { const trimmed = text(value, "--user-model"); if (trimmed === undefined) return undefined; return isModel(trimmed) ? trimmed : fail(`Invalid --user-model: ${trimmed}.`, "ULW_LOOP_STEERING_USER_MODEL_INVALID", { value: trimmed, expected: ULW_LOOP_SUCCESS_CRITERION_USER_MODELS }); }
+function neverKind(kind: never): never { return fail(`Unsupported steering kind: ${String(kind)}.`, "ULW_LOOP_STEERING_KIND_UNSUPPORTED", { kind }); }
+
+export async function parseSteeringProposal(argv: readonly string[]): Promise<CliSteeringProposal> {
+	const kind = parseSteeringKind(argv); const source = parseSteeringSource(argv); const base = { kind, source, evidence: required(argv, "--evidence"), rationale: required(argv, "--rationale") };
+	switch (kind) {
+		case "add_subgoal": return normalizeSteeringProposal({ ...base, title: required(argv, "--title"), objective: required(argv, "--objective") });
+		case "split_subgoal": { const goalId = requiredGoal(argv); return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, childGoals: await children(argv, "--children", true) }); }
+		case "reorder_pending": return normalizeSteeringProposal({ ...base, pendingOrder: await stringArray(argv, "--order") });
+		case "revise_pending_wording": { const goalId = requiredGoal(argv); const revisedTitle = readValue(argv, "--title"); const revisedObjective = readValue(argv, "--objective"); if (revisedTitle === undefined && revisedObjective === undefined) return fail("revise_pending_wording requires --title or --objective.", "ULW_LOOP_STEERING_UPDATE_REQUIRED", { kind }); return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, ...(revisedTitle === undefined ? {} : { revisedTitle }), ...(revisedObjective === undefined ? {} : { revisedObjective }) }); }
+		case "revise_criterion": { const goalId = requiredGoal(argv); const criterionId = required(argv, "--criterion-id"); const scenario = readValue(argv, "--scenario"); const expectedEvidence = readValue(argv, "--expected-evidence"); const userModel = model(readValue(argv, "--user-model")); if (scenario === undefined && expectedEvidence === undefined && userModel === undefined) return fail("revise_criterion requires scenario, expected-evidence, or user-model.", "ULW_LOOP_STEERING_UPDATE_REQUIRED", { kind }); return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, criterionId, ...(scenario === undefined ? {} : { scenario }), ...(expectedEvidence === undefined ? {} : { expectedEvidence }), ...(userModel === undefined ? {} : { userModel }) }); }
+		case "annotate_ledger": return normalizeSteeringProposal(base);
+		case "mark_blocked_superseded": { const goalId = requiredGoal(argv); const childGoals = await children(argv, "--replacements", false); return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, ...(childGoals.length === 0 ? {} : { childGoals }) }); }
+		default: return neverKind(kind);
+	}
+}
+
+function normalizedChildren(values: readonly UlwLoopSteeringChildGoal[] | undefined): UlwLoopSteeringChildGoal[] | undefined { if (values === undefined) return undefined; return values.map((item) => ({ title: text(item.title, "child.title") ?? "", objective: text(item.objective, "child.objective") ?? "" })); }
+function normalizedStrings(values: readonly string[] | undefined, field: string): string[] | undefined { if (values === undefined) return undefined; return values.map((value) => text(value, field) ?? ""); }
+
+export function normalizeSteeringProposal(proposal: CliSteeringProposal): CliSteeringProposal {
+	const evidence = text(proposal.evidence, "evidence") ?? ""; const rationale = text(proposal.rationale, "rationale") ?? ""; const goalId = text(proposal.goalId, "goalId"); const targetGoalId = text(proposal.targetGoalId, "targetGoalId"); const targetGoalIds = normalizedStrings(proposal.targetGoalIds, "targetGoalIds");
+	const criterionId = text(proposal.criterionId, "criterionId"); const title = text(proposal.title, "title"); const objective = text(proposal.objective, "objective"); const revisedTitle = text(proposal.revisedTitle, "revisedTitle"); const revisedObjective = text(proposal.revisedObjective, "revisedObjective");
+	const blockedReason = text(proposal.blockedReason, "blockedReason"); const directiveText = text(proposal.directiveText, "directiveText"); const promptSignature = text(proposal.promptSignature, "promptSignature"); const idempotencyKey = text(proposal.idempotencyKey, "idempotencyKey");
+	const scenario = text(proposal.scenario, "scenario"); const expectedEvidence = text(proposal.expectedEvidence, "expectedEvidence"); const childGoals = normalizedChildren(proposal.childGoals); const pendingOrder = normalizedStrings(proposal.pendingOrder, "pendingOrder");
+	return { kind: proposal.kind, source: proposal.source, evidence, rationale, ...(goalId === undefined ? {} : { goalId }), ...(targetGoalId === undefined ? {} : { targetGoalId }), ...(targetGoalIds === undefined ? {} : { targetGoalIds }), ...(criterionId === undefined ? {} : { criterionId }), ...(title === undefined ? {} : { title }), ...(objective === undefined ? {} : { objective }), ...(childGoals === undefined ? {} : { childGoals }), ...(revisedTitle === undefined ? {} : { revisedTitle }), ...(revisedObjective === undefined ? {} : { revisedObjective }), ...(pendingOrder === undefined ? {} : { pendingOrder }), ...(blockedReason === undefined ? {} : { blockedReason }), ...(proposal.after === undefined ? {} : { after: proposal.after }), ...(directiveText === undefined ? {} : { directiveText }), ...(promptSignature === undefined ? {} : { promptSignature }), ...(idempotencyKey === undefined ? {} : { idempotencyKey }), ...(proposal.now === undefined ? {} : { now: proposal.now }), ...(scenario === undefined ? {} : { scenario }), ...(expectedEvidence === undefined ? {} : { expectedEvidence }), ...(proposal.userModel === undefined ? {} : { userModel: proposal.userModel }) };
+}
+
+export function printSteerResult(result: SteerUlwLoopResult, json: boolean): void {
+	if (json) { printJson({ ok: result.accepted, accepted: result.accepted, rejectedReasons: result.rejectedReasons, deduped: result.deduped, audit: result.audit, plan: result.plan }); return; }
+	const outcome = result.deduped ? "deduped" : result.accepted ? "accepted" : "rejected";
+	process.stdout.write(`ulw-loop steer: ${outcome} ${result.audit.kind}\n`);
+	if (result.rejectedReasons.length > 0) process.stdout.write(`rejected: ${result.rejectedReasons.join("; ")}\n`);
+	if (result.audit.idempotencyKey !== undefined) process.stdout.write(`idempotency-key: ${result.audit.idempotencyKey}\n`);
+	printStatus(result.plan);
+}

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { ulwLoopCommand } from "./cli-commands.js";
+import { runPreToolUseGoalBudgetGuardCli, runUlwLoopHookCli } from "./codex-hook.js";
+
+const TOP_LEVEL_HELP =
+	"Usage:\n  omo ulw-loop <subcommand> [args]\n  omo hook user-prompt-submit         (Codex UserPromptSubmit hook)\n  omo help | --help | -h              (this message)\n\nRun `omo ulw-loop help` for ulw-loop subcommands.\n";
+
+async function main(): Promise<number> {
+	const argv = process.argv.slice(2);
+	const command = argv[0];
+	if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+		process.stdout.write(TOP_LEVEL_HELP);
+		return 0;
+	}
+	if (command === "ulw-loop") return ulwLoopCommand(argv.slice(1));
+	if (command === "hook") {
+		const sub = argv[1];
+		if (sub === "user-prompt-submit") {
+			await runUlwLoopHookCli(process.stdin, process.stdout);
+			return 0;
+		}
+		if (sub === "pre-tool-use") {
+			await runPreToolUseGoalBudgetGuardCli(process.stdin, process.stdout);
+			return 0;
+		}
+		process.stderr.write(`[omo] unknown hook subcommand: ${sub ?? "(none)"}\n`);
+		return 1;
+	}
+	process.stderr.write(`[omo] unknown command: ${command}\n${TOP_LEVEL_HELP}`);
+	return 1;
+}
+
+main()
+	.then((code) => {
+		process.exit(code);
+	})
+	.catch((error: unknown) => {
+		process.stderr.write(`[omo] ${error instanceof Error ? error.message : String(error)}\n`);
+		process.exit(1);
+	});