oh-my-opencode 5.0.0-beta.30 → 5.0.0-beta.32

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

@@ -1,14 +1,23 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir } from "./paths.js";
+import { GATE_REVIEWER_AGENT_NAMES, REVIEWER_ROLES_BY_SURFACE, resolveToolkitSurface, reviewerRolesFor, } from "./surface.js";
 // spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
 // hook token from codex-rs hook_names.rs; collaboration.spawn_agent = the
 // dotted token observed live in the task-1 probe (hook-tool-tokens.txt).
 const SPAWN_TOOL_TOKENS = new Set(["spawn_agent", "collaborationspawn_agent", "collaboration.spawn_agent"]);
 const DEFAULT_FANOUT_LIMIT = 60;
-const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|final gate review/i;
+const DEFAULT_REVIEW_SPAWN_LIMIT = 3;
+const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
+const REVIEW_AGENT_TYPES = [
+    ...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview),
+    ...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.codeReview),
+    ...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.manualQa),
+];
+const REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
 export function applySpawnGuards(payload) {
     if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
         return "";
@@ -16,12 +25,18 @@ export function applySpawnGuards(payload) {
     const plan = readPlan(join(stateDir, "goals.json"));
     if (plan === null)
         return "";
-    const fanOutDenial = consumeFanOutBudget(stateDir);
-    if (fanOutDenial !== null)
-        return deny(fanOutDenial);
+    const fanOutPeek = peekFanOutBudget(stateDir);
+    if (fanOutPeek !== null)
+        return deny(fanOutPeek);
     const missingArtifact = missingGateArtifact(payload, plan);
     if (missingArtifact !== null)
         return deny(`spawn code-review + QA first; gate audits their artifacts: missing ${missingArtifact}`);
+    const reviewDenial = consumeReviewSpawnBudget(payload, plan, stateDir);
+    if (reviewDenial !== null)
+        return deny(reviewDenial);
+    const fanOutDenial = consumeFanOutBudget(stateDir);
+    if (fanOutDenial !== null)
+        return deny(fanOutDenial);
     return "";
 }
 export async function runSpawnGuardCli(stdin, stdout) {
@@ -41,17 +56,51 @@ export async function runSpawnGuardCli(stdin, stdout) {
             return;
     }
 }
+// Read-only fan-out eligibility check. Returns a denial reason when the next
+// spawn would exceed the limit, without incrementing the counter. Call this
+// before charging any per-reviewer quota so a saturated global cap cannot
+// silently consume reviewer allowances for spawns that will never run.
+function peekFanOutBudget(stateDir) {
+    const counterPath = join(stateDir, "spawn-count.json");
+    const count = readCount(counterPath) + 1;
+    const limit = fanOutLimit();
+    if (count <= limit)
+        return null;
+    return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
+}
 // Per-session spawn counter; depth/lineage tracking is descoped — this is a
 // total-volume backstop against fan-out explosions, not a recursion tracker.
 function consumeFanOutBudget(stateDir) {
     const counterPath = join(stateDir, "spawn-count.json");
     const count = readCount(counterPath) + 1;
-    writeFileSync(counterPath, JSON.stringify({ count }));
+    atomicWriteJson(counterPath, { count });
     const limit = fanOutLimit();
     if (count <= limit)
         return null;
     return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
 }
+function consumeReviewSpawnBudget(payload, plan, stateDir) {
+    const agentType = reviewAgentType(payload.tool_input);
+    if (agentType === null)
+        return null;
+    const goal = plan.goals.find((candidate) => candidate.id === plan.activeGoalId) ??
+        plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
+    if (goal === undefined)
+        return null;
+    const counterPath = join(stateDir, "review-spawn-counts.json");
+    const lockPath = `${counterPath}.lock`;
+    const limit = reviewSpawnLimit();
+    return withExclusiveLock(lockPath, () => {
+        const counts = readCounts(counterPath);
+        const key = `${agentType}:${goal.id}:a${goal.attempt}`;
+        const count = (counts[key] ?? 0) + 1;
+        if (count > limit)
+            return `ulw-loop reviewer no-progress cap reached (${agentType} ${count}/${limit}) for ${goal.id} attempt ${goal.attempt}. Consolidate existing review findings, or checkpoint and start a new attempt after concrete progress.`;
+        counts[key] = count;
+        atomicWriteJson(counterPath, counts);
+        return null;
+    });
+}
 function missingGateArtifact(payload, plan) {
     if (!isGateReviewerSpawn(payload.tool_input))
         return null;
@@ -61,9 +110,11 @@ function missingGateArtifact(payload, plan) {
     if (!goal.successCriteria.every((criterion) => criterion.status === "pass"))
         return null;
     const scope = { sessionId: payload.session_id };
+    const surface = resolveToolkitSurface();
+    const requiredArtifacts = surface === "omo-senpi" ? [`${goal.id}-manual-qa.md`] : [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`];
     if (plan.evidenceLayoutVersion === 2) {
         const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
-        for (const name of [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`]) {
+        for (const name of requiredArtifacts) {
             const relative = `${attemptDir}/${name}`;
             if (!isNonEmptyFile(join(payload.cwd, relative)))
                 return relative;
@@ -71,22 +122,117 @@ function missingGateArtifact(payload, plan) {
         return null;
     }
     const flatReport = `.omo/evidence/${goal.id}-code-review.md`;
-    if (!isNonEmptyFile(join(payload.cwd, flatReport)))
+    if (surface !== "omo-senpi" && !isNonEmptyFile(join(payload.cwd, flatReport)))
         return flatReport;
+    if (surface === "omo-senpi") {
+        const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
+        return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
+    }
     // v1 manual-QA approximation: any other non-empty evidence file counts.
     if (!hasOtherEvidenceFile(join(payload.cwd, ".omo", "evidence"), `${goal.id}-code-review.md`))
-        return `.omo/evidence/<any manual-QA artifact besides ${goal.id}-code-review.md>`;
+        return `.omo/evidence/${goal.id}-manual-qa.md`;
     return null;
 }
 function isGateReviewerSpawn(toolInput) {
+    const agentType = reviewAgentType(toolInput);
+    return agentType !== null && GATE_REVIEWER_AGENT_NAMES.has(agentType);
+}
+function reviewAgentType(toolInput) {
     if (typeof toolInput !== "object" || toolInput === null)
-        return false;
+        return null;
     const record = toolInput;
     const agentType = record["agent_type"];
-    if (typeof agentType === "string")
-        return agentType === "lazycodex-gate-reviewer";
+    if (typeof agentType === "string") {
+        // V1: agent_type is present — only reviewer types proceed; any other type is not a review spawn.
+        if (!REVIEW_AGENT_TYPE_SET.has(agentType))
+            return null;
+        return activeSurfaceReviewerAlias(agentType);
+    }
     const message = record["message"];
-    return typeof message === "string" && GATE_MESSAGE_PATTERN.test(message);
+    if (typeof message !== "string")
+        return null;
+    const normalizedMessage = message.toLowerCase();
+    // Explicit "act as <role>" assignment takes priority. If the assigned role is not a reviewer,
+    // treat the spawn as non-review so a message that merely mentions a reviewer name does not
+    // accidentally charge that reviewer's quota.
+    const allRoleNames = [...REVIEW_AGENT_TYPES];
+    const explicitAssignment = allRoleNames
+        .map((name) => ({
+        name,
+        index: normalizedMessage.search(new RegExp(`\\bact as (?:an? )?${name}\\b`)),
+    }))
+        .filter(({ index }) => index >= 0)
+        .sort((left, right) => left.index - right.index)[0];
+    if (explicitAssignment !== undefined)
+        return activeSurfaceReviewerAlias(explicitAssignment.name);
+    // Check for an explicit "act as <non-reviewer-role>" assignment. If found, the spawn is not a
+    // review spawn even if the message body mentions a reviewer name.
+    const nonReviewerActAs = /\bact as (?:an? )?\S+/.test(normalizedMessage);
+    if (nonReviewerActAs)
+        return null;
+    const namedReviewer = REVIEW_AGENT_TYPES.find((name) => normalizedMessage.includes(name));
+    if (namedReviewer !== undefined)
+        return activeSurfaceReviewerAlias(namedReviewer);
+    return GATE_MESSAGE_PATTERN.test(message) ? reviewerRolesFor(resolveToolkitSurface()).gateReview : null;
+}
+function activeSurfaceReviewerAlias(reviewer) {
+    const activeRoles = reviewerRolesFor(resolveToolkitSurface());
+    for (const roles of Object.values(REVIEWER_ROLES_BY_SURFACE)) {
+        if (reviewer === roles.codeReview)
+            return activeRoles.codeReview;
+        if (reviewer === roles.manualQa)
+            return activeRoles.manualQa;
+        if (reviewer === roles.gateReview)
+            return activeRoles.gateReview;
+    }
+    return reviewer;
+}
+function withExclusiveLock(lockPath, fn) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const maxAttempts = 10;
+    const baseDelayMs = 10;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        let fd = null;
+        try {
+            fd = openSync(lockPath, "wx");
+            writeFileSync(fd, process.pid.toString());
+            try {
+                return fn();
+            }
+            finally {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    /* empty */
+                }
+            }
+        }
+        catch (error) {
+            if (fd !== null) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    /* empty */
+                }
+            }
+            if (error.code !== "EEXIST") {
+                return fn();
+            }
+            const delayMs = baseDelayMs * 2 ** attempt + Math.random() * baseDelayMs;
+            const deadline = Date.now() + delayMs;
+            while (Date.now() < deadline) {
+                /* spin */
+            }
+        }
+    }
+    return fn();
+}
+function atomicWriteJson(targetPath, data) {
+    const tmp = join(dirname(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
+    writeFileSync(tmp, JSON.stringify(data));
+    renameSync(tmp, targetPath);
 }
 function deny(reason) {
     return `${JSON.stringify({
@@ -105,6 +251,13 @@ function fanOutLimit() {
     const parsed = Number.parseInt(raw, 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
 }
+function reviewSpawnLimit() {
+    const raw = process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
+    if (raw === undefined)
+        return DEFAULT_REVIEW_SPAWN_LIMIT;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_REVIEW_SPAWN_LIMIT;
+}
 function isNonEmptyFile(path) {
     try {
         return existsSync(path) && statSync(path).size > 0;
@@ -136,6 +289,24 @@ function readCount(counterPath) {
         throw error;
     }
 }
+function readCounts(counterPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return {};
+        const counts = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === "number" && value >= 0)
+                counts[key] = value;
+        }
+        return counts;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return {};
+        throw error;
+    }
+}
 function readPlan(goalsPath) {
     try {
         return JSON.parse(readFileSync(goalsPath, "utf8"));

package/packages/omo-codex/plugin/components/ulw-loop/dist/status-next-actions.d.ts

@@ -0,0 +1,6 @@
+import type { UlwLoopPlan } from "./types.js";
+/**
+ * `status --json` is the one call every agent already makes between steps, so it is
+ * also the cheapest place to answer "what now?" without a second round trip.
+ */
+export declare function statusNextActions(plan: UlwLoopPlan): readonly string[];

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

@@ -0,0 +1,33 @@
+import { hasAllCriteriaPass, isFinalRunCompletionCandidate } from "./goal-status.js";
+import { ULW_LOOP_CREATE_GOALS_COMMAND } from "./plan-missing-recovery.js";
+/**
+ * `status --json` is the one call every agent already makes between steps, so it is
+ * also the cheapest place to answer "what now?" without a second round trip.
+ */
+export function statusNextActions(plan) {
+    const actions = [];
+    const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+    if (plan.goals.length === 0)
+        actions.push(`No goals yet: bootstrap with \`${ULW_LOOP_CREATE_GOALS_COMMAND}\`.`);
+    else if (active !== undefined)
+        actions.push(...activeGoalActions(plan, active));
+    for (const goal of plan.goals.filter((candidate) => candidate.status === "review_blocked"))
+        actions.push(`${goal.id} is review_blocked: capture the reviewer verdict with \`omo-agent-toolkit ulw-loop record-review-blockers --goal-id ${goal.id} --title "<title>" --objective "<objective>" --evidence "<verdict>" --codex-goal-json '<get_goal json>'\`.`);
+    if (plan.evidenceLayoutVersion !== 2 || active === undefined)
+        actions.push("plan is evidence-layout v1; artifacts go under .omo/evidence/");
+    return actions;
+}
+function activeGoalActions(plan, active) {
+    const unresolved = active.successCriteria.filter((criterion) => criterion.status !== "pass");
+    if (unresolved.length > 0)
+        return [
+            `${active.id} has ${unresolved.length} unresolved criterion(s) (${unresolved.map((criterion) => criterion.id).join(", ")}): record proof with \`omo-agent-toolkit ulw-loop record-evidence --goal-id ${active.id} --criterion-id <id> --status pass --evidence "<observable proof>"\`.`,
+        ];
+    if (hasAllCriteriaPass(active) && isFinalRunCompletionCandidate(plan, active))
+        return [
+            `${active.id} passes every criterion and is the final story: update_goal complete, then checkpoint --print-template to build the final quality gate.`,
+        ];
+    return [
+        `${active.id} passes every criterion: close it with \`omo-agent-toolkit ulw-loop checkpoint --goal-id ${active.id} --status complete --evidence "<proof>" --codex-goal-json '<get_goal json>'\`.`,
+    ];
+}

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

@@ -0,0 +1,18 @@
+export type UlwLoopToolkitSurface = "lazycodex" | "omo-senpi";
+export interface UlwLoopReviewerRoles {
+    readonly codeReview: string;
+    readonly manualQa: string;
+    readonly gateReview: string;
+}
+export declare const REVIEWER_ROLES_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, UlwLoopReviewerRoles>>;
+export declare const GATE_REVIEWER_AGENT_NAMES: ReadonlySet<string>;
+export type UlwLoopGateSection = "codeReview" | "manualQa" | "gateReview" | "iteration" | "criteriaCoverage";
+export declare const REQUIRED_GATE_SECTIONS_BY_SURFACE: Readonly<Record<UlwLoopToolkitSurface, readonly UlwLoopGateSection[]>>;
+export declare const GATE_SECTION_BY_ACCEPTOR: Readonly<Record<UlwLoopToolkitSurface, Readonly<Partial<Record<UlwLoopGateSection, readonly string[]>>>>>;
+export declare function reviewerRolesFor(surface: UlwLoopToolkitSurface): UlwLoopReviewerRoles;
+export declare const SURFACE_MARKER_FILENAME = "surface.json";
+export interface ResolveToolkitSurfaceOptions {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly entryDir?: string;
+}
+export declare function resolveToolkitSurface(options?: ResolveToolkitSurfaceOptions): UlwLoopToolkitSurface;

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

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const REVIEWER_ROLES_BY_SURFACE = {
+    lazycodex: {
+        codeReview: "lazycodex-code-reviewer",
+        manualQa: "lazycodex-qa-executor",
+        gateReview: "lazycodex-gate-reviewer",
+    },
+    "omo-senpi": {
+        codeReview: "omo-senpi-code-reviewer",
+        manualQa: "omo-senpi-qa-executor",
+        gateReview: "omo-senpi-gate-reviewer",
+    },
+};
+export const GATE_REVIEWER_AGENT_NAMES = new Set(Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview));
+export const REQUIRED_GATE_SECTIONS_BY_SURFACE = {
+    lazycodex: ["codeReview", "manualQa", "gateReview", "iteration", "criteriaCoverage"],
+    "omo-senpi": ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+};
+export const GATE_SECTION_BY_ACCEPTOR = {
+    lazycodex: {
+        codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview],
+        manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa],
+        gateReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview],
+    },
+    "omo-senpi": {
+        manualQa: ["main-session"],
+        gateReview: ["category:deep", "category:unspecified-high", "category:unspecified-low"],
+    },
+};
+export function reviewerRolesFor(surface) {
+    return REVIEWER_ROLES_BY_SURFACE[surface];
+}
+export const SURFACE_MARKER_FILENAME = "surface.json";
+const SURFACE_ENV_KEY = "OMO_AGENT_TOOLKIT_SURFACE";
+function parseSurface(value) {
+    return value === "lazycodex" || value === "omo-senpi" ? value : null;
+}
+// Resolution order: explicit env override (tests, doctor probes) -> staged surface.json marker
+// sitting next to the running bundle -> lazycodex default. The marker is distribution-baked, so a
+// malformed marker falls back to the default instead of crashing checkpoint validation; the env
+// override remains available to force the intended surface on a damaged install.
+export function resolveToolkitSurface(options) {
+    const env = options?.env ?? process.env;
+    const fromEnv = parseSurface(env[SURFACE_ENV_KEY]);
+    if (fromEnv !== null)
+        return fromEnv;
+    const entryDir = options?.entryDir ?? dirname(fileURLToPath(import.meta.url));
+    const markerPath = join(entryDir, SURFACE_MARKER_FILENAME);
+    return readMarkerSurface(markerPath) ?? "lazycodex";
+}
+function readMarkerSurface(markerPath) {
+    try {
+        if (!existsSync(markerPath))
+            return null;
+        const parsed = JSON.parse(readFileSync(markerPath, "utf8"));
+        return parseSurface(parsed["surface"]);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return null;
+        throw error;
+    }
+}

