@cleocode/core 2026.10.18 → 2026.10.19

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

@@ -1,80 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,105 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,61 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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"}

package/dist/goal/arm.js

@@ -1,65 +0,0 @@
-/**
- * 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 { createGoal } from './store.js';
-/** Default turn budget for a saga-level goal (a full autopilot session). */
-const SAGA_GOAL_TURN_BUDGET = 20;
-/**
- * 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 async function armGoalLoop(params) {
-    const { sagaId, sagaTitle, cwd, turnBudget = SAGA_GOAL_TURN_BUDGET } = params;
-    // Idempotency key: one goal per saga per calendar day.
-    const epochDay = Math.floor(Date.now() / (1000 * 60 * 60 * 24));
-    const idempotencyKey = `cleo-go:${sagaId}:${epochDay}`;
-    const intent = sagaTitle != null
-        ? `Drive saga ${sagaId} (${sagaTitle}) forward — pick the next ready task and advance it until done.`
-        : `Drive saga ${sagaId} forward — pick the next ready task and advance it until done.`;
-    const criteria = [
-        `All tasks in saga ${sagaId} reach 'done' status with ADR-051 evidence gates satisfied.`,
-        'Each turn: run `cleo go` to pick the next ready task and start IVTR.',
-    ];
-    return createGoal({
-        goalKind: { kind: 'fuzzy' },
-        intent,
-        turnBudget,
-        criteria,
-        idempotencyKey,
-    }, cwd);
-}
-//# sourceMappingURL=arm.js.map

package/dist/goal/arm.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"arm.js","sourceRoot":"","sources":["../../src/goal/arm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,4EAA4E;AAC5E,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAoBjC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAyB;IACzD,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,qBAAqB,EAAE,GAAG,MAAM,CAAC;IAE9E,uDAAuD;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAChE,MAAM,cAAc,GAAG,WAAW,MAAM,IAAI,QAAQ,EAAE,CAAC;IAEvD,MAAM,MAAM,GACV,SAAS,IAAI,IAAI;QACf,CAAC,CAAC,cAAc,MAAM,KAAK,SAAS,iEAAiE;QACrG,CAAC,CAAC,cAAc,MAAM,gEAAgE,CAAC;IAE3F,MAAM,QAAQ,GAAsB;QAClC,qBAAqB,MAAM,6DAA6D;QACxF,sEAAsE;KACvE,CAAC;IAEF,OAAO,UAAU,CACf;QACE,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;QAC3B,MAAM;QACN,UAAU;QACV,QAAQ;QACR,cAAc;KACf,EACD,GAAG,CACJ,CAAC;AACJ,CAAC"}

package/dist/goal/continuation.d.ts

@@ -1,66 +0,0 @@
-/**
- * Prompt-cache-safe goal continuation builder (Layer 4 of SG-COGNITIVE-SUBSTRATE).
- *
- * ## The prompt-cache-safety contract (why user-message, not system mutation)
- *
- * Prompt caching keys on a STABLE message prefix — most importantly the system
- * prompt. The harness assembles `[system, ...history]` once and caches the long
- * static prefix; every cache hit skips re-processing those tokens. If the goal
- * loop nudged the agent by REWRITING the system prompt each turn, it would
- * invalidate that cached prefix on every single turn — turning a cheap cache hit
- * into a full re-encode and defeating the entire point of caching.
- *
- * {@link buildContinuation} therefore emits the nudge as a `role: 'user'`
- * message that is APPENDED after the existing conversation. The system prompt is
- * never touched, so the cached prefix stays valid and only the new (short) user
- * message is processed. The builder is also byte-stable for identical
- * `(goal, verdict)` inputs — the same continuation text is produced every call —
- * which is required so a re-issued turn reuses the same cache prefix rather than
- * minting a fresh, cache-busting string.
- *
- * ## Harness boundary (AC4)
- *
- * The CLI/SDK side (this builder) guarantees the continuation is a user message
- * and never mutates the system prompt. The HARNESS owns final message-array
- * assembly (it decides where to splice this user message and how the system
- * prompt is cached). This module guarantees the CLI-side contract; the harness
- * guarantees its own. The two together deliver end-to-end cache safety.
- *
- * @module @cleocode/core/goal/continuation
- *
- * @epic T11290 EP-CLEO-GOAL-SYSTEM
- * @task T11380
- * @saga T11283 SG-COGNITIVE-SUBSTRATE
- */
-import type { GoalContinuation, GoalJudgeVerdict, GoalRecord } from '@cleocode/contracts';
-/**
- * Maximum byte length of a continuation's `content`. A continuation is a nudge,
- * not a document — keeping it small bounds the per-turn token cost and keeps the
- * appended user message cheap to (re)process. Criteria beyond what fits are
- * truncated with an explicit marker so the cap is never silently exceeded.
- *
- * @task T11380
- */
-export declare const CONTINUATION_MAX_BYTES = 1200;
-/**
- * Build the next-turn continuation nudge for a goal, or `null` when no nudge is
- * warranted.
- *
- * Returns `null` for a TERMINAL verdict/status — a `satisfied`, `abandoned`, or
- * `impossible` goal has nothing left to nudge toward, so no user message is
- * emitted. Only `active` and `paused` goals receive a continuation (`paused`
- * because it can be resumed). The presence of `verdict.ok` or
- * `verdict.impossible` ALSO short-circuits to `null` even if a stale status says
- * otherwise — the verdict is the freshest signal.
- *
- * The continuation embeds the goal intent, the outstanding criteria, and the
- * judge's reason (so the agent knows WHY it must continue), and is byte-stable
- * for identical inputs (deterministic — required for prompt-cache prefix reuse).
- *
- * @param goal - The current goal record.
- * @param verdict - The judge's latest verdict for this goal.
- * @returns A `{ role: 'user', content }` continuation, or `null` when terminal.
- * @task T11380
- */
-export declare function buildContinuation(goal: GoalRecord, verdict: GoalJudgeVerdict): GoalContinuation | null;
-//# sourceMappingURL=continuation.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"continuation.d.ts","sourceRoot":"","sources":["../../src/goal/continuation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAG1F;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,gBAAgB,GACxB,gBAAgB,GAAG,IAAI,CA6BzB"}

