@cleocode/core 2026.5.131 → 2026.5.132

package/dist/go/driver.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `cleo go` autopilot driver — the thin orchestration sequencer.
+ *
+ * This is the canonical entry point for `cleo go` (SG-AUTOPILOT / T11492).
+ * It is PURE GLUE: it sequences existing core engines without adding new
+ * orchestration math.
+ *
+ * ## Pipeline (AC1)
+ *
+ * ```
+ * briefing (optional context anchor)
+ *   → sagaNext() — pick highest-priority non-terminal saga
+ *   → orchestrateReady(sagaId) — fetch readyFrontier
+ *   → branch on pipelineStage of the active epic:
+ *       AC-only (no children, research stage)
+ *         → { action: 'needsDecomposition', sagaId, epicId }
+ *       research | specification | decomposition
+ *         → { action: 'lifecycleHop', sagaId, epicId, currentStage }
+ *       implementation | validation | testing | release | contribution
+ *         → fan-out startIvtr over readyFrontier tasks
+ *         → { action: 'ivtrFanOut', sagaId, epicId, tasks: string[] }
+ *   → return ONE LAFS-compatible EngineResult envelope
+ * ```
+ *
+ * ## Design constraints
+ *
+ * - AC2: ONE LAFS envelope per call — all branching produces a single return.
+ * - AC3: empty ready-set + zero children → `needsDecomposition` (typed, not silent []).
+ * - No new orchestration math — only sequences ops from `sagas`, `orchestrate`,
+ *   and `lifecycle` modules.
+ * - CORE-FIRST: all logic here in `packages/core/src/go/`; CLI is a thin dispatch.
+ *
+ * @module @cleocode/core/go
+ *
+ * @task T11494 — E2-CLEO-GO
+ * @saga T11492 — SG-AUTOPILOT
+ */
+import type { TaskViewPipelineStage } from '@cleocode/contracts';
+import { type EngineResult } from '../engine-result.js';
+/**
+ * Input parameters for {@link cleoGo}.
+ *
+ * @task T11494
+ */
+export interface CleoGoParams {
+    /**
+     * Optional saga ID to scope the autopilot run. When omitted, `sagaNext`
+     * auto-selects the highest-priority non-terminal Saga in canonical order.
+     */
+    sagaId?: string;
+    /**
+     * When true, suppress any interactive output suitable for daemon / unattended
+     * runs. The result shape is identical; only side-channel logging is affected.
+     */
+    headless?: boolean;
+    /** Override project root (useful in tests). */
+    projectRoot?: string;
+}
+/**
+ * Discriminated union of the four action outcomes `cleoGo` can produce.
+ *
+ * Consumers pattern-match on `action` to route further processing.
+ *
+ * @task T11494
+ */
+export type CleoGoAction = {
+    /** No children + research stage — the epic needs decomposition before IVTR. */
+    action: 'needsDecomposition';
+    sagaId: string;
+    /** The AC-only epic that needs task children added. */
+    epicId: string;
+    /** Current pipelineStage (always `'research'` for AC-only epics). */
+    currentStage: TaskViewPipelineStage;
+} | {
+    /** Pre-implementation stage — lifecycle must hop before IVTR is valid. */
+    action: 'lifecycleHop';
+    sagaId: string;
+    epicId: string;
+    currentStage: TaskViewPipelineStage;
+    /** All ready-frontier task IDs (may be empty while lifecycle hops). */
+    readyFrontier: string[];
+} | {
+    /** Fan-out: IVTR started for each task on the ready frontier. */
+    action: 'ivtrFanOut';
+    sagaId: string;
+    epicId: string;
+    currentStage: TaskViewPipelineStage;
+    /** Task IDs for which IVTR was initiated (non-empty). */
+    tasks: string[];
+} | {
+    /** No non-terminal sagas remain — the workgraph is complete. */
+    action: 'complete';
+};
+/**
+ * Result payload for {@link cleoGo}.
+ *
+ * @task T11494
+ * @task T11496 E4-GOAL-LOOP
+ */
+export interface CleoGoResult {
+    /** The action taken by the driver in this turn. */
+    outcome: CleoGoAction;
+    /**
+     * Structured diagnostics for display / logging. Always present; may be empty.
+     */
+    diagnostics: string[];
+    /**
+     * The id of the goal that was armed (or reused) for the Stop-hook loop.
+     *
+     * `null` when no saga was selected (workgraph `complete` action) — there is
+     * nothing to arm when the workgraph is already done.
+     *
+     * @task T11496
+     */
+    armedGoalId: string | null;
+}
+/**
+ * Run one turn of the `cleo go` autopilot pipeline.
+ *
+ * Returns a single LAFS-compatible {@link EngineResult} wrapping a
+ * {@link CleoGoResult}. Each call is stateless (side effects — IVTR writes,
+ * lifecycle progression — happen inside the called engines); the driver itself
+ * carries no mutable state.
+ *
+ * @param params - Input parameters controlling the saga scope and mode.
+ * @returns EngineResult with {@link CleoGoResult}.
+ *
+ * @task T11494
+ * @saga T11492
+ */
+export declare function cleoGo(params?: CleoGoParams): Promise<EngineResult<CleoGoResult>>;
+//# sourceMappingURL=driver.d.ts.map

