@code-yeongyu/lazycodex 0.1.1

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

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