@litfamily/litclaude 1.0.24 → 1.0.26

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 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.
+- The card is wider. It now grows with the terminal up to 120 columns instead of 80.
+- The bottom edge shows the weekly usage window next to the five-hour one, as the status line does.
+- The installer sets up the Claude desktop app too. The app's Code tab reads the same settings as the terminal but has no editor for the card's options, so the installer now writes the defaults for `motion`, `glyphs` and `band`, keeping any value you already chose. The new `litclaude-ai config` command shows them, and `litclaude-ai config <option> <value>` changes one from a terminal. Uninstall removes only the defaults it wrote that you never changed.
+- The README demo film now opens on a title card and names each step with a numbered two-line caption, and the card pictures show the new width and the weekly window.
+
 ## 1.0.24 - 2026-10-12
 
 - The LIT card no longer drops to idle while background work is still running. When the main turn ends after starting background subagents or a workflow, the card stays at work and counts the running agents until the last one finishes, and it never reads `DONE` while an agent is still busy. A workflow's agents now count too, and a subagent that finishes in the middle of a turn no longer dims the chips of the request that is still running. An agent that never reports back stops counting after 30 quiet minutes, so it cannot hold the card at work.

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.24/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.24/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.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>
 
 <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.24/docs/assets/readme/badge-version.svg" alt="1.0.24" />
-  <a href="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.24/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.24/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+  <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>
 </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.24/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.26/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.24/docs/privacy.md)
-- [Migration and ownership conflicts](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.24/docs/migration.md)
-- [Release history](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.24/CHANGELOG.md)
-- [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litclaude@1.0.24/LICENSE)
+- [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)

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

package/bin/litclaude-ai.js

@@ -30,6 +30,7 @@ import {
   themeForAccent,
 } from "../plugins/litclaude/lib/hud-accent-palette.mjs";
 import { readPublicSource } from "../plugins/litclaude/lib/public-source-reader/reader.mjs";
+import { MOD_CHOICES } from "../plugins/litclaude/lib/mod/settings.mjs";
 import { verifyBundledSkillsIntegrity } from "../plugins/litclaude/lib/bundled-skills-integrity.mjs";
 import { verifyCanonicalFrontendCorpus } from "../plugins/litclaude/lib/canonical-frontend-corpus.mjs";
 import { verifyCanonicalRuntimeClosures } from "../plugins/litclaude/lib/canonical-runtime-closures.mjs";
@@ -38,6 +39,7 @@ 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";
@@ -80,12 +82,16 @@ const prewarmMotionRuntime = () => {
 };
 const version = packageJson.version;
 
-const usage = `Usage: litclaude-ai [--dry-run] <install|doctor|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, 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.
   run -- ...    Run Claude Code after the global plugin install.
   litgoal       Manage litgoal runtime state and evidence.
@@ -93,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.
@@ -378,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`);
@@ -720,6 +729,82 @@ const registerMarketplace = (marketplacePath, home = claudeHome()) => {
   writeKnownMarketplaces(knownMarketplaces, home);
 };
 