package/dist/goal/continuation.js

@@ -1,111 +0,0 @@
-/**
- * Prompt-cache-safe goal continuation builder (Layer 4 of SG-COGNITIVE-SUBSTRATE).
- *
- * ## The prompt-cache-safety contract (why user-message, not system mutation)
- *
- * Prompt caching keys on a STABLE message prefix — most importantly the system
- * prompt. The harness assembles `[system, ...history]` once and caches the long
- * static prefix; every cache hit skips re-processing those tokens. If the goal
- * loop nudged the agent by REWRITING the system prompt each turn, it would
- * invalidate that cached prefix on every single turn — turning a cheap cache hit
- * into a full re-encode and defeating the entire point of caching.
- *
- * {@link buildContinuation} therefore emits the nudge as a `role: 'user'`
- * message that is APPENDED after the existing conversation. The system prompt is
- * never touched, so the cached prefix stays valid and only the new (short) user
- * message is processed. The builder is also byte-stable for identical
- * `(goal, verdict)` inputs — the same continuation text is produced every call —
- * which is required so a re-issued turn reuses the same cache prefix rather than
- * minting a fresh, cache-busting string.
- *
- * ## Harness boundary (AC4)
- *
- * The CLI/SDK side (this builder) guarantees the continuation is a user message
- * and never mutates the system prompt. The HARNESS owns final message-array
- * assembly (it decides where to splice this user message and how the system
- * prompt is cached). This module guarantees the CLI-side contract; the harness
- * guarantees its own. The two together deliver end-to-end cache safety.
- *
- * @module @cleocode/core/goal/continuation
- *
- * @epic T11290 EP-CLEO-GOAL-SYSTEM
- * @task T11380
- * @saga T11283 SG-COGNITIVE-SUBSTRATE
- */
-import { isTerminalGoalStatus } from '@cleocode/contracts/goal.js';
-/**
- * Maximum byte length of a continuation's `content`. A continuation is a nudge,
- * not a document — keeping it small bounds the per-turn token cost and keeps the
- * appended user message cheap to (re)process. Criteria beyond what fits are
- * truncated with an explicit marker so the cap is never silently exceeded.
- *
- * @task T11380
- */
-export const CONTINUATION_MAX_BYTES = 1200;
-/**
- * Build the next-turn continuation nudge for a goal, or `null` when no nudge is
- * warranted.
- *
- * Returns `null` for a TERMINAL verdict/status — a `satisfied`, `abandoned`, or
- * `impossible` goal has nothing left to nudge toward, so no user message is
- * emitted. Only `active` and `paused` goals receive a continuation (`paused`
- * because it can be resumed). The presence of `verdict.ok` or
- * `verdict.impossible` ALSO short-circuits to `null` even if a stale status says
- * otherwise — the verdict is the freshest signal.
- *
- * The continuation embeds the goal intent, the outstanding criteria, and the
- * judge's reason (so the agent knows WHY it must continue), and is byte-stable
- * for identical inputs (deterministic — required for prompt-cache prefix reuse).
- *
- * @param goal - The current goal record.
- * @param verdict - The judge's latest verdict for this goal.
- * @returns A `{ role: 'user', content }` continuation, or `null` when terminal.
- * @task T11380
- */
-export function buildContinuation(goal, verdict) {
-    // The verdict is the freshest signal: a satisfied or impossible verdict means
-    // there is nothing to nudge toward, regardless of the persisted status.
-    if (verdict.ok || verdict.impossible) {
-        return null;
-    }
-    // A terminal status (satisfied/abandoned/impossible) likewise yields no nudge.
-    if (isTerminalGoalStatus(goal.status)) {
-        return null;
-    }
-    const lines = [];
-    lines.push(`[GOAL CONTINUATION] Your active goal is not yet satisfied.`);
-    lines.push(`Intent: ${goal.intent}`);
-    if (goal.criteria.length > 0) {
-        lines.push(`Outstanding criteria:`);
-        for (const criterion of goal.criteria) {
-            lines.push(`  - ${criterion}`);
-        }
-    }
-    lines.push(`Why continue: ${verdict.reason}`);
-    lines.push(`Turns: ${goal.turnsUsed}/${goal.turnBudget} used. Keep working until the goal's gates are evidence-backed.`);
-    const content = clampToBytes(lines.join('\n'), CONTINUATION_MAX_BYTES);
-    return { role: 'user', content };
-}
-/**
- * Clamp a string to at most `maxBytes` UTF-8 bytes, appending a truncation
- * marker when it overflows. Deterministic — identical input yields identical
- * output, preserving byte-stability for prompt-cache prefix reuse.
- *
- * @internal
- */
-function clampToBytes(text, maxBytes) {
-    const encoder = new TextEncoder();
-    if (encoder.encode(text).length <= maxBytes) {
-        return text;
-    }
-    const marker = '\n… [truncated]';
-    const budget = maxBytes - encoder.encode(marker).length;
-    // Walk back from the byte budget to a safe character boundary so we never
-    // split a multi-byte codepoint.
-    let sliced = text;
-    while (encoder.encode(sliced).length > budget && sliced.length > 0) {
-        sliced = sliced.slice(0, -1);
-    }
-    return sliced + marker;
-}
-//# sourceMappingURL=continuation.js.map

