workflow-ledger 0.3.5

package/bin/workflow-ledger

@@ -0,0 +1,417 @@
+#!/usr/bin/env bash
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -n "${WORKFLOW_LEDGER_ROOT:-}" ]; then
+  ROOT="$WORKFLOW_LEDGER_ROOT"
+elif [ "$(basename "$SCRIPT_DIR")" = "bin" ] && [ "$(basename "$(dirname "$SCRIPT_DIR")")" = ".claude" ]; then
+  ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+else
+  ROOT="$PWD"
+fi
+LEDGER="$ROOT/.claude/WORKFLOW.md"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+error_count=0
+warning_count=0
+
+print_help() {
+  cat <<'HELP'
+workflow-ledger — lightweight project-local workflow guardrails
+
+Usage:
+  workflow-ledger help
+  workflow-ledger init
+  workflow-ledger doctor
+  workflow-ledger list
+  workflow-ledger hooks status
+  workflow-ledger hooks install
+
+Exit codes:
+  help: always 0
+  init: 0 on created/already exists/guidance, 1 on filesystem errors
+  doctor: 0 when no errors, 1 when errors exist
+  list: 0 for readable output or missing ledger, 1 when ledger exists but cannot be read
+  hooks status: 0 when status is reported, 1 on filesystem errors
+  hooks install: 0 when installed or no-op, 1 on filesystem errors
+HELP
+}
+
+say_error() {
+  error_count=$((error_count + 1))
+  printf 'ERROR: %s\n' "$1"
+}
+
+say_warning() {
+  warning_count=$((warning_count + 1))
+  printf 'WARNING: %s\n' "$1"
+}
+
+say_info() {
+  printf 'INFO: %s\n' "$1"
+}
+
+section_exists() {
+  local name="$1"
+  grep -Eq "^##[[:space:]]+$name[[:space:]]*$" "$LEDGER"
+}
+
+hook_status_value() {
+  local hooks_json="$ROOT/.claude/hooks/hooks.json"
+  local hook_script="$ROOT/.claude/hooks/session-start"
+  if [ ! -f "$hooks_json" ] || [ ! -f "$hook_script" ]; then
+    printf 'not installed'
+    return 0
+  fi
+  if grep -Fq 'SessionStart' "$hooks_json" && grep -Fq '.claude/hooks/session-start' "$hooks_json" && [ -x "$hook_script" ]; then
+    printf 'installed'
+  else
+    printf 'incomplete'
+  fi
+}
+
+find_template() {
+  local candidates=(
+    "$ROOT/.claude/skills/workflow-ledger/templates/WORKFLOW.md"
+    "$REPO_ROOT/skills/workflow-ledger/templates/WORKFLOW.md"
+  )
+  local candidate
+  for candidate in "${candidates[@]}"; do
+    if [ -f "$candidate" ]; then
+      printf '%s' "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+cmd_init() {
+  if ! mkdir -p "$ROOT/.claude" 2>/dev/null; then
+    printf 'error: cannot create .claude directory\n' >&2
+    return 1
+  fi
+
+  if [ -f "$LEDGER" ]; then
+    printf 'kept existing .claude/WORKFLOW.md\n'
+  else
+    local template
+    if ! template="$(find_template)"; then
+      printf 'workflow-ledger skill template not found; run install.sh from the workflow-ledger checkout.\n' >&2
+      return 0
+    fi
+    if ! cp "$template" "$LEDGER" 2>/dev/null; then
+      printf 'error: cannot create .claude/WORKFLOW.md\n' >&2
+      return 1
+    fi
+    printf 'created .claude/WORKFLOW.md\n'
+  fi
+
+  if [ ! -d "$ROOT/.claude/skills/workflow-ledger" ]; then
+    printf 'note: .claude/skills/workflow-ledger is missing; run install.sh to install the skill.\n' >&2
+  fi
+  return 0
+}
+
+cmd_doctor() {
+  error_count=0
+  warning_count=0
+
+  if [ ! -f "$LEDGER" ]; then
+    say_error '.claude/WORKFLOW.md is missing.'
+    return 1
+  fi
+  if [ ! -r "$LEDGER" ]; then
+    say_error '.claude/WORKFLOW.md exists but cannot be read.'
+    return 1
+  fi
+
+  section_exists 'Active' || say_error 'Missing ## Active section.'
+  section_exists 'Backlog / Future' || say_error 'Missing ## Backlog / Future section.'
+  section_exists 'Completed' || say_error 'Missing ## Completed section.'
+
+  local active_count=0
+  local backlog_items=0
+  local completed_items=0
+  local hook_status
+  hook_status="$(hook_status_value)"
+
+  local in_active=0 in_backlog=0 in_completed=0
+  local task_title='' task_status='' task_level='' task_current=''
+  local task_has_intent=0 task_has_todo=0 task_has_changes=0 task_has_prereq=0 task_has_resume=0 task_has_blocked_by=0 task_has_close_summary=0
+  local task_line_count=0
+
+  finish_task() {
+    if [ -z "$task_title" ]; then
+      return 0
+    fi
+
+    if [ "$task_status" = 'In Progress' ]; then
+      [ -n "$task_current" ] || say_error "In Progress task '$task_title' lacks Current phase."
+      [ "$task_has_intent" -eq 1 ] || say_error "In Progress task '$task_title' lacks Intent."
+      [ "$task_has_todo" -eq 1 ] || say_error "In Progress task '$task_title' lacks Current todo."
+      [ "$task_has_resume" -eq 1 ] || say_error "In Progress task '$task_title' lacks Resume next."
+      if [ "$task_level" = '2' ] || [ "$task_level" = '3' ]; then
+        [ "$task_has_changes" -eq 1 ] || say_warning "Level $task_level task '$task_title' lacks Changes."
+        [ "$task_has_prereq" -eq 1 ] || say_warning "Level $task_level task '$task_title' lacks Prerequisites."
+      fi
+    fi
+
+    if [ "$task_status" = 'Blocked' ]; then
+      [ "$task_has_blocked_by" -eq 1 ] || say_error "Blocked task '$task_title' lacks Blocked by."
+      [ "$task_has_resume" -eq 1 ] || say_error "Blocked task '$task_title' lacks Resume next."
+    fi
+
+    if [ "$task_status" = 'Done' ] || [ "$task_status" = 'Completed' ]; then
+      [ "$task_has_close_summary" -eq 1 ] || say_warning "Completed task '$task_title' is still under Active and lacks Close summary. Move it to ## Completed when closing."
+    fi
+
+    if [ "$task_line_count" -gt 80 ]; then
+      say_warning "Task '$task_title' has more than 80 lines."
+    fi
+  }
+
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      '## Active')
+        finish_task
+        in_active=1; in_backlog=0; in_completed=0
+        task_title=''
+        continue
+        ;;
+      '## Backlog / Future')
+        finish_task
+        in_active=0; in_backlog=1; in_completed=0
+        task_title=''
+        continue
+        ;;
+      '## Completed')
+        finish_task
+        in_active=0; in_backlog=0; in_completed=1
+        task_title=''
+        continue
+        ;;
+      '## '*)
+        finish_task
+        in_active=0; in_backlog=0; in_completed=0
+        task_title=''
+        ;;
+    esac
+
+    if [ "$in_backlog" -eq 1 ] && [[ "$line" =~ ^-[[:space:]]+(\[[[:space:]xX]\][[:space:]]+)? ]]; then
+      backlog_items=$((backlog_items + 1))
+    fi
+    if [ "$in_completed" -eq 1 ] && [[ "$line" =~ ^###[[:space:]]+ ]]; then
+      completed_items=$((completed_items + 1))
+    fi
+
+    if [ "$in_active" -eq 1 ]; then
+      if [ -n "$task_title" ]; then
+        task_line_count=$((task_line_count + 1))
+      fi
+      if [[ "$line" =~ ^###[[:space:]]+(.+) ]]; then
+        finish_task
+        active_count=$((active_count + 1))
+        task_title="${BASH_REMATCH[1]}"
+        task_status=''; task_level=''; task_current=''
+        task_has_intent=0; task_has_todo=0; task_has_changes=0; task_has_prereq=0; task_has_resume=0; task_has_blocked_by=0; task_has_close_summary=0
+        task_line_count=1
+        continue
+      fi
+      [[ "$line" =~ ^Status:[[:space:]]*(.+) ]] && [ -z "$task_status" ] && task_status="${BASH_REMATCH[1]}"
+      [[ "$line" =~ ^Level:[[:space:]]*([0-3]) ]] && task_level="${BASH_REMATCH[1]}"
+      [[ "$line" =~ ^Current[[:space:]]phase:[[:space:]]*(.+) ]] && task_current="${BASH_REMATCH[1]}"
+      [[ "$line" =~ ^Intent: ]] && task_has_intent=1
+      [[ "$line" =~ ^Current[[:space:]]todo: ]] && task_has_todo=1
+      [[ "$line" =~ ^Changes: ]] && task_has_changes=1
+      [[ "$line" =~ ^Prerequisites: ]] && task_has_prereq=1
+      [[ "$line" =~ ^Blocked[[:space:]]by: ]] && task_has_blocked_by=1
+      [[ "$line" =~ ^Resume[[:space:]]next: ]] && task_has_resume=1
+      [[ "$line" =~ ^Close[[:space:]]summary: ]] && task_has_close_summary=1
+    fi
+  done < "$LEDGER"
+  finish_task
+
+  if [ "$backlog_items" -gt 10 ]; then
+    say_warning 'Backlog / Future contains more than 10 items.'
+  fi
+  if [ "$active_count" -gt 1 ]; then
+    say_warning 'More than one Active task; include priority, blocker state, and Resume next if this is intentional.'
+  fi
+
+  say_info "Active tasks: $active_count"
+  say_info "Backlog items: $backlog_items"
+  say_info "Completed tasks: $completed_items"
+  if ledger_mtime="$(stat -c %Y "$LEDGER" 2>/dev/null)"; then
+    say_info "Ledger modified: $(date -d "@$ledger_mtime" '+%Y-%m-%d %H:%M:%S' 2>/dev/null || printf '%s' "$ledger_mtime")"
+  fi
+  if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    local commit_time
+    if commit_time="$(git -C "$ROOT" log -1 --format=%ct 2>/dev/null)" && [ -n "$commit_time" ]; then
+      say_info "Latest git commit: $(date -d "@$commit_time" '+%Y-%m-%d %H:%M:%S' 2>/dev/null || printf '%s' "$commit_time")"
+      if [ -n "${ledger_mtime:-}" ] && [ "$ledger_mtime" -lt "$commit_time" ]; then
+        say_warning 'Ledger modified time is older than latest git commit.'
+      fi
+    fi
+  fi
+  say_info "Hooks: $hook_status"
+
+  if [ "$error_count" -gt 0 ]; then
+    printf 'doctor finished with %d error(s), %d warning(s).\n' "$error_count" "$warning_count"
+    return 1
+  fi
+  printf 'doctor finished with 0 errors, %d warning(s).\n' "$warning_count"
+  return 0
+}
+
+cmd_list() {
+  if [ ! -f "$LEDGER" ]; then
+    printf 'No .claude/WORKFLOW.md found; no tasks to list.\n' >&2
+    return 0
+  fi
+  if [ ! -r "$LEDGER" ]; then
+    printf 'error: .claude/WORKFLOW.md exists but cannot be read.\n' >&2
+    return 1
+  fi
+
+  local in_active=0 in_backlog=0 in_completed=0 in_resume=0
+  local backlog_items=0 completed_items=0
+  local current_task='' status='' level='' current_phase='' resume_next=''
+
+  print_task() {
+    if [ -n "$current_task" ]; then
+      local meta=''
+      [ -n "$level" ] && meta="[Level $level]"
+      [ -n "$status" ] && meta="$meta $status"
+      printf -- '- %s %s\n' "$current_task" "$meta"
+      [ -n "$current_phase" ] && printf '  Current phase: %s\n' "$current_phase"
+      [ -n "$resume_next" ] && printf '  Resume next: %s\n' "$resume_next"
+    fi
+  }
+
+  printf 'Active:\n'
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      '## Active') in_active=1; in_backlog=0; in_completed=0; in_resume=0; continue ;;
+      '## Backlog / Future') print_task; current_task=''; in_active=0; in_backlog=1; in_completed=0; in_resume=0; continue ;;
+      '## Completed') print_task; current_task=''; in_active=0; in_backlog=0; in_completed=1; in_resume=0; continue ;;
+      '## '*) print_task; current_task=''; in_active=0; in_backlog=0; in_completed=0; in_resume=0 ;;
+    esac
+    if [ "$in_active" -eq 1 ]; then
+      if [[ "$line" =~ ^###[[:space:]]+(.+) ]]; then
+        print_task
+        current_task="${BASH_REMATCH[1]}"; status=''; level=''; current_phase=''; resume_next=''; in_resume=0
+      elif [[ "$line" =~ ^Status:[[:space:]]*(.+) ]] && [ -z "$status" ]; then
+        status="${BASH_REMATCH[1]}"
+        in_resume=0
+      elif [[ "$line" =~ ^Level:[[:space:]]*([0-3]) ]]; then
+        level="${BASH_REMATCH[1]}"
+        in_resume=0
+      elif [[ "$line" =~ ^Current[[:space:]]phase:[[:space:]]*(.+) ]]; then
+        current_phase="${BASH_REMATCH[1]}"
+        in_resume=0
+      elif [[ "$line" =~ ^Resume[[:space:]]next: ]]; then
+        in_resume=1
+      elif [ "$in_resume" -eq 1 ] && [[ "$line" =~ ^-[[:space:]]+(.+) ]]; then
+        [ -z "$resume_next" ] && resume_next="${BASH_REMATCH[1]}"
+      elif [[ -n "$line" && ! "$line" =~ ^[[:space:]]*$ ]]; then
+        in_resume=0
+      fi
+    elif [ "$in_backlog" -eq 1 ] && [[ "$line" =~ ^-[[:space:]]+(\[[[:space:]xX]\][[:space:]]+)? ]]; then
+      backlog_items=$((backlog_items + 1))
+    elif [ "$in_completed" -eq 1 ] && [[ "$line" =~ ^###[[:space:]]+ ]]; then
+      completed_items=$((completed_items + 1))
+    fi
+  done < "$LEDGER"
+  print_task
+  printf '\nBacklog / Future:\n- %d items\n\nCompleted:\n- %d items\n' "$backlog_items" "$completed_items"
+}
+
+cmd_hooks_status() {
+  local hooks_json="$ROOT/.claude/hooks/hooks.json"
+  local hook_script="$ROOT/.claude/hooks/session-start"
+  printf 'hooks: %s\n' "$(hook_status_value)"
+  printf 'hooks.json: %s\n' "$hooks_json"
+  printf 'session-start: %s\n' "$hook_script"
+  return 0
+}
+
+cmd_hooks_install() {
+  local target_dir="$ROOT/.claude/hooks"
+  if ! mkdir -p "$target_dir" 2>/dev/null; then
+    printf 'error: cannot create .claude/hooks directory.\n' >&2
+    return 1
+  fi
+  if [ -e "$target_dir/hooks.json" ]; then
+    printf 'kept existing .claude/hooks/hooks.json\n'
+  else
+    cat > "$target_dir/hooks.json" <<'HOOKS_JSON'
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "command": ".claude/hooks/session-start"
+      }
+    ]
+  }
+}
+HOOKS_JSON
+    printf 'installed .claude/hooks/hooks.json\n'
+  fi
+  if [ -e "$target_dir/session-start" ]; then
+    printf 'kept existing .claude/hooks/session-start\n'
+  else
+    cat > "$target_dir/session-start" <<'HOOK_SCRIPT'
+#!/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
+HOOK_SCRIPT
+    chmod +x "$target_dir/session-start" || return 1
+    printf 'installed .claude/hooks/session-start\n'
+  fi
+}
+main() {
+  local cmd="${1:-help}"
+  case "$cmd" in
+    help|-h|--help) print_help; return 0 ;;
+    init) shift; cmd_init "$@" ;;
+    doctor) shift; cmd_doctor "$@" ;;
+    list) shift; cmd_list "$@" ;;
+    hooks)
+      local sub="${2:-status}"
+      case "$sub" in
+        status) cmd_hooks_status ;;
+        install) cmd_hooks_install ;;
+        *) printf 'error: unknown hooks command: %s\n' "$sub" >&2; return 1 ;;
+      esac
+      ;;
+    *) printf 'error: unknown command: %s\n\n' "$cmd" >&2; print_help; return 1 ;;
+  esac
+}
+
+main "$@"