+// The LIT card's options live in settings.json `pluginConfigs`, which the terminal and the desktop
+// app both read; the desktop app has no editor for them, so install writes each default the user
+// has not set and records which ones it wrote. Uninstall removes only those still at that value.
+const modOptionDefaults = () => Object.fromEntries(Object.keys(MOD_CHOICES).map((key) => [key, MOD_CHOICES[key][0]]));
+const modOptionsOf = (settings) => ({ ...modOptionDefaults(), ...(settings.pluginConfigs?.[pluginKey]?.options ?? {}) });
+const modOptionsLine = (settings) => {
+  const options = modOptionsOf(settings);
+  return Object.keys(MOD_CHOICES).map((key) => `${key} ${options[key]}`).join(" · ");
+};
+
+const writeModOptions = (settings, options) => {
+  settings.pluginConfigs = settings.pluginConfigs ?? {};
+  const entry = settings.pluginConfigs[pluginKey] ?? {};
+  settings.pluginConfigs[pluginKey] = { ...entry, options: { ...(entry.options ?? {}), ...options } };
+};
+
+const installModOptions = (home = claudeHome()) => {
+  const settings = readClaudeSettings(home);
+  const present = settings.pluginConfigs?.[pluginKey]?.options ?? {};
+  const existingLitClaude = settings[litClaudeSettingsKey] ?? {};
+  const written = { ...(existingLitClaude.modOptionsWritten ?? {}) };
+  const missing = Object.fromEntries(Object.entries(modOptionDefaults()).filter(([key]) => present[key] === undefined));
+  if (Object.keys(missing).length === 0) return;
+  writeModOptions(settings, missing);
+  settings[litClaudeSettingsKey] = { ...existingLitClaude, modOptionsWritten: { ...written, ...missing } };
+  writeClaudeSettings(settings, home);
+};
+
+const uninstallModOptions = (home = claudeHome()) => {
+  if (!existsSync(claudeSettingsPath(home))) return;
+  const settings = readClaudeSettings(home);
+  const litClaude = settings[litClaudeSettingsKey];
+  if (!litClaude?.modOptionsWritten) return;
+  const entry = settings.pluginConfigs?.[pluginKey];
+  if (entry?.options) {
+    const options = { ...entry.options };
+    for (const [key, value] of Object.entries(litClaude.modOptionsWritten)) if (options[key] === value) delete options[key];
+    const rest = { ...entry };
+    if (Object.keys(options).length > 0) rest.options = options;
+    else delete rest.options;
+    if (Object.keys(rest).length > 0) settings.pluginConfigs[pluginKey] = rest;
+    else delete settings.pluginConfigs[pluginKey];
+    if (Object.keys(settings.pluginConfigs).length === 0) delete settings.pluginConfigs;
+  }
+  const remainingLitClaude = { ...litClaude };
+  delete remainingLitClaude.modOptionsWritten;
+  if (Object.keys(remainingLitClaude).length > 0) settings[litClaudeSettingsKey] = remainingLitClaude;
+  else delete settings[litClaudeSettingsKey];
+  writeClaudeSettings(settings, home);
+};
+
+// `config` prints the options; `config <option> <value>` sets one. A value the user sets is theirs,
+// so it leaves the install record and uninstall keeps it.
+const configModOptions = (rest, home = claudeHome()) => {
+  if (rest.length === 0) {
+    const options = modOptionsOf(readClaudeSettings(home));
+    for (const key of Object.keys(MOD_CHOICES)) process.stdout.write(`${key.padEnd(7)} ${options[key].padEnd(7)} (${MOD_CHOICES[key].join(", ")})\n`);
+    process.stdout.write("Change one with: litclaude-ai config <option> <value>. New Claude Code sessions, terminal or desktop app, pick it up.\n");
+    return;
+  }
+  const [key, raw] = rest;
+  if (!Object.hasOwn(MOD_CHOICES, key)) fail(`Unknown option: ${key}. Options: ${Object.keys(MOD_CHOICES).join(", ")}`, 64);
+  const value = String(raw ?? "").trim().toLowerCase();
+  if (!MOD_CHOICES[key].includes(value) || rest.length > 2) fail(`${key} takes one of: ${MOD_CHOICES[key].join(", ")}`, 64);
+  const settings = readClaudeSettings(home);
+  writeModOptions(settings, { [key]: value });
+  const litClaude = settings[litClaudeSettingsKey];
+  if (litClaude?.modOptionsWritten && Object.hasOwn(litClaude.modOptionsWritten, key)) {
+    const written = { ...litClaude.modOptionsWritten };
+    delete written[key];
+    settings[litClaudeSettingsKey] = { ...litClaude, modOptionsWritten: written };
+  }
+  writeClaudeSettings(settings, home);
+  process.stdout.write(`MOD_OPTIONS: ${modOptionsLine(settings)}\n`);
+};
+
 const ownsHudStatusLine = (settings, ownership) =>
   settings.statusLine?.type === "command" && settings.statusLine.command === ownership.statusLineCommand &&
   Object.keys(settings.statusLine).every((key) => key === "type" || key === "command");
@@ -1025,6 +1110,7 @@ const registerClaudePlugin = (installRoot, marketplacePath, home = claudeHome(),
   writeInstalledPlugins(registry, home);
   registerMarketplace(marketplacePath, home);
   installHudStatusLine(installRoot, home, hudAccent);
+  installModOptions(home);
   recordPermissionConfiguration(permissionMode, home);
 };
 