package/dist/go/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/go/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,KAAK,YAAY,EAA8B,MAAM,qBAAqB,CAAC;AAWpF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,+EAA+E;IAC/E,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,YAAY,EAAE,qBAAqB,CAAC;CACrC,GACD;IACE,0EAA0E;IAC1E,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,qBAAqB,CAAC;IACpC,uEAAuE;IACvE,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,GACD;IACE,iEAAiE;IACjE,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,qBAAqB,CAAC;IACpC,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,GACD;IACE,gEAAgE;IAChE,MAAM,EAAE,UAAU,CAAC;CACpB,CAAC;AAEN;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,OAAO,EAAE,YAAY,CAAC;IACtB;;OAEG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,MAAM,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CA0I3F"}

package/dist/go/driver.js

@@ -0,0 +1,191 @@
+/**
+ * `cleo go` autopilot driver — the thin orchestration sequencer.
+ *
+ * This is the canonical entry point for `cleo go` (SG-AUTOPILOT / T11492).
+ * It is PURE GLUE: it sequences existing core engines without adding new
+ * orchestration math.
+ *
+ * ## Pipeline (AC1)
+ *
+ * ```
+ * briefing (optional context anchor)
+ *   → sagaNext() — pick highest-priority non-terminal saga
+ *   → orchestrateReady(sagaId) — fetch readyFrontier
+ *   → branch on pipelineStage of the active epic:
+ *       AC-only (no children, research stage)
+ *         → { action: 'needsDecomposition', sagaId, epicId }
+ *       research | specification | decomposition
+ *         → { action: 'lifecycleHop', sagaId, epicId, currentStage }
+ *       implementation | validation | testing | release | contribution
+ *         → fan-out startIvtr over readyFrontier tasks
+ *         → { action: 'ivtrFanOut', sagaId, epicId, tasks: string[] }
+ *   → return ONE LAFS-compatible EngineResult envelope
+ * ```
+ *
+ * ## Design constraints
+ *
+ * - AC2: ONE LAFS envelope per call — all branching produces a single return.
+ * - AC3: empty ready-set + zero children → `needsDecomposition` (typed, not silent []).
+ * - No new orchestration math — only sequences ops from `sagas`, `orchestrate`,
+ *   and `lifecycle` modules.
+ * - CORE-FIRST: all logic here in `packages/core/src/go/`; CLI is a thin dispatch.
+ *
+ * @module @cleocode/core/go
+ *
+ * @task T11494 — E2-CLEO-GO
+ * @saga T11492 — SG-AUTOPILOT
+ */
+import { engineError, engineSuccess } from '../engine-result.js';
+import { armGoalLoop } from '../goal/arm.js';
+import { startIvtr } from '../lifecycle/ivtr-loop.js';
+import { orchestrateReady } from '../orchestrate/query-ops.js';
+import { getProjectRoot } from '../paths.js';
+import { sagaNext } from '../sagas/next.js';
+// ---------------------------------------------------------------------------
+// Pre-implementation stage set
+// ---------------------------------------------------------------------------
+/**
+ * Pipeline stages that require a lifecycle hop before spawning IVTR workers.
+ *
+ * Tasks whose parent epic is still in one of these stages are not yet
+ * implementation-ready; the driver signals `lifecycleHop` instead of fanning
+ * out IVTR.
+ */
+const PRE_IMPLEMENTATION_STAGES = new Set([
+    'research',
+    'specification',
+    'decomposition',
+]);
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Run one turn of the `cleo go` autopilot pipeline.
+ *
+ * Returns a single LAFS-compatible {@link EngineResult} wrapping a
+ * {@link CleoGoResult}. Each call is stateless (side effects — IVTR writes,
+ * lifecycle progression — happen inside the called engines); the driver itself
+ * carries no mutable state.
+ *
+ * @param params - Input parameters controlling the saga scope and mode.
+ * @returns EngineResult with {@link CleoGoResult}.
+ *
+ * @task T11494
+ * @saga T11492
+ */
+export async function cleoGo(params = {}) {
+    const root = getProjectRoot(params.projectRoot);
+    const diagnostics = [];
+    // 1. sagaNext — pick the next actionable saga (or the explicit one).
+    const nextResult = await sagaNext(root, { sagaId: params.sagaId });
+    if (!nextResult.success) {
+        return engineError(nextResult.error?.code ?? 'E_GENERAL', nextResult.error?.message ?? 'sagaNext failed');
+    }
+    const next = nextResult.data;
+    // 2. Workgraph complete guard: no active sagas.
+    if (!next.sagaId) {
+        return engineSuccess({
+            outcome: { action: 'complete' },
+            diagnostics: ['No non-terminal sagas remain — workgraph is complete.'],
+            armedGoalId: null,
+        });
+    }
+    const sagaId = next.sagaId;
+    diagnostics.push(`active saga: ${sagaId}${next.sagaTitle ? ` (${next.sagaTitle})` : ''} — ${next.completionPct ?? 0}% complete`);
+    // 2b. Arm the goal loop (AC3 of T11496): create/reuse a per-saga goal that
+    //     the Stop-hook advances each turn to self-renudge until satisfied.
+    //     Best-effort: failure is non-fatal (diagnostics only).
+    let armedGoalId = null;
+    try {
+        const armedGoal = await armGoalLoop({
+            sagaId,
+            sagaTitle: next.sagaTitle,
+            cwd: root,
+        });
+        armedGoalId = armedGoal.id;
+        diagnostics.push(`goal loop armed: ${armedGoalId}`);
+    }
+    catch (err) {
+        diagnostics.push(`goal loop arm failed (non-fatal): ${err.message}`);
+    }
+    // 3. orchestrateReady — get the ready frontier for the saga.
+    const readyResult = await orchestrateReady(sagaId, root);
+    if (!readyResult.success) {
+        return engineError(readyResult.error?.code ?? 'E_GENERAL', `orchestrateReady failed for saga ${sagaId}: ${readyResult.error?.message ?? 'unknown'}`);
+    }
+    const readyData = readyResult.data;
+    const readyTasks = readyData.readyTasks ?? [];
+    const readyFrontier = readyTasks.map((t) => t.id);
+    // 4. Identify the "active epic" — the first ready task's parent, or the first
+    //    saga member if the frontier is empty.
+    //
+    //    We need the epicId to read its pipelineStage and decide the branch action.
+    const epicId = readyTasks[0]?.parentId ?? next.memberEpics?.[0]?.id ?? sagaId;
+    const rawStage = readyTasks[0]?.pipelineStage ??
+        next.memberEpics?.[0]?.status ?? // fallback: treat member epic status as a proxy
+        'research';
+    // Normalise to a valid TaskViewPipelineStage, defaulting to 'research'.
+    const currentStage = rawStage ?? 'research';
+    // 5. AC-only detection: empty ready frontier + no descendant tasks under the
+    //    active epic signals that the epic has acceptance criteria only and needs
+    //    to be decomposed into subtasks (AC3 — fixes the silent [] dead-end).
+    const totalDescendants = next.memberEpics?.find((e) => e.id === epicId)?.descendantTaskCount ?? 0;
+    if (readyFrontier.length === 0 && totalDescendants === 0) {
+        diagnostics.push(`epic ${epicId} has no children and no ready tasks — needs decomposition`);
+        return engineSuccess({
+            outcome: {
+                action: 'needsDecomposition',
+                sagaId,
+                epicId,
+                currentStage,
+            },
+            diagnostics,
+            armedGoalId,
+        });
+    }
+    // 6. Pre-implementation stage check → lifecycle hop signal.
+    if (PRE_IMPLEMENTATION_STAGES.has(currentStage)) {
+        diagnostics.push(`epic ${epicId} is at stage '${currentStage}' — lifecycle hop required before IVTR`);
+        return engineSuccess({
+            outcome: {
+                action: 'lifecycleHop',
+                sagaId,
+                epicId,
+                currentStage,
+                readyFrontier,
+            },
+            diagnostics,
+            armedGoalId,
+        });
+    }
+    // 7. Implementation+ → fan-out IVTR over the ready frontier.
+    const ivtrStarted = [];
+    for (const taskId of readyFrontier) {
+        try {
+            await startIvtr(taskId, { cwd: root });
+            ivtrStarted.push(taskId);
+        }
+        catch (err) {
+            diagnostics.push(`IVTR start failed for ${taskId}: ${err.message}`);
+        }
+    }
+    if (ivtrStarted.length === 0 && readyFrontier.length > 0) {
+        // All IVTR starts failed — surface the errors but return gracefully.
+        diagnostics.push(`All ${readyFrontier.length} IVTR starts failed — see diagnostics`);
+    }
+    else {
+        diagnostics.push(`IVTR started for ${ivtrStarted.length} task(s): ${ivtrStarted.join(', ')}`);
+    }
+    return engineSuccess({
+        outcome: {
+            action: 'ivtrFanOut',
+            sagaId,
+            epicId,
+            currentStage,
+            tasks: ivtrStarted,
+        },
+        diagnostics,
+        armedGoalId,
+    });
+}
+//# sourceMappingURL=driver.js.map

