lazycodex-ai 5.0.0-beta.7 → 5.0.0-beta.71

package/packages/omo-codex/plugin/components/ulw-loop/README.md

@@ -21,7 +21,17 @@ Every subcommand below is implemented. Pass `--json` where supported for machine
 | `omo-agent-toolkit ulw-loop record-evidence` | Record observable evidence for one criterion. |
 | `omo-agent-toolkit ulw-loop record-review-blockers` | Mark a goal as review-blocked and add follow-up work from final-review findings. |
 
-The final quality gate parsed by `checkpoint` validates `codeReview`, `manualQa`, `gateReview`, `iteration`, and `criteriaCoverage`. `criteriaCoverage` records the original intent, desired outcome, user-facing outcome review, pass counts, and covered adversarial classes.
+The final quality gate parsed by `checkpoint` requires `manualQa`, `gateReview`, `iteration`, and `criteriaCoverage`; lazycodex accepts optional `codeReview`. Lazycodex defaults to `main-session` self-review, with `category:*` and reviewer acceptors available when needed. `criteriaCoverage` records the original intent, desired outcome, user-facing outcome review, pass counts, and covered adversarial classes. The companion `codex-goal-json` must contain `goal.objective` equal to the plan's `codexObjective` verbatim.
+
+A complete passing checkpoint uses both payloads:
+
+```json
+{"goal":{"objective":"Ship the requested behavior","status":"complete"}}
+```
+
+```json
+{"gateReview":{"by":"main-session","recommendation":"APPROVE","reportPath":".omo/evidence/gate-review.md","evidence":"Gate review passed.","blockers":[],"notes":[]},"manualQa":{"by":"lazycodex-qa-executor","status":"passed","evidence":"Manual QA passed.","surfaceEvidence":[{"id":"cli","criterionRef":"C1","surface":"cli","invocation":"omo-agent-toolkit ulw-loop checkpoint --json","verdict":"passed","artifactRefs":["cli-artifact"]}],"adversarialCases":[{"id":"malformed","criterionRef":"C2","scenario":"Malformed input","expectedBehavior":"Rejected","verdict":"not_applicable","reason":"Not triggered","artifactRefs":["cli-artifact"]}],"artifactRefs":[{"id":"cli-artifact","kind":"cli-transcript","description":"Passing CLI transcript","path":".omo/evidence/cli.txt"}]},"codeReview":{"by":"lazycodex-code-reviewer","recommendation":"APPROVE","codeQualityStatus":"CLEAR","reportPath":".omo/evidence/code-review.md","evidence":"Code review passed.","blockers":[]},"iteration":{"fullRerun":true,"status":"passed","rerunCommands":["bun test"],"evidence":"Full rerun passed."},"criteriaCoverage":{"totalCriteria":2,"passCount":2,"originalIntent":"Ship the requested behavior","desiredOutcome":"The behavior works for users.","userOutcomeReview":"The result matches the requested outcome.","adversarialClassesCovered":["malformed_input"]}}
+```
 
 Validation batches are optional review boundaries declared at plan creation with `--validation-batch-json '[{"batchId":"VB001","memberIds":[...],"finalGoalId":"..."}]'`. The batch-final goal cannot complete until every other member is complete or superseded-resolved, every member criterion is pass, and a quality gate's coverage counts match the recomputed member criteria. Steering split/supersede mutations keep batch membership consistent and record `batch_updated`.
 
@@ -35,6 +45,7 @@ This directory is a component of the aggregate `@sisyphuslabs/omo-codex-plugin`
   - `PreToolUse` matching the spawn tool tokens -> `node "${PLUGIN_ROOT}/dist/cli.js" hook pre-tool-use-spawn` (fan-out cap + gate-artifact preflight)
   - `Stop` -> `node "${PLUGIN_ROOT}/dist/cli.js" hook stop` (auto-resume with a two-strike no-progress cap)
 - `skills/ulw-loop/` for the bundled `ulw-loop` skill.
+- `directive.md`, the ultrawork directive read at runtime when `--with-ultrawork` falls back to the full text. This package is published standalone and takes no dependency on `@oh-my-opencode/prompts-core`, so it intentionally bundles its own byte-identical copy of the canonical `packages/prompts-core/prompts/ultrawork/codex.md`. The copy is generated by `components/ultrawork/scripts/sync-directive.mjs` and pinned byte-for-byte by `test/ultrawork-directive.test.ts`; do not hand-edit it.
 - `bin.omo-ulw-loop` -> `dist/cli.js` for standalone CLI invocation.
 
 This component ships a CLI, a skill, and hooks. It does not expose an MCP server.

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