@@ -1384,6 +1470,8 @@ const install = async ({ dryRun, rest }) => {
   process.stdout.write(`Plugin path: ${intendedPluginPath(home)}\n`);
   process.stdout.write(hudManaged ? `HUD: LitClaude statusLine installed (${hudAccent})\n` : "HUD: user statusLine setting preserved\n");
   process.stdout.write(`Global Claude settings permissions.allow/deny: ${permissionMode} — ${permissionProfile(permissionMode).description}\n`);
+  process.stdout.write(`MOD_OPTIONS: ${modOptionsLine(readClaudeSettings(home))} (change: litclaude-ai config <option> <value>)\n`);
+  process.stdout.write("DESKTOP_APP: ready — the Claude desktop app's Code tab reads these same settings; open a new session there\n");
   process.stdout.write(`${prewarmMotionRuntime()}\n`);
   if (wantsIconFont) await runIconFontInstall();
   process.stdout.write("Launch with: claude\n");
@@ -1505,6 +1593,7 @@ const doctor = ({ dryRun }) => {
   process.stdout.write(`${jevStatusLine(process.env)}\n`);
   writeAutoHandoffDoctorLines();
   process.stdout.write(`${iconFontDoctorLine()}\n`);
+  process.stdout.write(`MOD_OPTIONS: ${modOptionsLine(readClaudeSettings())}\n`);
 
   // lit-typographic-motion: the five readiness probes, every run. Read-only and never fatal; a
   // missing pre-warm names the command that fixes it.
@@ -1635,6 +1724,7 @@ const uninstall = ({ dryRun }) => {
   uninstallHudStatusLine();
   uninstallOutputStyle();
   uninstallPermissionRules();
+  uninstallModOptions();
   rmSync(claudePluginRoot(), { recursive: true, force: true });
   removeEmptyDirectory(dirname(claudePluginRoot()));
   removeEmptyDirectory(pluginCacheRoot);
@@ -1730,6 +1820,9 @@ const main = async () => {
     case "doctor":
       doctor(parsed);
       break;
+    case "config":
+      configModOptions(parsed.rest);
+      break;
     case "path":
       printPath(parsed);
       break;
@@ -1748,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.24"><title>release: 1.0.24</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.24</text></g></svg>
+<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>

package/docs/hooks.md

@@ -105,10 +105,10 @@ 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. |
 | `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,40 +347,76 @@ 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% · 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
-  rate window and the Git branch (read from `HEAD`, across a linked worktree).
+  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
   saved, interface probe pending or failed, motion gate, context near the auto-handoff percent,
   auto-handoff fired. The completion moment takes it when the last task is checked, the work
@@ -397,9 +433,11 @@ chips of the current request stay bright until the main turn completes. An agent
 as ended stops counting at once, and one quiet for 30 minutes (no tool call, no status change)
 stops counting too, so a crashed or lost agent cannot hold the card at work.
 
-The card is the terminal's width up to 80 columns and every row is fitted to it, with Hangul and
+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 rate window, 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
@@ -408,19 +446,42 @@ newest litgoal ledger entries; the lanes; and the gates.
 Motion: entrances pop in 60 ms apart with a slight overshoot (160 ms each), fills and colour
 changes ease in and out (300 ms and 140 ms), notices slide in over 220 ms and leave over 150 ms,
 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. The band's `Client` element animates on Claude Code's frame
-clock only while something moves and stops its timer as soon as everything settles. In Claude
+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 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.
-
-Options, in `/config` under LitClaude (stored in `pluginConfigs`):
+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 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.
 
 | Option | Values | Default |
 | --- | --- | --- |
-| `motion` | `full`, `subtle` (no overshoot, shimmer or embers, shorter), `off` (final frames only) | `full` |
+| `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.24",
+  "version": "1.0.26",
   "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.24",
+  "version": "1.0.26",
   "author": {
     "name": "LitClaude contributors"
   },
@@ -18,7 +18,7 @@
     "motion": {
       "type": "string",
       "title": "LIT band motion",
-      "description": "How the band above the prompt moves: full, subtle (no overshoot, shimmer or embers) or off.",
+      "description": "How the band above the prompt moves: full (during work the LIT pill breathes, a light sweeps the phase and a comet runs the border), subtle (only the breathing) or off.",
       "default": "full"
     },
     "glyphs": {
@@ -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";
@@ -1322,6 +1324,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 +1416,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 +1471,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 });
@@ -1545,6 +1571,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.24";
+const serverVersion = "1.0.26";
 
 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",