@lumenflow/cli 1.3.0 → 1.3.3

package/dist/__tests__/cli-entry-point.test.js

@@ -0,0 +1,111 @@
+/**
+ * Tests for CLI entry point error handling
+ *
+ * Verifies that runCLI wrapper properly:
+ * - Catches async errors from main()
+ * - Logs error messages to stderr
+ * - Exits with EXIT_CODES.ERROR on failure
+ *
+ * WU-1071: Also verifies that CLI entry points use import.meta.main pattern
+ * instead of the broken process.argv[1] === fileURLToPath(import.meta.url) pattern.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { runCLI } from '../cli-entry-point.js';
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+describe('runCLI', () => {
+    let mockExit;
+    let mockConsoleError;
+    beforeEach(() => {
+        mockExit = vi.spyOn(process, 'exit').mockImplementation(() => undefined);
+        mockConsoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        mockExit.mockRestore();
+        mockConsoleError.mockRestore();
+    });
+    it('should call main() and do nothing on success', async () => {
+        const main = vi.fn().mockResolvedValue(undefined);
+        await runCLI(main);
+        expect(main).toHaveBeenCalledOnce();
+        expect(mockExit).not.toHaveBeenCalled();
+        expect(mockConsoleError).not.toHaveBeenCalled();
+    });
+    it('should catch errors and exit with ERROR code', async () => {
+        const error = new Error('Test error message');
+        const main = vi.fn().mockRejectedValue(error);
+        await runCLI(main);
+        expect(main).toHaveBeenCalledOnce();
+        expect(mockConsoleError).toHaveBeenCalledWith('Test error message');
+        expect(mockExit).toHaveBeenCalledWith(EXIT_CODES.ERROR);
+    });
+    it('should handle errors without message property', async () => {
+        const main = vi.fn().mockRejectedValue('string error');
+        await runCLI(main);
+        expect(mockConsoleError).toHaveBeenCalledWith('string error');
+        expect(mockExit).toHaveBeenCalledWith(EXIT_CODES.ERROR);
+    });
+    it('should handle null/undefined errors', async () => {
+        const main = vi.fn().mockRejectedValue(null);
+        await runCLI(main);
+        expect(mockConsoleError).toHaveBeenCalledWith('Unknown error');
+        expect(mockExit).toHaveBeenCalledWith(EXIT_CODES.ERROR);
+    });
+});
+/**
+ * WU-1071: Verify CLI entry points use import.meta.main pattern
+ *
+ * The old pattern `process.argv[1] === fileURLToPath(import.meta.url)` fails with
+ * pnpm symlinks because process.argv[1] is the symlink path but import.meta.url
+ * resolves to the real path - they never match so main() is never called.
+ *
+ * The fix is to use `import.meta.main` (Node.js 22.16.0+ built-in) which correctly
+ * handles symlinks.
+ */
+describe('WU-1071: CLI entry point patterns', () => {
+    // CLI files that should have the main() entry guard
+    const CLI_FILES_WITH_ENTRY_GUARD = [
+        'gates.ts',
+        'wu-spawn.ts',
+        'wu-create.ts',
+        'wu-claim.ts',
+        'wu-done.ts',
+    ];
+    // Old broken pattern that fails with pnpm symlinks
+    const OLD_BROKEN_PATTERN = /if\s*\(\s*process\.argv\[1\]\s*===\s*fileURLToPath\(import\.meta\.url\)\s*\)/;
+    // New working pattern using import.meta.main
+    const NEW_WORKING_PATTERN = /if\s*\(\s*import\.meta\.main\s*\)/;
+    it('should use import.meta.main instead of process.argv[1] comparison', () => {
+        const srcDir = path.resolve(__dirname, '..');
+        for (const file of CLI_FILES_WITH_ENTRY_GUARD) {
+            const filePath = path.join(srcDir, file);
+            const content = readFileSync(filePath, 'utf-8');
+            // Should NOT have old broken pattern
+            expect(OLD_BROKEN_PATTERN.test(content), `${file} should not use the old broken pattern (process.argv[1] === fileURLToPath)`).toBe(false);
+            // Should have new working pattern
+            expect(NEW_WORKING_PATTERN.test(content), `${file} should use import.meta.main pattern`).toBe(true);
+        }
+    });
+    it('should not have unused fileURLToPath imports in CLI files with entry guards', () => {
+        const srcDir = path.resolve(__dirname, '..');
+        for (const file of CLI_FILES_WITH_ENTRY_GUARD) {
+            const filePath = path.join(srcDir, file);
+            const content = readFileSync(filePath, 'utf-8');
+            // If the file imports fileURLToPath, it should actually use it somewhere
+            // (not just for the now-removed entry guard pattern)
+            const hasFileURLToPathImport = /import\s*{[^}]*fileURLToPath[^}]*}\s*from\s*['"]node:url['"]/.test(content);
+            const usesFileURLToPath = /fileURLToPath\(/.test(content);
+            if (hasFileURLToPathImport && !usesFileURLToPath) {
+                expect.fail(`${file} imports fileURLToPath but does not use it - remove unused import`);
+            }
+        }
+    });
+    it('cli-entry-point.ts JSDoc should document import.meta.main pattern', () => {
+        const srcDir = path.resolve(__dirname, '..');
+        const cliEntryPointPath = path.join(srcDir, 'cli-entry-point.ts');
+        const content = readFileSync(cliEntryPointPath, 'utf-8');
+        // JSDoc example should show import.meta.main pattern, not the old one
+        expect(content.includes('import.meta.main'), 'cli-entry-point.ts JSDoc should mention import.meta.main').toBe(true);
+    });
+});

