litcodex-ai 0.3.0

package/node_modules/@litcodex/lit-loop/dist/loop-errors.js

@@ -0,0 +1,43 @@
+// src/loop-errors.ts — M09/T14 CLI error model (A3 C7: branch on `err.code`, NOT instanceof).
+//
+// The CLI-owned `LitLoopError` + its stable `LoopErrorCode` union, plus `exitCodeForLoop`, which
+// maps ANY thrown error to an exit code by reading `.code` (never `instanceof`
+// PlanMissingError/PlanCorruptError). The store's own codes (PLAN_MISSING→3, PLAN_CORRUPT→4,
+// WRITE_FAILED→5) defer to the store-owned `exitCodeFor`. Split out of loop-cli for the LOC ceiling
+// and to break the cli↔handlers import cycle (handlers throw these; cli renders + maps them).
+import { exitCodeFor } from "./state-store.js";
+/** Machine-readable CLI error. `code` is the stable token; the exit code is derived from it. */
+export class LitLoopError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.name = "LitLoopError";
+        this.code = code;
+        if (details !== undefined) {
+            this.details = details;
+        }
+    }
+}
+/**
+ * Exit code for any thrown error, branching ONLY on `err.code` (A3 C7 — never `instanceof`
+ * PlanMissingError/PlanCorruptError). Store codes (PLAN_MISSING→3, PLAN_CORRUPT→4, WRITE_FAILED→5)
+ * defer to the store-owned {@link exitCodeFor}; the CLI's own codes map here.
+ */
+export function exitCodeForLoop(err) {
+    const code = typeof err === "object" && err !== null && "code" in err ? err.code : undefined;
+    switch (code) {
+        case "LIT_LOOP_SUBCOMMAND_UNKNOWN":
+            return 1; // unknown subcommand / usage
+        case "LIT_LOOP_ARGUMENT_MISSING":
+        case "LIT_LOOP_ARGUMENT_INVALID":
+        case "LIT_LOOP_BRIEF_REQUIRED":
+        case "LIT_LOOP_BRIEF_FILE_UNREADABLE":
+        case "LIT_LOOP_EVIDENCE_STATUS_INVALID":
+            return 2; // bad args
+        case "LIT_LOOP_GOAL_NOT_FOUND":
+        case "LIT_LOOP_CRITERION_NOT_FOUND":
+        case "LIT_LOOP_CRITERIA_NOT_ALL_PASS":
+            return 3; // not found / unresolved
+        default:
+            return exitCodeFor(err); // store codes (3/4/5) + unexpected → 1
+    }
+}

package/node_modules/@litcodex/lit-loop/dist/loop-handlers.d.ts

@@ -0,0 +1,18 @@
+import { type resolveLoopScope } from "./state-store.js";
+export type LoopClock = () => string;
+export type Ctx = {
+    repoRoot: string;
+    scope: ReturnType<typeof resolveLoopScope>;
+    now: LoopClock;
+};
+export interface HandlerResult {
+    readonly exitCode: number;
+    readonly text: string;
+    readonly json: Record<string, unknown>;
+}
+export declare function hasFlag(argv: readonly string[], flag: string): boolean;
+export declare function handleCreate(argv: readonly string[], ctx: Ctx): Promise<HandlerResult>;
+export declare function handleStatus(ctx: Ctx): Promise<HandlerResult>;
+export declare function handleRun(argv: readonly string[], ctx: Ctx): Promise<HandlerResult>;
+export declare function handleCheckpoint(argv: readonly string[], ctx: Ctx): Promise<HandlerResult>;
+export declare function handleRecordEvidence(argv: readonly string[], ctx: Ctx): Promise<HandlerResult>;

package/node_modules/@litcodex/lit-loop/dist/loop-handlers.js

