@lumenflow/cli 2.10.0 → 2.12.0

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__/initiative-add-wu.test.js

@@ -10,7 +10,8 @@ import { describe, it, expect, vi, beforeEach, afterEach, beforeAll } from 'vite
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { stringifyYAML, readWU } from '@lumenflow/core/dist/wu-yaml.js';
+import { readInitiative } from '@lumenflow/initiatives/dist/initiative-yaml.js';
 // Test constants to avoid lint warnings about duplicate strings
 const TEST_WU_ID = 'WU-123';
 const TEST_INIT_ID = 'INIT-001';
@@ -22,6 +23,7 @@ const TEST_INIT_TITLE = 'Test Initiative';
 const TEST_INIT_STATUS = 'open';
 const TEST_DATE = '2026-01-25';
 const MIN_DESCRIPTION_LENGTH = 50;
+const TEST_WU_ID_2 = 'WU-124';
 // Valid WU document template
 const createValidWUDoc = (overrides = {}) => ({
     id: TEST_WU_ID,
@@ -324,6 +326,50 @@ describe('initiative:add-wu WU validation (WU-1330)', () => {
             expect(result.valid).toBe(true);
         });
     });
+    describe('batch linking (WU-1460)', () => {
+        it('should normalize repeatable --wu values with dedupe and order preservation', async () => {
+            const { normalizeWuIds } = await import('../initiative-add-wu.js');
+            expect(normalizeWuIds(TEST_WU_ID)).toEqual([TEST_WU_ID]);
+            expect(normalizeWuIds([TEST_WU_ID, TEST_WU_ID_2, TEST_WU_ID])).toEqual([
+                TEST_WU_ID,
+                TEST_WU_ID_2,
+            ]);
+        });
+        it('should update multiple WUs and initiative in one execute call', async () => {
+            const { buildAddWuMicroWorktreeOptions } = await import('../initiative-add-wu.js');
+            // Setup valid WUs and initiative
+            const wuDir = join(tempDir, WU_REL_PATH);
+            const initDir = join(tempDir, INIT_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            mkdirSync(initDir, { recursive: true });
+            const wuPath1 = join(wuDir, `${TEST_WU_ID}.yaml`);
+            const wuPath2 = join(wuDir, `${TEST_WU_ID_2}.yaml`);
+            const initPath = join(initDir, `${TEST_INIT_ID}.yaml`);
+            writeFileSync(wuPath1, stringifyYAML(createValidWUDoc({ id: TEST_WU_ID })));
+            writeFileSync(wuPath2, stringifyYAML(createValidWUDoc({ id: TEST_WU_ID_2 })));
+            writeFileSync(initPath, stringifyYAML(createValidInitDoc()));
+            process.chdir(tempDir);
+            const options = buildAddWuMicroWorktreeOptions([TEST_WU_ID, TEST_WU_ID_2], TEST_INIT_ID);
+            const result = await options.execute({ worktreePath: tempDir });
+            expect(result.files).toContain(`${WU_REL_PATH}/${TEST_WU_ID}.yaml`);
+            expect(result.files).toContain(`${WU_REL_PATH}/${TEST_WU_ID_2}.yaml`);
+            expect(result.files).toContain(`${INIT_REL_PATH}/${TEST_INIT_ID}.yaml`);
+            const updatedWu1 = readWU(wuPath1, TEST_WU_ID);
+            const updatedWu2 = readWU(wuPath2, TEST_WU_ID_2);
+            const updatedInit = readInitiative(initPath, TEST_INIT_ID);
+            expect(updatedWu1.initiative).toBe(TEST_INIT_ID);
+            expect(updatedWu2.initiative).toBe(TEST_INIT_ID);
+            expect(updatedInit.wus).toContain(TEST_WU_ID);
+            expect(updatedInit.wus).toContain(TEST_WU_ID_2);
+        });
+        it('should validate conflicting links across multiple WUs', async () => {
+            const { validateNoConflictingLinks } = await import('../initiative-add-wu.js');
+            expect(() => validateNoConflictingLinks([
+                { id: TEST_WU_ID, initiative: TEST_INIT_ID },
+                { id: TEST_WU_ID_2, initiative: 'INIT-999' },
+            ], TEST_INIT_ID)).toThrow();
+        });
+    });
     describe('error formatting', () => {
         it('should format errors in human-readable format', async () => {
             const { formatValidationErrors } = await import('../initiative-add-wu.js');
@@ -356,6 +402,24 @@ describe('initiative:add-wu WU validation (WU-1330)', () => {
             const mod = await import('../initiative-add-wu.js');
             expect(typeof mod.formatRetryExhaustionError).toBe('function');
         });
+        it('should export operation-level push retry override (WU-1459)', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(mod.INITIATIVE_ADD_WU_PUSH_RETRY_OVERRIDE).toBeDefined();
+            expect(mod.INITIATIVE_ADD_WU_PUSH_RETRY_OVERRIDE.retries).toBeGreaterThan(3);
+            expect(mod.INITIATIVE_ADD_WU_PUSH_RETRY_OVERRIDE.min_delay_ms).toBeGreaterThan(100);
+        });
+        it('should export helper to build micro-worktree options (WU-1459)', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.buildAddWuMicroWorktreeOptions).toBe('function');
+            const options = mod.buildAddWuMicroWorktreeOptions(TEST_WU_ID, TEST_INIT_ID);
+            expect(options.pushOnly).toBe(true);
+            expect(options.pushRetryOverride).toEqual(mod.INITIATIVE_ADD_WU_PUSH_RETRY_OVERRIDE);
+        });
+        it('should export batch helpers (WU-1460)', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.normalizeWuIds).toBe('function');
+            expect(typeof mod.validateNoConflictingLinks).toBe('function');
+        });
     });
 });
 /**
@@ -416,5 +480,11 @@ describe('initiative:add-wu retry handling (WU-1333)', () => {
             // Should mention concurrent agents as possible cause
             expect(formatted).toMatch(/concurrent|agent|traffic/i);
         });
+        it('should include git.push_retry tuning guidance', async () => {
+            const { formatRetryExhaustionError } = await import('../initiative-add-wu.js');
+            const retryError = new Error('Push failed after 3 attempts.');
+            const formatted = formatRetryExhaustionError(retryError, TEST_WU_ID, TEST_INIT_ID);
+            expect(formatted).toContain('git.push_retry.retries');
+        });
     });
 });

package/dist/__tests__/no-beacon-references-docs.test.js

@@ -0,0 +1,30 @@
+/**
+ * @file no-beacon-references-docs.test.ts
+ * Guardrail test: public + onboarding docs must not reference legacy `.beacon` paths (WU-1450).
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function repoRootFromThisFile() {
+    // packages/@lumenflow/cli/src/__tests__/no-beacon-references-docs.test.ts -> repo root
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(thisDir, '..', '..', '..', '..', '..');
+}
+describe('no legacy .beacon references in docs (WU-1450)', () => {
+    it('should not contain .beacon references in onboarding/public docs', () => {
+        const repoRoot = repoRootFromThisFile();
+        const files = [
+            'docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-safety-card.md',
+            'docs/04-operations/_frameworks/lumenflow/agent/onboarding/lumenflow-force-usage.md',
+            'apps/docs/src/content/docs/getting-started/upgrade.mdx',
+            'apps/docs/src/content/docs/reference/changelog.mdx',
+            'apps/docs/src/content/docs/reference/compatibility.mdx',
+        ];
+        for (const relPath of files) {
+            const absPath = path.join(repoRoot, relPath);
+            const content = readFileSync(absPath, 'utf-8');
+            expect(content, `${relPath} should not reference .beacon`).not.toContain('.beacon');
+        }
+    });
+});

package/dist/__tests__/no-beacon-references.test.js

@@ -0,0 +1,39 @@
+/**
+ * @file no-beacon-references.test.ts
+ * Guardrail test: `.beacon` is legacy and must not be referenced in docs/templates/scripts (WU-1447).
+ *
+ * This keeps onboarding friction-free by ensuring `.lumenflow/` is the single canonical namespace.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function repoRootFromThisFile() {
+    // packages/@lumenflow/cli/src/__tests__/no-beacon-references.test.ts -> repo root (../../../../../)
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(thisDir, '..', '..', '..', '..', '..');
+}
+describe('no legacy .beacon references (WU-1447)', () => {
+    it('should not contain .beacon references in tracked onboarding docs/templates/scripts', () => {
+        const repoRoot = repoRootFromThisFile();
+        const files = [
+            'scripts/safe-git',
+            'scripts/hooks/check-lockfile.sh',
+            'scripts/hooks/scan-secrets.sh',
+            'scripts/hooks/validate-paths.sh',
+            'scripts/hooks/validate-worktree-discipline.sh',
+            'LUMENFLOW.md',
+            'packages/@lumenflow/cli/templates/core/LUMENFLOW.md.template',
+            'packages/@lumenflow/cli/templates/core/ai/onboarding/agent-safety-card.md.template',
+            'packages/@lumenflow/cli/templates/core/ai/onboarding/lumenflow-force-usage.md.template',
+            'apps/docs/src/content/docs/guides/agent-onboarding.mdx',
+            'apps/docs/src/content/docs/guides/ai-agents.mdx',
+            'packages/@lumenflow/agent/README.md',
+        ];
+        for (const relPath of files) {
+            const absPath = path.join(repoRoot, relPath);
+            const content = readFileSync(absPath, 'utf-8');
+            expect(content, `${relPath} should not reference .beacon`).not.toContain('.beacon');
+        }
+    });
+});

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,121 @@
+/**
+ * @file wu-create.test.ts
+ * Tests for wu:create helpers and warnings (WU-1429)
+ */
+import { describe, it, expect } from 'vitest';
+import { buildWUContent, collectInitiativeWarnings, validateCreateSpec } 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 default notes to non-empty placeholder when not provided', () => {
+        const wu = buildWUContent({
+            ...BASE_WU,
+            opts: {
+                ...BASE_WU.opts,
+                // Intentionally omit notes
+                notes: undefined,
+            },
+        });
+        expect(typeof wu.notes).toBe('string');
+        expect(wu.notes.trim().length).toBeGreaterThan(0);
+        expect(wu.notes).toContain('(auto)');
+    });
+    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 allow creating a plan-first WU without explicit test flags when code_paths are non-code', () => {
+        const validation = validateCreateSpec({
+            id: 'WU-2000',
+            lane: 'Framework: CLI',
+            title: 'Plan-only spec creation',
+            priority: 'P2',
+            type: 'feature',
+            opts: {
+                description: 'Context: test context.\nProblem: test problem.\nSolution: test solution that exceeds minimum.',
+                acceptance: ['Acceptance criterion'],
+                exposure: 'backend-only',
+                // Non-code file path: manual-only tests are acceptable.
+                codePaths: ['docs/README.md'],
+                // No testPathsManual/unit/e2e provided - should auto-default manual stub.
+                specRefs: ['lumenflow://plans/WU-2000-plan.md'],
+                strict: false,
+            },
+        });
+        expect(validation.valid).toBe(true);
+        const wu = buildWUContent({
+            id: 'WU-2000',
+            lane: 'Framework: CLI',
+            title: 'Plan-only spec creation',
+            priority: 'P2',
+            type: 'feature',
+            created: '2026-02-05',
+            opts: {
+                description: 'Context: test context.\nProblem: test problem.\nSolution: test solution that exceeds minimum.',
+                acceptance: ['Acceptance criterion'],
+                exposure: 'backend-only',
+                codePaths: ['docs/README.md'],
+                specRefs: ['lumenflow://plans/WU-2000-plan.md'],
+            },
+        });
+        expect(wu.tests?.manual?.length).toBeGreaterThan(0);
+    });
+    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/__tests__/wu-done-docs-only-policy.test.js