package/dist/__tests__/cli-subprocess.test.js

@@ -0,0 +1,64 @@
+/**
+ * Integration tests for CLI subprocess execution
+ *
+ * Tests that CLI commands properly:
+ * - Exit with non-zero code on errors
+ * - Output error messages to stderr
+ * - Don't silently fail
+ *
+ * These tests run CLI commands as subprocesses to verify
+ * the entry point error handling works end-to-end.
+ */
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+const CLI_DIR = resolve(__dirname, '../../dist');
+/**
+ * Helper to run a CLI command as subprocess
+ */
+function runCLI(command, args = []) {
+    const result = spawnSync('node', [resolve(CLI_DIR, `${command}.js`), ...args], {
+        encoding: 'utf-8',
+        timeout: 10000,
+    });
+    return {
+        code: result.status ?? -1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+describe('CLI subprocess error handling', () => {
+    describe('wu-claim', () => {
+        it('should exit with non-zero code when required options are missing', () => {
+            const result = runCLI('wu-claim', ['--id', 'WU-TEST']);
+            // Should NOT exit 0 (silent failure)
+            expect(result.code).not.toBe(0);
+            // Should have some error output
+            expect(result.stderr.length + result.stdout.length).toBeGreaterThan(0);
+        });
+        it('should output help when --help is passed', () => {
+            const result = runCLI('wu-claim', ['--help']);
+            // Help should work
+            expect(result.code).toBe(0);
+            expect(result.stdout).toContain('Usage');
+        });
+    });
+    describe('wu-done', () => {
+        it('should exit with non-zero code for non-existent WU', () => {
+            const result = runCLI('wu-done', ['--id', 'WU-NONEXISTENT-99999']);
+            // Should NOT exit 0 (silent failure)
+            expect(result.code).not.toBe(0);
+            // Should have some error output
+            expect(result.stderr.length + result.stdout.length).toBeGreaterThan(0);
+        });
+    });
+    describe('wu-create', () => {
+        it('should exit with non-zero code when validation fails', () => {
+            const result = runCLI('wu-create', ['--id', 'WU-TEST', '--lane', 'Invalid Lane']);
+            // Should NOT exit 0 (silent failure)
+            expect(result.code).not.toBe(0);
+            // Should have some error output
+            expect(result.stderr.length + result.stdout.length).toBeGreaterThan(0);
+        });
+    });
+});

package/dist/__tests__/wu-done-staging-whitelist.test.js

@@ -0,0 +1,35 @@
+/**
+ * @file Tests for wu-done staging whitelist patterns
+ * @see WU-1072: Fix staging whitelist for auto-generated docs
+ */
+import { describe, it, expect } from 'vitest';
+/**
+ * Pattern matching logic extracted from validateStagedFiles in wu-done.ts
+ * This tests the MDX whitelist pattern added in WU-1072
+ */
+function isWhitelistedAutoGeneratedDoc(file) {
+    return file.startsWith('apps/docs/') && file.endsWith('.mdx');
+}
+describe('wu-done staging whitelist', () => {
+    describe('auto-generated docs pattern (WU-1072)', () => {
+        it('should whitelist MDX files in apps/docs/', () => {
+            expect(isWhitelistedAutoGeneratedDoc('apps/docs/api/wu-create.mdx')).toBe(true);
+            expect(isWhitelistedAutoGeneratedDoc('apps/docs/commands/gates.mdx')).toBe(true);
+            expect(isWhitelistedAutoGeneratedDoc('apps/docs/nested/deep/file.mdx')).toBe(true);
+        });
+        it('should not whitelist MDX files outside apps/docs/', () => {
+            expect(isWhitelistedAutoGeneratedDoc('docs/something.mdx')).toBe(false);
+            expect(isWhitelistedAutoGeneratedDoc('packages/cli/README.mdx')).toBe(false);
+            expect(isWhitelistedAutoGeneratedDoc('src/docs/file.mdx')).toBe(false);
+        });
+        it('should not whitelist non-MDX files in apps/docs/', () => {
+            expect(isWhitelistedAutoGeneratedDoc('apps/docs/config.ts')).toBe(false);
+            expect(isWhitelistedAutoGeneratedDoc('apps/docs/package.json')).toBe(false);
+            expect(isWhitelistedAutoGeneratedDoc('apps/docs/styles.css')).toBe(false);
+        });
+        it('should not whitelist files with mdx in the path but not as extension', () => {
+            expect(isWhitelistedAutoGeneratedDoc('apps/docs/mdx-utils/helper.ts')).toBe(false);
+            expect(isWhitelistedAutoGeneratedDoc('apps/docs/mdx')).toBe(false);
+        });
+    });
+});

package/dist/cli-entry-point.js

@@ -0,0 +1,51 @@
+/**
+ * Shared CLI entry point wrapper
+ *
+ * Provides consistent error handling for all CLI commands.
+ * Catches async errors, logs them, and exits with proper code.
+ *
+ * WU-1071: Use import.meta.main (Node.js 22.16.0+) instead of the old
+ * process.argv[1] === fileURLToPath(import.meta.url) pattern. The old
+ * pattern fails with pnpm symlinks because process.argv[1] is the symlink
+ * path but import.meta.url resolves to the real path - they never match
+ * so main() is never called.
+ *
+ * @example
+ * ```typescript
+ * // At the bottom of each CLI file:
+ * import { runCLI } from './cli-entry-point.js';
+ *
+ * if (import.meta.main) {
+ *   runCLI(main);
+ * }
+ * ```
+ */
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+/**
+ * Wraps an async main function with proper error handling.
+ *
+ * @param main - The async main function to execute
+ * @returns Promise that resolves when main completes (or after error handling)
+ */
+export async function runCLI(main) {
+    try {
+        await main();
+    }
+    catch (err) {
+        const message = getErrorMessage(err);
+        console.error(message);
+        process.exit(EXIT_CODES.ERROR);
+    }
+}
+/**
+ * Extracts error message from unknown error type.
+ */
+function getErrorMessage(err) {
+    if (err === null || err === undefined) {
+        return 'Unknown error';
+    }
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}

package/dist/gates.js

@@ -42,7 +42,6 @@ import { execSync, spawnSync } from 'node:child_process';
 import { closeSync, mkdirSync, openSync, readSync, statSync, writeSync } from 'node:fs';
 import { access } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { emitGateEvent, getCurrentWU, getCurrentLane } from '@lumenflow/core/dist/telemetry.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { getChangedLintableFiles, convertToPackageRelativePaths, } from '@lumenflow/core/dist/incremental-lint.js';
@@ -753,7 +752,10 @@ async function main() {
     }
     process.exit(EXIT_CODES.SUCCESS);
 }
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+// WU-1071: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+if (import.meta.main) {
     main().catch((error) => {
         console.error('Gates failed:', error);
         process.exit(EXIT_CODES.ERROR);

package/dist/init.js

@@ -8,6 +8,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
 import { getDefaultConfig } from '@lumenflow/core';
+// WU-1067: Import GATE_PRESETS for --preset support
+import { GATE_PRESETS } from '@lumenflow/core/dist/gates-config.js';
 const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
 const FRAMEWORK_HINT_FILE = '.lumenflow.framework.yaml';
 const LUMENFLOW_DIR = '.lumenflow';
@@ -16,11 +18,20 @@ const CLAUDE_DIR = '.claude';
 const CLAUDE_AGENTS_DIR = path.join(CLAUDE_DIR, 'agents');
 /**
  * Generate YAML configuration with header comment
+ * WU-1067: Supports --preset option for config-driven gates
  */
-function generateLumenflowConfigYaml() {
+function generateLumenflowConfigYaml(gatePreset) {
     const header = `# LumenFlow Configuration\n# Generated by: lumenflow init\n# Customize paths based on your project structure\n\n`;
     const config = getDefaultConfig();
     config.directories.agentsDir = LUMENFLOW_AGENTS_DIR;
+    // WU-1067: Add gates.execution section with preset if specified
+    if (gatePreset && GATE_PRESETS[gatePreset]) {
+        const presetConfig = GATE_PRESETS[gatePreset];
+        config.gates.execution = {
+            preset: gatePreset,
+            ...presetConfig,
+        };
+    }
     return header + yaml.stringify(config);
 }
 /**
@@ -144,6 +155,28 @@ function parseFrameworkArg(args) {
     }
     return undefined;
 }
+/**
+ * WU-1067: Parse --preset flag from arguments for config-driven gates
+ */
+function parsePresetArg(args) {
+    const presetArg = args.find((arg) => arg.startsWith('--preset='));
+    if (presetArg) {
+        const [, value] = presetArg.split('=', 2);
+        const preset = value?.trim().toLowerCase();
+        if (preset && ['node', 'python', 'go', 'rust', 'dotnet'].includes(preset)) {
+            return preset;
+        }
+        return undefined;
+    }
+    const presetIndex = args.findIndex((arg) => arg === '--preset');
+    if (presetIndex !== -1 && args[presetIndex + 1]) {
+        const preset = args[presetIndex + 1].toLowerCase();
+        if (['node', 'python', 'go', 'rust', 'dotnet'].includes(preset)) {
+            return preset;
+        }
+    }
+    return undefined;
+}
 function shouldUseVendor(vendor, defaultClient) {
     if (vendor) {
         return vendor;
@@ -168,8 +201,8 @@ export async function scaffoldProject(targetDir, options) {
         DATE: getCurrentDate(),
         PROJECT_ROOT: targetDir,
     };
-    // Create .lumenflow.config.yaml
-    await createFile(path.join(targetDir, CONFIG_FILE_NAME), generateLumenflowConfigYaml(), options.force, result, targetDir);
+    // Create .lumenflow.config.yaml (WU-1067: includes gate preset if specified)
+    await createFile(path.join(targetDir, CONFIG_FILE_NAME), generateLumenflowConfigYaml(options.gatePreset), options.force, result, targetDir);
     // Create LUMENFLOW.md (main entry point)
     await createFile(path.join(targetDir, 'LUMENFLOW.md'), processTemplate(LUMENFLOW_MD_TEMPLATE, tokenDefaults), options.force, result, targetDir);
     // Create .lumenflow/constraints.md
@@ -271,16 +304,19 @@ export async function main() {
     const full = args.includes('--full');
     const vendor = parseVendorArg(args);
     const framework = parseFrameworkArg(args);
+    const gatePreset = parsePresetArg(args); // WU-1067
     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)'}`);
     const result = await scaffoldProject(targetDir, {
         force,
         full,
         vendor,
         framework,
+        gatePreset,
     });
     if (result.created.length > 0) {
         console.log('\nCreated:');

package/dist/initiative-add-wu.js

@@ -229,6 +229,7 @@ async function main() {
 }
 // Guard main() for testability
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/initiative-create.js

@@ -163,6 +163,7 @@ async function main() {
 }
 // Guard main() for testability
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/initiative-list.js

@@ -96,6 +96,7 @@ async function main() {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/initiative-status.js

@@ -216,6 +216,7 @@ async function main() {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/wu-claim.js

@@ -1297,7 +1297,10 @@ async function main() {
     }
 }
 // Guard main() for testability (WU-1366)
-import { fileURLToPath } from 'node:url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+// WU-1071: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
 }

package/dist/wu-cleanup.js

@@ -5,7 +5,7 @@
  * Cleans up worktree and branch after PR merge (PR-based completion workflow).
  *
  * Sequence:
- * 1) Verify PR is merged (via gh API or git merge-base fallback)
+ * 1) Verify PR is merged (via gh API; no merge-base fallback)
  * 2) Remove worktree (if exists)
  * 3) Delete lane branch (local + remote)
  *
@@ -16,7 +16,7 @@
  *   pnpm wu:cleanup --artifacts
  */
 import { execSync } from 'node:child_process';
-import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { createGitForPath, getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
@@ -25,16 +25,11 @@ import { cleanupWorktreeBuildArtifacts } from '@lumenflow/core/dist/rebase-artif
 import { detectCurrentWorktree } from '@lumenflow/core/dist/wu-done-validators.js';
 import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { readWU } from '@lumenflow/core/dist/wu-yaml.js';
-import { BRANCHES, EXIT_CODES, FILE_SYSTEM, LOG_PREFIX, REMOTES, GIT_REFS, } from '@lumenflow/core/dist/wu-constants.js';
+import { isGhCliAvailable } from '@lumenflow/core/dist/wu-done-pr.js';
+import { BOX, CLEANUP_GUARD, EXIT_CODES, FILE_SYSTEM, LOG_PREFIX, REMOTES, STRING_LITERALS, WU_STATUS, } from '@lumenflow/core/dist/wu-constants.js';
 // WU-2278: Import ownership validation for cross-agent protection
 import { validateWorktreeOwnership } from '@lumenflow/core/dist/worktree-ownership.js';
 /* eslint-disable security/detect-non-literal-fs-filename */
-// Box drawing characters for consistent output
-const BOX = {
-    TOP: '╔═══════════════════════════════════════════════════════════════════╗',
-    MID: '╠═══════════════════════════════════════════════════════════════════╣',
-    BOT: '╚═══════════════════════════════════════════════════════════════════╝',
-};
 const CLEANUP_OPTIONS = {
     artifacts: {
         name: 'artifacts',
@@ -42,15 +37,36 @@ const CLEANUP_OPTIONS = {
         description: 'Remove build artifacts (dist, tsbuildinfo) in current worktree',
     },
 };
+export const CLEANUP_GUARD_REASONS = CLEANUP_GUARD.REASONS;
+export function evaluateCleanupGuards({ hasUncommittedChanges, hasUnpushedCommits, hasStamp, yamlStatus, ghAvailable, prMerged, }) {
+    if (hasUncommittedChanges) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.UNCOMMITTED_CHANGES };
+    }
+    if (hasUnpushedCommits) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.UNPUSHED_COMMITS };
+    }
+    if (yamlStatus !== WU_STATUS.DONE) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.STATUS_NOT_DONE };
+    }
+    if (!hasStamp) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.MISSING_STAMP };
+    }
+    if (ghAvailable && prMerged !== true) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.PR_NOT_MERGED };
+    }
+    return { allowed: true, reason: null };
+}
 // Help text is now auto-generated by commander via createWUParser
 async function verifyPRMerged(laneBranch) {
-    // Try gh API first (most reliable)
+    if (!isGhCliAvailable()) {
+        return { merged: null, method: 'gh_unavailable' };
+    }
     let ghResult;
     try {
         ghResult = execSync(`gh api repos/:owner/:repo/pulls -q '.[] | select(.head.ref == "${laneBranch}") | .merged'`, { encoding: FILE_SYSTEM.UTF8 }).trim();
     }
     catch {
-        ghResult = '';
+        ghResult = STRING_LITERALS.EMPTY;
     }
     if (ghResult === 'true') {
         return { merged: true, method: 'gh_api' };
@@ -58,37 +74,7 @@ async function verifyPRMerged(laneBranch) {
     if (ghResult === 'false') {
         return { merged: false, method: 'gh_api' };
     }
-    // Fallback: git merge-base --is-ancestor
-    // Always fetch origin/main first for accurate merge-base check
-    await getGitForCwd().fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
-    const localBranchExists = await getGitForCwd().branchExists(laneBranch);
-    if (!localBranchExists) {
-        // Branch doesn't exist locally - check if it exists remotely
-        const remoteBranchExists = await getGitForCwd().raw([
-            'ls-remote',
-            '--heads',
-            REMOTES.ORIGIN,
-            laneBranch,
-        ]);
-        if (!remoteBranchExists) {
-            // Branch is gone both locally and remotely - assume merged
-            return { merged: true, method: 'branch_deleted' };
-        }
-        // Branch exists remotely but not locally - need to fetch
-        await getGitForCwd().fetch(REMOTES.ORIGIN, laneBranch);
-    }
-    let isAncestor;
-    try {
-        await getGitForCwd().raw(['merge-base', '--is-ancestor', laneBranch, GIT_REFS.ORIGIN_MAIN]);
-        isAncestor = true;
-    }
-    catch {
-        isAncestor = false;
-    }
-    if (isAncestor) {
-        return { merged: true, method: 'git_merge_base' };
-    }
-    return { merged: false, method: 'git_merge_base' };
+    return { merged: null, method: 'gh_api' };
 }
 async function removeWorktree(worktreePath) {
     if (!existsSync(worktreePath)) {
@@ -154,6 +140,31 @@ async function cleanupArtifactsInWorktree() {
     }
     console.log(`${LOG_PREFIX.CLEANUP} ✓ Build artifact cleanup complete`);
 }
+async function hasUncommittedChanges(worktreePath) {
+    if (!existsSync(worktreePath)) {
+        return false;
+    }
+    const git = createGitForPath(worktreePath);
+    const status = await git.getStatus();
+    return status.length > 0;
+}
+async function hasUnpushedCommits(worktreePath) {
+    if (!existsSync(worktreePath)) {
+        return false;
+    }
+    const git = createGitForPath(worktreePath);
+    try {
+        const unpushed = await git.getUnpushedCommits();
+        return unpushed.length > 0;
+    }
+    catch {
+        return true;
+    }
+}
+function hasStampFile(wuId) {
+    const stampPath = path.join(process.cwd(), WU_PATHS.STAMP(wuId));
+    return existsSync(stampPath);
+}
 async function main() {
     const args = createWUParser({
         name: 'wu-cleanup',
@@ -181,6 +192,7 @@ async function main() {
     const idK = args.id.toLowerCase();
     const laneBranch = `lane/${laneK}/${idK}`;
     const worktreePath = path.join('worktrees', `${laneK}-${idK}`);
+    const absoluteWorktreePath = path.resolve(worktreePath);
     console.log(`[wu-cleanup] Cleaning up ${args.id} (${wu.title})`);
     console.log(`[wu-cleanup] Lane: ${wu.lane}`);
     console.log(`[wu-cleanup] Branch: ${laneBranch}`);
@@ -200,25 +212,38 @@ async function main() {
         console.error(BOX.BOT);
         process.exit(EXIT_CODES.ERROR);
     }
-    // 1. Verify PR is merged
-    console.log('[wu-cleanup] Verifying PR merge status...');
-    const { merged, method } = await verifyPRMerged(laneBranch);
-    if (!merged) {
+    const cleanupCheck = {
+        hasUncommittedChanges: await hasUncommittedChanges(absoluteWorktreePath),
+        hasUnpushedCommits: await hasUnpushedCommits(absoluteWorktreePath),
+        hasStamp: hasStampFile(id),
+        yamlStatus: wu.status,
+        ghAvailable: isGhCliAvailable(),
+        prMerged: null,
+    };
+    if (cleanupCheck.ghAvailable) {
+        console.log(`${LOG_PREFIX.CLEANUP} ${CLEANUP_GUARD.PR_CHECK.START}`);
+        const { merged, method } = await verifyPRMerged(laneBranch);
+        cleanupCheck.prMerged = merged;
+        console.log(`${LOG_PREFIX.CLEANUP} ${CLEANUP_GUARD.PR_CHECK.RESULT} ${method}`);
+        console.log();
+    }
+    const guardResult = evaluateCleanupGuards(cleanupCheck);
+    if (!guardResult.allowed) {
         console.error();
         console.error(BOX.TOP);
-        console.error('║  PR NOT MERGED');
+        console.error(`${BOX.SIDE}  ${CLEANUP_GUARD.TITLES.BLOCKED}`);
         console.error(BOX.MID);
-        console.error(`║  Branch ${laneBranch} has not been merged to main yet.`);
-        console.error('║');
-        console.error('║  Next steps:');
-        console.error('║  1. Review the PR in GitHub UI');
-        console.error('║  2. Merge the PR');
-        console.error(`║  3. Re-run: pnpm wu:cleanup --id ${args.id}`);
+        console.error(`${BOX.SIDE}  ${CLEANUP_GUARD.MESSAGES[guardResult.reason]}`);
+        console.error(`${BOX.SIDE}`);
+        console.error(`${BOX.SIDE}  ${CLEANUP_GUARD.TITLES.NEXT_STEPS}`);
+        const steps = CLEANUP_GUARD.NEXT_STEPS[guardResult.reason] || CLEANUP_GUARD.NEXT_STEPS.DEFAULT;
+        for (const step of steps) {
+            const line = step.appendId ? `${step.text} ${args.id}` : step.text;
+            console.error(`${BOX.SIDE}  ${line}`);
+        }
         console.error(BOX.BOT);
         process.exit(EXIT_CODES.ERROR);
     }
-    console.log(`[wu-cleanup] ✓ PR merged (verified via ${method})`);
-    console.log();
     // 2. Remove worktree
     await removeWorktree(worktreePath);
     console.log();
@@ -235,6 +260,7 @@ async function main() {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/wu-create.js

@@ -38,10 +38,12 @@ import { validateLaneFormat, extractParent } from '@lumenflow/core/dist/lane-che
 // WU-2330: Import lane inference for sub-lane suggestions
 import { inferSubLane } from '@lumenflow/core/dist/lane-inference.js';
 import { parseBacklogFrontmatter } from '@lumenflow/core/dist/backlog-parser.js';
-import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { createWUParser, WU_CREATE_OPTIONS, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { validateWU } from '@lumenflow/core/dist/wu-schema.js';
-import { COMMIT_FORMATS, FILE_SYSTEM, STRING_LITERALS, READINESS_UI, } from '@lumenflow/core/dist/wu-constants.js';
+import { getPlanPath, getPlanProtocolRef, getPlansDir, } from '@lumenflow/core/dist/lumenflow-home.js';
+import { 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';
 // WU-1439: Use shared micro-worktree helper
@@ -184,6 +186,36 @@ const parseCommaSeparated = (value) => value
         .map((s) => s.trim())
         .filter(Boolean)
     : [];
+function mergeSpecRefs(specRefs, extraRef) {
+    const refs = parseCommaSeparated(specRefs);
+    if (extraRef && !refs.includes(extraRef)) {
+        refs.push(extraRef);
+    }
+    return refs.length > 0 ? refs.join(',') : undefined;
+}
+function createPlanTemplate(wuId, title) {
+    const plansDir = getPlansDir();
+    mkdirSync(plansDir, { recursive: true });
+    const planPath = getPlanPath(wuId);
+    if (existsSync(planPath)) {
+        die(`Plan already exists: ${planPath}\n\n` +
+            `Options:\n` +
+            `  1. Open the existing plan and continue editing\n` +
+            `  2. Delete or rename the existing plan before retrying\n` +
+            `  3. Run wu:create without --plan`);
+    }
+    const today = todayISO();
+    const content = `# ${wuId} Plan — ${title}\n\n` +
+        `Created: ${today}\n\n` +
+        `## Goal\n\n` +
+        `## Scope\n\n` +
+        `## Approach\n\n` +
+        `## Risks\n\n` +
+        `## Open Questions\n`;
+    writeFileSync(planPath, content, { encoding: FILE_SYSTEM.UTF8 });
+    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;
     const code_paths = parseCommaSeparated(codePaths);
@@ -453,6 +485,8 @@ async function main() {
             WU_OPTIONS.exposure,
             WU_OPTIONS.userJourney,
             WU_OPTIONS.uiPairingWus,
+            // WU-1062: External plan options for wu:create
+            WU_CREATE_OPTIONS.plan,
         ],
         required: ['id', 'lane', 'title'],
         allowPositionalId: false,
@@ -477,13 +511,15 @@ async function main() {
     }
     // WU-2330: Warn if a more specific sub-lane matches code_paths or description
     warnIfBetterLaneExists(args.lane, args.codePaths, args.title, args.description);
-    checkWUExists(args.id);
     await ensureOnMain(getGitForCwd());
+    checkWUExists(args.id);
     // WU-1368: Get assigned_to from flag or git config user.email
     const assignedTo = args.assignedTo || (await getDefaultAssignedTo());
     if (!assignedTo) {
         console.warn(`${LOG_PREFIX} ⚠️  No assigned_to set - WU will need manual assignment`);
     }
+    const planSpecRef = args.plan ? getPlanProtocolRef(args.id) : undefined;
+    const mergedSpecRefs = mergeSpecRefs(args.specRefs, planSpecRef);
     const createSpecValidation = validateCreateSpec({
         id: args.id,
         lane: args.lane,
@@ -500,7 +536,7 @@ async function main() {
             exposure: args.exposure,
             userJourney: args.userJourney,
             uiPairingWus: args.uiPairingWus,
-            specRefs: args.specRefs,
+            specRefs: mergedSpecRefs,
             initiative: args.initiative,
             phase: args.phase,
             blockedBy: args.blockedBy,
@@ -516,6 +552,22 @@ async function main() {
         die(`${LOG_PREFIX} ❌ Spec validation failed:\n\n${errorList}`);
     }
     console.log(`${LOG_PREFIX} ✅ Spec validation passed`);
+    const specRefsList = parseCommaSeparated(mergedSpecRefs);
+    const specRefsValidation = validateSpecRefs(specRefsList);
+    if (!specRefsValidation.valid) {
+        const errorList = specRefsValidation.errors
+            .map((error) => `  • ${error}`)
+            .join(STRING_LITERALS.NEWLINE);
+        die(`${LOG_PREFIX} ❌ Spec reference validation failed:\n\n${errorList}`);
+    }
+    if (specRefsValidation.warnings.length > 0) {
+        for (const warning of specRefsValidation.warnings) {
+            console.warn(`${LOG_PREFIX} ⚠️  ${warning}`);
+        }
+    }
+    if (args.plan) {
+        createPlanTemplate(args.id, args.title);
+    }
     // Transaction: micro-worktree isolation (WU-1439)
     try {
         const priority = args.priority || DEFAULT_PRIORITY;
@@ -550,7 +602,7 @@ async function main() {
                         userJourney: args.userJourney,
                         uiPairingWus: args.uiPairingWus,
                         // WU-2320: Spec references
-                        specRefs: args.specRefs,
+                        specRefs: mergedSpecRefs,
                     });
                     // Update backlog.md in micro-worktree
                     const backlogPath = updateBacklogInWorktree(worktreePath, args.id, args.lane, args.title);
@@ -588,7 +640,10 @@ async function main() {
     }
 }
 // Guard main() for testability (WU-1366)
-import { fileURLToPath } from 'node:url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+// WU-1071: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
 }

package/dist/wu-deps.js

@@ -114,6 +114,7 @@ function renderGraphJSON(graph, rootId, depth, direction) {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/wu-done.js

@@ -956,6 +956,9 @@ async function validateStagedFiles(id, isDocsOnly = false) {
         // Whitelist .beacon/stamps/** pattern
         if (file.startsWith('.beacon/stamps/'))
             return false;
+        // WU-1072: Whitelist apps/docs/**/*.mdx for auto-generated docs from turbo docs:generate
+        if (file.startsWith('apps/docs/') && file.endsWith('.mdx'))
+            return false;
         return true;
     });
     if (unexpected.length > 0) {
@@ -2213,7 +2216,10 @@ async function detectChangedDocPaths(worktreePath, baseBranch) {
 }
 // Guard main() execution for testability (WU-1366)
 // When imported as a module for testing, main() should not auto-run
-import { fileURLToPath } from 'node:url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+// WU-1071: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
 }

package/dist/wu-infer-lane.js

@@ -93,7 +93,7 @@ function loadWuYaml(id) {
             `  2. Fix YAML errors manually and retry`);
     }
 }
-function main() {
+async function main() {
     const args = parseArgs(process.argv);
     let codePaths = [];
     let description = '';
@@ -130,6 +130,7 @@ function main() {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/wu-preflight.js

@@ -160,8 +160,9 @@ async function main() {
     process.exit(EXIT_CODES.SUCCESS);
 }
 // Guard main() for testability
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }
 // Export for testing
 export { parseArgs, detectWorktreePath };

package/dist/wu-prune.js

@@ -19,8 +19,8 @@ import { readWUYaml, validateBranchName, extractWUFromBranch, } from '@lumenflow
 import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
-import { detectOrphanWorktrees, removeOrphanDirectory, } from '@lumenflow/core/dist/orphan-detector.js';
-import { BRANCHES, WU_STATUS, CLI_FLAGS, EXIT_CODES, STRING_LITERALS, EMOJI, LOG_PREFIX, } from '@lumenflow/core/dist/wu-constants.js';
+import { detectOrphanWorktrees, detectMissingTrackedWorktrees, removeOrphanDirectory, } from '@lumenflow/core/dist/orphan-detector.js';
+import { BRANCHES, WU_STATUS, CLI_FLAGS, EXIT_CODES, STRING_LITERALS, EMOJI, LOG_PREFIX, WORKTREE_WARNINGS, } from '@lumenflow/core/dist/wu-constants.js';
 function parseArgs(argv) {
     const args = { dryRun: true }; // Default to dry-run for safety
     for (let i = 2; i < argv.length; i++) {
@@ -145,6 +145,14 @@ This tool:
     }
     console.log(`${PREFIX} Worktree Hygiene Check`);
     console.log(`${PREFIX} =====================\n`);
+    const missingTracked = await detectMissingTrackedWorktrees(process.cwd());
+    if (missingTracked.length > 0) {
+        console.warn(`${PREFIX} ${EMOJI.WARNING} ${WORKTREE_WARNINGS.MISSING_TRACKED_HEADER}`);
+        for (const missingPath of missingTracked) {
+            console.warn(`${PREFIX} ${WORKTREE_WARNINGS.MISSING_TRACKED_LINE(missingPath)}`);
+        }
+        console.warn('');
+    }
     if (args.dryRun) {
         console.log(`${PREFIX} ${EMOJI.INFO} DRY-RUN MODE (use --execute to apply changes)\n`);
     }
@@ -254,6 +262,7 @@ This tool:
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/wu-repair.js

@@ -219,8 +219,9 @@ async function main() {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }
 // Export for testing
 export { normaliseWUId, isValidWUId };

package/dist/wu-spawn.js

@@ -731,7 +731,7 @@ function generateLaneGuidance(lane) {
 - Follow prompt versioning guidelines in ai/prompts/README.md`,
         Experience: `## Lane-Specific: Experience
 
-- Follow design system tokens in packages/@patientpath/design-system
+- Follow design system tokens defined in the project
 - Ensure accessibility compliance (WCAG 2.1 AA)`,
         Core: `## Lane-Specific: Core
 
@@ -1239,8 +1239,11 @@ async function main() {
         console.log(`\n${registryMessage}`);
     }
 }
-// Guard main() for testability
-import { fileURLToPath } from 'node:url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+// Guard main() for testability (WU-1366)
+// WU-1071: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
 }

package/dist/wu-unlock-lane.js

@@ -155,4 +155,9 @@ async function main() {
     console.log(`${PREFIX} Previous owner: ${result.previousLock?.wuId || 'unknown'}`);
     console.log(`${PREFIX} Reason: ${result.reason}`);
 }
-main();
+// Guard main() for testability (WU-1064)
+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-validate.js

@@ -188,6 +188,7 @@ async function main() {
 }
 // Guard main() for testability
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -75,7 +75,19 @@
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc",
+    "build:dist": "tsc -p tsconfig.build.json",
+    "pack:dist": "pnpm pack",
+    "clean": "rm -rf dist *.tgz",
+    "test": "vitest run"
+  },
   "dependencies": {
+    "@lumenflow/core": "workspace:*",
+    "@lumenflow/metrics": "workspace:*",
+    "@lumenflow/memory": "workspace:*",
+    "@lumenflow/initiatives": "workspace:*",
+    "@lumenflow/agent": "workspace:*",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.2",
@@ -84,12 +96,7 @@
     "ms": "^2.1.3",
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
-    "yaml": "^2.8.2",
-    "@lumenflow/memory": "1.3.0",
-    "@lumenflow/agent": "1.3.0",
-    "@lumenflow/initiatives": "1.3.0",
-    "@lumenflow/metrics": "1.3.0",
-    "@lumenflow/core": "1.3.0"
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",
@@ -101,12 +108,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsc",
-    "build:dist": "tsc -p tsconfig.build.json",
-    "pack:dist": "pnpm pack",
-    "clean": "rm -rf dist *.tgz",
-    "test": "vitest run"
   }
-}
+}