lazycodex-ai 5.0.0-beta.4 → 5.0.0-beta.40

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

@@ -0,0 +1,45 @@
+import { canReconcileActiveFinalTaskScopedAggregateSnapshot, canReconcileCompletedTaskScopedAggregateSnapshot, codexSnapshotMismatchError, } from "./checkpoint-reconciliation.js";
+import { readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot } from "./codex-goal-snapshot.js";
+import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate, } from "./goal-status.js";
+import { UlwLoopError } from "./types.js";
+function normalizeObjective(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+export async function validateCheckpointCodexGoal(input) {
+    const aggregate = codexGoalMode(input.plan) === "aggregate";
+    const final = isFinalRunCompletionCandidate(input.plan, input.goal);
+    const snapshot = await readCodexGoalSnapshotInput(input.raw, input.repoRoot);
+    const expectedObjective = expectedCodexObjective(input.plan, input.goal);
+    const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
+        expectedObjective,
+        ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(input.plan) } : {}),
+        allowedStatuses: aggregate ? (final ? ["complete"] : ["active"]) : ["complete"],
+        requireSnapshot: true,
+        requireComplete: !aggregate || final,
+    });
+    if (reconciliation.ok)
+        return reconciliation.snapshot.raw;
+    const objective = snapshot?.objective;
+    const mismatchedTaskObjective = snapshot?.available === true &&
+        objective !== undefined &&
+        normalizeObjective(objective) !== normalizeObjective(expectedObjective);
+    const completedTaskScoped = mismatchedTaskObjective &&
+        snapshot.status === "complete" &&
+        (await canReconcileCompletedTaskScopedAggregateSnapshot(input.repoRoot, input.plan, input.goal, objective, input.evidence, input.scope));
+    const activeFinalTaskScoped = mismatchedTaskObjective &&
+        snapshot.status === "active" &&
+        (await canReconcileActiveFinalTaskScopedAggregateSnapshot(input.repoRoot, input.plan, input.goal, objective, input.evidence, input.scope));
+    if (completedTaskScoped || activeFinalTaskScoped)
+        return reconciliation.snapshot.raw;
+    throw codexSnapshotMismatchError({
+        reconciliation,
+        snapshot,
+        expectedObjective,
+        taskScopedHint: { goal: input.goal, aggregate, final },
+    });
+}
+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,6 +16,14 @@ 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");

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

@@ -1,5 +1,20 @@
+import type { CodexGoalReconciliation, CodexGoalSnapshot } from "./codex-goal-snapshot.js";
 import { type UlwLoopScope } from "./paths.js";
 import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+import { UlwLoopError } from "./types.js";
+export interface CodexSnapshotMismatchInput {
+    readonly reconciliation: CodexGoalReconciliation;
+    readonly snapshot: CodexGoalSnapshot | null | undefined;
+    readonly expectedObjective: string;
+    /** Only the checkpoint path can fall back to task-scoped aggregate reconciliation, so only it asks for that hint. */
+    readonly taskScopedHint?: {
+        readonly goal: UlwLoopItem;
+        readonly aggregate: boolean;
+        readonly final: boolean;
+    };
+}
+export declare function combineCheckpointValidationErrors(codexError: UlwLoopError, gateError: UlwLoopError): UlwLoopError;
+export declare function codexSnapshotMismatchError(input: CodexSnapshotMismatchInput): UlwLoopError;
 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;

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

@@ -1,8 +1,22 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { codexGoalMismatchRecovery, formatCodexGoalReconciliation } from "./codex-goal-snapshot.js";
 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";
+import { ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, 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 ?? {}) },
+    });
+}
+export function codexSnapshotMismatchError(input) {
+    const { reconciliation, snapshot, taskScopedHint } = input;
+    const hint = taskScopedHint?.aggregate === true && snapshot?.status === "complete" && snapshot.objective !== undefined
+        ? buildTaskScopedAggregateReconciliationHint(taskScopedHint.goal, taskScopedHint.final)
+        : "";
+    const recovery = codexGoalMismatchRecovery(input.expectedObjective, snapshot);
+    return new UlwLoopError(`${formatCodexGoalReconciliation(reconciliation)}${hint}\n${recovery.message}`, "ulw_loop_codex_snapshot_mismatch", { details: recovery.details });
+}
 function normalizeObjective(value) {
     return value.replace(/\s+/g, " ").trim();
 }

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

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

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

