oh-my-opencode 4.7.5 → 4.8.0

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

@@ -0,0 +1,64 @@
+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];

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

@@ -0,0 +1,98 @@
+import type {
+	UlwLoopCodexGoalMode,
+	UlwLoopCriterionStatus,
+	UlwLoopLedgerEventKind,
+	UlwLoopStatus,
+	UlwLoopSteeringMutationKind,
+	UlwLoopSteeringStatus,
+	UlwLoopSuccessCriterionUserModel,
+} from "./constants.js";
+import type { UlwLoopSteeringAudit } from "./steering-types.js";
+
+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 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 UlwLoopQualityGate {
+	aiSlopCleaner: { status: "passed"; evidence: string };
+	verification: { status: "passed"; commands: string[]; evidence: string };
+	codeReview: { recommendation: "APPROVE"; architectStatus: "CLEAR"; evidence: string };
+}
+
+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;
+}

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

@@ -2,7 +2,7 @@
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 
-import { aggregateCodexObjectiveForScope } from "./goal-status.js";
+import { aggregateCodexObjectiveForScope, isUlwLoopDone } 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";
@@ -55,7 +55,11 @@ function clearGoalBlockerFields(goal: UlwLoopItem): void {
 
 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");
+		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: UlwLoopPlan = { version: 1, createdAt: now, updatedAt: now, briefPath: ulwLoopBriefRelativePath(scope), goalsPath: ulwLoopGoalsRelativePath(scope), ledgerPath: ulwLoopLedgerRelativePath(scope), codexGoalMode: args.codexGoalMode ?? "aggregate", goals };
@@ -69,6 +73,17 @@ export async function createUlwLoopPlan(repoRoot: string, args: { brief: string;
 	});
 }
 
+function completedPlanExistsError(scope?: UlwLoopScope): UlwLoopError {
+	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: string, args: { title: string; objective: string }, scope?: UlwLoopScope): Promise<{ plan: UlwLoopPlan; goal: UlwLoopItem }> {
 	return withUlwLoopMutationLock(repoRoot, scope, async () => {
 		const plan = await readUlwLoopPlan(repoRoot, scope);

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

@@ -0,0 +1,22 @@
+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/src/steering-types.ts

@@ -0,0 +1,69 @@
+import type { UlwLoopSteeringMutationKind, UlwLoopSteeringSource } from "./constants.js";
+import type { UlwLoopPlan } from "./domain-types.js";
+
+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;
+}

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

@@ -1,277 +1,5 @@
-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();
-}
+export * from "./command-types.js";
+export * from "./constants.js";
+export * from "./domain-types.js";
+export * from "./runtime.js";
+export * from "./steering-types.js";

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

@@ -55,6 +55,14 @@ function stdoutJson(): Record<string, unknown> {
 function codexSnapshot(status: "active" | "complete" = "active"): string {
 	return JSON.stringify({ goal: { objective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE, status } });
 }
+function qualityGate(): string {
+	return JSON.stringify({
+		aiSlopCleaner: { status: "passed", evidence: "no-op" },
+		verification: { status: "passed", commands: ["vitest"], evidence: "green" },
+		codeReview: { recommendation: "APPROVE", architectStatus: "CLEAR", evidence: "small test fixture" },
+		criteriaCoverage: { totalCriteria: 3, passCount: 3, adversarialClassesCovered: ["stale_state"] },
+	});
+}
 
 async function createPlan(brief = "- Goal A\n- Goal B"): Promise<Record<string, unknown>> {
 	resetOutput();
@@ -101,6 +109,33 @@ describe("ulwLoopCommand create-goals", () => {
 		expect(await readFile(join(testDir, ".omo/ulw-loop/ledger.jsonl"), "utf8")).toContain("plan_created");
 	});
 
+	it("#given completed default aggregate #when creating another default plan #then guides to a fresh session", async () => {
+		await createPlan("- Finished");
+		for (const criterionId of ["C001", "C002", "C003"]) await passCriterion("G001-finished", criterionId);
+		expect(
+			await ulwLoopCommand([
+				"checkpoint",
+				"--goal-id",
+				"G001-finished",
+				"--status",
+				"complete",
+				"--evidence",
+				"done",
+				"--codex-goal-json",
+				codexSnapshot("complete"),
+				"--quality-gate-json",
+				qualityGate(),
+			]),
+		).toBe(0);
+		resetOutput();
+
+		expect(await ulwLoopCommand(["create-goals", "--brief", "- New task"])).toBe(1);
+
+		expect(err.join("")).toContain("Existing ulw-loop aggregate is already complete");
+		expect(err.join("")).toContain("create-goals --session-id <new-id>");
+		expect(err.join("")).toContain("--force only");
+	});
+
 	it("#given two session ids #when creating goals #then writes isolated session-scoped plans", async () => {
 		expect(await ulwLoopCommand(["create-goals", "--session-id", "session-A", "--brief", "- Alpha", "--json"])).toBe(
 			0,
@@ -153,19 +188,6 @@ describe("ulwLoopCommand status", () => {
 	});
 });
 
-describe("ulwLoopCommand complete-goals", () => {
-	it("starts the next goal and returns a Codex instruction", async () => {
-		await createPlan();
-
-		expect(await ulwLoopCommand(["complete-goals", "--json"])).toBe(0);
-		expect(stdoutJson()).toMatchObject({
-			ok: true,
-			goal: { status: "in_progress" },
-			instruction: { json: { status: "active" } },
-		});
-	});
-});
-
 describe("ulwLoopCommand record-evidence", () => {
 	it("records evidence + returns updated criterion", async () => {
 		await createPlan();

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-complete-goals.test.ts

@@ -0,0 +1,52 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ulwLoopCommand } from "../src/cli-commands.ts";
+
+let testDir: string;
+let out: string[];
+
+beforeEach(async () => {
+	testDir = await mkdtemp(join(tmpdir(), "ug-cli-complete-"));
+	out = [];
+	vi.spyOn(process, "cwd").mockReturnValue(testDir);
+	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
+		out.push(chunk.toString());
+		return true;
+	});
+});
+
+afterEach(async () => {
+	vi.restoreAllMocks();
+	await rm(testDir, { recursive: true, force: true });
+});
+
+function resetOutput(): void {
+	out = [];
+}
+
+function stdoutJson(): Record<string, unknown> {
+	return JSON.parse(out.join(""));
+}
+
+async function createPlan(): Promise<void> {
+	expect(await ulwLoopCommand(["create-goals", "--brief", "- Goal A\n- Goal B", "--json"])).toBe(0);
+	resetOutput();
+}
+
+describe("ulwLoopCommand complete-goals", () => {
+	it("#given a pending plan #when complete-goals starts the next goal #then returns a Codex create_goal instruction", async () => {
+		await createPlan();
+
+		expect(await ulwLoopCommand(["complete-goals", "--json"])).toBe(0);
+
+		expect(stdoutJson()).toMatchObject({
+			ok: true,
+			goal: { status: "in_progress" },
+			instruction: { json: { objective: expect.any(String) } },
+		});
+		expect(JSON.stringify(stdoutJson())).not.toContain('"status":"active"');
+	});
+});