package/dist/go/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/go/driver.ts"],"names":[],"mappings":"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"}

package/dist/go/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `cleo go` autopilot driver — public barrel.
+ *
+ * Re-exports the {@link cleoGo} orchestration sequencer and its result types.
+ * Consumed by the thin CLI handler in `packages/cleo/src/cli/commands/go.ts`.
+ *
+ * @module @cleocode/core/go
+ *
+ * @task T11494 — E2-CLEO-GO
+ * @saga T11492 — SG-AUTOPILOT
+ */
+export { type CleoGoAction, type CleoGoParams, type CleoGoResult, cleoGo, } from './driver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/go/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/go/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,MAAM,GACP,MAAM,aAAa,CAAC"}

package/dist/go/index.js

@@ -0,0 +1,13 @@
+/**
+ * `cleo go` autopilot driver — public barrel.
+ *
+ * Re-exports the {@link cleoGo} orchestration sequencer and its result types.
+ * Consumed by the thin CLI handler in `packages/cleo/src/cli/commands/go.ts`.
+ *
+ * @module @cleocode/core/go
+ *
+ * @task T11494 — E2-CLEO-GO
+ * @saga T11492 — SG-AUTOPILOT
+ */
+export { cleoGo, } from './driver.js';
+//# sourceMappingURL=index.js.map

