@litfamily/litclaude 1.0.26 → 1.0.28

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.0.28 - 2026-10-14
+
+- A new lit-loop no longer shows every stage of the card's workflow map as done when an older goal in the project had already finished. The finished goal now ends the map only when it finished after the current stage was recorded, so the map follows the work you are doing now; a goal that really finishes still shows done.
+- `litclaude-ai` is now on the Bash PATH after a plugin install, so the documented `litclaude-ai litgoal`, `start-work`, `workflow-stage` and similar commands run without the npm package. Other subcommands point you at the npm package.
+- The start-work gate lets its own `start-work pause` through when it names an outside target root. The pause records a pending boundary and grants nothing; forbidden actions are still refused.
+
+## 1.0.27 - 2026-10-13
+
+- The lit-loop map now moves when the work happens in the shell. Writing a test with a shell command (`cat > test/…`, `>>`, `tee` or `sed -i`) turns the map to RED, changing a source file the same way turns it to GREEN, and the next test run turns it to VERIFY. A failing test run while the criterion is still pinned also counts as RED, including a bare `npm test` that exits with an error. The card keeps only the stage, never the command or the file names.
+- `litclaude-ai install` no longer stops with `INSTALL_OWNERSHIP_CONFLICT` when the Claude desktop app has marked the installed plugin as in use. The app's `.in_use` folder, with its process-numbered entries, is left in place; anything else inside it is still reported.
+- The start-work gate lets read-only git through during active work: `git status`, `git diff`, `git log` and `git show`, with any paths they name still checked against the work's grants. Its own lifecycle commands, `litclaude-ai start-work progress`, `complete` and `cancel`, pass too. `node -e` stays blocked, because its script cannot be read as read-only from the command alone.
+- The README demo film is retaken: the card's workflow map turns RED on the failing test, then GREEN and VERIFY when the tests pass, and the live step names the running tool and its time.
+
 ## 1.0.26 - 2026-10-13
 
 - The LIT card now shows where you are in the LIT workflow. A map row lights the current stage of the running family (interview, plan, work, review, loop, research), and a detail line under it says what that stage is doing: the interview round and ambiguity, whether the plan awaits approval, how many tasks are checked and which comes next, each review lane's verdict. On the right of that line the live step names the tool the main loop is running and for how long, or `thinking` between tool calls, and never shows its arguments.

package/README.md

@@ -1,14 +1,14 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitClaude robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitClaude robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
 <h1 align="center">LitClaude</h1>
 <p align="center"><strong>Keep the work lit.</strong></p>
 <p align="center">A Claude Code plugin that helps every session plan the work, build it, check it, and leave a note the next session can pick up.</p>
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/assets/readme/badge-version.svg" alt="1.0.26" />
-  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+  <img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/assets/readme/badge-version.svg" alt="1.0.28" />
+  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
 </p>
 <p align="center">
-  <a href="https://github.com/wjgoarxiv/litclaude#readme">Full guide and skills gallery on GitHub</a> · <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/README_ko-KR.md">한국어</a>
+  <a href="https://github.com/wjgoarxiv/litclaude#readme">Full guide and skills gallery on GitHub</a> · <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/README_ko-KR.md">한국어</a>
 </p>
 
 Add `lit` to a Claude Code prompt and Claude pins the goal, writes a failing test first,