@@ -1,9 +1,9 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.5.9/schema.json",
 	"linter": {
 		"enabled": true,
 		"rules": {
-			"recommended": true,
+			"preset": "recommended",
 			"style": {
 				"noDefaultExport": "error",
 				"noEnum": "error",

package/packages/omo-codex/plugin/components/ulw-loop/directive.md

@@ -46,8 +46,8 @@ first-class for CLI- or data-shaped work; self-review recorded in the
 notepad instead of the reviewer loop.
 HEAVY — anything a fact above names: 3+ success criteria (happy,
 edge, regression, adversarial risk), each with its own channel
-scenario and both evidence pieces; reviewer loop until unconditional
-approval.
+scenario and both evidence pieces; when the verification gate is
+triggered, run the reviewer loop until unconditional approval.
 
 # Manual-QA channels
 Run real-surface proof yourself through the channel that faithfully
@@ -62,11 +62,18 @@ exercises the surface; capture the artifact.
      for color / layout / CJK evidence, which degrades truecolor.
   3. Browser use — in Codex, use `browser:control-in-app-browser`
      first when available and no authenticated/persistent user browser
-     profile is required. Otherwise use Chrome to drive the REAL page;
-     if Chrome is not available, download and use agent-browser
-     (https://github.com/vercel-labs/agent-browser). Capture action
+     profile is required. Otherwise, or for Chrome semantics, stealth,
+     or trace, WRITE a `playwright-core` script and run it from js eval
+     against local Chrome (`chromium.launch({ channel: "chrome" })` /
+     `launchPersistentContext` on a CLONED profile). Capture action
      log + screenshot path. Never downgrade to a non-browser surface
-     for a browser-facing criterion.
+     for a browser-facing criterion. NEVER clear cookies, cache, or
+     site data (`Network.clearBrowserCookies`, `Storage.clearCookies`,
+     `chrome.browsingData.remove`, "clear browsing data") on the user's
+     real/main browser profile — it wipes their logged-in state. If you
+     need that profile's login state, clone it first (`rsync -a
+     <profile>/ <tmp-clone>/`) and launch Chrome against
+     the clone as the user-data-dir; run any clearing there only.
   4. Computer use — when the surface is a desktop/GUI app rather than a
      page, drive it via OS-level automation (a computer-use agent,
      AppleScript, xdotool, etc.) against the running app; capture
@@ -223,8 +230,8 @@ and utility functions to batch commands and reduce output. Keep direct calls
 when one result chooses the next action, outputs are already small, semantic
 judgment is required between calls, approval or side effects are involved,
 or native artifacts / citations must be preserved.
-- Architecture / flow / blast radius → `codegraph_explore` first when
-  `codegraph_*` exists; if unavailable, continue with repo tools and LSP.
+- Architecture / flow / blast radius → explore agents plus LSP references
+  and impact; do not guess from conventions.
 - **SYMBOLS REQUIRE LSP** — definitions, references, rename impact,
   workspace symbols, and diagnostics use the available `lsp_*` tools, not
   text search. Run diagnostics after edits and treat errors as blocking.
@@ -334,17 +341,26 @@ make the child continue old parent context instead of the delegated task.
 If your tool list has a flat `spawn_agent` with a required `task_name` instead of `multi_agent_v1.*` (`multi_agent_v2`), rewrite: `fork_context: false` becomes `fork_turns: "none"`, `send_input` becomes `send_message`, finished agents end on their own (no `close_agent`; `followup_task` re-tasks, `interrupt_agent` stops), and `wait_agent` takes only `timeout_ms`, returning on any child mailbox activity.
 
 # TOML-backed subagent routing compatibility
-Installed role TOMLs (`~/.codex/agents/`) bind ONLY via `agent_type`.
-`multi_agent_v1.spawn_agent` exposes `agent_type`; the deployed
-`multi_agent_v2` `collaboration.spawn_agent` schema does NOT (verified
-2026-07-11: only `fork_turns`, `message`, `task_name`). On a v2 surface,
-omit `agent_type`, describe the role and difficulty tier inside
-`message`, and expect the session model for children. Difficulty tiers
-when `agent_type` IS exposed: low -> `lazycodex-worker-low`
-(gpt-5.6-luna/high), medium -> `lazycodex-worker-medium`
-(gpt-5.6-luna/max), high -> `lazycodex-worker-high` (gpt-5.6-sol/max);
-explorer/librarian carry their own TOMLs (gpt-5.6-luna/low). Difficulty
-(model power) is orthogonal to LIGHT/HEAVY rigor (process size).
+Inspect the ACTUAL spawn tool schema, not a version or namespace assumption.
+When `agent_type` is exposed (V1 or V2), EVERY spawn MUST pass an exact
+LazyCodex role: `explorer`, `librarian`, `plan`, `metis`, `momus`,
+`lazycodex-worker-low`, `lazycodex-worker-medium`, `lazycodex-worker-high`,
+`lazycodex-code-reviewer`, `lazycodex-qa-executor`, `lazycodex-gate-reviewer`,
+or `lazycodex-clone-fidelity-reviewer`. Map implementation difficulty to
+worker low/medium/high; their installed TOMLs supply model and instructions.
+Never select generic `worker`/`default` or describe a role instead of selecting it.
+Use `fork_turns: "none"` on V2 or `fork_context: false` on V1 unless full
+history is deliberately required; even a deliberate fork MUST name its role.
+
+Legacy-schema exception: ONLY when `agent_type` is absent, omit that unsupported
+field and carry the role, difficulty, and complete instructions in `message`;
+explicitly disable history. This cannot select a specialized TOML. The managed
+`default` supplies the medium worker for unnamed non-forks, unless opted out or
+blocked by a preserved user default. The spawn guard cannot see the schema and
+rejects unnamed requests: report incompatible routing, do not retry generically.
+An unnamed full-history fork skips role application inside Codex; no LazyCodex
+config can fix that upstream gap. Never claim this path has been repaired.
+Difficulty (model power) is orthogonal to LIGHT/HEAVY rigor (process size).
 
 Treat child status as a progress signal, not a timeout counter. For
 work likely to exceed one wait cycle, tell the child to send
@@ -379,16 +395,17 @@ BLOCKED: <reason>`. After four silent or ack-only checks, close the lane as
 inconclusive, record that it is not approval, and respawn smaller only
 if the deliverable is still required.
 
-# Verification gate (TRIGGERED, NOT OPTIONAL)
+# Verification gate (TRIGGERED ONLY ON EXPLICIT DEMAND)
 
-Trigger when ANY apply:
-- Tier is HEAVY.
-- User demanded strict, rigorous, or proper review.
-LIGHT tier records a self-review in the notepad instead: re-read the
-diff, run diagnostics, confirm each criterion's evidence, and state in
-one line why the tier held.
+Trigger ONLY when the user explicitly demanded strict, rigorous, proper,
+or high-accuracy review of this work, in any language (for example,
+고정밀 or 엄격). The tier alone never triggers the gate. HEAVY without
+such a demand records the same self-review as LIGHT.
+LIGHT and non-triggered HEAVY work records a self-review in the notepad
+instead: re-read the diff, run diagnostics, confirm each criterion's
+evidence, and state in one line why the tier held.
 
-Procedure (NON-NEGOTIABLE):
+When triggered, follow this procedure (NON-NEGOTIABLE):
 1. Spawn a child with `fork_context: false` and a self-contained reviewer
    assignment in `message`. The `multi_agent_v1.spawn_agent` schema cannot select a
    TOML-backed reviewer role, so paste the reviewer requirements into

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

@@ -0,0 +1,18 @@
+import type { UlwLoopScope } from "./paths.js";
+import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+import { UlwLoopError } from "./types.js";
+export interface CheckpointCodexGoalValidation {
+    readonly raw: unknown;
+    readonly nextActions: readonly string[];
+    readonly warnings: readonly string[];
+    readonly unacknowledgedObjective?: string;
+}
+export declare function validateCheckpointCodexGoal(input: {
+    readonly repoRoot: string;
+    readonly plan: UlwLoopPlan;
+    readonly goal: UlwLoopItem;
+    readonly raw: string | undefined;
+    readonly evidence: string;
+    readonly scope?: UlwLoopScope;
+}): Promise<CheckpointCodexGoalValidation>;
+export declare function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError;

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

@@ -0,0 +1,30 @@
+import { CodexGoalSnapshotError, formatCodexGoalReconciliation, readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot, } from "./codex-goal-snapshot.js";
+import { acknowledgedDriverObjectives } from "./driver-objective-ack.js";
+import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective } from "./goal-status.js";
+import { UlwLoopError } from "./types.js";
+export async function validateCheckpointCodexGoal(input) {
+    const snapshot = await readCodexGoalSnapshotInput(input.raw, input.repoRoot);
+    const expected = expectedCodexObjective(input.plan, input.goal);
+    const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
+        expectedObjective: expected,
+        acknowledgedObjectives: acknowledgedDriverObjectives(input.plan),
+        ...(codexGoalMode(input.plan) === "aggregate"
+            ? { acceptedObjectives: compatibleCodexObjectives(input.plan) }
+            : {}),
+    });
+    if (!reconciliation.ok)
+        throw new CodexGoalSnapshotError(formatCodexGoalReconciliation(reconciliation));
+    return {
+        raw: snapshot?.raw,
+        nextActions: reconciliation.nextActions,
+        warnings: reconciliation.warnings,
+        ...(reconciliation.unacknowledgedObjective === undefined
+            ? {}
+            : { unacknowledgedObjective: reconciliation.unacknowledgedObjective }),
+    };
+}
+export function combineCheckpointValidationErrors(codexError, gateError) {
+    return new UlwLoopError(`${codexError.message}\n${gateError.message}`, "ULW_LOOP_QUALITY_GATE_INVALID", {
+        details: { ...(codexError.details ?? {}), ...(gateError.details ?? {}) },
+    });
+}

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

@@ -1,4 +1,5 @@
 import { 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 } from "./codex-goal-instruction.js";
@@ -15,13 +16,18 @@ export async function checkpointAndContinue(repoRoot, args, scope) {
     return { ...result, plan: next.plan, next: { resumed: next.resumed, goal: next.goal, instruction } };
 }
 export async function checkpoint(repoRoot, argv, json, scope) {
+    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");
-    const codexGoalJson = await parseCodexGoalJson(statusValue === "complete" ? required(argv, "--codex-goal-json") : readValue(argv, "--codex-goal-json"));
-    if (statusValue === "complete" && codexGoalJson === undefined) {
-        throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
-    }
+    const codexGoalJson = await parseCodexGoalJson(readValue(argv, "--codex-goal-json"));
     const qualityGateJson = readValue(argv, "--quality-gate-json");
     const args = {
         goalId,

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

@@ -1,5 +1,2 @@
-import { type UlwLoopScope } from "./paths.js";
-import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
-export declare function canReconcileCompletedTaskScopedAggregateSnapshot(repoRoot: string, plan: UlwLoopPlan, goal: UlwLoopItem, snapshotObjective: string, evidence: string, scope?: UlwLoopScope): Promise<boolean>;
-export declare function canReconcileActiveFinalTaskScopedAggregateSnapshot(repoRoot: string, plan: UlwLoopPlan, goal: UlwLoopItem, snapshotObjective: string, evidence: string, scope?: UlwLoopScope): Promise<boolean>;
-export declare function buildTaskScopedAggregateReconciliationHint(goal: UlwLoopItem, final: boolean): string;
+import { UlwLoopError } from "./types.js";
+export declare function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError;

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

@@ -1,79 +1,6 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
-import { ulwLoopBriefPath } from "./paths.js";
-import { ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
-function normalizeObjective(value) {
-    return value.replace(/\s+/g, " ").trim();
-}
-function textMentionsUlwLoopPlanArtifact(value) {
-    const normalized = (value ?? "").toLowerCase();
-    return (normalized.includes(ULW_LOOP_DIR.toLowerCase()) ||
-        normalized.includes(ULW_LOOP_GOALS.toLowerCase()) ||
-        normalized.includes(ULW_LOOP_LEDGER.toLowerCase()));
-}
-function textMentionsGoalId(value, goalId) {
-    return (value ?? "").toLowerCase().includes(goalId.toLowerCase());
-}
-function textHasCompletionValidationEvidence(value) {
-    const normalized = (value ?? "").toLowerCase();
-    const done = /\b(?:planned work|implementation|deliverables?|scope|task|work)\b/.test(normalized) &&
-        /\b(?:done|complete|completed|finished|shipped)\b/.test(normalized);
-    const verified = /\b(?:validation|verification|tests?|build|lint|review|quality gate|code-review)\b/.test(normalized) &&
-        /\b(?:passed|complete|completed|clean|green|approve|approved|clear)\b/.test(normalized);
-    return done && verified;
-}
-async function snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope) {
-    const actual = normalizeObjective(snapshotObjective).toLowerCase();
-    if (textMentionsUlwLoopPlanArtifact(actual))
-        return true;
-    if (actual.length < 24 || !existsSync(ulwLoopBriefPath(repoRoot, scope)))
-        return false;
-    try {
-        const brief = normalizeObjective(await readFile(ulwLoopBriefPath(repoRoot, scope), "utf8")).toLowerCase();
-        return brief.length >= 24 && (brief.includes(actual) || actual.includes(brief));
-    }
-    catch (error) {
-        if (error instanceof Error)
-            return false;
-        throw error;
-    }
-}
-export async function canReconcileCompletedTaskScopedAggregateSnapshot(repoRoot, plan, goal, snapshotObjective, evidence, scope) {
-    if (codexGoalMode(plan) !== "aggregate")
-        return false;
-    if (goal.status !== "in_progress" || plan.activeGoalId !== goal.id)
-        return false;
-    if (isFinalRunCompletionCandidate(plan, goal)) {
-        return snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope);
-    }
-    if (!textMentionsUlwLoopPlanArtifact(evidence) || !textMentionsGoalId(evidence, goal.id))
-        return false;
-    if (!textHasCompletionValidationEvidence(evidence))
-        return false;
-    return snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope);
-}
-export async function canReconcileActiveFinalTaskScopedAggregateSnapshot(repoRoot, plan, goal, snapshotObjective, evidence, scope) {
-    if (codexGoalMode(plan) !== "aggregate")
-        return false;
-    if (goal.status !== "in_progress" || plan.activeGoalId !== goal.id)
-        return false;
-    if (!isFinalRunCompletionCandidate(plan, goal))
-        return false;
-    if (!textHasCompletionValidationEvidence(evidence))
-        return false;
-    return snapshotObjectiveMapsToUlwLoopPlan(repoRoot, snapshotObjective, scope);
-}
-function buildCompletedLegacyGoalRemediation(goal) {
-    return [
-        "If get_goal returns a different completed legacy/thread objective, do not repeat --status complete in this thread.",
-        `Record a non-terminal blocker with: omo-agent-toolkit ulw-loop checkpoint --goal-id ${goal.id} --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json "<different completed get_goal JSON or path>".`,
-        "Then continue only from a Codex goal context with no active/completed conflicting goal, in the same repo/worktree, and create the intended goal there.",
-    ].join(" ");
-}
-export function buildTaskScopedAggregateReconciliationHint(goal, final) {
-    if (final) {
-        return ` Final task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress final OMO goal and the completed get_goal objective to map to the ulw-loop brief or artifact. ${buildCompletedLegacyGoalRemediation(goal)}`;
-    }
-    return ` Completed task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress OMO goal, evidence that names that active OMO goal id, names .omo/ulw-loop/goals.json or ledger.jsonl, includes completed implementation plus validation/review evidence, and a get_goal objective that maps to the ulw-loop brief/artifact. ${buildCompletedLegacyGoalRemediation(goal)}`;
+import { UlwLoopError } from "./types.js";
+export function combineCheckpointValidationErrors(codexError, gateError) {
+    return new UlwLoopError(`${codexError.message}\n${gateError.message}`, "ULW_LOOP_QUALITY_GATE_INVALID", {
+        details: { ...(codexError.details ?? {}), ...(gateError.details ?? {}) },
+    });
 }

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

@@ -0,0 +1,12 @@
+import { type UlwLoopScope } from "./paths.js";
+import { type UlwLoopToolkitSurface } from "./surface.js";
+export interface CheckpointTemplate {
+    readonly qualityGateTemplate: Record<string, unknown>;
+    readonly codexGoalTemplate: Record<string, unknown>;
+    readonly attemptDir?: string;
+    readonly guidance?: string;
+}
+export interface CheckpointTemplateDependencies {
+    readonly surface?: UlwLoopToolkitSurface;
+}
+export declare function checkpointTemplate(repoRoot: string, scope?: UlwLoopScope, goalId?: string, dependencies?: CheckpointTemplateDependencies): Promise<CheckpointTemplate>;

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

@@ -0,0 +1,114 @@
+import { ulwLoopAttemptEvidenceDir } from "./paths.js";
+import { readUlwLoopPlan } from "./plan-io.js";
+import { resolveToolkitSurface } from "./surface.js";
+import { UlwLoopError } from "./types.js";
+function artifactPath(base, name) {
+    return `${base}/${name}`;
+}
+function gateTemplate(surface, base) {
+    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: "main-session",
+        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" : "main-session",
+            recommendation: "APPROVE",
+            reportPath: artifactPath(base, "gate-review.md"),
+            evidence: "<replace:gate review evidence>",
+            blockers: [],
+            notes: [],
+        },
+        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>"],
+        },
+    };
+    return common;
+}
+export async function checkpointTemplate(repoRoot, scope, goalId, dependencies) {
+    const plan = await readUlwLoopPlan(repoRoot, scope);
+    const surface = dependencies?.surface ?? resolveToolkitSurface();
+    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";
+    const guidance = [
+        "codex-goal-json requires goal.objective to equal the plan's codexObjective verbatim; do not paraphrase it.",
+        "Fill every <replace:...> value with plausible non-empty evidence and use real, non-empty artifact files.",
+        'Passing codex-goal-json example: {"goal":{"objective":"<plan codexObjective verbatim>","status":"complete"}}.',
+        'Passing quality-gate-json example requires gateReview {"by":"category:deep","recommendation":"APPROVE","evidence":"review passed","reportPath":"<attemptDir>/gate-review.md","blockers":[],"notes":[]}, manualQa.artifactRefs objects, iteration, and criteriaCoverage.',
+        ...(surface === "lazycodex"
+            ? [
+                "Self-review defaults: manualQa.by and gateReview.by are main-session. Alternatives: manualQa.by accepts lazycodex-qa-executor; gateReview.by accepts lazycodex-gate-reviewer, category:deep, category:unspecified-high, or category:unspecified-low. Optional codeReview.by accepts lazycodex-code-reviewer or main-session.",
+            ]
+            : []),
+        ...(hasAttempt ? [] : ["This plan is evidence-layout v1; artifacts go under .omo/evidence/."]),
+    ].join(" ");
+    return {
+        qualityGateTemplate: gateTemplate(surface, attemptDir),
+        codexGoalTemplate: {
+            goal: { objective: plan.codexObjective ?? "<replace:codex objective>", status: "complete" },
+        },
+        guidance,
+        ...(hasAttempt ? { attemptDir } : {}),
+    };
+}

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

