litclaude-ai 0.3.1 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 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
+  reference hierarchical AGENTS.md generator: discovery → score → generate → review, with dynamic
+  explore-subagent scaling, a weighted scoring matrix, AGENTS.md templates, and quality gates. All
+  reference orchestration/LSP calls are re-authored to Claude Code surfaces (`Agent`/`Task` background
+  subagents, the `LSP` tool, `Workflow` for parallel generation, `TodoWrite`) — no literal calls to
+  missing tools, no Codex/opencode tokens.
+- Add `plans/litclaude-reference-parity-sdd.md`: a decision-complete SDD plan capturing the full
+  OmO-reference parity audit (all 11 shared skills + both auxiliary packs are byte-identical) and the
+  remaining portable ports (`init-deep` done; `visual-qa` and `lsp-setup` planned), plus a verified
+  deliberate-omission (N/A) registry. Allowlisted as a non-shipped doc-class file.
+
+## 0.3.2 - 2026-06-14 — port the git-master skill
+
+- Add the `git-master` skill (`plugins/litclaude/skills/git-master/`), a Claude-adapted port of the
+  reference git-history specialist: mode-gated COMMIT / REBASE / HISTORY / STATUS workflows, atomic
+  commit grouping with local message-style detection, `--force-with-lease` rebase safety, and
+  `git log -S/-G` / `blame` / `bisect` / `reflog` history investigation. Aligned with LitClaude's
+  publish boundary — no commit/push/history rewrite without explicit user authorization.
+
 ## 0.3.1 - 2026-06-14 — neon-HUD truecolor detection on Windows Terminal / WSL2
 
 - Fix the `[🔥LITCLAUDE]` HUD falling back to flat 256-color magenta in Windows Terminal under WSL2.

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.1-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.6-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.1` for personal install
+This checkout is prepared as `litclaude-ai@0.3.6` 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.1
+Future package releases still require explicit user approval. The v0.3.6
 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.1 install
+npx --yes litclaude-ai@0.3.6 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.1] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.6] | 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.1-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.6-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.1` 배포 준비용으로 정리되어 있습니다. 목적은
+현재 checkout은 `litclaude-ai@0.3.6` 배포 준비용으로 정리되어 있습니다. 목적은
 다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
 npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
 marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
-승인 후에 진행합니다. v0.3.1 release material은 v0.2.2 Dynamic workflow
+승인 후에 진행합니다. v0.3.6 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.1 install
+npx --yes litclaude-ai@0.3.6 install
 ```
 
 설치 상태를 확인합니다.
@@ -111,7 +111,7 @@ installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.1] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.6] | 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.1` is the current release candidate — a patch that fixes neon-HUD truecolor
-detection on Windows Terminal / WSL2 (and other 24-bit terminals that do not export `COLORTERM`).
-`package.json` is aligned to `0.3.1`, and
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.1`.
+Status: `litclaude-ai@0.3.6` is the current release candidate — adds **litgoal autoloop**: a
+plugin-owned `Stop` hook bound to the litgoal ledger that reproduces `/goal`'s autonomous
+keep-running behavior under plugin control (opt-in `--autoloop`, default off, deterministic
+completion, 4 safety brakes). Enables `/goal`-equivalent execution via LitClaude skills + hooks.
+`package.json` is aligned to `0.3.6`, and
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.6`.
 
 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.1`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.1`.
+- `package.json` version is `0.3.6`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.6`.
 - `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.1",
+  "version": "0.3.6",
   "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.1",
+  "version": "0.3.6",
   "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) => {