@@ -73,7 +73,7 @@ the `/plugin` menu.
 ## More
 
 - [Full guide and skills gallery on GitHub](https://github.com/wjgoarxiv/litclaude#readme)
-- [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/privacy.md)
-- [Migration and ownership conflicts](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/migration.md)
-- [Release history](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/CHANGELOG.md)
-- [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/LICENSE)
+- [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/privacy.md)
+- [Migration and ownership conflicts](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/migration.md)
+- [Release history](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/CHANGELOG.md)
+- [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/LICENSE)

package/README_ko-KR.md

@@ -1,14 +1,14 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitClaude 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitClaude 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
 <h1 align="center">LitClaude</h1>
 <p align="center"><strong>Keep the work lit.</strong></p>
 <p align="center">Claude Code에서 세션마다 계획하고, 만들고, 확인한 뒤 다음 세션이 이어받을 기록을 남기게 돕는 플러그인입니다.</p>
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/assets/readme/badge-version.svg" alt="1.0.26" />
-  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+  <img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/assets/readme/badge-version.svg" alt="1.0.28" />
+  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
 </p>
 <p align="center">
-  <a href="https://github.com/wjgoarxiv/litclaude/blob/main/README_ko-KR.md">전체 안내와 스킬 갤러리는 GitHub에서</a> · <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/README.md">English</a>
+  <a href="https://github.com/wjgoarxiv/litclaude/blob/main/README_ko-KR.md">전체 안내와 스킬 갤러리는 GitHub에서</a> · <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/README.md">English</a>
 </p>
 
 Claude Code 프롬프트에 `lit`을 붙이면 Claude가 목표를 고정하고, 실패하는 테스트를 먼저 쓰고,
@@ -71,7 +71,7 @@ LitClaude는 프로젝트 상태를 `.litclaude/`에 두고, 그 안의 `.gitign
 ## 더 보기
 
 - [전체 안내와 스킬 갤러리 (GitHub)](https://github.com/wjgoarxiv/litclaude/blob/main/README_ko-KR.md)
-- [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/privacy.md)
-- [이전과 소유권 충돌](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/docs/migration.md)
-- [변경 이력](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/CHANGELOG.md)
-- [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.26/LICENSE)
+- [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/privacy.md)
+- [이전과 소유권 충돌](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/docs/migration.md)
+- [변경 이력](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/CHANGELOG.md)
+- [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.28/LICENSE)

package/bin/install-ownership.mjs

@@ -23,6 +23,11 @@ const legacyVendorPathMap = [
 // Python writes bytecode next to the scripts it runs. That cache is generated, never user data, so ownership
 // checks skip it. A symlink or a plain file named __pycache__ is not a cache and is still reported.
 const isBytecodeCache = (name, value) => (value.isDirectory() && name === "__pycache__") || (value.isFile() && name.endsWith(".pyc"));
+// Claude Code and the desktop app mark a cache version they have loaded with `.in_use/`, empty or
+// holding one pid-named entry per process. That marker is the host's: ownership checks skip it and
+// never remove it. Any other name inside it, or a symlink, is still reported.
+const isHostUseMarker = (path, name, value) => name === hostUseMarker && value.isDirectory()
+  && readdirSync(path, { withFileTypes: true }).every((entry) => /^\d+$/u.test(entry.name) && (entry.isDirectory() || entry.isFile()));
 const conflict = (path, detail = "") => { throw new Error(`INSTALL_OWNERSHIP_CONFLICT: ${path}; use a compatible CLI or preserve this modified, foreign, or unsupported state before retrying${detail ? `. ${detail}` : ""}`); };
 const stat = (path) => {
   try { return lstatSync(path); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
@@ -49,7 +54,7 @@ function treeHash(root) {
       if (!prefix && name === receiptName) continue;
       const next = join(path, name), rel = prefix ? `${prefix}/${name}` : name, value = lstatSync(next);
       if (isBytecodeCache(name, value)) continue;
-      if (!prefix && name === hostUseMarker && value.isDirectory() && readdirSync(next).length === 0) continue;
+      if (!prefix && isHostUseMarker(next, name, value)) continue;
       if (value.isDirectory()) { entries.push([rel, "directory"]); walk(next, rel); }
       else if (value.isFile() && value.nlink === 1) entries.push([rel, "file", createHash("sha256").update(readFileSync(next)).digest("hex")]);
       else conflict(next);
@@ -69,6 +74,7 @@ function detailedTree(root, { receipt = false } = {}) {
       rows.push([prefix, "directory", value.mode & 0o777]);
       for (const name of readdirSync(path).sort()) {
         if (!prefix && !receipt && name === receiptName) continue;
+        if (!prefix && isHostUseMarker(join(path, name), name, lstatSync(join(path, name)))) continue;
         walk(join(path, name), prefix ? `${prefix}/${name}` : name);
       }
       return;
@@ -270,6 +276,18 @@ export function assertCurrentPointer(home, current, target, version, { expectedV
   return currentVersion;
 }
 
+// Empties an owned tree before a fresh copy, leaving the host's `.in_use` marker in place.
+export function clearOwnedTree(path) {
+  const value = stat(path);
+  if (!value) return;
+  if (!value.isDirectory() || value.isSymbolicLink()) { rmSync(path, { recursive: true, force: true }); return; }
+  for (const name of readdirSync(path)) {
+    const next = join(path, name);
+    if (isHostUseMarker(next, name, lstatSync(next))) continue;
+    rmSync(next, { recursive: true, force: true });
+  }
+}
+
 export function removeEmptyDirectory(path) {
   try { rmdirSync(path); } catch (error) { if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error; }
 }

package/bin/litclaude-ai.js

@@ -46,7 +46,7 @@ import { jevStatusLine } from "../plugins/litclaude/lib/jev-skill-hint.mjs";
 import { autoHandoffDoctorLines } from "../plugins/litclaude/lib/auto-handoff.mjs";
 import { resolveProjectStateRoot } from "../plugins/litclaude/lib/project-state-root.mjs";
 import { runUpdateNotifier } from "./update-notifier.mjs";
-import { assertInstallPath, assertOwnedTree, assertCurrentPointer, assertOwnedRegistrations, migrateLegacyVendorPaths, planModifiedLegacySkill, preserveModifiedLegacySkill, registeredPluginInstallation, writeOwnershipReceipt, removeEmptyDirectory } from "./install-ownership.mjs";
+import { assertInstallPath, assertOwnedTree, assertCurrentPointer, assertOwnedRegistrations, migrateLegacyVendorPaths, planModifiedLegacySkill, preserveModifiedLegacySkill, registeredPluginInstallation, writeOwnershipReceipt, removeEmptyDirectory, clearOwnedTree } from "./install-ownership.mjs";
 import { banner, lockup, colorMode, supportsBlocks, terminalRows } from "./litfamily-banner.mjs";
 import {
   ICON_FONT,
@@ -1393,7 +1393,7 @@ const install = async ({ dryRun, rest }) => {
       target: targetPlugin,
     },
     async () => {
-      await rm(targetPlugin, { recursive: true, force: true });
+      clearOwnedTree(targetPlugin);
       await mkdir(dirname(targetPlugin), { recursive: true });
       await cp(sourcePlugin, targetPlugin, { recursive: true });
       writeOwnershipReceipt(targetPlugin, "plugin", version);

package/docs/assets/readme/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.26"><title>release: 1.0.26</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.26</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.28"><title>release: 1.0.28</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.28</text></g></svg>

package/docs/hooks.md

@@ -12,7 +12,7 @@ surface: Claude Code plugin hooks
 runtime: plugins/litclaude/bin/litclaude-hook.js
 registration: plugins/litclaude/hooks/hooks.json
 settings_activation: global Claude settings.json enabledPlugins entry for litclaude@litclaude-ai
-events: [SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, SessionEnd]
+events: [SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStart, SubagentStop, SessionEnd]
 verdicts: [PASS, FAIL, BLOCKED]
 ```
 
@@ -106,6 +106,7 @@ silent no-op for callers that still invoke it directly.
 | `UserPromptSubmit` | `plugins/litclaude/bin/litclaude-hook.js user-prompt-submit` | Detects prompt routes and injects workflow context; independently delivers static rules not already recorded for this session; with `LITCLAUDE_JEV=1` and `TYPESAFE_API_KEY` set, adds at most one Jev skill hint line to an unrouted turn; answers the exact prompts `lit-handoff auto on <percent>`, `lit-handoff auto off` and `lit-handoff auto status` by changing or reporting the automatic handoff setting. |
 | `PreToolUse` | `plugins/litclaude/bin/litclaude-hook.js pre-tool-use` | Enforces semantic action/root grants before Write, Edit, MultiEdit, NotebookEdit, Bash, Agent, and bounded read tools execute; denies supported reader-facing text writes with a humanizer block-tier finding. |
 | `PostToolUse` | `plugins/litclaude/bin/litclaude-hook.js post-tool-use` | Moves the LIT card's stage record on from what the tool did (plan saved, task checked, lit-loop step, a reviewer's verdict from an `Agent` result). Names the post-edit checks the edit actually earned, injects any glob-scoped rule matching the edited paths, and checks successfully created DOCX/PPTX/PDF files for humanizer findings, including paths reported by Bash output. |
