@lumenflow/cli 2.10.0 → 2.11.0

package/README.md

@@ -134,7 +134,7 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 | Command           | Description                                                                                |
 | ----------------- | ------------------------------------------------------------------------------------------ |
 | `gates`           | Run quality gates with support for docs-only mode, incremental linting, and tiered testing |
-| `lumenflow-gates` | Alias for `gates` - run quality gates with support for docs-only mode and tiered testing   |
+| `lumenflow-gates` | Alias for `gates` command                                                                  |
 
 ### System & Setup
 
@@ -202,7 +202,7 @@ pnpm wu:done --id WU-123
 
 # Memory operations
 pnpm mem:checkpoint "Completed port definitions" --wu WU-123
-pnpm mem:inbox --unread
+pnpm mem:inbox --since 10m
 
 # Initiative management
 pnpm initiative:status INIT-007
@@ -245,6 +245,27 @@ The CLI integrates with other LumenFlow packages:
 - `@lumenflow/agent` - Agent session management
 - `@lumenflow/initiatives` - Initiative tracking
 
+## MCP Server Setup (Claude Code)
+
+LumenFlow provides an MCP (Model Context Protocol) server for deep integration with Claude Code.
+
+When you run `lumenflow init --client claude`, a `.mcp.json` is automatically created:
+
+```json
+{
+  "mcpServers": {
+    "lumenflow": {
+      "command": "npx",
+      "args": ["@lumenflow/mcp"]
+    }
+  }
+}
+```
+
+The `@lumenflow/mcp` server provides tools for WU lifecycle, memory coordination, and lane management directly within Claude Code.
+
+See [AI Integrations](https://lumenflow.dev/guides/ai-integrations) for full MCP documentation.
+
 ## Documentation
 
 For complete documentation, see [lumenflow.dev](https://lumenflow.dev/reference/cli).

package/dist/__tests__/gates-integration-tests.test.js

@@ -0,0 +1,112 @@
+/**
+ * @file gates-integration-tests.test.ts
+ * @description Tests for gates infrastructure fixes (WU-1415)
+ *
+ * Bug 1: vitest --include is not a valid CLI option
+ * Bug 2: docs-only turbo filter uses directory names instead of package names
+ */
+import { describe, it, expect } from 'vitest';
+import { extractPackagesFromCodePaths, resolveDocsOnlyTestPlan } from '../gates.js';
+describe('WU-1415: Gates infrastructure fixes', () => {
+    describe('Bug 1: vitest integration test command', () => {
+        it('should NOT use --include flag (vitest does not support it)', async () => {
+            // Import the module to inspect the command construction
+            // We need to verify that runIntegrationTests uses valid vitest syntax
+            //
+            // vitest run accepts positional glob patterns, NOT --include flags:
+            //   WRONG: vitest run --include='**/*.integration.*'
+            //   RIGHT: vitest run '**/*.integration.*'
+            //
+            // This test ensures we're using the correct vitest CLI syntax
+            const gatesModule = await import('../gates.js');
+            // The command construction happens in runIntegrationTests
+            // We can't directly test the internal function, but we can verify
+            // via the module's exported constants or by checking the implementation
+            // doesn't contain --include
+            // Read the source to verify no --include in vitest commands
+            const fs = await import('fs');
+            const path = await import('path');
+            const gatesPath = path.join(import.meta.dirname, '..', 'gates.ts');
+            const source = fs.readFileSync(gatesPath, 'utf-8');
+            // Find the runIntegrationTests function and check it doesn't use --include
+            const integrationTestMatch = source.match(/function runIntegrationTests[\s\S]*?^}/m);
+            if (integrationTestMatch) {
+                const functionBody = integrationTestMatch[0];
+                // vitest run should NOT have --include flags
+                expect(functionBody).not.toMatch(/vitest.*--include/);
+                // Instead, glob patterns should be positional args or via proper config
+                // The fix should pass patterns directly: vitest run 'pattern1' 'pattern2'
+            }
+        });
+    });
+    describe('Bug 2: docs-only turbo filter', () => {
+        describe('extractPackagesFromCodePaths', () => {
+            it('should extract scoped package names from packages/ paths', () => {
+                const codePaths = [
+                    'packages/@lumenflow/cli/src/gates.ts',
+                    'packages/@lumenflow/core/src/index.ts',
+                ];
+                const packages = extractPackagesFromCodePaths(codePaths);
+                expect(packages).toContain('@lumenflow/cli');
+                expect(packages).toContain('@lumenflow/core');
+            });
+            it('should return empty array for apps/ paths that are not real turbo packages', () => {
+                // apps/docs/ directory name is 'docs' but the turbo package might be
+                // named differently (e.g., '@lumenflow/docs' or not exist at all)
+                //
+                // The current implementation returns 'docs' which causes turbo to fail:
+                //   "No package found with name 'docs' in workspace"
+                //
+                // Fix: Either lookup actual package.json name or skip apps
+                const codePaths = ['apps/docs/src/content/docs/', 'apps/github-app/'];
+                const packages = extractPackagesFromCodePaths(codePaths);
+                // Current buggy behavior returns ['docs', 'github-app']
+                // Fixed behavior should either:
+                // - Return actual package names from package.json
+                // - Or return empty array (apps don't have turbo test tasks)
+                //
+                // For now, the fix should skip apps that aren't valid turbo packages
+                // because apps/docs has no test script and apps/github-app was deleted
+                expect(packages).not.toContain('docs');
+                expect(packages).not.toContain('github-app');
+            });
+            it('should handle mixed code_paths (packages + apps + docs)', () => {
+                const codePaths = [
+                    'packages/@lumenflow/cli/src/file.ts',
+                    'apps/docs/astro.config.mjs',
+                    'docs/DISTRIBUTION.md',
+                ];
+                const packages = extractPackagesFromCodePaths(codePaths);
+                // Should include the real package
+                expect(packages).toContain('@lumenflow/cli');
+                // Should NOT include apps (no valid turbo package)
+                expect(packages).not.toContain('docs');
+                // Should NOT include docs/ (not a package)
+                expect(packages.length).toBe(1);
+            });
+            it('should return empty array for pure docs paths', () => {
+                const codePaths = ['docs/01-product/product-lines.md', 'docs/DISTRIBUTION.md'];
+                const packages = extractPackagesFromCodePaths(codePaths);
+                expect(packages).toEqual([]);
+            });
+        });
+        describe('resolveDocsOnlyTestPlan', () => {
+            it('should return skip mode for pure documentation WUs', () => {
+                const plan = resolveDocsOnlyTestPlan({
+                    codePaths: ['docs/README.md', 'apps/docs/content/'],
+                });
+                expect(plan.mode).toBe('skip');
+                expect(plan.packages).toEqual([]);
+            });
+            it('should return filtered mode only for valid package paths', () => {
+                const plan = resolveDocsOnlyTestPlan({
+                    codePaths: ['packages/@lumenflow/cli/src/gates.ts', 'apps/docs/content/'],
+                });
+                expect(plan.mode).toBe('filtered');
+                expect(plan.packages).toContain('@lumenflow/cli');
+                // apps/docs should not be included
+                expect(plan.packages).not.toContain('docs');
+            });
+        });
+    });
+});

package/dist/__tests__/init.test.js

@@ -740,4 +740,229 @@ describe('lumenflow init', () => {
             });
         });
     });
