oh-my-opencode 4.5.1 → 4.5.12

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

@@ -0,0 +1,124 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+
+import { aggregateCodexObjectiveForScope } from "./goal-status.js";
+import {
+	repoRelative,
+	type UlwLoopScope,
+	ulwLoopDir,
+	ulwLoopGoalsPath,
+	ulwLoopLedgerPath,
+	ulwLoopRelativeDir,
+} from "./paths.js";
+import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
+import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
+
+const LEGACY_OBJECTIVE_PREFIX = `Complete all ulw-loop stories in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}: `;
+const LEGACY_OBJECTIVE = `Complete all ulw-loop stories listed in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}. Use ${ULW_LOOP_DIR}/${ULW_LOOP_LEDGER} as the durable audit trail.`;
+const locks = new Map<string, Promise<unknown>>();
+
+function hasCode(error: unknown, code: string): boolean {
+	return error instanceof Error && "code" in error && error.code === code;
+}
+
+function isLegacyEnumeratedAggregateObjective(objective: string | undefined): objective is string {
+	return objective === LEGACY_OBJECTIVE || Boolean(objective?.startsWith(LEGACY_OBJECTIVE_PREFIX));
+}
+
+function isSteeringKind(value: unknown): value is UlwLoopLedgerEntry["kind"] {
+	return value === "steering_accepted" || value === "steering_rejected" || value === "criteria_revised";
+}
+
+export async function withUlwLoopMutationLock<T>(repoRoot: string, fn: () => Promise<T>): Promise<T>;
+export async function withUlwLoopMutationLock<T>(
+	repoRoot: string,
+	scope: UlwLoopScope | undefined,
+	fn: () => Promise<T>,
+): Promise<T>;
+export async function withUlwLoopMutationLock<T>(
+	repoRoot: string,
+	scopeOrFn: UlwLoopScope | (() => Promise<T>) | undefined,
+	maybeFn?: () => Promise<T>,
+): Promise<T> {
+	const scope = typeof scopeOrFn === "function" ? undefined : scopeOrFn;
+	const fn = typeof scopeOrFn === "function" ? scopeOrFn : maybeFn;
+	if (fn === undefined) throw new UlwLoopError("Missing ulw-loop mutation body.", "ULW_LOOP_LOCK_BODY_MISSING");
+	const lockKey = `${repoRoot}\0${ulwLoopRelativeDir(scope)}`;
+	const prior = locks.get(lockKey) ?? Promise.resolve();
+	const run = prior.then(fn, fn);
+	locks.set(
+		lockKey,
+		run.catch(() => undefined),
+	);
+	return run;
+}
+
+export async function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopPlan> {
+	const path = ulwLoopGoalsPath(repoRoot, scope);
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		if (!hasCode(error, "ENOENT")) throw error;
+		throw new UlwLoopError(
+			`No ulw-loop plan found at ${repoRelative(path, repoRoot)}. Run \`omo ulw-loop create-goals ...\` first.`,
+			"ULW_LOOP_PLAN_MISSING",
+			{ cause: error },
+		);
+	}
+	const parsed: UlwLoopPlan = JSON.parse(raw);
+	if (parsed.version !== 1 || !Array.isArray(parsed.goals)) {
+		throw new UlwLoopError(`Invalid ulw-loop plan at ${repoRelative(path, repoRoot)}.`, "ULW_LOOP_PLAN_INVALID");
+	}
+	const previousObjective = parsed.codexObjective;
+	if (
+		(parsed.codexGoalMode ?? "per_story") === "aggregate" &&
+		isLegacyEnumeratedAggregateObjective(previousObjective)
+	) {
+		const now = iso();
+		parsed.codexObjective = aggregateCodexObjectiveForScope(scope);
+		parsed.codexObjectiveAliases = [...new Set([...(parsed.codexObjectiveAliases ?? []), previousObjective])];
+		parsed.updatedAt = now;
+		await writePlan(repoRoot, parsed, scope);
+		await appendLedger(
+			repoRoot,
+			{
+				at: now,
+				kind: "aggregate_objective_migrated",
+				message: "Migrated legacy enumerated aggregate Codex objective to the stable pointer objective.",
+				before: { codexObjective: previousObjective },
+				after: { codexObjective: parsed.codexObjective },
+			},
+			scope,
+		);
+	}
+	return parsed;
+}
+
+export async function writePlan(repoRoot: string, plan: UlwLoopPlan, scope?: UlwLoopScope): Promise<void> {
+	await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
+	const path = ulwLoopGoalsPath(repoRoot, scope);
+	const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+	await writeFile(tmpPath, `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+	await rename(tmpPath, path);
+}
+
+export async function appendLedger(repoRoot: string, entry: UlwLoopLedgerEntry, scope?: UlwLoopScope): Promise<void> {
+	await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
+	await appendFile(ulwLoopLedgerPath(repoRoot, scope), `${JSON.stringify(entry)}\n`, "utf8");
+}
+
+export async function readSteeringLedgerEntries(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopLedgerEntry[]> {
+	let raw: string;
+	try {
+		raw = await readFile(ulwLoopLedgerPath(repoRoot, scope), "utf8");
+	} catch (error) {
+		if (hasCode(error, "ENOENT")) return [];
+		throw error;
+	}
+	const entries: UlwLoopLedgerEntry[] = [];
+	for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+		const entry: UlwLoopLedgerEntry = JSON.parse(line);
+		if (isSteeringKind(entry.kind)) entries.push(entry);
+	}
+	return entries;
+}

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

@@ -0,0 +1,102 @@
+import type { UlwLoopItem, UlwLoopPlan, UlwLoopQualityGate } from "./types.js";
+import { UlwLoopError } from "./types.js";
+
+const BLOCKER_FIELD_KEYS = "blocker blockerSignature blockerEvidence blockerOccurrences blockedAt".split(" ");
+const URL_PATTERN = /https?:\/\/\S+/g;
+const PUNCTUATION_PATTERN = /[`"'()[\]{}:,;]/g;
+const WHITESPACE_PATTERN = /\s+/g;
+const AUTH_PATTERN = /\b(auth\w*|credential\w*|token|permission\w*|scope\w*|access|unauthorized|forbidden|401|403)\b/;
+const MISSING_PATTERN =
+	/\b(unset|missing|required|requires|without|omit\w*|not set|not available|no read packages|read packages)\b/;
+const GHCR_PATTERN =
+	/\b(ghcr|github container registry|read packages|imagepullsecret|package api|anonymous|container image)\b/;
+const GHCR_401_PATTERN = /\b(401|unauthorized|anonymous pull|authentication required)\b/;
+const GHCR_403_PATTERN = /\b(403|forbidden|read packages|package api)\b/;
+
+function invalid(message: string, field: string): never {
+	throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function section(value: unknown, field: string): Record<string, unknown> {
+	return isRecord(value) ? value : invalid(`Final quality gate is missing ${field} evidence.`, field);
+}
+
+function nonEmptyString(value: unknown, field: string): string {
+	return typeof value === "string" && value.trim() !== ""
+		? value
+		: invalid(`Final quality gate requires non-empty ${field}.`, field);
+}
+
+function numberField(value: unknown, field: string): number {
+	return typeof value === "number" && Number.isFinite(value)
+		? value
+		: invalid(`Final quality gate requires numeric ${field}.`, field);
+}
+
+function stringArray(value: unknown, field: string): string[] {
+	if (!Array.isArray(value) || value.length === 0) return invalid(`Final quality gate requires ${field}.`, field);
+	return value.map((item) => nonEmptyString(item, field));
+}
+
+export function validateQualityGate(input: unknown): UlwLoopQualityGate {
+	const gate = section(input, "qualityGate");
+	const cleaner = section(gate["aiSlopCleaner"], "aiSlopCleaner");
+	const verification = section(gate["verification"], "verification");
+	const review = section(gate["codeReview"], "codeReview");
+	const coverage = section(gate["criteriaCoverage"], "criteriaCoverage");
+	if (cleaner["status"] !== "passed") invalid("aiSlopCleaner.status must be passed.", "aiSlopCleaner.status");
+	if (verification["status"] !== "passed") invalid("verification.status must be passed.", "verification.status");
+	if (review["recommendation"] !== "APPROVE") invalid("recommendation must be APPROVE.", "codeReview.recommendation");
+	if (review["architectStatus"] !== "CLEAR") invalid("architectStatus must be CLEAR.", "codeReview.architectStatus");
+	const totalCriteria = numberField(coverage["totalCriteria"], "criteriaCoverage.totalCriteria");
+	const passCount = numberField(coverage["passCount"], "criteriaCoverage.passCount");
+	if (passCount < totalCriteria)
+		invalid("criteriaCoverage.passCount must cover totalCriteria.", "criteriaCoverage.passCount");
+	const commands = stringArray(verification["commands"], "verification.commands");
+	const covered = stringArray(coverage["adversarialClassesCovered"], "criteriaCoverage.adversarialClassesCovered");
+	const cleanerEvidence = nonEmptyString(cleaner["evidence"], "aiSlopCleaner.evidence");
+	const verificationEvidence = nonEmptyString(verification["evidence"], "verification.evidence");
+	const reviewEvidence = nonEmptyString(review["evidence"], "codeReview.evidence");
+	const result: UlwLoopQualityGate = {
+		aiSlopCleaner: { status: "passed", evidence: cleanerEvidence },
+		verification: { status: "passed", commands, evidence: verificationEvidence },
+		codeReview: { recommendation: "APPROVE", architectStatus: "CLEAR", evidence: reviewEvidence },
+	};
+	Object.assign(result, { criteriaCoverage: { totalCriteria, passCount, adversarialClassesCovered: covered } });
+	return result;
+}
+
+export function normalizeBlockerEvidence(evidence: string): string {
+	const withoutUrls = evidence.toLowerCase().replace(URL_PATTERN, " ");
+	const withoutPunctuation = withoutUrls.replace(PUNCTUATION_PATTERN, " ");
+	return withoutPunctuation.replace(WHITESPACE_PATTERN, " ").trim();
+}
+
+export function classifyExternalAuthorizationBlocker(evidence: string): string | null {
+	const normalized = normalizeBlockerEvidence(evidence);
+	if (!normalized || !AUTH_PATTERN.test(normalized) || !MISSING_PATTERN.test(normalized)) return null;
+	if (!GHCR_PATTERN.test(normalized)) return "EXTERNAL_AUTHORIZATION_REQUIRED";
+	const status401 = GHCR_401_PATTERN.test(normalized) ? "HTTP_401_ANONYMOUS" : null;
+	const status403 = GHCR_403_PATTERN.test(normalized) ? "HTTP_403_NO_READ_PACKAGES" : null;
+	const status = [status401, status403].filter((part): part is string => part !== null).join("+");
+	return `GHCR_PULL_ACCESS:${status || "AUTHORIZATION_REQUIRED"}:GHCR_VISIBILITY_OR_CREDENTIAL_REQUIRED`;
+}
+
+function nestedBlockerSignature(goal: UlwLoopItem): string | null {
+	const blocker = Reflect.get(goal, "blocker");
+	const signature = isRecord(blocker) ? blocker["signature"] : null;
+	return typeof signature === "string" ? signature : null;
+}
+
+export function sameBlockerOccurrences(plan: UlwLoopPlan, signature: string): number {
+	return plan.goals.filter((goal) => goal.blockerSignature === signature || nestedBlockerSignature(goal) === signature)
+		.length;
+}
+
+export function clearGoalBlockerFields(goal: UlwLoopItem): void {
+	for (const key of BLOCKER_FIELD_KEYS) Reflect.deleteProperty(goal, key);
+}

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

@@ -0,0 +1,81 @@
+// biome-ignore-all format: compact port must stay within the requested pure LOC budget.
+
+import { readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
+import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.js";
+import type { UlwLoopScope } from "./paths.js";
+import { seedDefaultSuccessCriteria } from "./plan-crud.js";
+import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
+import { iso, UlwLoopError } from "./types.js";
+
+export interface RecordFinalReviewBlockersArgs { readonly goalId: string; readonly title: string; readonly objective: string; readonly evidence: string; readonly codexGoalJson: string }
+export interface RecordFinalReviewBlockersResult { readonly plan: UlwLoopPlan; readonly blockedGoal: UlwLoopItem; readonly newGoal: UlwLoopItem; readonly ledgerEntries: UlwLoopLedgerEntry[] }
+
+const BLOCKER_FIELDS = "blockedReason blockerSignature blockerOccurrenceCount requiredExternalDecision nonRetriable failedAt failureReason completedAt blocker blockerEvidence blockerOccurrences blockedAt".split(" ");
+
+function ulwLoopError(message: string, code: string): never {
+	throw new UlwLoopError(message, code);
+}
+
+function nextGoalId(plan: UlwLoopPlan): string {
+	const max = plan.goals.reduce((current, goal) => {
+		const digits = /^G(\d+)/u.exec(goal.id)?.[1];
+		return digits === undefined ? current : Math.max(current, Number(digits));
+	}, 0);
+	return `G${String(max + 1).padStart(3, "0")}`;
+}
+
+function appendBlockerGoal(plan: UlwLoopPlan, args: RecordFinalReviewBlockersArgs, now: string): UlwLoopItem {
+	const index = plan.goals.length;
+	const goal: UlwLoopItem = {
+		id: nextGoalId(plan),
+		title: args.title,
+		objective: args.objective,
+		status: "pending",
+		successCriteria: seedDefaultSuccessCriteria(index, args.objective),
+		attempt: 0,
+		createdAt: now,
+		updatedAt: now,
+	};
+	plan.goals.push(goal);
+	return goal;
+}
+
+export async function recordFinalReviewBlockers(
+	repoRoot: string,
+	args: RecordFinalReviewBlockersArgs,
+	scope?: UlwLoopScope,
+): Promise<RecordFinalReviewBlockersResult> {
+	return withUlwLoopMutationLock(repoRoot, scope, async () => {
+		const plan = await readUlwLoopPlan(repoRoot, scope);
+		const goal = plan.goals.find((candidate) => candidate.id === args.goalId);
+		if (goal === undefined) ulwLoopError(`Unknown ulw-loop id: ${args.goalId}`, "ulw_loop_goal_not_found");
+		if (goal.status !== "in_progress") ulwLoopError(`${goal.id} is ${goal.status}.`, "ulw_loop_goal_not_in_progress");
+		if (!isFinalRunCompletionCandidate(plan, goal)) ulwLoopError(`${goal.id} is not final.`, "ulw_loop_not_final_story");
+
+		const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
+		const aggregate = codexGoalMode(plan) === "aggregate";
+		const reconciliation = reconcileCodexGoalSnapshot(snapshot, { expectedObjective: expectedCodexObjective(plan, goal), ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}), allowedStatuses: ["active"], requireSnapshot: true, requireComplete: false });
+		if (!reconciliation.ok) ulwLoopError(reconciliation.errors.join(" "), "ulw_loop_codex_snapshot_mismatch");
+
+		const now = iso();
+		for (const field of BLOCKER_FIELDS) Reflect.deleteProperty(goal, field);
+		goal.status = "review_blocked";
+		goal.reviewBlockedAt = now;
+		goal.evidence = args.evidence;
+		goal.updatedAt = now;
+		if (plan.activeGoalId === goal.id) delete plan.activeGoalId;
+		const newGoal = appendBlockerGoal(plan, args, now);
+		plan.updatedAt = now;
+
+		const codexGoal = reconciliation.snapshot.raw;
+		const blockedEntry: UlwLoopLedgerEntry = { at: now, kind: "goal_review_blocked", goalId: goal.id, status: goal.status, evidence: args.evidence, codexGoal };
+		const addedEntry: UlwLoopLedgerEntry = { at: now, kind: "goal_added", goalId: newGoal.id, status: newGoal.status, evidence: args.evidence, message: newGoal.title };
+		const summaryEntry: UlwLoopLedgerEntry = { at: now, kind: "goal_review_blocked", goalId: goal.id, status: goal.status, evidence: args.evidence, codexGoal, message: `Review blockers recorded; appended ${newGoal.id}.` };
+		Reflect.set(summaryEntry, "kind", "blocker_recorded");
+		const ledgerEntries = [blockedEntry, addedEntry, summaryEntry];
+		await writePlan(repoRoot, plan, scope);
+		for (const entry of ledgerEntries) await appendLedger(repoRoot, entry, scope);
+		return { plan, blockedGoal: goal, newGoal, ledgerEntries };
+	});
+}

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

@@ -0,0 +1,270 @@
+// biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
+import { isUlwLoopDone } from "./goal-status.js";
+import type { UlwLoopScope } from "./paths.js";
+import { seedDefaultSuccessCriteria } from "./plan-crud.js";
+import { appendLedger, readSteeringLedgerEntries, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import type {
+	SteerUlwLoopResult,
+	UlwLoopItem,
+	UlwLoopLedgerEntry,
+	UlwLoopPlan,
+	UlwLoopSteeringAudit,
+	UlwLoopSteeringChildGoal,
+	UlwLoopSteeringMutationKind,
+	UlwLoopSteeringProposal,
+	UlwLoopSteeringSource,
+	UlwLoopSuccessCriterionUserModel,
+} from "./types.js";
+import { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
+
+const SOURCES = ["user_prompt_submit", "finding", "cli"] as const satisfies readonly UlwLoopSteeringSource[];
+const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
+const isObject = (value: unknown): value is object => typeof value === "object" && value !== null; const isPlain = (value: unknown): value is object => isObject(value) && !Array.isArray(value);
+const read = (value: object, key: string): unknown => Object.entries(value).find(([name]) => name === key)?.[1];
+const isText = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
+const text = (value: object, key: string): string | undefined => {
+	const candidate = read(value, key);
+	return isText(candidate) ? candidate.trim() : undefined;
+};
+const isKind = (value: unknown): value is UlwLoopSteeringMutationKind => typeof value === "string" && ULW_LOOP_STEERING_MUTATION_KINDS.some((kind) => kind === value);
+const isSource = (value: unknown): value is UlwLoopSteeringSource => typeof value === "string" && SOURCES.some((source) => source === value);
+const isModel = (value: unknown): value is UlwLoopSuccessCriterionUserModel => typeof value === "string" && ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value);
+const texts = (value: object, key: string): string[] => {
+	const candidate = read(value, key);
+	return Array.isArray(candidate) && candidate.every((item) => typeof item === "string") ? candidate : [];
+};
+
+function targets(proposal: object): string[] {
+	const many = texts(proposal, "targetGoalIds");
+	const one = text(proposal, "targetGoalId") ?? text(proposal, "goalId");
+	return many.length > 0 ? many : one === undefined ? [] : [one];
+}
+
+const after = (proposal: object): object | undefined => {
+	const candidate = read(proposal, "after");
+	return isPlain(candidate) ? candidate : undefined;
+};
+const revised = (proposal: object, direct: string, nested: string): string | undefined => text(proposal, direct) ?? text(after(proposal) ?? proposal, nested);
+
+function child(value: unknown): UlwLoopSteeringChildGoal | null {
+	if (!isPlain(value)) return null;
+	const title = text(value, "title");
+	const objective = text(value, "objective");
+	if (title === undefined || objective === undefined) return null;
+	return { title, objective };
+}
+
+function childValues(proposal: object): unknown[] {
+	const direct = read(proposal, "childGoals");
+	if (Array.isArray(direct) && direct.length > 0) return direct;
+	const nested = after(proposal);
+	const fromAfter = nested === undefined ? undefined : read(nested, "children");
+	return Array.isArray(fromAfter) ? fromAfter : [];
+}
+
+const children = (proposal: object): UlwLoopSteeringChildGoal[] => childValues(proposal).map(child).filter((item): item is UlwLoopSteeringChildGoal => item !== null);
+const pendingOrder = (proposal: object): string[] => {
+	const direct = texts(proposal, "pendingOrder");
+	return direct.length > 0 ? direct : texts(after(proposal) ?? proposal, "pendingGoalIds");
+};
+
+function hasProtected(value: unknown): boolean {
+	if (!isObject(value)) return false;
+	for (const [key, childValue] of Object.entries(value)) if (PROTECTED.has(key) || key.toLowerCase().includes("complete") || hasProtected(childValue)) return true;
+	return false;
+}
+
+function allText(value: unknown): string {
+	if (typeof value === "string") return value;
+	return isObject(value) ? Object.values(value).map(allText).filter(Boolean).join("\n") : "";
+}
+
+function weakens(value: unknown): boolean {
+	const valueText = allText(value).toLowerCase();
+	return /\b(skip|bypass|weaken|remove|omit|auto[-\s]?complete|mark complete|complete faster)\b/.test(valueText) && /\b(test|tests|verification|review|quality gate|complete|completion)\b/.test(valueText);
+}
+
+function auditFor(proposal: unknown, reasons: string[]): UlwLoopSteeringAudit {
+	const object = isPlain(proposal) ? proposal : undefined;
+	const kindRaw = object === undefined ? undefined : read(object, "kind");
+	const sourceRaw = object === undefined ? undefined : read(object, "source");
+	const evidence = object === undefined ? "" : (text(object, "evidence") ?? "");
+	const rationale = object === undefined ? "" : (text(object, "rationale") ?? "");
+	const audit: UlwLoopSteeringAudit = { kind: isKind(kindRaw) ? kindRaw : "annotate_ledger", source: isSource(sourceRaw) ? sourceRaw : "cli", targetGoalIds: object === undefined ? [] : targets(object), evidence, rationale, invariant: { accepted: reasons.length === 0, structuralInvariantAccepted: reasons.length === 0, evidenceBackedNecessity: evidence.length > 0 && rationale.length > 0, noEasierCompletion: !weakens(proposal), rejectedReasons: reasons, reasons } };
+	if (object === undefined) return audit;
+	const criterionId = text(object, "criterionId");
+	const directiveText = text(object, "directiveText");
+	const promptSignature = text(object, "promptSignature");
+	const idempotencyKey = text(object, "idempotencyKey");
+	if (criterionId !== undefined) audit.criterionId = criterionId;
+	if (directiveText !== undefined) audit.directiveText = directiveText;
+	if (promptSignature !== undefined) audit.promptSignature = promptSignature;
+	if (idempotencyKey !== undefined) audit.idempotencyKey = idempotencyKey;
+	return audit;
+}
+
+export function validateUlwLoopSteeringProposal(plan: UlwLoopPlan, proposal: unknown): UlwLoopSteeringAudit {
+	const reasons: string[] = [];
+	if (!isPlain(proposal)) reasons.push("proposal must be an object");
+	const object = isPlain(proposal) ? proposal : {};
+	const kind = read(object, "kind");
+	if (!isKind(kind)) reasons.push(`invalid kind: ${String(kind)}`);
+	if (!isSource(read(object, "source"))) reasons.push(`invalid source: ${String(read(object, "source"))}`);
+	if (text(object, "evidence") === undefined) reasons.push("missing evidence");
+	if (text(object, "rationale") === undefined) reasons.push("missing rationale");
+	if (hasProtected(proposal)) reasons.push("protected payload");
+	if (weakens(proposal)) reasons.push("weakened completion");
+	if (isUlwLoopDone(plan)) reasons.push("plan already complete");
+	if (isKind(kind)) validateKind(plan, object, kind, reasons);
+	return auditFor(proposal, reasons);
+}
+
+function goal(plan: UlwLoopPlan, id: string | undefined): UlwLoopItem | undefined {
+	return id === undefined ? undefined : plan.goals.find((item) => item.id === id);
+}
+
+function validateKind(plan: UlwLoopPlan, proposal: object, kind: UlwLoopSteeringMutationKind, reasons: string[]): void {
+	const target = goal(plan, targets(proposal)[0]);
+	if (kind === "add_subgoal" && (text(proposal, "title") === undefined || text(proposal, "objective") === undefined)) reasons.push("add_subgoal requires title/objective");
+	if ((kind === "split_subgoal" || kind === "revise_pending_wording" || kind === "mark_blocked_superseded") && target === undefined) reasons.push(`${kind} requires target`);
+	if ((kind === "split_subgoal" || kind === "revise_pending_wording") && target !== undefined && target.status !== "pending") reasons.push(`${kind} requires pending target`);
+	const rawChildren = childValues(proposal);
+	if (kind === "split_subgoal" && rawChildren.length === 0) reasons.push("split_subgoal requires children");
+	if ((kind === "split_subgoal" || kind === "mark_blocked_superseded") && rawChildren.some((item) => child(item) === null)) reasons.push(`${kind} children require title/objective`);
+	if (kind === "reorder_pending") validateOrder(plan, proposal, reasons);
+	if (kind === "revise_pending_wording" && revised(proposal, "revisedTitle", "title") === undefined && revised(proposal, "revisedObjective", "objective") === undefined) reasons.push("revise_pending_wording requires update");
+	if (kind === "revise_criterion") validateCriterion(plan, proposal, reasons);
+}
+
+function validateOrder(plan: UlwLoopPlan, proposal: object, reasons: string[]): void {
+	const requested = pendingOrder(proposal);
+	const pending = plan.goals.filter((item) => item.status === "pending" && item.steeringStatus === undefined).map((item) => item.id);
+	if (requested.length === 0) reasons.push("reorder_pending requires ids");
+	if (new Set(requested).size !== requested.length) reasons.push("duplicate pending id");
+	if (requested.some((id) => !pending.includes(id))) reasons.push("unknown pending id");
+}
+
+function validateCriterion(plan: UlwLoopPlan, proposal: object, reasons: string[]): void {
+	const target = goal(plan, targets(proposal)[0]);
+	const criterionId = text(proposal, "criterionId");
+	if (target === undefined) reasons.push("revise_criterion requires goalId");
+	else if (criterionId === undefined || target.successCriteria.every((item) => item.id !== criterionId)) reasons.push("revise_criterion requires criterionId");
+	const model = read(proposal, "userModel");
+	if (read(proposal, "scenario") === undefined && read(proposal, "expectedEvidence") === undefined && model === undefined) reasons.push("revise_criterion requires update");
+	if (model !== undefined && !isModel(model)) reasons.push("invalid userModel");
+}
+
+function nextId(plan: UlwLoopPlan, offset: number): string {
+	const max = plan.goals.reduce((current, item) => {
+		const digits = /^G(\d+)(?:-|$)/u.exec(item.id)?.[1];
+		return digits === undefined ? current : Math.max(current, Number(digits));
+	}, 0);
+	return `G${String(max + offset).padStart(3, "0")}`;
+}
+
+function makeGoal(plan: UlwLoopPlan, childGoal: UlwLoopSteeringChildGoal, evidence: string, now: string, offset: number): UlwLoopItem {
+	const id = nextId(plan, offset);
+	const digits = /^G(\d+)/u.exec(id)?.[1];
+	const goalIndex = digits === undefined ? plan.goals.length + offset - 1 : Number(digits) - 1;
+	return { id, title: childGoal.title, objective: childGoal.objective, status: "pending", successCriteria: seedDefaultSuccessCriteria(goalIndex, childGoal.objective), attempt: 0, createdAt: now, updatedAt: now, evidence };
+}
+
+export function applySteeringMutation(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit): UlwLoopPlan {
+	const next = structuredClone(plan);
+	if (!audit.invariant.accepted) return next;
+	const now = proposal.now?.toISOString() ?? iso();
+	if (proposal.kind === "add_subgoal") next.goals.push(makeGoal(next, { title: proposal.title ?? "", objective: proposal.objective ?? "" }, proposal.evidence, now, 1));
+	if (proposal.kind === "reorder_pending") {
+		const order = pendingOrder(proposal);
+		next.goals = [...order.map((id) => goal(next, id)).filter((item): item is UlwLoopItem => item !== undefined), ...next.goals.filter((item) => !order.includes(item.id))];
+	}
+	if (proposal.kind === "revise_pending_wording") reviseWording(next, proposal, now);
+	if (proposal.kind === "split_subgoal" || proposal.kind === "mark_blocked_superseded") splitOrBlock(next, proposal, now);
+	if (proposal.kind === "revise_criterion") reviseCriterion(next, proposal, now);
+	if (proposal.kind !== "annotate_ledger") next.updatedAt = now;
+	return next;
+}
+
+function reviseWording(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
+	const target = goal(plan, targets(proposal)[0]);
+	if (target === undefined) return;
+	target.title = revised(proposal, "revisedTitle", "title") ?? target.title;
+	target.objective = revised(proposal, "revisedObjective", "objective") ?? target.objective;
+	target.steeringEvidence = proposal.evidence;
+	target.steeringRationale = proposal.rationale;
+	target.updatedAt = now;
+}
+
+function splitOrBlock(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
+	const target = goal(plan, targets(proposal)[0]);
+	if (target === undefined) return;
+	const replacements = children(proposal).map((item, index) => makeGoal(plan, item, proposal.evidence, now, index + 1));
+	target.steeringEvidence = proposal.evidence;
+	target.steeringRationale = proposal.rationale;
+	target.updatedAt = now;
+	if (replacements.length === 0) {
+		target.status = "blocked";
+		target.steeringStatus = "blocked";
+		target.blockedReason = proposal.blockedReason ?? proposal.rationale;
+	} else {
+		target.steeringStatus = "superseded";
+		target.supersededBy = replacements.map((item) => item.id);
+		for (const item of replacements) item.supersedes = [target.id];
+		plan.goals.splice(plan.goals.indexOf(target) + 1, 0, ...replacements);
+	}
+	if (plan.activeGoalId === target.id) delete plan.activeGoalId;
+}
+
+function reviseCriterion(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, now: string): void {
+	const target = goal(plan, targets(proposal)[0]);
+	const index = target?.successCriteria.findIndex((item) => item.id === proposal.criterionId) ?? -1;
+	const current = target?.successCriteria[index];
+	if (target === undefined || current === undefined) return;
+	const model = read(proposal, "userModel");
+	target.successCriteria[index] = { ...current, scenario: text(proposal, "scenario") ?? current.scenario, expectedEvidence: text(proposal, "expectedEvidence") ?? current.expectedEvidence, userModel: isModel(model) ? model : current.userModel };
+	target.updatedAt = now;
+}
+
+function isProposal(value: unknown): value is UlwLoopSteeringProposal {
+	return isPlain(value) && isKind(read(value, "kind")) && isSource(read(value, "source")) && isText(read(value, "evidence")) && isText(read(value, "rationale"));
+}
+
+export function parseUlwLoopSteeringDirective(text: string): UlwLoopSteeringProposal | null {
+	const match = /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer):\s*([\s\S]+)$/u.exec(text);
+	if (match?.[1] === undefined) return null;
+	try {
+		const parsed: unknown = JSON.parse(match[1].trim());
+		return isProposal(parsed) ? parsed : null;
+	} catch (error) {
+		if (error instanceof SyntaxError) return null;
+		throw error;
+	}
+}
+
+export async function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringProposal, scope?: UlwLoopScope): Promise<SteerUlwLoopResult> {
+	return withUlwLoopMutationLock(repoRoot, scope, async () => {
+		const plan = await readUlwLoopPlan(repoRoot, scope);
+		const key = proposal.idempotencyKey ?? proposal.promptSignature;
+		const prior = key === undefined ? undefined : (await readSteeringLedgerEntries(repoRoot, scope)).find((entry) => entry.steering?.invariant.accepted === true && (entry.idempotencyKey === key || entry.steering.idempotencyKey === key || entry.steering.promptSignature === key));
+		if (prior?.steering !== undefined) return { plan, accepted: true, audit: { ...prior.steering, deduped: true }, rejectedReasons: [], deduped: true };
+		const audit = validateUlwLoopSteeringProposal(plan, proposal);
+		const accepted = audit.invariant.accepted;
+		const next = accepted ? applySteeringMutation(plan, proposal, audit) : plan;
+		const finalAudit: UlwLoopSteeringAudit = { ...audit, before: plan };
+		if (accepted) finalAudit.after = next;
+		if (accepted) await writePlan(repoRoot, next, scope);
+		await appendLedger(repoRoot, ledgerEntry(proposal, finalAudit, proposal.now?.toISOString() ?? iso()), scope);
+		return { plan: next, accepted, audit: finalAudit, rejectedReasons: audit.invariant.rejectedReasons, deduped: false };
+	});
+}
+
+function ledgerEntry(proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit, at: string): UlwLoopLedgerEntry {
+	const entry: UlwLoopLedgerEntry = { at, kind: audit.invariant.accepted ? (proposal.kind === "revise_criterion" ? "criteria_revised" : "steering_accepted") : "steering_rejected", evidence: proposal.evidence, message: proposal.rationale, steering: audit, mutationKind: proposal.kind };
+	const goalId = audit.targetGoalIds[0];
+	if (goalId !== undefined) entry.goalId = goalId;
+	if (proposal.criterionId !== undefined) entry.criterionId = proposal.criterionId;
+	if (proposal.idempotencyKey !== undefined) entry.idempotencyKey = proposal.idempotencyKey;
+	if (audit.before !== undefined) entry.before = audit.before;
+	if (audit.after !== undefined) entry.after = audit.after;
+	return entry;
+}