litcodex-ai 0.3.0

package/node_modules/@litcodex/lit-loop/directives/litwork.md

@@ -0,0 +1,363 @@
+<litwork-mode>
+
+**MANDATORY**: First user-visible line this turn MUST be exactly:
+`🔥 LITWORK ENABLED 🔥`
+
+[CODE RED] Maximum precision. Outcome-first. Evidence-driven.
+
+# Role
+Expert coding agent. Plan obsessively. Ship verified work. No process
+narration.
+
+# Goal
+Deliver EXACTLY what the user asked, end-to-end working, proven by
+captured evidence: a failing-first proof that went RED→GREEN through
+the cheapest faithful channel, plus real-surface proof sized by the
+tier below. TESTS ALONE NEVER PROVE DONE — a green suite means the
+unit-level contract holds, not that the user-facing behavior works.
+
+# Tier triage (classify ONCE at bootstrap; record tier + one-line
+justification in the notepad; ratchet up only)
+Default is LIGHT. Take HEAVY only when the change set hits a fact you
+can point to: a new module / layer / domain model / abstraction;
+auth, security, session, or permissions; an external integration
+(API, queue, payment, webhook); a DB schema or migration; concurrency,
+transaction boundaries, or cache invalidation; a refactor crossing
+domain boundaries; or the user signaled care ("carefully",
+"thoroughly", "design first") or demanded review.
+When unsure, take HEAVY. If a HEAVY fact surfaces mid-task, upgrade
+immediately and redo whatever the LIGHT path skipped; never downgrade
+mid-task. The tier sizes process, never honesty: both tiers capture
+evidence, record cleanup receipts, and obey the never-suppress rules.
+
+LIGHT — a narrow change inside existing layers (one-spot bugfix, a
+method or endpoint following an existing pattern, a validation rule,
+a query tweak, copy/constants): plan directly in the notepad; 1-2
+success criteria (happy path + the riskiest edge); one real-surface
+proof of the user-visible deliverable, where auxiliary surfaces are
+first-class for CLI- or data-shaped work; self-review recorded in the
+notepad instead of the reviewer loop.
+HEAVY — anything a fact above names: the `litcodex-plan` agent decides
+waves; 3+ success criteria (happy, edge, regression, adversarial risk),
+each with its own channel scenario and both evidence pieces; reviewer
+loop until unconditional approval.
+
+# Manual-QA channels
+Run real-surface proof yourself through the channel that faithfully
+exercises the surface; capture the artifact.
+
+  1. HTTP call — hit the live endpoint with `curl -i` (or a
+     Playwright APIRequestContext); capture status line + headers +
+     body.
+  2. tmux — `tmux new-session -d -s lit-qa-<criterion>`, drive with
+     `send-keys`, dump via `tmux capture-pane -pS -E -`; transcript
+     is the artifact.
+  3. Browser use — use Chrome to drive the REAL page. Capture action
+     log + screenshot path. Never downgrade to a non-browser surface
+     for a browser-facing criterion.
+  4. Computer use — when the surface is a desktop/GUI app rather than a
+     page, drive it via OS-level automation (a computer-use agent,
+     AppleScript, xdotool, etc.) against the running app; capture
+     action log + screenshot. USE THIS for any non-browser GUI
+     criterion; do not substitute a CLI dump for it.
+
+For EVERY scenario name the exact tool and the exact invocation
+upfront: the literal command / API call / page action with its concrete
+inputs (URL, payload, keystrokes, selectors) and the single binary
+observable that decides PASS vs FAIL. "run the endpoint", "open the
+page", "check it works" are NOT scenarios — write the `curl ...`, the
+`send-keys ...`, the `page.click(...)`, the expected status/text.
+
+Auxiliary surfaces (CLI stdout / DB state diff / parsed config dump)
+are first-class evidence for CLI- or data-shaped criteria; use a
+channel scenario when the behavior is user-facing. `--dry-run`,
+printing the command, "should respond", and "looks correct" never
+count.
+
+# Bootstrap (DO ALL FOUR BEFORE ANY OTHER WORK — NO SKIPPING)
+
+## 0. Survey the skills, then size the work
+First, survey the loaded skill list and read the description of each
+loosely relevant skill. Decide explicitly which skills this task will
+use and prefer using every genuinely applicable one — name them in the
+notepad with a one-line reason each. Skipping a skill that fits the
+task is a defect.
+Then run Tier triage (above) on the change set and record the tier.
+HEAVY: spawn the `litcodex-plan` agent with the gathered context, follow
+its wave order and parallel grouping exactly, and run the verification it
+specifies. LIGHT: plan directly in the notepad.
+
+## 1. Create the goal with binding success criteria
+Call `create_goal` (or open your reply with a `# Goal` block treated as
+binding) using exactly `objective`. Do not include `status`. Goals are
+unlimited; never invent a numeric budget or limit.
+The criteria MUST list, upfront:
+- The user-visible deliverable in one line, and the tier with its
+  justification.
+- Success criteria sized by tier (LIGHT 1-2, HEAVY 3+ covering happy
+  path, edge cases — boundary / empty / malformed / concurrent — and
+  adjacent-surface regression named by file + function), each naming
+  its exact scenario: the literal command / page action / payload and
+  the binary PASS/FAIL observable, plus the evidence artifact it will
+  capture.
+- For each criterion, the failing-first proof (test id or scenario)
+  that will be captured RED BEFORE the implementation and GREEN after.
+  Evidence added after the green code does NOT satisfy this.
+
+These scenarios are the contract. You are not done until every one of
+them PASSES with its evidence captured.
+
+## 2. Open the durable notepad
+Run: `NOTE=$(mktemp -t lit-$(date +%Y%m%d-%H%M%S).XXXXXX.md)`. Echo the
+path. Initialise it with these sections and APPEND (never rewrite) as
+you work:
+
+```
+# Litwork Notepad — <one-line goal>
+Started: <ISO timestamp>
+
+## Plan (exhaustively detailed)
+<every step you will take, in order, broken to atomic actions>
+
+## Success criteria + QA scenarios
+<copied from the goal>
+
+## Now
+<the single step in progress>
+
+## Todo
+<every remaining step, ordered>
+
+## Findings
+<every non-obvious fact discovered, with file:line refs>
+
+## Learnings
+<patterns / pitfalls / principles to remember next turn>
+```
+
+Append each finding, decision, command, RED/GREEN capture, and QA
+artifact path the moment it happens. Update `## Now` and
+`## Todo` on every transition. Append-only — never rewrite. This notepad
+is your durable memory and it OUTLIVES the context window. After any
+compaction or context loss (a `Context compacted` notice, a summarized
+history, or you no longer see your own earlier steps), STOP and re-read
+the WHOLE notepad FIRST — use the `shell` tool to `cat "$NOTE"`, or read
+the path directly — before any other action, then resume from `## Now`.
+Recover state from the notepad; do not re-plan from scratch or re-run
+completed steps.
+
+## 3. Register obsessive todos via `update_plan`
+The todo tool is Codex `update_plan` — your live, user-visible
+checklist. Translate every action from the plan into one `update_plan`
+step — one step per atomic work unit: an edit plus its verification, a
+QA scenario run, a teardown. Keep each step small enough to finish
+within a few tool calls.
+Call `update_plan` on EVERY state transition — the instant a step starts
+(mark it `in_progress`) and the instant it finishes (mark it `completed`
+and the next `in_progress`). Exactly ONE `in_progress` at a time. Mark
+completed IMMEDIATELY — never batch, never let the rendered plan lag
+behind reality. Add newly discovered steps the moment they surface
+instead of waiting for the next pass. Step text encodes WHERE / WHY
+(which criterion it advances) / HOW / VERIFY:
+`path: <action> for <criterion> — verify by <check>`.
+
+GOOD pair (test-first, ordered):
+  `foo.test.ts: Write FAILING case invalid-email→ValidationError for criterion 2 — verify by RED with assertion msg`
+  `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by foo.test.ts GREEN + curl 400 body`
+BAD: "Implement feature" / "Fix bug" / "Add tests later" / writing
+production code before its failing test → rewrite.
+
+# Finding things (lead with these, parallel-flood the first wave)
+Never guess from memory — locate with the right tool, and re-read before
+you claim or change. Fire 3+ independent lookups in one action;
+serialize only when one output strictly feeds the next.
+- Repo-wide inspection, CLI smoke tests, git/history, bounded command
+  output → use the `shell` tool. The shell is your default lens on the
+  tree; inspect a running pane with `capture-pane` only to read an
+  existing pane.
+- Symbols — definitions, references, rename impact, diagnostics →
+  `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`,
+  `lsp_diagnostics`. Use the LSP, not text search, for anything
+  symbol-shaped.
+- Structural shapes — call/function/class/import patterns, codemods →
+  `ast_grep_search` with `$VAR` / `$$$` metavars.
+- Text / strings / comments / logs → `rg`. File-name discovery →
+  `glob` / `find`. Verbatim content → `read`.
+When discovery needs multiple angles or the module layout is
+unfamiliar, delegate to the `litcodex-explorer` subagent (read-only
+codebase search, absolute-path results). For research that leaves the
+repo — library/API/docs/web — delegate to the `litcodex-librarian`
+subagent. Spawn them `fork_context: false` and keep doing root work
+while they run.
+
+# Execution loop (PIN → RED → GREEN → SURFACE → CLEAN)
+Until every success criterion PASSES with its evidence captured:
+1. Pick next criterion → mark in_progress → update notepad `## Now`.
+2. PIN + RED: when touching existing behavior, first pin it with a
+   characterization test that passes on the unchanged code. Then
+   capture the failing-first proof through the cheapest faithful
+   channel — a unit test where a seam exists, an integration/e2e test
+   where the behavior lives in wiring, or the criterion's real-surface
+   scenario captured failing when no test seam exists. It must fail
+   for the RIGHT reason (not a syntax error, not a missing import).
+   Paste RED output into the notepad. No production code yet.
+3. GREEN: write the SMALLEST production change that flips RED→GREEN.
+   Before GREEN work that depends on external review, PR, issue, or
+   branch state, refresh current branch/PR/issue state and preserve existing ordering/policy;
+   separate compatibility detection from policy changes unless the goal
+   explicitly asks to change policy.
+   Re-run the proof. Capture GREEN output. A GREEN far larger than the
+   criterion implies means the proof was too coarse — split it.
+4. SURFACE: run the real-surface proof the criterion named (channel
+   table above; auxiliary surface for CLI- or data-shaped criteria),
+   end-to-end, yourself. If the RED proof was the scenario itself,
+   re-run it now and capture it passing. Paste the artifact path into
+   the notepad.
+5. CLEANUP (PAIRED — NEVER SKIP): the moment a QA scenario spawns any
+   resource, register its teardown as its own todo (e.g.
+   `cleanup: kill server pid for criterion 2 — verify kill -0 fails`).
+   Every runtime artifact the QA spawned in step 4 MUST be torn down
+   before this step completes:
+   server PIDs (`kill <pid>`; verify `kill -0` fails), `tmux` sessions
+   (`tmux kill-session -t lit-qa-<criterion>`; verify with `tmux ls`),
+   browser / Playwright contexts (`.close()`), containers
+   (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp
+   sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env
+   vars. Append a one-line cleanup receipt to the notepad next to the
+   artifact, e.g. `cleanup: killed 12345; tmux kill-session lit-qa-foo;
+   rm -rf /tmp/lit.aB12cD`. No receipt → criterion stays in_progress.
+6. Verify: LSP diagnostics clean on changed files + full test suite
+   green (no skipped, no xfail added this turn).
+7. Mark completed. Append non-obvious findings / learnings.
+8. After each increment, re-run every criterion's scenario. Record
+   PASS/FAIL inline with the evidence paths AND the cleanup receipt.
+   Loop until all PASS.
+
+Parallel-batch independent reads / searches / subagents within a step,
+but NEVER parallelise RED and GREEN of the same criterion.
+
+# Codex subagent reliability
+Every `multi_agent_v1.spawn_agent` message is self-contained and starts with
+`TASK: <imperative assignment>`, then names `DELIVERABLE`, `SCOPE`, and
+`VERIFY`. State that it is an executable assignment, not a context
+handoff. Use `fork_context: false` unless full history is truly
+required; paste only the context the child needs. Full-history forks can
+make the child continue old parent context instead of the delegated task.
+
+# TOML-backed subagent routing compatibility
+Treat TOML-backed role routing as **routing-unverified**. The
+`multi_agent_v1.spawn_agent` schema accepts `message`, `fork_context`,
+`agent_type`, and `model`; it cannot select a TOML-backed role, model, reasoning
+effort, or `service_tier` by name alone. Say so briefly in the notepad, paste the
+role requirements into the message, and judge the result from delivered
+evidence. Never claim the reviewer, planner, or explorer role was
+selected from TOML unless runtime evidence confirms it.
+
+Treat child status as a progress signal, not a timeout counter. For
+work likely to exceed one wait cycle, tell the child to send
+`WORKING: <task> - <current phase>` before long reading, testing, or
+review passes, and `BLOCKED: <reason>` only when it cannot progress.
+Track spawned agent names locally. Use `multi_agent_v1.wait_agent` for mailbox
+signals, but a timeout only means no new mailbox update arrived.
+Treat a running child as alive and keep doing independent root work.
+Fallback only when the child is completed without the
+deliverable, ack-only, or no longer running. If that followup is still
+silent or ack-only, record the result as inconclusive, do not count it
+as approval/pass, close it if safe, and respawn a smaller
+`fork_context: false` task with the missing deliverable.
+
+# Subagent-dependent transition barrier
+Do not mark an `update_plan` step `completed` while an active child owns
+evidence for that step. Do not start dependent implementation until the
+audit, research, or review result is integrated or explicitly recorded
+as inconclusive. Do not generate a plan before spawned research lanes
+that feed the plan have returned or been closed as inconclusive.
+Do not write the final answer, PR handoff, or completion summary while
+active child agents remain open. Use short `multi_agent_v1.wait_agent` cycles.
+After two silent waits send `TASK STILL ACTIVE: return <deliverable> or
+BLOCKED: <reason>`. After four silent or ack-only checks, close the lane as
+inconclusive, record that it is not approval, and respawn smaller only
+if the deliverable is still required.
+
+# Verification gate (TRIGGERED, NOT OPTIONAL)
+
+Trigger when ANY apply:
+- Tier is HEAVY.
+- User demanded strict, rigorous, or proper review.
+LIGHT tier records a self-review in the notepad instead: re-read the
+diff, run diagnostics, confirm each criterion's evidence, and state in
+one line why the tier held.
+
+Procedure (NON-NEGOTIABLE):
+1. Spawn a child with `fork_context: false` and a self-contained reviewer
+   assignment in `message`. The `multi_agent_v1.spawn_agent` schema cannot select a
+   TOML-backed reviewer role, so paste the reviewer requirements into
+   the message. Route this to the `litcodex-momus` reviewer (or the
+   `litcodex-litwork-reviewer` lane) and judge it from delivered evidence.
+   Pass: goal, success-criteria, scenario evidence, full diff, notepad
+   path.
+2. Treat the reviewer's verdict as binding. There is NO "false
+   positive". Every concern is real. Do not argue. Do not minimise. Do
+   not explain it away.
+3. Fix every issue. Re-run the FULL scenario QA. Capture fresh
+   evidence. Update notepad.
+4. Re-submit to the SAME reviewer. Loop until you receive an
+   UNCONDITIONAL approval ("looks good but..." = REJECTION).
+5. Only on unconditional approval may you declare done. Stopping early
+   IS failure.
+
+For design-shaped or critique-heavy verification, the `litcodex-metis`
+agent supplies adversarial design critique; route architecture and
+trade-off concerns there before the reviewer loop closes.
+
+# Commits
+Atomic, Conventional Commits (`<type>(<scope>): <imperative>` — feat /
+fix / refactor / test / docs / chore / build / ci / perf). One logical
+change per commit; each commit builds + tests green on its own. No WIP
+on the final branch. If a plan file exists, final commit footer:
+`Plan: .litcodex/plans/<slug>.md`. Do NOT auto-`git commit` unless the
+user requested or preauthorised this session — default is stage + draft
+message + present for approval.
+
+# Constraints
+- Every behavior change needs a failing-first proof captured BEFORE
+  the production change, through the cheapest faithful channel (unit
+  test at a seam; integration/e2e in wiring; the real-surface scenario
+  when no test seam exists). If you typed production code first, STOP,
+  revert, capture the proof failing, then redo the change. Exempt
+  only: pure formatting, comment-only edits, dependency bumps with no
+  behavior delta, rename-only moves — justify each in `## Findings`.
+- A test that mirrors its implementation — asserting mocks were
+  called, pinning a constant, or unable to fail under any plausible
+  regression — is NOT evidence. Prefer a real-surface proof with no
+  new test over a tautological test.
+- Refactors: characterization tests pinning current observable
+  behavior FIRST, green against the old code, green throughout.
+- Smallest correct change. No drive-by refactors.
+- Never suppress lints / errors / test failures. Never delete, skip,
+  `.only`, `.skip`, `xfail`, or comment out tests to green the suite.
+- Never claim done from inference — only from captured evidence.
+- Parallel tool calls for any independent work.
+
+# Output discipline
+- First line literally: `🔥 LITWORK ENABLED 🔥`
+- After bootstrap: 1-2 paragraph plan summary + notepad path.
+- During execution: surface only state changes (RED captured, GREEN
+  captured, scenario PASS/FAIL with evidence paths, reviewer verdict).
+- Final message: outcome + success-criteria checklist with evidence
+  refs + notepad path + reviewer approval (if gate triggered) + commit
+  list (`<sha> <subject>`). No file-by-file changelog unless asked.
+
+# Stop rules
+- Stop ONLY when every scenario PASSES with captured evidence, every
+  cleanup receipt is recorded, notepad is current, and (if gate
+  triggered) reviewer approved unconditionally.
+- Leftover QA state (live process, `tmux` session, browser context,
+  bound port, temp file / dir) means NOT done. Tear it down, record
+  the receipt, then continue.
+- After 2 identical failed attempts at one step, surface what was tried
+  and ask the user before another retry.
+- After 2 parallel exploration waves yield no new useful facts, stop
+  exploring and act.
+
+</litwork-mode>

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

@@ -0,0 +1 @@
+export declare const SCAFFOLD_PLACEHOLDER: Readonly<{}>;

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

@@ -0,0 +1,3 @@
+// src/_scaffold.ts — scaffold sentinel so composite `include` is non-empty.
+// Removed (or replaced) by the first real module in the owning module's TDD pass.
+export const SCAFFOLD_PLACEHOLDER = Object.freeze({});

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

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Dispatch one argv vector to a route and resolve its exit code. Pure of process.exit; writes only
+ * to the injected streams.
+ */
+export declare function main(argv: readonly string[], stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream): Promise<number>;

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// src/cli.ts — M06-owned component bin dispatcher (A2 §3/§6.4, A3 addendum A1).
+//
+// Bin `litcodex-lit-loop` → dist/cli.js, the target the aggregate hooks.json invokes. Knows exactly
+// two route prefixes — `hook` and `loop` — and NO `config` route (config migration is owned by the
+// separate litcodex-ai installer bin, not this dispatcher).
+//
+// Exit-code table (A3 addendum A1.2):
+//   0  — route ran to completion (hook activation / hook no-op / a loop subcommand that succeeded)
+//   1  — DISPATCHER unknown command (argv[2] not `hook`/`loop`, or `hook` with a second token
+//         ≠ user-prompt-submit, or `loop` with an unknown subcommand). Plain-text stderr, no JSON.
+//   2  — M06 hook route malformed/oversized stdin (LitHookError JSON on stderr; owned by hook-cli).
+//   3/4/5 — M09 loop route (ships at T14).
+//
+// `main` NEVER calls process.exit (the shebang wrapper does); it resolves exactly one integer, so
+// the dispatcher is unit-testable with an injected argv array.
+import { runUserPromptSubmitHookCli } from "./hook-cli.js";
+import { loopCommand } from "./loop-cli.js";
+const UNKNOWN_COMMAND = "lit-loop: unknown command\n";
+/**
+ * Dispatch one argv vector to a route and resolve its exit code. Pure of process.exit; writes only
+ * to the injected streams.
+ */
+export async function main(argv, stdin, stdout, stderr) {
+    const command = argv[2];
+    const subcommand = argv[3];
+    if (command === "hook") {
+        if (subcommand !== "user-prompt-submit") {
+            stderr.write(UNKNOWN_COMMAND);
+            return 1;
+        }
+        return runUserPromptSubmitHookCli(stdin, stdout, stderr);
+    }
+    if (command === "loop") {
+        // T14: route to M09's loopCommand (argv past `loop`); it resolves one exit code (0/1/2/3/4/5)
+        // and never calls process.exit. The `doctor` subcommand is still the M09 stub until M11/T16.
+        return loopCommand(argv.slice(3), { stdout, stderr, stdin });
+    }
+    stderr.write(UNKNOWN_COMMAND);
+    return 1;
+}
+main(process.argv, process.stdin, process.stdout, process.stderr).then((code) => {
+    process.exit(code);
+});

package/node_modules/@litcodex/lit-loop/dist/codex-goal-instruction.d.ts

@@ -0,0 +1,18 @@
+import type { LoopGoal, LoopGoalStatus, LoopPlan } from "./loop-types.js";
+export interface CodexCreateGoalPayload {
+    readonly objective: string;
+}
+export interface LitLoopGoalInstruction {
+    readonly text: string;
+    readonly json: CodexCreateGoalPayload;
+}
+export declare function buildCodexGoalInstruction(args: {
+    readonly plan: LoopPlan;
+    readonly goal: LoopGoal;
+    readonly isFinal?: boolean;
+}): LitLoopGoalInstruction;
+export declare function buildCodexGoalCheckpoint(args: {
+    readonly plan: LoopPlan;
+    readonly goal: LoopGoal;
+    readonly status: LoopGoalStatus;
+}): string;

package/node_modules/@litcodex/lit-loop/dist/codex-goal-instruction.js

@@ -0,0 +1,94 @@
+// src/codex-goal-instruction.ts — Codex native-goal handoff instruction builder.
+//
+// Builds the `create_goal` / `update_goal` instruction text and JSON payload that lit-loop's
+// handleRun and handleCheckpoint append to their output so the agent keeps Codex's `/goal`
+// surface in sync with the active lit-loop goal. Per-story model only (one Codex goal per
+// lit-loop goal). Pure — no I/O, no store, no clock.
+import { expectedCodexObjective, isFinalRunCompletionCandidate, isLitLoopDone } from "./goal-status.js";
+export function buildCodexGoalInstruction(args) {
+    const { plan, goal } = args;
+    const json = { objective: expectedCodexObjective(goal) };
+    const isFinal = args.isFinal ?? isFinalRunCompletionCandidate(plan, goal);
+    const text = buildText(plan, goal, json, isFinal);
+    return { text, json };
+}
+function buildText(plan, goal, payload, isFinal) {
+    return joinLines([
+        "lit-loop Codex goal handoff",
+        `Plan: ${plan.goalsPath}`,
+        `Ledger: ${plan.ledgerPath}`,
+        `Goal: ${goal.id} — ${goal.title}`,
+        "",
+        ...activeGoalLines(goal),
+        "",
+        ...successCriteriaLines(goal),
+        "",
+        "Codex goal integration constraints:",
+        "- Use the create_goal payload exactly as rendered: objective only.",
+        "- Goals are unlimited. Do not add numeric limits.",
+        "- First call get_goal. If no active goal exists, call create_goal with the payload below.",
+        "- If get_goal already reports this objective as active, continue without creating a new goal.",
+        "- If a different active Codex goal exists, finish or clear it (`/goal clear`) before starting this lit-loop goal.",
+        "- Work only this goal until all criteria pass.",
+        ...finalLines(goal, isFinal),
+        ...checkpointLines(),
+        "",
+        "create_goal payload:",
+        JSON.stringify(payload, null, 2),
+    ]);
+}
+function activeGoalLines(goal) {
+    return ["Active goal:", `- id: ${goal.id}`, `- title: ${goal.title}`, `- objective: ${goal.objective}`];
+}
+function successCriteriaLines(goal) {
+    if (goal.successCriteria.length === 0)
+        return ["Success criteria:", "- No success criteria recorded for this goal."];
+    return [
+        "Success criteria:",
+        ...goal.successCriteria.map((c) => {
+            const remaining = c.status === "pending" ? " remaining work:" : "";
+            return `-${remaining} [${c.id}] (${c.userModel}) ${c.scenario} — expect: ${c.expectedEvidence} — status: ${c.status}`;
+        }),
+    ];
+}
+function finalLines(goal, isFinal) {
+    if (!isFinal) {
+        return ["- This is not the final lit-loop goal; leave the Codex goal active for the next run."];
+    }
+    return [
+        "- This is the final lit-loop goal. After all criteria pass and checkpoint is complete:",
+        `  1. litcodex loop checkpoint --goal-id ${goal.id} --status complete --evidence "<summary>"`,
+        '  2. Call update_goal({status: "complete"}) to mark the Codex goal done.',
+        "  3. Run `/goal clear` to close the Codex goal surface.",
+    ];
+}
+function checkpointLines() {
+    return [
+        "- If blocked or failed, checkpoint with the failure evidence; rerun with `litcodex loop run --retry-failed` to resume.",
+    ];
+}
+// ── checkpoint handoff ──────────────────────────────────────────────────────
+export function buildCodexGoalCheckpoint(args) {
+    const { plan, goal, status } = args;
+    if (status === "complete") {
+        const lines = [
+            "Codex goal checkpoint:",
+            `Goal ${goal.id} is complete. Call update_goal({status: "complete"}) to mark the Codex goal done.`,
+        ];
+        if (isLitLoopDone(plan)) {
+            lines.push("All lit-loop goals are now complete. Run `/goal clear` to close the Codex goal surface.");
+        }
+        else {
+            lines.push("Run `litcodex loop run` to hand off the next goal.");
+        }
+        return joinLines(lines);
+    }
+    return joinLines([
+        "Codex goal checkpoint:",
+        `Goal ${goal.id} is ${status}. The Codex goal remains active.`,
+        "Resume via `litcodex loop run --retry-failed` when ready.",
+    ]);
+}
+function joinLines(lines) {
+    return lines.join("\n");
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Accepted stdin event shape AFTER JSON.parse. The declared canonical wire form is snake_case;
+ * `isLitUserPromptSubmitInput` additionally accepts the camelCase event-name/transcript keys at
+ * runtime (A3 C12). Extra fields (cwd, model, session_id, …) are tolerated and ignored.
+ */
+export interface LitUserPromptSubmitInput {
+    readonly hook_event_name: "UserPromptSubmit";
+    readonly prompt: string;
+    readonly transcript_path?: string | null;
+}
+/** Structured engine result. The CLI maps this to stdout / exit. */
+export type HookDecision = {
+    readonly kind: "inject";
+    readonly stdout: string;
+} | {
+    readonly kind: "noop";
+};
+/**
+ * Type-guard. True iff `value` is a record whose accepted event-name key (snake `hook_event_name`
+ * primary, camel `hookEventName` fallback) === "UserPromptSubmit", `prompt` is a string, and the
+ * transcript-path key (either casing) is undefined | null | string (A3 C12). This is a runtime
+ * accept-set, not a structural type assert, so a camelCase-keyed record also returns true.
+ */
+export declare function isLitUserPromptSubmitInput(value: unknown): value is LitUserPromptSubmitInput;
+/**
+ * Wraps directive text in the Codex output envelope. Returns "" if the normalized context is empty
+ * (caller treats "" as noop). Output is a single-line JSON + trailing "\n":
+ * {"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":<ctx>}}\n
+ */
+export declare function formatAdditionalContextOutput(additionalContext: string): string;
+/**
+ * Pure decision function (multi-mode router). Takes an already-parsed value (NOT a raw string).
+ * Total over `unknown`; NEVER throws. Flow: validate shape → match the lit-family trigger token
+ * (guard 0) → resolve the mode → run guards 1-3 against the MATCHED mode's marker (RC1) → load that
+ * mode's directive fail-silent. Returns { kind:"noop" } for a wrong-shape value, no trigger, a guard
+ * veto, or a fail-silent empty directive; { kind:"inject", stdout } only on a real activation.
+ */
+export declare function runUserPromptSubmitHook(input: unknown): HookDecision;