package/dist/go/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/go/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAIL,MAAM,GACP,MAAM,aAAa,CAAC"}

package/dist/goal/advance-with-persist.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Goal advance-with-persist — load → advance → persist → continuation.
+ *
+ * This is the ORCHESTRATED entry point called by `cleo goal advance <goalId>`
+ * (CLI) and by the Claude Code Stop-hook. It wraps the PURE
+ * {@link advanceGoal} (no I/O) with the persistence and continuation steps
+ * that complete the AC loop:
+ *
+ * ```
+ * getGoalById(id)
+ *   → advanceGoal(goal, judgeGoal-closure)   [pure, no I/O]
+ *   → updateGoal(id, { status, turnsUsed, lastVerdict })
+ *   → buildContinuation(updatedGoal, verdict) [null when terminal]
+ * ```
+ *
+ * The injected `llmJudge` is only called for `fuzzy` goals — task-completion
+ * goals use the ADR-051 evidence path (pure, offline). Tests pass
+ * {@link StaticGoalJudge} to stay fully hermetic.
+ *
+ * ## Return shape
+ *
+ * The returned {@link AdvanceWithPersistResult} always carries the
+ * `advanceResult` (verdict, nextStatus, turnsRemaining), the fully-updated
+ * `goal` record (after the persistence write), and — critically — the
+ * `continuation` nudge ({@link GoalContinuation}) or `null` when the goal
+ * has reached a terminal state.  The CLI formats this as a LAFS envelope; the
+ * Stop-hook uses `continuation` to decide whether to emit a block decision.
+ *
+ * @module @cleocode/core/goal/advance-with-persist
+ *
+ * @epic T11290 EP-CLEO-GOAL-SYSTEM
+ * @task T11496 E4-GOAL-LOOP
+ * @saga T11283 SG-COGNITIVE-SUBSTRATE
+ */
+import type { GoalAdvanceResult, GoalContinuation, GoalJudge, GoalRecord } from '@cleocode/contracts';
+/**
+ * The combined result of one orchestrated advance turn.
+ *
+ * @task T11496
+ */
+export interface AdvanceWithPersistResult {
+    /**
+     * The raw advance result from the pure `advanceGoal` engine (verdict,
+     * nextStatus, turnsRemaining). This is what is persisted.
+     */
+    readonly advanceResult: GoalAdvanceResult;
+    /**
+     * The goal record AFTER the persistence write. Status and verdict are
+     * already updated — callers render this, not the pre-advance snapshot.
+     */
+    readonly goal: GoalRecord;
+    /**
+     * The continuation nudge, or `null` when the goal is terminal.
+     *
+     * Non-null for `active` and `paused` goals — the Stop-hook emits this as a
+     * `{ decision: 'block', reason: continuation.content }` response to keep
+     * Claude working. Null for `satisfied`, `abandoned`, `impossible`.
+     */
+    readonly continuation: GoalContinuation | null;
+}
+/**
+ * Advance a goal one turn and persist the result.
+ *
+ * Orchestrates the full load → advance (pure) → persist → continuation
+ * pipeline in one call. Returns `null` when the goal id is not found.
+ *
+ * @param goalId - The goal to advance (idempotency key / primary key).
+ * @param options - Optional overrides.
+ * @param options.llmJudge - LLM judge for fuzzy goals (default: offline stub).
+ * @param options.cwd - Project root override.
+ * @returns The combined result, or `null` when the goal is absent.
+ *
+ * @task T11496
+ * @adr ADR-051
+ */
+export declare function advanceGoalWithPersist(goalId: string, options?: {
+    readonly llmJudge?: GoalJudge;
+    readonly cwd?: string;
+}): Promise<AdvanceWithPersistResult | null>;
+//# sourceMappingURL=advance-with-persist.d.ts.map

