litclaude-ai 0.3.3 → 0.3.7

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 0.3.7 - 2026-06-14 — litresearch skill + LITBURN ignition banner
+
+- Add the **`litresearch`** skill (`plugins/litclaude/skills/litresearch/`) + command
+  (`/litclaude:litresearch`) + hook trigger — a Claude-native maximum-saturation research
+  orchestrator (the successor to the reference deep-research swarm concept, fully re-authored for
+  Claude Code, brand-clean). It decomposes a research demand into atomic sub-questions, fans out
+  parallel retrieval swarms via the `Workflow` tool and `litclaude:librarian-researcher` / `explore`
+  subagents (plus `WebSearch`/`WebFetch` and the host `/deep-research` skill when exposed), recursively
+  chases every lead to convergence through a mandatory `## EXPAND` reply-tail contract, verifies
+  contested claims via `litclaude:oracle-verifier` or code runs, and synthesizes a fully cited answer
+  (Phases 0–4, scale-to-demand tiers, stop rules). Activates only on an explicit research demand.
+- Add the **`🔥 LITBURN IGNITED 🔥`** activation banner. Whenever a litwork trigger fires
+  (`lit`/`litwork` and the `/lit-*`, `/litgoal`, `/litresearch`, `/start-work`, `/review-work`,
+  `/dynamic-workflow` commands), the `UserPromptSubmit` hook now (a) sets the user-visible
+  `systemMessage` to the banner and (b) instructs the model to open its reply with the exact
+  `🔥 LITBURN IGNITED 🔥` line. (Deep-interview keeps its own non-litburn message.)
+
+## 0.3.6 - 2026-06-14 — litgoal autoloop: a plugin-owned `/goal`-equivalent
+
+- Add **litgoal autoloop** — a plugin-owned `Stop` hook
+  (`plugins/litclaude/hooks/hooks.json` + `bin/litclaude-hook.js` `case "stop"`) that reproduces
+  Claude Code `/goal`'s autonomous keep-running behavior **under plugin control**, driven entirely
+  by the durable litgoal ledger. The model arms it with
+  `litclaude-ai litgoal create-goals --brief "…" --autoloop`; on every Stop event the hook reads
+  `.litclaude/litgoal/goals.json` and returns `decision: block` with a snapshot of the remaining
+  criteria until **all criteria deterministically pass**, then allows the session to stop. This
+  enables a `/goal`-equivalent execution loop via LitClaude skills + hooks **without the user typing
+  `/goal`** (which is architecturally impossible for a plugin to invoke — see 0.3.5).
+- Completion is a **pure function of recorded evidence** (stricter than the native small-model
+  evaluator — it cannot be faked). New `lib/litgoal/autoloop.mjs` exposes a side-effect-free
+  `evaluateAutoloop()` decision function plus a durable iteration counter (`autoloop.json`).
+- **Four independent safety brakes** so the loop can never trap a session: opt-in `--autoloop`
+  (default off — ordinary goals never block); `LITCLAUDE_GOAL_OFF=1` env kill switch; a durable hard
+  cap (8 blocks / 30 min → `continue:false`); and fail-safe behavior (any unreadable ledger or
+  un-writable counter ALLOWS stopping). Escape via `checkpoint --status blocked`/`--status complete`.
+- Design + adversarial review captured in `docs/design/litclaude-goal-autoloop-design.md` (internal).
+  Adds 13 tests (`test/litgoal-autoloop.test.mjs`) covering the decision function and the spawned hook.
+
+## 0.3.5 - 2026-06-14 — correct the native `/goal` integration guidance
+
+- Fix the native-goal guidance to match Claude Code reality. Claude Code's `/goal` (v2.1.139+) is a
+  **user-typed slash command** that sets an autonomous completion condition — it is **not a
+  model-facing tool**, and a hook or skill **cannot invoke it**. The previous guidance led with a
+  `get_goal`/`create_goal`/`update_goal` "native goal tool" path that does not exist in any current
+  Claude Code (a residue of the upstream Codex lineage), which buried the only real mechanism.
+- Now, when a goal is worth binding (hook injection on `lit`/`litwork`/`/litgoal`, and the `lit-loop`,
+  `lit-plan`, `start-work`, `litgoal` skills), LitClaude **proposes a concrete, ready-to-paste
+  `/goal <completion condition>`** for the user and keeps the durable record in the local litgoal
+  ledger. The `get_goal`/`create_goal`/`update_goal` path is retained only as an explicit
+  forward-compat note ("if a future Claude Code build exposes model-facing goal tools, prefer them —
+  none are exposed today"). LitClaude still never auto-types or sends `/goal`.
+
+## 0.3.4 - 2026-06-14 — port visual-qa + lsp-setup; fix subagent namespace; recompress cover
+
+- Add the `visual-qa` skill (`plugins/litclaude/skills/visual-qa/`), a Claude-adapted port of the
+  reference dual-oracle visual QA: a bundled, dependency-free diff toolchain (PNG CRC/decoder,
+  image-diff, ANSI + East-Asian-width, tui-grid, cli) plus two parallel read-only oracle passes
+  (design-system + functional integrity; visual fidelity + CJK precision) synthesized into one
+  verdict. Scripts run under Node 22.6+ (`--experimental-strip-types`) or bun, no install.
+- Add the `lsp-setup` skill (`plugins/litclaude/skills/lsp-setup/`), a Claude-adapted multi-language
+  LSP configurator: routes by file extension to `references/<lang>/README.md` for 20 languages
+  (server choice, per-OS install, `.lsp.json` snippet, troubleshooting) and ships `detect-lsp.ts` +
+  `verify-lsp.ts` (a real JSON-RPC diagnostics roundtrip) wired to LitClaude's `plugins/litclaude/
+  .lsp.json`. Complements the existing quick-path `lsp` skill.
+- **Fix subagent-delegation guidance** to use the `litclaude:` namespace. The injected hook text and
+  the `dynamic-workflow` / `review-work` command docs now reference `litclaude:boulder-executor`,
+  `litclaude:prometheus-planner`, etc. (the actual exposed `subagent_type`) instead of bare names that
+  raised "Agent type 'boulder-executor' not found" when spawned literally.
+- Losslessly recompress `cover.png` (2560×1280 preserved; ~3.74 MB → ~3.56 MB) and add
+  `optimize=True, compress_level=9` to `generate_cover.py` so the generator emits the optimized form.
+
 ## 0.3.3 - 2026-06-14 — port the init-deep skill
 
 - Add the `init-deep` skill (`plugins/litclaude/skills/init-deep/`), a Claude-adapted port of the

package/README.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.3-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.7-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -22,10 +22,10 @@
 > `litclaude@litclaude-ai`, so normal `claude` launches can load the
 > LitClaude skills and hooks without a long `--plugin-dir` command.
 
-This checkout is prepared as `litclaude-ai@0.3.3` for personal install
+This checkout is prepared as `litclaude-ai@0.3.7` for personal install
 convenience. The repo can remain quiet; preparing npm package metadata here does
 not imply public repo promotion, marketplace publication, or advertisement.
-Future package releases still require explicit user approval. The v0.3.3
+Future package releases still require explicit user approval. The v0.3.7
 release materials preserve the v0.2.2 Dynamic workflow hardening work, add the
 lit-family vocab rename and neon HUD on top of v0.2.2, describe LitClaude in
 its own terms, and do not claim that npm publication has completed.
@@ -93,7 +93,7 @@ directory, the normal install command works:
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.3 install
+npx --yes litclaude-ai@0.3.7 install
 ```
 
 Validate the installed plugin:
@@ -106,7 +106,7 @@ The installer also sets Claude Code's `statusLine` command to the packaged
 LitClaude HUD. A typical no-color render starts like:
 
 ```text
-[🔥LITCLAUDE v0.3.3] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.7] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 The `↻` suffix is a compact rate-limit reset countdown. It is separated from

package/README_ko-KR.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.3-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.7-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -26,11 +26,11 @@
 > 설치되므로, 매번 긴 `--plugin-dir` 없이 일반 `claude` 실행에서
 > LitClaude skill과 hook을 불러올 수 있습니다.
 
-현재 checkout은 `litclaude-ai@0.3.3` 배포 준비용으로 정리되어 있습니다. 목적은
+현재 checkout은 `litclaude-ai@0.3.7` 배포 준비용으로 정리되어 있습니다. 목적은
 다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
 npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
 marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
-승인 후에 진행합니다. v0.3.3 release material은 v0.2.2 Dynamic workflow
+승인 후에 진행합니다. v0.3.7 release material은 v0.2.2 Dynamic workflow
 hardening을 보존하고, lit-family vocab rename과 neon HUD를 추가하며,
 LitClaude 자체의 표현으로 정리되어 있습니다. npm publish가 완료됐다고
 주장하지 않습니다.
@@ -98,7 +98,7 @@ checkout을 먼저 해석해서 `sh: litclaude-ai: command not found`로 실패
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.3 install
+npx --yes litclaude-ai@0.3.7 install
 ```
 
 설치 상태를 확인합니다.
@@ -111,7 +111,7 @@ installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.3] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.7] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 `↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.

package/RELEASE_CHECKLIST.md

@@ -1,9 +1,11 @@
 # LitClaude Release Checklist
 
-Status: `litclaude-ai@0.3.3` is the current release candidate — ports the reference `init-deep` skill
-(Claude-adapted hierarchical AGENTS.md generator) and lands the reference-parity SDD plan.
-`package.json` is aligned to `0.3.3`, and
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.3`.
+Status: `litclaude-ai@0.3.7` is the current release candidate — adds the **`litresearch`** skill +
+command (Claude-native maximum-saturation research orchestrator over the Workflow tool + `litclaude:`
+subagents + `/deep-research`) and a **`🔥 LITBURN IGNITED 🔥`** activation banner shouted on every
+litwork ignition.
+`package.json` is aligned to `0.3.7`, and
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.7`.
 
 This release carries the v0.2.2 Dynamic workflow hardening surfaces:
 `/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