@@ -61,12 +65,12 @@ const litworkContext = ({ command, skill, discipline, softConfirm }) => [
   discipline === "deep-interview" ? "DEEP INTERVIEW MODE ENABLED." : "LITWORK MODE ENABLED.",
   `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(" ");
@@ -103,6 +107,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/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/git-master/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: git-master
+description: "MUST USE whenever a task needs a commit or git-history investigation. Covers atomic commits, staging, commit-message style, rebase, squash, fixup/autosquash, blame, bisect, reflog, git log -S/-G, and questions like who wrote this or when was this added. Do not use for ordinary code edits unless the user asks for git work."
+---
+
+# Git Master
+
+The LitClaude git-history specialist for Claude Code. Use this skill when the user
+asks you to operate on Git history or answer a Git-history question. Be exact,
+conservative, and evidence-led. Read the repository state before you infer anything.
+
+## LitClaude publish boundary
+
+Commit, push, force-push, and history rewrites are outward-facing or hard-to-reverse
+operations. Per LitClaude discipline, do **not** commit, push, force-push, reset,
+stash-pop, or rewrite history unless the user explicitly authorized that exact
+operation. Investigative requests report findings and stop.
+
+## Mode Gate
+
+Classify the request first:
+
+- `COMMIT`: stage and commit local changes.
+- `REBASE`: rebase, squash, fixup, autosquash, reorder, split, or otherwise rewrite branch history.
+- `HISTORY`: answer when, where, who, why, or which commit changed something.
+- `STATUS`: inspect branch, diff, or working-tree state without changing it.
+
+If the request is only investigative, report findings and stop.
+
+## Ground Truth
+
+Gather independent facts first (these are read-only and safe to run in parallel):
+
+```bash
+git status --short
+git diff --stat
+git diff --staged --stat
+git branch --show-current
+git log -30 --oneline
+git rev-parse --abbrev-ref @{upstream}
+git merge-base HEAD origin/main
+git merge-base HEAD origin/master
+```
+
+Missing upstream or missing `main`/`master` is normal. Fall back to the best
+available branch or report the missing fact. Never treat a failed lookup as proof.
+
+## Commit Mode
+
+Commit only the user's requested changes. Preserve unrelated dirty work.
+
+1. Detect message style from recent history (`git log -30 --pretty=format:%s`). Use the
+   dominant local pattern, language, and casing. Do not default to Conventional
+   Commits unless the repo already uses them.
+2. Inspect the full diff, not only filenames. Separate unrelated user edits from the
+   requested commit.
+3. Build atomic groups by behavior, module, and revertability. Keep implementation and
+   its direct tests together.
+4. Prefer multiple commits for unrelated concerns. A single commit is acceptable only
+   when the changed files form one indivisible behavior or the user explicitly asks for one.
+5. Stage by path or hunk so each commit contains only its atomic group.
+6. Before each commit, verify `git diff --staged --stat` and enough staged diff to prove
+   the group is right.
+7. Commit with the detected style. After each commit, verify `git log -1 --oneline`.
+
+Grouping rules:
+
+- Split different features, modules, generated artifacts, config, docs, and test-only
+  changes unless they are inseparable.
+- Keep generated files with the source change that produced them when omitting them
+  would leave the repo inconsistent.
+- Never hide failing or unrelated changes inside a broad commit.
+- Follow the user's git conventions (e.g. no AI/co-author attribution when the repo or
+  the user's rules forbid it).
+
+Final report: list commit hashes, messages, and any remaining uncommitted files.
+
+## Rebase Mode
+
+History rewriting is a shared-impact operation.
+
+- Never rebase or rewrite `main`, `master`, `dev`, release branches, or a protected
+  branch unless the user explicitly named that exact operation.
+- If commits may already be pushed, ask before force-pushing. Use `--force-with-lease`,
+  never plain `--force`.
+- If the worktree is dirty, preserve it intentionally before rebasing. Do not stash-pop
+  over conflicts without checking what changed.
+- For fixups, prefer `git commit --fixup=<hash>` then
+  `GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <base>`.
+- For conflicts, read the conflicting files and resolve by intent. Do not choose
+  ours/theirs blindly.
+- If a rebase goes wrong, run `git rebase --abort` first. Use reflog only after
+  explaining the recovery path.
+
+After rewriting, run the relevant tests or at least the project's cheapest smoke check,
+then show the new branch log from base to HEAD.
+
+## History Mode
+
+Choose the Git tool by the question:
+
+- `git log -S "text"`: when the count of an exact string changed.
+- `git log -G "regex"`: when diffs touched lines matching a pattern.
+- `git blame -L start,end -- file`: who last changed specific lines.
+- `git log --follow -- file`: history across renames for one file.
+- `git show <hash>`: inspect the commit that appears relevant.
+- `git bisect`: find the first bad commit when there is a deterministic pass/fail
+  command and known good/bad bounds.
+- `git reflog`: recover or explain recent local history movement.
+
+Always cite the exact command evidence in the answer: commit hash, subject, file path,
+and line or diff context when relevant. If the evidence is ambiguous, say what remains
+unproven.
+
+## Safety Checks
+
+Before any write to Git history:
+
+- Current branch is known.
+- Dirty work is accounted for.
+- Upstream/pushed status is known or explicitly unknown.
+- The operation matches an explicit user request and authorization.
+- Recovery path is known (`rebase --abort`, reflog hash, or untouched worktree).
+
+Before finishing:
+
+- Run the most relevant verification available for the changed behavior or history
+  operation (Manual QA evidence where a behavior changed).
+- Report commands that passed and any command you could not run.
+- Leave the worktree state explicit.