@@ -0,0 +1,311 @@
+// src/loop-handlers.ts — M09/T14 subcommand handlers (split out of loop-cli for the LOC ceiling).
+//
+// The five mutating/reading handlers (create/status/run/checkpoint/record-evidence) plus their
+// tiny arg helpers and shared plan helpers. Each is one read→mutate→writePlan→appendLedger critical
+// section under the store's withMutationLock. All fs I/O is delegated to the M08 store via flat
+// `./state-store.js` (A3 C9) — this module never touches node:fs. Errors are the CLI's
+// `LitLoopError` (mapped on `.code` by loop-cli's exitCodeForLoop) or re-thrown store errors.
+import { buildCodexGoalCheckpoint, buildCodexGoalInstruction } from "./codex-goal-instruction.js";
+import { LitLoopError } from "./loop-errors.js";
+import { buildRunInstruction, deriveGoalCandidates, normalizeGoalId, pickNextRunnableGoal, requireAllCriteriaPass, seedDefaultSuccessCriteria, summarizePlan, titleFromObjective, } from "./loop-model.js";
+import { LOOP_CREATE_STDOUT } from "./loop-stdout.js";
+import { repoRelative } from "./state-paths.js";
+import { appendLedger, readBriefFile, readPlan, resolveLoopStateDir, withMutationLock, writeBrief, writePlan, } from "./state-store.js";
+// ── tiny arg helpers (no I/O) ────────────────────────────────────────────────
+export function hasFlag(argv, flag) {
+    return argv.includes(flag);
+}
+function readValue(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === flag) {
+            return argv[i + 1];
+        }
+        if (a?.startsWith(`${flag}=`)) {
+            return a.slice(flag.length + 1);
+        }
+    }
+    return undefined;
+}
+function requireValue(argv, flag) {
+    const v = readValue(argv, flag);
+    if (v === undefined || v === "") {
+        throw new LitLoopError(`Missing ${flag}.`, "LIT_LOOP_ARGUMENT_MISSING", { flag });
+    }
+    return v;
+}
+function requireNonEmpty(value, flag) {
+    if (value.trim() === "") {
+        throw new LitLoopError(`Missing ${flag}.`, "LIT_LOOP_ARGUMENT_MISSING", { flag });
+    }
+    return value;
+}
+function positionalText(argv) {
+    return argv.filter((a) => !a.startsWith("-")).join(" ");
+}
+// ── create ───────────────────────────────────────────────────────────────────
+async function resolveBrief(argv, repoRoot) {
+    const inline = readValue(argv, "--brief");
+    if (inline !== undefined && inline.trim() !== "") {
+        return inline;
+    }
+    const briefFile = readValue(argv, "--brief-file");
+    if (briefFile !== undefined && briefFile !== "") {
+        try {
+            return await readBriefFile(repoRoot, briefFile);
+        }
+        catch {
+            throw new LitLoopError(`Cannot read --brief-file: ${briefFile}.`, "LIT_LOOP_BRIEF_FILE_UNREADABLE", {
+                path: briefFile,
+            });
+        }
+    }
+    return positionalText(argv);
+}
+export async function handleCreate(argv, ctx) {
+    const brief = await resolveBrief(argv, ctx.repoRoot);
+    if (brief.trim() === "") {
+        throw new LitLoopError("Missing brief text.", "LIT_LOOP_BRIEF_REQUIRED");
+    }
+    const force = hasFlag(argv, "--force");
+    return withMutationLock(ctx.repoRoot, ctx.scope, async () => {
+        const existing = await readPlanOrNull(ctx);
+        if (existing !== null && !force) {
+            return planResult(existing); // idempotent no-op
+        }
+        const now = ctx.now();
+        const candidates = deriveGoalCandidates(brief);
+        const goals = candidates.map((objective, i) => ({
+            id: normalizeGoalId(i, objective),
+            title: titleFromObjective(objective),
+            objective,
+            status: "pending",
+            successCriteria: seedDefaultSuccessCriteria(objective),
+            attempt: 0,
+            createdAt: now,
+            updatedAt: now,
+        }));
+        const paths = planPaths(ctx);
+        const plan = {
+            version: 1,
+            createdAt: now,
+            updatedAt: now,
+            ...paths,
+            sessionId: ctx.scope?.sessionId ?? null,
+            goals,
+        };
+        await writeBrief(ctx.repoRoot, brief, ctx.scope);
+        await writePlan(ctx.repoRoot, plan, ctx.scope);
+        await appendLedger(ctx.repoRoot, { at: now, kind: "plan_created", message: `${goals.length} goal(s) derived from brief.` }, ctx.scope);
+        return {
+            exitCode: 0,
+            text: LOOP_CREATE_STDOUT(goals.length, plan),
+            json: { ok: true, plan, summary: summarizePlan(plan) },
+        };
+    });
+}
+// ── status ───────────────────────────────────────────────────────────────────
+export async function handleStatus(ctx) {
+    const plan = await readPlan(ctx.repoRoot, ctx.scope);
+    const summary = summarizePlan(plan);
+    const header = `lit-loop status: ${summary.total} goals (${summary.pending} pending, ${summary.in_progress} in progress, ${summary.complete} complete, ${summary.failed} failed, ${summary.blocked} blocked)`;
+    const lines = plan.goals.map((g) => {
+        const pass = g.successCriteria.filter((c) => c.status === "pass").length;
+        return `- ${g.id} [${g.status}] ${g.title} (criteria ${pass}/${g.successCriteria.length} pass)`;
+    });
+    return { exitCode: 0, text: `${[header, ...lines].join("\n")}\n`, json: { ok: true, plan, summary } };
+}
+// ── run ──────────────────────────────────────────────────────────────────────
+export async function handleRun(argv, ctx) {
+    const retryFailed = hasFlag(argv, "--retry-failed");
+    return withMutationLock(ctx.repoRoot, ctx.scope, async () => {
+        const plan = await readPlan(ctx.repoRoot, ctx.scope);
+        const pick = pickNextRunnableGoal(plan, { retryFailed });
+        if (pick === null) {
+            return {
+                exitCode: 0,
+                text: "lit-loop: all goals complete\n",
+                json: { ok: true, done: true, summary: summarizePlan(plan), plan },
+            };
+        }
+        const now = ctx.now();
+        const goal = pick.goal;
+        if (pick.retried) {
+            goal.status = "pending";
+            await appendLedger(ctx.repoRoot, { at: now, kind: "goal_retried", goalId: goal.id }, ctx.scope);
+        }
+        goal.status = "in_progress";
+        goal.attempt += 1;
+        goal.startedAt ??= now;
+        goal.updatedAt = now;
+        plan.activeGoalId = goal.id;
+        plan.updatedAt = now;
+        await writePlan(ctx.repoRoot, plan, ctx.scope);
+        await appendLedger(ctx.repoRoot, {
+            at: now,
+            kind: pick.resumed ? "goal_resumed" : "goal_started",
+            goalId: goal.id,
+            message: `Attempt ${goal.attempt}`,
+        }, ctx.scope);
+        const runText = buildRunInstruction(plan, goal);
+        const goalInstruction = buildCodexGoalInstruction({ plan, goal });
+        const text = `${runText}\n${goalInstruction.text}\n`;
+        return {
+            exitCode: 0,
+            text,
+            json: {
+                ok: true,
+                done: false,
+                resumed: pick.resumed,
+                goal,
+                instruction: { text },
+                codexGoal: goalInstruction.json,
+                plan,
+            },
+        };
+    });
+}
+// ── checkpoint ───────────────────────────────────────────────────────────────
+const CHECKPOINT_STATUSES = new Set(["complete", "failed", "blocked"]);
+export async function handleCheckpoint(argv, ctx) {
+    const goalId = requireValue(argv, "--goal-id");
+    const statusRaw = requireValue(argv, "--status");
+    if (!CHECKPOINT_STATUSES.has(statusRaw)) {
+        throw new LitLoopError(`Invalid --status: ${statusRaw} (use complete|failed|blocked).`, "LIT_LOOP_ARGUMENT_INVALID", {
+            status: statusRaw,
+        });
+    }
+    const status = statusRaw;
+    const evidence = requireNonEmpty(requireValue(argv, "--evidence"), "--evidence");
+    return withMutationLock(ctx.repoRoot, ctx.scope, async () => {
+        const plan = await readPlan(ctx.repoRoot, ctx.scope);
+        const goal = findGoal(plan, goalId);
+        if (status === "complete") {
+            const unresolved = requireAllCriteriaPass(goal);
+            if (unresolved.length > 0) {
+                throw new LitLoopError(`Goal ${goalId} has unresolved criteria.`, "LIT_LOOP_CRITERIA_NOT_ALL_PASS", {
+                    goalId,
+                    unresolved,
+                });
+            }
+        }
+        const now = ctx.now();
+        goal.status = status;
+        goal.evidence = evidence;
+        goal.updatedAt = now;
+        if (status === "complete") {
+            goal.completedAt = now;
+            delete goal.failedAt;
+            delete goal.failureReason;
+        }
+        else {
+            goal.failedAt = now;
+            goal.failureReason = evidence;
+        }
+        if (plan.activeGoalId === goalId) {
+            delete plan.activeGoalId;
+        }
+        plan.updatedAt = now;
+        const kind = status === "complete" ? "goal_completed" : status === "failed" ? "goal_failed" : "goal_blocked";
+        const ledgerEntry = { at: now, kind, goalId, goalStatus: status, evidence };
+        await writePlan(ctx.repoRoot, plan, ctx.scope);
+        await appendLedger(ctx.repoRoot, ledgerEntry, ctx.scope);
+        const codexCheckpoint = buildCodexGoalCheckpoint({ plan, goal, status });
+        return {
+            exitCode: 0,
+            text: `lit-loop checkpoint: ${goalId} -> ${status}\n\n${codexCheckpoint}\n`,
+            json: { ok: true, goal, ledgerEntry, codexGoal: { status }, plan, summary: summarizePlan(plan) },
+        };
+    });
+}
+// -- record-evidence -----------------------------------------------------------
+const EVIDENCE_STATUSES = new Set(["pass", "fail", "blocked"]);
+export async function handleRecordEvidence(argv, ctx) {
+    const goalId = requireValue(argv, "--goal-id");
+    const criterionId = requireValue(argv, "--criterion-id");
+    const statusRaw = requireValue(argv, "--status");
+    if (!EVIDENCE_STATUSES.has(statusRaw)) {
+        throw new LitLoopError(`Invalid --status: ${statusRaw} (use pass|fail|blocked).`, "LIT_LOOP_EVIDENCE_STATUS_INVALID", {
+            status: statusRaw,
+        });
+    }
+    const status = statusRaw;
+    const evidence = requireNonEmpty(requireValue(argv, "--evidence"), "--evidence");
+    const notes = readValue(argv, "--notes");
+    return withMutationLock(ctx.repoRoot, ctx.scope, async () => {
+        const plan = await readPlan(ctx.repoRoot, ctx.scope);
+        const goal = findGoal(plan, goalId);
+        const crit = goal.successCriteria.find((c) => c.id === criterionId);
+        if (crit === undefined) {
+            throw new LitLoopError(`Unknown criterion: ${criterionId}.`, "LIT_LOOP_CRITERION_NOT_FOUND", {
+                goalId,
+                criterionId,
+            });
+        }
+        const now = ctx.now();
+        const prevStatus = crit.status;
+        crit.status = status;
+        crit.capturedEvidence = evidence;
+        crit.capturedAt = now;
+        if (notes !== undefined) {
+            crit.notes = notes;
+        }
+        goal.updatedAt = now;
+        plan.updatedAt = now;
+        const kind = status === "pass" ? "evidence_captured" : status === "fail" ? "criterion_failed" : "criterion_blocked";
+        const ledgerEntry = {
+            at: now,
+            kind,
+            goalId,
+            criterionId,
+            criterionStatus: status,
+            evidence,
+            before: { status: prevStatus },
+            after: { status, capturedAt: now },
+        };
+        await writePlan(ctx.repoRoot, plan, ctx.scope);
+        await appendLedger(ctx.repoRoot, ledgerEntry, ctx.scope);
+        return {
+            exitCode: 0,
+            text: `lit-loop evidence recorded: ${goalId}/${criterionId} -> ${status}\n`,
+            json: { ok: true, goal, criterion: crit, ledgerEntry, plan, summary: summarizePlan(plan) },
+        };
+    });
+}
+// ── shared helpers ───────────────────────────────────────────────────────────
+function findGoal(plan, goalId) {
+    const goal = plan.goals.find((g) => g.id === goalId);
+    if (goal === undefined) {
+        throw new LitLoopError(`Unknown lit-loop goal id: ${goalId}.`, "LIT_LOOP_GOAL_NOT_FOUND", { goalId });
+    }
+    return goal;
+}
+function planPaths(ctx) {
+    const dir = resolveLoopStateDir(ctx.repoRoot, ctx.scope);
+    const rel = repoRelative(dir, ctx.repoRoot);
+    return {
+        briefPath: `${rel}/brief.md`,
+        goalsPath: `${rel}/goals.json`,
+        ledgerPath: `${rel}/ledger.jsonl`,
+        evidenceDir: `${rel}/evidence`,
+    };
+}
+async function readPlanOrNull(ctx) {
+    try {
+        return await readPlan(ctx.repoRoot, ctx.scope);
+    }
+    catch (err) {
+        const code = typeof err === "object" && err !== null && "code" in err ? err.code : undefined;
+        if (code === "LIT_LOOP_PLAN_MISSING") {
+            return null;
+        }
+        throw err;
+    }
+}
+function planResult(plan) {
+    return {
+        exitCode: 0,
+        text: LOOP_CREATE_STDOUT(plan.goals.length, plan),
+        json: { ok: true, plan, summary: summarizePlan(plan) },
+    };
+}