+    // WU-1408: safe-git and pre-commit hook scaffolding
+    describe('WU-1408: safe-git and pre-commit scaffolding', () => {
+        describe('safe-git wrapper', () => {
+            it('should scaffold scripts/safe-git', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const safeGitPath = path.join(tempDir, 'scripts', 'safe-git');
+                expect(fs.existsSync(safeGitPath)).toBe(true);
+            });
+            it('should make safe-git executable', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const safeGitPath = path.join(tempDir, 'scripts', 'safe-git');
+                const stats = fs.statSync(safeGitPath);
+                // Check for executable bit (owner, group, or other)
+                // eslint-disable-next-line no-bitwise
+                const isExecutable = (stats.mode & 0o111) !== 0;
+                expect(isExecutable).toBe(true);
+            });
+            it('should include worktree remove block in safe-git', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const safeGitPath = path.join(tempDir, 'scripts', 'safe-git');
+                const content = fs.readFileSync(safeGitPath, 'utf-8');
+                expect(content).toContain('worktree');
+                expect(content).toContain('remove');
+                expect(content).toContain('BLOCKED');
+            });
+            it('should scaffold safe-git even in minimal mode', async () => {
+                const options = {
+                    force: false,
+                    full: false, // minimal mode
+                };
+                await scaffoldProject(tempDir, options);
+                const safeGitPath = path.join(tempDir, 'scripts', 'safe-git');
+                expect(fs.existsSync(safeGitPath)).toBe(true);
+            });
+        });
+        describe('pre-commit hook', () => {
+            it('should scaffold .husky/pre-commit', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                expect(fs.existsSync(preCommitPath)).toBe(true);
+            });
+            it('should make pre-commit executable', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                const stats = fs.statSync(preCommitPath);
+                // eslint-disable-next-line no-bitwise
+                const isExecutable = (stats.mode & 0o111) !== 0;
+                expect(isExecutable).toBe(true);
+            });
+            it('should NOT run pnpm test in pre-commit hook', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                const content = fs.readFileSync(preCommitPath, 'utf-8');
+                // The pre-commit hook should NOT assume pnpm test exists
+                expect(content).not.toContain('pnpm test');
+                expect(content).not.toContain('npm test');
+            });
+            it('should block commits to main/master in pre-commit', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                const content = fs.readFileSync(preCommitPath, 'utf-8');
+                // Should protect main branch
+                expect(content).toContain('main');
+                expect(content).toContain('BLOCK');
+            });
+            it('should scaffold pre-commit even in minimal mode', async () => {
+                const options = {
+                    force: false,
+                    full: false, // minimal mode
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                expect(fs.existsSync(preCommitPath)).toBe(true);
+            });
+        });
+    });
+    // WU-1413: MCP server configuration scaffolding
+    describe('WU-1413: .mcp.json scaffolding', () => {
+        const MCP_JSON_FILE = '.mcp.json';
+        describe('.mcp.json creation with --client claude', () => {
+            it('should scaffold .mcp.json when --client claude is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(true);
+            });
+            it('should include lumenflow MCP server configuration', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                const content = fs.readFileSync(mcpJsonPath, 'utf-8');
+                const mcpConfig = JSON.parse(content);
+                // Should have mcpServers key
+                expect(mcpConfig.mcpServers).toBeDefined();
+                // Should have lumenflow server entry
+                expect(mcpConfig.mcpServers.lumenflow).toBeDefined();
+                // Should use npx command
+                expect(mcpConfig.mcpServers.lumenflow.command).toBe('npx');
+                // Should reference @lumenflow/mcp package
+                expect(mcpConfig.mcpServers.lumenflow.args).toContain('@lumenflow/mcp');
+            });
+            it('should be valid JSON', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                const content = fs.readFileSync(mcpJsonPath, 'utf-8');
+                // Should parse without error
+                expect(() => JSON.parse(content)).not.toThrow();
+            });
+        });
+        describe('.mcp.json creation with --client all', () => {
+            it('should scaffold .mcp.json when --client all is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'all',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(true);
+            });
+        });
+        describe('.mcp.json NOT created with other clients', () => {
+            it('should NOT scaffold .mcp.json when --client none is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'none',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(false);
+            });
+            it('should NOT scaffold .mcp.json when --client cursor is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'cursor',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(false);
+            });
+            it('should NOT scaffold .mcp.json when no client is specified', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(false);
+            });
+        });
+        describe('.mcp.json file modes', () => {
+            it('should skip .mcp.json if it already exists (skip mode)', async () => {
+                // Create existing .mcp.json
+                const existingContent = '{"mcpServers":{"custom":{}}}';
+                fs.writeFileSync(path.join(tempDir, MCP_JSON_FILE), existingContent);
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                const result = await scaffoldProject(tempDir, options);
+                expect(result.skipped).toContain(MCP_JSON_FILE);
+                // Content should not be changed
+                const content = fs.readFileSync(path.join(tempDir, MCP_JSON_FILE), 'utf-8');
+                expect(content).toBe(existingContent);
+            });
+            it('should overwrite .mcp.json in force mode', async () => {
+                // Create existing .mcp.json
+                fs.writeFileSync(path.join(tempDir, MCP_JSON_FILE), '{"custom":true}');
+                const options = {
+                    force: true,
+                    full: false,
+                    client: 'claude',
+                };
+                const result = await scaffoldProject(tempDir, options);
+                expect(result.created).toContain(MCP_JSON_FILE);
+                const content = fs.readFileSync(path.join(tempDir, MCP_JSON_FILE), 'utf-8');
+                const mcpConfig = JSON.parse(content);
+                expect(mcpConfig.mcpServers.lumenflow).toBeDefined();
+            });
+        });
+    });
 });