@@ -0,0 +1,120 @@
+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: surface === "omo-senpi" ? "main-session" : "lazycodex-qa-executor",
+        status: "passed",
+        evidence: "<replace:manual QA evidence>",
+        surfaceEvidence: [
+            {
+                id: "surface-cli",
+                criterionRef: "<replace:criterion id>",
+                surface: "cli",
+                invocation: "<replace:command>",
+                verdict: "passed",
+                artifactRefs: ["artifact-cli"],
+            },
+            {
+                id: "surface-data",
+                criterionRef: "<replace:criterion id>",
+                surface: "data",
+                invocation: "<replace:command>",
+                verdict: "passed",
+                artifactRefs: ["artifact-data"],
+            },
+        ],
+        adversarialCases: [
+            {
+                id: "<replace:adversarial case id>",
+                criterionRef: "<replace:criterion id>",
+                scenario: "<replace:scenario>",
+                expectedBehavior: "<replace:expected behavior>",
+                verdict: "not_applicable",
+                reason: "<replace:reason>",
+                artifactRefs: ["artifact-cli"],
+            },
+        ],
+        artifactRefs: artifacts,
+    };
+    const common = {
+        manualQa,
+        gateReview: {
+            by: surface === "omo-senpi" ? "category:deep" : "lazycodex-gate-reviewer",
+            recommendation: "APPROVE",
+            reportPath: artifactPath(base, "gate-review.md"),
+            evidence: "<replace:gate review evidence>",
+            blockers: [],
+            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>"],
+        },
+    };
+    if (surface === "omo-senpi")
+        return common;
+    return {
+        codeReview: {
+            by: "lazycodex-code-reviewer",
+            recommendation: "APPROVE",
+            codeQualityStatus: "CLEAR",
+            reportPath: artifactPath(base, "code-review.md"),
+            evidence: "<replace:code review evidence>",
+            blockers: [],
+        },
+        ...common,
+    };
+}
+export async function checkpointTemplate(repoRoot, scope, goalId) {
+    const plan = await readUlwLoopPlan(repoRoot, scope);
+    const targetId = goalId ?? plan.activeGoalId;
+    const active = plan.goals.find((goal) => goal.id === targetId);
+    if (goalId !== undefined && active === undefined)
+        throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
+    const hasAttempt = plan.evidenceLayoutVersion === 2 && active !== undefined;
+    const attemptDir = hasAttempt ? ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) : ".omo/evidence";
+    const guidance = [
+        "codex-goal-json requires goal.objective to equal the plan's codexObjective verbatim; do not paraphrase it.",
+        "Fill every <replace:...> value with plausible non-empty evidence and use real, non-empty artifact files.",
+        'Passing codex-goal-json example: {"goal":{"objective":"<plan codexObjective verbatim>","status":"complete"}}.',
+        'Passing quality-gate-json example requires gateReview {"by":"category:deep","recommendation":"APPROVE","evidence":"review passed","reportPath":"<attemptDir>/gate-review.md","blockers":[],"notes":[]}, manualQa.artifactRefs objects, iteration, and criteriaCoverage.',
+        ...(hasAttempt ? [] : ["This plan is evidence-layout v1; artifacts go under .omo/evidence/."]),
+    ].join(" ");
+    return {
+        qualityGateTemplate: gateTemplate(resolveToolkitSurface(), attemptDir),
+        codexGoalTemplate: {
+            goal: { objective: plan.codexObjective ?? "<replace:codex objective>", status: "complete" },
+        },
+        guidance,
+        ...(hasAttempt ? { attemptDir } : {}),
+    };
+}

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

@@ -2,22 +2,19 @@
 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 { 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 { 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 +79,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;
@@ -124,29 +123,21 @@ 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 {
+                codexGoal = await validateCheckpointCodexGoal({
+                    repoRoot,
+                    plan,
+                    goal,
+                    raw: args.codexGoalJson,
+                    evidence,
+                    ...(scope === undefined ? {} : { scope }),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof UlwLoopError))
+                    throw error;
+                codexValidationError = error;
             }
             if (closesBatch)
                 requireBatchFinalReady(plan, goal);
@@ -155,15 +146,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: 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;

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

@@ -1,8 +1,9 @@
 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 { sessionIdRequiredMessage } from "./plan-missing-recovery.js";
 import { UlwLoopError } from "./types.js";
 export const ULW_LOOP_SUBCOMMANDS = [
     "help",
@@ -37,6 +38,10 @@ 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;
+        }
         switch (command) {
             case "help":
                 process.stdout.write(`${ULW_LOOP_HELP}\n`);
@@ -88,7 +93,7 @@ function commandScope(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 },
             });
         }

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\nAll subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.\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.`;
+All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.
+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.js

@@ -9,6 +9,7 @@ import { ulwLoopAttemptEvidenceDir } from "./paths.js";
 import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "./plan-crud.js";
 import { readUlwLoopPlan } from "./plan-io.js";
 import { recordFinalReviewBlockers } from "./review-blockers.js";
+import { statusNextActions } from "./status-next-actions.js";
 import { steerUlwLoop } from "./steering.js";
 import { steerUlwLoopBatch } from "./steering-batch.js";
 import { UlwLoopError } from "./types.js";
@@ -47,6 +48,7 @@ export async function status(repoRoot, json, scope) {
             plan,
             summary: summarizeUlwLoopPlan(plan),
             ...(currentAttemptDir === undefined ? {} : { currentAttemptDir }),
+            nextActions: statusNextActions(plan),
         });
     }
     else