lazycodex-ai 5.0.0-beta.9 → 5.0.0

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) {

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

@@ -1,8 +1,10 @@
 import { checkpoint } from "./checkpoint-continuation.js";
 import { hasFlag, readValue } from "./cli-arg-parser.js";
-import { printJsonError, ULW_LOOP_HELP } from "./cli-output.js";
+import { printJsonError, subcommandHelp, ULW_LOOP_HELP } from "./cli-output.js";
 import { addGoal, captureEvidence, completeGoals, createGoals, criteria, reviewBlockers, status, steer, } from "./cli-subcommands.js";
 import { resolveUlwLoopSessionIdFromEnv } from "./paths.js";
+import { listUlwLoopSessionIds } from "./plan-io.js";
+import { sessionIdRequiredMessage, sessionScopeRequiredMessage } from "./plan-missing-recovery.js";
 import { UlwLoopError } from "./types.js";
 export const ULW_LOOP_SUBCOMMANDS = [
     "help",
@@ -26,7 +28,6 @@ export async function ulwLoopCommand(argv) {
     const repoRoot = process.cwd();
     const json = hasFlag(rest, "--json");
     try {
-        const scope = commandScope(rest);
         if (!isUlwLoopSubcommand(command)) {
             if (json) {
                 printJsonError(new UlwLoopError(`Unknown ulw-loop subcommand: ${command}.`, "ULW_LOOP_SUBCOMMAND_UNKNOWN", {
@@ -37,10 +38,16 @@ export async function ulwLoopCommand(argv) {
             process.stdout.write(`${ULW_LOOP_HELP}\n`);
             return 1;
         }
+        if (command !== "help" && (hasFlag(rest, "--help") || hasFlag(rest, "-h"))) {
+            process.stdout.write(`${subcommandHelp(command)}\n`);
+            return 0;
+        }
+        if (command === "help") {
+            process.stdout.write(`${ULW_LOOP_HELP}\n`);
+            return 0;
+        }
+        const scope = commandScope(repoRoot, rest);
         switch (command) {
-            case "help":
-                process.stdout.write(`${ULW_LOOP_HELP}\n`);
-                return 0;
             case "create-goals":
                 return await createGoals(repoRoot, rest, json, scope);
             case "status":
@@ -84,16 +91,22 @@ const SESSION_ID_FLAG = "--session-id";
 function sessionIdFlagPresent(argv) {
     return hasFlag(argv, SESSION_ID_FLAG) || argv.some((arg) => arg.startsWith(`${SESSION_ID_FLAG}=`));
 }
-function commandScope(argv) {
+// Every state subcommand runs against exactly one session directory. Without a flag or
+// a session env there is no owner to resolve, so the command refuses instead of
+// falling back to the repo-global root that every session in the cwd would share.
+function commandScope(repoRoot, argv) {
     if (sessionIdFlagPresent(argv)) {
         const sessionId = readValue(argv, SESSION_ID_FLAG)?.trim();
         if (!sessionId) {
-            throw new UlwLoopError(`${SESSION_ID_FLAG} requires a non-empty value.`, "ULW_LOOP_SESSION_ID_REQUIRED", {
+            throw new UlwLoopError(sessionIdRequiredMessage(SESSION_ID_FLAG), "ULW_LOOP_SESSION_ID_REQUIRED", {
                 details: { flag: SESSION_ID_FLAG },
             });
         }
         return { sessionId };
     }
     const sessionId = resolveUlwLoopSessionIdFromEnv();
-    return sessionId === null ? undefined : { sessionId };
+    if (sessionId !== null)
+        return { sessionId };
+    const existingSessionIds = listUlwLoopSessionIds(repoRoot);
+    throw new UlwLoopError(sessionScopeRequiredMessage(SESSION_ID_FLAG, existingSessionIds), "ULW_LOOP_SESSION_SCOPE_REQUIRED", { details: { flag: SESSION_ID_FLAG, existingSessionIds } });
 }

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

@@ -1,5 +1,6 @@
 import type { UlwLoopCodexGoalMode, UlwLoopPlan } from "./types.js";
-export declare const ULW_LOOP_HELP = "Usage:\n  omo-agent-toolkit ulw-loop create-goals --brief \"...\" [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]\n  omo-agent-toolkit ulw-loop status [--json]\n  omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]\n  omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]\n  omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence \"...\" [--notes \"...\"] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence \"...\" --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]\n  omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence \"...\" --rationale \"...\" [--proposals-json <json-or-path>] [--json]\n  omo-agent-toolkit ulw-loop add-goal --title \"...\" --objective \"...\" [--json]\n  omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title \"...\" --objective \"...\" --evidence \"...\" --codex-goal-json <...> [--json]\n\nAll subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.";
+export declare const ULW_LOOP_HELP = "Usage:\n  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)\n  omo-agent-toolkit help | --help | -h                          (this message)\n  omo-agent-toolkit ulw-loop help\n  omo-agent-toolkit ulw-loop create-goals --brief \"...\" [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]\n  omo-agent-toolkit ulw-loop status [--json]\n  omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]\n  omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]\n  omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence \"...\" [--notes \"...\"] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --print-template [--goal-id <id>] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence \"...\" --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]\n  omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence \"...\" --rationale \"...\" [--proposals-json <json-or-path>] [--json]\n  omo-agent-toolkit ulw-loop add-goal --title \"...\" --objective \"...\" [--json]\n  omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title \"...\" --objective \"...\" --evidence \"...\" --codex-goal-json <...> [--json]\n\nEvery state subcommand needs a session scope: [--session-id <id>] or the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID); state lives under .omo/ulw-loop/<id>/ and the unscoped root is never used implicitly. status --json exposes the currentAttemptDir; put all quality-gate artifacts under it.\nEvery subcommand accepts --help | -h to print its own usage line.";
+export declare function subcommandHelp(subcommand: string): string;
 export declare function printJson(value: unknown): void;
 export declare function printJsonError(error: unknown): void;
 export declare function printStatus(plan: UlwLoopPlan): void;

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

@@ -1,16 +1,27 @@
 import { UlwLoopError } from "./types.js";
 export const ULW_LOOP_HELP = `Usage:
+  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
+  omo-agent-toolkit help | --help | -h                          (this message)
+  omo-agent-toolkit ulw-loop help
   omo-agent-toolkit ulw-loop create-goals --brief "..." [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]
   omo-agent-toolkit ulw-loop status [--json]
   omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]
   omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]
   omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence "..." [--notes "..."] [--json]
+  omo-agent-toolkit ulw-loop checkpoint --print-template [--goal-id <id>] [--json]
   omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence "..." --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]
   omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence "..." --rationale "..." [--proposals-json <json-or-path>] [--json]
   omo-agent-toolkit ulw-loop add-goal --title "..." --objective "..." [--json]
   omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
 
-All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.`;
+Every state subcommand needs a session scope: [--session-id <id>] or the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID); state lives under .omo/ulw-loop/<id>/ and the unscoped root is never used implicitly. status --json exposes the currentAttemptDir; put all quality-gate artifacts under it.
+Every subcommand accepts --help | -h to print its own usage line.`;
+export function subcommandHelp(subcommand) {
+    const lines = ULW_LOOP_HELP.split("\n").filter((line) => line.trimStart().startsWith(`omo-agent-toolkit ulw-loop ${subcommand}`));
+    if (lines.length === 0)
+        return ULW_LOOP_HELP;
+    return ["Usage:", ...lines].join("\n");
+}
 export function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }

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

@@ -1,4 +1,4 @@
-import { type UlwLoopScope } from "./paths.js";
+import type { UlwLoopScope } from "./paths.js";
 export declare function createGoals(repoRoot: string, argv: readonly string[], json: boolean, scope?: UlwLoopScope): Promise<number>;
 export declare function status(repoRoot: string, json: boolean, scope?: UlwLoopScope): Promise<number>;
 export declare function completeGoals(repoRoot: string, argv: readonly string[], json: boolean, scope?: UlwLoopScope): Promise<number>;