@lumenflow/cli 2.4.0 → 2.5.0

package/dist/__tests__/init-scripts.test.js

@@ -0,0 +1,96 @@
+/**
+ * @file init-scripts.test.ts
+ * Test: Generated package.json scripts use correct format (wu-create, wu-claim, wu-done, gates)
+ *
+ * WU-1307: Fix lumenflow-init scaffolding
+ *
+ * The init command should inject standalone binary scripts that work
+ * in consumer projects without requiring the full @lumenflow/cli path.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { scaffoldProject } from '../init.js';
+/** Package.json file name - extracted to avoid duplicate string lint errors */
+const PACKAGE_JSON_FILE_NAME = 'package.json';
+describe('init scripts generation (WU-1307)', () => {
+    let tempDir;
+    beforeEach(() => {
+        // Create a temporary directory for each test
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-init-scripts-'));
+    });
+    afterEach(() => {
+        // Clean up temporary directory
+        if (tempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    /** Helper to read and parse package.json from temp directory */
+    function readPackageJson() {
+        const packageJsonPath = path.join(tempDir, PACKAGE_JSON_FILE_NAME);
+        return JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    }
+    it('should generate package.json scripts using standalone binaries', async () => {
+        // Arrange
+        const packageJsonPath = path.join(tempDir, PACKAGE_JSON_FILE_NAME);
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        expect(fs.existsSync(packageJsonPath)).toBe(true);
+        const packageJson = readPackageJson();
+        expect(packageJson.scripts).toBeDefined();
+        // Scripts should use standalone binary format (wu-create, wu-claim, etc.)
+        // NOT 'pnpm exec lumenflow' format
+        expect(packageJson.scripts?.['wu:claim']).toBe('wu-claim');
+        expect(packageJson.scripts?.['wu:done']).toBe('wu-done');
+        expect(packageJson.scripts?.['wu:create']).toBe('wu-create');
+        expect(packageJson.scripts?.gates).toBe('gates');
+    });
+    it('should NOT use pnpm exec lumenflow format', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        const packageJson = readPackageJson();
+        // Ensure scripts do NOT use the old 'pnpm exec lumenflow' format
+        const scriptValues = Object.values(packageJson.scripts ?? {});
+        const hasOldFormat = scriptValues.some((script) => script.includes('pnpm exec lumenflow'));
+        expect(hasOldFormat).toBe(false);
+    });
+    it('should include all essential WU lifecycle scripts', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        const packageJson = readPackageJson();
+        // Essential scripts that must be present
+        const essentialScripts = ['wu:claim', 'wu:done', 'wu:create', 'wu:status', 'gates'];
+        for (const scriptName of essentialScripts) {
+            expect(packageJson.scripts?.[scriptName]).toBeDefined();
+        }
+    });
+    it('should preserve existing scripts when updating package.json', async () => {
+        // Arrange
+        const packageJsonPath = path.join(tempDir, PACKAGE_JSON_FILE_NAME);
+        const existingPackageJson = {
+            name: 'test-project',
+            version: '1.0.0',
+            scripts: {
+                test: 'vitest',
+                build: 'tsc',
+                custom: 'echo hello',
+            },
+        };
+        fs.writeFileSync(packageJsonPath, JSON.stringify(existingPackageJson, null, 2));
+        // Act
+        await scaffoldProject(tempDir, { force: false, full: true });
+        // Assert
+        const packageJson = readPackageJson();
+        // Existing scripts should be preserved
+        expect(packageJson.scripts?.test).toBe('vitest');
+        expect(packageJson.scripts?.build).toBe('tsc');
+        expect(packageJson.scripts?.custom).toBe('echo hello');
+        // LumenFlow scripts should be added
+        expect(packageJson.scripts?.['wu:claim']).toBeDefined();
+        expect(packageJson.scripts?.gates).toBeDefined();
+    });
+});

package/dist/__tests__/init-template-portability.test.js

@@ -0,0 +1,97 @@
+/**
+ * @file init-template-portability.test.ts
+ * Tests for template portability - no absolute paths (WU-1309)
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { scaffoldProject } from '../init.js';
+// Constants to avoid duplicate strings (sonarjs/no-duplicate-string)
+const ARC42_DOCS_STRUCTURE = 'arc42';
+const PROJECT_ROOT_PLACEHOLDER = '<project-root>';
+describe('template portability', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-portability-test-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    describe('no absolute paths in templates', () => {
+        it('should use <project-root> placeholder instead of absolute paths', async () => {
+            const options = {
+                force: false,
+                full: true,
+                client: 'claude',
+            };
+            await scaffoldProject(tempDir, options);
+            // Check LUMENFLOW.md for absolute paths
+            const lumenflowContent = fs.readFileSync(path.join(tempDir, 'LUMENFLOW.md'), 'utf-8');
+            expect(lumenflowContent).not.toMatch(/\/home\//);
+            expect(lumenflowContent).not.toMatch(/\/Users\//);
+            expect(lumenflowContent).not.toMatch(/C:\\/);
+            // Should contain <project-root> placeholder for portable references
+            expect(lumenflowContent).toContain(PROJECT_ROOT_PLACEHOLDER);
+        });
+        it('should not contain hardcoded user paths in AGENTS.md', async () => {
+            const options = {
+                force: false,
+                full: true,
+            };
+            await scaffoldProject(tempDir, options);
+            const agentsContent = fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+            expect(agentsContent).not.toMatch(/\/home\/[a-zA-Z0-9_-]+\//);
+            expect(agentsContent).not.toMatch(/\/Users\/[a-zA-Z0-9_-]+\//);
+            expect(agentsContent).not.toMatch(/C:\\Users\\[a-zA-Z0-9_-]+\\/);
+        });
+        it('should not contain hardcoded paths in quick-ref-commands.md', async () => {
+            const options = {
+                force: false,
+                full: true,
+                docsStructure: ARC42_DOCS_STRUCTURE,
+            };
+            await scaffoldProject(tempDir, options);
+            // Find the quick-ref-commands.md based on docs structure (arc42)
+            const quickRefPath = path.join(tempDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding', 'quick-ref-commands.md');
+            if (fs.existsSync(quickRefPath)) {
+                const quickRefContent = fs.readFileSync(quickRefPath, 'utf-8');
+                expect(quickRefContent).not.toMatch(/\/home\/[a-zA-Z0-9_-]+\//);
+                expect(quickRefContent).not.toMatch(/\/Users\/[a-zA-Z0-9_-]+\//);
+                expect(quickRefContent).toContain(PROJECT_ROOT_PLACEHOLDER);
+            }
+        });
+        it('should use relative paths for docs cross-references', async () => {
+            const options = {
+                force: false,
+                full: true,
+                client: 'claude',
+                docsStructure: ARC42_DOCS_STRUCTURE,
+            };
+            await scaffoldProject(tempDir, options);
+            // Starting prompt should have relative paths to other docs
+            const onboardingDir = path.join(tempDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+            const startingPromptPath = path.join(onboardingDir, 'starting-prompt.md');
+            if (fs.existsSync(startingPromptPath)) {
+                const content = fs.readFileSync(startingPromptPath, 'utf-8');
+                // Should use relative paths like ../../../../../../LUMENFLOW.md
+                // eslint-disable-next-line sonarjs/slow-regex -- Simple path pattern, no backtracking risk
+                expect(content).toMatch(/\[.*?\]\([./]+.*?\.md\)/);
+            }
+        });
+    });
+    describe('PROJECT_ROOT token replacement', () => {
+        it('should replace {{PROJECT_ROOT}} with <project-root> placeholder', async () => {
+            const options = {
+                force: false,
+                full: true,
+            };
+            await scaffoldProject(tempDir, options);
+            const lumenflowContent = fs.readFileSync(path.join(tempDir, 'LUMENFLOW.md'), 'utf-8');
+            // Should not have unreplaced {{PROJECT_ROOT}} tokens
+            expect(lumenflowContent).not.toContain('{{PROJECT_ROOT}}');
+            // Should have the portable placeholder
+            expect(lumenflowContent).toContain('<project-root>');
+        });
+    });
+});

package/dist/__tests__/init.test.js

@@ -268,6 +268,7 @@ describe('lumenflow init', () => {
             const options = {
                 force: false,
                 full: true, // This is now the default when parsed
+                docsStructure: 'arc42', // WU-1309: Explicitly request arc42 for legacy test
             };
             await scaffoldProject(tempDir, options);
             // Should create agent onboarding docs
@@ -311,8 +312,10 @@ describe('lumenflow init', () => {
                 const laneInferencePath = path.join(tempDir, '.lumenflow.lane-inference.yaml');
                 expect(fs.existsSync(laneInferencePath)).toBe(true);
                 const content = fs.readFileSync(laneInferencePath, 'utf-8');
-                // Should have lane definitions
-                expect(content).toContain('lanes:');
+                // WU-1307: Should have hierarchical lane definitions (not flat lanes: array)
+                expect(content).toContain('Framework:');
+                expect(content).toContain('Content:');
+                expect(content).toContain('Operations:');
             });
             it('should scaffold lane-inference with framework-specific lanes when --framework is provided', async () => {
                 const options = {
@@ -330,6 +333,7 @@ describe('lumenflow init', () => {
                 const options = {
                     force: false,
                     full: true,
+                    docsStructure: 'arc42', // WU-1309: Explicitly request arc42 for legacy test
                 };
                 await scaffoldProject(tempDir, options);
                 const onboardingDir = path.join(tempDir, ONBOARDING_DOCS_PATH);
@@ -381,6 +385,7 @@ describe('lumenflow init', () => {
                 const options = {
                     force: false,
                     full: true,
+                    docsStructure: 'arc42', // WU-1309: Explicitly request arc42 for legacy test
                 };
                 await scaffoldProject(tempDir, options);
                 const agentsContent = fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf-8');

package/dist/__tests__/initiative-add-wu.test.js

@@ -0,0 +1,420 @@
+/**
+ * Tests for initiative:add-wu command validation (WU-1330)
+ *
+ * The initiative:add-wu command now validates WU specs before linking.
+ * This ensures only valid, complete WUs can be linked to initiatives.
+ *
+ * TDD: These tests are written BEFORE the implementation.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach, beforeAll } from 'vitest';
+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';
+// Test constants to avoid lint warnings about duplicate strings
+const TEST_WU_ID = 'WU-123';
+const TEST_INIT_ID = 'INIT-001';
+const TEST_LANE = 'Framework: CLI';
+const WU_REL_PATH = 'docs/04-operations/tasks/wu';
+const INIT_REL_PATH = 'docs/04-operations/tasks/initiatives';
+const TEST_INIT_SLUG = 'test-initiative';
+const TEST_INIT_TITLE = 'Test Initiative';
+const TEST_INIT_STATUS = 'open';
+const TEST_DATE = '2026-01-25';
+const MIN_DESCRIPTION_LENGTH = 50;
+// Valid WU document template
+const createValidWUDoc = (overrides = {}) => ({
+    id: TEST_WU_ID,
+    title: 'Test Work Unit Title',
+    lane: TEST_LANE,
+    status: 'ready',
+    type: 'feature',
+    priority: 'P2',
+    created: TEST_DATE,
+    description: 'Context: Testing WU validation. Problem: No validation on add-wu. Solution: Add strict validation before linking.',
+    acceptance: ['WU validates schema', 'Invalid WUs rejected', 'Valid WUs linked bidirectionally'],
+    code_paths: ['packages/@lumenflow/cli/src/initiative-add-wu.ts'],
+    tests: { unit: ['packages/@lumenflow/cli/src/__tests__/initiative-add-wu.test.ts'] },
+    exposure: 'backend-only',
+    ...overrides,
+});
+// Valid initiative document template
+const createValidInitDoc = (overrides = {}) => ({
+    id: TEST_INIT_ID,
+    slug: TEST_INIT_SLUG,
+    title: TEST_INIT_TITLE,
+    status: TEST_INIT_STATUS,
+    created: TEST_DATE,
+    wus: [],
+    ...overrides,
+});
+// Pre-import the module to ensure coverage tracking includes the module itself
+beforeAll(async () => {
+    await import('../initiative-add-wu.js');
+});
+// Mock modules before importing the module under test
+const mockGit = {
+    branch: vi.fn().mockResolvedValue({ current: 'main' }),
+    status: vi.fn().mockResolvedValue({ isClean: () => true }),
+};
+vi.mock('@lumenflow/core/dist/git-adapter.js', () => ({
+    getGitForCwd: vi.fn(() => mockGit),
+}));
+vi.mock('@lumenflow/core/dist/wu-helpers.js', () => ({
+    ensureOnMain: vi.fn().mockResolvedValue(undefined),
+}));
+vi.mock('@lumenflow/core/dist/micro-worktree.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        withMicroWorktree: vi.fn(async ({ execute }) => {
+            // Simulate micro-worktree by executing in temp dir
+            const tempDir = join(tmpdir(), `init-add-wu-test-${Date.now()}`);
+            mkdirSync(tempDir, { recursive: true });
+            try {
+                await execute({ worktreePath: tempDir });
+            }
+            finally {
+                // Cleanup handled by test
+            }
+        }),
+    };
+});
+describe('initiative:add-wu WU validation (WU-1330)', () => {
+    let tempDir;
+    let originalCwd;
+    beforeEach(() => {
+        tempDir = join(tmpdir(), `init-add-wu-validation-test-${Date.now()}`);
+        mkdirSync(tempDir, { recursive: true });
+        originalCwd = process.cwd();
+    });
+    afterEach(() => {
+        process.chdir(originalCwd);
+        if (existsSync(tempDir)) {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        vi.clearAllMocks();
+    });
+    describe('validateWUForLinking', () => {
+        it('should return valid for a well-formed WU', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a valid WU file
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML(createValidWUDoc()));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            expect(result.valid).toBe(true);
+            expect(result.errors).toHaveLength(0);
+        });
+        it('should reject WU with missing required fields', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a WU missing required fields (no description)
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                id: TEST_WU_ID,
+                title: 'Test',
+                lane: TEST_LANE,
+                status: 'ready',
+                created: TEST_DATE,
+                // Missing: description, acceptance, code_paths
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            expect(result.valid).toBe(false);
+            expect(result.errors.length).toBeGreaterThan(0);
+            expect(result.errors.some((e) => e.toLowerCase().includes('description'))).toBe(true);
+        });
+        it('should reject WU with invalid schema', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a WU with invalid status
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                ...createValidWUDoc(),
+                status: 'invalid_status', // Invalid status value
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.toLowerCase().includes('status'))).toBe(true);
+        });
+        it('should reject WU with description containing placeholder marker', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a WU with placeholder in description
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                ...createValidWUDoc(),
+                description: '[PLACEHOLDER] This is a placeholder description that is long enough.',
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes('PLACEHOLDER'))).toBe(true);
+        });
+        it('should reject WU with too short description', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a WU with short description
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                ...createValidWUDoc(),
+                description: 'Too short', // Less than MIN_DESCRIPTION_LENGTH
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes(`${MIN_DESCRIPTION_LENGTH}`))).toBe(true);
+        });
+        it('should reject WU with invalid ID format', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a WU with invalid ID
+            const invalidId = 'INVALID-123';
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${invalidId}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                ...createValidWUDoc(),
+                id: invalidId,
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(invalidId);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.toLowerCase().includes('id'))).toBe(true);
+        });
+        it('should reject WU that does not exist', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            process.chdir(tempDir);
+            const result = validateWUForLinking('WU-999');
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.toLowerCase().includes('not found'))).toBe(true);
+        });
+        it('should reject WU with empty acceptance criteria', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a WU with empty acceptance
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                ...createValidWUDoc(),
+                acceptance: [], // Empty array
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.toLowerCase().includes('acceptance'))).toBe(true);
+        });
+        it('should aggregate multiple errors', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a WU with multiple issues
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                id: TEST_WU_ID,
+                title: '', // Empty title
+                lane: TEST_LANE,
+                status: 'invalid_status', // Invalid status
+                created: TEST_DATE,
+                description: 'short', // Too short
+                acceptance: [], // Empty
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            expect(result.valid).toBe(false);
+            // Should have multiple errors aggregated
+            expect(result.errors.length).toBeGreaterThanOrEqual(2);
+        });
+        it('should include warnings but still be valid', async () => {
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Create a valid WU that might have warnings (missing optional recommended fields)
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                ...createValidWUDoc(),
+                notes: '', // Empty notes - should produce warning
+                spec_refs: [], // Empty spec_refs for feature - should produce warning
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            // Should be valid (warnings don't block)
+            expect(result.valid).toBe(true);
+            // But should have warnings
+            expect(result.warnings.length).toBeGreaterThan(0);
+        });
+    });
+    describe('checkWUExists with validation', () => {
+        it('should throw for invalid WU when strict validation enabled', async () => {
+            const { checkWUExistsAndValidate } = await import('../initiative-add-wu.js');
+            // Create an invalid WU file
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                id: TEST_WU_ID,
+                title: 'Test',
+                lane: TEST_LANE,
+                status: 'ready',
+                created: TEST_DATE,
+                description: 'short', // Too short
+            }));
+            process.chdir(tempDir);
+            // Should throw with aggregated validation errors
+            expect(() => checkWUExistsAndValidate(TEST_WU_ID)).toThrow();
+        });
+        it('should return WU doc when validation passes', async () => {
+            const { checkWUExistsAndValidate } = await import('../initiative-add-wu.js');
+            // Create a valid WU file
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML(createValidWUDoc()));
+            process.chdir(tempDir);
+            const result = checkWUExistsAndValidate(TEST_WU_ID);
+            expect(result.id).toBe(TEST_WU_ID);
+        });
+    });
+    describe('initiative:add-wu integration', () => {
+        it('should reject linking invalid WU with clear error message', async () => {
+            // This is an integration test scenario - main() calls validation before linking
+            // The main() function should call validateWUForLinking and die() with aggregated errors
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Setup invalid WU
+            const wuDir = join(tempDir, WU_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            const wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML({
+                id: TEST_WU_ID,
+                title: 'Test',
+                lane: TEST_LANE,
+                status: 'ready',
+                created: TEST_DATE,
+                description: 'Too short',
+            }));
+            process.chdir(tempDir);
+            const result = validateWUForLinking(TEST_WU_ID);
+            // The error message should be suitable for display to user
+            expect(result.valid).toBe(false);
+            expect(result.errors.join('\n')).toContain('50'); // Should mention minimum length
+        });
+        it('should successfully link valid WU bidirectionally', async () => {
+            // This test verifies that after validation passes, bidirectional linking works
+            // The existing functionality should still work for valid WUs
+            const { validateWUForLinking } = await import('../initiative-add-wu.js');
+            // Setup valid WU 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 wuPath = join(wuDir, `${TEST_WU_ID}.yaml`);
+            const initPath = join(initDir, `${TEST_INIT_ID}.yaml`);
+            writeFileSync(wuPath, stringifyYAML(createValidWUDoc()));
+            writeFileSync(initPath, stringifyYAML(createValidInitDoc()));
+            process.chdir(tempDir);
+            // Validation should pass
+            const result = validateWUForLinking(TEST_WU_ID);
+            expect(result.valid).toBe(true);
+        });
+    });
+    describe('error formatting', () => {
+        it('should format errors in human-readable format', async () => {
+            const { formatValidationErrors } = await import('../initiative-add-wu.js');
+            const errors = ['description: Description is required', 'acceptance: At least one criterion'];
+            const wuId = TEST_WU_ID;
+            const formatted = formatValidationErrors(wuId, errors);
+            expect(formatted).toContain(wuId);
+            expect(formatted).toContain('description');
+            expect(formatted).toContain('acceptance');
+        });
+    });
+    describe('exports', () => {
+        it('should export validateWUForLinking function', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.validateWUForLinking).toBe('function');
+        });
+        it('should export checkWUExistsAndValidate function', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.checkWUExistsAndValidate).toBe('function');
+        });
+        it('should export formatValidationErrors function', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.formatValidationErrors).toBe('function');
+        });
+        it('should export isRetryExhaustionError function (WU-1333)', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.isRetryExhaustionError).toBe('function');
+        });
+        it('should export formatRetryExhaustionError function (WU-1333)', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.formatRetryExhaustionError).toBe('function');
+        });
+    });
+});
+/**
+ * WU-1333: Retry handling tests for initiative:add-wu
+ *
+ * When origin/main moves during operation, the micro-worktree layer handles retry.
+ * When retries are exhausted, the error message should include actionable next steps.
+ */
+describe('initiative:add-wu retry handling (WU-1333)', () => {
+    describe('isRetryExhaustionError', () => {
+        it('should detect retry exhaustion from error message', async () => {
+            const { isRetryExhaustionError } = await import('../initiative-add-wu.js');
+            // Should detect retry exhaustion error
+            const retryError = new Error('Push failed after 3 attempts. Origin main may have significant traffic.');
+            expect(isRetryExhaustionError(retryError)).toBe(true);
+        });
+        it('should detect retry exhaustion with any attempt count', async () => {
+            const { isRetryExhaustionError } = await import('../initiative-add-wu.js');
+            // Different attempt counts should still match
+            const error5 = new Error('Push failed after 5 attempts. Something.');
+            expect(isRetryExhaustionError(error5)).toBe(true);
+            const error1 = new Error('Push failed after 1 attempts. Something.');
+            expect(isRetryExhaustionError(error1)).toBe(true);
+        });
+        it('should not match other errors', async () => {
+            const { isRetryExhaustionError } = await import('../initiative-add-wu.js');
+            const otherError = new Error('Some other error');
+            expect(isRetryExhaustionError(otherError)).toBe(false);
+            const networkError = new Error('Network unreachable');
+            expect(isRetryExhaustionError(networkError)).toBe(false);
+        });
+    });
+    describe('formatRetryExhaustionError', () => {
+        it('should include actionable next steps', async () => {
+            const { formatRetryExhaustionError } = await import('../initiative-add-wu.js');
+            const retryError = new Error('Push failed after 3 attempts. Origin main may have significant traffic.');
+            const formatted = formatRetryExhaustionError(retryError, TEST_WU_ID, TEST_INIT_ID);
+            // Should include the original error
+            expect(formatted).toContain('Push failed after 3 attempts');
+            // Should include next steps heading
+            expect(formatted).toContain('Next steps:');
+            // Should include actionable suggestions
+            expect(formatted).toContain('Wait a few seconds and retry');
+            expect(formatted).toContain('initiative:add-wu');
+        });
+        it('should include the retry command', 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);
+            // Should include command to retry
+            expect(formatted).toContain(`--wu ${TEST_WU_ID}`);
+            expect(formatted).toContain(`--initiative ${TEST_INIT_ID}`);
+        });
+        it('should suggest checking for concurrent agents', 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);
+            // Should mention concurrent agents as possible cause
+            expect(formatted).toMatch(/concurrent|agent|traffic/i);
+        });
+    });
+});