package/node_modules/@litcodex/lit-loop/dist/loop-model.d.ts

@@ -0,0 +1,51 @@
+import type { LoopCriterion, LoopGoal, LoopPlan, PlanSummary } from "./loop-types.js";
+/**
+ * Derive ordered goal objective strings from a free-text brief. Bullets/numbered lines win; if
+ * none, non-heading paragraphs; if neither yields a candidate, a single fallback objective. Pure
+ * and deterministic — a single linear pass, per-line capped at 1200 chars, deduped keeping first.
+ */
+export declare function deriveGoalCandidates(brief: string): string[];
+/**
+ * Build a goal id `G` + 3-digit zero-padded (index+1) + optional `-<slug>`. The slug strips every
+ * non-`[a-z0-9]` run to `-`, trims edge dashes, caps at 36 chars; an empty slug body drops the
+ * trailing dash so the id is just `G001`. Always matches `^G\d{3}(-[a-z0-9-]+)?$`.
+ */
+export declare function normalizeGoalId(index: number, objective: string): string;
+/** First non-empty line of the objective, truncated to 69 + "..." when longer than 72 chars. */
+export declare function titleFromObjective(objective: string): string;
+/**
+ * Seed exactly C001(happy)/C002(edge)/C003(regression), each pending with no captured evidence.
+ * The objective's first 80 chars form the human-readable subject in the happy-path scenario.
+ */
+export declare function seedDefaultSuccessCriteria(objective: string): LoopCriterion[];
+/** A scheduler pick: the selected goal plus whether it was a resume or a retry re-pick. */
+export interface RunnablePick {
+    goal: LoopGoal;
+    resumed: boolean;
+    retried: boolean;
+}
+/**
+ * Select the next goal to run: first `in_progress` (resume), else first `pending`, else — only
+ * when `retryFailed` — the first `failed` (retry re-pick), else null. Pure: returns the goal
+ * reference; the caller (R4) applies the attempt/status mutations.
+ */
+export declare function pickNextRunnableGoal(plan: LoopPlan, opts: {
+    retryFailed: boolean;
+}): RunnablePick | null;
+/**
+ * Returns the list of `{id,status}` criteria blocking completion. A goal completes only when it
+ * has >=1 criterion and EVERY criterion is `pass`; an empty list FAILS (returns a sentinel entry).
+ */
+export declare function requireAllCriteriaPass(goal: LoopGoal): Array<{
+    id: string;
+    status: string;
+}>;
+/** Roll up goal-status counts and the criteria pass/pending/fail/blocked totals. Never persisted. */
+export declare function summarizePlan(plan: LoopPlan): PlanSummary;
+/**
+ * The deterministic, marker-free, legacy-token-free run handoff block. No `<lit-loop-mode>`
+ * marker (that is the M15 directive, not the CLI instruction) and no marketing copy — only the
+ * plan/ledger paths, the goal, its objective, the seeded criteria, and the LitCodex-native
+ * next-action commands a caller runs to record evidence and checkpoint.
+ */
+export declare function buildRunInstruction(plan: LoopPlan, goal: LoopGoal): string;

