lazycodex-ai 5.0.0-beta.9 → 5.0.0

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

@@ -0,0 +1,21 @@
+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 LEGACY_REVIEWER_AGENT_ALIASES: Readonly<Record<string, string>>;
+export declare function canonicalReviewerAgentName(reviewer: string): string;
+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 OPTIONAL_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,100 @@
+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-native-code-reviewer",
+        manualQa: "omo-native-qa-executor",
+        gateReview: "omo-native-gate-reviewer",
+    },
+};
+// The reviewer agents were renamed omo-senpi-* -> omo-native-*. The retired spellings stay
+// resolvable for one release line so a caller that still names one is recognized rather than
+// silently treated as a non-review spawn.
+export const LEGACY_REVIEWER_AGENT_ALIASES = {
+    "omo-senpi-code-reviewer": REVIEWER_ROLES_BY_SURFACE["omo-senpi"].codeReview,
+    "omo-senpi-qa-executor": REVIEWER_ROLES_BY_SURFACE["omo-senpi"].manualQa,
+    "omo-senpi-gate-reviewer": REVIEWER_ROLES_BY_SURFACE["omo-senpi"].gateReview,
+};
+export function canonicalReviewerAgentName(reviewer) {
+    return LEGACY_REVIEWER_AGENT_ALIASES[reviewer] ?? reviewer;
+}
+const CANONICAL_GATE_REVIEW_NAMES = Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview);
+export const GATE_REVIEWER_AGENT_NAMES = new Set([
+    ...CANONICAL_GATE_REVIEW_NAMES,
+    ...Object.entries(LEGACY_REVIEWER_AGENT_ALIASES)
+        .filter(([, canonical]) => CANONICAL_GATE_REVIEW_NAMES.includes(canonical))
+        .map(([legacy]) => legacy),
+]);
+export const REQUIRED_GATE_SECTIONS_BY_SURFACE = {
+    lazycodex: ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+    "omo-senpi": ["manualQa", "gateReview", "iteration", "criteriaCoverage"],
+};
+export const OPTIONAL_GATE_SECTIONS_BY_SURFACE = {
+    lazycodex: ["codeReview"],
+    "omo-senpi": [],
+};
+export const GATE_SECTION_BY_ACCEPTOR = {
+    lazycodex: {
+        codeReview: [REVIEWER_ROLES_BY_SURFACE.lazycodex.codeReview, "main-session"],
+        manualQa: [REVIEWER_ROLES_BY_SURFACE.lazycodex.manualQa, "main-session"],
+        gateReview: [
+            REVIEWER_ROLES_BY_SURFACE.lazycodex.gateReview,
+            "category:deep-high",
+            "category:deep-low",
+            "category:deep",
+            "category:unspecified-high",
+            "category:unspecified-low",
+            "main-session",
+        ],
+    },
+    "omo-senpi": {
+        manualQa: ["main-session"],
+        gateReview: [
+            "category:deep-high",
+            "category:deep-low",
+            "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,20 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.9) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0) Checking Ulw-Loop Steering"
+					}
+				]
+			}
+		],
+		"PostToolUse": [
+			{
+				"matcher": "^(spawn_agent|multi_agent_v1\\.spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use-spawn",
+						"timeout": 5,
+						"statusMessage": "(OmO 5.0.0) Recording Spawn Admission"
 					}
 				]
 			}
