oh-my-opencode 4.8.1 → 4.9.1

package/packages/omo-codex/plugin/components/ulw-loop/dist/goal-status.js

@@ -0,0 +1,69 @@
+import { ulwLoopGoalsRelativePath, ulwLoopLedgerRelativePath } from "./paths.js";
+export const ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE = aggregateCodexObjectiveForScope();
+export function aggregateCodexObjectiveForScope(scope) {
+    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) {
+    return plan.codexGoalMode ?? "per_story";
+}
+function isResolvedStatus(status) {
+    return status === "complete";
+}
+function isSupersededResolved(goal, plan) {
+    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, plan) {
+    if (goal.steeringStatus === "superseded")
+        return !isSupersededResolved(goal, plan);
+    if (goal.steeringStatus === "blocked")
+        return true;
+    return !isResolvedStatus(goal.status);
+}
+function isCompletionBlockingForFinalCandidate(candidate, finalCandidate, plan) {
+    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) {
+    if (plan.aggregateCompletion?.status === "complete")
+        return true;
+    return plan.goals.every((goal) => !isCompletionBlocking(goal, plan));
+}
+export function isFinalRunCompletionCandidate(plan, goal) {
+    return (isCompletionBlocking(goal, plan) &&
+        plan.goals.every((candidate) => !isCompletionBlockingForFinalCandidate(candidate, goal, plan)));
+}
+export function aggregateCodexObjective(plan) {
+    return plan.codexObjective ?? ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE;
+}
+export function expectedCodexObjective(plan, goal) {
+    return codexGoalMode(plan) === "aggregate" ? aggregateCodexObjective(plan) : goal.objective;
+}
+export function compatibleCodexObjectives(plan) {
+    return [aggregateCodexObjective(plan), ...(plan.codexObjectiveAliases ?? [])];
+}
+export function hasAllCriteriaPass(goal) {
+    return goal.successCriteria.length > 0 && goal.successCriteria.every((criterion) => criterion.status === "pass");
+}
+export function firstUnresolvedCriterion(goal) {
+    return goal.successCriteria.find((criterion) => criterion.status !== "pass");
+}

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

@@ -0,0 +1,16 @@
+export interface UlwLoopScope {
+    readonly sessionId?: string | null;
+}
+type EnvMap = Readonly<Record<string, string | undefined>>;
+export declare function normalizeUlwLoopSessionId(sessionId: string | null | undefined): string | null;
+export declare function resolveUlwLoopSessionIdFromEnv(env?: EnvMap): string | null;
+export declare function ulwLoopRelativeDir(scope?: UlwLoopScope): string;
+export declare function ulwLoopDir(repoRoot: string, scope?: UlwLoopScope): string;
+export declare function ulwLoopBriefRelativePath(scope?: UlwLoopScope): string;
+export declare function ulwLoopGoalsRelativePath(scope?: UlwLoopScope): string;
+export declare function ulwLoopLedgerRelativePath(scope?: UlwLoopScope): string;
+export declare function ulwLoopBriefPath(repoRoot: string, scope?: UlwLoopScope): string;
+export declare function ulwLoopGoalsPath(repoRoot: string, scope?: UlwLoopScope): string;
+export declare function ulwLoopLedgerPath(repoRoot: string, scope?: UlwLoopScope): string;
+export declare function repoRelative(absolutePath: string, repoRoot: string): string;
+export {};

package/packages/omo-codex/plugin/components/ulw-loop/dist/paths.js

