oh-my-opencode 4.5.1 → 4.5.12

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);
+	});

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(" ");
+}