@lumenflow/cli 2.9.0 → 2.11.0

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/dist/orchestrate-initiative.js

@@ -91,7 +91,25 @@ const program = new Command()
         console.log(formatExecutionPlan(initiative, plan));
         if (dryRun) {
             console.log(chalk.yellow(`${LOG_PREFIX} Dry run mode - no agents spawned`));
-            console.log(chalk.cyan('To execute this plan, remove the --dry-run flag.'));
+            console.log('');
+            console.log(chalk.bold('Next Steps (Recommended Defaults):'));
+            console.log('');
+            console.log(chalk.cyan('  Option 1 (Recommended): Checkpoint-per-wave mode'));
+            console.log('    pnpm orchestrate:initiative -i ' + initIds[0] + ' -c');
+            console.log('    Best for: Large initiatives, context management, idempotent resumption');
+            console.log('');
+            console.log(chalk.cyan('  Option 2: Full execution (polling mode)'));
+            console.log('    pnpm orchestrate:initiative -i ' + initIds[0]);
+            console.log('    Best for: Small initiatives (<4 WUs), quick execution');
+            console.log('');
+            console.log(chalk.cyan('  Option 3: Manual spawn per WU'));
+            console.log('    pnpm wu:spawn --id <WU-ID> --client claude-code');
+            console.log('    Best for: Testing, debugging, single WU execution');
+            console.log('');
+            console.log(chalk.bold('Monitoring Commands:'));
+            console.log('  pnpm mem:inbox --since 10m          # Check for signals from agents');
+            console.log('  pnpm orchestrate:init-status -i ' + initIds[0] + '   # Check progress');
+            console.log('  pnpm orchestrate:monitor            # Live agent activity');
             return;
         }
         // WU-1202: Output spawn XML for actual execution (not dry-run)

package/dist/state-doctor-fix.js

@@ -1,5 +1,5 @@
 /**
- * State Doctor Fix Operations (WU-1230)
+ * State Doctor Fix Operations (WU-1230, WU-1420)
  *
  * Provides fix dependencies for state:doctor --fix that use micro-worktree
  * isolation for all tracked file changes. This ensures:
@@ -8,6 +8,7 @@
  * 2. Removal of stale WU references from backlog.md and status.md
  * 3. All changes pushed via merge, not direct file modification
  * 4. WU-1362: Retry logic for push failures (inherited from withMicroWorktree)
+ * 5. WU-1420: Emit corrective events to reconcile YAML vs state store mismatches
  *
  * Retry behavior is configured via .lumenflow.config.yaml git.push_retry section.
  * Default: 3 retries with exponential backoff and jitter.
@@ -72,6 +73,9 @@ async function readFileSafe(filePath) {
  * WU-1230: All file modifications happen in a micro-worktree and are pushed
  * to origin/main via merge. This prevents direct modifications to local main.
  *
+ * WU-1420: Includes emitEvent for fixing status mismatches by emitting
+ * corrective events (release, complete) to reconcile state store with YAML.
+ *
  * @param baseDir - Project base directory
  * @returns Partial StateDoctorDeps with fix operations
  */
@@ -190,5 +194,36 @@ export function createStateDoctorFixDeps(_baseDir) {
                 },
             });
         },
+        /**
+         * Emit a corrective event to fix status mismatch (WU-1420)
+         *
+         * Appends a release or complete event to wu-events.jsonl to reconcile
+         * the state store with the WU YAML status.
+         */
+        emitEvent: async (event) => {
+            await withMicroWorktree({
+                operation: OPERATION_NAME,
+                id: `emit-event-${event.wuId.toLowerCase()}-${event.type}`,
+                logPrefix: LOG_PREFIX,
+                pushOnly: true,
+                execute: async ({ worktreePath }) => {
+                    const eventsPath = path.join(worktreePath, WU_EVENTS_FILE);
+                    // Build the event object
+                    const eventLine = JSON.stringify({
+                        wuId: event.wuId,
+                        type: event.type,
+                        reason: event.reason,
+                        timestamp: event.timestamp || new Date().toISOString(),
+                    });
+                    // Append to events file (create if needed)
+                    await fs.mkdir(path.dirname(eventsPath), { recursive: true });
+                    await fs.appendFile(eventsPath, eventLine + '\n', 'utf-8');
+                    return {
+                        commitMessage: `fix(state-doctor): emit ${event.type} event for ${event.wuId} to reconcile state`,
+                        files: [WU_EVENTS_FILE],
+                    };
+                },
+            });
+        },
     };
 }