@@ -1,4 +1,5 @@
 import type { UlwLoopScope } from "./paths.js";
+import { type UlwLoopToolkitSurface } from "./surface.js";
 import type { UlwLoopAggregateCompletion, UlwLoopItem, UlwLoopLedgerEntry, UlwLoopPlan } from "./types.js";
 export interface CheckpointUlwLoopArgs {
     readonly goalId: string;
@@ -7,10 +8,15 @@ export interface CheckpointUlwLoopArgs {
     readonly codexGoalJson?: string;
     readonly qualityGateJson?: string;
 }
+export interface CheckpointUlwLoopDependencies {
+    readonly surface?: UlwLoopToolkitSurface;
+}
 export interface CheckpointUlwLoopResult {
     readonly plan: UlwLoopPlan;
     readonly goal: UlwLoopItem;
     readonly ledgerEntry: UlwLoopLedgerEntry;
     readonly aggregateCompletion?: UlwLoopAggregateCompletion;
+    readonly nextActions: readonly string[];
+    readonly warnings: readonly string[];
 }
-export declare function checkpointUlwLoop(repoRoot: string, args: CheckpointUlwLoopArgs, scope?: UlwLoopScope): Promise<CheckpointUlwLoopResult>;
+export declare function checkpointUlwLoop(repoRoot: string, args: CheckpointUlwLoopArgs, scope?: UlwLoopScope, dependencies?: CheckpointUlwLoopDependencies): Promise<CheckpointUlwLoopResult>;