package/dist/__tests__/safe-git.test.js

@@ -13,7 +13,7 @@ const USER_NAME_CONFIG = 'user.name';
 const TEST_EMAIL = 'test@test.com';
 const TEST_USERNAME = 'Test';
 const FORCE_BYPASSES_LOG = 'force-bypasses.log';
-// Create a temporary directory for testing to avoid polluting the real .beacon directory
+// Create a temporary directory for testing to avoid polluting the real .lumenflow directory
 const createTempDir = () => {
     return fs.mkdtempSync(path.join(os.tmpdir(), 'safe-git-test-'));
 };
@@ -128,7 +128,7 @@ describe('safe-git', () => {
                 env: { ...process.env, LUMENFLOW_FORCE: '1' },
             });
             // Check that the force bypass log exists and contains the entry
-            const bypassLog = path.join(testRepo, '.beacon', FORCE_BYPASSES_LOG);
+            const bypassLog = path.join(testRepo, '.lumenflow', FORCE_BYPASSES_LOG);
             expect(fs.existsSync(bypassLog)).toBe(true);
             const logContent = fs.readFileSync(bypassLog, 'utf-8');
             expect(logContent).toContain('reset --hard');
@@ -155,7 +155,7 @@ describe('safe-git', () => {
                 encoding: 'utf-8',
                 env: { ...process.env, LUMENFLOW_FORCE: '1', LUMENFLOW_FORCE_REASON: testReason },
             });
