lazycodex-ai 5.0.0-beta.8 → 5.0.0-beta.80

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-high" : "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-high","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-high, category:deep-low, 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>;

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

@@ -2,22 +2,21 @@
 import { existsSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { buildTaskScopedAggregateReconciliationHint, canReconcileActiveFinalTaskScopedAggregateSnapshot, canReconcileCompletedTaskScopedAggregateSnapshot, } from "./checkpoint-reconciliation.js";
-import { formatCodexGoalReconciliation, readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot, } from "./codex-goal-snapshot.js";
+import { combineCheckpointValidationErrors, validateCheckpointCodexGoal, } from "./checkpoint-codex-validation.js";
+import { acknowledgeDriverObjective } from "./driver-objective-ack.js";
 import { requireAllCriteriaPass, requireAllPlanCriteriaPass, requireEssentialCriteriaPass } from "./evidence.js";
-import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate, } from "./goal-status.js";
+import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir } from "./paths.js";
-import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { commit } from "./plan-commit.js";
+import { readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
 import { classifyExternalAuthorizationBlocker, clearGoalBlockerFields, sameBlockerOccurrences, validateQualityGate, } from "./quality-gate.js";
+import { resolveToolkitSurface } from "./surface.js";
 import { iso, UlwLoopError } from "./types.js";
 import { batchClosedBy, requireAllValidationBatchesClosed, requireBatchFinalReady, requireBatchGate } from "./validation-batch.js";
 const QUALITY_GATE_FS = { existsSync, statSync };
 function ulwLoopFail(message, code) {
     throw new UlwLoopError(message, code);
 }
-function normalizeObjective(value) {
-    return value.replace(/\s+/g, " ").trim();
-}
 function nonEmptyEvidence(value) {
     const trimmed = value.trim();
     return trimmed || ulwLoopFail("Evidence must be a non-empty string.", "ulw_loop_evidence_required");
@@ -82,13 +81,15 @@ function ledgerKind(status, goal, aggregateCompletion) {
     return status === "blocked" ? "goal_blocked" : "goal_failed";
 }
 function buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion) {
-    const watch = qualityGate?.codeReview.codeQualityStatus === "WATCH";
+    const watch = qualityGate?.surface === "lazycodex" && qualityGate.codeReview?.codeQualityStatus === "WATCH";
     const entry = {
         at: now,
         kind: ledgerKind(args.status, goal, aggregateCompletion),
         goalId: goal.id,
         status: goal.status,
-        evidence: watch ? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview.evidence}` : args.evidence,
+        evidence: watch && qualityGate.surface === "lazycodex"
+            ? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview?.evidence ?? ""}`
+            : args.evidence,
     };
     if (codexGoal !== undefined)
         entry.codexGoal = codexGoal;
@@ -102,7 +103,7 @@ function buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletio
         entry.requiredExternalDecision = goal.requiredExternalDecision;
     return entry;
 }