@@ -20,18 +33,18 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.9) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
 			{
-				"matcher": "^(spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
+				"matcher": "^(spawn_agent|multi_agent_v1\\.spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
 				"hooks": [
 					{
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.9) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -43,7 +56,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.9) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0) 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.9",
+	"version": "5.0.0",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",
@@ -38,7 +38,7 @@
 		"CHANGELOG.md"
 	],
 	"scripts": {
-		"build": "tsc -p tsconfig.build.json",
+		"build": "tsc -p tsconfig.build.json && bun build src/cli.ts --target node --format esm --outfile dist/cli.js",
 		"test": "vitest --run",
 		"test:watch": "vitest",
 		"typecheck": "tsc --noEmit",
@@ -47,10 +47,11 @@
 		"check": "tsc --noEmit && biome check . && npm run build"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.4.16",
-		"@types/node": "^25.9.3",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.8"
+		"@vitest/coverage-v8": "5.0.1",
+		"@biomejs/biome": "2.5.14",
+		"@types/node": "^26.6.2",
+		"typescript": "^7.0.2",
+		"vitest": "5.0.1"
 	},
 	"engines": {
 		"node": ">=20.0.0"

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

@@ -1,6 +1,6 @@
 ---
 name: ulw-loop
-description: Goal-like loop that uses ultrawork mode to decompose work into systematic, evidence-bound steps.
+description: "A goal-like loop that decomposes work into systematic, evidence-bound ultrawork steps. Use when the user wants a goal loop or durable, checkpointed execution."
 metadata:
   short-description: Goal-like ultrawork loop for systematic decomposition
 ---
@@ -23,7 +23,8 @@ This skill is intentionally compact. The full workflow lives in `references/full
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
 - Register goals up front, shaped by `references/define-goal.md` (`omo-agent-toolkit ulw-loop create-goals`, then `create_goal` from the printed handoff), and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo-agent-toolkit ulw-loop status --json`, then resume; never re-plan from scratch.
-- If `omo-agent-toolkit ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
+- Every ulw-loop command needs the session scope: pass `--session-id <id>` (the printed handoff and resume directive carry it; `CODEX_THREAD_ID` in the environment also resolves it). The CLI refuses unscoped state (`ULW_LOOP_SESSION_SCOPE_REQUIRED`) instead of touching the shared `.omo/ulw-loop` root.
+- If `omo-agent-toolkit ulw-loop create-goals` says this session's aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` (passed on every later call) instead of steering or forcing the completed state. Use `--force` only to intentionally overwrite completed evidence.
 - Every success criterion needs observable evidence from a real surface: a channel (terminal/TUI via the xterm.js web terminal, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
 - Evidence is bound to the tree it was captured at (`git rev-parse --short "HEAD^{tree}"`); it goes stale only when tracked content changes — a rebase or amend that keeps the tree identical keeps it valid. When the tree differs, re-run at the current HEAD and re-record, never relabel or regenerate. Record only after cleanup receipts exist.
 - Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.
@@ -67,3 +68,7 @@ Codex exposes ONE subagent surface per session — check your tool list. GPT-5.6
 V1 fallback (gpt-5.5, gpt-5.6-luna): `multi_agent_v1.spawn_agent({...,"fork_context":false})`, `multi_agent_v1.send_input` (re-task), `multi_agent_v1.wait_agent({"targets":[...],"timeout_ms":...})`, `multi_agent_v1.close_agent`.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`.
+
+## Driver goal lifecycle
+
+The Codex thread goal is a DRIVER the loop instructs, never a gate. `checkpoint` takes an OPTIONAL `--codex-goal-json` snapshot, records it verbatim in the ledger, and never rejects on its status or objective; the advice arrives in `nextActions`. A driver completed early yields advice to `create_goal` again with the plan's objective verbatim; `paused`, `usage_limited`, and `budget_limited` yield resume advice; a differing objective is a warning, not a refusal. Malformed snapshot input is the only failure, reported as `ULW_LOOP_CODEX_GOAL_JSON_INVALID`.

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/define-goal.md

@@ -39,8 +39,7 @@ Every criterion carries, at definition time, not after the work:
 
 - a binary pass condition ("returns 200 and the body matches the schema", never "works correctly");
 - the exact scenario: the literal command, request, page action, or payload that will prove it;
-- the evidence artifact it will capture: transcript, status plus body, screenshot path, diff, parsed dump;
-- the failing-first proof (test id or scenario) that will be captured RED before implementation.
+- the evidence artifact it will capture: transcript, status plus body, screenshot path, diff, parsed dump.
 
 A criterion that cannot fail is not a criterion. If no input could make the scenario fail, it measures nothing; rewrite it until failure is possible.
 
@@ -50,7 +49,7 @@ Prefer numbers that represent real success over decorative precision. A threshol
 
 | Domain | Quantify as |
 | --- | --- |
-| Bug fix | reproduction first, fix second: the failing case captured RED, then the same validator green |
+| Bug fix | reproduction first, fix second: the failing case captured before, the same case passing after |
 | Tests | the exact command and required pass condition, plus run count for flake-sensitive suites |
 | Performance | metric, target threshold, measurement method, and run count ("p95 under 250ms across 3 consecutive local runs") |
 | Quality work | the observable acceptance bar: lint, typecheck, and test pass; reviewed examples; a user-approved artifact |

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

@@ -13,14 +13,14 @@ Use GPT-5.x style: outcome-first, evidence-bound, atomic decisions, no nested br
 Deliver every goal in `.omo/ulw-loop/goals.json` end-to-end.
 Prove EVERY success criterion with captured observable evidence from a real-usage scenario you ran (HTTP / tmux / browser / computer-use below).
 TESTS ALONE NEVER PROVE DONE. A green test suite is supporting evidence, not completion proof.
-Audit each pass, fail, block, steering change, and checkpoint in `.omo/ulw-loop/ledger.jsonl`.
+Audit each pass, fail, block, steering change, and checkpoint in `.omo/ulw-loop/<session-id>/ledger.jsonl`.
 
 ## Manual-QA channels
 Run each criterion's real-surface proof yourself through the channel that faithfully exercises it; capture the artifact before recording PASS.
 
-1. **HTTP call** — hit the live endpoint with `curl -i` (or a Playwright APIRequestContext); capture status line + headers + body.
+1. **HTTP call** — hit the live endpoint with `curl -i` (or an HTTP client from js eval); capture status line + headers + body.
 2. **Terminal / TUI** - prove it through the xterm.js web terminal; tmux `send-keys` is fine for a boot smoke, but NEVER `tmux capture-pane` for color/layout/CJK evidence (it degrades truecolor).
-3. **Browser use** — in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile. Otherwise use Chrome to drive the REAL page; if unavailable, use agent-browser. Capture action log + screenshot path. Never downgrade a browser-facing criterion.
+3. **Browser use** — in Codex, prefer `browser:control-in-app-browser`. Otherwise omowright from js eval (staged in the `browser` skill): the owned engine (`connectPipe` on a task-owned profile, `connectCloakProfile` for bot-scored targets) for unauthenticated pages, the attached engine (`connectBrowserSkill()` in the user's signed-in browser) when the page needs their login — never a clone of, or a launch against, the live profile. Capture action log + screenshot path. Never downgrade a browser-facing criterion.
 4. **Computer use** — for desktop/GUI apps, drive the running app via OS automation (computer-use, AppleScript, xdotool, etc.); capture action log + screenshot.
 
 For TUI visual QA (mandatory when a PR or review must inspect the terminal screen),
@@ -110,13 +110,16 @@ If `ULW_LOOP_CLI` is empty, open the durable notepad first, record the missing C
 
 Run one form:
 ```sh
-omo-agent-toolkit ulw-loop create-goals --brief "<brief>" [--validation-batch-json <json-or-path>] --json
-omo-agent-toolkit ulw-loop create-goals --brief-file <path> [--validation-batch-json <json-or-path>] --json
-cat <brief> | omo-agent-toolkit ulw-loop create-goals --from-stdin [--validation-batch-json <json-or-path>] --json
+omo-agent-toolkit ulw-loop create-goals --session-id <id> --brief "<brief>" [--validation-batch-json <json-or-path>] --json
+omo-agent-toolkit ulw-loop create-goals --session-id <id> --brief-file <path> [--validation-batch-json <json-or-path>] --json
+cat <brief> | omo-agent-toolkit ulw-loop create-goals --session-id <id> --from-stdin [--validation-batch-json <json-or-path>] --json
 ```
-If the existing aggregate is already complete, do not steer or force the
-completed default state for unrelated new work. Start a fresh run with
-`omo-agent-toolkit ulw-loop create-goals --session-id <new-id> ...`; use `--force`
+Every state subcommand runs against exactly one session scope: pass `--session-id <id>` on every call (the printed handoff and the Stop hook resume directive carry this session's id; `PI_SESSION_ID`, `CODEX_THREAD_ID`, `CODEX_SESSION_ID`, or `OMO_ULW_LOOP_SESSION_ID` in the environment also resolve it). The CLI refuses with `ULW_LOOP_SESSION_SCOPE_REQUIRED` when neither is present instead of touching the shared `.omo/ulw-loop` root, because eval kernels, subprocesses, and hooks do not inherit the session env and every session in the directory would otherwise read and overwrite the same plan. Mutations are serialized across processes by `.omo/ulw-loop/<id>/.state.lock`, so parallel `record-evidence` calls from several workers are safe; `ULW_LOOP_LOCK_TIMEOUT` means another live process held the state for more than 10s — retry, never delete the lock while that process is alive.
+If this session's aggregate is already complete, do not steer or force the
+completed state for unrelated new work. Start a fresh run with
+`omo-agent-toolkit ulw-loop create-goals --session-id <new-id> ...` and keep passing
+that id on every later call; the Stop hook auto-resume follows only the
+Codex session's own id, so a run under a custom id is resumed by hand. Use `--force`
 only when deliberately overwriting completed evidence.
 Write state through the CLI path. Do not hand-edit state files.
 
@@ -162,7 +165,7 @@ Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures a
 4. INTEGRATE + CRITICAL SELF-QA + GIT CHECKPOINT (EVERY WORKER RETURN): do NOT trust the worker's report. Read the diff yourself, re-run its tests, and run LSP diagnostics on the changed files. Treat "done" as a claim to disprove. If the diff drifts, the test is hollow, or evidence is missing, RESPAWN the worker with the specific failure context. Once the work unit is verified, use `git-master` before staging: inspect recent repository commits and touched-path history to infer commit language, Conventional Commit scope, message shape, and unit size. Stage only that unit's files and commit in the observed style; do not carry verified work forward into a later omnibus commit. If no git-tracked files changed or committing is unsafe, record the no-commit reason as evidence. Forward every finding/learning to subsequent workers.
 5. EXECUTE-AS-SCENARIO: ACTUALLY run the Manual-QA scenario the criterion named (channel table above). Run it yourself for the orchestrator check; for heavier flows dispatch a dedicated QA execution worker (`lazycodex-worker-medium` by default; `lazycodex-worker-high` when the QA flow itself is hard) whose ONLY job is to drive the channel and write the artifact to the named evidence path. If the scenario FAILS, respawn the implementing worker with the captured failure — do not hand-patch around it.
 6. CAPTURE: collect the observable artifact path: transcript, stdout, screenshot, assertion, status+body, diff, or parsed dump. No artifact written at the evidence path — not done; record BLOCKED and respawn QA.
-7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND close every finished worker (v1 `close_agent`; on V2 finished workers end on their own — `interrupt_agent` any still running). Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browsers / agent-browser sessions, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; interrupt_agent w-3`. Missing receipt → record BLOCKED, not PASS.
+7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND close every finished worker (v1 `close_agent`; on V2 finished workers end on their own — `interrupt_agent` any still running). Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browser contexts, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; interrupt_agent w-3`. Missing receipt → record BLOCKED, not PASS.
 8. RECORD one result immediately from the artifact you just wrote — never from memory or a later turn — stamping the capture tree `$(git rev-parse --short "HEAD^{tree}")` into the evidence:
    - PASS: `omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass --evidence "<observable> @tree:<short-tree> | <cleanup receipt>" --json`
    - FAIL: `omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status fail --evidence "<observable> @tree:<short-tree> | <cleanup receipt>" --notes "<diagnosis>" --json`
@@ -179,6 +182,24 @@ 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.
+# codex-goal-json.goal.objective must equal the plan's codexObjective verbatim.
+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 requires `manualQa`, `gateReview`, `iteration`, and `criteriaCoverage`; `codeReview` is optional. Self-review defaults to `main-session`, while gate review may use `main-session` or an approved `category:*` acceptor. Spawn reviewer lanes only when strict review is explicitly requested.
+
 ## 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.
@@ -192,12 +213,14 @@ Trigger only for the final aggregate goal after every criterion in every goal is
 ```sh
 omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete --evidence "<e2e evidence + manual QA notes>" --codex-goal-json <snapshot> --quality-gate-json <json-or-path> --json
 ```
+`--quality-gate-json` shape. In `manualQa.artifactRefs`, `kind` must be one of `cli-transcript`, `log`, `screenshot`, `image`, `http-dump`, or `data-diff`; review and QA reports belong in `codeReview.reportPath` or `gateReview.reportPath`, not `artifactRefs`. `surfaceEvidence.surface` must be one of `cli`, `http`, `tmux`, `browser`, `gui`, or `data`. Compatibility is `cli`/`tmux` -> `cli-transcript`/`log`, `http` -> `http-dump`, `browser`/`gui` -> `screenshot`/`image`, and `data` -> `data-diff`.
+
 `--quality-gate-json` shape:
 ```json
 {
   "codeReview":{"by":"lazycodex-code-reviewer","recommendation":"APPROVE","codeQualityStatus":"CLEAR","reportPath":"test/fixtures/artifacts/code-review.md","evidence":"Diff review passed.","blockers":[]},
   "manualQa":{"by":"lazycodex-qa-executor","status":"passed","evidence":"CLI and data surfaces passed.","surfaceEvidence":[{"id":"surface-cli-pass","criterionRef":"C1","surface":"cli","invocation":"omo-agent-toolkit ulw-loop checkpoint --quality-gate-json sample-quality-gate.json --json","verdict":"passed","artifactRefs":["artifact-cli-pass"]},{"id":"surface-data-pass","criterionRef":"C2","surface":"data","invocation":"diff -u before-ledger.json after-ledger.json","verdict":"passed","artifactRefs":["artifact-data-diff"]}],"adversarialCases":[{"id":"adv-malformed-input","criterionRef":"C3","scenario":"malformed gate input omits manual QA evidence","expectedBehavior":"validator rejects ULW_LOOP_QUALITY_GATE_INVALID","verdict":"passed","artifactRefs":["artifact-cli-reject"]}],"artifactRefs":[{"id":"artifact-cli-pass","kind":"cli-transcript","description":"CLI pass artifact.","path":"test/fixtures/artifacts/cli-pass.txt"},{"id":"artifact-cli-reject","kind":"log","description":"Reject log artifact.","path":"test/fixtures/artifacts/rejection.txt"},{"id":"artifact-data-diff","kind":"data-diff","description":"Data diff artifact.","path":"test/fixtures/artifacts/data-diff.txt"}]},
-  "gateReview":{"by":"lazycodex-gate-reviewer","recommendation":"APPROVE","reportPath":"test/fixtures/artifacts/gate-review.md","evidence":"Gate review passed.","blockers":[]},
+  "gateReview":{"by":"lazycodex-gate-reviewer","recommendation":"APPROVE","reportPath":"test/fixtures/artifacts/gate-review.md","evidence":"Gate review passed.","blockers":[],"notes":[]},
   "iteration":{"fullRerun":true,"status":"passed","rerunCommands":["bunx vitest run packages/omo-codex/plugin/components/ulw-loop/test/quality-gate-doc.test.ts"],"evidence":"Focused rerun passed."},
   "criteriaCoverage":{"totalCriteria":3,"passCount":3,"originalIntent":"User wanted artifact-backed completion.","desiredOutcome":"Behavior ships with review and QA evidence.","userOutcomeReview":"Result matches brief and goals.","adversarialClassesCovered":["malformed_input","stale_state"]}
 }

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

@@ -0,0 +1,52 @@
+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 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 async function validateCheckpointCodexGoal(input: {
+	readonly repoRoot: string;
+	readonly plan: UlwLoopPlan;
+	readonly goal: UlwLoopItem;
+	readonly raw: string | undefined;
+	readonly evidence: string;
+	readonly scope?: UlwLoopScope;
+}): Promise<CheckpointCodexGoalValidation> {
+	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: UlwLoopError, gateError: UlwLoopError): UlwLoopError {
+	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/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,15 +33,16 @@ 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");
-	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: CheckpointUlwLoopArgs & { readonly advance: boolean } = {
 		goalId,

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

@@ -1,100 +1,7 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { UlwLoopError } from "./types.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";
-
-function normalizeObjective(value: string): string {
-	return value.replace(/\s+/g, " ").trim();
-}
-
-function textMentionsUlwLoopPlanArtifact(value: string | undefined): boolean {
-	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: string | undefined, goalId: string): boolean {
-	return (value ?? "").toLowerCase().includes(goalId.toLowerCase());
-}
-
-function textHasCompletionValidationEvidence(value: string | undefined): boolean {
-	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: string,
-	snapshotObjective: string,
-	scope?: UlwLoopScope,
-): Promise<boolean> {
-	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: string,
-	plan: UlwLoopPlan,
-	goal: UlwLoopItem,
-	snapshotObjective: string,
-	evidence: string,
-	scope?: UlwLoopScope,
-): Promise<boolean> {
-	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: string,
-	plan: UlwLoopPlan,
-	goal: UlwLoopItem,
-	snapshotObjective: string,
-	evidence: string,
-	scope?: UlwLoopScope,
-): Promise<boolean> {
-	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: UlwLoopItem): string {
-	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: UlwLoopItem, final: boolean): string {
-	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)}`;
+export function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError {
+	return new UlwLoopError(`${codexError.message}\n${gateError.message}`, "ULW_LOOP_QUALITY_GATE_INVALID", {
+		details: { ...(codexError.details ?? {}), ...(gateError.details ?? {}) },
+	});
 }