@lumenflow/cli 2.8.0 → 2.10.0

package/dist/init.js

@@ -12,13 +12,15 @@ 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
 import { updateMergeBlock } from './merge-block.js';
 // WU-1362: Import worktree guard utilities for branch checking
 import { isMainBranch, isInWorktree } from '@lumenflow/core/dist/core/worktree-guard.js';
+// WU-1386: Import doctor for auto-run after init
+import { runDoctorForInit } from './doctor.js';
 /**
  * WU-1085: CLI option definitions for init command
  * WU-1171: Added --merge and --client options
@@ -70,9 +72,12 @@ const INIT_OPTIONS = {
  * Provides proper --help, --version, and option parsing
  */
 export function parseInitOptions() {
+    // WU-1378: Description includes subcommand hint
     const opts = createWUParser({
         name: 'lumenflow-init',
-        description: 'Initialize LumenFlow in a project',
+        description: 'Initialize LumenFlow in a project\n\n' +
+            'Subcommands:\n' +
+            '  lumenflow commands    List all available CLI commands',
         options: Object.values(INIT_OPTIONS),
     });
     // WU-1171: --client takes precedence, --vendor is alias
@@ -321,9 +326,24 @@ const DEFAULT_LANE_DEFINITIONS = [
  * WU-1067: Supports --preset option for config-driven gates
  * WU-1307: Includes default lane definitions for onboarding
  * WU-1364: Supports git config overrides (requireRemote)
+ * WU-1383: Adds enforcement hooks config for Claude client by default
  */
-function generateLumenflowConfigYaml(gatePreset, gitConfigOverride) {
-    const header = `# LumenFlow Configuration\n# Generated by: lumenflow init\n# Customize paths based on your project structure\n\n`;
+function generateLumenflowConfigYaml(gatePreset, gitConfigOverride, client) {
+    // WU-1382: Add managed file header to prevent manual edits
+    const header = `# ============================================================================
+# LUMENFLOW MANAGED FILE - DO NOT EDIT MANUALLY
+# ============================================================================
+# Generated by: lumenflow init
+# Regenerate with: pnpm exec lumenflow init --force
+#
+# This file is managed by LumenFlow tooling. Manual edits may be overwritten.
+# To customize, use the CLI commands or edit the appropriate source templates.
+# ============================================================================
+
+# LumenFlow Configuration
+# Customize paths based on your project structure
+
+`;
     const config = getDefaultConfig();
     config.directories.agentsDir = LUMENFLOW_AGENTS_DIR;
     // WU-1067: Add gates.execution section with preset if specified
@@ -344,6 +364,22 @@ function generateLumenflowConfigYaml(gatePreset, gitConfigOverride) {
             requireRemote: gitConfigOverride.requireRemote,
         };
     }
+    // WU-1383: Add enforcement hooks for Claude client by default
+    // This prevents agents from working on main and editing config files manually
+    if (client === 'claude') {
+        config.agents = {
+            clients: {
+                'claude-code': {
+                    enforcement: {
+                        hooks: true,
+                        block_outside_worktree: true,
+                        require_wu_for_edits: true,
+                        warn_on_stop_without_wu_done: true,
+                    },
+                },
+            },
+        };
+    }
     return header + yaml.stringify(config);
 }
 /**
@@ -453,7 +489,78 @@ const LUMENFLOW_MD_TEMPLATE = `# LumenFlow Workflow Guide\n\n**Last updated:** {
 const CONSTRAINTS_MD_TEMPLATE = `# LumenFlow Constraints Capsule\n\n**Version:** 1.0\n**Last updated:** {{DATE}}\n\n## The 6 Non-Negotiable Constraints\n\n### 1. Worktree Discipline and Git Safety\nWork only in worktrees, treat main as read-only, never run destructive git commands on main.\n\n### 2. WUs Are Specs, Not Code\nRespect code_paths boundaries, no feature creep, no code blocks in WU YAML files.\n\n### 3. Docs-Only vs Code WUs\nDocumentation WUs use \`--docs-only\` gates, code WUs run full gates.\n\n### 4. LLM-First, Zero-Fallback Inference\nUse LLMs for semantic tasks, fall back to safe defaults (never regex/keywords).\n\n### 5. Gates and Skip-Gates\nComplete via \`pnpm wu:done\`; skip-gates only for pre-existing failures with \`--reason\` and \`--fix-wu\`.\n\n### 6. Safety and Governance\nRespect privacy rules, approved sources, security policies; when uncertain, choose safer path.\n\n---\n\n## Mini Audit Checklist\n\nBefore running \`wu:done\`, verify:\n\n- [ ] Working in worktree (not main)\n- [ ] Only modified files in \`code_paths\`\n- [ ] Gates pass\n- [ ] No forbidden git commands used\n- [ ] Acceptance criteria satisfied\n\n---\n\n## Escalation Triggers\n\nStop and ask a human when:\n- Same error repeats 3 times\n- Auth or permissions changes required\n- PII/PHI/safety issues discovered\n- Cloud spend or secrets involved\n`;
 // Template for root CLAUDE.md
 // WU-1309: Use <project-root> placeholder for portability
-const CLAUDE_MD_TEMPLATE = `# Claude Code Instructions\n\n**Last updated:** {{DATE}}\n\nThis project uses LumenFlow workflow. For workflow documentation, see [LUMENFLOW.md](LUMENFLOW.md).\n\n---\n\n## Quick Start\n\n\`\`\`bash\n# 1. Claim a WU\npnpm wu:claim --id WU-XXXX --lane <Lane>\ncd worktrees/<lane>-wu-xxxx\n\n# 2. Work in worktree, run gates\npnpm gates\n\n# 3. Complete (ALWAYS run this!)\ncd <project-root>\npnpm wu:done --id WU-XXXX\n\`\`\`\n\n---\n\n## Critical: Always wu:done\n\nAfter completing work, ALWAYS run \`pnpm wu:done --id WU-XXXX\`.\n\nSee [LUMENFLOW.md](LUMENFLOW.md) for full workflow documentation.\n`;
+// WU-1382: Expanded with CLI commands table and warning about manual YAML editing
+const CLAUDE_MD_TEMPLATE = `# Claude Code Instructions
+
+**Last updated:** {{DATE}}
+
+This project uses LumenFlow workflow. For workflow documentation, see [LUMENFLOW.md](LUMENFLOW.md).
+
+---
+
+## Quick Start
+
+\`\`\`bash
+# 1. Claim a WU
+pnpm wu:claim --id WU-XXXX --lane <Lane>
+cd worktrees/<lane>-wu-xxxx
+
+# 2. Work in worktree, run gates
+pnpm gates
+
+# 3. Complete (ALWAYS run this!)
+cd <project-root>
+pnpm wu:done --id WU-XXXX
+\`\`\`
+
+---
+
+## CLI Commands Reference
+
+### WU Lifecycle
+
+| Command                                   | Description                              |
+| ----------------------------------------- | ---------------------------------------- |
+| \`pnpm wu:status --id WU-XXX\`              | Show WU status, location, valid commands |
+| \`pnpm wu:claim --id WU-XXX --lane <Lane>\` | Claim WU and create worktree             |
+| \`pnpm wu:prep --id WU-XXX\`                | Run gates in worktree, prep for wu:done  |
+| \`pnpm wu:done --id WU-XXX\`                | Complete WU (from main checkout)         |
+| \`pnpm wu:block --id WU-XXX --reason "..."\`| Block WU with reason                     |
+| \`pnpm wu:unblock --id WU-XXX\`             | Unblock WU                               |
+
+### Gates & Quality
+
+| Command                  | Description                |
+| ------------------------ | -------------------------- |
+| \`pnpm gates\`             | Run all quality gates      |
+| \`pnpm gates --docs-only\` | Run gates for docs changes |
+| \`pnpm format\`            | Format all files           |
+| \`pnpm lint\`              | Run linter                 |
+| \`pnpm typecheck\`         | Run TypeScript check       |
+| \`pnpm test\`              | Run tests                  |
+
+---
+
+## Critical: Always wu:done
+
+After completing work, ALWAYS run \`pnpm wu:done --id WU-XXXX\` from the main checkout.
+
+See [LUMENFLOW.md](LUMENFLOW.md) for full workflow documentation.
+
+---
+
+## Warning: Do Not Edit WU YAML Files Manually
+
+**Never manually edit WU YAML files** in \`docs/.../tasks/wu/WU-XXX.yaml\`.
+
+Use CLI commands instead:
+
+- \`pnpm wu:create ...\` to create new WUs
+- \`pnpm wu:edit --id WU-XXX ...\` to modify WU fields
+- \`pnpm wu:claim\` / \`wu:block\` / \`wu:done\` for status changes
+
+Manual edits bypass validation and can corrupt workflow state.
+`;
 // Template for .claude/settings.json
 const CLAUDE_SETTINGS_TEMPLATE = `{
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
@@ -1095,9 +1202,19 @@ Choose the safer path:
 `;
 // WU-1307: Lane inference configuration template (hierarchical Parent→Sublane format)
 // WU-1364: Added Core and Feature as parent lanes for intuitive naming
+// WU-1382: Added managed file header to prevent manual edits
 // This format is required by lane-inference.ts and lane-checker.ts
-const LANE_INFERENCE_TEMPLATE = `# Lane Inference Configuration
+const LANE_INFERENCE_TEMPLATE = `# ============================================================================
+# LUMENFLOW MANAGED FILE - DO NOT EDIT MANUALLY
+# ============================================================================
 # Generated by: lumenflow init
+# Regenerate with: pnpm exec lumenflow init --force
+#
+# This file is managed by LumenFlow tooling. Manual edits may be overwritten.
+# To customize lanes, use: pnpm lane:suggest --output .lumenflow.lane-inference.yaml
+# ============================================================================
+
+# Lane Inference Configuration
 #
 # Hierarchical format: Parent -> Sublane -> { code_paths, keywords }
 # This format is required by lane-inference.ts for proper sub-lane suggestion.
@@ -1363,6 +1480,7 @@ LumenFlow uses Work Units (WUs) to track all changes:
 - [quick-ref-commands.md](quick-ref-commands.md) - Complete command reference
 - [agent-safety-card.md](agent-safety-card.md) - Safety guidelines
 - [wu-create-checklist.md](wu-create-checklist.md) - WU creation guide
+- [wu-sizing-guide.md](wu-sizing-guide.md) - WU complexity and context management
 `;
 const WU_CREATE_CHECKLIST_TEMPLATE = `# WU Creation Checklist
 
@@ -1751,6 +1869,96 @@ This detects:
 - Overlapping code paths between lanes
 - Code files not covered by any lane
 `;
+// WU-1385: WU sizing guide template for agent onboarding
+const WU_SIZING_GUIDE_TEMPLATE = `# Work Unit Sizing & Strategy Guide
+
+**Last updated:** {{DATE}}
+
+**Purpose:** Decision framework for agents to determine execution strategy based on task complexity.
+
+**Status:** Active — Thresholds are **mandatory limits**, not guidelines.
+
+---
+
+## Complexity Assessment Matrix
+
+Before claiming a WU, estimate its "weight" using these heuristics.
+
+| Complexity    | Files | Tool Calls | Context Budget | Strategy                                     |
+| :------------ | :---- | :--------- | :------------- | :------------------------------------------- |
+| **Simple**    | <20   | <50        | <30%           | **Single Session** (Tier 2 Context)          |
+| **Medium**    | 20-50 | 50-100     | 30-50%         | **Checkpoint-Resume** (Standard Handoff)     |
+| **Complex**   | 50+   | 100+       | >50%           | **Orchestrator-Worker** OR **Decomposition** |
+| **Oversized** | 100+  | 200+       | —              | **MUST Split** (See Patterns below)          |
+
+**These thresholds are mandatory.** Exceeding them leads to context exhaustion and rule loss. Agents operate in context windows and tool calls, not clock time.
+
+---
+
+## Context Safety Triggers
+
+If you hit ANY of these triggers during a session, you MUST checkpoint and spawn fresh:
+
+- **Token Limit:** Context usage hits **50% (Warning)** or **80% (Critical)**.
+- **Tool Volume:** **50+ tool calls** in current session.
+- **File Volume:** **20+ files** modified in \`git status\`.
+- **Session Staleness:** Repeated redundant queries or forgotten context.
+
+---
+
+## Spawn Fresh, Don't Continue
+
+**When approaching context limits, spawn a fresh agent instead of continuing after compaction.**
+
+Context compaction causes agents to lose critical rules. The disciplined approach:
+
+1. Checkpoint your progress: \`pnpm mem:checkpoint --wu WU-XXX\`
+2. Commit and push work
+3. Generate fresh agent prompt: \`pnpm wu:spawn --id WU-XXX\`
+4. EXIT current session (do NOT continue after compaction)
+
+---
+
+## Splitting Patterns
+
+When a WU is Oversized or Complex, split it using approved patterns:
+
+- **Tracer Bullet**: WU-1 proves skeleton works, WU-2 implements real logic
+- **Layer Split**: WU-1 for ports/application, WU-2 for infrastructure
+- **UI/Logic Split**: WU-1 for backend, WU-2 for frontend
+- **Feature Flag**: WU-1 behind flag, WU-2 removes flag
+
+---
+
+## Quick Reference
+
+| Scenario                            | Strategy            | Action                                       |
+| :---------------------------------- | :------------------ | :------------------------------------------- |
+| Bug fix, single file, <20 calls     | Simple              | Claim, fix, commit, \`wu:done\`              |
+| Feature 50-100 calls, clear phases  | Checkpoint-Resume   | Phase 1 → checkpoint → Phase 2 → done        |
+| Multi-domain, must land atomically  | Orchestrator-Worker | Main agent coordinates, spawns sub-agents    |
+| Large refactor 100+ calls           | Feature Flag Split  | WU-A: New behind flag → WU-B: Remove flag    |
+
+---
+
+## Documentation-Only Exception
+
+Documentation WUs (\`type: documentation\`) have relaxed file count thresholds:
+
+| Complexity | Files (docs) | Tool Calls | Strategy          |
+| :--------- | :----------- | :--------- | :---------------- |
+| **Simple** | <40          | <50        | Single Session    |
+| **Medium** | 40-80        | 50-100     | Checkpoint-Resume |
+
+**Applies when ALL true:**
+- WU \`type: documentation\`
+- Only modifies: \`docs/**\`, \`*.md\`
+- Does NOT touch code paths
+
+---
+
+For complete sizing guidance, see the canonical [wu-sizing-guide.md](https://lumenflow.dev/reference/wu-sizing-guide/) documentation.
+`;
 // WU-1083: Claude skills templates
 const WU_LIFECYCLE_SKILL_TEMPLATE = `---
 name: wu-lifecycle
@@ -2127,8 +2335,17 @@ export async function scaffoldProject(targetDir, options) {
     };
     // Create .lumenflow.config.yaml (WU-1067: includes gate preset if specified)
     // WU-1364: Includes git config overrides (e.g., requireRemote: false for local-only)
+    // WU-1383: Includes enforcement hooks for Claude client
     // Note: Config files don't use merge mode (always skip or force)
-    await createFile(path.join(targetDir, CONFIG_FILE_NAME), generateLumenflowConfigYaml(options.gatePreset, gitConfigOverride), options.force ? 'force' : 'skip', result, targetDir);
+    const configPath = path.join(targetDir, CONFIG_FILE_NAME);
+    // WU-1383: Warn if config already exists to discourage manual editing
+    if (fs.existsSync(configPath) && !options.force) {
+        result.warnings = result.warnings ?? [];
+        result.warnings.push(`${CONFIG_FILE_NAME} already exists. ` +
+            'To modify configuration, use CLI commands (e.g., pnpm lumenflow:init --force) ' +
+            'instead of manual editing.');
+    }
+    await createFile(configPath, generateLumenflowConfigYaml(options.gatePreset, gitConfigOverride, client), options.force ? 'force' : 'skip', result, targetDir);
     // WU-1171: Create AGENTS.md (universal entry point for all agents)
     try {
         const agentsTemplate = loadTemplate('core/AGENTS.md.template');
@@ -2382,6 +2599,8 @@ async function scaffoldAgentOnboardingDocs(targetDir, options, result, tokens) {
     await createFile(path.join(onboardingDir, 'troubleshooting-wu-done.md'), processTemplate(TROUBLESHOOTING_WU_DONE_TEMPLATE, tokens), options.force, result, targetDir);
     await createFile(path.join(onboardingDir, 'agent-safety-card.md'), processTemplate(AGENT_SAFETY_CARD_TEMPLATE, tokens), options.force, result, targetDir);
     await createFile(path.join(onboardingDir, 'wu-create-checklist.md'), processTemplate(WU_CREATE_CHECKLIST_TEMPLATE, tokens), options.force, result, targetDir);
+    // WU-1385: Add wu-sizing-guide.md to onboarding docs
+    await createFile(path.join(onboardingDir, 'wu-sizing-guide.md'), processTemplate(WU_SIZING_GUIDE_TEMPLATE, tokens), options.force, result, targetDir);
 }
 /**
  * WU-1083: Scaffold Claude skills
@@ -2429,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)
@@ -2555,12 +2801,45 @@ 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
  * WU-1171: Added --merge and --client support
+ * WU-1378: Added subcommand routing for 'commands' subcommand
  */
 export async function main() {
+    // WU-1378: Check for subcommands before parsing init options
+    const subcommand = process.argv[2];
+    if (subcommand === 'commands') {
+        // Route to commands subcommand
+        const { main: commandsMain } = await import('./commands.js');
+        // Remove 'commands' from argv so the subcommand parser sees clean args
+        process.argv.splice(2, 1);
+        await commandsMain();
+        return;
+    }
     const opts = parseInitOptions();
     const targetDir = process.cwd();
     console.log('[lumenflow init] Scaffolding LumenFlow project...');
@@ -2603,6 +2882,18 @@ export async function main() {
         console.log('\nWarnings:');
         result.warnings.forEach((w) => console.log(`  ⚠ ${w}`));
     }
+    // WU-1386: Run doctor auto-check (non-blocking)
+    // This provides feedback on workflow health without failing init
+    try {
+        const doctorResult = await runDoctorForInit(targetDir);
+        if (doctorResult.output) {
+            console.log('');
+            console.log(doctorResult.output);
+        }
+    }
+    catch {
+        // Doctor check is non-blocking - if it fails, continue with init
+    }
     // WU-1359: Show complete lifecycle with auto-ID (no --id flag required)
     // WU-1364: Added initiative-first guidance for product visions
     console.log('\n[lumenflow init] Done! Next steps:');

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);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -99,6 +99,7 @@
     "lumenflow-init": "./dist/init.js",
     "lumenflow": "./dist/init.js",
     "lumenflow-doctor": "./dist/doctor.js",
+    "lumenflow-commands": "./dist/commands.js",
     "lumenflow-release": "./dist/release.js",
     "lumenflow-docs-sync": "./dist/docs-sync.js",
     "lumenflow-sync-templates": "./dist/sync-templates.js",
@@ -150,11 +151,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "2.8.0",
-    "@lumenflow/memory": "2.8.0",
-    "@lumenflow/metrics": "2.8.0",
-    "@lumenflow/agent": "2.8.0",
-    "@lumenflow/initiatives": "2.8.0"
+    "@lumenflow/core": "2.10.0",
+    "@lumenflow/metrics": "2.10.0",
+    "@lumenflow/initiatives": "2.10.0",
+    "@lumenflow/agent": "2.10.0",
+    "@lumenflow/memory": "2.10.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",