-export async function checkpointUlwLoop(repoRoot, args, scope) {
+export async function checkpointUlwLoop(repoRoot, args, scope, dependencies) {
     return withUlwLoopMutationLock(repoRoot, scope, async () => {
         const plan = await readUlwLoopPlan(repoRoot, scope);
         const goal = findGoal(plan, args.goalId);
@@ -111,6 +112,8 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
         let aggregateCompletion;
         let qualityGate;
         let codexGoal;
+        let nextActions = [];
+        let warnings = [];
         if (args.status === "complete") {
             const aggregate = codexGoalMode(plan) === "aggregate";
             const final = isFinalRunCompletionCandidate(plan, goal);
@@ -124,29 +127,25 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
                 requireEssentialCriteriaPass(goal);
             else
                 requireAllCriteriaPass(goal);
-            const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
-            const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
-                expectedObjective: expectedCodexObjective(plan, goal),
-                ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}),
-                allowedStatuses: aggregate ? (final ? ["complete"] : ["active"]) : ["complete"],
-                requireSnapshot: true,
-                requireComplete: !aggregate || final,
-            });
-            codexGoal = reconciliation.snapshot.raw;
-            if (!reconciliation.ok) {
-                const objective = snapshot?.objective;
-                const mismatchedTaskObjective = snapshot?.available === true &&
-                    objective !== undefined &&
-                    normalizeObjective(objective) !== normalizeObjective(expectedCodexObjective(plan, goal));
-                const completedTaskScoped = mismatchedTaskObjective &&
-                    snapshot.status === "complete" &&
-                    (await canReconcileCompletedTaskScopedAggregateSnapshot(repoRoot, plan, goal, objective, evidence, scope));
-                const activeFinalTaskScoped = mismatchedTaskObjective &&
-                    snapshot.status === "active" &&
-                    (await canReconcileActiveFinalTaskScopedAggregateSnapshot(repoRoot, plan, goal, objective, evidence, scope));
-                const taskScoped = completedTaskScoped || activeFinalTaskScoped;
-                if (!taskScoped)
-                    throw new UlwLoopError(`${formatCodexGoalReconciliation(reconciliation)}${aggregate && snapshot?.status === "complete" && objective !== undefined ? buildTaskScopedAggregateReconciliationHint(goal, final) : ""}`, "ulw_loop_codex_snapshot_mismatch");
+            let codexValidationError;
+            try {
+                const validation = await validateCheckpointCodexGoal({
+                    repoRoot,
+                    plan,
+                    goal,
+                    raw: args.codexGoalJson,
+                    evidence,
+                    ...(scope === undefined ? {} : { scope }),
+                });
+                codexGoal = validation.raw;
+                nextActions = validation.nextActions;
+                warnings = validation.warnings;
+                acknowledgeDriverObjective(plan, validation.unacknowledgedObjective);
+            }
+            catch (error) {
+                if (!(error instanceof UlwLoopError))
+                    throw error;
+                codexValidationError = error;
             }
             if (closesBatch)
                 requireBatchFinalReady(plan, goal);
@@ -155,15 +154,25 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
             if (final)
                 aggregateCompletion = makeAggregateCompletion(now, evidence, codexGoal);
             if (final || aggregateCompletion !== undefined || closesBatch) {
-                qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
-                    repoRoot,
-                    fs: QUALITY_GATE_FS,
-                    ...(plan.evidenceLayoutVersion === 2
-                        ? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
-                        : {}),
-                });
-                requireBatchGate(plan, goal, qualityGate);
+                try {
+                    qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
+                        repoRoot,
+                        fs: QUALITY_GATE_FS,
+                        reviewerSurface: dependencies?.surface ?? resolveToolkitSurface(),
+                        ...(plan.evidenceLayoutVersion === 2
+                            ? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
+                            : {}),
+                    });
+                    requireBatchGate(plan, goal, qualityGate);
+                }
+                catch (error) {
+                    if (!(error instanceof UlwLoopError) || codexValidationError === undefined)
+                        throw error;
+                    throw combineCheckpointValidationErrors(codexValidationError, error);
+                }
             }
+            if (codexValidationError !== undefined)
+                throw codexValidationError;
             goal.status = "complete";
             goal.completedAt = now;
             goal.evidence = evidence;
@@ -178,15 +187,17 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
         goal.updatedAt = now;
         if (aggregateCompletion !== undefined)
             plan.aggregateCompletion = aggregateCompletion;
+        if (aggregateCompletion !== undefined)
+            nextActions = [...nextActions, 'aggregate complete — now update_goal({status:"complete"})'];
         plan.updatedAt = now;
-        await writePlan(repoRoot, plan, scope);
         const ledgerEntry = buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion);
-        await appendLedger(repoRoot, ledgerEntry, scope);
+        const entries = [ledgerEntry];
         const closedBatch = args.status === "complete" ? batchClosedBy(plan, goal.id) : undefined;
         if (closedBatch !== undefined)
-            await appendLedger(repoRoot, { at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId }, scope);
+            entries.push({ at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId });
+        await commit(repoRoot, scope, { plan, entries });
         return aggregateCompletion === undefined
-            ? { plan, goal, ledgerEntry }
-            : { plan, goal, ledgerEntry, aggregateCompletion };
+            ? { plan, goal, ledgerEntry, nextActions, warnings }
+            : { plan, goal, ledgerEntry, aggregateCompletion, nextActions, warnings };
     });
 }

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli-arg-parser.js

@@ -66,14 +66,14 @@ export async function readJsonInput(value) {
 export async function parseCodexGoalJson(value) {
     if (value === undefined)
         return undefined;
-    const raw = looksLikeJson(value) ? value : await readFile(value, "utf8");
     try {
+        const raw = looksLikeJson(value) ? value : await readFile(value, "utf8");
         JSON.parse(raw);
         return raw;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "unknown error";
-        throw new UlwLoopError(`Invalid --codex-goal-json: ${message}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
+        throw new UlwLoopError(`Invalid --codex-goal-json: ${looksLikeJson(value) ? message : "neither valid JSON nor a readable path"}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
     }
 }
 function required(argv, flag, code) {