@lumenflow/cli 2.5.0 → 2.6.0

package/README.md

@@ -16,19 +16,22 @@ npm install @lumenflow/cli
 ## Quick Start
 
 ```bash
+# Install the CLI
+pnpm add -D @lumenflow/cli   # or: npm install -D @lumenflow/cli
+
 # Initialize LumenFlow (works with any AI)
-npx lumenflow-init
+pnpm exec lumenflow
 
 # Or specify your AI tool for enhanced integration
-npx lumenflow-init --client claude    # Claude Code
-npx lumenflow-init --client cursor    # Cursor
-npx lumenflow-init --client windsurf  # Windsurf
-npx lumenflow-init --client cline     # Cline
-npx lumenflow-init --client aider     # Aider
-npx lumenflow-init --client all       # All integrations
+pnpm exec lumenflow --client claude    # Claude Code
+pnpm exec lumenflow --client cursor    # Cursor
+pnpm exec lumenflow --client windsurf  # Windsurf
+pnpm exec lumenflow --client cline     # Cline
+pnpm exec lumenflow --client aider     # Aider
+pnpm exec lumenflow --client all       # All integrations
 ```
 
-The default `lumenflow-init` creates `AGENTS.md` and `LUMENFLOW.md` which work with **any AI coding assistant**. The `--client` flag adds vendor-specific configuration files for deeper integration.
+The default `lumenflow` command creates `AGENTS.md` and `LUMENFLOW.md` which work with **any AI coding assistant**. The `--client` flag adds vendor-specific configuration files for deeper integration.
 
 See [AI Integrations](https://lumenflow.dev/guides/ai-integrations) for details on each tool.
 

package/dist/__tests__/gates-config.test.js

@@ -0,0 +1,304 @@
+/**
+ * @file gates-config.test.ts
+ * WU-1356: Tests for package manager and script name configuration.
+ *
+ * Tests configurable package_manager, gates.commands, test_runner, and build_command
+ * in .lumenflow.config.yaml for framework agnosticism.
+ */
+/* eslint-disable sonarjs/no-duplicate-string -- Test files intentionally repeat string literals for readability */
+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 * as yaml from 'yaml';
+// Import the schema and functions we're testing
+import { PackageManagerSchema, TestRunnerSchema, GatesCommandsConfigSchema, parseConfig, } from '@lumenflow/core/dist/lumenflow-config-schema.js';
+import { resolvePackageManager, resolveBuildCommand, resolveGatesCommands, resolveTestRunner, getIgnorePatterns, } from '@lumenflow/core/dist/gates-config.js';
+describe('WU-1356: Package manager and script configuration', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-test-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    describe('PackageManagerSchema', () => {
+        it('accepts pnpm as default', () => {
+            const result = PackageManagerSchema.parse(undefined);
+            expect(result).toBe('pnpm');
+        });
+        it('accepts npm', () => {
+            const result = PackageManagerSchema.parse('npm');
+            expect(result).toBe('npm');
+        });
+        it('accepts yarn', () => {
+            const result = PackageManagerSchema.parse('yarn');
+            expect(result).toBe('yarn');
+        });
+        it('accepts bun', () => {
+            const result = PackageManagerSchema.parse('bun');
+            expect(result).toBe('bun');
+        });
+        it('rejects invalid package manager', () => {
+            expect(() => PackageManagerSchema.parse('invalid')).toThrow();
+        });
+    });
+    describe('TestRunnerSchema', () => {
+        it('accepts vitest as default', () => {
+            const result = TestRunnerSchema.parse(undefined);
+            expect(result).toBe('vitest');
+        });
+        it('accepts jest', () => {
+            const result = TestRunnerSchema.parse('jest');
+            expect(result).toBe('jest');
+        });
+        it('accepts mocha', () => {
+            const result = TestRunnerSchema.parse('mocha');
+            expect(result).toBe('mocha');
+        });
+        it('rejects invalid test runner', () => {
+            expect(() => TestRunnerSchema.parse('invalid')).toThrow();
+        });
+    });
+    describe('GatesCommandsConfigSchema', () => {
+        it('has sensible defaults for test commands', () => {
+            const result = GatesCommandsConfigSchema.parse({});
+            expect(result.test_full).toBeDefined();
+            expect(result.test_docs_only).toBeDefined();
+            expect(result.test_incremental).toBeDefined();
+        });
+        it('allows custom test commands', () => {
+            const config = {
+                test_full: 'npm test',
+                test_docs_only: 'npm test -- --grep docs',
+                test_incremental: 'npm test -- --changed',
+            };
+            const result = GatesCommandsConfigSchema.parse(config);
+            expect(result.test_full).toBe('npm test');
+            expect(result.test_docs_only).toBe('npm test -- --grep docs');
+            expect(result.test_incremental).toBe('npm test -- --changed');
+        });
+    });
+    describe('LumenFlowConfigSchema - package_manager field', () => {
+        it('includes package_manager with default pnpm', () => {
+            const config = parseConfig({});
+            expect(config.package_manager).toBe('pnpm');
+        });
+        it('accepts npm as package_manager', () => {
+            const config = parseConfig({ package_manager: 'npm' });
+            expect(config.package_manager).toBe('npm');
+        });
+        it('accepts yarn as package_manager', () => {
+            const config = parseConfig({ package_manager: 'yarn' });
+            expect(config.package_manager).toBe('yarn');
+        });
+        it('accepts bun as package_manager', () => {
+            const config = parseConfig({ package_manager: 'bun' });
+            expect(config.package_manager).toBe('bun');
+        });
+    });
+    describe('LumenFlowConfigSchema - test_runner field', () => {
+        it('includes test_runner with default vitest', () => {
+            const config = parseConfig({});
+            expect(config.test_runner).toBe('vitest');
+        });
+        it('accepts jest as test_runner', () => {
+            const config = parseConfig({ test_runner: 'jest' });
+            expect(config.test_runner).toBe('jest');
+        });
+        it('accepts mocha as test_runner', () => {
+            const config = parseConfig({ test_runner: 'mocha' });
+            expect(config.test_runner).toBe('mocha');
+        });
+    });
+    describe('LumenFlowConfigSchema - gates.commands section', () => {
+        it('includes gates.commands with defaults', () => {
+            const config = parseConfig({});
+            expect(config.gates.commands).toBeDefined();
+            expect(config.gates.commands.test_full).toBeDefined();
+            expect(config.gates.commands.test_docs_only).toBeDefined();
+            expect(config.gates.commands.test_incremental).toBeDefined();
+        });
+        it('allows custom gates commands configuration', () => {
+            const config = parseConfig({
+                gates: {
+                    commands: {
+                        test_full: 'npm test',
+                        test_docs_only: 'npm test -- --docs',
+                        test_incremental: 'npm test -- --changed',
+                    },
+                },
+            });
+            expect(config.gates.commands.test_full).toBe('npm test');
+            expect(config.gates.commands.test_docs_only).toBe('npm test -- --docs');
+            expect(config.gates.commands.test_incremental).toBe('npm test -- --changed');
+        });
+    });
+    describe('LumenFlowConfigSchema - build_command field', () => {
+        it('includes build_command with default for pnpm', () => {
+            const config = parseConfig({});
+            expect(config.build_command).toBe('pnpm --filter @lumenflow/cli build');
+        });
+        it('allows custom build_command', () => {
+            const config = parseConfig({ build_command: 'npm run build' });
+            expect(config.build_command).toBe('npm run build');
+        });
+    });
+    describe('resolvePackageManager', () => {
+        it('returns pnpm when no config file exists', () => {
+            const result = resolvePackageManager(tempDir);
+            expect(result).toBe('pnpm');
+        });
+        it('returns configured package manager from config file', () => {
+            const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+            fs.writeFileSync(configPath, yaml.stringify({ package_manager: 'npm' }));
+            const result = resolvePackageManager(tempDir);
+            expect(result).toBe('npm');
+        });
+        it('returns yarn when configured', () => {
+            const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+            fs.writeFileSync(configPath, yaml.stringify({ package_manager: 'yarn' }));
+            const result = resolvePackageManager(tempDir);
+            expect(result).toBe('yarn');
+        });
+    });
+    describe('resolveBuildCommand', () => {
+        it('returns default build command when no config file exists', () => {
+            const result = resolveBuildCommand(tempDir);
+            expect(result).toBe('pnpm --filter @lumenflow/cli build');
+        });
+        it('returns configured build_command from config file', () => {
+            const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+            fs.writeFileSync(configPath, yaml.stringify({ build_command: 'npm run build' }));
+            const result = resolveBuildCommand(tempDir);
+            expect(result).toBe('npm run build');
+        });
+        it('adapts default build command for different package managers', () => {
+            const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+            fs.writeFileSync(configPath, yaml.stringify({ package_manager: 'npm' }));
+            const result = resolveBuildCommand(tempDir);
+            expect(result).toContain('npm');
+        });
+    });
+    describe('resolveGatesCommands', () => {
+        it('returns default commands when no config file exists', () => {
+            const commands = resolveGatesCommands(tempDir);
+            expect(commands.test_full).toBeDefined();
+            expect(commands.test_docs_only).toBeDefined();
+            expect(commands.test_incremental).toBeDefined();
+        });
+        it('returns configured commands from config file', () => {
+            const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+            fs.writeFileSync(configPath, yaml.stringify({
+                gates: {
+                    commands: {
+                        test_full: 'npm test',
+                        test_docs_only: 'npm test -- --docs',
+                        test_incremental: 'npm test -- --changed',
+                    },
+                },
+            }));
+            const commands = resolveGatesCommands(tempDir);
+            expect(commands.test_full).toBe('npm test');
+            expect(commands.test_docs_only).toBe('npm test -- --docs');
+            expect(commands.test_incremental).toBe('npm test -- --changed');
+        });
+    });
+    describe('resolveTestRunner', () => {
+        it('returns vitest when no config file exists', () => {
+            const result = resolveTestRunner(tempDir);
+            expect(result).toBe('vitest');
+        });
+        it('returns jest when configured', () => {
+            const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+            fs.writeFileSync(configPath, yaml.stringify({ test_runner: 'jest' }));
+            const result = resolveTestRunner(tempDir);
+            expect(result).toBe('jest');
+        });
+    });
+    describe('getIgnorePatterns', () => {
+        it('returns .turbo pattern for vitest', () => {
+            const patterns = getIgnorePatterns('vitest');
+            expect(patterns).toContain('.turbo');
+        });
+        it('returns different pattern for jest', () => {
+            const patterns = getIgnorePatterns('jest');
+            expect(patterns).not.toContain('.turbo');
+        });
+        it('returns custom pattern from config', () => {
+            const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+            fs.writeFileSync(configPath, yaml.stringify({
+                gates: {
+                    ignore_patterns: ['.nx', 'dist'],
+                },
+            }));
+            // This would be a config-aware version
+            const patterns = getIgnorePatterns('jest');
+            expect(Array.isArray(patterns)).toBe(true);
+        });
+    });
+});
+describe('WU-1356: npm+jest configuration', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-npm-jest-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    it('supports npm+jest configuration', () => {
+        const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+        fs.writeFileSync(configPath, yaml.stringify({
+            package_manager: 'npm',
+            test_runner: 'jest',
+            gates: {
+                commands: {
+                    test_full: 'npm test',
+                    test_docs_only: 'npm test -- --testPathPattern=docs',
+                    test_incremental: 'npm test -- --onlyChanged',
+                },
+            },
+            build_command: 'npm run build',
+        }));
+        const pkgManager = resolvePackageManager(tempDir);
+        const testRunner = resolveTestRunner(tempDir);
+        const commands = resolveGatesCommands(tempDir);
+        const buildCmd = resolveBuildCommand(tempDir);
+        expect(pkgManager).toBe('npm');
+        expect(testRunner).toBe('jest');
+        expect(commands.test_full).toBe('npm test');
+        expect(commands.test_incremental).toBe('npm test -- --onlyChanged');
+        expect(buildCmd).toBe('npm run build');
+    });
+});
+describe('WU-1356: yarn+nx configuration', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-yarn-nx-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    it('supports yarn+nx configuration', () => {
+        const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+        fs.writeFileSync(configPath, yaml.stringify({
+            package_manager: 'yarn',
+            test_runner: 'jest',
+            gates: {
+                commands: {
+                    test_full: 'yarn nx run-many --target=test --all',
+                    test_docs_only: 'yarn nx test docs',
+                    test_incremental: 'yarn nx affected --target=test',
+                },
+            },
+            build_command: 'yarn nx build @lumenflow/cli',
+        }));
+        const pkgManager = resolvePackageManager(tempDir);
+        const commands = resolveGatesCommands(tempDir);
+        const buildCmd = resolveBuildCommand(tempDir);
+        expect(pkgManager).toBe('yarn');
+        expect(commands.test_full).toBe('yarn nx run-many --target=test --all');
+        expect(commands.test_incremental).toBe('yarn nx affected --target=test');
+        expect(buildCmd).toBe('yarn nx build @lumenflow/cli');
+    });
+});

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