package/dist/goal/advance-with-persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance-with-persist.d.ts","sourceRoot":"","sources":["../../src/goal/advance-with-persist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,UAAU,EACX,MAAM,qBAAqB,CAAC;AA8B7B;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAChD;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CAClB,GACL,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CA4C1C"}

package/dist/goal/advance-with-persist.js

@@ -0,0 +1,105 @@
+/**
+ * Goal advance-with-persist — load → advance → persist → continuation.
+ *
+ * This is the ORCHESTRATED entry point called by `cleo goal advance <goalId>`
+ * (CLI) and by the Claude Code Stop-hook. It wraps the PURE
+ * {@link advanceGoal} (no I/O) with the persistence and continuation steps
+ * that complete the AC loop:
+ *
+ * ```
+ * getGoalById(id)
+ *   → advanceGoal(goal, judgeGoal-closure)   [pure, no I/O]
+ *   → updateGoal(id, { status, turnsUsed, lastVerdict })
+ *   → buildContinuation(updatedGoal, verdict) [null when terminal]
+ * ```
+ *
+ * The injected `llmJudge` is only called for `fuzzy` goals — task-completion
+ * goals use the ADR-051 evidence path (pure, offline). Tests pass
+ * {@link StaticGoalJudge} to stay fully hermetic.
+ *
+ * ## Return shape
+ *
+ * The returned {@link AdvanceWithPersistResult} always carries the
+ * `advanceResult` (verdict, nextStatus, turnsRemaining), the fully-updated
+ * `goal` record (after the persistence write), and — critically — the
+ * `continuation` nudge ({@link GoalContinuation}) or `null` when the goal
+ * has reached a terminal state.  The CLI formats this as a LAFS envelope; the
+ * Stop-hook uses `continuation` to decide whether to emit a block decision.
+ *
+ * @module @cleocode/core/goal/advance-with-persist
+ *
+ * @epic T11290 EP-CLEO-GOAL-SYSTEM
+ * @task T11496 E4-GOAL-LOOP
+ * @saga T11283 SG-COGNITIVE-SUBSTRATE
+ */
+import { buildContinuation } from './continuation.js';
+import { judgeGoal, StaticGoalJudge } from './judge.js';
+import { advanceGoal } from './loop.js';
+import { getGoalById, updateGoal } from './store.js';
+// ---------------------------------------------------------------------------
+// Default offline-safe LLM judge
+// ---------------------------------------------------------------------------
+/**
+ * The fallback judge used when no real LLM judge is provided.
+ *
+ * Always returns a non-satisfied, non-impossible verdict so the loop
+ * continues (safe default). In production the caller should inject a
+ * real LLM-backed {@link GoalJudge} for fuzzy goals.
+ *
+ * @internal
+ */
+const DEFAULT_FALLBACK_JUDGE = new StaticGoalJudge({
+    ok: false,
+    impossible: false,
+    reason: 'No LLM judge provided — fuzzy goal keeps running until explicitly resolved or budget exhausted.',
+});
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Advance a goal one turn and persist the result.
+ *
+ * Orchestrates the full load → advance (pure) → persist → continuation
+ * pipeline in one call. Returns `null` when the goal id is not found.
+ *
+ * @param goalId - The goal to advance (idempotency key / primary key).
+ * @param options - Optional overrides.
+ * @param options.llmJudge - LLM judge for fuzzy goals (default: offline stub).
+ * @param options.cwd - Project root override.
+ * @returns The combined result, or `null` when the goal is absent.
+ *
+ * @task T11496
+ * @adr ADR-051
+ */
+export async function advanceGoalWithPersist(goalId, options = {}) {
+    const { llmJudge = DEFAULT_FALLBACK_JUDGE, cwd } = options;
+    // 1. Load the current goal record.
+    const goal = await getGoalById(goalId, cwd);
+    if (!goal) {
+        return null;
+    }
+    // 2. Build the injected judge closure over `judgeGoal` (the evidence-gate-
+    //    aware judge from judge.ts). This is what the AC says: "calling EXISTING
+    //    advanceGoal(goal, judgeGoal-closure)".
+    const judgeFn = (g) => judgeGoal(g, llmJudge, cwd);
+    // 3. Advance one turn (pure — no I/O, no side effects).
+    const advanceResult = await advanceGoal(goal, judgeFn);
+    // 4. Persist the updated status + turnsUsed + lastVerdict.
+    const turnsConsumed = goal.turnsUsed + (goal.turnBudget - goal.turnsUsed - advanceResult.turnsRemaining);
+    const updated = await updateGoal(goalId, {
+        status: advanceResult.nextStatus,
+        turnsUsed: Math.max(goal.turnsUsed, goal.turnBudget - advanceResult.turnsRemaining),
+        lastVerdict: advanceResult.verdict,
+        // Clear pausedReason when we successfully advanced (non-paused result).
+        ...(advanceResult.nextStatus !== 'paused' ? { pausedReason: null } : {}),
+    }, cwd);
+    // `updated` can only be null if the row disappeared between load and update
+    // (extremely unlikely — treat as present with the pre-update snapshot).
+    const persisted = updated ?? { ...goal, status: advanceResult.nextStatus };
+    // Suppress unused variable warning.
+    void turnsConsumed;
+    // 5. Build the continuation nudge for the updated goal + latest verdict.
+    const continuation = buildContinuation(persisted, advanceResult.verdict);
+    return { advanceResult, goal: persisted, continuation };
+}
+//# sourceMappingURL=advance-with-persist.js.map

