@lumenflow/cli 2.9.0 → 2.10.0

package/README.md

@@ -134,7 +134,7 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 | Command           | Description                                                                                |
 | ----------------- | ------------------------------------------------------------------------------------------ |
 | `gates`           | Run quality gates with support for docs-only mode, incremental linting, and tiered testing |
-| `lumenflow-gates` | Alias for `gates` - run quality gates                                                      |
+| `lumenflow-gates` | Alias for `gates` - run quality gates with support for docs-only mode and tiered testing   |
 
 ### System & Setup
 

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
@@ -2648,7 +2648,34 @@ 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-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 +2801,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

package/dist/mem-recover.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Memory Recover CLI (WU-1390)
+ *
+ * Generate post-compaction recovery context for agents that have lost
+ * their LumenFlow instructions due to context compaction.
+ *
+ * Usage:
+ *   pnpm mem:recover --wu WU-XXXX [options]
+ *
+ * Options:
+ *   --max-size <bytes>     Maximum output size in bytes (default: 2048)
+ *   --format <json|human>  Output format (default: human)
+ *   --quiet                Suppress header/footer output
+ *
+ * The recovery context includes:
+ * - Last checkpoint for the WU
+ * - Compact constraints (7 rules)
+ * - Essential CLI commands
+ * - Guidance to spawn fresh agent
+ *
+ * @see {@link packages/@lumenflow/memory/src/mem-recover-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/memory/__tests__/mem-recover-core.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { generateRecoveryContext } from '@lumenflow/memory/dist/mem-recover-core.js';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { EXIT_CODES, LUMENFLOW_PATHS } from '@lumenflow/core/dist/wu-constants.js';
+/**
+ * Log prefix for mem:recover output
+ */
+const LOG_PREFIX = '[mem:recover]';
+/**
+ * Tool name for audit logging
+ */
+const TOOL_NAME = 'mem:recover';
+/**
+ * Valid output formats
+ */
+const VALID_FORMATS = ['json', 'human'];
+/**
+ * CLI argument options specific to mem:recover
+ */
+const CLI_OPTIONS = {
+    maxSize: {
+        name: 'maxSize',
+        flags: '-m, --max-size <bytes>',
+        description: 'Maximum output size in bytes (default: 2048)',
+    },
+    format: {
+        name: 'format',
+        flags: '-f, --format <format>',
+        description: 'Output format: json or human (default: human)',
+    },
+    baseDir: {
+        name: 'baseDir',
+        flags: '-d, --base-dir <path>',
+        description: 'Base directory (defaults to current directory)',
+    },
+    quiet: {
+        name: 'quiet',
+        flags: '-q, --quiet',
+        description: 'Suppress header/footer output, only show recovery context',
+    },
+};
+/**
+ * Write audit log entry for tool execution
+ */
+async function writeAuditLog(baseDir, entry) {
+    try {
+        const logPath = path.join(baseDir, LUMENFLOW_PATHS.AUDIT_LOG);
+        const logDir = path.dirname(logPath);
+        await fs.mkdir(logDir, { recursive: true });
+        const line = `${JSON.stringify(entry)}\n`;
+        await fs.appendFile(logPath, line, 'utf-8');
+    }
+    catch {
+        // Audit logging is non-fatal - silently ignore errors
+    }
+}
+/**
+ * Validate and parse a positive integer argument
+ */
+function parsePositiveInt(value, optionName) {
+    if (!value) {
+        return undefined;
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed) || parsed <= 0) {
+        throw new Error(`Invalid ${optionName} value: "${value}". Must be a positive integer.`);
+    }
+    return parsed;
+}
+/**
+ * Validate format argument
+ */
+function validateFormat(format) {
+    if (!format) {
+        return 'human';
+    }
+    if (!VALID_FORMATS.includes(format)) {
+        throw new Error(`Invalid --format value: "${format}". Valid formats: ${VALID_FORMATS.join(', ')}`);
+    }
+    return format;
+}
+/**
+ * Print output in human-readable format
+ */
+function printHumanFormat(result, wuId, quiet) {
+    if (!quiet) {
+        console.log(`${LOG_PREFIX} Recovery context for ${wuId}:`);
+        console.log('');
+    }
+    console.log(result.context);
+    if (!quiet) {
+        console.log('');
+        console.log(`${LOG_PREFIX} ${result.size} bytes${result.truncated ? ' (truncated)' : ''}`);
+    }
+}
+/**
+ * Print output in JSON format
+ */
+function printJsonFormat(result, wuId) {
+    const output = {
+        wuId,
+        context: result.context,
+        size: result.size,
+        truncated: result.truncated,
+    };
+    console.log(JSON.stringify(output, null, 2));
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = createWUParser({
+        name: 'mem-recover',
+        description: 'Generate post-compaction recovery context for agents',
+        options: [
+            WU_OPTIONS.wu,
+            CLI_OPTIONS.maxSize,
+            CLI_OPTIONS.format,
+            CLI_OPTIONS.baseDir,
+            CLI_OPTIONS.quiet,
+        ],
+        required: ['wu'],
+    });
+    const baseDir = args.baseDir || process.cwd();
+    const startedAt = new Date().toISOString();
+    const startTime = Date.now();
+    let maxSize;
+    let format;
+    // Validate arguments
+    try {
+        maxSize = parsePositiveInt(args.maxSize, '--max-size');
+        format = validateFormat(args.format);
+    }
+    catch (err) {
+        const error = err;
+        console.error(`${LOG_PREFIX} Error: ${error.message}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    let result;
+    let error = null;
+    try {
+        result = await generateRecoveryContext({
+            wuId: args.wu,
+            baseDir,
+            maxSize,
+        });
+    }
+    catch (err) {
+        const e = err;
+        error = e.message;
+        result = {
+            success: false,
+            context: '',
+            size: 0,
+            truncated: false,
+        };
+    }
+    const durationMs = Date.now() - startTime;
+    // Write audit log entry
+    await writeAuditLog(baseDir, {
+        tool: TOOL_NAME,
+        status: error ? 'failed' : 'success',
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs,
+        input: {
+            baseDir,
+            wuId: args.wu,
+            maxSize,
+            format,
+            quiet: args.quiet,
+        },
+        output: result.success
+            ? {
+                contextSize: result.size,
+                truncated: result.truncated,
+            }
+            : null,
+        error: error ? { message: error } : null,
+    });
+    if (error) {
+        console.error(`${LOG_PREFIX} Error: ${error}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // Print output based on format
+    if (format === 'json') {
+        printJsonFormat(result, args.wu);
+    }
+    else {
+        printHumanFormat(result, args.wu, !!args.quiet);
+    }
+}
+main().catch((e) => {
+    console.error(`${LOG_PREFIX} ${e.message}`);
+    process.exit(EXIT_CODES.ERROR);
+});