oh-my-opencode 4.5.1 → 4.6.0

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

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

@@ -0,0 +1,73 @@
+import { join } from "node:path";
+import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
+
+export interface UlwLoopScope {
+	readonly sessionId?: string | null;
+}
+
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"] as const;
+type EnvMap = Readonly<Record<string, string | undefined>>;
+
+export function normalizeUlwLoopSessionId(sessionId: string | null | undefined): string | null {
+	const trimmed = sessionId?.trim();
+	if (!trimmed) return null;
+	const pathSegments = trimmed
+		.split(/[\\/]+/)
+		.filter((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+	const candidate = (pathSegments.length > 0 ? pathSegments.join("-") : trimmed)
+		.replace(/[^A-Za-z0-9._-]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^\.+/, "")
+		.replace(/^[.-]+|[.-]+$/g, "");
+	return candidate.length > 0 ? candidate : null;
+}
+
+export function resolveUlwLoopSessionIdFromEnv(env: EnvMap = process.env): string | null {
+	for (const key of SESSION_ENV_KEYS) {
+		const normalized = normalizeUlwLoopSessionId(env[key]);
+		if (normalized !== null) return normalized;
+	}
+	return null;
+}
+
+export function ulwLoopRelativeDir(scope?: UlwLoopScope): string {
+	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId);
+	return sessionId === null ? ULW_LOOP_DIR : `${ULW_LOOP_DIR}/${sessionId}`;
+}
+
+export function ulwLoopDir(repoRoot: string, scope?: UlwLoopScope): string {
+	return join(repoRoot, ulwLoopRelativeDir(scope));
+}
+
+export function ulwLoopBriefRelativePath(scope?: UlwLoopScope): string {
+	return `${ulwLoopRelativeDir(scope)}/${ULW_LOOP_BRIEF}`;
+}
+
+export function ulwLoopGoalsRelativePath(scope?: UlwLoopScope): string {
+	return `${ulwLoopRelativeDir(scope)}/${ULW_LOOP_GOALS}`;
+}
+
+export function ulwLoopLedgerRelativePath(scope?: UlwLoopScope): string {
+	return `${ulwLoopRelativeDir(scope)}/${ULW_LOOP_LEDGER}`;
+}
+
+export function ulwLoopBriefPath(repoRoot: string, scope?: UlwLoopScope): string {
+	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_BRIEF);
+}
+
+export function ulwLoopGoalsPath(repoRoot: string, scope?: UlwLoopScope): string {
+	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_GOALS);
+}
+
+export function ulwLoopLedgerPath(repoRoot: string, scope?: UlwLoopScope): string {
+	return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_LEDGER);
+}
+
+export function repoRelative(absolutePath: string, repoRoot: string): string {
+	const slashPrefix = `${repoRoot}/`;
+	const backslashPrefix = `${repoRoot}\\`;
+	if (absolutePath.startsWith(slashPrefix)) return absolutePath.slice(slashPrefix.length).split("\\").join("/");
+	if (absolutePath.startsWith(backslashPrefix))
+		return absolutePath.slice(backslashPrefix.length).split("\\").join("/");
+	return absolutePath.split("\\").join("/");
+}

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

