@litfamily/litgrok 1.0.18 → 1.0.19

package/.grok/hooks/workflow-stage.mjs

@@ -0,0 +1,189 @@
+// Where the session is in the LIT workflow, for the status line's third row.
+//
+// The ledger keeps the history: a prompt that names a workflow skill carries its `stage`, and a test
+// run's PostToolUse or PostToolUseFailure record carries its `test` verdict. The status line reads only
+// the end of the ledger, so the hooks also keep a small per-session snapshot beside it,
+// `<session-hash>.workflow.json`, written only once there is something to show. Neither file holds a
+// prompt, a command line, a tool argument or tool output: only stage names, plan checkbox counts and a
+// pass or fail verdict with one count. It depends on nothing outside this folder, so the status line
+// can import it.
+
+import { randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+
+export const WORKFLOW_SCHEMA = 'litgrok.workflow/v1';
+export const STAGES = Object.freeze(['interview', 'plan', 'work', 'review', 'done']);
+const MAX_STATE_BYTES = 4096;
+const MAX_COUNT = 1_000_000;
+// The end of a long test log carries its summary.
+const RESULT_TAIL_CHARACTERS = 64 * 1024;
+
+// The first workflow skill a prompt names sets the stage. A bare `lit` starts litwork, as on row one.
+const STAGE_PATTERN = /(?:^|[\s/])(deep-interview|lit-plan|start-work|review-work|litwork|lit)(?=$|[^\w-])/iu;
+const STAGE_OF = { 'deep-interview': 'interview', 'lit-plan': 'plan', 'start-work': 'work', litwork: 'work', lit: 'work', 'review-work': 'review' };
+
+// A command counts as a test run when it calls a test runner; the command text itself is never stored.
+const TEST_COMMAND = /(?:^|[\s;&|(])(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test\b|node\s+(?:[^;&|\n]*\s)?--test\b|(?:npx\s+|bunx\s+)?(?:vitest|jest|mocha)\b|(?:python3?\s+-m\s+)?(?:pytest|unittest)\b|cargo\s+(?:test|nextest)\b|go\s+test\b|deno\s+test\b|make\s+(?:test|check)\b|(?:\.\/)?gradlew?\s+test\b|mvn\s+(?:-\S+\s+)*test\b|rspec\b|ctest\b|swift\s+test\b|dotnet\s+test\b)/u;
+const TAP_PASS = /^\s*[#ℹ]\s*pass\s+(\d+)\s*$/gmu;
+const TAP_FAIL = /^\s*[#ℹ]\s*fail\s+(\d+)\s*$/gmu;
+const PASSED = /\b(\d+)\s+(?:tests?\s+)?(?:passed|passing)\b/gu;
+const FAILED = /\b(\d+)\s+(?:tests?\s+)?(?:failed|failing)\b/gu;
+const EXIT_TEXT = /\bexit(?:ed with)?\s+(?:code|status)[\s:=]+(-?\d+)/giu;
+const EXIT_KEY = /^(?:exit_?code|exitCode|exit_?status|returncode)$/iu;
+const FAIL_MARK = /^(?:FAIL\b|not ok \d)/mu;
+
+// Heredoc bodies and quoted strings are data: a script that only mentions a test runner, such as a plan
+// check that embeds the plan's test command, is not a test run.
+function commandWords(command) {
+  const kept = [];
+  let delimiter = null;
+  for (const line of command.split('\n')) {
+    if (delimiter !== null) {
+      if (line.trim() === delimiter) delimiter = null;
+      continue;
+    }
+    kept.push(line);
+    const heredoc = /<<-?\s*(['"]?)([A-Za-z_][\w-]*)\1/u.exec(line);
+    if (heredoc) delimiter = heredoc[2];
+  }
+  return kept.join('\n').replace(/'[^'\n]*'|"(?:[^"\\\n]|\\.)*"/gu, "''");
+}
+
+export function stageFromPrompt(visibleText) {
+  if (typeof visibleText !== 'string') return null;
+  const match = STAGE_PATTERN.exec(visibleText);
+  return match ? STAGE_OF[match[1].toLowerCase()] : null;
+}
+
+function lastCount(text, pattern) {
+  let count = null;
+  for (const match of text.matchAll(pattern)) count = Number(match[1]);
+  return count !== null && Number.isSafeInteger(count) && count <= MAX_COUNT ? count : null;
+}
+
+function resultText(result) {
+  if (typeof result === 'string') return { text: result.slice(-RESULT_TAIL_CHARACTERS), exitCode: null };
+  const parts = [];
+  let exitCode = null;
+  const walk = (value, key, depth) => {
+    if (depth > 4) return;
+    if (typeof value === 'string') parts.push(value);
+    else if (typeof value === 'number' && Number.isInteger(value) && EXIT_KEY.test(key)) exitCode = value;
+    else if (value && typeof value === 'object') {
+      for (const [childKey, child] of Object.entries(value)) walk(child, childKey, depth + 1);
+    }
+  };
+  walk(result, '', 0);
+  return { text: parts.join('\n').slice(-RESULT_TAIL_CHARACTERS), exitCode };
+}
+
+/**
+ * The verdict of a test run, or null when the tool call was not a test run or its outcome cannot be
+ * read. Returns { verdict: 'pass' | 'fail', count? }: the passing count for a pass, the failing count
+ * for a fail, each only when the runner printed it.
+ */
+export function testVerdict({ toolInput, toolResult }, failed = false) {
+  const command = toolInput?.command ?? toolInput?.cmd;
+  if (typeof command !== 'string' || command.length > 16 * 1024 || !TEST_COMMAND.test(commandWords(command))) return null;
+  const { text, exitCode: exitKey } = resultText(toolResult);
+  const tapPassed = lastCount(text, TAP_PASS);
+  const tapFailed = lastCount(text, TAP_FAIL);
+  const tap = tapPassed !== null || tapFailed !== null;
+  const passed = tap ? tapPassed : lastCount(text, PASSED);
+  const failedCount = tap ? tapFailed : lastCount(text, FAILED);
+  const exitCode = exitKey ?? lastCount(text, EXIT_TEXT);
+  let verdict = null;
+  if (failed || (failedCount ?? 0) > 0) verdict = 'fail';
+  else if (exitCode !== null) verdict = exitCode === 0 ? 'pass' : 'fail';
+  else if (passed !== null) verdict = 'pass';
+  else if (FAIL_MARK.test(text)) verdict = 'fail';
+  if (verdict === null) return null;
+  const count = verdict === 'pass' ? passed : failedCount;
+  return count !== null && (verdict === 'pass' || count > 0) ? { verdict, count } : { verdict };
+}
+
+export function workflowStatePath(ledgerFile) {
+  return ledgerFile.replace(/\.jsonl$/u, '.workflow.json');
+}
+
+const isCount = (value) => Number.isSafeInteger(value) && value >= 0 && value <= MAX_COUNT;
+const isTime = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+
+function validState(state, sessionId) {
+  return state !== null && typeof state === 'object' && !Array.isArray(state)
+    && state.schema === WORKFLOW_SCHEMA && state.sessionId === sessionId
+    && (state.stage === null || STAGES.includes(state.stage))
+    && Array.isArray(state.visited) && state.visited.length <= STAGES.length && state.visited.every((stage) => STAGES.includes(stage))
+    && typeof state.ended === 'boolean'
+    && (state.plan === null || (isCount(state.plan?.done) && isCount(state.plan?.total) && state.plan.done <= state.plan.total))
+    && (state.test === null || (['pass', 'fail'].includes(state.test?.verdict) && (state.test.count === undefined || isCount(state.test.count)) && isTime(state.test.at)))
+    && isTime(state.updatedAt);
+}
+
+/** This session's snapshot, or null when it is missing, malformed, oversized, a symlink or another session's. */
+export function readWorkflowState(path, sessionId) {
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  } catch {
+    return null;
+  }
+  try {
+    const status = fstatSync(descriptor);
+    if (!status.isFile() || status.size > MAX_STATE_BYTES) return null;
+    const buffer = Buffer.alloc(status.size);
+    const state = JSON.parse(buffer.subarray(0, readSync(descriptor, buffer, 0, status.size, 0)).toString('utf8'));
+    return validState(state, sessionId) ? state : null;
+  } catch {
+    return null;
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+/**
+ * Applies one hook's news to the snapshot: { stage } when a prompt names a workflow skill, { ended }
+ * when a turn stops (true) or is held (false), { plan } and { test }. A turn that ends a review with
+ * every plan task checked moves the stage to done. Nothing is written for a session with nothing to show.
+ */
+export function updateWorkflowState(ledgerFile, sessionId, { stage, ended, plan, test, now = new Date() }) {
+  const path = workflowStatePath(ledgerFile);
+  try {
+    if (lstatSync(path).isSymbolicLink()) throw new Error('WORKFLOW_STATE_UNSAFE');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  const previous = readWorkflowState(path, sessionId);
+  const state = previous ?? { schema: WORKFLOW_SCHEMA, sessionId, stage: null, visited: [], ended: false, plan: null, test: null };
+  if (stage !== undefined && stage !== null) {
+    state.stage = stage;
+    state.ended = false;
+    if (!state.visited.includes(stage)) state.visited = STAGES.filter((name) => name === stage || state.visited.includes(name));
+  }
+  if (plan !== undefined) state.plan = plan;
+  if (test) state.test = { ...test, at: now.toISOString() };
+  if (typeof ended === 'boolean' && state.stage !== null) {
+    state.ended = ended;
+    if (ended && state.stage === 'review' && state.plan && state.plan.total > 0 && state.plan.done === state.plan.total) {
+      state.stage = 'done';
+      state.visited = STAGES.filter((name) => name === 'done' || state.visited.includes(name));
+    }
+  }
+  if (previous === null && state.stage === null && state.test === null) return null;
+  state.updatedAt = now.toISOString();
+  if (!validState(state, sessionId)) throw new Error('WORKFLOW_STATE_INVALID');
+  const content = `${JSON.stringify(state)}\n`;
+  if (Buffer.byteLength(content) > MAX_STATE_BYTES) throw new Error('WORKFLOW_STATE_TOO_LARGE');
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, content, { flag: 'wx', mode: 0o600 });
+    renameSync(temporary, path);
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+  return state;
+}

package/.grok/skills/litgrok/SKILL.md

@@ -34,13 +34,15 @@ The `lit-pptx` and `lit-docx` skill folders also ship explicitly invoked engines
 
 The `lit-typographic-motion` skill folder ships a film director (a treatment validator, a type engine for films that are the words themselves, a stage capture for authored films, a generated sound bed, look rounds), its QA gate and pinned locks; it never installs on first use: run `npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime install` once outside a Grok session to pre-warm its cache (`npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime status` shows the five pre-render probes). Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.
 
-The skills, agents, and rule are static guidance loaded from documented Grok Build paths. Hook commands and the opt-in status-line command are the package code executed by the host. The installer discovers, compares, copies, and removes package-owned `.grok/` files; only `install --user --status-line` also merges the status-line value into user config after preserving a backup.
+The skills, agents, and rule are static guidance loaded from documented Grok Build paths. Hook commands and the opt-in status-line command are the package code executed by the host. The installer discovers, compares, copies, and removes package-owned `.grok/` files; only `install --user --status-line` and `install --user --notify` also merge a value into user config after preserving a backup.
 
 ## Install destinations
 
 The project install writes the packaged tree into `<cwd>/.grok/`. The user install writes the whole packaged tree into `~/.grok/`, including skills, rules, and hooks. Use the dry-run first to preview exact destinations without mutation.
 
-`install --user --status-line` is an opt-in that adds a user-level `[ui.status_line]` command in `~/.grok/config.toml` with a two-second refresh. Grok accepts this setting only from user or administrator config, not project config or a plugin. The installer backs up an existing config before changing it and leaves any existing `ui.status_line` untouched. `uninstall --user` removes only unchanged LitGrok-managed values. This status command does not add a hook registration.
+`install --user --status-line` is an opt-in that adds a user-level `[ui.status_line]` command in `~/.grok/config.toml` with a two-second refresh. Grok accepts this setting only from user or administrator config, not project config or a plugin. The installer backs up an existing config before changing it and leaves any existing `ui.status_line` untouched. `uninstall --user` removes only unchanged LitGrok-managed values. This status command does not add a hook registration. Once a prompt names `deep-interview`, `lit-plan`, `start-work`, `litwork` or `review-work`, the command adds a workflow line (stage path, checked plan tasks, the tool in flight, the last test verdict) from the stage records the passive hooks keep; `LITGROK_HUD_LINES=1` hides it.
+
+`install --user --notify` is a separate opt-in that adds a managed `[ui.notifications]` table so Grok's own terminal notification fires when a turn completes, needs approval or fails, even while the terminal has focus. It is off by default, leaves any existing notification setting untouched, and `uninstall --user` removes only the unchanged table.
 
 Project hooks do not run merely because files exist. The user must trust the project through `/hooks-trust` or the `--trust` flow; Grok records trusted folders in `~/.grok/trusted_folders.toml`. Installation never grants trust or edits that file.
 

package/.grok-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "litgrok",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Grok Build skills, project rules, and bounded lifecycle hooks for evidence-first lit work.",
   "author": {
     "name": "LitGrok contributors"

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 1.0.19 — 2026-10-13
+
+- The status row shows where a session is in the LIT workflow. Once a prompt names `deep-interview`, `lit-plan`, `start-work`, `litwork`, a bare `lit` or `review-work`, a line such as `plan ✓ ━━━━ [WORK 3/7] ──── review · ──── done ·   ⠹ Bash · 0:31   tests ✓ 214` shows the stages passed, the current stage with the checked tasks of the newest plan, the tool running now and for how long, and the last test run. A command that only mentions a test runner inside a heredoc or a quoted string is not counted as a test run. LitGrok keeps only stage names, task counts and the test verdict, never a prompt, a command or its output.
+- `litgrok install --user --notify` turns on Grok's own terminal notification for a finished turn, an approval request or an error, even while you are looking at the terminal. It is off until you ask for it, and a user uninstall removes only the unchanged table it added.
+- The running ribbon and the live tool step now show in Grok Build 1.0.13, which sends the status line no turn start. LitGrok reads a turn in flight from its own session log instead, and stops showing it once the turn ends, fails or has been quiet for ten minutes.
+- The bright cell that moves along the workflow rail is cyan, so it stays visible on a light terminal.
+
 ## 1.0.18 — 2026-10-12
 
 - The README shows automatic handoff step by step. Each `litgrok auto-handoff` command (`on 60`, `status`, `off`) and the environment switches appear as terminal pictures with their real output, followed by the status row as the context nears your percent and the handoff is requested, and the `/compact` step that comes after.

package/README.md

@@ -1,18 +1,18 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/cover-motion-still.webp" /><source media="(prefers-reduced-motion: no-preference)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/cover-motion.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitGrok 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/litgrok@1.0.19/docs/assets/cover-motion-still.webp" /><source media="(prefers-reduced-motion: no-preference)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/cover-motion.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitGrok robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
 <h1 align="center">LitGrok</h1>
 <p align="center"><strong>Keep the work lit.</strong></p>
 
 Skills, a project rule and hooks for xAI's Grok Build that help every session plan the change, build it, check it, and leave a handoff the next session can pick up.
 
-**[Full README on GitHub](https://github.com/wjgoarxiv/litgrok#readme)** · [Guide](https://github.com/wjgoarxiv/litgrok/blob/main/docs/guide.md) · [All skills](https://github.com/wjgoarxiv/litgrok/blob/main/docs/skills.md) · [한국어](https://github.com/wjgoarxiv/litgrok/blob/main/README_ko-KR.md) · [Install](#install-in-30-seconds) · [Reference](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/reference.md)
+**[Full README on GitHub](https://github.com/wjgoarxiv/litgrok#readme)** · [Guide](https://github.com/wjgoarxiv/litgrok/blob/main/docs/guide.md) · [All skills](https://github.com/wjgoarxiv/litgrok/blob/main/docs/skills.md) · [한국어](https://github.com/wjgoarxiv/litgrok/blob/main/README_ko-KR.md) · [Install](#install-in-30-seconds) · [Reference](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/reference.md)
 
 <p align="center">
-<a href="#install-in-30-seconds"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/badge-version.svg" alt="1.0.18" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+<a href="#install-in-30-seconds"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/badge-version.svg" alt="1.0.19" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
 </p>
 
-<p align="center"><a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/reference.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install-in-30-seconds">Install</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/cover-motion.webp"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/lucide-play.svg" width="16" alt="" /> Cover motion</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a></p>
+<p align="center"><a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/reference.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install-in-30-seconds">Install</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/cover-motion.webp"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/lucide-play.svg" width="16" alt="" /> Cover motion</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a></p>
 
 Long Grok Build sessions get compacted, a new session starts without what the last one knew, and "done" often means the model said so. LitGrok gives each session a routine to follow: a written plan before the first edit, checks against that plan, and a handoff file the next session can read. It ships 38 skills, 11 agents, one project rule, and eleven hook registrations. Grok Build still runs the session and chooses the model.
 
@@ -24,7 +24,7 @@ You need Node.js and Grok Build. In an interactive terminal, from the project yo
 npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
 ```
 
-The files land in `<project>/.grok/`. Add `--user` to install under `~/.grok/` instead, or use `--package @litfamily/litgrok@1.0.18` to pin this release. Add `--dry-run` to see every destination before anything is written.
+The files land in `<project>/.grok/`. Add `--user` to install under `~/.grok/` instead, or use `--package @litfamily/litgrok@1.0.19` to pin this release. Add `--dry-run` to see every destination before anything is written.
 
 Trying a local package instead? Put its real absolute path in a variable, then run these two lines separately:
 
@@ -72,9 +72,9 @@ Beyond code, `lit-pptx` makes slide decks and `lit-docx` makes reports and Word
 
 ## What changes after install
 
-The installer copies the skills, agents, project rule, and hooks into `.grok/`. The eleven hook registrations in [`hooks/hooks.json`](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/hooks/hooks.json) run only in a trusted Git root, and they log the order of events in `.grok/litgrok/session-ledger/`. Everything runs inside your Grok session, and nothing runs in the background; when the session ends, the work waits for the next one.
+The installer copies the skills, agents, project rule, and hooks into `.grok/`. The eleven hook registrations in [`hooks/hooks.json`](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/hooks/hooks.json) run only in a trusted Git root, and they log the order of events in `.grok/litgrok/session-ledger/`. Everything runs inside your Grok session, and nothing runs in the background; when the session ends, the work waits for the next one.
 
-If you'd like a status row showing the active LitGrok skill, the model and how much context is used, add it with `install --user --status-line`. It writes `[ui.status_line]` into `~/.grok/config.toml` and backs up an existing file first.
+If you'd like a status row showing the active LitGrok skill, the model and how much context is used, add it with `install --user --status-line`. It writes `[ui.status_line]` into `~/.grok/config.toml` and backs up an existing file first. Once a prompt starts a workflow skill, the row also shows the workflow stage, the tool running now and the last test result. Add `--notify` for Grok's terminal notification when a turn finishes.
 
 ## Safety and uninstall
 
@@ -109,6 +109,6 @@ The installer never runs `git init`, trusts hooks, signs in or picks a model for
 
 If LitGrok saves you some re-explaining, a [star on GitHub](https://github.com/wjgoarxiv/litgrok) helps other Grok Build users find it.
 
-[Reference](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/reference.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/CHANGELOG.md) · [Privacy](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/privacy.md) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/LICENSE)
+[Reference](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/reference.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/CHANGELOG.md) · [Privacy](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/privacy.md) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/LICENSE)
 
 The cover is brand motion made with the LitFamily motion skill: animated artwork, with no Grok session recorded in it.

package/README_ko-KR.md

@@ -1,18 +1,18 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/cover-motion-still.webp" /><source media="(prefers-reduced-motion: no-preference)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/cover-motion.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitGrok 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/cover-motion-still.webp" /><source media="(prefers-reduced-motion: no-preference)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/cover-motion.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitGrok 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
 <h1 align="center">LitGrok</h1>
 <p align="center"><strong>Keep the work lit.</strong></p>
 
 xAI Grok Build에 스킬, 프로젝트 규칙, 훅을 더해 세션마다 계획하고, 만들고, 확인하고, 다음 세션이 이어받을 인수인계 문서를 남기게 합니다.
 
-**[GitHub에서 README 전체 보기](https://github.com/wjgoarxiv/litgrok/blob/main/README_ko-KR.md)** · [안내서](https://github.com/wjgoarxiv/litgrok/blob/main/docs/guide_ko-KR.md) · [전체 스킬](https://github.com/wjgoarxiv/litgrok/blob/main/docs/skills_ko-KR.md) · [English](https://github.com/wjgoarxiv/litgrok#readme) · [설치](#30초-설치) · [상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/reference_ko-KR.md)
+**[GitHub에서 README 전체 보기](https://github.com/wjgoarxiv/litgrok/blob/main/README_ko-KR.md)** · [안내서](https://github.com/wjgoarxiv/litgrok/blob/main/docs/guide_ko-KR.md) · [전체 스킬](https://github.com/wjgoarxiv/litgrok/blob/main/docs/skills_ko-KR.md) · [English](https://github.com/wjgoarxiv/litgrok#readme) · [설치](#30초-설치) · [상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/reference_ko-KR.md)
 
 <p align="center">
-<a href="#30초-설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/badge-version.svg" alt="1.0.18" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
+<a href="#30초-설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/badge-version.svg" alt="1.0.19" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
 </p>
 
-<p align="center"><a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/reference_ko-KR.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> 상세 안내</a> &nbsp; <a href="#30초-설치">설치</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/cover-motion.webp"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/lucide-play.svg" width="16" alt="" /> 커버 모션</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a></p>
+<p align="center"><a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/reference_ko-KR.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> 상세 안내</a> &nbsp; <a href="#30초-설치">설치</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/cover-motion.webp"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/lucide-play.svg" width="16" alt="" /> 커버 모션</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a></p>
 
 Grok Build 세션이 길어지면 대화가 압축되고, 새 세션은 앞 세션이 알던 내용을 모른 채 시작하며, "다 됐다"는 말도 모델이 그렇게 말했다는 뜻일 때가 많습니다. LitGrok은 세션마다 따라갈 순서를 줍니다. 첫 수정 전에 계획을 글로 남기고, 그 계획에 비추어 확인하고, 다음 세션이 읽을 인수인계 문서를 남깁니다. 스킬 38개, 에이전트 11개, 프로젝트 규칙 하나, 훅 등록 열한 개가 들어 있고, 세션 실행과 모델 선택은 계속 Grok Build가 맡습니다.
 
@@ -24,7 +24,7 @@ Node.js와 Grok Build가 있으면 됩니다. 써 보고 싶은 프로젝트에
 npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
 ```
 
-파일은 `<project>/.grok/`에 들어갑니다. `~/.grok/`에 설치하려면 `--user`를, 이 릴리스로 고정하려면 `--package @litfamily/litgrok@1.0.18`을 쓰세요. `--dry-run`을 붙이면 파일을 쓰기 전에 들어갈 경로를 모두 보여 줍니다.
+파일은 `<project>/.grok/`에 들어갑니다. `~/.grok/`에 설치하려면 `--user`를, 이 릴리스로 고정하려면 `--package @litfamily/litgrok@1.0.19`을 쓰세요. `--dry-run`을 붙이면 파일을 쓰기 전에 들어갈 경로를 모두 보여 줍니다.
 
 로컬 패키지로 써 보려면 실제 절대 경로를 변수에 넣고 두 줄을 따로 실행하세요.
 
@@ -72,9 +72,9 @@ npm exec --yes --package "$LITGROK_PACK" -- litgrok install
 
 ## 설치하면 달라지는 것
 
-설치 프로그램이 스킬, 에이전트, 프로젝트 규칙, 훅을 `.grok/`에 복사합니다. [`hooks/hooks.json`](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/hooks/hooks.json)에 있는 훅 등록 열한 개는 신뢰한 Git 루트에서만 동작하고, `.grok/litgrok/session-ledger/`에 이벤트 순서를 남깁니다. 모든 작업은 Grok 세션 안에서 돌고 백그라운드 작업은 없습니다. 세션이 끝나면 다음 세션이 이어받을 때까지 그 자리에 멈춰 있습니다.
+설치 프로그램이 스킬, 에이전트, 프로젝트 규칙, 훅을 `.grok/`에 복사합니다. [`hooks/hooks.json`](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/hooks/hooks.json)에 있는 훅 등록 열한 개는 신뢰한 Git 루트에서만 동작하고, `.grok/litgrok/session-ledger/`에 이벤트 순서를 남깁니다. 모든 작업은 Grok 세션 안에서 돌고 백그라운드 작업은 없습니다. 세션이 끝나면 다음 세션이 이어받을 때까지 그 자리에 멈춰 있습니다.
 
-지금 어떤 LitGrok 스킬이 동작 중인지, 어떤 모델을 쓰는지, 컨텍스트를 얼마나 썼는지 보고 싶으면 `install --user --status-line`으로 상태 행을 켜세요. `~/.grok/config.toml`에 `[ui.status_line]`을 넣고, 파일이 이미 있으면 먼저 백업합니다.
+지금 어떤 LitGrok 스킬이 동작 중인지, 어떤 모델을 쓰는지, 컨텍스트를 얼마나 썼는지 보고 싶으면 `install --user --status-line`으로 상태 행을 켜세요. `~/.grok/config.toml`에 `[ui.status_line]`을 넣고, 파일이 이미 있으면 먼저 백업합니다. 프롬프트가 작업 흐름 스킬을 시작하면 지금 단계, 돌고 있는 도구, 마지막 테스트 결과도 함께 보입니다. 턴이 끝날 때 Grok의 터미널 알림을 받으려면 `--notify`를 붙이세요.
 
 ## 안전과 제거
 
@@ -109,6 +109,6 @@ npm exec --yes --package @litfamily/litgrok@latest -- litgrok uninstall --user
 
 LitGrok 덕분에 같은 설명을 덜 반복하게 됐다면, [GitHub 스타](https://github.com/wjgoarxiv/litgrok) 하나가 다른 Grok Build 사용자에게 이 프로젝트를 알리는 데 도움이 됩니다.
 
-[상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/reference_ko-KR.md) · [변경 이력](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/CHANGELOG.md) · [개인정보](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/docs/privacy.md) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.18/LICENSE)
+[상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/reference_ko-KR.md) · [변경 이력](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/CHANGELOG.md) · [개인정보](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/docs/privacy.md) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.19/LICENSE)
 
 커버의 모션은 LitFamily 모션 스킬로 만든 브랜드 연출입니다. 그려서 움직인 그림이라 실제 Grok 세션을 녹화한 장면은 들어 있지 않습니다.

package/bin/litgrok.mjs

@@ -6,7 +6,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { renderMark, terminalMode } from '../.grok/hooks/lit-mark.mjs';
-import { installStatusLine, removeStatusLine } from './status-line-config.mjs';
+import { installNotifications, installStatusLine, removeNotifications, removeStatusLine } from './status-line-config.mjs';
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const PAYLOAD_ROOT = join(PACKAGE_ROOT, '.grok');
@@ -52,6 +52,9 @@ const PRE_MANIFEST_PAYLOAD_HASHES = Object.freeze({
   'hooks/deliverable-hedge-guard.json': '65a0008a8c51be203a385f0ca55a5e7eb9e60e487c701c08d6d2407f0a3a1170',
   'hooks/deliverable-hedge-guard.mjs': '78f997d793e94853d1ef9073fbc9dd8b1577fe756d5e8a89d4fc3859d4bde5a9',
   'hooks/plan-gate.mjs': '0477520c23776d4031e0703fc0d776a53a7e2938f5ec1a41ac0f3388bc91d7a3',
+  'hooks/post-tool-use-failure.mjs': 'b6d290bb93909a4a1a5abbba25ccc87a3ccd806a3d2810868297bab9db18b784',
+  'hooks/post-tool-use.json': 'ddccda78e32ca3f072cba48ce57a413e54e9f9da36376fadbb08eeae1fe5c95b',
+  'hooks/post-tool-use.mjs': '8984c47025285cfe2bc4a4f34edcba5921c96071703306a8c39fbc7874b73cdb',
   'hooks/record-passive-event.mjs': '9f5bd1d6c8b8e6c0be4cc61cf31f0e26f4f8a41fceb826e88567f22efa2b0090',
   'hooks/session-start.mjs': '5706ccce58340e78e435b9c1fd2224e101872ce1d0f51a9d187feb31b67c3b5d',
   'hooks/stop.mjs': 'c796f02ac3dc99716d0c2f478bf93ec35cd8a9c725de18d12895957ee261b9c3',
@@ -198,7 +201,7 @@ const PRE_MANIFEST_LEGACY_PAYLOAD_HASHES = Object.freeze({
   'skills/text-naturalization/SKILL.md': 'aa1ff8f68ab0bf71cb47818b536c4a2934da65adb413ee43ec5839b540b2df8e',
   'skills/lit-korean/SKILL.md': 'dc2e4b0ea2ff6acca904f05767a62448387571e4183a615d5e53b230704ee828',
 });
-const USAGE = 'Usage: litgrok [install|uninstall] [--user|--project] [--status-line] [--dry-run] [--no-color] [--yes]\n       litgrok auto-handoff on [percent]|off|status\n       litgrok doctor [--no-color]\n       litgrok motion-runtime install|status\nTypographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit ca251e3.\n';
+const USAGE = 'Usage: litgrok [install|uninstall] [--user|--project] [--status-line] [--notify] [--dry-run] [--no-color] [--yes]\n       litgrok auto-handoff on [percent]|off|status\n       litgrok doctor [--no-color]\n       litgrok motion-runtime install|status\nTypographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit ca251e3.\n';
 const BRAILLE_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 const SPINNER_INTERVAL_MS = 80;
 const CLEAR_LINE = '\r\u001b[2K';
@@ -207,19 +210,26 @@ function parseInstall(args) {
   const remaining = [...args];
   let command = 'install';
   if (['install', 'uninstall'].includes(remaining[0])) command = remaining.shift();
-  if (remaining.some((argument) => !['--user', '--project', '--status-line', '--dry-run', '--no-color', '--yes'].includes(argument))) return null;
+  if (remaining.some((argument) => !['--user', '--project', '--status-line', '--notify', '--dry-run', '--no-color', '--yes'].includes(argument))) return null;
   if (remaining.includes('--user') && remaining.includes('--project')) return null;
-  if (remaining.includes('--status-line') && (command !== 'install' || !remaining.includes('--user'))) return null;
+  // Both opt-ins change ~/.grok/config.toml, which only a user install may touch.
+  if ((remaining.includes('--status-line') || remaining.includes('--notify')) && (command !== 'install' || !remaining.includes('--user'))) return null;
   return {
     command,
     dryRun: remaining.includes('--dry-run'),
     noColor: remaining.includes('--no-color'),
     yes: remaining.includes('--yes'),
     statusLine: remaining.includes('--status-line'),
+    notify: remaining.includes('--notify'),
     scope: remaining.includes('--user') ? 'user' : 'project',
   };
 }
 
+// What the user-config opt-ins did, appended to the WRITE step.
+function configDetail(...results) {
+  return results.filter(Boolean).map((result) => ` · ${result.detail}`).join('');
+}
+
 function packageVersion() {
   try {
     const version = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
@@ -908,6 +918,7 @@ export async function run(args, context = {}) {
     stdout.write(`${reasons.join(' / ')} — no files written\n`);
     for (const { target } of files) stdout.write(`would ${options.command} ${target}\n`);
     if (options.statusLine) stdout.write(`would configure user status line ${join(root, 'config.toml')}\n`);
+    if (options.notify) stdout.write(`would configure user finish notification ${join(root, 'config.toml')}\n`);
     printHookTrustRequirement(files);
     return 0;
   }
@@ -988,8 +999,12 @@ export async function run(args, context = {}) {
       progress.start('WRITE');
       let removed = 0;
       let statusLineResult = null;
+      let notifyResult = null;
       try {
-        if (options.scope === 'user') statusLineResult = removeStatusLine(root);
+        if (options.scope === 'user') {
+          statusLineResult = removeStatusLine(root);
+          notifyResult = removeNotifications(root);
+        }
         for (let index = 0; index < files.length; index += 1) {
           if (!['current', 'owned'].includes(states.states[index])) continue;
           unlinkSync(files[index].target);
@@ -999,7 +1014,7 @@ export async function run(args, context = {}) {
         removeRetiredDirectories(states.retiredDirectories);
         removeEmptyPayloadDirectories(payloadDirectories(root, files));
         removeOwnershipManifest(root, states.manifest);
-        const statusDetail = statusLineResult ? ` · ${statusLineResult.detail}` : '';
+        const statusDetail = configDetail(statusLineResult, notifyResult);
         progress.finish('ok', 'WRITE', `${removed} removed · ${states.counts.missing} already absent${statusDetail}`, elapsedSince(writeStarted));
       } catch (error) {
         progress.finish('failed', 'WRITE', errorText(error), elapsedSince(writeStarted));
@@ -1014,14 +1029,16 @@ export async function run(args, context = {}) {
 
     if (states.states.every((state) => state === 'current') && states.legacyStates.every((state) => state === 'missing') && states.retiredDirectories.length === 0) {
       let statusLineResult = null;
+      let notifyResult = null;
       try {
         writeOwnershipManifest(root, files, states.manifest);
         if (options.statusLine) statusLineResult = installStatusLine(root);
+        if (options.notify) notifyResult = installNotifications(root);
       } catch (error) {
         if (error && typeof error === 'object') error.step = 'WRITE';
         throw error;
       }
-      const statusDetail = statusLineResult ? ` · ${statusLineResult.detail}` : '';
+      const statusDetail = configDetail(statusLineResult, notifyResult);
       skipStep(progress, 'WRITE', `SKIPPED · 0 written · ${states.counts.current} already-current${statusDetail}`);
       const receipt = receiptCard(options, displayRoot, colors, { status: 'Already current', written: 0, current: states.counts.current });
       progress.close();
@@ -1045,8 +1062,9 @@ export async function run(args, context = {}) {
       removeRetiredDirectories(states.retiredDirectories);
       writeOwnershipManifest(root, files, states.manifest);
       const statusLineResult = options.statusLine ? installStatusLine(root) : null;
+      const notifyResult = options.notify ? installNotifications(root) : null;
       const legacyDetail = removedLegacy === 0 ? '' : ` · ${removedLegacy} legacy removed`;
-      const statusDetail = statusLineResult ? ` · ${statusLineResult.detail}` : '';
+      const statusDetail = configDetail(statusLineResult, notifyResult);
       progress.finish('ok', 'WRITE', `${installed} written · ${states.counts.current} already-current · ${states.counts.owned} owned${legacyDetail}${statusDetail}`, elapsedSince(writeStarted));
     } catch (error) {
       progress.finish('failed', 'WRITE', errorText(error), elapsedSince(writeStarted));