@litfamily/litclaude 1.0.25 → 1.0.27

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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.
+- The map moves on its own. LitClaude's hooks advance it as lit-plan saves the plan, start-work's tasks are checked, review lanes report their verdicts and a lit-loop criterion goes from RED to GREEN to VERIFY, so the model does not have to report each step. For what the hooks cannot see, such as a loop step or a crucible verdict, the new `litclaude-ai workflow-stage` command records the stage.
+- In the Claude desktop app the card is drawn as one picture. The app sets text in a proportional font, which pulled the terminal card apart there, so the desktop and editor surfaces now get the same rows as a single drawing, moving under the same `motion` setting. The terminal keeps the card it had.
+- A new `notify` option raises a notification through your own notification channel when LIT work completes or a LIT turn longer than three minutes ends. It is `off` unless you turn it on with `/config` or `litclaude-ai config notify finish`.
+- The start-work gate no longer blocks read-only searches. It used to read a grep or rg pattern, a quoted phrase passed to a node script, or `litclaude-ai start-work status` as an unverified path and deny it. Patterns and plain words now count as data, while the searched paths are still checked against the work's grants.
+- `litclaude-ai doctor` reports the card options before the Claude validation step.
+- The README card pictures are retaken to show the workflow map and the detail line.
+
 ## 1.0.25 - 2026-10-12
 
 - The LIT card now moves while LitClaude is at work, so a glance tells you it is busy. The LIT pill and the border slowly glow from pink to flame orange and back, a light passes over the current phase and the skill chips of this request, and a spark runs along the top edge and back along the bottom one. When the turn ends the card goes still again. With the `motion` setting at `subtle` only the glow stays, and `off` keeps the card still.

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.25/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/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.27/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/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.25/docs/assets/readme/badge-version.svg" alt="1.0.25" />
-  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+  <img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/docs/assets/readme/badge-version.svg" alt="1.0.27" />
+  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/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.25/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.27/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.25/docs/privacy.md)
-- [Migration and ownership conflicts](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/docs/migration.md)
-- [Release history](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/CHANGELOG.md)
-- [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/LICENSE)
+- [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/docs/privacy.md)
+- [Migration and ownership conflicts](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/docs/migration.md)
+- [Release history](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/CHANGELOG.md)
+- [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/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.25/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/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.27/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/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.25/docs/assets/readme/badge-version.svg" alt="1.0.25" />
-  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+  <img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/docs/assets/readme/badge-version.svg" alt="1.0.27" />
+  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/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.25/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.27/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.25/docs/privacy.md)
-- [이전과 소유권 충돌](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/docs/migration.md)
-- [변경 이력](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/CHANGELOG.md)
-- [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.25/LICENSE)
+- [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/docs/privacy.md)
+- [이전과 소유권 충돌](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/docs/migration.md)
+- [변경 이력](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/CHANGELOG.md)
+- [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.27/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

@@ -39,13 +39,14 @@ import { runStartWorkContinuationCli } from "../plugins/litclaude/lib/start-work
 import { runStartWorkCli } from "../plugins/litclaude/lib/start-work-cli.mjs";
 import { runLitgoalCli } from "../plugins/litclaude/lib/litgoal/cli.mjs";
 import { runWorkflowCheckCli } from "../plugins/litclaude/lib/workflow-check.mjs";
+import { runWorkflowStageCli } from "../plugins/litclaude/lib/workflow-stage.mjs";
 import { runWikifyKnowledgeCli } from "../plugins/litclaude/lib/wikify-knowledge-cli.mjs";
 import { automaticUpdateRoot, runAutomaticUpdate } from "../plugins/litclaude/lib/automatic-update.mjs";
 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,
@@ -81,14 +82,14 @@ const prewarmMotionRuntime = () => {
 };
 const version = packageJson.version;
 
-const usage = `Usage: litclaude-ai [--dry-run] <install|doctor|config|path|run|update|uninstall|litgoal|wikify|workflow-check|start-work|start-work-next|public-read|motion-runtime> [...args]
+const usage = `Usage: litclaude-ai [--dry-run] <install|doctor|config|path|run|update|uninstall|litgoal|wikify|workflow-check|workflow-stage|start-work|start-work-next|public-read|motion-runtime> [...args]
        litclaude-ai --version
 
 Commands:
   install       Register the packaged LitClaude plugin in Claude Code.
   doctor        Validate the installed LitClaude plugin path.
   config [<option> <value>]
-                Show or change the LIT card options (motion, glyphs, band) in
+                Show or change the LIT card options (motion, glyphs, band, notify) in
                 pluginConfigs, the same values /config edits. Works for the
                 desktop app too, which shows no editor for them.
   path          Print the installed Claude plugin path.
@@ -98,6 +99,9 @@ Commands:
   workflow-check Verify Dynamic workflow, /goal, and subagent delegation readiness.
   start-work    Manage schema-3 bounded-authority lifecycle state.
   start-work-next Print the next active start-work continuation directive.
+  workflow-stage <family> <stage> [--n N --total M --unit U --verdict name=pass]
+                Record where a review, loop, iteration or crucible run stands, for
+                the LIT card's workflow map (.litclaude/workflow-stage.json).
   public-read   Read a public http(s) source with FetchAttempt/FetchVerdict JSON.
   motion-runtime Pre-warm (install [--audio] [--word-timing]) or report (status) the
                 lit-typographic-motion runtime cache. Run it outside a sandboxed session.
@@ -383,7 +387,7 @@ const familyBanner = ({ color = shouldColorInstall() } = {}) => [
 ].join("\n");
 
 const printCommandBanner = (parsed) => {
-  if (["install", "update"].includes(parsed.command)) return;
+  if (["install", "update", "workflow-stage"].includes(parsed.command)) return;
   if (parsed.rest.some((arg) => arg === "--json" || arg.startsWith("--json="))) return;
   const color = shouldColorInstall();
   process.stdout.write(`${renderLitClaudeWordmark({ color }).join("\n")}\n`);
@@ -1389,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);
@@ -1837,6 +1841,9 @@ const main = async () => {
     case "workflow-check":
       exitAfterFlush(runWorkflowCheckCli(root, version, parsed.rest));
       break;
+    case "workflow-stage":
+      exitAfterFlush(runWorkflowStageCli(parsed.rest, process.cwd()));
+      break;
     case "public-read":
       exitAfterFlush(await runPublicRead(parsed));
       break;

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.25"><title>release: 1.0.25</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.25</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.27"><title>release: 1.0.27</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.27</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]
 ```
 
@@ -105,10 +105,11 @@ silent no-op for callers that still invoke it directly.
 | `SessionStart` | `plugins/litclaude/bin/litclaude-hook.js session-start` | Runs the bounded foreground automatic-update barrier on a fresh session (or starts the detached version-cache refresh when the cache is stale), discovers repo-local rule files, names the newest valid `plans/<slug>.md`, and on `source: compact` spends one of two durable re-injection reservations at reduced caps and, with automatic handoff on, reloads the fresh handoff once. |
 | `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` | 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. |
+| `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. |
+| `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. |
 | `SessionEnd` | `plugins/litclaude/bin/litclaude-hook.js session-end` | Records root-session end without blocking Claude. |
 
 ### Changed-text humanizer guard
@@ -347,38 +348,74 @@ itself. LitClaude's is `plugins/litclaude/hooks/lit-mod.mjs`, named under `modul
 setup. The status line stays as it is; the band adds a live layer above the prompt.
 
 From the first prompt to the end of the session a LIT card sits above the prompt. It keeps the
-same four rows whether LitClaude is working or idle, and takes the status line's accent
+same five rows whether LitClaude is working or idle, and takes the status line's accent
 (`LITCLAUDE_HUD_ACCENT`, read from the installed status line command), so the card and the
 status line read as one family:
 
 ```
-╭─ [🔥 LIT] · lit-loop ─────────────────────────── WORK ● ─╮
-│ ● PLAN ━━ [WORK] ━━ ○ REVIEW              goal ██░░░ 2/5 │
-│ skills [⚡ lit-plan] [⚡ litresearch] [↯ lit-docx]        │
-╰─ ctx 42% ▰▰▱▱▱ · 5h 31% · 1w 12% · git main ─────────────╯
+╭─ [🔥 LIT] · start-work ───────────────────────────────── WORK ● ─╮
+│ interview ✓ ━━ plan ✓ ━━ [work 3/7] ━━ review · ── done ·  1 lane │
+│ └ task 3/7 ███░░░░░ · next ▸ 4. README demo        - Bash · 0:12 │
+│ skills [⚡ start-work] [↯ lit-plan]                               │
+╰─ ctx 42% ▰▰▱▱▱ · 5h 31% · 1w 12% · git main ─────────────────────╯
 ```
 
 The brackets stand for the ends of filled pills: rounded caps from the icon font with `nerd`
-glyphs, one cell of the pill's colour with `basic`. The brand is a pink pill, the active phase
+glyphs, one cell of the pill's colour with `basic`. The brand is a pink pill, the current stage
 and the skills of this request are pills on the accent with dark text, and skills from earlier
 requests are muted grey pills.
 
 - The top edge names the discipline the prompt hook ignited (the last one, dimmed, while the
-  session is idle; `ready` before any) and, on the right, the current phase: `WORK ●`, `idle`,
-  or `DONE ✓` during the finish. While a subagent is still running the card stays at work
-  (`LIVE ●` when no phase is active) and never reads `DONE`, even after the main turn ended.
-- The phase row lights `PLAN ━━ WORK ━━ REVIEW` from the start-work plan, the litgoal goal and
-  the discipline (the active phase as a pill, done phases `●`, the rest `○`), and on its right shows a pink-to-cyan progress bar with the checked tasks or
-  passed criteria (`goal ✓ 5/5` once a goal is met), the number of live subagents (`● 2 lanes`), the autoloop
-  count with the time left in its 30-minute budget, and `ctx 76% → 80%` when the context is
-  within five points of the auto-handoff percent.
-- The chips row shows each LitFamily skill that fired as a pill: a Skill tool call naming a LitClaude
+  session is idle; `ready` before any) and, on the right, the current stage: `WORK ●`, `RED ●`,
+  `idle`, or `DONE ✓` during the finish. While a subagent is still running the card stays at
+  work (`LIVE ●` when no stage is current) and never reads `DONE`, even after the main turn ended.
+- The second row is the workflow map: where the session stands in its LIT family
+  (`lib/mod/workflow.mjs`). The main chain is `interview › plan › work n/m › review › done`
+  (litgoal criteria and autoresearch iterations ride the work stage); litresearch is
+  `decompose › wave n › expand › verify › synthesis`; a lit-loop criterion cycles
+  `PIN › RED › GREEN › VERIFY › REVIEW › RECORD` (SURFACE shows on VERIFY, CLEAN on RECORD).
+  Done stages carry `✓` in a colour graded along the rail from flame orange through pink to the
+  accent, the current stage is a pill, the stages ahead are dim `name ·`. The rail into the
+  current stage is solid `━`; the rail leaving it fills with the stage's count and, while
+  LitClaude works, carries a bright head; the rails ahead are dim `─`. On its right the row keeps
+  the live subagents (`● 2 lanes`), the autoloop count and its time left, and `ctx 76% → 80%` when
+  the context nears the auto-handoff percent. A session no family places (a lit-docx request, a
+  fresh session) keeps the old `PLAN ━━ WORK ━━ REVIEW` track there.
+- The stage comes from the newest of the ignited discipline, a LitClaude skill this request
+  fired, and the stage record; with none of those, from the state that says work is under way.
+  The detail comes from files LitClaude already writes: the deep-interview state
+  (`round 3/12 · ambiguity 42% → 20%`), the lit-plan draft's approval gate (`drafting`,
+  `awaiting approval`), the start-work plan's tasks and next task, the litgoal criteria and the
+  litresearch session folder (`wave-*.md`, `verify-*.md`, `SYNTHESIS.md`). What no file
+  records goes into `.litclaude/workflow-stage.json`, a small record LitClaude's hooks keep
+  moving without the model's help. The prompt and PreToolUse hooks start it when lit-plan,
+  review-work, lit-loop, autoresearch or lit-crucible starts, and clear it for any other skill. PostToolUse checks the plan stage when lit-plan saves
+  `plans/<slug>.md` (`plan ✓`, detail `plan saved`), counts the tasks each time the active
+  start-work plan is edited (`work 1/2`), and steps a lit-loop criterion to RED when a test
+  file is written, GREEN when the code changes after it, VERIFY when the tests run and RECORD
+  when `litgoal record-evidence` runs. For review-work, PreToolUse marks a lane running when a
+  prompt titled `Review lane: <lane>.` is spawned, and the lane's `verdict:` line, read by
+  PostToolUse for a foreground reviewer and by SubagentStop for a background one, marks it
+  passed or failed. The card names the lanes `goal`, `quality`, `security`, `qa` and `context`
+  (review-work's scope/diff, package/payload, security/provenance, tests/evidence and
+  real-surface/docs lanes); five passes finish the review. The hooks keep only the stage, the
+  lane and the counts, never a path, command or prompt. The model can still refine the record
+  with `litclaude-ai workflow-stage <family> <stage> [--n --total --unit --verdict
+  name=pass|fail|pending|running]` for what the hooks cannot see: a lane run without a child
+  agent, a loop step such as SURFACE, an autoresearch iteration, the crucible verdict. Another
+  session's record is ignored and a source older than six hours no longer counts.
+- The third row is the detail line: `└` and the current stage's detail (a pink-to-cyan bar for a
+  count, the lane verdicts as `✓`, `✗`, `●` while a reviewer runs, or `·`, the next task), and on the right the live step,
+  the tool the main loop is running and for how long (`- Bash · 0:12`, `thinking` between tool
+  calls). The step shows the tool's name and its clock only, never its arguments, command,
+  prompt or paths.
+- The fourth row shows each LitFamily skill that fired as a pill: a Skill tool call naming a LitClaude
   skill, a typed `/litclaude:<name>`, or bare `lit` routing seen through the ignition record.
   A skill fired in the current request is bright, with a short light passing over its name as
   it arrives; when the turn completes it dims into the `recent` list, and a new firing brightens
   it again. Chips follow a dim `skills` label; those that do not fit collapse into a muted `+N`. Skills of other plugins never get a chip.