package/dist/goal/advance-with-persist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance-with-persist.js","sourceRoot":"","sources":["../../src/goal/advance-with-persist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAQH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAErD,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,sBAAsB,GAAc,IAAI,eAAe,CAAC;IAC5D,EAAE,EAAE,KAAK;IACT,UAAU,EAAE,KAAK;IACjB,MAAM,EACJ,iGAAiG;CACpG,CAAC,CAAC;AAgCH,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAc,EACd,UAGI,EAAE;IAEN,MAAM,EAAE,QAAQ,GAAG,sBAAsB,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAE3D,mCAAmC;IACnC,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2EAA2E;IAC3E,6EAA6E;IAC7E,4CAA4C;IAC5C,MAAM,OAAO,GAAG,CAAC,CAAa,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE/D,wDAAwD;IACxD,MAAM,aAAa,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAEvD,2DAA2D;IAC3D,MAAM,aAAa,GACjB,IAAI,CAAC,SAAS,GAAG,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;IAErF,MAAM,OAAO,GAAG,MAAM,UAAU,CAC9B,MAAM,EACN;QACE,MAAM,EAAE,aAAa,CAAC,UAAU;QAChC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,GAAG,aAAa,CAAC,cAAc,CAAC;QACnF,WAAW,EAAE,aAAa,CAAC,OAAO;QAClC,wEAAwE;QACxE,GAAG,CAAC,aAAa,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzE,EACD,GAAG,CACJ,CAAC;IAEF,4EAA4E;IAC5E,wEAAwE;IACxE,MAAM,SAAS,GAAG,OAAO,IAAI,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,UAAU,EAAE,CAAC;IAE3E,oCAAoC;IACpC,KAAK,aAAa,CAAC;IAEnB,yEAAyE;IACzE,MAAM,YAAY,GAAG,iBAAiB,CAAC,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAEzE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AAC1D,CAAC"}