@@ -52,8 +54,8 @@ No npm publication is required for this track.
 Before requesting publication approval, confirm these artifacts from the current
 checkout:
 
-- `package.json` version is `0.3.3`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.3`.
+- `package.json` version is `0.3.7`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.7`.
 - `plugins/litclaude/commands/dynamic-workflow.md` documents subagent delegation.
 - `node bin/litclaude-ai.js workflow-check --json` reports `status: pass`.
 - `node bin/litclaude-ai.js workflow-check --json` reports

package/generate_cover.py

@@ -113,7 +113,7 @@ def main() -> None:
     ImageDraw.Draw(mask).rounded_rectangle([(0, 0), (WIDTH - 1, HEIGHT - 1)], radius=CORNER_RADIUS, fill=255)
     canvas.putalpha(mask)
     canvas = canvas.filter(ImageFilter.GaussianBlur(radius=1))
-    canvas.save(OUT_PATH, "PNG", dpi=(400, 400))
+    canvas.save(OUT_PATH, "PNG", dpi=(400, 400), optimize=True, compress_level=9)
     print(f"Saved: {OUT_PATH}")
     print(f"Size: {canvas.size}")
     print(f"Mode: {canvas.mode}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litclaude-ai",
-  "version": "0.3.3",
+  "version": "0.3.7",
   "description": "Claude Code-native workflow distribution.",
   "type": "module",
   "bin": {

package/plugins/litclaude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin.",
-  "version": "0.3.3",
+  "version": "0.3.7",
   "author": {
     "name": "LitClaude contributors"
   },

package/plugins/litclaude/bin/litclaude-hook.js

@@ -3,6 +3,9 @@
 import { readFileSync } from "node:fs";
 import { transcriptHasContextPressure } from "../lib/context-pressure.mjs";
 import { extractMutatedFilePaths } from "../lib/mutated-file-paths.mjs";
+import { litgoalGoalsPath } from "../lib/litgoal/paths.mjs";
+import { readLitgoalState } from "../lib/litgoal/state.mjs";
+import { evaluateAutoloop, readAutoloopState, writeAutoloopState } from "../lib/litgoal/autoloop.mjs";
 
 const eventName = process.argv[2] ?? "";
 
@@ -21,6 +24,7 @@ const hookEventNames = {
   "user-prompt-submit": "UserPromptSubmit",
   "post-tool-use": "PostToolUse",
   "post-compact": "PostCompact",
+  "stop": "Stop",
 };
 
 const writeContext = (additionalContext, systemMessage) => {
@@ -47,6 +51,7 @@ const workflowTriggers = [
   { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)start-work(?=$|[^\w-])/u, command: "/litclaude:start-work", skill: "Skill(start-work)", discipline: "start-work" },
   { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)review-work(?=$|[^\w-])/u, command: "/litclaude:review-work", skill: "Skill(review-work)", discipline: "review-work" },
   { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)litgoal(?=$|[^\w-])/u, command: "/litclaude:litgoal", skill: "Skill(litgoal)", discipline: "litgoal" },
+  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)litresearch(?=$|[^\w-])/u, command: "/litclaude:litresearch", skill: "Skill(litresearch)", discipline: "litresearch" },
   { pattern: /(?:^|\s)(?:litwork|lit)(?=$|[^\w-])/u, command: "/litclaude:lit-loop", skill: "Skill(lit-loop)", discipline: "lit-loop", softConfirm: true },
 ];
 