-  With no chip yet, the row shows the next task while work runs, or how to start (`lit <task>`)
-  while idle.
+  With no chip yet, the row shows the next task while work runs (when the detail line does not),
+  or how to start (`lit <task>`) while idle.
 - The bottom edge carries the live figures from the status line: context fill, the five-hour
   and weekly rate windows and the Git branch (read from `HEAD`, across a linked worktree).
 - A notice takes the chips row for a few seconds, with a toast, when a gate fires: lit-plan not
@@ -399,7 +436,9 @@ stops counting too, so a crashed or lost agent cannot hold the card at work.
 
 The card is the terminal's width up to 120 columns and every row is fitted to it, with Hangul and
 emoji counted as two cells. Nothing wraps: on a narrow terminal the Git branch goes first, then
-the weekly and five-hour windows, the lanes, the autoloop count and the long phase labels (`P ━ W ━ R`).
+the weekly and five-hour windows, the lanes and the autoloop count. The map drops its rails, then
+shortens the names (`int ✓ pla ✓ [wor 3/7] rev ·`), then shows only the current stage and its
+neighbours; the review verdicts shorten to three letters and then to their marks.
 
 The spinner gains ` · <discipline> · n/m` after its ellipsis. `/lit-evidence` opens a pane with
 three tabs (keys `1`, `2`, `3`): the goal's criteria with their last evidence, blockers and the