@@ -93,4 +93,115 @@ describe('init scripts generation (WU-1307)', () => {
         expect(packageJson.scripts?.['wu:claim']).toBeDefined();
         expect(packageJson.scripts?.gates).toBeDefined();
     });
+    // WU-1342: Test for all 17 essential commands
+    it('should include all 17 essential commands (WU-1342)', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        const packageJson = readPackageJson();
+        // All 17 essential commands that must be present per WU-1342 acceptance criteria
+        const essentialScripts = [
+            // Core WU lifecycle
+            'wu:claim',
+            'wu:done',
+            'wu:create',
+            'wu:status',
+            'wu:block',
+            'wu:unblock',
+            // Additional critical commands (WU-1342)
+            'wu:prep',
+            'wu:recover',
+            'wu:spawn',
+            'wu:validate',
+            'wu:infer-lane',
+            // Memory commands
+            'mem:init',
+            'mem:checkpoint',
+            'mem:inbox',
+            // Lane commands
+            'lane:suggest',
+            // Gates
+            'gates',
+            'gates:docs',
+        ];
+        for (const scriptName of essentialScripts) {
+            expect(packageJson.scripts?.[scriptName], `Missing essential script: ${scriptName}`).toBeDefined();
+        }
+        // Verify count
+        const lumenflowScripts = Object.keys(packageJson.scripts ?? {}).filter((key) => key.startsWith('wu:') ||
+            key.startsWith('mem:') ||
+            key.startsWith('lane:') ||
+            key === 'gates' ||
+            key === 'gates:docs');
+        expect(lumenflowScripts.length).toBeGreaterThanOrEqual(17);
+    });
+});
+describe('init .gitignore generation (WU-1342)', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-init-gitignore-'));
+    });
+    afterEach(() => {
+        if (tempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    it('should create .gitignore with required exclusions (WU-1342)', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        const gitignorePath = path.join(tempDir, '.gitignore');
+        expect(fs.existsSync(gitignorePath)).toBe(true);
+        const content = fs.readFileSync(gitignorePath, 'utf-8');
+        // Must include node_modules
+        expect(content).toContain('node_modules');
+        // Must include .lumenflow/state
+        expect(content).toContain('.lumenflow/state');
+        // Must include worktrees
+        expect(content).toContain('worktrees');
+    });
+    it('should preserve existing .gitignore content in merge mode (WU-1342)', async () => {
+        // Arrange
+        const gitignorePath = path.join(tempDir, '.gitignore');
+        const existingContent = '# Custom ignores\n.env\n*.log\n';
+        fs.writeFileSync(gitignorePath, existingContent);
+        // Act
+        await scaffoldProject(tempDir, { force: false, full: true, merge: true });
+        // Assert
+        const content = fs.readFileSync(gitignorePath, 'utf-8');
+        // Should preserve existing content
+        expect(content).toContain('.env');
+        expect(content).toContain('*.log');
+        // Should add LumenFlow exclusions
+        expect(content).toContain('node_modules');
+        expect(content).toContain('.lumenflow/state');
+        expect(content).toContain('worktrees');
+    });
+});
+describe('init .claude directory creation (WU-1342)', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-init-claude-'));
+    });
+    afterEach(() => {
+        if (tempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    it('should create .claude directory when --client claude specified (WU-1342)', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: false, client: 'claude' });
+        // Assert
+        const claudeDir = path.join(tempDir, '.claude');
+        expect(fs.existsSync(claudeDir)).toBe(true);
+        // Should have agents directory
+        const agentsDir = path.join(claudeDir, 'agents');
+        expect(fs.existsSync(agentsDir)).toBe(true);
+        // Should have settings.json
+        const settingsPath = path.join(claudeDir, 'settings.json');
+        expect(fs.existsSync(settingsPath)).toBe(true);
+        // Should have skills directory
+        const skillsDir = path.join(claudeDir, 'skills');
+        expect(fs.existsSync(skillsDir)).toBe(true);
+    });
 });