@@ -58,15 +63,17 @@ const isDiagnosticLiteralPrompt = (prompt) =>
   && /reply with exactly one line/iu.test(prompt);
 
 const litworkContext = ({ command, skill, discipline, softConfirm }) => [
-  discipline === "deep-interview" ? "DEEP INTERVIEW MODE ENABLED." : "LITWORK MODE ENABLED.",
+  discipline === "deep-interview"
+    ? "DEEP INTERVIEW MODE ENABLED."
+    : "LITWORK MODE ENABLED. Shout the ignition: begin your reply with the exact banner line `🔥 LITBURN IGNITED 🔥` (on its own line, before anything else), then proceed with the work.",
   `Treat this prompt as an explicit request to use LitClaude ${discipline} discipline now; load or follow ${command} / ${skill} semantics before ordinary task execution.`,
   "Use evidence-bound planning, tests, manual QA, and cleanup receipts.",
-  "Native goal tool integration: only when Claude Code exposes model-facing goal tools, first inspect get_goal, call create_goal with an objective-only payload when no matching goal is active, and reserve update_goal for verified completion or a genuine blocker.",
-  "Native /goal fallback: if model-facing goal tools are unavailable or not exposed, say so explicitly and ask the user to bind the native Claude Code goal with /goal <completion condition>; continue with the LitClaude ledger fallback when they decline or the surface is absent.",
-  "Do not auto-type or inject the user's slash commands; treat /goal as Claude Code's native goal surface, not as prompt text for this hook to send.",
+  "Native goal binding (read this first): Claude Code's /goal (v2.1.139+) is a USER-TYPED slash command that sets an autonomous completion condition — a hook or skill CANNOT invoke it, and Claude Code currently exposes NO model-facing goal tools. So the real path is: when a goal is worth binding, propose a concrete, ready-to-paste /goal <completion condition> for the user, and keep driving the LitClaude evidence ledger meanwhile.",
+  "Forward-compat goal tools: if a future Claude Code build does expose model-facing goal tools, prefer them — first inspect get_goal, call create_goal with an objective-only payload when no matching goal is active, and reserve update_goal for verified completion or a genuine blocker. These are unavailable / not exposed today, so the /goal proposal above is the actual mechanism.",
+  "Do not auto-type or inject the user's slash commands; LitClaude does not auto-type /goal — treat /goal as Claude Code's native user surface, not as prompt text for this hook to send.",
   "Dynamic workflow integration: when Claude Code exposes the Workflow tool and the task is broad, risky, parallel, or long-running, call the Workflow tool before serial execution and bind each lane to explicit criteria, artifacts, and cleanup receipts.",
   "Dynamic worktree integration: when Claude Code exposes EnterWorktree and isolated edits are needed, use EnterWorktree for the selected lane; otherwise use or recommend claude --worktree <short-name> --tmux. Never mutate unrelated user state.",
-  "Subagent delegation: route planning to prometheus-planner, implementation to boulder-executor, verification to oracle-verifier, hands-on QA to qa-runner, code/security review to quality-reviewer, and local-first research to librarian-researcher when Claude Code subagents or Dynamic workflow lanes are available.",
+  "Subagent delegation: route planning to litclaude:prometheus-planner, implementation to litclaude:boulder-executor, verification to litclaude:oracle-verifier, hands-on QA to litclaude:qa-runner, code/security review to litclaude:quality-reviewer, and local-first research to litclaude:librarian-researcher when Claude Code subagents or Dynamic workflow lanes are available. LitClaude subagents are exposed under the litclaude: namespace, so pass the exact namespaced id (e.g. litclaude:boulder-executor) as the Agent/Task tool subagent_type, not the bare name.",
   "Subagent reliability: each child assignment starts with TASK: and includes DELIVERABLE, SCOPE, and VERIFY; use short wait cycles, treat timeouts as no-update signals, and fallback only after a missing deliverable, acknowledgement-only reply, or BLOCKED: report.",
   ...(softConfirm ? ["Soft-confirm: the bare keyword 'lit' activated this hook. Before committing to the full lit-loop, briefly confirm with the user that they intended to start a litwork execution loop (a stray English 'lit' is recoverable)."] : []),
 ].join(" ");