package/dist/goal/continuation.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"continuation.js","sourceRoot":"","sources":["../../src/goal/continuation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAgB,EAChB,OAAyB;IAEzB,8EAA8E;IAC9E,wEAAwE;IACxE,IAAI,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,+EAA+E;IAC/E,IAAI,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAC;IACzE,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAErC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACpC,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,OAAO,SAAS,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,KAAK,CAAC,IAAI,CACR,UAAU,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,UAAU,iEAAiE,CAC7G,CAAC;IAEF,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACvE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,QAAgB;IAClD,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC;IACjC,MAAM,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IACxD,0EAA0E;IAC1E,gCAAgC;IAChC,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,MAAM,GAAG,MAAM,CAAC;AACzB,CAAC"}

package/dist/goal/judge.d.ts

@@ -1,113 +0,0 @@
-/**
- * Evidence-gate-aware goal judge (Layer 4 of SG-COGNITIVE-SUBSTRATE).
- *
- * This is CLEO's core differentiator over Claude-Code (transcript judge) and
- * Hermes (post-turn loop, still transcript-judged for fuzzy intent). For a
- * `task-completion` goal, the judge NEVER reads the transcript: it resolves the
- * target task's REAL status and re-uses the shipped ADR-051 evidence
- * infrastructure ({@link validateEvidenceForGate} +
- * {@link GATE_EVIDENCE_REQUIREMENTS} via `tasks/evidence.ts`). A goal is
- * satisfied ONLY when the task is `status === 'done'` AND every required gate
- * ({@link CRITICAL_GATES}) is backed by evidence atoms of the kinds ADR-051
- * mandates. Transcript text can never satisfy a task-completion goal.
- *
- * `fuzzy` goals — those with no machine-checkable artifact — delegate to an
- * INJECTABLE LLM judge ({@link GoalJudge}). The judge interface, not a concrete
- * model client, is the dependency, so vitest passes a deterministic mock and
- * stays fully offline/hermetic. The fuzzy path NEVER touches the evidence
- * infrastructure.
- *
- * @module @cleocode/core/goal/judge
- *
- * @epic T11290 EP-CLEO-GOAL-SYSTEM
- * @task T11378
- * @saga T11283 SG-COGNITIVE-SUBSTRATE
- * @adr ADR-051
- */
-import type { GoalJudge, GoalJudgeVerdict, GoalRecord, VerificationGate } from '@cleocode/contracts';
-/**
- * The gates a task-completion goal demands be evidence-backed before it is
- * judged satisfied. These are the ADR-051 critical gates that reject
- * override-only evidence (`implemented` + `testsPassed`) — the same two gates
- * `cleo complete` enforces hardest. A goal that says "complete T123" therefore
- * means exactly what CLEO means by complete: code landed (commit+files) AND
- * tests proven (test-run/tool/pr), with real, validated atoms.
- *
- * @task T11378
- * @adr ADR-051
- */
-export declare const CRITICAL_GATES: readonly VerificationGate[];
-/**
- * Judge a goal and return a uniform {@link GoalJudgeVerdict}.
- *
- * Routing:
- * - `task-completion` → {@link judgeTaskCompletion} (evidence path, no LLM).
- * - `fuzzy`           → the injected {@link GoalJudge} (LLM fallback).
- *
- * The `llmJudge` is REQUIRED only for fuzzy goals; a task-completion goal never
- * calls it. Passing the judge by parameter (dependency injection) is what keeps
- * vitest hermetic.
- *
- * @param goal - The goal under evaluation.
- * @param llmJudge - The injectable LLM judge used for fuzzy goals.
- * @param cwd - Project root override for task lookup.
- * @returns The verdict (same shape for both paths).
- * @task T11378
- */
-export declare function judgeGoal(goal: GoalRecord, llmJudge: GoalJudge, cwd?: string): Promise<GoalJudgeVerdict>;
-/**
- * Evidence-gate-aware judgement for a single task-completion goal.
- *
- * Decision table (first match wins):
- * 1. Task not found → `impossible` (the goal references a task that no longer
- *    exists).
- * 2. Task `cancelled` / `archived` → `impossible` (terminal non-done state —
- *    it can never become `done`).
- * 3. Task not `done` → `ok: false` (still in flight; reason carries the real
- *    status so the continuation tells the agent what remains).
- * 4. Task `done` but a critical gate lacks the ADR-051-required evidence atoms
- *    → `ok: false` (done-without-proof is NOT satisfied — the whole point).
- * 5. Task `done` AND every critical gate is evidence-backed → `ok: true`.
- *
- * @param targetTaskId - The task the goal wants completed.
- * @param cwd - Project root override.
- * @returns The verdict, with `evidence[]` listing the atom kinds inspected.
- * @task T11378
- * @adr ADR-051
- */
-export declare function judgeTaskCompletion(targetTaskId: string, cwd?: string): Promise<GoalJudgeVerdict>;
-/**
- * A deterministic, offline {@link GoalJudge} that always returns a fixed
- * verdict. Wired in tests (and as a safe default in non-LLM contexts) so the
- * fuzzy path is fully exercised without a live model call.
- *
- * Production wires a real LLM-backed implementation of {@link GoalJudge}; this
- * stub exists so the goal loop has a hermetic fallback and so the gate
- * `GATE_EVIDENCE_REQUIREMENTS` import stays referenced for downstream tooling.
- *
- * @task T11378
- */
-export declare class StaticGoalJudge implements GoalJudge {
-    private readonly verdict;
-    /**
-     * @param verdict - The verdict every {@link judge} call returns.
-     */
-    constructor(verdict: GoalJudgeVerdict);
-    /**
-     * Return the configured verdict, ignoring the goal entirely (deterministic).
-     *
-     * @param _goal - The goal under evaluation (unused — deterministic stub).
-     * @returns The fixed verdict.
-     */
-    judge(_goal: GoalRecord): Promise<GoalJudgeVerdict>;
-}
-/**
- * The number of distinct critical gates the evidence judge inspects. Exposed so
- * callers/tests can assert the judge consulted the full {@link CRITICAL_GATES}
- * set without hard-coding the count, and to keep {@link GATE_EVIDENCE_REQUIREMENTS}
- * referenced as the SSoT the judge validates against.
- *
- * @task T11378
- */
-export declare const CRITICAL_GATE_COUNT: number;
-//# sourceMappingURL=judge.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/goal/judge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAY7B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAGpD,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,SAAS,EACnB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAkE3B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAInC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC;;OAEG;gBAC0B,OAAO,EAAE,gBAAgB;IAEtD;;;;;OAKG;IACG,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG1D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAE1B,CAAC"}