@@ -0,0 +1,113 @@
+// biome-ignore-all format: keep this port under the mandated pure LOC budget.
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+
+import { aggregateCodexObjectiveForScope } from "./goal-status.js";
+import { type UlwLoopScope, ulwLoopBriefPath, ulwLoopBriefRelativePath, ulwLoopDir, ulwLoopGoalsPath, ulwLoopGoalsRelativePath, ulwLoopLedgerPath, ulwLoopLedgerRelativePath } from "./paths.js";
+import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
+import { iso, UlwLoopError } from "./types.js";
+
+export type UlwLoopPlanSummary = { readonly total: number; readonly pending: number; readonly in_progress: number; readonly complete: number; readonly failed: number; readonly blocked: number; readonly review_blocked: number; readonly needs_user_decision: number; readonly superseded: number; readonly criteria: { readonly total: number; readonly pass: number; readonly pending: number; readonly fail: number; readonly blocked: number } };
+
+function cleanLine(line: string): string { return line.replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, "").trim(); }
+function normalizeObjective(value: string): string { return value.replace(/\s+/g, " ").trim(); }
+function titleFromObjective(objective: string, fallback: string): string { const firstLine = objective.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? fallback; return firstLine.length > 72 ? `${firstLine.slice(0, 69).trimEnd()}...` : firstLine; }
+function normalizeGoalId(title: string, index: number): string { const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 36).replace(/-+$/g, ""); return `G${String(index + 1).padStart(3, "0")}${slug ? `-${slug}` : ""}`; }
+function assertNonEmpty(value: string | undefined, label: string): string { const trimmed = value?.trim(); if (!trimmed) throw new UlwLoopError(`Missing ${label}.`, "ULW_LOOP_ARGUMENT_MISSING"); return trimmed; }
+function truncateObjective(objective: string): string { return objective.length > 80 ? `${objective.slice(0, 77).trimEnd()}...` : objective; }
+
+export function seedDefaultSuccessCriteria(goalIndex: number, objective: string): UlwLoopSuccessCriterion[] {
+	const subject = truncateObjective(normalizeObjective(objective) || `Goal ${goalIndex + 1}`);
+	const rows = [
+		["C001", "happy", `happy path for: ${subject}`, `Replace via revise_criterion with observable happy-path proof for goal ${goalIndex + 1}.`],
+		["C002", "edge", "edge case (boundary/empty/malformed)", `Replace via revise_criterion with boundary or malformed-input proof for: ${subject}.`],
+		["C003", "regression", "regression: adjacent surface still works", `Replace via revise_criterion with regression proof for neighboring behavior after: ${subject}.`],
+	] as const;
+	return rows.map(([id, userModel, scenario, expectedEvidence]) => ({ id, scenario, userModel, expectedEvidence, capturedEvidence: null, status: "pending" }));
+}
+
+export function deriveGoalCandidates(brief: string): Array<{ title: string; objective: string }> {
+	const bulletGoals = brief.split(/\r?\n/).map((line) => ({ original: line, cleaned: normalizeObjective(cleanLine(line)) })).filter(({ cleaned }) => cleaned.length > 0 && cleaned.length <= 1200).filter(({ original, cleaned }, index, all) => /^\s*(?:[-*+]\s+|\d+[.)]\s+)/.test(original) && all.findIndex((candidate) => candidate.cleaned === cleaned) === index).map(({ cleaned }) => cleaned);
+	const paragraphs = brief.split(/\n\s*\n/).map(normalizeObjective).filter((paragraph) => paragraph.length > 0 && !paragraph.startsWith("#"));
+	const selected = (bulletGoals.length > 0 ? bulletGoals : paragraphs).length > 0 ? (bulletGoals.length > 0 ? bulletGoals : paragraphs) : ["Complete the requested project objective."];
+	return selected.map((objective, index) => ({ title: titleFromObjective(objective, `Goal ${index + 1}`), objective }));
+}
+
+function makeGoal(title: string, objective: string, index: number, now: string): UlwLoopItem {
+	const cleanTitle = assertNonEmpty(title, "title");
+	const cleanObjective = assertNonEmpty(objective, "objective");
+	return { id: normalizeGoalId(cleanTitle, index), title: cleanTitle, objective: cleanObjective, status: "pending", successCriteria: seedDefaultSuccessCriteria(index, cleanObjective), attempt: 0, createdAt: now, updatedAt: now };
+}
+
+function appendGoalToPlan(plan: UlwLoopPlan, title: string, objective: string, now: string): UlwLoopItem {
+	const goal = makeGoal(title, objective, plan.goals.length, now);
+	plan.goals.push(goal);
+	plan.updatedAt = now;
+	return goal;
+}
+
+function isScheduleEligible(goal: UlwLoopItem): boolean { return goal.steeringStatus !== "superseded" && goal.steeringStatus !== "blocked"; }
+
+function clearGoalBlockerFields(goal: UlwLoopItem): void {
+	for (const key of ["blockedReason", "blockerSignature", "blockerOccurrenceCount", "requiredExternalDecision", "nonRetriable", "failedAt", "failureReason"] as const) delete goal[key];
+}
+
+export async function createUlwLoopPlan(repoRoot: string, args: { brief: string; codexGoalMode?: UlwLoopCodexGoalMode; force?: boolean }, scope?: UlwLoopScope): Promise<UlwLoopPlan> {
+	return withUlwLoopMutationLock(repoRoot, scope, async () => {
+		if (!args.force && existsSync(ulwLoopGoalsPath(repoRoot, scope))) throw new UlwLoopError(`Refusing to overwrite existing ${ulwLoopGoalsRelativePath(scope)}; pass --force to recreate it.`, "ULW_LOOP_PLAN_EXISTS");
+		const now = iso();
+		const goals = deriveGoalCandidates(args.brief).map((goal, index) => makeGoal(goal.title, goal.objective, index, now));
+		const plan: UlwLoopPlan = { version: 1, createdAt: now, updatedAt: now, briefPath: ulwLoopBriefRelativePath(scope), goalsPath: ulwLoopGoalsRelativePath(scope), ledgerPath: ulwLoopLedgerRelativePath(scope), codexGoalMode: args.codexGoalMode ?? "aggregate", goals };
+		if (plan.codexGoalMode === "aggregate") plan.codexObjective = aggregateCodexObjectiveForScope(scope);
+		await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
+		await writeFile(ulwLoopBriefPath(repoRoot, scope), args.brief.endsWith("\n") ? args.brief : `${args.brief}\n`, "utf8");
+		await writePlan(repoRoot, plan, scope);
+		await writeFile(ulwLoopLedgerPath(repoRoot, scope), "", "utf8");
+		await appendLedger(repoRoot, { at: now, kind: "plan_created", message: `${goals.length} goal(s) created` }, scope);
+		return plan;
+	});
+}
+
+export async function addUlwLoopGoal(repoRoot: string, args: { title: string; objective: string }, scope?: UlwLoopScope): Promise<{ plan: UlwLoopPlan; goal: UlwLoopItem }> {
+	return withUlwLoopMutationLock(repoRoot, scope, async () => {
+		const plan = await readUlwLoopPlan(repoRoot, scope);
+		const now = iso();
+		const goal = appendGoalToPlan(plan, args.title, args.objective, now);
+		await writePlan(repoRoot, plan, scope);
+		await appendLedger(repoRoot, { at: now, kind: "goal_added", goalId: goal.id, status: goal.status, message: goal.title }, scope);
+		return { plan, goal };
+	});
+}
+
+export async function startNextUlwLoop(repoRoot: string, args: { retryFailed?: boolean } = {}, scope?: UlwLoopScope): Promise<{ plan: UlwLoopPlan; goal: UlwLoopItem; resumed: boolean } | { done: true; plan: UlwLoopPlan }> {
+	return withUlwLoopMutationLock(repoRoot, scope, async () => {
+		const plan = await readUlwLoopPlan(repoRoot, scope);
+		const now = iso();
+		if (plan.aggregateCompletion?.status === "complete") return { done: true, plan };
+		const existing = plan.goals.find((goal) => goal.status === "in_progress" && isScheduleEligible(goal));
+		if (existing) { await appendLedger(repoRoot, { at: now, kind: "goal_resumed", goalId: existing.id, status: existing.status, message: "Resuming active ulw-loop" }, scope); return { plan, goal: existing, resumed: true }; }
+		let next = plan.goals.find((goal) => goal.status === "pending" && isScheduleEligible(goal));
+		if (!next && args.retryFailed) {
+			next = plan.goals.find((goal) => goal.status === "failed" && !goal.nonRetriable && isScheduleEligible(goal));
+			if (next) await appendLedger(repoRoot, { at: now, kind: "goal_retried", goalId: next.id, status: "pending", ...(next.failureReason ? { message: next.failureReason } : {}) }, scope);
+		}
+		if (!next) return { done: true, plan };
+		next.status = "in_progress";
+		next.attempt += 1;
+		next.startedAt = now;
+		clearGoalBlockerFields(next);
+		next.updatedAt = now;
+		plan.activeGoalId = next.id;
+		plan.updatedAt = now;
+		await writePlan(repoRoot, plan, scope);
+		await appendLedger(repoRoot, { at: now, kind: "goal_started", goalId: next.id, status: next.status, message: `Attempt ${next.attempt}` }, scope);
+		return { plan, goal: next, resumed: false };
+	});
+}
+
+export function summarizeUlwLoopPlan(plan: UlwLoopPlan): UlwLoopPlanSummary {
+	const countStatus = (status: UlwLoopItem["status"]): number => plan.goals.filter((goal) => goal.status === status).length;
+	const countCriteria = (status: UlwLoopSuccessCriterion["status"]): number => plan.goals.reduce((sum, goal) => sum + goal.successCriteria.filter((criterion) => criterion.status === status).length, 0);
+	return { total: plan.goals.length, pending: countStatus("pending"), in_progress: countStatus("in_progress"), complete: countStatus("complete"), failed: countStatus("failed"), blocked: countStatus("blocked"), review_blocked: countStatus("review_blocked"), needs_user_decision: countStatus("needs_user_decision"), superseded: plan.goals.filter((goal) => goal.steeringStatus === "superseded").length, criteria: { total: plan.goals.reduce((sum, goal) => sum + goal.successCriteria.length, 0), pass: countCriteria("pass"), pending: countCriteria("pending"), fail: countCriteria("fail"), blocked: countCriteria("blocked") } };
+}