-            const bypassLog = path.join(testRepo, '.beacon', FORCE_BYPASSES_LOG);
+            const bypassLog = path.join(testRepo, '.lumenflow', FORCE_BYPASSES_LOG);
             const logContent = fs.readFileSync(bypassLog, 'utf-8');
             expect(logContent).toContain(testReason);
         });
@@ -182,7 +182,7 @@ describe('safe-git', () => {
                 stdio: ['pipe', 'pipe', 'pipe'],
             });
             // Check the bypasslog for the NO_REASON marker
-            const bypassLog = path.join(testRepo, '.beacon', FORCE_BYPASSES_LOG);
+            const bypassLog = path.join(testRepo, '.lumenflow', FORCE_BYPASSES_LOG);
             const logContent = fs.readFileSync(bypassLog, 'utf-8');
             expect(logContent).toContain('NO_REASON');
         });

package/dist/__tests__/wu-create-required-fields.test.js

@@ -82,6 +82,28 @@ describe('wu:create required field aggregation (WU-1366)', () => {
             expect(result.valid).toBe(false);
             expect(result.errors.some((e) => e.includes('--spec-refs'))).toBe(true);
         });
+        it('should treat empty spec-refs array as missing for feature WUs', () => {
+            const result = validateCreateSpec({
+                id: TEST_WU_ID,
+                lane: TEST_LANE,
+                title: 'Test WU',
+                priority: 'P2',
+                type: 'feature',
+                opts: {
+                    description: VALID_DESCRIPTION,
+                    acceptance: TEST_ACCEPTANCE,
+                    exposure: 'backend-only',
+                    codePaths: ['packages/@lumenflow/cli/src/wu-create.ts'],
+                    testPathsUnit: [
+                        'packages/@lumenflow/cli/src/__tests__/wu-create-required-fields.test.ts',
+                    ],
+                    specRefs: [],
+                    strict: false,
+                },
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes('--spec-refs'))).toBe(true);
+        });
         it('should return all errors at once, not fail on first error', () => {
             const result = validateCreateSpec({
                 id: TEST_WU_ID,

package/dist/__tests__/wu-create.test.js

@@ -0,0 +1,72 @@
+/**
+ * @file wu-create.test.ts
+ * Tests for wu:create helpers and warnings (WU-1429)
+ */
+import { describe, it, expect } from 'vitest';
+import { buildWUContent, collectInitiativeWarnings } from '../wu-create.js';
+const BASE_WU = {
+    id: 'WU-1429',
+    lane: 'Framework: CLI',
+    title: 'Test WU',
+    priority: 'P2',
+    type: 'feature',
+    created: '2026-02-04',
+    opts: {
+        description: 'Context: test context.\nProblem: test problem.\nSolution: test solution that exceeds minimum.',
+        acceptance: ['Acceptance criterion'],
+        exposure: 'backend-only',
+        codePaths: ['packages/@lumenflow/cli/src/wu-create.ts'],
+        testPathsUnit: ['packages/@lumenflow/cli/src/__tests__/wu-create.test.ts'],
+        specRefs: ['lumenflow://plans/WU-1429-plan.md'],
+    },
+};
+describe('wu:create helpers (WU-1429)', () => {
+    it('should persist notes when provided', () => {
+        const wu = buildWUContent({
+            ...BASE_WU,
+            opts: {
+                ...BASE_WU.opts,
+                notes: 'Implementation notes for test',
+            },
+        });
+        expect(wu.notes).toBe('Implementation notes for test');
+    });
+    it('should warn when initiative has phases but no --phase is provided', () => {
+        const warnings = collectInitiativeWarnings({
+            initiativeId: 'INIT-TEST',
+            initiativeDoc: {
+                phases: [{ id: 1, title: 'Phase 1' }],
+            },
+            phase: undefined,
+            specRefs: ['lumenflow://plans/WU-1429-plan.md'],
+        });
+        expect(warnings).toEqual(expect.arrayContaining([
+            'Initiative INIT-TEST has phases defined. Consider adding --phase to link this WU to a phase.',
+        ]));
+    });
+    it('should warn when initiative has related_plan but no spec_refs', () => {
+        const warnings = collectInitiativeWarnings({
+            initiativeId: 'INIT-TEST',
+            initiativeDoc: {
+                related_plan: 'lumenflow://plans/INIT-TEST-plan.md',
+            },
+            phase: '1',
+            specRefs: [],
+        });
+        expect(warnings).toEqual(expect.arrayContaining([
+            'Initiative INIT-TEST has related_plan (lumenflow://plans/INIT-TEST-plan.md). Consider adding --spec-refs to link this WU to the plan.',
+        ]));
+    });
+    it('should not warn when phase and spec_refs are provided', () => {
+        const warnings = collectInitiativeWarnings({
+            initiativeId: 'INIT-TEST',
+            initiativeDoc: {
+                phases: [{ id: 1, title: 'Phase 1' }],
+                related_plan: 'lumenflow://plans/INIT-TEST-plan.md',
+            },
+            phase: '1',
+            specRefs: ['lumenflow://plans/WU-1429-plan.md'],
+        });
+        expect(warnings).toEqual([]);
+    });
+});

package/dist/gates.js

@@ -294,13 +294,9 @@ function extractPackageFromPath(codePath) {
             return parts[0];
         }
     }
-    // Handle apps/name/...
-    if (normalized.startsWith('apps/')) {
-        const parts = normalized.slice('apps/'.length).split('/');
-        if (parts[0]) {
-            return parts[0];
-        }
-    }
+    // WU-1415: Skip apps/ paths - they aren't valid turbo packages for test filtering
+    // apps/ directories (e.g., apps/docs, apps/github-app) don't have turbo test tasks
+    // and using directory names as --filter args causes "No package found" errors
     return null;
 }
 /**
@@ -1004,7 +1000,9 @@ async function runIntegrationTests({ agentLog, } = {}) {
     };
     try {
         logLine('\n> Integration tests (high-risk changes detected)\n');
-        const result = run(`RUN_INTEGRATION_TESTS=1 ${pnpmCmd('vitest', 'run', "--include='**/*.integration.*'", "--include='**/golden-*.test.*'")}`, { agentLog });
+        // WU-1415: vitest doesn't support --include flag
+        // Pass glob patterns as positional arguments instead
+        const result = run(`RUN_INTEGRATION_TESTS=1 ${pnpmCmd('vitest', 'run', "'**/*.integration.*'", "'**/golden-*.test.*'")}`, { agentLog });
         const duration = Date.now() - start;
         return {
             ok: result.ok,

package/dist/init.js

@@ -699,6 +699,16 @@ pnpm wu:done --id WU-XXX
 `;
 // Template for .aider.conf.yml
 const AIDER_CONF_TEMPLATE = `# Aider Configuration for LumenFlow Projects\n# See LUMENFLOW.md for workflow documentation\n\nmodel: gpt-4-turbo\nauto-commits: false\ndirty-commits: false\n\nread:\n  - LUMENFLOW.md\n  - .lumenflow/constraints.md\n`;
+// WU-1413: Template for .mcp.json (MCP server configuration for Claude Code)
+const MCP_JSON_TEMPLATE = `{
+  "mcpServers": {
+    "lumenflow": {
+      "command": "npx",
+      "args": ["@lumenflow/mcp"]
+    }
+  }
+}
+`;
 // Template for docs/04-operations/tasks/backlog.md
 const BACKLOG_TEMPLATE = `---\nsections:\n  ready:\n    heading: '## 🚀 Ready (pull from here)'\n    insertion: after_heading_blank_line\n  in_progress:\n    heading: '## 🔧 In progress'\n    insertion: after_heading_blank_line\n  blocked:\n    heading: '## ⛔ Blocked'\n    insertion: after_heading_blank_line\n  done:\n    heading: '## ✅ Done'\n    insertion: after_heading_blank_line\n---\n\n# Backlog (single source of truth)\n\n## 🚀 Ready (pull from here)\n\n(No items ready)\n\n## 🔧 In progress\n\n(No items in progress)\n\n## ⛔ Blocked\n\n(No items blocked)\n\n## ✅ Done\n\n(No items completed yet)\n`;
 // Template for docs/04-operations/tasks/status.md
@@ -2364,6 +2374,9 @@ export async function scaffoldProject(targetDir, options) {
     await createFile(path.join(targetDir, LUMENFLOW_AGENTS_DIR, '.gitkeep'), '', options.force ? 'force' : 'skip', result, targetDir);
     // WU-1342: Create .gitignore with required exclusions
     await scaffoldGitignore(targetDir, options, result);
+    // WU-1408: Scaffold safe-git wrapper and pre-commit hook
+    // These are core safety components needed for all projects
+    await scaffoldSafetyScripts(targetDir, options, result);
     // Optional: full docs scaffolding
     if (options.full) {
         await scaffoldFullDocs(targetDir, options, result, tokenDefaults);
@@ -2490,6 +2503,128 @@ const LUMENFLOW_SCRIPTS = {
     gates: 'gates',
     'gates:docs': 'gates --docs-only',
 };
+/** WU-1408: Safety script path constants */
+const SCRIPTS_DIR = 'scripts';
+const SAFE_GIT_FILE = 'safe-git';
+const HUSKY_DIR = '.husky';
+const PRE_COMMIT_FILE = 'pre-commit';
+const SAFE_GIT_TEMPLATE_PATH = 'core/scripts/safe-git.template';
+const PRE_COMMIT_TEMPLATE_PATH = 'core/.husky/pre-commit.template';
+/**
+ * WU-1408: Scaffold safety scripts (safe-git wrapper and pre-commit hook)
+ * These are core safety components needed for LumenFlow enforcement:
+ * - scripts/safe-git: Blocks dangerous git operations (e.g., manual worktree remove)
+ * - .husky/pre-commit: Blocks direct commits to main/master, enforces WU workflow
+ *
+ * Both scripts are scaffolded in all modes (full and minimal) because they are
+ * required for lumenflow-doctor to pass.
+ */
+async function scaffoldSafetyScripts(targetDir, options, result) {
+    const fileMode = getFileMode(options);
+    // Scaffold scripts/safe-git
+    const safeGitPath = path.join(targetDir, SCRIPTS_DIR, SAFE_GIT_FILE);
+    try {
+        const safeGitTemplate = loadTemplate(SAFE_GIT_TEMPLATE_PATH);
+        await createExecutableScript(safeGitPath, safeGitTemplate, fileMode, result, targetDir);
+    }
+    catch {
+        // Fallback to hardcoded template if template file not found
+        await createExecutableScript(safeGitPath, SAFE_GIT_TEMPLATE, fileMode, result, targetDir);
+    }
+    // Scaffold .husky/pre-commit
+    const preCommitPath = path.join(targetDir, HUSKY_DIR, PRE_COMMIT_FILE);
+    try {
+        const preCommitTemplate = loadTemplate(PRE_COMMIT_TEMPLATE_PATH);
+        await createExecutableScript(preCommitPath, preCommitTemplate, fileMode, result, targetDir);
+    }
+    catch {
+        // Fallback to hardcoded template if template file not found
+        await createExecutableScript(preCommitPath, PRE_COMMIT_TEMPLATE, fileMode, result, targetDir);
+    }
+}
+/**
+ * WU-1408: Fallback safe-git template
+ * Blocks dangerous git operations in LumenFlow environment
+ */
+const SAFE_GIT_TEMPLATE = `#!/bin/sh
+#
+# safe-git - LumenFlow safety wrapper for git
+#
+# Blocks dangerous operations that can corrupt agent state.
+# For all other commands, passes through to system git.
+#
+
+set -e
+
+# Block 'worktree remove'
+if [ "$1" = "worktree" ] && [ "$2" = "remove" ]; then
+  echo "" >&2
+  echo "=== LUMENFLOW SAFETY BLOCK ===" >&2
+  echo "" >&2
+  echo "BLOCKED: Manual 'git worktree remove' is unsafe in this environment." >&2
+  echo "" >&2
+  echo "REASON: Manual removal leaves orphan directories and corrupts agent state." >&2
+  echo "" >&2
+  echo "USE INSTEAD:" >&2
+  echo "  pnpm wu:done --id <ID>    (To complete a task)" >&2
+  echo "  pnpm wu:cleanup --id <ID> (To discard a task)" >&2
+  echo "==============================" >&2
+  exit 1
+fi
+
+# Pass through to real git
+exec git "$@"
+`;
+/**
+ * WU-1408: Fallback pre-commit template
+ * Blocks direct commits to main/master, allows commits on lane branches
+ * Does NOT run pnpm test (which fails on new projects)
+ */
+const PRE_COMMIT_TEMPLATE = `#!/bin/sh
+#
+# LumenFlow Pre-Commit Hook
+#
+# Enforces worktree discipline by blocking direct commits to main/master.
+# Does NOT assume pnpm test or any other commands exist.
+#
+# Rules:
+#   1. BLOCK commits to main/master (use WU workflow instead)
+#   2. ALLOW commits on lane branches (lane/*/wu-*)
+#   3. ALLOW commits on tmp/* branches (CLI micro-worktrees)
+#
+
+# Skip on tmp/* branches (CLI micro-worktrees)
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+case "$BRANCH" in tmp/*) exit 0 ;; esac
+
+# Check for force bypass
+if [ "$LUMENFLOW_FORCE" = "1" ]; then
+  exit 0
+fi
+
+# Block direct commits to main/master
+case "$BRANCH" in
+  main|master)
+    echo "" >&2
+    echo "=== DIRECT COMMIT TO \${BRANCH} BLOCKED ===" >&2
+    echo "" >&2
+    echo "LumenFlow protects main from direct commits." >&2
+    echo "" >&2
+    echo "USE INSTEAD:" >&2
+    echo "  pnpm wu:claim --id WU-XXXX --lane \\"<Lane>\\"" >&2
+    echo "  cd worktrees/<lane>-wu-xxxx" >&2
+    echo "  # Make commits in the worktree" >&2
+    echo "" >&2
+    echo "EMERGENCY BYPASS (logged):" >&2
+    echo "  LUMENFLOW_FORCE=1 git commit ..." >&2
+    echo "==========================================" >&2
+    exit 1
+    ;;
+esac
+
+# Allow commits on other branches
+exit 0
+`;
 /**
  * WU-1300: Inject LumenFlow scripts into package.json
  * - Creates package.json if it doesn't exist
@@ -2657,6 +2792,15 @@ async function scaffoldClientFiles(targetDir, options, result, tokens, client) {
             settingsContent = CLAUDE_SETTINGS_TEMPLATE;
         }
         await createFile(path.join(targetDir, CLAUDE_DIR, 'settings.json'), settingsContent, options.force ? 'force' : 'skip', result, targetDir);
+        // WU-1413: Scaffold .mcp.json for MCP server integration
+        let mcpJsonContent;
+        try {
+            mcpJsonContent = loadTemplate('core/.mcp.json.template');
+        }
+        catch {
+            mcpJsonContent = MCP_JSON_TEMPLATE;
+        }
+        await createFile(path.join(targetDir, '.mcp.json'), mcpJsonContent, fileMode, result, targetDir);
         // WU-1394: Scaffold recovery hook scripts with executable permissions
         const hooksDir = path.join(targetDir, CLAUDE_DIR, 'hooks');
         await createDirectory(hooksDir, result, targetDir);

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.10.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.10.0",
-    "@lumenflow/metrics": "2.10.0",
-    "@lumenflow/initiatives": "2.10.0",
-    "@lumenflow/agent": "2.10.0",
-    "@lumenflow/memory": "2.10.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/ai/onboarding/vendor-support.md.template

@@ -55,6 +55,13 @@ Claude Code is Anthropic's official CLI for Claude. It has the deepest integrati
 - `.claude/settings.json` - Permission configuration
 - `.claude/agents/` - Agent definitions
 - `.claude/skills/` - Skill definitions
+- `.mcp.json` - MCP server configuration (WU-1413)
+
+**MCP Integration:** Claude Code supports MCP (Model Context Protocol) servers. When initializing with `--client claude`, LumenFlow automatically configures the `@lumenflow/mcp` server which provides:
+
+- WU lifecycle tools (status, claim, gates)
+- Memory coordination tools (checkpoint, signal, inbox)
+- Lane management tools (health, suggest)
 
 **Auto-detection:** Environment variables `CLAUDE_PROJECT_DIR` or `CLAUDE_CODE`
 
@@ -194,6 +201,72 @@ This creates all vendor-specific configuration files alongside the universal ent
 
 ---
 
+## MCP Server Integration
+
+LumenFlow provides an MCP (Model Context Protocol) server package for deeper AI integration.
+
+### What is MCP?
+
+MCP is a protocol that allows AI assistants to access tools and context from external servers. LumenFlow's MCP server (`@lumenflow/mcp`) exposes workflow tools directly to compatible AI assistants.
+
+### Supported Assistants
+
+| Assistant     | MCP Support | Configuration   |
+| ------------- | ----------- | --------------- |
+| Claude Code   | Yes         | `.mcp.json`     |
+| Antigravity   | Yes         | TBD             |
+| Cursor        | No          | Uses rules file |
+| Windsurf      | No          | Uses rules file |
+
+### Setup (Claude Code)
+
+When you run `lumenflow init --client claude`, a `.mcp.json` is automatically created:
+
+```json
+{
+  "mcpServers": {
+    "lumenflow": {
+      "command": "npx",
+      "args": ["@lumenflow/mcp"]
+    }
+  }
+}
+```
+
+### Manual Setup
+
+If you already have LumenFlow but need to add MCP support:
+
+```bash
+# Option 1: Re-run init with force to regenerate all files
+lumenflow init --client claude --force
+
+# Option 2: Manually create .mcp.json
+echo '{
+  "mcpServers": {
+    "lumenflow": {
+      "command": "npx",
+      "args": ["@lumenflow/mcp"]
+    }
+  }
+}' > .mcp.json
+```
+
+### Available MCP Tools
+
+The `@lumenflow/mcp` server provides these tools to AI assistants:
+
+| Tool           | Description                          |
+| -------------- | ------------------------------------ |
+| `wu_status`    | Get current WU status and location   |
+| `wu_claim`     | Claim a WU and create worktree       |
+| `gates`        | Run quality gates                    |
+| `mem_checkpoint` | Save progress checkpoint           |
+| `mem_inbox`    | Check coordination signals           |
+| `lane_health`  | Check lane configuration health      |
+
+---
+
 ## Sync Vendor Configs
 
 To ensure all vendor configs are in sync with the template:

package/templates/core/scripts/safe-git.template

@@ -0,0 +1,29 @@
+#!/bin/sh
+#
+# safe-git
+#
+# A wrapper around git that blocks dangerous operations in the LumenFlow environment.
+# Specifically intercepts 'worktree remove' to prevent orphan directories and state corruption.
+# For all other commands, it passes through to the system git.
+#
+
+set -e
+
+# Block 'worktree remove'
+if [ "$1" = "worktree" ] && [ "$2" = "remove" ]; then
+  echo "" >&2
+  echo "=== LUMENFLOW SAFETY BLOCK ===" >&2
+  echo "" >&2
+  echo "BLOCKED: Manual 'git worktree remove' is unsafe in this environment." >&2
+  echo "" >&2
+  echo "REASON: Manual removal leaves orphan directories and corrupts agent state." >&2
+  echo "" >&2
+  echo "USE INSTEAD:" >&2
+  echo "  pnpm wu:done --id <ID>    (To complete a task)" >&2
+  echo "  pnpm wu:cleanup --id <ID> (To discard a task)" >&2
+  echo "==============================" >&2
+  exit 1
+fi
+
+# Pass through to real git
+exec git "$@"