package/dist/goal/arm.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Goal-loop arming — create + register the per-saga goal that `cleo go`
+ * uses to drive the Stop-hook self-renudge cycle (AC3 of T11496).
+ *
+ * `armGoalLoop` is called by `cleoGo()` after it has selected the active saga.
+ * It creates (or reuses via idempotency key) a `fuzzy` goal whose intent
+ * describes the saga work. The Stop-hook then advances this goal each turn,
+ * re-injecting the continuation nudge until `judgeGoal` signals
+ * `satisfied` or `impossible`.
+ *
+ * ## Idempotency
+ *
+ * The idempotency key is `cleo-go:${sagaId}:${epochDay}`, ensuring one goal
+ * per saga per calendar day. Re-runs of `cleo go` on the same day reuse the
+ * existing goal (via `onConflictDoNothing` in the store) rather than
+ * accumulating rows.
+ *
+ * ## Why fuzzy?
+ *
+ * Saga completion is orchestration-level progress — not a single task with
+ * ADR-051 evidence gates. A `fuzzy` goal lets the loop keep nudging Claude
+ * until the saga rollup shows the desired state; the injected nudge text
+ * (from `buildContinuation`) reminds Claude of the intent each turn.
+ *
+ * @module @cleocode/core/goal/arm
+ *
+ * @task T11496 E4-GOAL-LOOP
+ * @epic T11492 SG-AUTOPILOT
+ * @saga T11283 SG-COGNITIVE-SUBSTRATE
+ */
+import type { GoalRecord } from '@cleocode/contracts';
+/**
+ * Parameters for {@link armGoalLoop}.
+ *
+ * @task T11496
+ */
+export interface ArmGoalLoopParams {
+    /** The saga being worked on (e.g. `'T11492'`). */
+    readonly sagaId: string;
+    /** Human-readable saga title for the goal intent. */
+    readonly sagaTitle?: string;
+    /** Override project root (useful in tests). */
+    readonly cwd?: string;
+    /**
+     * Turn budget for the goal (default: {@link SAGA_GOAL_TURN_BUDGET}).
+     */
+    readonly turnBudget?: number;
+}
+/**
+ * Create (or reuse) the per-saga goal that arms the Stop-hook self-renudge
+ * loop for `cleo go`.
+ *
+ * Idempotent on `(sagaId, calendarDay)` — safe to call every `cleo go` turn.
+ *
+ * @param params - Arming parameters.
+ * @returns The created (or pre-existing) {@link GoalRecord}.
+ *
+ * @task T11496
+ */
+export declare function armGoalLoop(params: ArmGoalLoopParams): Promise<GoalRecord>;
+//# sourceMappingURL=arm.d.ts.map

package/dist/goal/arm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arm.d.ts","sourceRoot":"","sources":["../../src/goal/arm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CA2BhF"}