@@ -410,18 +449,31 @@ changes ease in and out (300 ms and 140 ms), notices slide in over 220 ms and le
 a chip's arrival light runs 400 ms (a plain fade under `subtle`, nothing under `off`), and the
 finish lasts at most 1.2 s. While LitClaude is at work the card keeps moving so you can tell it
 is active at a glance: the LIT pill breathes from pink to flame orange every 2.4 s, a light sweeps
-across the active phase and this request's skill chips every 1.8 s, and a comet runs along the top rule and back along the
-bottom one every 2.6 s. Under `subtle` only the breathing stays; under `off` nothing moves. An
+across the current stage and this request's skill chips every 1.8 s, a bright head runs the rail
+leaving the current stage every 1.4 s, the count bar's head shimmers, and a comet runs along the
+top rule and back along the bottom one every 2.6 s. Under `subtle` only the breathing stays; under `off` nothing moves. An
 idle card holds still. The band's `Client` element animates on Claude Code's frame clock, every
 33 ms while a transition plays and every 66 ms during work, and stops its timer once the card is
 idle and settled. In Claude
 Code 2.1.292 a terminal row whose only change is a non-ASCII glyph is not repainted, so every
 moving part changes ASCII text or colour: bar cells are coloured spaces, embers are ASCII sparks,