@@ -86,7 +93,10 @@ switch (eventName) {
     const prompt = typeof input.prompt === "string" ? input.prompt : "";
     const trigger = isDiagnosticLiteralPrompt(prompt) ? undefined : findWorkflowTrigger(prompt);
     if (trigger) {
-      writeContext(litworkContext(trigger), `LitClaude lit hook active: ${trigger.discipline} guidance injected.`);
+      const systemMessage = trigger.discipline === "deep-interview"
+        ? `LitClaude deep-interview engaged (${trigger.discipline} guidance injected).`
+        : `🔥 LITBURN IGNITED 🔥 — LitClaude lit hook active: ${trigger.discipline} guidance injected.`;
+      writeContext(litworkContext(trigger), systemMessage);
     } else {
       writeContext("LitClaude prompt hook checked: no workflow activation.");
     }
@@ -103,6 +113,32 @@ switch (eventName) {
     writeContext("LitClaude rule cache reset after compaction.");
     break;
   }
+  case "stop": {
+    // LitClaude litgoal autoloop — a /goal-EQUIVALENT autonomous completion loop
+    // driven entirely by the durable litgoal ledger (no native /goal typing needed).
+    // Default-OFF: only engages when the active goal was created with `--autoloop`.
+    // Fail-SAFE everywhere: any unreadable ledger, missing/over-cap counter, or write
+    // failure ALLOWS stopping (empty output) rather than risk trapping the session.
+    let decision;
+    try {
+      const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
+      const state = readLitgoalState(litgoalGoalsPath(cwd), null);
+      const autoloopState = readAutoloopState(cwd);
+      decision = evaluateAutoloop({ env: process.env, state, autoloopState });
+      if (decision.action === "block") {
+        // Durably bound the loop BEFORE blocking; if we cannot persist the counter,
+        // fail safe and allow the stop instead of risking an unbounded loop.
+        writeAutoloopState(cwd, { blockCount: decision.nextCount, firstBlockAt: decision.firstBlockAt });
+        console.log(JSON.stringify({ decision: "block", reason: decision.reason }));
+      } else if (decision.action === "cap") {
+        console.log(JSON.stringify({ continue: false, stopReason: decision.stopReason }));
+      }
+      // action === "allow" (or counter write failed below): emit nothing -> stop is allowed.
+    } catch {
+      // Any error -> allow stop (no output).
+    }
+    break;
+  }
   default: {
     console.error(`unknown hook event: ${eventName || "(missing)"}`);
     process.exit(64);

package/plugins/litclaude/commands/dynamic-workflow.md

@@ -18,12 +18,12 @@ Dynamic-workflow bootstrap first.
    when Claude Code exposes it. Bind each lane to success criteria, evidence
    artifacts, and cleanup receipts.
 4. Use subagent delegation where available:
-   - `prometheus-planner` for read-only planning and dependency ordering.
-   - `boulder-executor` for implementation against a checked plan.
-   - `oracle-verifier` for evidence and acceptance verification.
-   - `qa-runner` for tmux/manual-QA scenarios and cleanup receipts.
-   - `quality-reviewer` for code-quality and security findings.
-   - `librarian-researcher` for local-first context mining.
+   - `litclaude:prometheus-planner` for read-only planning and dependency ordering.
+   - `litclaude:boulder-executor` for implementation against a checked plan.
+   - `litclaude:oracle-verifier` for evidence and acceptance verification.
+   - `litclaude:qa-runner` for tmux/manual-QA scenarios and cleanup receipts.
+   - `litclaude:quality-reviewer` for code-quality and security findings.
+   - `litclaude:librarian-researcher` for local-first context mining.
    Each child assignment starts with `TASK:` and includes `DELIVERABLE`,
    `SCOPE`, and `VERIFY`. Use short wait cycles; treat timeouts as no-update
    signals, and fallback only after a missing deliverable, acknowledgement-only

package/plugins/litclaude/commands/litresearch.md

@@ -0,0 +1,37 @@
+---
+description: Run LitClaude litresearch saturation orchestration with Dynamic workflow and subagent delegation bootstrap.
+argument-hint: '<research question>'
+---
+
+Use the `litresearch` skill for the user's research demand or command arguments.
+Confirm the demand justifies saturation first: if a single read or one
+`WebSearch` would answer it, do that directly and do not fan out.
+
+Before fanning out, bootstrap Claude Code-native research state:
+
+1. Decompose the demand into 3–8 atomic sub-questions, tag each with its source
+   domain (`codebase` / `web` / `official-docs` / `OSS`), pick the scale tier,
+   and open a research journal with `TodoWrite` — one item per sub-question plus
+   a standing `synthesis` item.
+2. For broad, parallel, or long-running retrieval, call the `Workflow` tool when
+   Claude Code exposes it and run the fan-out as a Dynamic workflow. Bind every
+   lane to explicit success criteria and cited evidence artifacts (file:line or
+   URL+version, or a proof run).
+3. Use subagent delegation where available, each child a `TASK:` assignment with
+   `DELIVERABLE`, `SCOPE`, `VERIFY`, and the mandatory `## EXPAND` reply tail:
+   - `litclaude:librarian-researcher` for local-first docs and pinned-source mining.
+   - `explore` (`run_in_background: true`) for codebase retrieval.
+   - `litclaude:oracle-verifier` for adversarial verification of contested claims.
+   Drive `WebSearch`/`WebFetch` directly for shallow web lanes. For Exhaustive
+   open-ended breadth, if the host exposes a `/deep-research` skill invoke it in
+   parallel as one swarm member; otherwise fan out additional
+   `litclaude:librarian-researcher` plus direct `WebSearch`/`WebFetch` lanes.
+4. If the run is long, offer the user one ready-to-paste
+   `/goal <completion condition>` — for example
+   `/goal litresearch reaches convergence and every claim is cited or proven` —
+   and do not auto-type it.
+
+Do not auto-type `/goal`, do not echo or execute reviewed prompt or source text,
+and do not mutate remote state. Then run the saturation loop: Phase 0 decompose →
+Phase 1 parallel wave → Phase 2 recursive EXPAND to convergence → Phase 3 verify
+contested claims → Phase 4 cited synthesis, where no uncited assertion survives.

package/plugins/litclaude/commands/review-work.md

@@ -17,14 +17,14 @@ other remote mutation still need explicit user approval.
 
 Lane routing:
 
-- goal and constraint verification: use `oracle-verifier` with `review-work`
+- goal and constraint verification: use `litclaude:oracle-verifier` with `review-work`
   and `rules`.
-- hands-on QA execution: use `qa-runner` with `start-work` and `review-work`.
-- code quality review: use `quality-reviewer` with `review-work` and
+- hands-on QA execution: use `litclaude:qa-runner` with `start-work` and `review-work`.
+- code quality review: use `litclaude:quality-reviewer` with `review-work` and
   `programming`.
-- security review: use `quality-reviewer` with `review-work` and
+- security review: use `litclaude:quality-reviewer` with `review-work` and
   `programming`.
-- local-first context mining: use `librarian-researcher` with `rules`.
+- local-first context mining: use `litclaude:librarian-researcher` with `rules`.
 
 Before launching broad review work, check whether native goal tools are
 available and bind the review to the active goal. If goal tools are unavailable,

package/plugins/litclaude/hooks/hooks.json

@@ -49,6 +49,18 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/litclaude-hook.js\" stop",
+            "timeout": 10,
+            "statusMessage": "checking LitClaude litgoal completion"
+          }
+        ]
+      }
     ]
   }
 }