@@ -0,0 +1,59 @@
+import { join } from "node:path";
+import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"];
+export function normalizeUlwLoopSessionId(sessionId) {
+    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 = process.env) {
+    for (const key of SESSION_ENV_KEYS) {
+        const normalized = normalizeUlwLoopSessionId(env[key]);
+        if (normalized !== null)
+            return normalized;
+    }
+    return null;
+}
+export function ulwLoopRelativeDir(scope) {
+    const sessionId = normalizeUlwLoopSessionId(scope?.sessionId);
+    return sessionId === null ? ULW_LOOP_DIR : `${ULW_LOOP_DIR}/${sessionId}`;
+}
+export function ulwLoopDir(repoRoot, scope) {
+    return join(repoRoot, ulwLoopRelativeDir(scope));
+}
+export function ulwLoopBriefRelativePath(scope) {
+    return `${ulwLoopRelativeDir(scope)}/${ULW_LOOP_BRIEF}`;
+}
+export function ulwLoopGoalsRelativePath(scope) {
+    return `${ulwLoopRelativeDir(scope)}/${ULW_LOOP_GOALS}`;
+}
+export function ulwLoopLedgerRelativePath(scope) {
+    return `${ulwLoopRelativeDir(scope)}/${ULW_LOOP_LEDGER}`;
+}
+export function ulwLoopBriefPath(repoRoot, scope) {
+    return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_BRIEF);
+}
+export function ulwLoopGoalsPath(repoRoot, scope) {
+    return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_GOALS);
+}
+export function ulwLoopLedgerPath(repoRoot, scope) {
+    return join(ulwLoopDir(repoRoot, scope), ULW_LOOP_LEDGER);
+}
+export function repoRelative(absolutePath, repoRoot) {
+    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/dist/plan-crud.d.ts

@@ -0,0 +1,48 @@
+import { type UlwLoopScope } from "./paths.js";
+import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } 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;
+    };
+};
+export declare function seedDefaultSuccessCriteria(goalIndex: number, objective: string): UlwLoopSuccessCriterion[];
+export declare function deriveGoalCandidates(brief: string): Array<{
+    title: string;
+    objective: string;
+}>;
+export declare function createUlwLoopPlan(repoRoot: string, args: {
+    brief: string;
+    codexGoalMode?: UlwLoopCodexGoalMode;
+    force?: boolean;
+}, scope?: UlwLoopScope): Promise<UlwLoopPlan>;
+export declare function addUlwLoopGoal(repoRoot: string, args: {
+    title: string;
+    objective: string;
+}, scope?: UlwLoopScope): Promise<{
+    plan: UlwLoopPlan;
+    goal: UlwLoopItem;
+}>;
+export declare function startNextUlwLoop(repoRoot: string, args?: {
+    retryFailed?: boolean;
+}, scope?: UlwLoopScope): Promise<{
+    plan: UlwLoopPlan;
+    goal: UlwLoopItem;
+    resumed: boolean;
+} | {
+    done: true;
+    plan: UlwLoopPlan;
+}>;
+export declare function summarizeUlwLoopPlan(plan: UlwLoopPlan): UlwLoopPlanSummary;

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-crud.js

