workflow-ledger 0.3.6 → 0.3.8

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "workflow-ledger",
       "description": "Lightweight, recoverable workflow ledger for Claude Code projects",
-      "version": "0.3.6",
+      "version": "0.3.8",
       "source": "./",
       "author": {
         "name": "MorseWayne"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "workflow-ledger",
   "description": "Lightweight, recoverable workflow ledger for Claude Code projects",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "author": {
     "name": "MorseWayne"
   },

package/README.md

@@ -94,6 +94,8 @@ npx workflow-ledger setup --tool codex
 npx workflow-ledger setup --tool all
 ```
 
+`setup` only installs the integration so supported agents can find it. It does not activate Workflow Ledger in every project.
+
 Then initialize a project ledger from the target project root. Bare `init` asks you to choose a language first; automation can pass `--lang en` or `--lang zh-CN` to skip the prompt:
 
 ```bash
@@ -104,9 +106,9 @@ npx workflow-ledger init --tool codex --lang en
 npx workflow-ledger init --tool all --lang en
 ```
 
-`setup` installs global tool integrations. `init` creates project-local ledger files and short instruction snippets. `claude-code` uses `.claude/WORKFLOW.md`; `codex` uses `.workflow-ledger/WORKFLOW.md` plus `AGENTS.md`. The language choice controls newly created ledger templates and tool instruction snippets; existing files are not overwritten.
+`init` is the activation step. It creates project-local ledger files and short instruction snippets. Without `init`, the skill stays dormant for ordinary development work. `claude-code` uses `.claude/WORKFLOW.md`; `codex` uses `.workflow-ledger/WORKFLOW.md` plus `AGENTS.md`. The language choice controls newly created ledger templates and tool instruction snippets; existing files are not overwritten.
 
-The Bash installer remains available for Claude Code project initialization:
+The Bash installer remains available for Claude Code project initialization. It uses the Node.js CLI internally, so Node.js 18 or newer is required:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/MorseWayne/workflow-ledger/main/install.sh | bash
@@ -132,11 +134,11 @@ mkdir -p ~/.claude/skills
 cp -R skills/workflow-ledger ~/.claude/skills/workflow-ledger
 ```
 
-The installer also copies a project-local CLI to `.claude/bin/workflow-ledger`:
+The CLI can check and summarize the ledger:
 
 ```bash
-.claude/bin/workflow-ledger doctor
-.claude/bin/workflow-ledger list
+npx workflow-ledger doctor
+npx workflow-ledger list
 ```
 
 See [docs/cli.md](docs/cli.md) for command details. The CLI is an optional guardrail; it does not replace the skill workflow.
@@ -154,7 +156,7 @@ Then invoke it in Claude Code:
 A project needs two layers:
 
 1. Global tool setup with `workflow-ledger setup` so supported agents can find the workflow instructions.
-2. Project initialization with `workflow-ledger init` so the repository has a ledger file and a short tool-specific reminder.
+2. Project initialization with `workflow-ledger init` so the repository has a ledger file and a short tool-specific reminder. This is what makes Workflow Ledger active for that project.
 
 For Claude Code, `init` adds the snippet from [examples/claude-project/CLAUDE.md.snippet](examples/claude-project/CLAUDE.md.snippet) to your project's `CLAUDE.md` and creates [skills/workflow-ledger/templates/WORKFLOW.md](skills/workflow-ledger/templates/WORKFLOW.md) at `.claude/WORKFLOW.md`.
 
@@ -191,7 +193,7 @@ Resume next:
 
 | Level | Use for | Ledger? |
 |---|---|---|
-| Level 0 | Q&A, read-only explanation | No |
+| Level 0 | Q&A, read-only explanation, tagging or release-version publishing | No |
 | Level 1 | typo, docs tweak, tiny config, no behavior change | Optional |
 | Level 2 | standard code work, tests, single-module behavior changes | Yes |
 | Level 3 | new features, cross-module work, public APIs, unclear or high-risk changes | Yes, attachments optional |
@@ -224,4 +226,4 @@ Skip it for:
 
 ## Repository status
 
-This version supports both npm setup and the legacy Bash installer. The CLI can install Workflow Ledger for Claude Code, Codex, or both, while keeping the ledger format lightweight and tool-readable.
+This version uses the Node.js CLI as the single implementation for setup, init, doctor, list, and hooks. The Bash installer remains as a small bootstrap wrapper for Claude Code project initialization.

package/README.zh-CN.md

@@ -92,6 +92,8 @@ npx workflow-ledger setup --tool codex
 npx workflow-ledger setup --tool all
 ```
 
+`setup` 只安装工具接入，让支持的 agent 能找到它；它不会让 Workflow Ledger 在所有项目里自动生效。
+
 然后在目标项目根目录初始化 ledger。裸 `init` 会先交互式选择语言；自动化脚本可传 `--lang en` 或 `--lang zh-CN` 跳过交互：
 
 ```bash
@@ -102,9 +104,9 @@ npx workflow-ledger init --tool codex --lang zh-CN
 npx workflow-ledger init --tool all --lang zh-CN
 ```
 
-`setup` 安装全局工具接入；`init` 创建项目本地 ledger 和短指令片段。`claude-code` 使用 `.claude/WORKFLOW.md`；`codex` 使用 `.workflow-ledger/WORKFLOW.md` 和 `AGENTS.md`。语言选择会影响新创建的 ledger 模板和工具指令片段；已有文件不会被覆盖。
+`init` 是启用步骤。它创建项目本地 ledger 和短指令片段。没有 `init` 时，本 skill 对普通开发任务保持 dormant。`claude-code` 使用 `.claude/WORKFLOW.md`；`codex` 使用 `.workflow-ledger/WORKFLOW.md` 和 `AGENTS.md`。语言选择会影响新创建的 ledger 模板和工具指令片段；已有文件不会被覆盖。
 
-Bash 安装器仍可用于 Claude Code 项目初始化：
+Bash 安装器仍可用于 Claude Code 项目初始化。它内部使用 Node.js CLI，因此需要 Node.js 18 或更高版本：
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/MorseWayne/workflow-ledger/main/install.sh | bash
@@ -130,11 +132,11 @@ mkdir -p ~/.claude/skills
 cp -R skills/workflow-ledger ~/.claude/skills/workflow-ledger
 ```
 
-安装器也会把项目本地 CLI 复制到 `.claude/bin/workflow-ledger`：
+CLI 可以检查和汇总 ledger：
 
 ```bash
-.claude/bin/workflow-ledger doctor
-.claude/bin/workflow-ledger list
+npx workflow-ledger doctor
+npx workflow-ledger list
 ```
 
 详见 [docs/cli.md](docs/cli.md)。CLI 是可选保护栏，不替代 skill 工作流。
@@ -152,7 +154,7 @@ cp -R skills/workflow-ledger ~/.claude/skills/workflow-ledger
 项目接入分两层：
 
 1. 先用 `workflow-ledger setup` 做全局工具接入，让支持的 agent 能找到工作流指令。
-2. 再用 `workflow-ledger init` 初始化项目，让仓库里有 ledger 文件和短工具提醒。
+2. 再用 `workflow-ledger init` 初始化项目，让仓库里有 ledger 文件和短工具提醒。这一步才会让 Workflow Ledger 在该项目生效。
 
 对 Claude Code，`init` 会把 [examples/claude-project/CLAUDE.md.snippet](examples/claude-project/CLAUDE.md.snippet) 加入项目 `CLAUDE.md`，并把 [skills/workflow-ledger/templates/WORKFLOW.md](skills/workflow-ledger/templates/WORKFLOW.md) 创建到 `.claude/WORKFLOW.md`。
 
@@ -189,7 +191,7 @@ Resume next:
 
 | Level | 适用场景 | 是否写 ledger |
 |---|---|---|
-| Level 0 | 问答、只读解释 | 不需要 |
+| Level 0 | 问答、只读解释、新增 tag 或发布版本 | 不需要 |
 | Level 1 | typo、文档小改、小配置、无行为变化 | 可选 |
 | Level 2 | 标准代码修改、测试、单模块行为变更 | 需要 |
 | Level 3 | 新功能、跨模块、公共 API、不明确或高风险变更 | 需要，可选附件 |
@@ -222,4 +224,4 @@ Resume next:
 
 ## 当前状态
 
-当前版本同时支持 npm setup 和旧的 Bash installer。CLI 可以为 Claude Code、Codex 或两者安装 Workflow Ledger，同时保持 ledger 格式轻量、可被多个工具读取。
+当前版本以 Node.js CLI 作为 setup、init、doctor、list 和 hooks 的唯一实现。Bash 安装器保留为 Claude Code 项目初始化的轻量 bootstrap wrapper。

package/bin/workflow-ledger.js

@@ -7,7 +7,16 @@ const { stdin: input, stdout: output } = require('process');
 const { spawnSync } = require('child_process');
 
 const repoRoot = path.resolve(__dirname, '..');
-const targetRoot = path.resolve(process.env.WORKFLOW_LEDGER_ROOT || process.cwd());
+
+function defaultTargetRoot() {
+  if (process.env.WORKFLOW_LEDGER_ROOT) return path.resolve(process.env.WORKFLOW_LEDGER_ROOT);
+  if (path.basename(__dirname) === 'bin' && path.basename(path.dirname(__dirname)) === '.claude') {
+    return path.resolve(__dirname, '..', '..');
+  }
+  return process.cwd();
+}
+
+const targetRoot = defaultTargetRoot();
 
 const toolAliases = new Map([
   ['cc', 'claude-code'],
@@ -104,6 +113,12 @@ function copyDir(src, dest) {
   fs.cpSync(src, dest, { recursive: true });
 }
 
+function copyCli(dest) {
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(__filename, dest);
+  fs.chmodSync(dest, 0o755);
+}
+
 function appendSnippet(marker, snippetPath, targetPath, updatedMessage, keptMessage, result) {
   let current = '';
   if (fs.existsSync(targetPath)) {
@@ -186,9 +201,7 @@ function setupClaudeCodeGlobal(result) {
   const binDir = path.join(claudeDir, 'bin');
   try {
     copyDir(path.join(repoRoot, 'skills', 'workflow-ledger'), path.join(skillsDir, 'workflow-ledger'));
-    ensureDir(binDir);
-    fs.copyFileSync(path.join(repoRoot, 'bin', 'workflow-ledger'), path.join(binDir, 'workflow-ledger'));
-    fs.chmodSync(path.join(binDir, 'workflow-ledger'), 0o755);
+    copyCli(path.join(binDir, 'workflow-ledger'));
     result.configured.push('Claude Code skill → ~/.claude/skills/workflow-ledger');
     result.configured.push('Claude Code local CLI → ~/.claude/bin/workflow-ledger');
   } catch (error) {
@@ -292,29 +305,452 @@ async function initProject(args) {
   printResult('Workflow Ledger Init', result);
 }
 
-function delegateToBash(argv) {
-  const script = path.join(repoRoot, 'bin', 'workflow-ledger');
-  const result = spawnSync(script, argv, {
-    stdio: 'inherit',
-    env: { ...process.env, WORKFLOW_LEDGER_ROOT: process.env.WORKFLOW_LEDGER_ROOT || targetRoot },
-  });
-  process.exitCode = result.status ?? 1;
+function ledgerPath(root = targetRoot) {
+  return path.join(root, '.claude', 'WORKFLOW.md');
 }
 
-const args = parseArgs(process.argv.slice(2));
-async function main() {
-  if (args.command === 'help' || args.command === '-h' || args.command === '--help') {
+function hooksJsonPath(root = targetRoot) {
+  return path.join(root, '.claude', 'hooks', 'hooks.json');
+}
+
+function hookScriptPath(root = targetRoot) {
+  return path.join(root, '.claude', 'hooks', 'session-start');
+}
+
+function isExecutable(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hookStatusValue(root = targetRoot) {
+  const hooksJson = hooksJsonPath(root);
+  const hookScript = hookScriptPath(root);
+  if (!fs.existsSync(hooksJson) || !fs.existsSync(hookScript)) return 'not installed';
+  const hooksText = fs.readFileSync(hooksJson, 'utf8');
+  if (hooksText.includes('SessionStart') && hooksText.includes('.claude/hooks/session-start') && isExecutable(hookScript)) {
+    return 'installed';
+  }
+  return 'incomplete';
+}
+
+function hasSection(lines, name) {
+  return lines.some((line) => new RegExp(`^##\\s+${name}\\s*$`).test(line));
+}
+
+function formatLocalTimestamp(epochSeconds) {
+  const date = new Date(epochSeconds * 1000);
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+function cmdDoctor() {
+  const ledger = ledgerPath();
+  let errorCount = 0;
+  let warningCount = 0;
+  const out = [];
+
+  const sayError = (message) => {
+    errorCount += 1;
+    out.push(`ERROR: ${message}`);
+  };
+  const sayWarning = (message) => {
+    warningCount += 1;
+    out.push(`WARNING: ${message}`);
+  };
+  const sayInfo = (message) => out.push(`INFO: ${message}`);
+
+  if (!fs.existsSync(ledger)) {
+    sayError('.claude/WORKFLOW.md is missing.');
+    console.log(out.join('\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  let text = '';
+  try {
+    text = fs.readFileSync(ledger, 'utf8');
+  } catch {
+    sayError('.claude/WORKFLOW.md exists but cannot be read.');
+    console.log(out.join('\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const lines = text.split(/\r?\n/);
+  if (!hasSection(lines, 'Active')) sayError('Missing ## Active section.');
+  if (!hasSection(lines, 'Backlog / Future')) sayError('Missing ## Backlog / Future section.');
+  if (!hasSection(lines, 'Completed')) sayError('Missing ## Completed section.');
+
+  let activeCount = 0;
+  let backlogItems = 0;
+  let completedItems = 0;
+  let inActive = false;
+  let inBacklog = false;
+  let inCompleted = false;
+  let task = null;
+
+  const finishTask = () => {
+    if (!task) return;
+    if (task.status === 'In Progress') {
+      if (!task.currentPhase) sayError(`In Progress task '${task.title}' lacks Current phase.`);
+      if (!task.hasIntent) sayError(`In Progress task '${task.title}' lacks Intent.`);
+      if (!task.hasTodo) sayError(`In Progress task '${task.title}' lacks Current todo.`);
+      if (!task.hasResume) sayError(`In Progress task '${task.title}' lacks Resume next.`);
+      if (task.level === '2' || task.level === '3') {
+        if (!task.hasChanges) sayWarning(`Level ${task.level} task '${task.title}' lacks Changes.`);
+        if (!task.hasPrerequisites) sayWarning(`Level ${task.level} task '${task.title}' lacks Prerequisites.`);
+      }
+    }
+    if (task.status === 'Blocked') {
+      if (!task.hasBlockedBy) sayError(`Blocked task '${task.title}' lacks Blocked by.`);
+      if (!task.hasResume) sayError(`Blocked task '${task.title}' lacks Resume next.`);
+    }
+    if (task.status === 'Done' || task.status === 'Completed') {
+      if (!task.hasCloseSummary) sayWarning(`Completed task '${task.title}' is still under Active and lacks Close summary. Move it to ## Completed when closing.`);
+    }
+    if (task.lineCount > 80) sayWarning(`Task '${task.title}' has more than 80 lines.`);
+  };
+
+  for (const line of lines) {
+    if (line === '## Active') {
+      finishTask();
+      inActive = true;
+      inBacklog = false;
+      inCompleted = false;
+      task = null;
+      continue;
+    }
+    if (line === '## Backlog / Future') {
+      finishTask();
+      inActive = false;
+      inBacklog = true;
+      inCompleted = false;
+      task = null;
+      continue;
+    }
+    if (line === '## Completed') {
+      finishTask();
+      inActive = false;
+      inBacklog = false;
+      inCompleted = true;
+      task = null;
+      continue;
+    }
+    if (line.startsWith('## ')) {
+      finishTask();
+      inActive = false;
+      inBacklog = false;
+      inCompleted = false;
+      task = null;
+    }
+
+    if (inBacklog && /^-\s+(\[[ xX]\]\s+)?/.test(line)) backlogItems += 1;
+    if (inCompleted && /^###\s+/.test(line)) completedItems += 1;
+
+    if (!inActive) continue;
+    if (task) task.lineCount += 1;
+    const titleMatch = line.match(/^###\s+(.+)/);
+    if (titleMatch) {
+      finishTask();
+      activeCount += 1;
+      task = {
+        title: titleMatch[1],
+        status: '',
+        level: '',
+        currentPhase: '',
+        hasIntent: false,
+        hasTodo: false,
+        hasChanges: false,
+        hasPrerequisites: false,
+        hasResume: false,
+        hasBlockedBy: false,
+        hasCloseSummary: false,
+        lineCount: 1,
+      };
+      continue;
+    }
+    if (!task) continue;
+    const statusMatch = line.match(/^Status:\s*(.+)/);
+    if (statusMatch && !task.status) task.status = statusMatch[1];
+    const levelMatch = line.match(/^Level:\s*([0-3])/);
+    if (levelMatch) task.level = levelMatch[1];
+    const currentMatch = line.match(/^Current\s+phase:\s*(.+)/);
+    if (currentMatch) task.currentPhase = currentMatch[1];
+    if (/^Intent:/.test(line)) task.hasIntent = true;
+    if (/^Current\s+todo:/.test(line)) task.hasTodo = true;
+    if (/^Changes:/.test(line)) task.hasChanges = true;
+    if (/^Prerequisites:/.test(line)) task.hasPrerequisites = true;
+    if (/^Blocked\s+by:/.test(line)) task.hasBlockedBy = true;
+    if (/^Resume\s+next:/.test(line)) task.hasResume = true;
+    if (/^Close\s+summary:/.test(line)) task.hasCloseSummary = true;
+  }
+  finishTask();
+
+  if (backlogItems > 10) sayWarning('Backlog / Future contains more than 10 items.');
+  if (activeCount > 1) sayWarning('More than one Active task; include priority, blocker state, and Resume next if this is intentional.');
+
+  sayInfo(`Active tasks: ${activeCount}`);
+  sayInfo(`Backlog items: ${backlogItems}`);
+  sayInfo(`Completed tasks: ${completedItems}`);
+
+  let ledgerMtime = 0;
+  try {
+    ledgerMtime = Math.floor(fs.statSync(ledger).mtimeMs / 1000);
+    sayInfo(`Ledger modified: ${formatLocalTimestamp(ledgerMtime)}`);
+  } catch {
+    ledgerMtime = 0;
+  }
+
+  const inGit = spawnSync('git', ['-C', targetRoot, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' });
+  if (inGit.status === 0) {
+    const latest = spawnSync('git', ['-C', targetRoot, 'log', '-1', '--format=%ct'], { encoding: 'utf8' });
+    const commitTime = Number(latest.stdout.trim());
+    if (latest.status === 0 && Number.isFinite(commitTime) && commitTime > 0) {
+      sayInfo(`Latest git commit: ${formatLocalTimestamp(commitTime)}`);
+      if (ledgerMtime > 0 && ledgerMtime < commitTime) sayWarning('Ledger modified time is older than latest git commit.');
+    }
+  }
+
+  sayInfo(`Hooks: ${hookStatusValue()}`);
+  if (errorCount > 0) {
+    out.push(`doctor finished with ${errorCount} error(s), ${warningCount} warning(s).`);
+    process.exitCode = 1;
+  } else {
+    out.push(`doctor finished with 0 errors, ${warningCount} warning(s).`);
+  }
+  console.log(out.join('\n'));
+}
+
+function cmdList() {
+  const ledger = ledgerPath();
+  if (!fs.existsSync(ledger)) {
+    console.error('No .claude/WORKFLOW.md found; no tasks to list.');
+    return;
+  }
+
+  let text = '';
+  try {
+    text = fs.readFileSync(ledger, 'utf8');
+  } catch {
+    console.error('error: .claude/WORKFLOW.md exists but cannot be read.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const lines = text.split(/\r?\n/);
+  const out = ['Active:'];
+  let inActive = false;
+  let inBacklog = false;
+  let inCompleted = false;
+  let inResume = false;
+  let backlogItems = 0;
+  let completedItems = 0;
+  let currentTask = '';
+  let status = '';
+  let level = '';
+  let currentPhase = '';
+  let resumeNext = '';
+
+  const printTask = () => {
+    if (!currentTask) return;
+    let meta = '';
+    if (level) meta = `[Level ${level}]`;
+    if (status) meta = `${meta} ${status}`;
+    out.push(`- ${currentTask} ${meta}`);
+    if (currentPhase) out.push(`  Current phase: ${currentPhase}`);
+    if (resumeNext) out.push(`  Resume next: ${resumeNext}`);
+  };
+
+  for (const line of lines) {
+    if (line === '## Active') {
+      inActive = true;
+      inBacklog = false;
+      inCompleted = false;
+      inResume = false;
+      continue;
+    }
+    if (line === '## Backlog / Future') {
+      printTask();
+      currentTask = '';
+      inActive = false;
+      inBacklog = true;
+      inCompleted = false;
+      inResume = false;
+      continue;
+    }
+    if (line === '## Completed') {
+      printTask();
+      currentTask = '';
+      inActive = false;
+      inBacklog = false;
+      inCompleted = true;
+      inResume = false;
+      continue;
+    }
+    if (line.startsWith('## ')) {
+      printTask();
+      currentTask = '';
+      inActive = false;
+      inBacklog = false;
+      inCompleted = false;
+      inResume = false;
+    }
+
+    if (inActive) {
+      const titleMatch = line.match(/^###\s+(.+)/);
+      if (titleMatch) {
+        printTask();
+        currentTask = titleMatch[1];
+        status = '';
+        level = '';
+        currentPhase = '';
+        resumeNext = '';
+        inResume = false;
+      } else {
+        const statusMatch = line.match(/^Status:\s*(.+)/);
+        const levelMatch = line.match(/^Level:\s*([0-3])/);
+        const currentMatch = line.match(/^Current\s+phase:\s*(.+)/);
+        if (statusMatch && !status) {
+          status = statusMatch[1];
+          inResume = false;
+        } else if (levelMatch) {
+          level = levelMatch[1];
+          inResume = false;
+        } else if (currentMatch) {
+          currentPhase = currentMatch[1];
+          inResume = false;
+        } else if (/^Resume\s+next:/.test(line)) {
+          inResume = true;
+        } else if (inResume && /^-\s+(.+)/.test(line)) {
+          if (!resumeNext) resumeNext = line.replace(/^-\s+/, '');
+        } else if (line.trim()) {
+          inResume = false;
+        }
+      }
+    } else if (inBacklog && /^-\s+(\[[ xX]\]\s+)?/.test(line)) {
+      backlogItems += 1;
+    } else if (inCompleted && /^###\s+/.test(line)) {
+      completedItems += 1;
+    }
+  }
+  printTask();
+  out.push('', 'Backlog / Future:', `- ${backlogItems} items`, '', 'Completed:', `- ${completedItems} items`);
+  console.log(out.join('\n'));
+}
+
+function cmdHooksStatus() {
+  console.log(`hooks: ${hookStatusValue()}`);
+  console.log(`hooks.json: ${hooksJsonPath()}`);
+  console.log(`session-start: ${hookScriptPath()}`);
+}
+
+const DEFAULT_HOOKS_JSON = `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "command": ".claude/hooks/session-start"
+      }
+    ]
+  }
+}
+`;
+
+const DEFAULT_SESSION_START_HOOK = `#!/usr/bin/env bash
+set -u
+
+ledger=".claude/WORKFLOW.md"
+cli=".claude/bin/workflow-ledger"
+
+if [ ! -f "$ledger" ]; then
+  exit 0
+fi
+
+if [ -n "\${CLAUDE_PLUGIN_ROOT:-}" ]; then
+  cat <<'PLUGIN_JSON'
+{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"Workflow Ledger detected.\\n- Read .claude/WORKFLOW.md before resuming tracked work.\\n- Check Active tasks, Current phase/current focus, Current todo, and Resume next.\\n- Run workflow-ledger doctor if state may be stale."}}
+PLUGIN_JSON
+  exit 0
+fi
+
+printf 'Workflow Ledger detected.\\n'
+printf -- '- Read .claude/WORKFLOW.md before resuming tracked work.\\n'
+printf -- '- Check Active tasks, Current phase/current focus, Current todo, and Resume next.\\n'
+
+if [ -x "$cli" ]; then
+  printf -- '- Run .claude/bin/workflow-ledger doctor if state may be stale.\\n'
+else
+  printf -- '- Run workflow-ledger doctor if the project CLI is available.\\n'
+fi
+
+exit 0
+`;
+
+function cmdHooksInstall() {
+  const targetDir = path.join(targetRoot, '.claude', 'hooks');
+  try {
+    ensureDir(targetDir);
+  } catch {
+    console.error('error: cannot create .claude/hooks directory.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const hooksJson = hooksJsonPath();
+  const hookScript = hookScriptPath();
+  if (fs.existsSync(hooksJson)) {
+    console.log('kept existing .claude/hooks/hooks.json');
+  } else {
+    fs.writeFileSync(hooksJson, DEFAULT_HOOKS_JSON);
+    console.log('installed .claude/hooks/hooks.json');
+  }
+
+  if (fs.existsSync(hookScript)) {
+    console.log('kept existing .claude/hooks/session-start');
+  } else {
+    fs.writeFileSync(hookScript, DEFAULT_SESSION_START_HOOK, { mode: 0o755 });
+    fs.chmodSync(hookScript, 0o755);
+    console.log('installed .claude/hooks/session-start');
+  }
+}
+
+function runCommand(argv) {
+  const command = argv[0] || 'help';
+  if (command === 'help' || command === '-h' || command === '--help') {
     printHelp();
-  } else if (args.command === 'setup') {
+  } else if (command === 'setup') {
     setup(args);
-  } else if (args.command === 'init') {
-    await initProject(args);
+  } else if (command === 'init') {
+    return initProject(args);
+  } else if (command === 'doctor') {
+    cmdDoctor();
+  } else if (command === 'list') {
+    cmdList();
+  } else if (command === 'hooks') {
+    const subcommand = argv[1] || 'status';
+    if (subcommand === 'status') cmdHooksStatus();
+    else if (subcommand === 'install') cmdHooksInstall();
+    else {
+      console.error(`error: unknown hooks command: ${subcommand}`);
+      process.exitCode = 1;
+    }
   } else {
-    delegateToBash(process.argv.slice(2));
+    console.error(`error: unknown command: ${command}\n`);
+    printHelp();
+    process.exitCode = 1;
   }
 }
 
+const args = parseArgs(process.argv.slice(2));
+async function main() {
+  await runCommand(process.argv.slice(2));
+}
+
 main().catch((error) => {
   console.error(error.message);
   process.exitCode = 1;
-});
+});