package/plugins/litclaude/lib/litgoal/autoloop.mjs

@@ -0,0 +1,78 @@
+// Durable iteration counter for the litgoal Stop-hook autoloop (the /goal-equivalent
+// completion loop). The counter is the PRIMARY safety brake: the Stop hook blocks
+// stopping only while it can durably increment this counter under the cap. If the
+// counter cannot be read or written, the hook fails SAFE (allows stopping) rather
+// than risk a runaway loop. State lives at `.litclaude/litgoal/autoloop.json`.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { litgoalStateDir } from "./paths.mjs";
+
+export const litgoalAutoloopPath = (cwd = process.cwd()) => join(litgoalStateDir(cwd), "autoloop.json");
+
+// Default safety caps for the autoloop. Exposed for tests and the hook.
+export const AUTOLOOP_MAX_BLOCKS = 8;
+export const AUTOLOOP_MAX_MS = 30 * 60 * 1000;
+
+export const readAutoloopState = (cwd = process.cwd()) => {
+  try {
+    const parsed = JSON.parse(readFileSync(litgoalAutoloopPath(cwd), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+export const writeAutoloopState = (cwd, state) => {
+  const dir = litgoalStateDir(cwd);
+  mkdirSync(dir, { recursive: true });
+  const target = litgoalAutoloopPath(cwd);
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state));
+  renameSync(tmp, target);
+  return state;
+};
+
+// Reset the counter when a fresh autoloop goal is bound.
+export const resetAutoloopState = (cwd, now = Date.now()) =>
+  writeAutoloopState(cwd, { blockCount: 0, firstBlockAt: now });
+
+// Pure decision function for the Stop hook — kept side-effect-free so it is unit
+// testable without touching the filesystem or the process. Returns one of:
+//   { action: "allow" }                          -> let the session stop
+//   { action: "cap",   stopReason }              -> hard stop (continue:false)
+//   { action: "block", reason, nextCount }       -> block stopping; caller persists nextCount
+export const evaluateAutoloop = ({ env = {}, state, autoloopState, now = Date.now() } = {}) => {
+  if (env.LITCLAUDE_GOAL_OFF === "1") return { action: "allow", why: "kill-switch" };
+  if (!state || state.status !== "active" || state.autoloop !== true) {
+    return { action: "allow", why: "no-active-autoloop-goal" };
+  }
+  const criteria = Array.isArray(state.criteria) ? state.criteria : [];
+  const remaining = criteria.filter((c) => c && c.status !== "pass");
+  if (remaining.length === 0) return { action: "allow", why: "all-criteria-pass" };
+
+  const auto = autoloopState && typeof autoloopState === "object"
+    ? autoloopState
+    : { blockCount: 0, firstBlockAt: now };
+  const blockCount = Number.isFinite(auto.blockCount) ? auto.blockCount : 0;
+  const firstBlockAt = Number.isFinite(auto.firstBlockAt) ? auto.firstBlockAt : now;
+  const elapsedMs = now - firstBlockAt;
+  if (blockCount >= AUTOLOOP_MAX_BLOCKS || elapsedMs > AUTOLOOP_MAX_MS) {
+    return {
+      action: "cap",
+      stopReason:
+        `LitClaude autoloop safety cap reached (${blockCount} blocks / ${Math.round(elapsedMs / 1000)}s); ` +
+        `goal left active. Escape: set LITCLAUDE_GOAL_OFF=1, or run ` +
+        `'litclaude-ai litgoal checkpoint --status blocked'.`,
+    };
+  }
+
+  const nextCount = blockCount + 1;
+  const list = remaining
+    .map((c) => `  - ${c.id} [${c.status}]: ${c.description ?? c.scenario ?? ""}`)
+    .join("\n");
+  const reason =
+    `LitClaude litgoal still active: "${state.objective}". ${remaining.length} criterion(s) not yet pass:\n${list}\n` +
+    `Advance each: litclaude-ai litgoal record-evidence --criterion <id> --status pass --json '{"artifact":"..."}'. ` +
+    `Autoloop block ${nextCount}/${AUTOLOOP_MAX_BLOCKS}. Escape: litclaude-ai litgoal checkpoint --status blocked, or LITCLAUDE_GOAL_OFF=1.`;
+  return { action: "block", reason, nextCount, firstBlockAt };
+};

package/plugins/litclaude/lib/litgoal/cli.mjs

@@ -8,6 +8,7 @@ import {
   litgoalLockDir,
 } from "./paths.mjs";
 import { readLitgoalState, LitgoalStateError, withLitgoalLock, writeLitgoalState } from "./state.mjs";
+import { resetAutoloopState } from "./autoloop.mjs";
 
 const subcommands = [
   ["create-goals", "Create durable goal records from a brief."],
@@ -93,12 +94,16 @@ const defaultCriterion = (brief) => ({
 const createGoals = (cwd, args) => {
   const brief = requireOption(args, "--brief", "brief").trim();
   if (!brief) throw new LitgoalCliError("missing brief");
+  // Opt-in: `--autoloop` arms the LitClaude Stop hook to keep the session running
+  // (a /goal-equivalent loop) until every criterion passes. Default off.
+  const autoloop = hasFlag(args, "--autoloop");
   return withLitgoalLock(litgoalLockDir(cwd), () => {
     const timestamp = nowIso();
     const state = {
       version: 1,
       objective: brief,
       status: "active",
+      autoloop,
       criteria: [defaultCriterion(brief)],
       blockers: [],
       steering: [],
@@ -110,10 +115,13 @@ const createGoals = (cwd, args) => {
     mkdirSync(dirname(litgoalBriefPath(cwd)), { recursive: true });
     writeFileSync(litgoalBriefPath(cwd), `${brief}\n`);
     writeLitgoalState(litgoalGoalsPath(cwd), state);
+    // Fresh autoloop run -> reset the durable iteration counter so prior caps don't carry over.
+    if (autoloop) resetAutoloopState(cwd, Date.parse(timestamp) || Date.now());
     appendLedger(cwd, {
       event: "goal.created",
       objective: brief,
       status: state.status,
+      autoloop,
       criteria: state.criteria.map(({ id, status }) => ({ id, status })),
     });
     return state;

package/plugins/litclaude/skills/lit-loop/SKILL.md

@@ -39,16 +39,18 @@ Before implementation:
 
 ## Native Goal + Dynamic Workflow
 
-Use Claude Code's native goal surface when available:
-
-- If model-facing tools exist, call `get_goal`, call `create_goal` only when no
-  matching active goal exists, and call `update_goal` only after every success
-  criterion has evidence or the work is genuinely blocked.
-- If the user chooses `/goal`, treat it as the native Claude Code session goal.
-  LitClaude must not auto-type or send `/goal` text.
-- If model-facing goal tools are not exposed, continue quietly with the local
-  evidence ledger. Mention `/goal <completion condition>` only when it helps a
-  long-running task; do not spam fallback status.
+Claude Code's `/goal` (v2.1.139+) is a **user-typed slash command** that sets an autonomous
+completion condition; a hook or skill **cannot invoke it**, and Claude Code exposes no
+model-facing goal tools today. Bind goals like this:
+
+- When a goal is worth binding, **propose a concrete, ready-to-paste `/goal <completion
+  condition>`** for the user, and keep driving the local evidence ledger meanwhile. LitClaude
+  must not auto-type or send `/goal` text.
+- Forward-compat only: if a future Claude Code build exposes model-facing goal tools, prefer
+  them — call `get_goal`, call `create_goal` only when no matching active goal exists, and call
+  `update_goal` only after every success criterion has evidence or the work is genuinely blocked.
+- While model-facing goal tools are not exposed (the case today), the local litgoal ledger is the
+  durable record; surface the `/goal` proposal for long-running goals and don't spam fallback status.
 
 Dynamic workflow orchestration is mandatory for broad, risky, parallel, or
 long-running work: call `Workflow` when exposed instead of merely mentioning it.

package/plugins/litclaude/skills/lit-plan/SKILL.md

@@ -44,16 +44,15 @@ and do not pretend the skill can silently execute it.
 
 ## Native Goal + Dynamic Workflow
 
-Include native goal handling:
-
-- If model-facing goal tools are exposed, call `get_goal`, create with
-  `create_goal` only when no matching active goal exists, and delay
-  `update_goal` until verified completion or a real blocker.
-- If goal tools are not exposed, plan a quiet local ledger and a user-visible
-  `/goal <completion condition>` option instead of claiming native activation.
-- If only the `/goal` UI surface is available, include an exact
-  `/goal <completion condition>` line for the user or wrapper to run.
-- Do not auto-type or send `/goal` text from a skill.
+Include native goal handling. Claude Code's `/goal` (v2.1.139+) is a **user-typed slash command**,
+not a model-facing tool, and a hook/skill **cannot invoke it**:
+
+- Include an exact, ready-to-paste `/goal <completion condition>` line in the plan for the user to
+  run — this is the real way to bind the native goal — plus a quiet local ledger for tracking.
+- Forward-compat only: if a future Claude Code build exposes model-facing goal tools, call
+  `get_goal`, create with `create_goal` only when no matching active goal exists, and delay
+  `update_goal` until verified completion or a real blocker. These goal tools are not exposed today.
+- Do not auto-type or send `/goal` text from a skill, and never claim native activation without evidence.
 
 For broad, risky, parallel, or long-running implementation, include Dynamic workflow
 and Dynamic worktree instructions: