@lumenflow/cli 2.9.0 → 2.11.0

package/dist/hooks/enforcement-generator.js

@@ -5,6 +5,9 @@
  * This module generates hook configurations that can be written to
  * .claude/settings.json to enforce LumenFlow workflow compliance.
  */
+import { CLAUDE_HOOKS, getHookCommand } from '@lumenflow/core';
+// Re-export for backwards compatibility (WU-1394)
+export const HOOK_SCRIPTS = CLAUDE_HOOKS.SCRIPTS;
 /**
  * Generate enforcement hooks based on configuration.
  *
@@ -20,18 +23,18 @@ export function generateEnforcementHooks(config) {
         if (config.block_outside_worktree) {
             writeEditHooks.push({
                 type: 'command',
-                command: '$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree.sh',
+                command: getHookCommand(HOOK_SCRIPTS.ENFORCE_WORKTREE),
             });
         }
         if (config.require_wu_for_edits) {
             writeEditHooks.push({
                 type: 'command',
-                command: '$CLAUDE_PROJECT_DIR/.claude/hooks/require-wu.sh',
+                command: getHookCommand(HOOK_SCRIPTS.REQUIRE_WU),
             });
         }
         if (writeEditHooks.length > 0) {
             preToolUseHooks.push({
-                matcher: 'Write|Edit',
+                matcher: CLAUDE_HOOKS.MATCHERS.WRITE_EDIT,
                 hooks: writeEditHooks,
             });
         }
@@ -43,16 +46,58 @@ export function generateEnforcementHooks(config) {
     if (config.warn_on_stop_without_wu_done) {
         hooks.stop = [
             {
-                matcher: '.*',
+                matcher: CLAUDE_HOOKS.MATCHERS.ALL,
                 hooks: [
                     {
                         type: 'command',
-                        command: '$CLAUDE_PROJECT_DIR/.claude/hooks/warn-incomplete.sh',
+                        command: getHookCommand(HOOK_SCRIPTS.WARN_INCOMPLETE),
                     },
                 ],
             },
         ];
     }
+    // Always generate PreCompact and SessionStart recovery hooks (WU-1394)
+    // These enable durable context recovery after compaction
+    hooks.preCompact = [
+        {
+            matcher: CLAUDE_HOOKS.MATCHERS.ALL,
+            hooks: [
+                {
+                    type: 'command',
+                    command: getHookCommand(HOOK_SCRIPTS.PRE_COMPACT_CHECKPOINT),
+                },
+            ],
+        },
+    ];
+    hooks.sessionStart = [
+        {
+            matcher: CLAUDE_HOOKS.MATCHERS.COMPACT,
+            hooks: [
+                {
+                    type: 'command',
+                    command: getHookCommand(HOOK_SCRIPTS.SESSION_START_RECOVERY),
+                },
+            ],
+        },
+        {
+            matcher: CLAUDE_HOOKS.MATCHERS.RESUME,
+            hooks: [
+                {
+                    type: 'command',
+                    command: getHookCommand(HOOK_SCRIPTS.SESSION_START_RECOVERY),
+                },
+            ],
+        },
+        {
+            matcher: CLAUDE_HOOKS.MATCHERS.CLEAR,
+            hooks: [
+                {
+                    type: 'command',
+                    command: getHookCommand(HOOK_SCRIPTS.SESSION_START_RECOVERY),
+                },
+            ],
+        },
+    ];
     return hooks;
 }
 /**
@@ -363,3 +408,209 @@ exit 0
 `;
     /* eslint-enable no-useless-escape */
 }