package/packages/omo-codex/plugin/components/ulw-loop/hooks/hooks.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.30) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.32) Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.30) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.32) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -31,7 +31,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.30) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.32) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -43,7 +43,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.30) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.32) Checking Ulw-Loop Resume"
 					}
 				]
 			}

package/packages/omo-codex/plugin/components/ulw-loop/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "5.0.0-beta.30",
+	"version": "5.0.0-beta.32",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/full-workflow.md

@@ -179,6 +179,23 @@ Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures a
 4. If blocked or failed, checkpoint with `--status blocked` or `--status failed` and include diagnosis evidence.
 5. If this is the final goal, run the final quality gate first and pass `--quality-gate-json`.
 
+## Exact final-story sequence
+For the final story, follow this exact checkpoint sequence:
+
+```sh
+omo-agent-toolkit ulw-loop status --json
+# Read nextActions and currentAttemptDir.
+omo-agent-toolkit ulw-loop record-evidence --goal-id <g> --criterion-id <c> --status pass --evidence "..."
+# Repeat record-evidence once per criterion.
+# Then use the harness update_goal tool with status complete.
+omo-agent-toolkit ulw-loop checkpoint --goal-id <g> --print-template --json
+# Fill the printed template: replace every placeholder and use real artifact paths under currentAttemptDir.
+omo-agent-toolkit ulw-loop checkpoint --goal-id <g> --status complete --evidence "..." --codex-goal-json <path> --quality-gate-json <path>
+omo-agent-toolkit ulw-loop complete-goals
+```
+
+The lazycodex gate uses all five sections shown in the sample below, including `codeReview`.
+
 ## Final Quality Gate
 Trigger only for the final aggregate goal after every criterion in every goal is `pass`.
 1. Run targeted verification for changed behavior.

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