-a chip's light moves over its ASCII name, and a glyph swaps only together with its words.
+a chip's light moves over its ASCII name, the map's `━` and `─` cells move by colour alone, the
+step's spinner (`- \ | /`) and clock are ASCII, and a glyph swaps only together with its words.
+
+The desktop app's Code tab, and the other surfaces that are not a terminal, draw a mod's `Text` in
+a proportional font and cut each span to the cells it was laid out for, so the card above comes
+apart there. On those surfaces the mod draws the same five rows as one `Svg` element instead
+(`lib/mod/svg-card.mjs`): monospace text placed by counted cells, real pills and a rounded border.
+It shows the settled state, with no entrances or crossfades. While LitClaude works it moves with
+SMIL animation inside the drawing, which the surface runs in a script-less sandboxed frame: the
+pill and the border breathe and the step's spinner turns, and on `full` a light crosses the
+current stage and the current chips, a head runs the rail leaving it, the count bar's head
+shimmers and a comet runs around the border. An idle card is a still image. The step's clock
+moves with each new drawing, about every two seconds.
 
 Options, in `/config` under LitClaude (stored in `pluginConfigs` in `~/.claude/settings.json`,
 which the terminal and the desktop app's Code tab both read). The installer writes each default
-you have not set, so the desktop app, which has no editor for them, starts with all three;
+you have not set, so the desktop app, which has no editor for them, starts with all four;
 `litclaude-ai config` prints them and `litclaude-ai config <option> <value>` changes one.
 Uninstall removes only the defaults it wrote that are still unchanged.
 
@@ -430,6 +482,7 @@ Uninstall removes only the defaults it wrote that are still unchanged.
 | `motion` | `full`, `subtle` (no overshoot, shimmer, embers, sweep or comet, shorter; the LIT pill still breathes during work), `off` (final frames only) | `full` |
 | `glyphs` | `auto` (Nerd glyphs when the icon font is installed), `nerd`, or `basic` | `auto` |
 | `band` | `always` (the whole session, idle included), `auto` (only while work is active or a skill of this request is lit), `off` | `always` |
+| `notify` | `off`, `finish` (a notification through your own notification channel, `$.ui.notify`, when LIT work completes or a LIT turn longer than three minutes ends), `finish+sound` (the same; a sound is added once LitClaude ships one, and none ships yet) | `off` |
 
 Unknown values fall back to the default. The fields are plain strings with no `options` list on
 purpose: Claude Code 2.1.270 and older refuse to load a plugin whose `userConfig` has one, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litclaude",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "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.25",
+  "version": "1.0.27",
   "author": {
     "name": "LitClaude contributors"
   },
@@ -32,6 +32,12 @@
       "title": "LIT band",
       "description": "When the LIT card shows above the prompt: always (the whole session, idle included), auto (only while LitClaude work is active or a skill of this request is lit) or off.",
       "default": "always"
+    },
+    "notify": {
+      "type": "string",
+      "title": "LIT finish notification",
+      "description": "off, or finish: a notification through your own notification channel when LIT work completes or a LIT turn longer than three minutes ends. finish+sound also plays a sound once LitClaude ships one; until then it notifies like finish.",
+      "default": "off"
     }
   }
 }

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