+| `PostToolUseFailure` | `plugins/litclaude/bin/litclaude-hook.js post-tool-use-failure` | For a Bash command that exits non-zero, such as a bare failing `npm test`, moves the LIT card's lit-loop map from what the command wrote and from its failing test run, which never counts as VERIFY. Nothing else runs on a failed tool. |
 | `Stop` | `plugins/litclaude/bin/litclaude-hook.js stop` | Holds a lit-plan turn with no persisted plan and a lit workflow turn that edited interface files without a clean interface-probe run (each at most twice per turn), emits bounded start-work continuation on new progress, otherwise applies the opt-in litgoal autoloop gate, and last of all, with automatic handoff on, blocks once per crossing of the chosen percent to have the handoff written. |
 | `SubagentStart` | `plugins/litclaude/bin/litclaude-hook.js subagent-start` | Registers child-lane and Claude-owned worktree identity. |
 | `SubagentStop` | `plugins/litclaude/bin/litclaude-hook.js subagent-stop` | Finalizes the lane without child continuation, and gives a background review-work reviewer's verdict to the LIT card's stage record. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litclaude",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "Claude Code plugin: add lit to a prompt and Claude plans, tests, checks and reviews the work, then leaves a handoff for the next session.",
   "type": "module",
   "bin": {

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

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin with a bounded-authority start-work lifecycle.",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "author": {
     "name": "LitClaude contributors"
   },