@@ -1,4 +1,5 @@
 import { type CheckpointUlwLoopArgs, type CheckpointUlwLoopResult, checkpointUlwLoop } from "./checkpoint.js";
+import { checkpointTemplate } from "./checkpoint-template.js";
 import { hasFlag, parseCodexGoalJson, readValue } from "./cli-arg-parser.js";
 import { blockedDecisionHandoff, printJson } from "./cli-output.js";
 import { buildCodexGoalInstruction, type UlwLoopGoalInstruction } from "./codex-goal-instruction.js";
@@ -32,6 +33,12 @@ export async function checkpoint(
 	json: boolean,
 	scope?: UlwLoopScope,
 ): Promise<number> {
+	if (hasFlag(argv, "--print-template")) {
+		const template = await checkpointTemplate(repoRoot, scope, readValue(argv, "--goal-id"));
+		if (json) printJson({ ok: true, ...template });
+		else printJson(template);
+		return 0;
+	}
 	const goalId = required(argv, "--goal-id");
 	const statusValue = checkpointStatus(required(argv, "--status"));
 	const evidence = required(argv, "--evidence");

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

@@ -1,10 +1,34 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
+import type { CodexGoalReconciliation, CodexGoalSnapshot } from "./codex-goal-snapshot.js";
+import { codexGoalMismatchRecovery, formatCodexGoalReconciliation } from "./codex-goal-snapshot.js";
 import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
 import { type UlwLoopScope, ulwLoopBriefPath } from "./paths.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
-import { ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
+import { ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
+
+export interface CodexSnapshotMismatchInput {
+	readonly reconciliation: CodexGoalReconciliation;
+	readonly snapshot: CodexGoalSnapshot | null | undefined;
+	readonly expectedObjective: string;
+	/** Only the checkpoint path can fall back to task-scoped aggregate reconciliation, so only it asks for that hint. */
+	readonly taskScopedHint?: { readonly goal: UlwLoopItem; readonly aggregate: boolean; readonly final: boolean };
+}
+
+export function codexSnapshotMismatchError(input: CodexSnapshotMismatchInput): UlwLoopError {
+	const { reconciliation, snapshot, taskScopedHint } = input;
+	const hint =
+		taskScopedHint?.aggregate === true && snapshot?.status === "complete" && snapshot.objective !== undefined
+			? buildTaskScopedAggregateReconciliationHint(taskScopedHint.goal, taskScopedHint.final)
+			: "";
+	const recovery = codexGoalMismatchRecovery(input.expectedObjective, snapshot);
+	return new UlwLoopError(
+		`${formatCodexGoalReconciliation(reconciliation)}${hint}\n${recovery.message}`,
+		"ulw_loop_codex_snapshot_mismatch",
+		{ details: recovery.details },
+	);
+}
 
 function normalizeObjective(value: string): string {
 	return value.replace(/\s+/g, " ").trim();

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

@@ -0,0 +1,127 @@
+import { type UlwLoopScope, ulwLoopAttemptEvidenceDir } from "./paths.js";
+import { readUlwLoopPlan } from "./plan-io.js";
+import { resolveToolkitSurface, type UlwLoopToolkitSurface } from "./surface.js";
+import type { UlwLoopPlan } from "./types.js";
+import { UlwLoopError } from "./types.js";
+
+export interface CheckpointTemplate {
+	readonly qualityGateTemplate: Record<string, unknown>;
+	readonly codexGoalTemplate: Record<string, unknown>;
+	readonly attemptDir?: string;
+	readonly guidance?: string;
+}
+
+function artifactPath(base: string, name: string): string {
+	return `${base}/${name}`;
+}
+
+function gateTemplate(surface: UlwLoopToolkitSurface, base: string): Record<string, unknown> {
+	const artifacts = [
+		{
+			id: "artifact-cli",
+			kind: "cli-transcript",
+			description: "<replace:artifact description>",
+			path: artifactPath(base, "cli-transcript.txt"),
+		},
+		{
+			id: "artifact-data",
+			kind: "data-diff",
+			description: "<replace:artifact description>",
+			path: artifactPath(base, "data-diff.txt"),
+		},
+	];
+	const manualQa = {
+		by: surface === "omo-senpi" ? "main-session" : "lazycodex-qa-executor",
+		status: "passed",
+		evidence: "<replace:manual QA evidence>",
+		surfaceEvidence: [
+			{
+				id: "surface-cli",
+				criterionRef: "<replace:criterion id>",
+				surface: "cli",
+				invocation: "<replace:command>",
+				verdict: "passed",
+				artifactRefs: ["artifact-cli"],
+			},
+			{
+				id: "surface-data",
+				criterionRef: "<replace:criterion id>",
+				surface: "data",
+				invocation: "<replace:command>",
+				verdict: "passed",
+				artifactRefs: ["artifact-data"],
+			},
+		],
+		adversarialCases: [
+			{
+				id: "<replace:adversarial case id>",
+				criterionRef: "<replace:criterion id>",
+				scenario: "<replace:scenario>",
+				expectedBehavior: "<replace:expected behavior>",
+				verdict: "not_applicable",
+				reason: "<replace:reason>",
+				artifactRefs: ["artifact-cli"],
+			},
+		],
+		artifactRefs: artifacts,
+	};
+	const common = {
+		manualQa,
+		gateReview: {
+			by: surface === "omo-senpi" ? "category:deep" : "lazycodex-gate-reviewer",
+			recommendation: "APPROVE",
+			reportPath: artifactPath(base, "gate-review.md"),
+			evidence: "<replace:gate review evidence>",
+			blockers: [],
+		},
+		iteration: {
+			fullRerun: true,
+			status: "passed",
+			rerunCommands: ["<replace:verification command>"],
+			evidence: "<replace:iteration evidence>",
+		},
+		criteriaCoverage: {
+			totalCriteria: 0,
+			passCount: 0,
+			originalIntent: "<replace:original intent>",
+			desiredOutcome: "<replace:desired outcome>",
+			userOutcomeReview: "<replace:user outcome review>",
+			adversarialClassesCovered: ["<replace:adversarial class>"],
+		},
+	};
+	if (surface === "omo-senpi") return common;
+	return {
+		codeReview: {
+			by: "lazycodex-code-reviewer",
+			recommendation: "APPROVE",
+			codeQualityStatus: "CLEAR",
+			reportPath: artifactPath(base, "code-review.md"),
+			evidence: "<replace:code review evidence>",
+			blockers: [],
+		},
+		...common,
+	};
+}
+
+export async function checkpointTemplate(
+	repoRoot: string,
+	scope?: UlwLoopScope,
+	goalId?: string,
+): Promise<CheckpointTemplate> {
+	const plan: UlwLoopPlan = await readUlwLoopPlan(repoRoot, scope);
+	const targetId = goalId ?? plan.activeGoalId;
+	const active = plan.goals.find((goal) => goal.id === targetId);
+	if (goalId !== undefined && active === undefined)
+		throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
+	const hasAttempt = plan.evidenceLayoutVersion === 2 && active !== undefined;
+	const attemptDir = hasAttempt ? ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) : ".omo/evidence";
+	return {
+		qualityGateTemplate: gateTemplate(resolveToolkitSurface(), attemptDir),
+		codexGoalTemplate: {
+			goal: { objective: plan.codexObjective ?? "<replace:codex objective>", status: "complete" },
+		},
+		...(hasAttempt
+			? { attemptDir }
+			: { guidance: "This plan is evidence-layout v1; artifacts go under .omo/evidence/." }),
+	};
+}