@@ -6,6 +6,8 @@ import { fileURLToPath } from "node:url";
 import { standard, micro, colorMode, supportsBlocks } from "../lib/lit-mark.mjs";
 import { NEON_END, NEON_START, rainbowText } from "../lib/hud-accent-palette.mjs";
 import { ignitionMark, writeIgnitionState } from "../lib/hud-ignition.mjs";
+import { DISCIPLINE_ENTRY } from "../lib/mod/workflow.mjs";
+import { observeWorkflowPostTool, observeWorkflowPreTool, observeWorkflowSubagentStop, startWorkflowStage } from "../lib/workflow-stage.mjs";
 import { renameAliases, renameNote } from "../lib/rename-aliases.mjs";
 import { hasInterfaceModeWord, interfaceMode } from "../lib/interface-mode.mjs";
 import { transcriptHasContextPressure } from "../lib/context-pressure.mjs";
@@ -122,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",
@@ -1322,6 +1325,13 @@ switch (eventName) {
       else clearLitPlanTurn(stateRoot);
       recordInterfaceProbeTurn(stateRoot, { sessionId: input.session_id, discipline: trigger?.safetyBlock ? null : trigger?.discipline });
       recordMotionTurn(stateRoot, { sessionId: input.session_id, discipline: trigger?.discipline });
+      // The LIT card's stage record follows the discipline this prompt ignited: it starts over for a
+      // skill only it can follow and is cleared for any other.
+      // A typed `/litclaude:<skill>` is expanded by the host and never routes here, so its skill
+      // is read off the prompt's first word.
+      const typed = /^\/(?:litclaude:)?([a-z][a-z-]{0,40})(?=\s|$)/u.exec(prompt.trim())?.[1];
+      const started = trigger?.discipline && !trigger.safetyBlock ? trigger.discipline : typed && Object.hasOwn(DISCIPLINE_ENTRY, typed) ? typed : null;
+      if (started) startWorkflowStage(cwd, { sessionId: input.session_id, skill: started });
     } catch {
       // Persistence-gate state is advisory to routing; an unwritable record never alters the prompt hook.
     }