package/plugins/litclaude/bin/litclaude-ai

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// The `litclaude-ai` the skills and commands name, as the installed plugin serves it. Claude Code
+// puts this bin/ directory on the Bash tool's PATH; the npm CLI (bin/litclaude-ai.js in the
+// package) is usually not there. This entry runs the in-session subcommands from the plugin's own
+// lib/ and sends everything else (install, doctor, update…) to the user's terminal.
+//
+// No file extension, so the bare name resolves on PATH; the code avoids `import`, `require`,
+// `import.meta` and `module` so it runs whether Node loads it as CommonJS or as an ES module.
+
+const SUBCOMMANDS = {
+  litgoal: async (load, rest) => (await load("../lib/litgoal/cli.mjs")).runLitgoalCli(rest),
+  "start-work": async (load, rest) => (await load("../lib/start-work-cli.mjs")).runStartWorkCli(rest, undefined, process.cwd()),
+  "start-work-next": async (load, rest) => {
+    const { resolveProjectStateRoot } = await load("../lib/project-state-root.mjs");
+    return (await load("../lib/start-work-continuation.mjs")).runStartWorkContinuationCli(resolveProjectStateRoot(process.cwd()), rest);
+  },
+  "workflow-stage": async (load, rest) => (await load("../lib/workflow-stage.mjs")).runWorkflowStageCli(rest, process.cwd()),
+  wikify: async (load, rest) => (await load("../lib/wikify-knowledge-cli.mjs")).runWikifyKnowledgeCli(rest, undefined, process.cwd()),
+  "motion-runtime": async (load, rest) => (await load("../skills/lit-typographic-motion/scripts/motion-runtime.mjs")).main(rest),
+};
+
+const main = async () => {
+  const [command, ...rest] = process.argv.slice(2);
+  const run = Object.hasOwn(SUBCOMMANDS, command ?? "") ? SUBCOMMANDS[command] : null;
+  if (!run) {
+    process.stderr.write(
+      `litclaude-ai (plugin): ${command ? `"${command}" is not served from the plugin` : "no command given"}. `
+      + `In-session commands: ${Object.keys(SUBCOMMANDS).join(", ")}. `
+      + `For install, update, doctor and the rest, ask the user to run in their own terminal: npx @litfamily/litclaude ${command ?? "--help"}\n`,
+    );
+    return 64;
+  }
+  const { realpathSync } = await import("node:fs");
+  const { dirname, join } = await import("node:path");
+  const { pathToFileURL } = await import("node:url");
+  const here = dirname(realpathSync(process.argv[1]));
+  return run((relative) => import(pathToFileURL(join(here, relative)).href), rest);
+};
+
+main().then(
+  (code) => {
+    process.exitCode = Number.isInteger(code) ? code : 0;
+  },
+  (error) => {
+    process.stderr.write(`litclaude-ai (plugin): ${error?.message ?? error}\n`);
+    process.exitCode = 1;
+  },
+);

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

