oh-my-opencode 4.5.1 → 4.6.0

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

@@ -0,0 +1,277 @@
+export const ULW_LOOP_DIR = ".omo/ulw-loop";
+export const ULW_LOOP_BRIEF = "brief.md";
+export const ULW_LOOP_GOALS = "goals.json";
+export const ULW_LOOP_LEDGER = "ledger.jsonl";
+
+export type UlwLoopStatus =
+	| "pending"
+	| "in_progress"
+	| "complete"
+	| "failed"
+	| "blocked"
+	| "review_blocked"
+	| "needs_user_decision";
+
+export type UlwLoopCodexGoalMode = "aggregate" | "per_story";
+
+export type UlwLoopSteeringStatus = "superseded" | "blocked";
+
+export const ULW_LOOP_STEERING_MUTATION_KINDS = [
+	"add_subgoal",
+	"split_subgoal",
+	"reorder_pending",
+	"revise_pending_wording",
+	"revise_criterion",
+	"annotate_ledger",
+	"mark_blocked_superseded",
+] as const satisfies readonly string[];
+export type UlwLoopSteeringMutationKind = (typeof ULW_LOOP_STEERING_MUTATION_KINDS)[number];
+
+export type UlwLoopSteeringSource = "user_prompt_submit" | "finding" | "cli";
+
+export const ULW_LOOP_SUCCESS_CRITERION_USER_MODELS = [
+	"happy",
+	"edge",
+	"regression",
+	"adversarial",
+] as const satisfies readonly string[];
+export type UlwLoopSuccessCriterionUserModel = (typeof ULW_LOOP_SUCCESS_CRITERION_USER_MODELS)[number];
+
+export const ULW_LOOP_CRITERION_STATUSES = ["pending", "pass", "fail", "blocked"] as const satisfies readonly string[];
+export type UlwLoopCriterionStatus = (typeof ULW_LOOP_CRITERION_STATUSES)[number];
+
+export const ULW_LOOP_LEDGER_EVENT_KINDS = [
+	"plan_created",
+	"goal_started",
+	"goal_resumed",
+	"goal_completed",
+	"goal_blocked",
+	"goal_failed",
+	"goal_needs_user_decision",
+	"goal_retried",
+	"aggregate_completed",
+	"aggregate_objective_migrated",
+	"goal_added",
+	"steering_accepted",
+	"steering_rejected",
+	"final_review_failed",
+	"goal_review_blocked",
+	"evidence_captured",
+	"criterion_failed",
+	"criterion_blocked",
+	"criteria_revised",
+] as const satisfies readonly string[];
+export type UlwLoopLedgerEventKind = (typeof ULW_LOOP_LEDGER_EVENT_KINDS)[number];
+
+export interface UlwLoopSuccessCriterion {
+	readonly id: string;
+	readonly scenario: string;
+	readonly userModel: UlwLoopSuccessCriterionUserModel;
+	readonly expectedEvidence: string;
+	capturedEvidence: string | null;
+	status: UlwLoopCriterionStatus;
+	capturedAt?: string;
+	notes?: string;
+}
+
+export interface UlwLoopSteeringInvariantResult {
+	accepted: boolean;
+	structuralInvariantAccepted: boolean;
+	evidenceBackedNecessity: boolean;
+	noEasierCompletion: boolean;
+	rejectedReasons: string[];
+	reasons?: string[];
+}
+
+export interface UlwLoopSteeringChildGoal {
+	title: string;
+	objective: string;
+}
+
+export interface UlwLoopSteeringAfterPayload {
+	title?: string;
+	objective?: string;
+	pendingGoalIds?: string[];
+	children?: UlwLoopSteeringChildGoal[];
+}
+
+export interface UlwLoopSteeringProposal {
+	kind: UlwLoopSteeringMutationKind;
+	source: UlwLoopSteeringSource;
+	targetGoalId?: string;
+	targetGoalIds?: string[];
+	criterionId?: string;
+	evidence: string;
+	rationale: string;
+	title?: string;
+	objective?: string;
+	childGoals?: UlwLoopSteeringChildGoal[];
+	revisedTitle?: string;
+	revisedObjective?: string;
+	pendingOrder?: string[];
+	blockedReason?: string;
+	after?: UlwLoopSteeringAfterPayload;
+	directiveText?: string;
+	promptSignature?: string;
+	idempotencyKey?: string;
+	now?: Date;
+}
+
+export interface UlwLoopSteeringAudit {
+	kind: UlwLoopSteeringMutationKind;
+	source: UlwLoopSteeringSource;
+	targetGoalIds: string[];
+	criterionId?: string;
+	before?: unknown;
+	after?: unknown;
+	evidence: string;
+	rationale: string;
+	invariant: UlwLoopSteeringInvariantResult;
+	directiveText?: string;
+	promptSignature?: string;
+	idempotencyKey?: string;
+	deduped?: boolean;
+}
+
+export interface SteerUlwLoopResult {
+	plan: UlwLoopPlan;
+	accepted: boolean;
+	audit: UlwLoopSteeringAudit;
+	rejectedReasons: string[];
+	deduped: boolean;
+}
+
+export interface UlwLoopItem {
+	id: string;
+	title: string;
+	objective: string;
+	status: UlwLoopStatus;
+	successCriteria: UlwLoopSuccessCriterion[];
+	attempt: number;
+	createdAt: string;
+	updatedAt: string;
+	startedAt?: string;
+	completedAt?: string;
+	failedAt?: string;
+	reviewBlockedAt?: string;
+	evidence?: string;
+	failureReason?: string;
+	steeringStatus?: UlwLoopSteeringStatus;
+	supersededBy?: string[];
+	supersedes?: string[];
+	blockedReason?: string;
+	blockerSignature?: string;
+	blockerOccurrenceCount?: number;
+	requiredExternalDecision?: string;
+	nonRetriable?: boolean;
+	steeringEvidence?: string;
+	steeringRationale?: string;
+}
+
+export interface UlwLoopAggregateCompletion {
+	status: "complete";
+	completedAt: string;
+	evidence: string;
+	codexGoal?: unknown;
+}
+
+export interface UlwLoopPlan {
+	version: 1;
+	createdAt: string;
+	updatedAt: string;
+	briefPath: string;
+	goalsPath: string;
+	ledgerPath: string;
+	codexGoalMode?: UlwLoopCodexGoalMode;
+	codexObjective?: string;
+	codexObjectiveAliases?: string[];
+	aggregateCompletion?: UlwLoopAggregateCompletion;
+	activeGoalId?: string;
+	goals: UlwLoopItem[];
+}
+
+export interface UlwLoopLedgerEntry {
+	at: string;
+	kind: UlwLoopLedgerEventKind;
+	goalId?: string;
+	criterionId?: string;
+	status?: UlwLoopStatus;
+	criterionStatus?: UlwLoopCriterionStatus;
+	message?: string;
+	codexGoal?: unknown;
+	evidence?: string;
+	capturedEvidence?: string;
+	qualityGate?: UlwLoopQualityGate;
+	steering?: UlwLoopSteeringAudit;
+	before?: unknown;
+	after?: unknown;
+	mutationKind?: UlwLoopSteeringMutationKind;
+	idempotencyKey?: string;
+	blockerSignature?: string;
+	blockerOccurrenceCount?: number;
+	requiredExternalDecision?: string;
+}
+
+export interface CreateUlwLoopOptions {
+	brief: string;
+	goals?: Array<{ title?: string; objective: string }>;
+	codexGoalMode?: UlwLoopCodexGoalMode;
+	now?: Date;
+	force?: boolean;
+}
+
+export interface StartNextOptions {
+	now?: Date;
+	retryFailed?: boolean;
+}
+
+export interface CheckpointOptions {
+	goalId: string;
+	status: Extract<UlwLoopStatus, "complete" | "failed"> | "blocked";
+	evidence?: string;
+	codexGoal?: unknown;
+	qualityGate?: unknown;
+	allowActiveFinalCodexGoal?: boolean;
+	now?: Date;
+}
+
+export interface AddUlwLoopGoalOptions {
+	title: string;
+	objective: string;
+	evidence?: string;
+	now?: Date;
+}
+
+export interface RecordFinalReviewBlockersOptions extends AddUlwLoopGoalOptions {
+	goalId: string;
+	codexGoal?: unknown;
+}
+
+export interface UlwLoopQualityGate {
+	aiSlopCleaner: { status: "passed"; evidence: string };
+	verification: { status: "passed"; commands: string[]; evidence: string };
+	codeReview: { recommendation: "APPROVE"; architectStatus: "CLEAR"; evidence: string };
+}
+
+export interface UlwLoopErrorOptions {
+	readonly cause?: unknown;
+	readonly details?: Record<string, unknown>;
+}
+
+export class UlwLoopError extends Error {
+	readonly code: string;
+	readonly details?: Record<string, unknown>;
+
+	constructor(message: string, code: string, opts?: UlwLoopErrorOptions) {
+		super(message, opts?.cause === undefined ? undefined : { cause: opts.cause });
+		this.name = "UlwLoopError";
+		this.code = code;
+		if (opts?.details !== undefined) {
+			this.details = opts.details;
+		}
+	}
+}
+
+export function iso(): string {
+	return new Date().toISOString();
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/checkpoint.test.ts

@@ -0,0 +1,213 @@
+// biome-ignore-all format: keep the single mandated checkpoint spec under the pure LOC budget.
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { checkpointUlwLoop } from "../src/checkpoint.js";
+import { ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE } from "../src/goal-status.js";
+import { ulwLoopBriefPath, ulwLoopDir, ulwLoopLedgerPath } from "../src/paths.js";
+import { writePlan } from "../src/plan-io.js";
+import type { UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan, UlwLoopSuccessCriterion } from "../src/types.js";
+import { UlwLoopError } from "../src/types.js";
+
+const NOW = "2026-05-23T00:00:00.000Z";
+const QUALITY_GATE_PATH = join(process.cwd(), "test", "fixtures", "sample-quality-gate.json");
+
+function criterion(id: string, status: UlwLoopSuccessCriterion["status"]): UlwLoopSuccessCriterion {
+	return { id, scenario: `${id} scenario`, userModel: "happy", expectedEvidence: `${id} proof`, capturedEvidence: status === "pass" ? `${id} passed` : null, status };
+}
+
+function goal(overrides: Partial<UlwLoopItem> = {}): UlwLoopItem {
+	return { id: "G001", title: "Build auth", objective: "Implement JWT auth endpoint", status: "in_progress", successCriteria: [criterion("C001", "pass"), criterion("C002", "pass"), criterion("C003", "pass")], attempt: 1, createdAt: NOW, updatedAt: NOW, ...overrides };
+}
+
+function plan(goals: UlwLoopItem[], overrides: Partial<UlwLoopPlan> = {}): UlwLoopPlan {
+	const result: UlwLoopPlan = { version: 1, createdAt: NOW, updatedAt: NOW, briefPath: ".omo/ulw-loop/brief.md", goalsPath: ".omo/ulw-loop/goals.json", ledgerPath: ".omo/ulw-loop/ledger.jsonl", codexGoalMode: "aggregate", codexObjective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE, goals };
+	Object.assign(result, overrides);
+	const activeGoalId = goals.find((candidate) => candidate.status === "in_progress")?.id;
+	if (result.activeGoalId === undefined && activeGoalId !== undefined) result.activeGoalId = activeGoalId;
+	return result;
+}
+
+async function samplePlan(overrides: Partial<UlwLoopPlan> = {}): Promise<UlwLoopPlan> {
+	const fixture: UlwLoopPlan = JSON.parse(await readFile(new URL("./fixtures/sample-plan.json", import.meta.url), "utf8"));
+	return plan(fixture.goals.map((item, index) => goal({ ...item, attempt: index + 1, createdAt: NOW, updatedAt: NOW })), overrides);
+}
+
+async function repoWith(seed: UlwLoopPlan): Promise<string> {
+	const repo = await mkdtemp(join(tmpdir(), "ug-checkpoint-"));
+	await mkdir(ulwLoopDir(repo), { recursive: true });
+	await writePlan(repo, seed);
+	return repo;
+}
+
+function snapshot(status: "active" | "complete", objective = ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE): string {
+	return JSON.stringify({ goal: { objective, status } });
+}
+
+async function lastLedger(repo: string): Promise<UlwLoopLedgerEntry> {
+	const last = (await readFile(ulwLoopLedgerPath(repo), "utf8")).trim().split(/\r?\n/).at(-1);
+	if (last === undefined) throw new Error("expected ledger entry");
+	const entry: UlwLoopLedgerEntry = JSON.parse(last);
+	return entry;
+}
+
+async function expectCode(action: () => Promise<unknown>, code: string): Promise<void> {
+	try {
+		await action();
+	} catch (error) {
+		expect(error).toBeInstanceOf(UlwLoopError);
+		if (!(error instanceof UlwLoopError)) throw error;
+		expect(error.code).toBe(code);
+		return;
+	}
+	throw new Error("Expected UlwLoopError");
+}
+
+function passGoal(id: string, overrides: Partial<UlwLoopItem> = {}): UlwLoopItem {
+	return goal({ id, successCriteria: [criterion("C001", "pass"), criterion("C002", "pass"), criterion("C003", "pass")], ...overrides });
+}
+
+describe("checkpointUlwLoop status=complete criteria gate", () => {
+	it("THROWS ulw_loop_criteria_not_all_pass when any criterion is pending", async () => {
+		const repo = await repoWith(await samplePlan({ goals: [goal({ successCriteria: [criterion("C001", "pass"), criterion("C002", "pending"), criterion("C003", "pass")] })] }));
+		await expectCode(() => checkpointUlwLoop(repo, { goalId: "G001", status: "complete", evidence: "done" }), "ulw_loop_criteria_not_all_pass");
+	});
+
+	it("THROWS when any criterion is fail or blocked", async () => {
+		for (const status of ["fail", "blocked"] satisfies UlwLoopSuccessCriterion["status"][]) {
+			const repo = await repoWith(plan([goal({ successCriteria: [criterion("C001", "pass"), criterion("C002", status), criterion("C003", "pass")] })]));
+			await expectCode(() => checkpointUlwLoop(repo, { goalId: "G001", status: "complete", evidence: "done" }), "ulw_loop_criteria_not_all_pass");
+		}
+	});
+
+	it("THROWS when criteria list is empty", async () => {
+		const repo = await repoWith(plan([goal({ successCriteria: [] }), goal({ id: "G002", status: "pending" })]));
+		await expectCode(() => checkpointUlwLoop(repo, { goalId: "G001", status: "complete", evidence: "done", codexGoalJson: snapshot("active") }), "ulw_loop_criteria_not_all_pass");
+	});
+
+	it("ACCEPTS complete when ALL criteria pass (with valid snapshot)", async () => {
+		const repo = await repoWith(plan([passGoal("G001"), goal({ id: "G002", status: "pending" })]));
+		const result = await checkpointUlwLoop(repo, { goalId: "G001", status: "complete", evidence: "implementation done and tests passed", codexGoalJson: snapshot("active") });
+		expect(result.goal.status).toBe("complete");
+		expect((await lastLedger(repo)).kind).toBe("goal_completed");
+	});
+});
+
+describe("checkpointUlwLoop reconciliation (status=complete)", () => {
+	it("succeeds when snapshot objective matches expected (aggregate active)", async () => {
+		const repo = await repoWith(plan([passGoal("G001"), goal({ id: "G002", status: "pending" })]));
+		await expect(checkpointUlwLoop(repo, { goalId: "G001", status: "complete", evidence: "work complete and validation passed", codexGoalJson: snapshot("active") })).resolves.toMatchObject({ goal: { status: "complete" } });
+	});
+
+	it("throws on mismatched objective", async () => {
+		const repo = await repoWith(plan([passGoal("G001"), goal({ id: "G002", status: "pending" })]));
+		await expectCode(() => checkpointUlwLoop(repo, { goalId: "G001", status: "complete", evidence: "work complete and validation passed", codexGoalJson: snapshot("active", "wrong objective") }), "ulw_loop_codex_snapshot_mismatch");
+	});
+
+	it("throws on mismatched status (snapshot complete when expected active)", async () => {
+		const repo = await repoWith(plan([passGoal("G001"), goal({ id: "G002", status: "pending" })]));
+		await expectCode(() => checkpointUlwLoop(repo, { goalId: "G001", status: "complete", evidence: "work complete and validation passed", codexGoalJson: snapshot("complete") }), "ulw_loop_codex_snapshot_mismatch");
+	});
+});
+
+describe("checkpointUlwLoop final story", () => {
+	it("requires quality-gate-json for the final goal complete", async () => {
+		const repo = await repoWith(plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }));
+		await expectCode(() => checkpointUlwLoop(repo, { goalId: "G002", status: "complete", evidence: "final work complete and validation passed", codexGoalJson: snapshot("complete") }), "ULW_LOOP_QUALITY_GATE_INVALID");
+	});
+
+	it("accepts final story when quality gate JSON includes valid criteriaCoverage", async () => {
+		const repo = await repoWith(plan([passGoal("G001", { status: "complete" }), passGoal("G002")], { activeGoalId: "G002" }));
+		const result = await checkpointUlwLoop(repo, { goalId: "G002", status: "complete", evidence: "final work complete and validation passed", codexGoalJson: snapshot("complete"), qualityGateJson: QUALITY_GATE_PATH });
+		expect(result.aggregateCompletion?.status).toBe("complete");
+		expect(result.plan.aggregateCompletion?.status).toBe("complete");
+	});
+
+	it("ACCEPTS complete when task-scoped completed Codex objective maps to the ulw-loop brief", async () => {
+		const taskObjective = "Fix ulw-loop objective mismatch and install local ulw";
+		const repo = await repoWith(plan([passGoal("G001")], { activeGoalId: "G001" }));
+		await writeFile(ulwLoopBriefPath(repo), `${taskObjective}\n`, "utf8");
+
+		const result = await checkpointUlwLoop(repo, {
+			goalId: "G001",
+			status: "complete",
+			evidence: "final implementation complete and quality gate passed",
+			codexGoalJson: snapshot("complete", taskObjective),
+			qualityGateJson: QUALITY_GATE_PATH,
+		});
+
+		expect(result.aggregateCompletion?.status).toBe("complete");
+		expect(result.ledgerEntry.kind).toBe("aggregate_completed");
+	});
+
+	it("explains final task-scoped objective mapping when completed Codex objective is unrelated", async () => {
+		const repo = await repoWith(plan([passGoal("G001")], { activeGoalId: "G001" }));
+		await writeFile(ulwLoopBriefPath(repo), "Fix ulw-loop objective mismatch and install local ulw\n", "utf8");
+
+		await expect(
+			checkpointUlwLoop(repo, {
+				goalId: "G001",
+				status: "complete",
+				evidence: "final implementation complete and quality gate passed",
+				codexGoalJson: snapshot("complete", "unrelated completed task"),
+				qualityGateJson: QUALITY_GATE_PATH,
+			}),
+		).rejects.toThrow("Final task-scoped aggregate reconciliation");
+	});
+});
+
+describe("checkpointUlwLoop status=failed", () => {
+	it("sets goal.status=failed, goal.failedAt, appends ledger", async () => {
+		const repo = await repoWith(plan([goal({ successCriteria: [criterion("C001", "pending")] })]));
+		const result = await checkpointUlwLoop(repo, { goalId: "G001", status: "failed", evidence: "tests failed" });
+		expect(result.goal.status).toBe("failed");
+		expect(result.goal.failedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/u);
+		expect((await lastLedger(repo)).kind).toBe("goal_failed");
+	});
+
+	it("classifies external authorization blocker signatures", async () => {
+		const repo = await repoWith(plan([goal()]));
+		const result = await checkpointUlwLoop(repo, { goalId: "G001", status: "failed", evidence: "ghcr.io returned 401 authentication required because token missing" });
+		expect(result.goal.blockerSignature).toBe("GHCR_PULL_ACCESS:HTTP_401_ANONYMOUS:GHCR_VISIBILITY_OR_CREDENTIAL_REQUIRED");
+	});
+
+	it("after 3 same-signature blockers, marks needs_user_decision + nonRetriable", async () => {
+		const repo = await repoWith(plan([goal({ id: "G001", status: "failed", blockerSignature: "EXTERNAL_AUTHORIZATION_REQUIRED" }), goal({ id: "G002", status: "blocked", blockerSignature: "EXTERNAL_AUTHORIZATION_REQUIRED" }), goal({ id: "G003" })], { activeGoalId: "G003" }));
+		const result = await checkpointUlwLoop(repo, { goalId: "G003", status: "failed", evidence: "Registry returned 401 because credentials are missing" });
+		expect(result.goal.status).toBe("needs_user_decision");
+		expect(result.goal.nonRetriable).toBe(true);
+	});
+
+	it("skips the criteria gate for failed status", async () => {
+		const repo = await repoWith(plan([goal({ successCriteria: [criterion("C001", "pending")] })]));
+		await expect(checkpointUlwLoop(repo, { goalId: "G001", status: "failed", evidence: "not done" })).resolves.toMatchObject({ goal: { status: "failed" } });
+	});
+});
+
+describe("checkpointUlwLoop status=blocked", () => {
+	it("preserves blocker fields + appends ledger", async () => {
+		const repo = await repoWith(plan([goal()]));
+		const result = await checkpointUlwLoop(repo, { goalId: "G001", status: "blocked", evidence: "ghcr.io requires token and credentials are missing" });
+		expect(result.goal.status).toBe("blocked");
+		expect(result.goal.blockedReason).toContain("ghcr.io");
+		expect(result.goal.blockerSignature).toContain("GHCR_PULL_ACCESS");
+		expect((await lastLedger(repo)).kind).toBe("goal_blocked");
+	});
+
+	it("skips the criteria gate for blocked status", async () => {
+		const repo = await repoWith(plan([goal({ successCriteria: [criterion("C001", "pending")] })]));
+		await expect(checkpointUlwLoop(repo, { goalId: "G001", status: "blocked", evidence: "waiting for approval" })).resolves.toMatchObject({ goal: { status: "blocked" } });
+	});
+});
+
+describe("checkpointUlwLoop rebrand", () => {
+	it("does not emit legacy brand token in any returned text or ledger payload", async () => {
+		const repo = await repoWith(plan([passGoal("G001"), goal({ id: "G002", status: "pending" })]));
+		const result = await checkpointUlwLoop(repo, { goalId: "G001", status: "complete", evidence: "implementation done in .omo/ulw-loop/goals.json for G001 and validation passed", codexGoalJson: snapshot("active") });
+		const forbidden = ["o", "m", "x"].join("");
+		const payload = `${JSON.stringify(result)}\n${await readFile(ulwLoopLedgerPath(repo), "utf8")}`.toLowerCase();
+		expect(payload).not.toContain(forbidden);
+	});
+});