package/node_modules/@litcodex/lit-loop/dist/loop-model.js

@@ -0,0 +1,165 @@
+// src/loop-model.ts — M09/T14 PURE domain logic (A3 C7, S09 §5 model rules).
+//
+// Goal derivation from a brief, success-criteria seeding, next-runnable-goal selection, plan
+// summary, the all-criteria-pass gate, and the deterministic run-handoff text. Operates on
+// in-memory plan objects only. Imports ONLY state-types (types) — NO node:fs, NO store, NO I/O,
+// no `process`, no clock. Every output is fully determined by its arguments.
+const FALLBACK_OBJECTIVE = "Complete the requested project objective.";
+const MAX_OBJECTIVE = 1200;
+const MAX_TITLE = 72;
+const BULLET_RE = /^\s*(?:[-*+]\s+|\d+[.)]\s+)/;
+/** Strip a leading bullet/numbered marker and surrounding whitespace from one line. */
+function cleanLine(line) {
+    return line.replace(BULLET_RE, "").trim();
+}
+/**
+ * Derive ordered goal objective strings from a free-text brief. Bullets/numbered lines win; if
+ * none, non-heading paragraphs; if neither yields a candidate, a single fallback objective. Pure
+ * and deterministic — a single linear pass, per-line capped at 1200 chars, deduped keeping first.
+ */
+export function deriveGoalCandidates(brief) {
+    const lines = brief.split(/\r?\n/);
+    const bulletLines = lines.filter((l) => BULLET_RE.test(l));
+    let raw;
+    if (bulletLines.length > 0) {
+        raw = bulletLines.map(cleanLine);
+    }
+    else {
+        raw = brief
+            .split(/\n\s*\n/)
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0 && !p.startsWith("#"));
+    }
+    const seen = new Set();
+    const candidates = [];
+    for (const value of raw) {
+        if (value.length === 0 || value.length > MAX_OBJECTIVE) {
+            continue;
+        }
+        if (seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        candidates.push(value);
+    }
+    return candidates.length > 0 ? candidates : [FALLBACK_OBJECTIVE];
+}
+/**
+ * Build a goal id `G` + 3-digit zero-padded (index+1) + optional `-<slug>`. The slug strips every
+ * non-`[a-z0-9]` run to `-`, trims edge dashes, caps at 36 chars; an empty slug body drops the
+ * trailing dash so the id is just `G001`. Always matches `^G\d{3}(-[a-z0-9-]+)?$`.
+ */
+export function normalizeGoalId(index, objective) {
+    const num = String(index + 1).padStart(3, "0");
+    const slugBody = objective
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 36)
+        .replace(/-+$/g, "");
+    return slugBody.length > 0 ? `G${num}-${slugBody}` : `G${num}`;
+}
+/** First non-empty line of the objective, truncated to 69 + "..." when longer than 72 chars. */
+export function titleFromObjective(objective) {
+    const firstLine = objective
+        .split(/\r?\n/)
+        .find((l) => l.trim().length > 0)
+        ?.trim() ?? "";
+    return firstLine.length > MAX_TITLE ? `${firstLine.slice(0, MAX_TITLE - 3)}...` : firstLine;
+}
+function truncate(value, max) {
+    return value.length > max ? value.slice(0, max) : value;
+}
+/**
+ * Seed exactly C001(happy)/C002(edge)/C003(regression), each pending with no captured evidence.
+ * The objective's first 80 chars form the human-readable subject in the happy-path scenario.
+ */
+export function seedDefaultSuccessCriteria(objective) {
+    const subject = truncate(titleFromObjective(objective) || objective, 80);
+    const seed = (id, userModel, scenario, expectedEvidence) => ({
+        id,
+        scenario,
+        userModel,
+        expectedEvidence,
+        capturedEvidence: null,
+        status: "pending",
+    });
+    return [
+        seed("C001", "happy", `happy path for: ${subject}`, "Run the happy-path scenario and capture passing output via record-evidence."),
+        seed("C002", "edge", "edge case (boundary/empty/malformed)", "Exercise a boundary/empty/malformed input and capture the result."),
+        seed("C003", "regression", "regression: adjacent surface still works", "Verify an adjacent surface is unbroken and capture proof."),
+    ];
+}
+/**
+ * Select the next goal to run: first `in_progress` (resume), else first `pending`, else — only
+ * when `retryFailed` — the first `failed` (retry re-pick), else null. Pure: returns the goal
+ * reference; the caller (R4) applies the attempt/status mutations.
+ */
+export function pickNextRunnableGoal(plan, opts) {
+    const inProgress = plan.goals.find((g) => g.status === "in_progress");
+    if (inProgress) {
+        return { goal: inProgress, resumed: true, retried: false };
+    }
+    const pending = plan.goals.find((g) => g.status === "pending");
+    if (pending) {
+        return { goal: pending, resumed: false, retried: false };
+    }
+    if (opts.retryFailed) {
+        const failed = plan.goals.find((g) => g.status === "failed");
+        if (failed) {
+            return { goal: failed, resumed: false, retried: true };
+        }
+    }
+    return null;
+}
+/**
+ * Returns the list of `{id,status}` criteria blocking completion. A goal completes only when it
+ * has >=1 criterion and EVERY criterion is `pass`; an empty list FAILS (returns a sentinel entry).
+ */
+export function requireAllCriteriaPass(goal) {
+    if (goal.successCriteria.length === 0) {
+        return [{ id: "(none)", status: "missing" }];
+    }
+    return goal.successCriteria.filter((c) => c.status !== "pass").map((c) => ({ id: c.id, status: c.status }));
+}
+/** Roll up goal-status counts and the criteria pass/pending/fail/blocked totals. Never persisted. */
+export function summarizePlan(plan) {
+    const summary = {
+        total: plan.goals.length,
+        pending: 0,
+        in_progress: 0,
+        complete: 0,
+        failed: 0,
+        blocked: 0,
+        criteria: { total: 0, pass: 0, pending: 0, fail: 0, blocked: 0 },
+    };
+    for (const goal of plan.goals) {
+        summary[goal.status] += 1;
+        for (const crit of goal.successCriteria) {
+            summary.criteria.total += 1;
+            summary.criteria[crit.status] += 1;
+        }
+    }
+    return summary;
+}
+/**
+ * The deterministic, marker-free, legacy-token-free run handoff block. No `<lit-loop-mode>`
+ * marker (that is the M15 directive, not the CLI instruction) and no marketing copy — only the
+ * plan/ledger paths, the goal, its objective, the seeded criteria, and the LitCodex-native
+ * next-action commands a caller runs to record evidence and checkpoint.
+ */
+export function buildRunInstruction(plan, goal) {
+    const lines = [
+        "lit-loop active-goal handoff",
+        `Plan: ${plan.goalsPath}`,
+        `Ledger: ${plan.ledgerPath}`,
+        `Goal: ${goal.id} — ${goal.title}`,
+        `Objective: ${goal.objective}`,
+        "Success criteria:",
+    ];
+    for (const c of goal.successCriteria) {
+        lines.push(`- [${c.id}] (${c.userModel}) ${c.scenario} — expect: ${c.expectedEvidence} — status: ${c.status}`);
+    }
+    lines.push("Next actions:", "1. Do the work for this goal.", `2. For each criterion: litcodex loop record-evidence --goal-id ${goal.id} --criterion-id <Cxxx> --status pass --evidence "<proof>"`, `3. Once all criteria pass: litcodex loop checkpoint --goal-id ${goal.id} --status complete --evidence "<summary>"`);
+    return `${lines.join("\n")}\n`;
+}