@@ -124,6 +124,7 @@ const hookEventNames = {
   "user-prompt-submit": "UserPromptSubmit",
   "pre-tool-use": "PreToolUse",
   "post-tool-use": "PostToolUse",
+  "post-tool-use-failure": "PostToolUseFailure",
   "stop": "Stop",
   "subagent-start": "SubagentStart",
   "subagent-stop": "SubagentStop",
@@ -1548,6 +1549,17 @@ switch (eventName) {
     // dispatch silent; compact re-injection is delivered by SessionStart source=compact.
     break;
   }
+  case "post-tool-use-failure": {
+    // A Bash command that exits non-zero (a bare failing `npm test`) never reaches PostToolUse. Its
+    // writes and its failing run still move the LIT card's lit-loop map; nothing else runs here.
+    try {
+      const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
+      observeWorkflowPostTool(cwd, input, { lifecycleRoot: lifecycleRootFor(cwd), failed: true });
+    } catch {
+      // The stage record only feeds the card.
+    }
+    break;
+  }
   case "subagent-start": {
     try {
       const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();

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

@@ -9,7 +9,7 @@ import {
 } from "../lib/wikify-knowledge.mjs";
 
 const protocolVersion = "2024-11-05";
-const serverVersion = "1.0.26";
+const serverVersion = "1.0.28";
 
 const publicSourceReadTool = {
   name: "public_source_read",

package/plugins/litclaude/hooks/hooks.json

@@ -51,6 +51,19 @@
         ]
       }
     ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/litclaude-hook.js\" post-tool-use-failure",
+            "timeout": 10,
+            "statusMessage": "moving the LIT card's workflow map"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

package/plugins/litclaude/lib/mod/state.mjs

@@ -233,6 +233,10 @@ export const parseGoals = (state, sessionId) => {
       .filter(Boolean),
     lastCheckpoint: str(Array.isArray(state.checkpoints) ? state.checkpoints.at(-1)?.status : null, 40),
     createdAt: time(state.createdAt),
+    // When the goal was finished: its last `complete` checkpoint, else its last update.
+    completedAt: state.status === "complete"
+      ? time((Array.isArray(state.checkpoints) ? state.checkpoints : []).findLast((entry) => entry?.status === "complete")?.createdAt) ?? time(state.updatedAt)
+      : null,
   };
 };
 

package/plugins/litclaude/lib/mod/workflow.mjs

@@ -111,6 +111,10 @@ const entryOf = ({ snapshot, skills, now }) => {
   return candidates.sort((a, b) => b.at - a.at || (a.from === "record" ? -1 : 1))[0] ?? null;
 };
 
+// A finished goal ends the map unless a stage record, skill or ignition came after it: that is a
+// new request, and the old finish says nothing about it.
+const goalFinished = (goal, entry) => goal?.status === "complete" && !(Number.isFinite(goal.completedAt) && Number.isFinite(entry?.at) && entry.at > goal.completedAt);
+
 const goalIsOpen = (goal) => Boolean(goal && ["active", "blocked", "review_blocked", "needs_user_decision"].includes(goal.status));
 
 // Without a discipline or a record, the durable state that says work is under way.
@@ -173,7 +177,7 @@ export const buildWorkflow = ({ snapshot, skills = [], completion = null, now })
     const planSaved = stage === "plan" && record?.stage === "plan" && record.done;
     if (planSaved) stage = "work";
     const lanes = record?.stage === "review" ? laneVerdicts(record.verdicts) : null;
-    if (completion || goal?.status === "complete" || stage === "done") stage = "done";
+    if (completion || goalFinished(goal, entry) || stage === "done") stage = "done";
     else if (stage === "work" && !work && !goalIsOpen(goal) && snapshot.completedWorkIds.length > 0) stage = "review";
     else if (stage === "review" && lanes?.every(({ state }) => state === "pass")) stage = "done";
     if (planSaved && stage === "work" && !work) items.push("plan saved");
@@ -226,7 +230,7 @@ export const buildWorkflow = ({ snapshot, skills = [], completion = null, now })
   }
 
   const order = WORKFLOW_FAMILIES[family];