+/**
+ * Generate the pre-compact-checkpoint.sh hook script content.
+ *
+ * This PreCompact hook saves a checkpoint and writes a durable recovery file
+ * before context compaction. The recovery file survives compaction and is
+ * read by session-start-recovery.sh on the next session start.
+ *
+ * Part of WU-1394: Durable recovery pattern for context preservation.
+ */
+export function generatePreCompactCheckpointScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# pre-compact-checkpoint.sh
+#
+# PreCompact hook - auto-checkpoint + durable recovery marker (WU-1390)
+#
+# Fires before context compaction to:
+# 1. Save a checkpoint with the current WU progress
+# 2. Write a durable recovery file that survives compaction
+#
+# The recovery file is read by session-start-recovery.sh on the next
+# session start (after compact, resume, or clear) to restore context.
+#
+# Exit codes:
+#   0 = Always allow (cannot block compaction)
+#
+# Uses python3 for JSON parsing (consistent with other hooks)
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -n "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  REPO_PATH="\$CLAUDE_PROJECT_DIR"
+else
+  REPO_PATH=\$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+  if [[ -z "\$REPO_PATH" ]]; then
+    exit 0
+  fi
+fi
+
+# Read JSON input from stdin
+INPUT=\$(cat)
+
+# Parse trigger from hook input (defensive - default to "auto")
+# PreCompact provides: { "trigger": "manual" | "auto" }
+TRIGGER=\$(python3 -c "
+import json
+import sys
+try:
+    data = json.loads('''\$INPUT''')
+    trigger = data.get('trigger', 'auto')
+    print(trigger if trigger else 'auto')
+except:
+    print('auto')
+" 2>/dev/null || echo "auto")
+
+# Get WU ID from worktree context (wu:status --json)
+# Location.worktreeWuId is set when in a worktree
+WU_ID=\$(pnpm wu:status --json 2>/dev/null | python3 -c "
+import json
+import sys
+try:
+    data = json.load(sys.stdin)
+    location = data.get('location', {})
+    wu_id = location.get('worktreeWuId') or ''
+    print(wu_id)
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+# Only proceed if we have a WU ID (working in a worktree)
+if [[ -n "\$WU_ID" ]]; then
+  # Save checkpoint with pre-compact trigger
+  # Note: This may fail if CLI not built, but that's OK - recovery file is more important
+  pnpm mem:checkpoint "Auto: pre-\${TRIGGER}-compaction" --wu "\$WU_ID" --trigger "pre-compact" --quiet 2>/dev/null || true
+
+  # Write durable recovery marker (survives compaction)
+  # This is the key mechanism - file persists and is read by session-start-recovery.sh
+  RECOVERY_DIR="\${REPO_PATH}/.lumenflow/state"
+  RECOVERY_FILE="\${RECOVERY_DIR}/recovery-pending-\${WU_ID}.md"
+
+  mkdir -p "\$RECOVERY_DIR"
+
+  # Generate recovery context using mem:recover
+  # The --quiet flag outputs only the recovery context without headers
+  pnpm mem:recover --wu "\$WU_ID" --quiet > "\$RECOVERY_FILE" 2>/dev/null || {
+    # Fallback minimal recovery if mem:recover fails
+    cat > "\$RECOVERY_FILE" << EOF
+# POST-COMPACTION RECOVERY
+
+You are resuming work after context compaction. Your previous context was lost.
+**WU:** \${WU_ID}
+
+## Next Action
+Run \\\`pnpm wu:spawn --id \${WU_ID}\\\` to spawn a fresh agent with full context.
+EOF
+  }
+
+  # Output brief warning to stderr (may be compacted away, but recovery file persists)
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "⚠️  COMPACTION: Checkpoint saved for \${WU_ID}" >&2
+  echo "Recovery context: \${RECOVERY_FILE}" >&2
+  echo "Next: pnpm wu:spawn --id \${WU_ID}" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+fi
+
+# Always exit 0 - cannot block compaction
+exit 0
+`;
+    /* eslint-enable no-useless-escape */
+}
+/**
+ * Generate the session-start-recovery.sh hook script content.
+ *
+ * This SessionStart hook checks for pending recovery files written by
+ * pre-compact-checkpoint.sh and displays the recovery context to the agent.
+ * After displaying, the recovery file is deleted (one-time recovery).
+ *
+ * Part of WU-1394: Durable recovery pattern for context preservation.
+ */
+export function generateSessionStartRecoveryScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# session-start-recovery.sh
+#
+# SessionStart hook - check for pending recovery and inject context (WU-1390)
+#
+# Fires after session start (on compact, resume, or clear) to:
+# 1. Check for recovery-pending-*.md files written by pre-compact-checkpoint.sh
+# 2. Display the recovery context to the agent
+# 3. Remove the recovery file (one-time recovery)
+#
+# This completes the durable recovery pattern:
+#   PreCompact writes file → SessionStart reads and deletes it
+#
+# Exit codes:
+#   0 = Always allow (informational hook)
+#
+
+set -euo pipefail
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -n "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  REPO_PATH="\$CLAUDE_PROJECT_DIR"
+else
+  REPO_PATH=\$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+  if [[ -z "\$REPO_PATH" ]]; then
+    exit 0
+  fi
+fi
+
+RECOVERY_DIR="\${REPO_PATH}/.lumenflow/state"
+
+# Check if recovery directory exists
+if [[ ! -d "\$RECOVERY_DIR" ]]; then
+  exit 0
+fi
+
+# Find any pending recovery files
+FOUND_RECOVERY=false
+
+for recovery_file in "\$RECOVERY_DIR"/recovery-pending-*.md; do
+  # Check if glob matched any files (bash glob returns literal pattern if no match)
+  [[ -f "\$recovery_file" ]] || continue
+
+  FOUND_RECOVERY=true
+
+  # Extract WU ID from filename for display
+  WU_ID=\$(basename "\$recovery_file" | sed 's/recovery-pending-\\(.*\\)\\.md/\\1/')
+
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "⚠️  POST-COMPACTION RECOVERY DETECTED" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "" >&2
+
+  # Display the recovery context
+  cat "\$recovery_file" >&2
+
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "" >&2
+
+  # Remove after displaying (one-time recovery)
+  rm -f "\$recovery_file"
+done
+
+# Additional context if recovery was displayed
+if [[ "\$FOUND_RECOVERY" == "true" ]]; then
+  echo "IMPORTANT: Your context was compacted. Review the recovery info above." >&2
+  echo "Recommended: Run 'pnpm wu:spawn --id \$WU_ID' for fresh full context." >&2
+  echo "" >&2
+fi
+
+exit 0
+`;
+    /* eslint-enable no-useless-escape */
+}

package/dist/hooks/enforcement-sync.js

@@ -10,7 +10,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { generateEnforcementHooks, generateEnforceWorktreeScript, generateRequireWuScript, generateWarnIncompleteScript, } from './enforcement-generator.js';
+import { generateEnforcementHooks, generateEnforceWorktreeScript, generateRequireWuScript, generateWarnIncompleteScript, generatePreCompactCheckpointScript, generateSessionStartRecoveryScript, HOOK_SCRIPTS, } from './enforcement-generator.js';
 /**
  * Read LumenFlow configuration from .lumenflow.config.yaml
  *
@@ -161,6 +161,48 @@ function mergeHooksIntoSettings(existing, generated) {
             }
         }
     }
+    // Merge PreCompact hooks (WU-1394)
+    if (generated.preCompact) {
+        if (!result.hooks.PreCompact) {
+            result.hooks.PreCompact = [];
+        }
+        for (const newHook of generated.preCompact) {
+            const existingIndex = result.hooks.PreCompact.findIndex((h) => h.matcher === newHook.matcher);
+            if (existingIndex >= 0) {
+                const existing = result.hooks.PreCompact[existingIndex];
+                for (const hook of newHook.hooks) {
+                    const isDuplicate = existing.hooks.some((h) => h.command === hook.command);
+                    if (!isDuplicate) {
+                        existing.hooks.push(hook);
+                    }
+                }
+            }
+            else {
+                result.hooks.PreCompact.push(newHook);
+            }
+        }
+    }
+    // Merge SessionStart hooks (WU-1394)
+    if (generated.sessionStart) {
+        if (!result.hooks.SessionStart) {
+            result.hooks.SessionStart = [];
+        }
+        for (const newHook of generated.sessionStart) {
+            const existingIndex = result.hooks.SessionStart.findIndex((h) => h.matcher === newHook.matcher);
+            if (existingIndex >= 0) {
+                const existing = result.hooks.SessionStart[existingIndex];
+                for (const hook of newHook.hooks) {
+                    const isDuplicate = existing.hooks.some((h) => h.command === hook.command);
+                    if (!isDuplicate) {
+                        existing.hooks.push(hook);
+                    }
+                }
+            }
+            else {
+                result.hooks.SessionStart.push(newHook);
+            }
+        }
+    }
     return result;
 }
 /**
@@ -191,14 +233,18 @@ export async function syncEnforcementHooks(projectDir) {
     });
     // Write hook scripts
     if (enforcement.block_outside_worktree) {
-        writeHookScript(projectDir, 'enforce-worktree.sh', generateEnforceWorktreeScript());
+        writeHookScript(projectDir, HOOK_SCRIPTS.ENFORCE_WORKTREE, generateEnforceWorktreeScript());
     }
     if (enforcement.require_wu_for_edits) {
-        writeHookScript(projectDir, 'require-wu.sh', generateRequireWuScript());
+        writeHookScript(projectDir, HOOK_SCRIPTS.REQUIRE_WU, generateRequireWuScript());
     }
     if (enforcement.warn_on_stop_without_wu_done) {
-        writeHookScript(projectDir, 'warn-incomplete.sh', generateWarnIncompleteScript());
+        writeHookScript(projectDir, HOOK_SCRIPTS.WARN_INCOMPLETE, generateWarnIncompleteScript());
     }
+    // Always write recovery hook scripts when enforcement.hooks is enabled (WU-1394)
+    // These enable durable context recovery after compaction
+    writeHookScript(projectDir, HOOK_SCRIPTS.PRE_COMPACT_CHECKPOINT, generatePreCompactCheckpointScript());
+    writeHookScript(projectDir, HOOK_SCRIPTS.SESSION_START_RECOVERY, generateSessionStartRecoveryScript());
     // Update settings.json
     const existingSettings = readClaudeSettings(projectDir);
     const updatedSettings = mergeHooksIntoSettings(existingSettings, generatedHooks);
@@ -215,8 +261,8 @@ export async function removeEnforcementHooks(projectDir) {
     if (!settings.hooks) {
         return;
     }
-    // Remove enforcement-related hooks
-    const enforcementCommands = ['enforce-worktree.sh', 'require-wu.sh', 'warn-incomplete.sh'];
+    // Remove enforcement-related hooks (includes all LumenFlow hook scripts)
+    const enforcementCommands = Object.values(HOOK_SCRIPTS);
     if (settings.hooks.PreToolUse) {
         settings.hooks.PreToolUse = settings.hooks.PreToolUse.map((entry) => ({
             ...entry,

package/dist/init.js

@@ -12,7 +12,7 @@ import * as path from 'node:path';
 import * as yaml from 'yaml';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { getDefaultConfig, createWUParser, WU_OPTIONS } from '@lumenflow/core';
+import { getDefaultConfig, createWUParser, WU_OPTIONS, CLAUDE_HOOKS } from '@lumenflow/core';
 // WU-1067: Import GATE_PRESETS for --preset support
 import { GATE_PRESETS } from '@lumenflow/core/dist/gates-config.js';
 // WU-1171: Import merge block utilities
@@ -699,6 +699,16 @@ pnpm wu:done --id WU-XXX
 `;
 // Template for .aider.conf.yml
 const AIDER_CONF_TEMPLATE = `# Aider Configuration for LumenFlow Projects\n# See LUMENFLOW.md for workflow documentation\n\nmodel: gpt-4-turbo\nauto-commits: false\ndirty-commits: false\n\nread:\n  - LUMENFLOW.md\n  - .lumenflow/constraints.md\n`;
+// WU-1413: Template for .mcp.json (MCP server configuration for Claude Code)
+const MCP_JSON_TEMPLATE = `{
+  "mcpServers": {
+    "lumenflow": {
+      "command": "npx",
+      "args": ["@lumenflow/mcp"]
+    }
+  }
+}
+`;
 // Template for docs/04-operations/tasks/backlog.md
 const BACKLOG_TEMPLATE = `---\nsections:\n  ready:\n    heading: '## 🚀 Ready (pull from here)'\n    insertion: after_heading_blank_line\n  in_progress:\n    heading: '## 🔧 In progress'\n    insertion: after_heading_blank_line\n  blocked:\n    heading: '## ⛔ Blocked'\n    insertion: after_heading_blank_line\n  done:\n    heading: '## ✅ Done'\n    insertion: after_heading_blank_line\n---\n\n# Backlog (single source of truth)\n\n## 🚀 Ready (pull from here)\n\n(No items ready)\n\n## 🔧 In progress\n\n(No items in progress)\n\n## ⛔ Blocked\n\n(No items blocked)\n\n## ✅ Done\n\n(No items completed yet)\n`;
 // Template for docs/04-operations/tasks/status.md
@@ -2364,6 +2374,9 @@ export async function scaffoldProject(targetDir, options) {
     await createFile(path.join(targetDir, LUMENFLOW_AGENTS_DIR, '.gitkeep'), '', options.force ? 'force' : 'skip', result, targetDir);
     // WU-1342: Create .gitignore with required exclusions
     await scaffoldGitignore(targetDir, options, result);
+    // WU-1408: Scaffold safe-git wrapper and pre-commit hook
+    // These are core safety components needed for all projects
+    await scaffoldSafetyScripts(targetDir, options, result);
     // Optional: full docs scaffolding
     if (options.full) {
         await scaffoldFullDocs(targetDir, options, result, tokenDefaults);
@@ -2490,6 +2503,128 @@ const LUMENFLOW_SCRIPTS = {
     gates: 'gates',
     'gates:docs': 'gates --docs-only',
 };
+/** WU-1408: Safety script path constants */
+const SCRIPTS_DIR = 'scripts';
+const SAFE_GIT_FILE = 'safe-git';
+const HUSKY_DIR = '.husky';
+const PRE_COMMIT_FILE = 'pre-commit';
+const SAFE_GIT_TEMPLATE_PATH = 'core/scripts/safe-git.template';
+const PRE_COMMIT_TEMPLATE_PATH = 'core/.husky/pre-commit.template';
+/**
+ * WU-1408: Scaffold safety scripts (safe-git wrapper and pre-commit hook)
+ * These are core safety components needed for LumenFlow enforcement:
+ * - scripts/safe-git: Blocks dangerous git operations (e.g., manual worktree remove)
+ * - .husky/pre-commit: Blocks direct commits to main/master, enforces WU workflow
+ *
+ * Both scripts are scaffolded in all modes (full and minimal) because they are
+ * required for lumenflow-doctor to pass.
+ */
+async function scaffoldSafetyScripts(targetDir, options, result) {
+    const fileMode = getFileMode(options);
+    // Scaffold scripts/safe-git
+    const safeGitPath = path.join(targetDir, SCRIPTS_DIR, SAFE_GIT_FILE);
+    try {
+        const safeGitTemplate = loadTemplate(SAFE_GIT_TEMPLATE_PATH);
+        await createExecutableScript(safeGitPath, safeGitTemplate, fileMode, result, targetDir);
+    }
+    catch {
+        // Fallback to hardcoded template if template file not found
+        await createExecutableScript(safeGitPath, SAFE_GIT_TEMPLATE, fileMode, result, targetDir);
+    }
+    // Scaffold .husky/pre-commit
+    const preCommitPath = path.join(targetDir, HUSKY_DIR, PRE_COMMIT_FILE);
+    try {
+        const preCommitTemplate = loadTemplate(PRE_COMMIT_TEMPLATE_PATH);
+        await createExecutableScript(preCommitPath, preCommitTemplate, fileMode, result, targetDir);
+    }
+    catch {
+        // Fallback to hardcoded template if template file not found
+        await createExecutableScript(preCommitPath, PRE_COMMIT_TEMPLATE, fileMode, result, targetDir);
+    }
+}
+/**
+ * WU-1408: Fallback safe-git template
+ * Blocks dangerous git operations in LumenFlow environment
+ */
+const SAFE_GIT_TEMPLATE = `#!/bin/sh
+#
+# safe-git - LumenFlow safety wrapper for git
+#
+# Blocks dangerous operations that can corrupt agent state.
+# For all other commands, passes through to system git.
+#
+
+set -e
+
+# Block 'worktree remove'
+if [ "$1" = "worktree" ] && [ "$2" = "remove" ]; then
+  echo "" >&2
+  echo "=== LUMENFLOW SAFETY BLOCK ===" >&2
+  echo "" >&2
+  echo "BLOCKED: Manual 'git worktree remove' is unsafe in this environment." >&2
+  echo "" >&2
+  echo "REASON: Manual removal leaves orphan directories and corrupts agent state." >&2
+  echo "" >&2
+  echo "USE INSTEAD:" >&2
+  echo "  pnpm wu:done --id <ID>    (To complete a task)" >&2
+  echo "  pnpm wu:cleanup --id <ID> (To discard a task)" >&2
+  echo "==============================" >&2
+  exit 1
+fi
+
+# Pass through to real git
+exec git "$@"
+`;
+/**
+ * WU-1408: Fallback pre-commit template
+ * Blocks direct commits to main/master, allows commits on lane branches
+ * Does NOT run pnpm test (which fails on new projects)
+ */
+const PRE_COMMIT_TEMPLATE = `#!/bin/sh
+#
+# LumenFlow Pre-Commit Hook
+#
+# Enforces worktree discipline by blocking direct commits to main/master.
+# Does NOT assume pnpm test or any other commands exist.
+#
+# Rules:
+#   1. BLOCK commits to main/master (use WU workflow instead)
+#   2. ALLOW commits on lane branches (lane/*/wu-*)
+#   3. ALLOW commits on tmp/* branches (CLI micro-worktrees)
+#
+
+# Skip on tmp/* branches (CLI micro-worktrees)
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+case "$BRANCH" in tmp/*) exit 0 ;; esac
+
+# Check for force bypass
+if [ "$LUMENFLOW_FORCE" = "1" ]; then
+  exit 0
+fi
+
+# Block direct commits to main/master
+case "$BRANCH" in
+  main|master)
+    echo "" >&2
+    echo "=== DIRECT COMMIT TO \${BRANCH} BLOCKED ===" >&2
+    echo "" >&2
+    echo "LumenFlow protects main from direct commits." >&2
+    echo "" >&2
+    echo "USE INSTEAD:" >&2
+    echo "  pnpm wu:claim --id WU-XXXX --lane \\"<Lane>\\"" >&2
+    echo "  cd worktrees/<lane>-wu-xxxx" >&2
+    echo "  # Make commits in the worktree" >&2
+    echo "" >&2
+    echo "EMERGENCY BYPASS (logged):" >&2
+    echo "  LUMENFLOW_FORCE=1 git commit ..." >&2
+    echo "==========================================" >&2
+    exit 1
+    ;;
+esac
+
+# Allow commits on other branches
+exit 0
+`;
 /**
  * WU-1300: Inject LumenFlow scripts into package.json
  * - Creates package.json if it doesn't exist
@@ -2648,7 +2783,43 @@ async function scaffoldClientFiles(targetDir, options, result, tokens, client) {
         await createFile(path.join(targetDir, 'CLAUDE.md'), processTemplate(CLAUDE_MD_TEMPLATE, tokens), fileMode, result, targetDir);
         await createDirectory(path.join(targetDir, CLAUDE_AGENTS_DIR), result, targetDir);
         await createFile(path.join(targetDir, CLAUDE_AGENTS_DIR, '.gitkeep'), '', options.force ? 'force' : 'skip', result, targetDir);
-        await createFile(path.join(targetDir, CLAUDE_DIR, 'settings.json'), CLAUDE_SETTINGS_TEMPLATE, options.force ? 'force' : 'skip', result, targetDir);
+        // WU-1394: Load settings.json from template (includes PreCompact/SessionStart hooks)
+        let settingsContent;
+        try {
+            settingsContent = loadTemplate(CLAUDE_HOOKS.TEMPLATES.SETTINGS);
+        }
+        catch {
+            settingsContent = CLAUDE_SETTINGS_TEMPLATE;
+        }
+        await createFile(path.join(targetDir, CLAUDE_DIR, 'settings.json'), settingsContent, options.force ? 'force' : 'skip', result, targetDir);
+        // WU-1413: Scaffold .mcp.json for MCP server integration
+        let mcpJsonContent;
+        try {
+            mcpJsonContent = loadTemplate('core/.mcp.json.template');
+        }
+        catch {
+            mcpJsonContent = MCP_JSON_TEMPLATE;
+        }
+        await createFile(path.join(targetDir, '.mcp.json'), mcpJsonContent, fileMode, result, targetDir);
+        // WU-1394: Scaffold recovery hook scripts with executable permissions
+        const hooksDir = path.join(targetDir, CLAUDE_DIR, 'hooks');
+        await createDirectory(hooksDir, result, targetDir);
+        // Load and write pre-compact-checkpoint.sh
+        try {
+            const preCompactScript = loadTemplate(CLAUDE_HOOKS.TEMPLATES.PRE_COMPACT);
+            await createExecutableScript(path.join(hooksDir, CLAUDE_HOOKS.SCRIPTS.PRE_COMPACT_CHECKPOINT), preCompactScript, options.force ? 'force' : 'skip', result, targetDir);
+        }
+        catch {
+            // Template not found - hook won't be scaffolded
+        }
+        // Load and write session-start-recovery.sh
+        try {
+            const sessionStartScript = loadTemplate(CLAUDE_HOOKS.TEMPLATES.SESSION_START);
+            await createExecutableScript(path.join(hooksDir, CLAUDE_HOOKS.SCRIPTS.SESSION_START_RECOVERY), sessionStartScript, options.force ? 'force' : 'skip', result, targetDir);
+        }
+        catch {
+            // Template not found - hook won't be scaffolded
+        }
         // WU-1083: Scaffold Claude skills
         await scaffoldClaudeSkills(targetDir, options, result, tokens);
         // WU-1083: Scaffold agent onboarding docs for Claude vendor (even without --full)
@@ -2774,6 +2945,28 @@ function writeNewFile(filePath, content, result, relativePath) {
     fs.writeFileSync(filePath, content);
     result.created.push(relativePath);
 }
+/**
+ * WU-1394: Create an executable script file with proper permissions
+ * Similar to createFile but sets 0o755 mode for shell scripts
+ */
+async function createExecutableScript(filePath, content, mode, result, targetDir) {
+    const relativePath = getRelativePath(targetDir, filePath);
+    const resolvedMode = resolveBooleanToFileMode(mode);
+    result.merged = result.merged ?? [];
+    result.warnings = result.warnings ?? [];
+    const fileExists = fs.existsSync(filePath);
+    if (fileExists && resolvedMode === 'skip') {
+        result.skipped.push(relativePath);
+        return;
+    }
+    // Write file with executable permissions
+    const parentDir = path.dirname(filePath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content, { mode: 0o755 });
+    result.created.push(relativePath);
+}
 /**
  * CLI entry point
  * WU-1085: Updated to use parseInitOptions for proper --help support