package/dist/state-doctor.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 /**
- * State Doctor CLI (WU-1209)
+ * State Doctor CLI (WU-1209, WU-1420)
  *
  * Integrity checker for LumenFlow state that detects:
  * - Orphaned WUs (done status but no stamp)
  * - Dangling signals (reference non-existent WUs)
  * - Broken memory relationships (events for missing WU specs)
+ * - Status mismatches between WU YAML and state store (WU-1420)
  *
  * Inspired by Beads bd doctor command.
  *
@@ -171,7 +172,7 @@ async function createDeps(baseDir) {
          */
         listStamps: async () => {
             try {
-                const stampsDir = path.join(baseDir, config.beacon.stampsDir);
+                const stampsDir = path.join(baseDir, config.state.stampsDir);
                 const stampFiles = await fg('WU-*.done', { cwd: stampsDir });
                 return stampFiles.map((file) => file.replace('.done', ''));
             }
@@ -321,6 +322,8 @@ function getIssueTypeLabel(type) {
             return 'Dangling Signal';
         case ISSUE_TYPES.BROKEN_EVENT:
             return 'Broken Event';
+        case ISSUE_TYPES.STATUS_MISMATCH:
+            return 'Status Mismatch';
         default:
             return type;
     }
@@ -330,10 +333,11 @@ function getIssueTypeLabel(type) {
  */
 function printSummary(result) {
     console.log('=== Summary ===');
-    console.log(`  Orphaned WUs:     ${result.summary.orphanedWUs}`);
-    console.log(`  Dangling Signals: ${result.summary.danglingSignals}`);
-    console.log(`  Broken Events:    ${result.summary.brokenEvents}`);
-    console.log(`  Total Issues:     ${result.summary.totalIssues}`);
+    console.log(`  Orphaned WUs:      ${result.summary.orphanedWUs}`);
+    console.log(`  Dangling Signals:  ${result.summary.danglingSignals}`);
+    console.log(`  Broken Events:     ${result.summary.brokenEvents}`);
+    console.log(`  Status Mismatches: ${result.summary.statusMismatches}`);
+    console.log(`  Total Issues:      ${result.summary.totalIssues}`);
 }
 /**
  * Print fixed issues section

package/dist/wu-create.js

@@ -43,7 +43,7 @@ import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { getConfig } from '@lumenflow/core/dist/lumenflow-config.js';
 import { validateWU } from '@lumenflow/core/dist/wu-schema.js';
 import { getPlanPath, getPlanProtocolRef, getPlansDir, } from '@lumenflow/core/dist/lumenflow-home.js';
-import { validateSpecRefs } from '@lumenflow/core/dist/wu-create-validators.js';
+import { hasSpecRefs, validateSpecRefs } from '@lumenflow/core/dist/wu-create-validators.js';
 import { COMMIT_FORMATS, FILE_SYSTEM, READINESS_UI, STRING_LITERALS, } from '@lumenflow/core/dist/wu-constants.js';
 // WU-1593: Use centralized validateWUIDFormat (DRY)
 import { ensureOnMain, validateWUIDFormat } from '@lumenflow/core/dist/wu-helpers.js';
@@ -114,6 +114,21 @@ export function warnIfBetterLaneExists(providedLane, codePathsArray, title, desc
         // Non-blocking - if inference fails, continue silently
     }
 }
+export function collectInitiativeWarnings({ initiativeId, initiativeDoc, phase, specRefs, }) {
+    const warnings = [];
+    const phaseCheck = checkInitiativePhases(initiativeDoc);
+    if (!phaseCheck.hasPhases && phaseCheck.warning) {
+        warnings.push(phaseCheck.warning);
+    }
+    if (phaseCheck.hasPhases && !phase) {
+        warnings.push(`Initiative ${initiativeId} has phases defined. Consider adding --phase to link this WU to a phase.`);
+    }
+    const relatedPlan = initiativeDoc.related_plan;
+    if (relatedPlan && !hasSpecRefs(specRefs)) {
+        warnings.push(`Initiative ${initiativeId} has related_plan (${relatedPlan}). Consider adding --spec-refs to link this WU to the plan.`);
+    }
+    return warnings;
+}
 /**
  * Check if WU already exists
  * @param {string} id - WU ID to check
@@ -211,8 +226,8 @@ function createPlanTemplate(wuId, title) {
     console.log(`${LOG_PREFIX} ✅ Created plan template: ${planPath}`);
     return planPath;
 }
-function buildWUContent({ id, lane, title, priority, type, created, opts, }) {
-    const { description, acceptance, codePaths, testPathsManual, testPathsUnit, testPathsE2e, initiative, phase, blockedBy, blocks, labels, assignedTo, exposure, userJourney, uiPairingWus, specRefs, } = opts;
+export function buildWUContent({ id, lane, title, priority, type, created, opts, }) {
+    const { description, acceptance, notes, codePaths, testPathsManual, testPathsUnit, testPathsE2e, initiative, phase, blockedBy, blocks, labels, assignedTo, exposure, userJourney, uiPairingWus, specRefs, } = opts;
     // Arrays come directly from Commander.js repeatable options - no parsing needed
     const code_paths = codePaths ?? [];
     const tests = {
@@ -235,7 +250,7 @@ function buildWUContent({ id, lane, title, priority, type, created, opts, }) {
         artifacts: [`.lumenflow/stamps/${id}.done`],
         dependencies: [],
         risks: [],
-        notes: '',
+        notes: notes ?? '',
         requires_review: false,
         ...(initiative && { initiative }),
         ...(phase && { phase: parseInt(phase, 10) }),
@@ -285,7 +300,7 @@ export function validateCreateSpec({ id, lane, title, priority, type, opts, }) {
             errors.push('At least one test path flag is required (--test-paths-manual, --test-paths-unit, or --test-paths-e2e)');
         }
     }
-    if (effectiveType === 'feature' && !opts.specRefs) {
+    if (effectiveType === 'feature' && !hasSpecRefs(opts.specRefs)) {
         errors.push('--spec-refs is required for type: feature WUs\n' +
             '    Tip: Create a plan first with: pnpm plan:create --id <WU-ID> --title "..."\n' +
             '    Then use --plan flag or --spec-refs lumenflow://plans/<WU-ID>-plan.md');
@@ -511,6 +526,7 @@ async function main() {
             // WU-1364: Full spec inline options
             WU_OPTIONS.description,
             WU_OPTIONS.acceptance,
+            WU_OPTIONS.notes,
             WU_OPTIONS.codePaths,
             WU_OPTIONS.testPathsManual,
             WU_OPTIONS.testPathsUnit,
@@ -588,6 +604,7 @@ async function main() {
         opts: {
             description: args.description,
             acceptance: args.acceptance,
+            notes: args.notes,
             codePaths: args.codePaths,
             testPathsManual: args.testPathsManual,
             testPathsUnit: args.testPathsUnit,
@@ -613,16 +630,6 @@ async function main() {
         die(`${LOG_PREFIX} ❌ Spec validation failed:\n\n${errorList}`);
     }
     console.log(`${LOG_PREFIX} ✅ Spec validation passed`);
-    // WU-1211: Warn if linking to initiative with no phases defined
-    if (args.initiative) {
-        const initiative = findInitiative(args.initiative);
-        if (initiative) {
-            const phaseCheck = checkInitiativePhases(initiative.doc);
-            if (!phaseCheck.hasPhases && phaseCheck.warning) {
-                console.warn(`${LOG_PREFIX} ⚠️  ${phaseCheck.warning}`);
-            }
-        }
-    }
     const specRefsList = mergedSpecRefs;
     const specRefsValidation = validateSpecRefs(specRefsList);
     if (!specRefsValidation.valid) {
@@ -636,6 +643,20 @@ async function main() {
             console.warn(`${LOG_PREFIX} ⚠️  ${warning}`);
         }
     }
+    if (args.initiative) {
+        const initiative = findInitiative(args.initiative);
+        if (initiative) {
+            const warnings = collectInitiativeWarnings({
+                initiativeId: initiative.id,
+                initiativeDoc: initiative.doc,
+                phase: args.phase,
+                specRefs: specRefsList,
+            });
+            for (const warning of warnings) {
+                console.warn(`${LOG_PREFIX} ⚠️  ${warning}`);
+            }
+        }
+    }
     if (args.plan) {
         createPlanTemplate(wuId, args.title);
     }
@@ -664,6 +685,7 @@ async function main() {
                         // WU-1364: Full spec inline options
                         description: args.description,
                         acceptance: args.acceptance,
+                        notes: args.notes,
                         codePaths: args.codePaths,
                         testPathsManual: args.testPathsManual,
                         testPathsUnit: args.testPathsUnit,

package/dist/wu-recover.js

@@ -15,16 +15,19 @@
  *   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 { existsSync, rmSync, writeFileSync } 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 { CONTEXT_VALIDATION, EMOJI, WU_STATUS, DEFAULTS, toKebab, FILE_SYSTEM, } from '@lumenflow/core/dist/wu-constants.js';
 import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { WUStateStore } from '@lumenflow/core/dist/wu-state-store.js';
+import { generateBacklog, generateStatus } from '@lumenflow/core/dist/backlog-generator.js';
+import { releaseLaneLock } from '@lumenflow/core/dist/lane-lock.js';
 import { join, relative } from 'node:path';
 const { RECOVERY_ACTIONS } = CONTEXT_VALIDATION;
 const LOG_PREFIX = '[wu:recover]';
@@ -159,6 +162,7 @@ async function executeResume(wuId) {
  * Execute reset action - discard worktree and reset to ready
  *
  * WU-1226: Uses micro-worktree isolation for WU YAML state changes.
+ * WU-1419: Emits release event to state store so WU can be re-claimed.
  * Worktree removal still happens directly (git operation, not file write).
  * Changes are pushed via merge, not direct file modification on main.
  */
@@ -171,6 +175,7 @@ async function executeReset(wuId) {
     }
     const doc = readWU(wuPath, wuId);
     const worktreePath = getWorktreePath(wuId, doc.lane || '');
+    const lane = doc.lane || '';
     // Remove worktree if exists (git operation, safe to do directly)
     // WU-1097: Use worktreeRemove() instead of deprecated run() with shell strings
     // This properly handles paths with spaces and special characters
@@ -193,6 +198,7 @@ async function executeReset(wuId) {
         }
     }
     // WU-1226: Use micro-worktree isolation for WU YAML state changes
+    // WU-1419: Also emit release event to state store
     try {
         await withMicroWorktree({
             operation: OPERATION_NAME,
@@ -211,12 +217,57 @@ async function executeReset(wuId) {
                 Reflect.deleteProperty(microDoc, 'session_id');
                 Reflect.deleteProperty(microDoc, 'baseline_main_sha');
                 writeWU(microWuPath, microDoc);
+                // WU-1419: Emit release event to state store so re-claiming works
+                // Without this, state store still thinks WU is in_progress, blocking re-claim
+                const stateDir = join(microPath, '.lumenflow', 'state');
+                const store = new WUStateStore(stateDir);
+                await store.load();
+                // Only emit release event if WU is currently in_progress in state store
+                const currentState = store.getWUState(wuId);
+                if (currentState && currentState.status === 'in_progress') {
+                    await store.release(wuId, 'Reset via wu:recover --action reset');
+                    console.log(`${LOG_PREFIX} Emitted release event to state store`);
+                    // Regenerate backlog.md and status.md from state store
+                    const microBacklogPath = join(microPath, WU_PATHS.BACKLOG());
+                    const microStatusPath = join(microPath, WU_PATHS.STATUS());
+                    const backlogContent = await generateBacklog(store);
+                    writeFileSync(microBacklogPath, backlogContent, {
+                        encoding: FILE_SYSTEM.UTF8,
+                    });
+                    const statusContent = await generateStatus(store);
+                    writeFileSync(microStatusPath, statusContent, {
+                        encoding: FILE_SYSTEM.UTF8,
+                    });
+                    return {
+                        commitMessage: `fix(wu-recover): reset ${wuId} - clear claim and emit release event`,
+                        files: [
+                            relative(process.cwd(), wuPath),
+                            WU_PATHS.STATUS(),
+                            WU_PATHS.BACKLOG(),
+                            '.lumenflow/state/wu-events.jsonl',
+                        ],
+                    };
+                }
+                // WU not in state store as in_progress, just update YAML
                 return {
                     commitMessage: `fix(wu-recover): reset ${wuId} - clear claim and set status to ready`,
                     files: [relative(process.cwd(), wuPath)],
                 };
             },
         });
+        // Release lane lock so another WU can be claimed
+        if (lane) {
+            try {
+                const releaseResult = releaseLaneLock(lane, { wuId });
+                if (releaseResult.released && !releaseResult.notFound) {
+                    console.log(`${LOG_PREFIX} Lane lock released for "${lane}"`);
+                }
+            }
+            catch (err) {
+                // Non-blocking: lock release failure should not block the reset operation
+                console.warn(`${LOG_PREFIX} Warning: Could not release lane lock: ${err.message}`);
+            }
+        }
         console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Reset completed - ${wuId} is now ready for re-claiming`);
         return true;
     }

package/dist/wu-spawn.js

@@ -630,10 +630,10 @@ When creating \`.lumenflow/\` stamps or other artifacts:
 # CORRECT: Create stamp in worktree
 WORKTREE_ROOT=$(git rev-parse --show-toplevel)
 mkdir -p "$WORKTREE_ROOT/.lumenflow/agent-runs"
-touch "$WORKTREE_ROOT/.lumenflow/agent-runs/beacon-guardian.stamp"
+touch "$WORKTREE_ROOT/.lumenflow/agent-runs/code-reviewer.stamp"
 
 # WRONG: Hardcoded path to main
-# touch /path/to/main/.lumenflow/agent-runs/beacon-guardian.stamp
+# touch /path/to/main/.lumenflow/agent-runs/code-reviewer.stamp
 \`\`\`
 
 ### Why This Matters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -151,11 +151,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "2.9.0",
-    "@lumenflow/metrics": "2.9.0",
-    "@lumenflow/memory": "2.9.0",
-    "@lumenflow/agent": "2.9.0",
-    "@lumenflow/initiatives": "2.9.0"
+    "@lumenflow/core": "2.11.0",
+    "@lumenflow/metrics": "2.11.0",
+    "@lumenflow/memory": "2.11.0",
+    "@lumenflow/initiatives": "2.11.0",
+    "@lumenflow/agent": "2.11.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",

package/templates/core/.mcp.json.template

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "lumenflow": {
+      "command": "npx",
+      "args": ["@lumenflow/mcp"]
+    }
+  }
+}

package/templates/core/LUMENFLOW.md.template

@@ -53,6 +53,30 @@ cd /path/to/main && pnpm wu:done --id WU-XXXX
 
 ---
 
+## When to Use Initiatives
+
+Use **Initiatives** for multi-phase work spanning multiple WUs:
+
+- **Product visions**: "Build a task management app"
+- **Larger features**: Work requiring multiple WUs across lanes
+- **Complex projects**: Anything that needs phased delivery
+
+```bash
+# Create an initiative for multi-phase work
+pnpm initiative:create --id INIT-001 --title "Feature Name" \
+  --description "..." --phase "Phase 1: MVP" --phase "Phase 2: Polish"
+
+# Add WUs to the initiative
+pnpm initiative:add-wu --initiative INIT-001 --wu WU-XXX --phase 1
+
+# Track progress
+pnpm initiative:status --id INIT-001
+```
+
+**Skip initiatives** for: single-file bug fixes, small docs updates, isolated refactoring.
+
+---
+
 ## Setup Notes (Common First-Run Failures)
 
 ### Lane inference (sub-lanes)