package/node_modules/@litcodex/lit-loop/dist/loop-stdout.d.ts

@@ -0,0 +1,6 @@
+/** The exact `loop create` stdout block (A3 C14): 4 lines, trailing `\n`. */
+export declare const LOOP_CREATE_STDOUT: (goalCount: number, paths: {
+    briefPath: string;
+    goalsPath: string;
+    ledgerPath: string;
+}) => string;

package/node_modules/@litcodex/lit-loop/dist/loop-stdout.js

@@ -0,0 +1,11 @@
+// src/loop-stdout.ts — M09/T14 `loop create` stdout contract (A3 C14). M20 imports this const.
+//
+// The single owner of the exact `loop create` stdout block: 4 lines, trailing `\n`. Exported as a
+// named const so M20 (path-robustness) imports it rather than hardcoding the literal. Split out of
+// loop-cli so both loop-cli (the dispatcher) and loop-handlers (the create handler) can import it
+// without an import cycle.
+/** The exact `loop create` stdout block (A3 C14): 4 lines, trailing `\n`. */
+export const LOOP_CREATE_STDOUT = (goalCount, paths) => `lit-loop plan created: ${goalCount} goal(s)\n` +
+    `brief: ${paths.briefPath}\n` +
+    `goals: ${paths.goalsPath}\n` +
+    `ledger: ${paths.ledgerPath}\n`;