-  const finished = family === "main" ? stage === "done" : completion !== null || (family === "loop" && snapshot.goal?.status === "complete");
+  const finished = family === "main" ? stage === "done" : completion !== null || (family === "loop" && goalFinished(snapshot.goal, entry));
   const current = finished ? -1 : order.indexOf(stage);
   const wave = sources.research?.wave ?? 0;
   const stages = order.map((id, index) => {

package/plugins/litclaude/lib/start-work-lifecycle.mjs

@@ -936,6 +936,33 @@ const classifyNodeScriptWords = (args, cwd) => {
 };
 
 const LITCLAUDE_CLI_NAMES = new Set(["litclaude-ai", "litclaude"]);
+const START_WORK_SELF_MOVES = new Set(["progress", "complete", "cancel"]);
+
+// Read-only git: status, diff, log and show over plain words. A flag that writes a file or runs an
+// external program is refused. An operand after `--`, one holding a `/` or one naming an existing
+// file is a path, checked as a read under the grants; other operands (HEAD~1, a commit, main..topic)
+// are data. Anything else, including a quote, an operator or `node -e`, meets the strict checks.
+const GIT_READ_SUBCOMMANDS = new Set(["status", "diff", "log", "show"]);
+const GIT_WORD = /^[\w.\/@^:=+,-][\w.\/@^~:=+,-]*$/u;
+const classifyReadOnlyGit = (command, cwd) => {
+  const words = command.split(/[ \t]+/u);
+  if (words[0] !== "git" || !GIT_READ_SUBCOMMANDS.has(words[1])) return null;
+  const paths = [];
+  let operands = false;
+  for (const word of words.slice(2)) {
+    if (!GIT_WORD.test(word)) return pathArgumentDenied;
+    if (!operands && word === "--") {
+      operands = true;
+      continue;
+    }
+    if (!operands && word.startsWith("-")) {
+      if (/^--(?:output|ext-diff|textconv)(?:=|$)/u.test(word) || word.includes("/")) return pathArgumentDenied;
+      continue;
+    }
+    if (operands || word.includes("/") || existsSync(resolve(cwd, word))) paths.push(word);
+  }
+  return canonicalBashTargets(cwd, [cwd, ...paths], "read");
+};
 
 const classifyBashWords = (words, cwd) => {
   const [head, ...args] = words;
@@ -958,6 +985,19 @@ const classifyBashWords = (words, cwd) => {
     if (rest[0] === "workflow-stage" && rest.every((word) => !word.includes("/"))) {
       return canonicalBashTargets(cwd, [cwd, ...cli], "write");
     }
+    // The lifecycle's own moves for the active work write its state under the project's .litclaude
+    // directory. `init` declares grants and `--root` points at another lifecycle, so neither passes.
+    if (rest[0] === "start-work" && START_WORK_SELF_MOVES.has(rest[1]) && !rest.includes("--root") && rest.every((word) => !word.includes("/"))) {
+      return canonicalBashTargets(cwd, [cwd, ...cli], "write");
+    }
+    // `pause` is how the work asks the user for a new boundary: it records the pending boundary
+    // and grants nothing, so the root it names may lie outside the grants, and the lifecycle
+    // refuses a forbidden action itself. Only that `--target-root` value may hold a `/`, and only
+    // the bare CLI name passes: a `node <path>/litclaude-ai.js` file is checked by name, not content.
+    if (cli.length === 0 && rest[0] === "start-work" && rest[1] === "pause" && !rest.includes("--root")
+      && rest.every((word, index) => !word.includes("/") || rest[index - 1] === "--target-root")) {
+      return canonicalBashTargets(cwd, [cwd, ...cli], "write");
+    }
   }
   if (head.text === "node") return classifyNodeScriptWords(args, cwd);
   return null;
@@ -970,6 +1010,8 @@ const classifyBash = (command, cwd) => {
   if (forbiddenShellPattern.test(command)) return { denied: "forbidden authority action in Bash command" };
   const trimmed = command.trim();
   if (shellRelocationPattern.test(trimmed)) return { denied: "Bash relocation flags are not authorized" };
+  const git = classifyReadOnlyGit(trimmed, cwd);
+  if (git) return git;
   const words = shellWords(trimmed);
   const worded = words ? classifyBashWords(words, cwd) : null;
   if (worded) return worded;

package/plugins/litclaude/lib/workflow-stage.mjs

@@ -5,14 +5,14 @@
 // see, with no help from the model. The prompt and PreToolUse hooks start it when one of
 // STAGE_RECORD_SKILLS starts and clear it for any other discipline; PreToolUse marks a review
 // lane running when its reviewer is spawned; PostToolUse moves it when the plan file is saved, a
-// task is checked in the active plan, a lit-loop test is written, made to pass, run or recorded,
-// or a foreground reviewer reports; SubagentStop takes a background reviewer's verdict.
+// task is checked in the active plan, a lit-loop test is written (with Write or Edit or through
+// the shell), made to pass, run or recorded, or a foreground reviewer reports; SubagentStop takes a background reviewer's verdict.
 // `litclaude-ai workflow-stage` stays as the model's optional refinement. The card
 // (lib/mod/state.mjs) reads the record back. One small file, written whole, its fields checked
 // against the same tables the card draws from (lib/mod/workflow.mjs). The hooks keep only which
 // stage, which lane and how many; never a path, a command or a prompt.
 
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 
 import { DISCIPLINE_ENTRY, STAGE_UNITS, VERDICT_STATES, WORKFLOW_FAMILIES, WORKFLOW_FRESH_MS, normalizeStage, reviewLaneOf } from "./mod/workflow.mjs";
@@ -174,10 +174,12 @@ const TEST_RUN = /(?:^|[\s;&|(])(?:npm\s+(?:run\s+)?test|pnpm\s+(?:run\s+)?test|
 const PLAN_SCAFFOLD = /scaffold-plan\.mjs/u;
 const LITGOAL_EVIDENCE = /\blitgoal\s+record-evidence\b/u;
 
-// lit-loop's steps as the hooks see them: a test written, the code that makes it pass, the test
-// run, the evidence recorded. Each move happens only from the step before it.
+// lit-loop's steps as the hooks see them: a test written (or a failing run while the criterion is
+// pinned), the code that makes it pass, the test run, the evidence recorded. Each move happens only
+// from the step before it.
 const LOOP_MOVES = Object.freeze([
   Object.freeze({ on: "test-edit", from: Object.freeze(["PIN", "RECORD"]), to: "RED" }),
+  Object.freeze({ on: "test-fail", from: Object.freeze(["PIN"]), to: "RED" }),
   Object.freeze({ on: "source-edit", from: Object.freeze(["RED"]), to: "GREEN" }),
   Object.freeze({ on: "test-run", from: Object.freeze(["GREEN"]), to: "VERIFY" }),
   Object.freeze({ on: "evidence", from: Object.freeze(WORKFLOW_FAMILIES.loop), to: "RECORD" }),
@@ -189,6 +191,94 @@ const moveLoop = (cwd, sessionId, previous, signal) => {
   return move ? moveStage(cwd, sessionId, previous, { family: "loop", stage: move.to }) : null;
 };
 
+// A test run's report of at least one failure: TAP (`not ok 2`, `# fail 1`) or a runner's summary
+// (`1 failed`, `2 failing`).
+const TEST_FAILED = /^\s*not ok \d|^# fail [1-9]|\b[1-9]\d* (?:failed|failing)\b/mu;
+const shellOutput = (response) => (typeof response === "string" ? response
+  : [response?.stdout, response?.stderr, resultText(response)].filter((text) => typeof text === "string").join("\n")).slice(0, 65_536);
+
+// A heredoc's body is data, so the command is read without it; the line that opens it stays.
+const withoutHeredocBodies = (command) => {
+  const opener = /<<-?\s*(["']?)([A-Za-z_][\w-]*)\1/u;
+  let rest = command;
+  let kept = "";
+  for (let match = opener.exec(rest); match; match = opener.exec(rest)) {
+    const lineEnd = rest.indexOf("\n", match.index);
+    if (lineEnd < 0) break;
+    kept += rest.slice(0, lineEnd + 1);
+    const body = rest.slice(lineEnd + 1);
+    const close = new RegExp(`^[\\t ]*${match[2]}[\\t ]*$`, "mu").exec(body);
+    rest = close ? body.slice(close.index + close[0].length) : "";
+  }
+  return kept + rest;
+};
+
+/**
+ * The files a shell command may write: `>` and `>>` targets, `tee` arguments and the files of an
+ * in-place `sed`. Words are read with their quotes and heredoc bodies are skipped; the caller keeps
+ * only targets that exist as files in the project, so a stray word never moves the map.
+ */
+export const shellWriteTargets = (command) => {
+  const text = withoutHeredocBodies(typeof command === "string" ? command.slice(0, 65_536) : "");
+  const segments = [[]];
+  const targets = [];
+  let word = null;
+  let quote = null;
+  let next = "word";
+  const push = () => {
+    if (word === null) return;
+    if (next === "target") targets.push(word);
+    else if (next === "word") segments.at(-1).push(word);
+    next = "word";
+    word = null;
+  };
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (quote) {
+      if (char === quote) quote = null;
+      else word += char;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+      word ??= "";
+    } else if (char === ">") {
+      if (/^(?:\d|&)?$/u.test(word ?? "")) word = null;
+      push();
+      if (text[index + 1] === ">") index += 1;
+      // `>&2` duplicates a descriptor; it names no file.
+      next = text[index + 1] === "&" ? "skip" : "target";
+      if (next === "skip") index += 1;
+    } else if (char === "<") {
+      push();
+      next = "skip";
+    } else if (/\s/u.test(char) || ";|&()".includes(char)) {
+      push();
+      if (!/[ \t]/u.test(char)) segments.push([]);
+    } else {
+      word = (word ?? "") + char;
+    }
+  }
+  push();
+  for (const words of segments) {
+    const args = words.filter((item) => !/^\w+=/u.test(item));
+    const [name, ...rest] = args;
+    const files = rest.filter((item) => item && !item.startsWith("-"));
+    if (name === "tee") targets.push(...files);
+    if (name === "sed" && rest.some((item) => /^-[A-Za-z]*i|^--in-place/u.test(item))) targets.push(...files);
+  }
+  return targets.filter((target) => target && target !== "/dev/null");
+};
+
+// A shell write counts as code only for a source file; a log or report the command writes is not the fix.
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?|py|go|rs|rb|java|kt|swift|c|cc|cpp|h|hpp|cs|php|lua|sh|zig|ex|exs|dart|scala)$/u;
+
+const isFile = (path) => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+
 const realOrResolved = (path) => {
   try {
     return realpathSync(path);
@@ -234,10 +324,13 @@ export const observeWorkflowPreTool = (cwd, input) => {
 /**
  * PostToolUse: the plan saved, a task checked in the active plan, a lit-loop step, a foreground
  * reviewer's verdict. `filePaths` are the paths the tool wrote (lib/mutated-file-paths.mjs).
+ * With `failed` (PostToolUseFailure) only a Bash command's lit-loop moves count: its writes, and its
+ * test run as a failing one, which never verifies.
  */
-export const observeWorkflowPostTool = (cwd, input, { filePaths = [], lifecycleRoot = cwd } = {}) => {
+export const observeWorkflowPostTool = (cwd, input, { filePaths = [], lifecycleRoot = cwd, failed = false } = {}) => {
   const sessionId = typeof input?.session_id === "string" ? input.session_id : null;
   if (!sessionId) return null;
+  if (failed && (input.tool_name !== "Bash" || input.is_interrupt === true)) return null;
   const previous = currentRecord(cwd, sessionId);
   const tool = input.tool_name;
   const planOpen = previous?.family === "main" && previous.stage === "plan" && previous.done !== true;
@@ -247,12 +340,33 @@ export const observeWorkflowPostTool = (cwd, input, { filePaths = [], lifecycleR
   }
   if (tool === "Bash") {
     const command = typeof input.tool_input?.command === "string" ? input.tool_input.command : "";
-    if (planOpen && PLAN_SCAFFOLD.test(command) && !/--check\b|--draft-only\b/u.test(command)) {
+    if (!failed && planOpen && PLAN_SCAFFOLD.test(command) && !/--check\b|--draft-only\b/u.test(command)) {
       return moveStage(cwd, sessionId, previous, { family: "main", stage: "plan", done: true });
     }
-    if (LITGOAL_EVIDENCE.test(command)) return moveLoop(cwd, sessionId, previous, "evidence");
-    if (TEST_RUN.test(command)) return moveLoop(cwd, sessionId, previous, "test-run");
-    return null;
+    if (!failed && LITGOAL_EVIDENCE.test(command)) return moveLoop(cwd, sessionId, previous, "evidence");
+    // Files the command wrote move the loop as a Write or Edit would; then its test run, where a
+    // failing run while the criterion is pinned counts as the test that fails first.
+    let current = previous;
+    let moved = null;
+    const step = (signal) => {
+      const record = moveLoop(cwd, sessionId, current, signal);
+      if (record) current = moved = record;
+    };
+    if (previous?.family === "loop") {
+      const root = realOrResolved(resolveProjectStateRoot(cwd));
+      for (const target of shellWriteTargets(command).slice(0, 20)) {
+        const absolute = realOrResolved(resolve(cwd, target));
+        const inProject = relative(root, absolute).split("\\").join("/");
+        if (!isFile(absolute) || inProject.startsWith("..") || /^(?:\.litclaude|plans)\//u.test(inProject)) continue;
+        if (TEST_PATH.test(inProject)) step("test-edit");
+        else if (SOURCE_FILE.test(inProject)) step("source-edit");
+      }
+    }
+    if (TEST_RUN.test(command)) {
+      if (failed) step("test-fail");
+      else step(current?.stage === "PIN" && TEST_FAILED.test(shellOutput(input.tool_response)) ? "test-fail" : "test-run");
+    }
+    return moved;
   }
   if (!filePaths.length) return null;
   const root = resolveProjectStateRoot(cwd);