@@ -0,0 +1,20 @@
+/**
+ * @file wu-done-docs-only-policy.test.ts
+ * Guardrail test: docs-only eligibility checks must not use raw type/exposure string literals (WU-1446).
+ *
+ * This keeps CLI policy logic DRY and aligned with core constants/helpers.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+describe('wu:done docs-only policy (WU-1446)', () => {
+    it('should not use raw documentation string comparisons for type/exposure checks', () => {
+        const thisDir = path.dirname(fileURLToPath(import.meta.url));
+        const filePath = path.join(thisDir, '..', 'wu-done.ts');
+        const content = readFileSync(filePath, 'utf-8');
+        // These comparisons should use core constants/helpers instead.
+        expect(content).not.toContain("exposure === 'documentation'");
+        expect(content).not.toContain("type === 'documentation'");
+    });
+});

package/dist/__tests__/wu-prep-default-exec.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('node:child_process', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, spawnSync: vi.fn() };
+});
+vi.mock('node:fs', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, existsSync: vi.fn() };
+});
+describe('wu-prep default exec helpers (WU-1441)', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.resetAllMocks();
+    });
+    it('uses node + dist wu-validate for JSON comparison when available', async () => {
+        const { spawnSync } = await import('node:child_process');
+        const { existsSync } = await import('node:fs');
+        // Pretend dist sibling exists so defaultExec picks node+dist path (not pnpm on main).
+        vi.mocked(existsSync).mockReturnValue(true);
+        // Both worktree and main should report WU-1 invalid.
+        vi.mocked(spawnSync).mockReturnValue({
+            status: 1,
+            stdout: JSON.stringify({ invalid: [{ wuId: 'WU-1' }] }),
+            stderr: '',
+        });
+        const { checkPreExistingFailures } = await import('../wu-prep.js');
+        const result = await checkPreExistingFailures({ mainCheckout: '/repo' });
+        expect(result.error).toBeUndefined();
+        expect(result.hasPreExisting).toBe(true);
+        expect(result.hasNewFailures).toBe(false);
+        // Default exec should run node directly, not "pnpm wu:validate" from the main checkout.
+        expect(vi.mocked(spawnSync).mock.calls.length).toBeGreaterThan(0);
+        expect(vi.mocked(spawnSync).mock.calls[0]?.[0]).toBe('node');
+    });
+});