package/node_modules/@litcodex/lit-loop/dist/loop-types.d.ts

@@ -0,0 +1,26 @@
+export type { LitLoopCriterion, LitLoopCriterionStatus, LitLoopGoal, LitLoopGoalStatus, LitLoopLedgerEntry, LitLoopLedgerEventKind, LitLoopLedgerInput, LitLoopPlan, LitLoopUserModel, } from "./state-types.js";
+export { LitLoopStateError } from "./state-types.js";
+import type { LitLoopCriterion, LitLoopCriterionStatus, LitLoopGoal, LitLoopGoalStatus, LitLoopLedgerEntry, LitLoopLedgerEventKind, LitLoopPlan, LitLoopUserModel } from "./state-types.js";
+export type LoopPlan = LitLoopPlan;
+export type LoopGoal = LitLoopGoal;
+export type LoopCriterion = LitLoopCriterion;
+export type LoopLedgerEntry = LitLoopLedgerEntry;
+export type LoopLedgerKind = LitLoopLedgerEventKind;
+export type LoopGoalStatus = LitLoopGoalStatus;
+export type LoopCriterionStatus = LitLoopCriterionStatus;
+export type LoopUserModel = LitLoopUserModel;
+export interface PlanSummary {
+    total: number;
+    pending: number;
+    in_progress: number;
+    complete: number;
+    failed: number;
+    blocked: number;
+    criteria: {
+        total: number;
+        pass: number;
+        pending: number;
+        fail: number;
+        blocked: number;
+    };
+}

