@lumenflow/cli 1.4.0 → 1.6.0

package/README.md

@@ -1,6 +1,11 @@
 # @lumenflow/cli
 
-Command-line interface for LumenFlow workflow management.
+[![npm version](https://img.shields.io/npm/v/@lumenflow/cli.svg)](https://www.npmjs.com/package/@lumenflow/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@lumenflow/cli.svg)](https://www.npmjs.com/package/@lumenflow/cli)
+[![license](https://img.shields.io/npm/l/@lumenflow/cli.svg)](https://github.com/hellmai/os/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@lumenflow/cli.svg)](https://nodejs.org)
+
+> Command-line interface for LumenFlow workflow framework
 
 ## Installation
 
@@ -105,6 +110,23 @@ npx wu-claim --id WU-123 --lane operations
 npx gates
 ```
 
+## Global Flags
+
+All commands support these flags:
+
+| Flag              | Description               |
+| ----------------- | ------------------------- |
+| `--help`, `-h`    | Show help for the command |
+| `--version`, `-V` | Show version number       |
+| `--no-color`      | Disable colored output    |
+
+## Environment Variables
+
+| Variable      | Description                                                                            |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `NO_COLOR`    | Disable colored output when set (any value, per [no-color.org](https://no-color.org/)) |
+| `FORCE_COLOR` | Override color level: `0` (disabled), `1` (basic), `2` (256 colors), `3` (16m colors)  |
+
 ## Integration
 
 The CLI integrates with other LumenFlow packages:
@@ -116,7 +138,7 @@ The CLI integrates with other LumenFlow packages:
 
 ## Documentation
 
-For complete documentation, see the [LumenFlow documentation](https://github.com/hellmai/os).
+For complete documentation, see [lumenflow.dev](https://lumenflow.dev/reference/cli).
 
 ## License
 

package/dist/cli-entry-point.js

@@ -10,6 +10,8 @@
  * path but import.meta.url resolves to the real path - they never match
  * so main() is never called.
  *
+ * WU-1085: Initializes color support respecting NO_COLOR/FORCE_COLOR/--no-color
+ *
  * @example
  * ```typescript
  * // At the bottom of each CLI file:
@@ -21,13 +23,17 @@
  * ```
  */
 import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+import { initColorSupport } from '@lumenflow/core';
 /**
  * Wraps an async main function with proper error handling.
+ * WU-1085: Also initializes color support based on NO_COLOR/FORCE_COLOR/--no-color
  *
  * @param main - The async main function to execute
  * @returns Promise that resolves when main completes (or after error handling)
  */
 export async function runCLI(main) {
+    // WU-1085: Initialize color support before running command
+    initColorSupport();
     try {
         await main();
     }

package/dist/docs-sync.js

@@ -1,9 +1,38 @@
 /**
  * @file docs-sync.ts
  * LumenFlow docs:sync command for syncing agent docs to existing projects (WU-1083)
+ * WU-1085: Added createWUParser for proper --help support
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core';
+/**
+ * WU-1085: CLI option definitions for docs-sync command
+ */
+const DOCS_SYNC_OPTIONS = {
+    vendor: {
+        name: 'vendor',
+        flags: '--vendor <type>',
+        description: 'Vendor type (claude, cursor, aider, all, none)',
+        default: 'claude',
+    },
+    force: WU_OPTIONS.force,
+};
+/**
+ * WU-1085: Parse docs-sync command options using createWUParser
+ * Provides proper --help, --version, and option parsing
+ */
+export function parseDocsSyncOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-docs-sync',
+        description: 'Sync agent onboarding docs to existing projects (skips existing files by default)',
+        options: Object.values(DOCS_SYNC_OPTIONS),
+    });
+    return {
+        force: opts.force ?? false,
+        vendor: opts.vendor ?? 'claude',
+    };
+}
 /**
  * Get current date in YYYY-MM-DD format
  */
@@ -407,32 +436,18 @@ export async function syncSkills(targetDir, options) {
     await createFile(path.join(gatesDir, 'SKILL.md'), processTemplate(LUMENFLOW_GATES_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
     return result;
 }
-/**
- * Parse vendor flag from arguments
- */
-function parseVendorArg(args) {
-    const vendorIndex = args.findIndex((arg) => arg === '--vendor');
-    if (vendorIndex !== -1 && args[vendorIndex + 1]) {
-        const vendor = args[vendorIndex + 1].toLowerCase();
-        if (['claude', 'cursor', 'aider', 'all', 'none'].includes(vendor)) {
-            return vendor;
-        }
-    }
-    return undefined;
-}
 /**
  * CLI entry point for docs:sync command
+ * WU-1085: Updated to use parseDocsSyncOptions for proper --help support
  */
 export async function main() {
-    const args = process.argv.slice(2);
-    const force = args.includes('--force') || args.includes('-f');
-    const vendor = parseVendorArg(args) ?? 'claude'; // Default to claude
+    const opts = parseDocsSyncOptions();
     const targetDir = process.cwd();
     console.log('[lumenflow docs:sync] Syncing agent documentation...');
-    console.log(`  Vendor: ${vendor}`);
-    console.log(`  Force: ${force}`);
-    const docsResult = await syncAgentDocs(targetDir, { force });
-    const skillsResult = await syncSkills(targetDir, { force, vendor });
+    console.log(`  Vendor: ${opts.vendor}`);
+    console.log(`  Force: ${opts.force}`);
+    const docsResult = await syncAgentDocs(targetDir, { force: opts.force });
+    const skillsResult = await syncSkills(targetDir, { force: opts.force, vendor: opts.vendor });
     const created = [...docsResult.created, ...skillsResult.created];
     const skipped = [...docsResult.skipped, ...skillsResult.skipped];
     if (created.length > 0) {

package/dist/gates.js

@@ -54,35 +54,92 @@ import { buildGatesLogPath, shouldUseGatesAgentMode, updateGatesLatestSymlink, }
 import { detectRiskTier, RISK_TIERS, } from '@lumenflow/core/dist/risk-detector.js';
 // WU-2252: Import invariants runner for first-check validation
 import { runInvariants } from '@lumenflow/core/dist/invariants-runner.js';
-import { Command } from 'commander';
+import { createWUParser } from '@lumenflow/core/dist/arg-parser.js';
 import { BRANCHES, PACKAGES, PKG_MANAGER, PKG_FLAGS, ESLINT_FLAGS, ESLINT_COMMANDS, ESLINT_DEFAULTS, SCRIPTS, CACHE_STRATEGIES, DIRECTORIES, GATE_NAMES, GATE_COMMANDS, TOOL_PATHS, CLI_MODES, EXIT_CODES, FILE_SYSTEM, PRETTIER_ARGS, PRETTIER_FLAGS, } from '@lumenflow/core/dist/wu-constants.js';
-// WU-2457: Add Commander.js for --help support
-function parseGatesArgs(argv = process.argv) {
+/**
+ * WU-1087: Gates-specific option definitions for createWUParser.
+ * Exported for testing and consistency with other CLI commands.
+ */
+export const GATES_OPTIONS = {
+    docsOnly: {
+        name: 'docsOnly',
+        flags: '--docs-only',
+        description: 'Run docs-only gates (format, spec-linter, prompts-lint, backlog-sync)',
+    },
+    fullLint: {
+        name: 'fullLint',
+        flags: '--full-lint',
+        description: 'Run full lint instead of incremental',
+    },
+    fullTests: {
+        name: 'fullTests',
+        flags: '--full-tests',
+        description: 'Run full test suite instead of incremental',
+    },
+    fullCoverage: {
+        name: 'fullCoverage',
+        flags: '--full-coverage',
+        description: 'Force full test suite and coverage gate (implies --full-tests)',
+    },
+    coverageMode: {
+        name: 'coverageMode',
+        flags: '--coverage-mode <mode>',
+        description: 'Coverage gate mode: "warn" logs warnings, "block" fails gate',
+        default: 'block',
+    },
+    verbose: {
+        name: 'verbose',
+        flags: '--verbose',
+        description: 'Stream output in agent mode instead of logging to file',
+    },
+};
+/**
+ * WU-1087: Parse gates options using createWUParser for consistency.
+ * Handles pnpm's `--` separator and provides automatic --help support.
+ *
+ * @returns Parsed options object
+ */
+export function parseGatesOptions() {
     // WU-2465: Pre-filter argv to handle pnpm's `--` separator
     // When invoked via `pnpm gates -- --docs-only`, pnpm passes ["--", "--docs-only"]
-    // Commander treats `--` as "everything after is positional", causing errors.
-    // Solution: Remove standalone `--` from argv before parsing.
-    const filteredArgv = argv.filter((arg, index, arr) => {
-        // Keep `--` only if it's followed by a non-option (actual positional arg)
-        // Remove it if it's followed by an option (starts with -)
+    // createWUParser's default filtering removes all `--`, but we need smarter handling:
+    // Remove `--` only if it's followed by an option (starts with -)
+    const originalArgv = process.argv;
+    const filteredArgv = originalArgv.filter((arg, index, arr) => {
         if (arg === '--') {
             const nextArg = arr[index + 1];
             return nextArg && !nextArg.startsWith('-');
         }
         return true;
     });
-    const program = new Command()
-        .name('gates')
-        .description('Run quality gates with support for docs-only mode, incremental linting, and tiered testing')
-        .option('--docs-only', 'Run docs-only gates (format, spec-linter, prompts-lint, backlog-sync)')
-        .option('--full-lint', 'Run full lint instead of incremental')
-        .option('--full-tests', 'Run full test suite instead of incremental')
-        .option('--full-coverage', 'Force full test suite and coverage gate (implies --full-tests)')
-        .option('--coverage-mode <mode>', 'Coverage gate mode: "warn" logs warnings, "block" fails gate (default)', 'block')
-        .option('--verbose', 'Stream output in agent mode instead of logging to file')
-        .helpOption('-h, --help', 'Display help for command');
-    program.parse(filteredArgv);
-    return program.opts();
+    // Temporarily replace process.argv for createWUParser
+    process.argv = filteredArgv;
+    try {
+        const opts = createWUParser({
+            name: 'gates',
+            description: 'Run quality gates with support for docs-only mode, incremental linting, and tiered testing',
+            options: Object.values(GATES_OPTIONS),
+        });
+        return {
+            docsOnly: opts.docsOnly,
+            fullLint: opts.fullLint,
+            fullTests: opts.fullTests,
+            fullCoverage: opts.fullCoverage,
+            coverageMode: opts.coverageMode ?? 'block',
+            verbose: opts.verbose,
+        };
+    }
+    finally {
+        // Restore original process.argv
+        process.argv = originalArgv;
+    }
+}
+/**
+ * @deprecated Use parseGatesOptions() instead (WU-1087)
+ * Kept for backward compatibility during migration.
+ */
+function parseGatesArgs(argv = process.argv) {
+    return parseGatesOptions();
 }
 /**
  * Build a pnpm command string

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @lumenflow/cli - Command-line interface for LumenFlow workflow framework
+ *
+ * This package provides CLI commands for the LumenFlow workflow framework.
+ * Most functionality is exposed via bin commands, but the cli-entry-point
+ * helper is exported for use in custom CLI wrappers.
+ *
+ * @see https://lumenflow.dev/reference/cli
+ */
+export { runCLI } from './cli-entry-point.js';

package/dist/init.js

@@ -3,13 +3,58 @@
  * LumenFlow project scaffolding command (WU-1045)
  * WU-1006: Library-First - use core defaults for config generation
  * WU-1028: Vendor-agnostic core + vendor overlays
+ * WU-1085: Added createWUParser for proper --help support
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { getDefaultConfig } from '@lumenflow/core';
+import { getDefaultConfig, createWUParser, WU_OPTIONS } from '@lumenflow/core';
 // WU-1067: Import GATE_PRESETS for --preset support
 import { GATE_PRESETS } from '@lumenflow/core/dist/gates-config.js';
+/**
+ * WU-1085: CLI option definitions for init command
+ */
+const INIT_OPTIONS = {
+    full: {
+        name: 'full',
+        flags: '--full',
+        description: 'Add docs + agent onboarding + task scaffolding',
+    },
+    framework: {
+        name: 'framework',
+        flags: '--framework <name>',
+        description: 'Add framework hint + overlay docs',
+    },
+    vendor: {
+        name: 'vendor',
+        flags: '--vendor <type>',
+        description: 'Vendor type (claude, cursor, aider, all, none)',
+    },
+    preset: {
+        name: 'preset',
+        flags: '--preset <preset>',
+        description: 'Gate preset for config (node, python, go, rust, dotnet)',
+    },
+    force: WU_OPTIONS.force,
+};
+/**
+ * WU-1085: Parse init command options using createWUParser
+ * Provides proper --help, --version, and option parsing
+ */
+export function parseInitOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-init',
+        description: 'Initialize LumenFlow in a project',
+        options: Object.values(INIT_OPTIONS),
+    });
+    return {
+        force: opts.force ?? false,
+        full: opts.full ?? false,
+        framework: opts.framework,
+        vendor: opts.vendor,
+        preset: opts.preset,
+    };
+}
 const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
 const FRAMEWORK_HINT_FILE = '.lumenflow.framework.yaml';
 const LUMENFLOW_DIR = '.lumenflow';
@@ -1100,26 +1145,22 @@ async function createFile(filePath, content, force, result, targetDir) {
 }
 /**
  * CLI entry point
+ * WU-1085: Updated to use parseInitOptions for proper --help support
  */
 export async function main() {
-    const args = process.argv.slice(2);
-    const force = args.includes('--force') || args.includes('-f');
-    const full = args.includes('--full');
-    const vendor = parseVendorArg(args);
-    const framework = parseFrameworkArg(args);
-    const gatePreset = parsePresetArg(args); // WU-1067
+    const opts = parseInitOptions();
     const targetDir = process.cwd();
     console.log('[lumenflow init] Scaffolding LumenFlow project...');
-    console.log(`  Mode: ${full ? 'full' : 'minimal'}`);
-    console.log(`  Framework: ${framework ?? 'none'}`);
-    console.log(`  Vendor overlays: ${vendor ?? 'auto'}`);
-    console.log(`  Gate preset: ${gatePreset ?? 'none (manual config)'}`);
+    console.log(`  Mode: ${opts.full ? 'full' : 'minimal'}`);
+    console.log(`  Framework: ${opts.framework ?? 'none'}`);
+    console.log(`  Vendor overlays: ${opts.vendor ?? 'auto'}`);
+    console.log(`  Gate preset: ${opts.preset ?? 'none (manual config)'}`);
     const result = await scaffoldProject(targetDir, {
-        force,
-        full,
-        vendor,
-        framework,
-        gatePreset,
+        force: opts.force,
+        full: opts.full,
+        vendor: opts.vendor,
+        framework: opts.framework,
+        gatePreset: opts.preset,
     });
     if (result.created.length > 0) {
         console.log('\nCreated:');

package/dist/release.js

@@ -13,9 +13,12 @@
  * - Creates git tag vX.Y.Z
  *
  * Usage:
- *   pnpm release --version 1.3.0
- *   pnpm release --version 1.3.0 --dry-run     # Preview without making changes
- *   pnpm release --version 1.3.0 --skip-publish # Bump and tag only (no npm publish)
+ *   pnpm release --release-version 1.3.0
+ *   pnpm release --release-version 1.3.0 --dry-run     # Preview without making changes
+ *   pnpm release --release-version 1.3.0 --skip-publish # Bump and tag only (no npm publish)
+ *
+ * WU-1085: The --release-version flag was renamed from --version to avoid conflict
+ * with the standard CLI --version flag that shows the CLI version.
  *
  * WU-1074: Add release command for npm publishing
  */
@@ -262,19 +265,22 @@ export async function pushTagWithForce(git, tagName, reason = 'release: tag push
 }
 /**
  * Main release function
+ * WU-1085: Renamed --version to --release-version to avoid conflict with CLI --version flag
  */
 async function main() {
     const program = new Command()
-        .name('release')
+        .name('lumenflow-release')
         .description('Release @lumenflow/* packages to npm with version bump, tag, and publish')
-        .requiredOption('-v, --version <version>', 'Semver version to release (e.g., 1.3.0)')
+        .version('1.0.0', '-V, --version', 'Output the CLI version')
+        .requiredOption('-v, --release-version <version>', 'Semver version to release (e.g., 1.3.0)')
         .option('--dry-run', 'Preview changes without making them', false)
         .option('--skip-publish', 'Skip npm publish (only bump and tag)', false)
         .option('--skip-build', 'Skip build step (use existing dist)', false)
         .helpOption('-h, --help', 'Display help for command');
     program.parse();
     const opts = program.opts();
-    const { version, dryRun, skipPublish, skipBuild } = opts;
+    // WU-1085: Use releaseVersion instead of version (renamed to avoid CLI --version conflict)
+    const { releaseVersion: version, dryRun, skipPublish, skipBuild } = opts;
     console.log(`${LOG_PREFIX} Starting release process for v${version}`);
     if (dryRun) {
         console.log(`${LOG_PREFIX} DRY RUN MODE - no changes will be made`);

package/dist/wu-recover.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+/**
+ * WU Recovery Command
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Analyzes WU state inconsistencies and offers recovery actions:
+ * - resume: Reconcile state and continue working (preserves work)
+ * - reset: Discard worktree and reset WU to ready
+ * - nuke: Remove all artifacts completely (requires --force)
+ * - cleanup: Remove leftover worktree for done WUs
+ *
+ * Usage:
+ *   pnpm wu:recover --id WU-123             # Analyze issues
+ *   pnpm wu:recover --id WU-123 --action resume  # Apply fix
+ *   pnpm wu:recover --id WU-123 --action nuke --force  # Destructive
+ */
+import { existsSync, rmSync } from 'node:fs';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { computeContext } from '@lumenflow/core/dist/context/index.js';
+import { analyzeRecovery, } from '@lumenflow/core/dist/recovery/recovery-analyzer.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { readWU, writeWU } from '@lumenflow/core/dist/wu-yaml.js';
+import { CONTEXT_VALIDATION, EMOJI, WU_STATUS, DEFAULTS, toKebab, } from '@lumenflow/core/dist/wu-constants.js';
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { join } from 'node:path';
+const { RECOVERY_ACTIONS } = CONTEXT_VALIDATION;
+const LOG_PREFIX = '[wu:recover]';
+/**
+ * Valid recovery action types
+ */
+const VALID_ACTIONS = [
+    RECOVERY_ACTIONS.RESUME,
+    RECOVERY_ACTIONS.RESET,
+    RECOVERY_ACTIONS.NUKE,
+    RECOVERY_ACTIONS.CLEANUP,
+];
+/**
+ * Check if action requires --force flag
+ */
+export function requiresForceFlag(action) {
+    return action === RECOVERY_ACTIONS.NUKE;
+}
+/**
+ * Validate recovery action
+ */
+export function validateRecoveryAction(action) {
+    if (VALID_ACTIONS.includes(action)) {
+        return { valid: true };
+    }
+    return {
+        valid: false,
+        error: `Invalid action '${action}'. Valid actions: ${VALID_ACTIONS.join(', ')}`,
+    };
+}
+/**
+ * Format recovery analysis output
+ */
+export function formatRecoveryOutput(analysis) {
+    const lines = [];
+    lines.push(`## Recovery Analysis for ${analysis.wuId || 'unknown'}`);
+    lines.push('');
+    if (!analysis.hasIssues) {
+        lines.push(`${EMOJI.SUCCESS} No issues found - WU state is healthy`);
+        return lines.join('\n');
+    }
+    // Issues section
+    lines.push('### Issues Detected');
+    for (const issue of analysis.issues) {
+        lines.push(`  ${EMOJI.FAILURE} ${issue.code}: ${issue.description}`);
+    }
+    lines.push('');
+    // Actions section
+    if (analysis.actions.length > 0) {
+        lines.push('### Available Recovery Actions');
+        for (const action of analysis.actions) {
+            lines.push(`  **${action.type}**: ${action.description}`);
+            lines.push(`    Command: ${action.command}`);
+            if (action.warning) {
+                lines.push(`    ${EMOJI.WARNING} Warning: ${action.warning}`);
+            }
+            if (action.requiresForce) {
+                lines.push(`    Requires: --force flag`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Get exit code for recovery command
+ */
+export function getRecoveryExitCode(analysis, actionFailed) {
+    if (actionFailed) {
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Get expected worktree path for a WU
+ */
+function getWorktreePath(wuId, lane) {
+    const laneKebab = toKebab(lane);
+    const wuIdLower = wuId.toLowerCase();
+    return join(process.cwd(), DEFAULTS.WORKTREES_DIR, `${laneKebab}-${wuIdLower}`);
+}
+/**
+ * Execute resume action - reconcile state and continue
+ */
+async function executeResume(wuId) {
+    console.log(`${LOG_PREFIX} Executing resume action for ${wuId}...`);
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} WU file not found: ${wuPath}`);
+        return false;
+    }
+    const doc = readWU(wuPath, wuId);
+    // Update status to in_progress if it was ready
+    if (doc.status === WU_STATUS.READY) {
+        doc.status = WU_STATUS.IN_PROGRESS;
+        writeWU(wuPath, doc);
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Updated ${wuId} status to in_progress`);
+    }
+    console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Resume completed - you can continue working in the worktree`);
+    return true;
+}
+/**
+ * Execute reset action - discard worktree and reset to ready
+ */
+async function executeReset(wuId) {
+    console.log(`${LOG_PREFIX} Executing reset action for ${wuId}...`);
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} WU file not found: ${wuPath}`);
+        return false;
+    }
+    const doc = readWU(wuPath, wuId);
+    const worktreePath = getWorktreePath(wuId, doc.lane || '');
+    // Remove worktree if exists
+    // WU-1097: Use worktreeRemove() instead of deprecated run() with shell strings
+    // This properly handles paths with spaces and special characters
+    if (existsSync(worktreePath)) {
+        try {
+            const git = getGitForCwd();
+            await git.worktreeRemove(worktreePath, { force: true });
+            console.log(`${LOG_PREFIX} Removed worktree: ${worktreePath}`);
+        }
+        catch (e) {
+            // Try manual removal if git command fails
+            try {
+                rmSync(worktreePath, { recursive: true, force: true });
+                console.log(`${LOG_PREFIX} Manually removed worktree directory: ${worktreePath}`);
+            }
+            catch (rmError) {
+                console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Failed to remove worktree: ${rmError.message}`);
+                return false;
+            }
+        }
+    }
+    // Reset WU status to ready
+    doc.status = WU_STATUS.READY;
+    delete doc.worktree_path;
+    delete doc.claimed_at;
+    delete doc.session_id;
+    writeWU(wuPath, doc);
+    console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Reset completed - ${wuId} is now ready for re-claiming`);
+    return true;
+}
+/**
+ * Execute nuke action - remove all artifacts completely
+ */
+async function executeNuke(wuId) {
+    console.log(`${LOG_PREFIX} Executing nuke action for ${wuId}...`);
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        console.log(`${LOG_PREFIX} WU file does not exist: ${wuPath}`);
+    }
+    else {
+        const doc = readWU(wuPath, wuId);
+        const worktreePath = getWorktreePath(wuId, doc.lane || '');
+        // Remove worktree if exists
+        // WU-1097: Use worktreeRemove() instead of deprecated run() with shell strings
+        if (existsSync(worktreePath)) {
+            try {
+                const git = getGitForCwd();
+                await git.worktreeRemove(worktreePath, { force: true });
+            }
+            catch {
+                rmSync(worktreePath, { recursive: true, force: true });
+            }
+            console.log(`${LOG_PREFIX} Removed worktree: ${worktreePath}`);
+        }
+        // Try to delete branch
+        // WU-1097: Use deleteBranch() instead of deprecated run() with shell strings
+        try {
+            const git = getGitForCwd();
+            const laneKebab = toKebab(doc.lane || '');
+            const branchName = `lane/${laneKebab}/${wuId.toLowerCase()}`;
+            await git.deleteBranch(branchName, { force: true });
+            console.log(`${LOG_PREFIX} Deleted branch: ${branchName}`);
+        }
+        catch {
+            // Branch may not exist, that's fine
+        }
+    }
+    console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Nuke completed - all artifacts removed for ${wuId}`);
+    return true;
+}
+/**
+ * Execute cleanup action - remove leftover worktree for done WUs
+ */
+async function executeCleanup(wuId) {
+    console.log(`${LOG_PREFIX} Executing cleanup action for ${wuId}...`);
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} WU file not found: ${wuPath}`);
+        return false;
+    }
+    const doc = readWU(wuPath, wuId);
+    if (doc.status !== WU_STATUS.DONE) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Cannot cleanup: WU status is '${doc.status}', expected 'done'`);
+        return false;
+    }
+    const worktreePath = getWorktreePath(wuId, doc.lane || '');
+    if (!existsSync(worktreePath)) {
+        console.log(`${LOG_PREFIX} Worktree does not exist, nothing to cleanup`);
+        return true;
+    }
+    // WU-1097: Use worktreeRemove() instead of deprecated run() with shell strings
+    try {
+        const git = getGitForCwd();
+        await git.worktreeRemove(worktreePath, { force: true });
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Removed leftover worktree: ${worktreePath}`);
+    }
+    catch (e) {
+        rmSync(worktreePath, { recursive: true, force: true });
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Manually removed leftover worktree: ${worktreePath}`);
+    }
+    return true;
+}
+/**
+ * Execute recovery action
+ */
+async function executeAction(action, wuId) {
+    switch (action) {
+        case RECOVERY_ACTIONS.RESUME:
+            return executeResume(wuId);
+        case RECOVERY_ACTIONS.RESET:
+            return executeReset(wuId);
+        case RECOVERY_ACTIONS.NUKE:
+            return executeNuke(wuId);
+        case RECOVERY_ACTIONS.CLEANUP:
+            return executeCleanup(wuId);
+        default:
+            console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Unknown action: ${action}`);
+            return false;
+    }
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    const args = createWUParser({
+        name: 'wu-recover',
+        description: 'Analyze and fix WU state inconsistencies (WU-1090)',
+        options: [
+            WU_OPTIONS.id,
+            {
+                name: 'action',
+                flags: '-a, --action <action>',
+                type: 'string',
+                description: 'Recovery action: resume, reset, nuke, cleanup',
+            },
+            {
+                name: 'force',
+                flags: '-f, --force',
+                type: 'boolean',
+                description: 'Required for destructive actions (nuke)',
+            },
+            {
+                name: 'json',
+                flags: '-j, --json',
+                type: 'boolean',
+                description: 'Output as JSON',
+            },
+        ],
+        required: ['id'],
+        allowPositionalId: true,
+    });
+    const { id, action, force, json } = args;
+    // Compute context for the WU
+    const { context } = await computeContext({ wuId: id });
+    // Analyze recovery issues
+    const analysis = await analyzeRecovery(context);
+    // If no action specified, just show analysis
+    if (!action) {
+        if (json) {
+            console.log(JSON.stringify(analysis, null, 2));
+        }
+        else {
+            console.log(formatRecoveryOutput(analysis));
+        }
+        process.exit(getRecoveryExitCode(analysis, false));
+        return;
+    }
+    // Validate action
+    const validation = validateRecoveryAction(action);
+    if (!validation.valid) {
+        die(validation.error);
+    }
+    // Check force flag for destructive actions
+    if (requiresForceFlag(action) && !force) {
+        die(`Action '${action}' requires --force flag`);
+    }
+    // Execute action
+    const success = await executeAction(action, id);
+    if (!success) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Recovery action failed`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+// Guard main() for testability
+import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    runCLI(main);
+}

package/dist/wu-status.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * WU Status Command
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Shows:
+ * - Current location (main checkout vs worktree)
+ * - WU state if in worktree or --id provided
+ * - Git state (branch, dirty, ahead/behind)
+ * - Valid commands for current context
+ *
+ * Usage:
+ *   pnpm wu:status              # Auto-detect from current directory
+ *   pnpm wu:status --id WU-123  # Show status for specific WU
+ */
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { computeContext } from '@lumenflow/core/dist/context/index.js';
+import { getValidCommandsForContext } from '@lumenflow/core/dist/validation/command-registry.js';
+import { CONTEXT_VALIDATION, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
+const { LOCATION_TYPES } = CONTEXT_VALIDATION;
+const LOG_PREFIX = '[wu:status]';
+/**
+ * Format location type for display
+ */
+function formatLocationType(type) {
+    switch (type) {
+        case LOCATION_TYPES.MAIN:
+            return 'main checkout';
+        case LOCATION_TYPES.WORKTREE:
+            return 'worktree';
+        case LOCATION_TYPES.DETACHED:
+            return 'detached HEAD';
+        default:
+            return 'unknown location';
+    }
+}
+/**
+ * Format git state for display
+ */
+function formatGitState(context) {
+    const lines = [];
+    const { git } = context;
+    if (git.hasError) {
+        lines.push(`  ${EMOJI.FAILURE} Git error: ${git.errorMessage}`);
+        return lines;
+    }
+    const branchInfo = git.branch || '(detached)';
+    lines.push(`  Branch: ${branchInfo}`);
+    if (git.isDirty) {
+        lines.push(`  ${EMOJI.WARNING} Working tree: dirty (${git.modifiedFiles.length} files)`);
+    }
+    else {
+        lines.push(`  ${EMOJI.SUCCESS} Working tree: clean`);
+    }
+    if (git.hasStaged) {
+        lines.push(`  Staged: yes`);
+    }
+    if (git.ahead > 0 || git.behind > 0) {
+        const parts = [];
+        if (git.ahead > 0)
+            parts.push(`${git.ahead} ahead`);
+        if (git.behind > 0)
+            parts.push(`${git.behind} behind`);
+        lines.push(`  Tracking: ${parts.join(', ')}`);
+    }
+    return lines;
+}
+/**
+ * Format WU state for display
+ */
+function formatWuState(context) {
+    const lines = [];
+    const { wu } = context;
+    if (!wu) {
+        lines.push(`  No WU context`);
+        return lines;
+    }
+    lines.push(`  ID: ${wu.id}`);
+    lines.push(`  Title: ${wu.title}`);
+    lines.push(`  Lane: ${wu.lane}`);
+    lines.push(`  Status: ${wu.status}`);
+    if (!wu.isConsistent) {
+        lines.push(`  ${EMOJI.WARNING} State inconsistency: ${wu.inconsistencyReason}`);
+    }
+    return lines;
+}
+/**
+ * Format valid commands for display
+ */
+function formatValidCommands(context) {
+    const lines = [];
+    const validCommands = getValidCommandsForContext(context);
+    if (validCommands.length === 0) {
+        lines.push(`  No commands available for current context`);
+        return lines;
+    }
+    for (const cmd of validCommands) {
+        lines.push(`  ${cmd.name} - ${cmd.description}`);
+    }
+    return lines;
+}
+/**
+ * Format complete status output
+ */
+export function formatStatusOutput(context) {
+    const lines = [];
+    // Location section
+    lines.push('## Location');
+    lines.push(`  Type: ${formatLocationType(context.location.type)}`);
+    lines.push(`  Path: ${context.location.cwd}`);
+    if (context.location.worktreeName) {
+        lines.push(`  Worktree: ${context.location.worktreeName}`);
+    }
+    if (context.location.worktreeWuId) {
+        lines.push(`  WU ID: ${context.location.worktreeWuId}`);
+    }
+    lines.push('');
+    // Git section
+    lines.push('## Git State');
+    lines.push(...formatGitState(context));
+    lines.push('');
+    // WU section
+    lines.push('## WU State');
+    lines.push(...formatWuState(context));
+    lines.push('');
+    // Valid commands section
+    lines.push('## Valid Commands');
+    lines.push(...formatValidCommands(context));
+    return lines.join('\n');
+}
+/**
+ * Get exit code based on context state
+ */
+export function getStatusExitCode(context) {
+    // Error if git has errors
+    if (context.git.hasError) {
+        return 1;
+    }
+    // Error if location is unknown
+    if (context.location.type === LOCATION_TYPES.UNKNOWN) {
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    const args = createWUParser({
+        name: 'wu-status',
+        description: 'Show WU status, location, and valid commands (WU-1090)',
+        options: [
+            { ...WU_OPTIONS.id, required: false },
+            {
+                name: 'json',
+                flags: '-j, --json',
+                type: 'boolean',
+                description: 'Output as JSON',
+            },
+        ],
+        required: [],
+        allowPositionalId: true,
+    });
+    const { id, json } = args;
+    // Compute context
+    const { context, computationMs, exceededBudget } = await computeContext({
+        wuId: id,
+    });
+    if (exceededBudget) {
+        console.warn(`${LOG_PREFIX} ${EMOJI.WARNING} Context computation took ${computationMs.toFixed(0)}ms (exceeded 100ms budget)`);
+    }
+    // Output
+    if (json) {
+        console.log(JSON.stringify(context, null, 2));
+    }
+    else {
+        console.log(formatStatusOutput(context));
+    }
+    // Exit with appropriate code
+    process.exit(getStatusExitCode(context));
+}
+// Guard main() for testability
+import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    runCLI(main);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -21,6 +21,18 @@
     "url": "https://hellm.ai"
   },
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli-entry-point": {
+      "types": "./dist/cli-entry-point.d.ts",
+      "import": "./dist/cli-entry-point.js"
+    }
+  },
   "bin": {
     "wu-claim": "./dist/wu-claim.js",
     "wu-done": "./dist/wu-done.js",
@@ -39,6 +51,8 @@
     "wu-delete": "./dist/wu-delete.js",
     "wu-unlock-lane": "./dist/wu-unlock-lane.js",
     "wu-release": "./dist/wu-release.js",
+    "wu-status": "./dist/wu-status.js",
+    "wu-recover": "./dist/wu-recover.js",
     "mem-init": "./dist/mem-init.js",
     "mem-checkpoint": "./dist/mem-checkpoint.js",
     "mem-start": "./dist/mem-start.js",
@@ -88,11 +102,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "1.4.0",
-    "@lumenflow/metrics": "1.4.0",
-    "@lumenflow/memory": "1.4.0",
-    "@lumenflow/initiatives": "1.4.0",
-    "@lumenflow/agent": "1.4.0"
+    "@lumenflow/core": "1.6.0",
+    "@lumenflow/initiatives": "1.6.0",
+    "@lumenflow/agent": "1.6.0",
+    "@lumenflow/metrics": "1.6.0",
+    "@lumenflow/memory": "1.6.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",