@@ -0,0 +1,119 @@
+// 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, isUlwLoopDone } from "./goal-status.js";
+import { ulwLoopBriefPath, ulwLoopBriefRelativePath, ulwLoopDir, ulwLoopGoalsPath, ulwLoopGoalsRelativePath, ulwLoopLedgerPath, ulwLoopLedgerRelativePath } from "./paths.js";
+import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { iso, UlwLoopError } from "./types.js";
+function cleanLine(line) { return line.replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, "").trim(); }
+function normalizeObjective(value) { return value.replace(/\s+/g, " ").trim(); }
+function titleFromObjective(objective, fallback) { 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, index) { 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, label) { const trimmed = value?.trim(); if (!trimmed)
+    throw new UlwLoopError(`Missing ${label}.`, "ULW_LOOP_ARGUMENT_MISSING"); return trimmed; }
+function truncateObjective(objective) { return objective.length > 80 ? `${objective.slice(0, 77).trimEnd()}...` : objective; }
+export function seedDefaultSuccessCriteria(goalIndex, objective) {
+    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}.`],
+    ];
+    return rows.map(([id, userModel, scenario, expectedEvidence]) => ({ id, scenario, userModel, expectedEvidence, capturedEvidence: null, status: "pending" }));
+}
+export function deriveGoalCandidates(brief) {
+    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, objective, index, now) {
+    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, title, objective, now) {
+    const goal = makeGoal(title, objective, plan.goals.length, now);
+    plan.goals.push(goal);
+    plan.updatedAt = now;
+    return goal;
+}
+function isScheduleEligible(goal) { return goal.steeringStatus !== "superseded" && goal.steeringStatus !== "blocked"; }
+function clearGoalBlockerFields(goal) {
+    for (const key of ["blockedReason", "blockerSignature", "blockerOccurrenceCount", "requiredExternalDecision", "nonRetriable", "failedAt", "failureReason"])
+        delete goal[key];
+}
+export async function createUlwLoopPlan(repoRoot, args, scope) {
+    return withUlwLoopMutationLock(repoRoot, scope, async () => {
+        if (!args.force && existsSync(ulwLoopGoalsPath(repoRoot, scope))) {
+            const existing = await readUlwLoopPlan(repoRoot, scope);
+            if (isUlwLoopDone(existing))
+                throw completedPlanExistsError(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 = { 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;
+    });
+}
+function completedPlanExistsError(scope) {
+    return new UlwLoopError([
+        `Existing ulw-loop aggregate is already complete at ${ulwLoopGoalsRelativePath(scope)}.`,
+        "Start a new run with `omo ulw-loop create-goals --session-id <new-id> ...` to isolate fresh state.",
+        "Use --force only when you intentionally want to overwrite the completed evidence.",
+    ].join(" "), "ULW_LOOP_PLAN_EXISTS_COMPLETE");
+}
+export async function addUlwLoopGoal(repoRoot, args, scope) {
+    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, args = {}, scope) {
+    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) {
+    const countStatus = (status) => plan.goals.filter((goal) => goal.status === status).length;
+    const countCriteria = (status) => 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") } };
+}

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

@@ -0,0 +1,8 @@
+import { type UlwLoopScope } from "./paths.js";
+import type { UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
+export declare function withUlwLoopMutationLock<T>(repoRoot: string, fn: () => Promise<T>): Promise<T>;
+export declare function withUlwLoopMutationLock<T>(repoRoot: string, scope: UlwLoopScope | undefined, fn: () => Promise<T>): Promise<T>;
+export declare function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopPlan>;
+export declare function writePlan(repoRoot: string, plan: UlwLoopPlan, scope?: UlwLoopScope): Promise<void>;
+export declare function appendLedger(repoRoot: string, entry: UlwLoopLedgerEntry, scope?: UlwLoopScope): Promise<void>;
+export declare function readSteeringLedgerEntries(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopLedgerEntry[]>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-io.js

@@ -0,0 +1,89 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { aggregateCodexObjectiveForScope } from "./goal-status.js";
+import { repoRelative, ulwLoopDir, ulwLoopGoalsPath, ulwLoopLedgerPath, ulwLoopRelativeDir, } from "./paths.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();
+function hasCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function isLegacyEnumeratedAggregateObjective(objective) {
+    return objective === LEGACY_OBJECTIVE || Boolean(objective?.startsWith(LEGACY_OBJECTIVE_PREFIX));
+}
+function isSteeringKind(value) {
+    return value === "steering_accepted" || value === "steering_rejected" || value === "criteria_revised";
+}
+export async function withUlwLoopMutationLock(repoRoot, scopeOrFn, maybeFn) {
+    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, scope) {
+    const path = ulwLoopGoalsPath(repoRoot, scope);
+    let raw;
+    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 = 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, plan, scope) {
+    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, entry, scope) {
+    await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
+    await appendFile(ulwLoopLedgerPath(repoRoot, scope), `${JSON.stringify(entry)}\n`, "utf8");
+}
+export async function readSteeringLedgerEntries(repoRoot, scope) {
+    let raw;
+    try {
+        raw = await readFile(ulwLoopLedgerPath(repoRoot, scope), "utf8");
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return [];
+        throw error;
+    }
+    const entries = [];
+    for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+        const entry = JSON.parse(line);
+        if (isSteeringKind(entry.kind))
+            entries.push(entry);
+    }
+    return entries;
+}

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

@@ -0,0 +1,6 @@
+import type { UlwLoopItem, UlwLoopPlan, UlwLoopQualityGate } from "./types.js";
+export declare function validateQualityGate(input: unknown): UlwLoopQualityGate;
+export declare function normalizeBlockerEvidence(evidence: string): string;
+export declare function classifyExternalAuthorizationBlocker(evidence: string): string | null;
+export declare function sameBlockerOccurrences(plan: UlwLoopPlan, signature: string): number;
+export declare function clearGoalBlockerFields(goal: UlwLoopItem): void;

package/packages/omo-codex/plugin/components/ulw-loop/dist/quality-gate.js

@@ -0,0 +1,123 @@
+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/;
+const UNCONDITIONAL_APPROVAL_PATTERN = /\bUNCONDITIONAL\s+APPROVAL\b/i;
+function invalid(message, field) {
+    throw new UlwLoopError(message, "ULW_LOOP_QUALITY_GATE_INVALID", { details: { field } });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function section(value, field) {
+    return isRecord(value) ? value : invalid(`Final quality gate is missing ${field} evidence.`, field);
+}
+function nonEmptyString(value, field) {
+    return typeof value === "string" && value.trim() !== ""
+        ? value
+        : invalid(`Final quality gate requires non-empty ${field}.`, field);
+}
+function numberField(value, field) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : invalid(`Final quality gate requires numeric ${field}.`, field);
+}
+function stringArray(value, field) {
+    if (!Array.isArray(value) || value.length === 0)
+        return invalid(`Final quality gate requires ${field}.`, field);
+    return value.map((item) => nonEmptyString(item, field));
+}
+function normalizeReviewerField({ value, field, expectedValue, evidenceApproved, }) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed === "") {
+            if (evidenceApproved)
+                return expectedValue;
+            invalid(`${field} must be ${expectedValue} or codeReview.evidence should include UNCONDITIONAL APPROVAL.`, field);
+        }
+        if (trimmed === expectedValue)
+            return expectedValue;
+        invalid(`${field} must be ${expectedValue}.`, field);
+    }
+    if (value === undefined) {
+        if (evidenceApproved)
+            return expectedValue;
+        invalid(`${field} must be ${expectedValue} or codeReview.evidence should include UNCONDITIONAL APPROVAL.`, field);
+    }
+    invalid(`${field} must be ${expectedValue}.`, field);
+}
+export function validateQualityGate(input) {
+    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");
+    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 approvalEvidence = UNCONDITIONAL_APPROVAL_PATTERN.test(reviewEvidence);
+    const recommendation = normalizeReviewerField({
+        value: review["recommendation"],
+        field: "codeReview.recommendation",
+        expectedValue: "APPROVE",
+        evidenceApproved: approvalEvidence,
+    });
+    const architectStatus = normalizeReviewerField({
+        value: review["architectStatus"],
+        field: "codeReview.architectStatus",
+        expectedValue: "CLEAR",
+        evidenceApproved: approvalEvidence,
+    });
+    const result = {
+        aiSlopCleaner: { status: "passed", evidence: cleanerEvidence },
+        verification: { status: "passed", commands, evidence: verificationEvidence },
+        codeReview: { recommendation, architectStatus, evidence: reviewEvidence },
+    };
+    Object.assign(result, { criteriaCoverage: { totalCriteria, passCount, adversarialClassesCovered: covered } });
+    return result;
+}
+export function normalizeBlockerEvidence(evidence) {
+    const withoutUrls = evidence.toLowerCase().replace(URL_PATTERN, " ");
+    const withoutPunctuation = withoutUrls.replace(PUNCTUATION_PATTERN, " ");
+    return withoutPunctuation.replace(WHITESPACE_PATTERN, " ").trim();
+}
+export function classifyExternalAuthorizationBlocker(evidence) {
+    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 !== null).join("+");
+    return `GHCR_PULL_ACCESS:${status || "AUTHORIZATION_REQUIRED"}:GHCR_VISIBILITY_OR_CREDENTIAL_REQUIRED`;
+}
+function nestedBlockerSignature(goal) {
+    const blocker = Reflect.get(goal, "blocker");
+    const signature = isRecord(blocker) ? blocker["signature"] : null;
+    return typeof signature === "string" ? signature : null;
+}
+export function sameBlockerOccurrences(plan, signature) {
+    return plan.goals.filter((goal) => goal.blockerSignature === signature || nestedBlockerSignature(goal) === signature)
+        .length;
+}
+export function clearGoalBlockerFields(goal) {
+    for (const key of BLOCKER_FIELD_KEYS)
+        Reflect.deleteProperty(goal, key);
+}

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

@@ -0,0 +1,16 @@
+import type { UlwLoopScope } from "./paths.js";
+import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan } 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[];
+}
+export declare function recordFinalReviewBlockers(repoRoot: string, args: RecordFinalReviewBlockersArgs, scope?: UlwLoopScope): Promise<RecordFinalReviewBlockersResult>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/review-blockers.js

@@ -0,0 +1,70 @@
+// 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 { seedDefaultSuccessCriteria } from "./plan-crud.js";
+import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { iso, UlwLoopError } from "./types.js";
+const BLOCKER_FIELDS = "blockedReason blockerSignature blockerOccurrenceCount requiredExternalDecision nonRetriable failedAt failureReason completedAt blocker blockerEvidence blockerOccurrences blockedAt".split(" ");
+function ulwLoopError(message, code) {
+    throw new UlwLoopError(message, code);
+}
+function nextGoalId(plan) {
+    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, args, now) {
+    const index = plan.goals.length;
+    const goal = {
+        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, args, scope) {
+    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 = { at: now, kind: "goal_review_blocked", goalId: goal.id, status: goal.status, evidence: args.evidence, codexGoal };
+        const addedEntry = { at: now, kind: "goal_added", goalId: newGoal.id, status: newGoal.status, evidence: args.evidence, message: newGoal.title };
+        const summaryEntry = { 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/dist/runtime.d.ts

@@ -0,0 +1,10 @@
+export interface UlwLoopErrorOptions {
+    readonly cause?: unknown;
+    readonly details?: Record<string, unknown>;
+}
+export declare class UlwLoopError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, opts?: UlwLoopErrorOptions);
+}
+export declare function iso(): string;