package/dist/__tests__/templates-sync.test.js

@@ -0,0 +1,219 @@
+/**
+ * @file templates-sync.test.ts
+ * Tests for templates synchronization and drift detection (WU-1353)
+ */
+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 { syncTemplates, syncOnboardingDocs, syncCoreDocs, convertToTemplate, checkTemplateDrift, } from '../sync-templates.js';
+// Constants for frequently used path segments (sonarjs/no-duplicate-string)
+const PACKAGES_DIR = 'packages';
+const LUMENFLOW_SCOPE = '@lumenflow';
+const CLI_DIR = 'cli';
+const TEMPLATES_DIR = 'templates';
+const CORE_DIR = 'core';
+const LUMENFLOW_DOT_DIR = '.lumenflow';
+const CONSTRAINTS_FILE = 'constraints.md';
+const CONSTRAINTS_TEMPLATE = 'constraints.md.template';
+describe('templates-sync', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'templates-sync-test-'));
+    });
+    afterEach(() => {
+        if (tempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    describe('convertToTemplate', () => {
+        it('should replace dates with {{DATE}} placeholder', () => {
+            const content = 'Updated: 2026-02-02\nCreated: 2025-01-15';
+            const result = convertToTemplate(content, '/home/test/project');
+            expect(result).toBe('Updated: {{DATE}}\nCreated: {{DATE}}');
+        });
+        it('should preserve content without dates', () => {
+            const content = '# Title\n\nSome content without dates.';
+            const result = convertToTemplate(content, '/home/test/project');
+            expect(result).toBe(content);
+        });
+    });
+    describe('syncCoreDocs', () => {
+        beforeEach(() => {
+            // Set up directory structure
+            const templatesDir = path.join(tempDir, PACKAGES_DIR, LUMENFLOW_SCOPE, CLI_DIR, TEMPLATES_DIR, CORE_DIR, LUMENFLOW_DOT_DIR);
+            fs.mkdirSync(templatesDir, { recursive: true });
+            // Create source constraints.md with v1.1 content
+            const lumenflowDir = path.join(tempDir, LUMENFLOW_DOT_DIR);
+            fs.mkdirSync(lumenflowDir, { recursive: true });
+            fs.writeFileSync(path.join(lumenflowDir, CONSTRAINTS_FILE), `# LumenFlow Constraints Capsule
+
+**Version:** 1.1
+**Last updated:** 2026-02-02
+
+This document contains the 7 non-negotiable constraints.
+
+### 1. Worktree Discipline and Git Safety
+
+**MANDATORY PRE-WRITE CHECK**
+
+**NEVER "QUICK FIX" ON MAIN**
+`);
+            // Create LUMENFLOW.md
+            fs.writeFileSync(path.join(tempDir, 'LUMENFLOW.md'), `# LumenFlow Workflow Guide
+
+**Last updated:** 2026-02-02
+
+## Critical Rule: Use wu:prep Then wu:done
+`);
+        });
+        it('should sync constraints.md to template', async () => {
+            const result = await syncCoreDocs(tempDir, false);
+            expect(result.errors).toHaveLength(0);
+            expect(result.synced).toContain(`${PACKAGES_DIR}/${LUMENFLOW_SCOPE}/${CLI_DIR}/${TEMPLATES_DIR}/${CORE_DIR}/${LUMENFLOW_DOT_DIR}/${CONSTRAINTS_TEMPLATE}`);
+            // Verify template content
+            const templatePath = path.join(tempDir, PACKAGES_DIR, LUMENFLOW_SCOPE, CLI_DIR, TEMPLATES_DIR, CORE_DIR, LUMENFLOW_DOT_DIR, CONSTRAINTS_TEMPLATE);
+            const templateContent = fs.readFileSync(templatePath, 'utf-8');
+            // Should have {{DATE}} placeholder
+            expect(templateContent).toContain('{{DATE}}');
+            expect(templateContent).not.toContain('2026-02-02');
+            // Should have v1.1 content markers
+            expect(templateContent).toContain('Version:** 1.1');
+            expect(templateContent).toContain('7 non-negotiable constraints');
+            expect(templateContent).toContain('MANDATORY PRE-WRITE CHECK');
+            expect(templateContent).toContain('NEVER "QUICK FIX" ON MAIN');
+        });
+        it('should use dry-run mode without writing files', async () => {
+            // First, ensure no template exists
+            const templatePath = path.join(tempDir, PACKAGES_DIR, LUMENFLOW_SCOPE, CLI_DIR, TEMPLATES_DIR, CORE_DIR, LUMENFLOW_DOT_DIR, CONSTRAINTS_TEMPLATE);
+            // Remove if it exists from beforeEach
+            if (fs.existsSync(templatePath)) {
+                fs.unlinkSync(templatePath);
+            }
+            const result = await syncCoreDocs(tempDir, true);
+            expect(result.errors).toHaveLength(0);
+            expect(result.synced.length).toBeGreaterThan(0);
+            expect(fs.existsSync(templatePath)).toBe(false);
+        });
+    });
+    describe('syncOnboardingDocs', () => {
+        const ONBOARDING_SUBPATH = [
+            'docs',
+            '04-operations',
+            '_frameworks',
+            'lumenflow',
+            'agent',
+            'onboarding',
+        ];
+        const FIRST_WU_MISTAKES_FILE = 'first-wu-mistakes.md';
+        beforeEach(() => {
+            // Set up onboarding source directory
+            const onboardingDir = path.join(tempDir, ...ONBOARDING_SUBPATH);
+            fs.mkdirSync(onboardingDir, { recursive: true });
+            // Create first-wu-mistakes.md with v1.1 content (11 mistakes)
+            fs.writeFileSync(path.join(onboardingDir, FIRST_WU_MISTAKES_FILE), `# First WU Mistakes
+
+**Last updated:** 2026-02-02
+
+## Mistake 1: Not Using Worktrees
+
+pnpm wu:prep --id WU-123
+
+## Mistake 11: "Quick Fixing" on Main
+
+## Quick Checklist
+
+- [ ] Check spec_refs for plans
+`);
+            // Set up target directory
+            const templatesDir = path.join(tempDir, PACKAGES_DIR, LUMENFLOW_SCOPE, CLI_DIR, TEMPLATES_DIR, CORE_DIR, 'ai', 'onboarding');
+            fs.mkdirSync(templatesDir, { recursive: true });
+        });
+        it('should sync first-wu-mistakes.md to template', async () => {
+            const result = await syncOnboardingDocs(tempDir, false);
+            expect(result.errors).toHaveLength(0);
+            expect(result.synced).toContain(`${PACKAGES_DIR}/${LUMENFLOW_SCOPE}/${CLI_DIR}/${TEMPLATES_DIR}/${CORE_DIR}/ai/onboarding/${FIRST_WU_MISTAKES_FILE}.template`);
+            // Verify template content
+            const templatePath = path.join(tempDir, PACKAGES_DIR, LUMENFLOW_SCOPE, CLI_DIR, TEMPLATES_DIR, CORE_DIR, 'ai', 'onboarding', `${FIRST_WU_MISTAKES_FILE}.template`);
+            const templateContent = fs.readFileSync(templatePath, 'utf-8');
+            // Should have {{DATE}} placeholder
+            expect(templateContent).toContain('{{DATE}}');
+            expect(templateContent).not.toContain('2026-02-02');
+            // Should have v1.1 content markers
+            expect(templateContent).toContain('Mistake 11:');
+            expect(templateContent).toContain('Quick Fixing" on Main');
+            expect(templateContent).toContain('wu:prep');
+            expect(templateContent).toContain('spec_refs');
+        });
+    });
+    describe('checkTemplateDrift', () => {
+        beforeEach(() => {
+            // Set up source files
+            const lumenflowDir = path.join(tempDir, LUMENFLOW_DOT_DIR);
+            fs.mkdirSync(lumenflowDir, { recursive: true });
+            fs.writeFileSync(path.join(lumenflowDir, CONSTRAINTS_FILE), `# Constraints
+**Version:** 1.1
+**Last updated:** 2026-02-02
+7 constraints`);
+            // Set up template directory
+            const templatesDir = path.join(tempDir, PACKAGES_DIR, LUMENFLOW_SCOPE, CLI_DIR, TEMPLATES_DIR, CORE_DIR, LUMENFLOW_DOT_DIR);
+            fs.mkdirSync(templatesDir, { recursive: true });
+        });
+        it('should detect drift when template is outdated', async () => {
+            // Create outdated template (v1.0, 6 constraints)
+            const templatePath = path.join(tempDir, PACKAGES_DIR, LUMENFLOW_SCOPE, CLI_DIR, TEMPLATES_DIR, CORE_DIR, LUMENFLOW_DOT_DIR, CONSTRAINTS_TEMPLATE);
+            fs.writeFileSync(templatePath, `# Constraints
+**Version:** 1.0
+**Last updated:** {{DATE}}
+6 constraints`);
+            const drift = await checkTemplateDrift(tempDir);
+            expect(drift.hasDrift).toBe(true);
+            expect(drift.driftingFiles.length).toBeGreaterThan(0);
+            expect(drift.driftingFiles.some((f) => f.includes(CONSTRAINTS_FILE))).toBe(true);
+        });
+        it('should report no drift when templates are in sync', async () => {
+            // First sync templates
+            await syncCoreDocs(tempDir, false);
+            // Then check for drift
+            const drift = await checkTemplateDrift(tempDir);
+            // After sync, constraints should not be drifting
+            expect(drift.driftingFiles.filter((f) => f.includes(CONSTRAINTS_FILE))).toHaveLength(0);
+        });
+        it('should return detailed drift report', async () => {
+            // Create outdated template
+            const templatePath = path.join(tempDir, PACKAGES_DIR, LUMENFLOW_SCOPE, CLI_DIR, TEMPLATES_DIR, CORE_DIR, LUMENFLOW_DOT_DIR, CONSTRAINTS_TEMPLATE);
+            fs.writeFileSync(templatePath, 'outdated content');
+            const drift = await checkTemplateDrift(tempDir);
+            expect(drift.hasDrift).toBe(true);
+            expect(drift.driftingFiles).toBeDefined();
+            expect(Array.isArray(drift.driftingFiles)).toBe(true);
+        });
+    });
+    describe('syncTemplates (full sync)', () => {
+        beforeEach(() => {
+            // Set up minimal directory structure
+            const lumenflowDir = path.join(tempDir, LUMENFLOW_DOT_DIR);
+            fs.mkdirSync(lumenflowDir, { recursive: true });
+            fs.writeFileSync(path.join(lumenflowDir, CONSTRAINTS_FILE), 'content');
+            fs.writeFileSync(path.join(tempDir, 'LUMENFLOW.md'), 'content');
+            const onboardingDir = path.join(tempDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+            fs.mkdirSync(onboardingDir, { recursive: true });
+            fs.writeFileSync(path.join(onboardingDir, 'first-wu-mistakes.md'), 'content');
+            const skillsDir = path.join(tempDir, '.claude', 'skills', 'test-skill');
+            fs.mkdirSync(skillsDir, { recursive: true });
+            fs.writeFileSync(path.join(skillsDir, 'SKILL.md'), 'skill content');
+        });
+        it('should sync all template categories', async () => {
+            const result = await syncTemplates(tempDir, false);
+            expect(result.core.errors).toHaveLength(0);
+            expect(result.onboarding.errors).toHaveLength(0);
+            expect(result.skills.errors).toHaveLength(0);
+            // Should sync at least constraints and LUMENFLOW
+            expect(result.core.synced.length).toBeGreaterThanOrEqual(2);
+            // Should sync onboarding docs
+            expect(result.onboarding.synced.length).toBeGreaterThanOrEqual(1);
+            // Should sync skills
+            expect(result.skills.synced.length).toBeGreaterThanOrEqual(1);
+        });
+    });
+});