@@ -1407,6 +1417,13 @@ switch (eventName) {
           },
         }));
       } else {
+        // The LIT card's stage record: a workflow skill starts it, a review lane's reviewer marks
+        // its lane running.
+        try {
+          observeWorkflowPreTool(cwd, guardInput);
+        } catch {
+          // The stage record only feeds the card; a failed write never changes the tool decision.
+        }
         let humanizerContext = "";
         try {
           const result = evaluateDeliverableHedgeGuard({ input: guardInput, pluginRoot });
@@ -1455,6 +1472,16 @@ switch (eventName) {
   case "post-tool-use": {
     const toolName = typeof input.tool_name === "string" ? input.tool_name : "unknown";
     const filePaths = extractMutatedFilePaths(input);
+    // The LIT card's stage record moves on from what this tool did: the plan saved, a task checked
+    // in the active plan, a lit-loop step, a reviewer's verdict.
+    try {
+      const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
+      observeWorkflowPostTool(cwd, input, { filePaths, lifecycleRoot: lifecycleRootFor(cwd) });
+    } catch {
+      // The stage record only feeds the card; a failed write never changes the tool's result.
+    }
+    // A reviewer's report only moves the card; the post-edit checks below are for writes.
+    if (toolName === "Agent") break;
     try {
       const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
       observeInterfaceProbeTool(resolveProjectStateRoot(cwd), { input, filePaths });
@@ -1522,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();
@@ -1545,6 +1583,11 @@ switch (eventName) {
     } catch {
       // SubagentStop remains continuation-inert; completion will fail closed on an active lane.
     }
+    try {
+      observeWorkflowSubagentStop(typeof input.cwd === "string" ? input.cwd : process.cwd(), input);
+    } catch {
+      // A background reviewer's verdict only feeds the card.
+    }
     break;
   }
   case "session-end": {

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.25";
+const serverVersion = "1.0.27";
 
 const publicSourceReadTool = {
   name: "public_source_read",

package/plugins/litclaude/hooks/hooks.json

@@ -40,7 +40,7 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "^(Write|Edit|MultiEdit|NotebookEdit|Bash)$",
+        "matcher": "^(Write|Edit|MultiEdit|NotebookEdit|Bash|Agent)$",
         "hooks": [
           {
             "type": "command",
@@ -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": [