package/node_modules/@litcodex/lit-loop/dist/loop-types.js

@@ -0,0 +1,8 @@
+// src/loop-types.ts — M09/T14 re-export / type-alias barrel (A3 C7, C9 flat layout).
+//
+// `state-types.ts` (M08) is the SINGLE schema source. This module declares NO independent
+// plan/goal/criterion/ledger shapes — it only re-exports the store types under M09's spelling
+// (`LoopPlan = LitLoopPlan`, etc.) plus the two pure VIEW types M09 computes and M11's doctor
+// imports (`PlanSummary`, `LoopGoalStatus`). Flat sibling import `./state-types.js` (NOT
+// `../state/...`). Types only; ZERO runtime / I/O.
+export { LitLoopStateError } from "./state-types.js";

package/node_modules/@litcodex/lit-loop/dist/markers.d.ts

@@ -0,0 +1,9 @@
+export declare const LIT_LOOP_DIRECTIVE_MARKER: "<lit-loop-mode>";
+export declare const LIT_LOOP_DIRECTIVE_CLOSE: "</lit-loop-mode>";
+export declare const LITWORK_DIRECTIVE_MARKER: "<litwork-mode>";
+export declare const LITWORK_DIRECTIVE_CLOSE: "</litwork-mode>";
+export declare const LIT_PLAN_DIRECTIVE_MARKER: "<lit-plan-mode>";
+export declare const LIT_PLAN_DIRECTIVE_CLOSE: "</lit-plan-mode>";
+export declare const LITGOAL_DIRECTIVE_MARKER: "<litgoal-mode>";
+export declare const LITGOAL_DIRECTIVE_CLOSE: "</litgoal-mode>";
+export type LitLoopDirectiveMarker = typeof LIT_LOOP_DIRECTIVE_MARKER;