package/bin/workflow-ledger.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const repoRoot = path.resolve(__dirname, '..');
+const targetRoot = path.resolve(process.env.WORKFLOW_LEDGER_ROOT || process.cwd());
+
+const toolAliases = new Map([
+  ['cc', 'claude-code'],
+  ['claude', 'claude-code'],
+  ['claude-code', 'claude-code'],
+  ['codex', 'codex'],
+  ['all', 'all'],
+]);
+
+function printHelp() {
+  console.log(`workflow-ledger — lightweight workflow guardrails for AI coding agents
+
+Usage:
+  workflow-ledger setup [--tool claude-code|codex|all]
+  workflow-ledger init [--tool claude-code|codex|all] [--root PATH]
+  workflow-ledger help
+  workflow-ledger doctor
+  workflow-ledger list
+  workflow-ledger hooks status
+  workflow-ledger hooks install
+
+setup installs global tool integrations. init creates project-local ledger files.`);
+}
+
+function parseArgs(argv) {
+  const args = { command: argv[0] || 'help', tool: 'claude-code', root: targetRoot };
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--tool') {
+      args.tool = argv[i + 1] || '';
+      i += 1;
+    } else if (arg.startsWith('--tool=')) {
+      args.tool = arg.slice('--tool='.length);
+    } else if (arg === '--root') {
+      args.root = path.resolve(argv[i + 1] || '.');
+      i += 1;
+    } else if (arg.startsWith('--root=')) {
+      args.root = path.resolve(arg.slice('--root='.length));
+    }
+  }
+  args.tool = toolAliases.get(args.tool) || args.tool;
+  return args;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function dirExists(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function copyFileIfMissing(src, dest, createdMessage, keptMessage, result) {
+  if (fs.existsSync(dest)) {
+    result.configured.push(keptMessage);
+    return;
+  }
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+  result.configured.push(createdMessage);
+}
+
+function copyDir(src, dest) {
+  fs.rmSync(dest, { recursive: true, force: true });
+  ensureDir(path.dirname(dest));
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+function appendSnippet(marker, snippetPath, targetPath, updatedMessage, keptMessage, result) {
+  let current = '';
+  if (fs.existsSync(targetPath)) {
+    current = fs.readFileSync(targetPath, 'utf8');
+  } else {
+    ensureDir(path.dirname(targetPath));
+  }
+  if (current.includes(marker)) {
+    result.configured.push(keptMessage);
+    return;
+  }
+  const prefix = current.length > 0 && !current.endsWith('\n') ? '\n\n' : current.length > 0 ? '\n' : '';
+  fs.appendFileSync(targetPath, `${prefix}${fs.readFileSync(snippetPath, 'utf8')}`);
+  result.configured.push(updatedMessage);
+}
+
+function validateTool(tool) {
+  if (!['claude-code', 'codex', 'all'].includes(tool)) {
+    console.error(`error: unknown tool '${tool}'. Expected claude-code, codex, or all.`);
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
+function createResult() {
+  return { configured: [], skipped: [], errors: [] };
+}
+
+function printResult(title, result) {
+  console.log(`\n${title}`);
+  if (result.configured.length > 0) {
+    console.log('Configured:');
+    for (const item of result.configured) console.log(`  + ${item}`);
+  }
+  if (result.skipped.length > 0) {
+    console.log('Skipped:');
+    for (const item of result.skipped) console.log(`  - ${item}`);
+  }
+  if (result.errors.length > 0) {
+    console.log('Errors:');
+    for (const item of result.errors) console.log(`  ! ${item}`);
+    process.exitCode = 1;
+  }
+}
+
+function setupClaudeCodeGlobal(result) {
+  const claudeDir = path.join(os.homedir(), '.claude');
+  if (!dirExists(claudeDir)) {
+    result.skipped.push('Claude Code (not installed)');
+    return;
+  }
+  const skillsDir = path.join(claudeDir, 'skills');
+  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);
+    result.configured.push('Claude Code skill → ~/.claude/skills/workflow-ledger');
+    result.configured.push('Claude Code local CLI → ~/.claude/bin/workflow-ledger');
+  } catch (error) {
+    result.errors.push(`Claude Code: ${error.message}`);
+  }
+}
+
+function setupCodexGlobal(result) {
+  const codexDir = path.join(os.homedir(), '.codex');
+  if (!dirExists(codexDir)) {
+    result.skipped.push('Codex (not installed)');
+    return;
+  }
+  const skillDir = path.join(os.homedir(), '.agents', 'skills', 'workflow-ledger');
+  try {
+    ensureDir(skillDir);
+    fs.copyFileSync(path.join(repoRoot, 'examples', 'codex-project', 'AGENTS.md.snippet'), path.join(skillDir, 'SKILL.md'));
+    result.configured.push('Codex skill → ~/.agents/skills/workflow-ledger');
+  } catch (error) {
+    result.errors.push(`Codex: ${error.message}`);
+  }
+}
+
+function setup(args) {
+  if (!validateTool(args.tool)) return;
+  const result = createResult();
+  if (args.tool === 'claude-code' || args.tool === 'all') setupClaudeCodeGlobal(result);
+  if (args.tool === 'codex' || args.tool === 'all') setupCodexGlobal(result);
+  printResult('Workflow Ledger Setup', result);
+  console.log('\nNext: run workflow-ledger init in a project.');
+}
+
+function initClaudeCodeProject(root, result) {
+  const claudeDir = path.join(root, '.claude');
+  ensureDir(claudeDir);
+  copyFileIfMissing(
+    path.join(repoRoot, 'skills', 'workflow-ledger', 'templates', 'WORKFLOW.md'),
+    path.join(claudeDir, 'WORKFLOW.md'),
+    'created .claude/WORKFLOW.md',
+    'kept existing .claude/WORKFLOW.md',
+    result
+  );
+  appendSnippet(
+    '## Workflow Ledger',
+    path.join(repoRoot, 'examples', 'claude-project', 'CLAUDE.md.snippet'),
+    path.join(root, 'CLAUDE.md'),
+    'updated CLAUDE.md',
+    'kept existing Workflow Ledger section in CLAUDE.md',
+    result
+  );
+}
+
+function initCodexProject(root, result) {
+  const ledgerDir = path.join(root, '.workflow-ledger');
+  ensureDir(ledgerDir);
+  copyFileIfMissing(
+    path.join(repoRoot, 'templates', 'WORKFLOW.md'),
+    path.join(ledgerDir, 'WORKFLOW.md'),
+    'created .workflow-ledger/WORKFLOW.md',
+    'kept existing .workflow-ledger/WORKFLOW.md',
+    result
+  );
+  appendSnippet(
+    '# Workflow Ledger',
+    path.join(repoRoot, 'examples', 'codex-project', 'AGENTS.md.snippet'),
+    path.join(root, 'AGENTS.md'),
+    'updated AGENTS.md',
+    'kept existing Workflow Ledger section in AGENTS.md',
+    result
+  );
+}
+
+function initProject(args) {
+  if (!validateTool(args.tool)) return;
+  const result = createResult();
+  ensureDir(args.root);
+  if (args.tool === 'claude-code' || args.tool === 'all') initClaudeCodeProject(args.root, result);
+  if (args.tool === 'codex' || args.tool === 'all') initCodexProject(args.root, result);
+  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;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.command === 'help' || args.command === '-h' || args.command === '--help') {
+  printHelp();
+} else if (args.command === 'setup') {
+  setup(args);
+} else if (args.command === 'init') {
+  initProject(args);
+} else {
+  delegateToBash(process.argv.slice(2));
+}