@lumenflow/cli 2.6.0 → 2.8.0

package/dist/__tests__/hooks/enforcement.test.js

@@ -0,0 +1,279 @@
+/**
+ * @file enforcement.test.ts
+ * Tests for Claude Code enforcement hooks (WU-1367)
+ *
+ * TDD: Write failing tests first, then implement.
+ */
+// Test file lint exceptions
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import * as fs from 'node:fs';
+// Mock fs before importing module under test
+vi.mock('node:fs');
+vi.mock('node:child_process');
+const TEST_PROJECT_DIR = '/test/project';
+const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
+describe('WU-1367: Enforcement Hooks Config Schema', () => {
+    describe('ClientConfigSchema enforcement block', () => {
+        it('should accept enforcement block under agents.clients.claude-code', async () => {
+            // Import dynamically to allow mocking
+            const { ClientConfigSchema } = await import('@lumenflow/core/dist/lumenflow-config-schema.js');
+            const config = {
+                preamble: 'CLAUDE.md',
+                skillsDir: '.claude/skills',
+                enforcement: {
+                    hooks: true,
+                    block_outside_worktree: true,
+                    require_wu_for_edits: true,
+                    warn_on_stop_without_wu_done: true,
+                },
+            };
+            const result = ClientConfigSchema.safeParse(config);
+            expect(result.success).toBe(true);
+            if (result.success) {
+                expect(result.data.enforcement).toEqual({
+                    hooks: true,
+                    block_outside_worktree: true,
+                    require_wu_for_edits: true,
+                    warn_on_stop_without_wu_done: true,
+                });
+            }
+        });
+        it('should default enforcement values to false when not specified', async () => {
+            const { ClientConfigSchema } = await import('@lumenflow/core/dist/lumenflow-config-schema.js');
+            const config = {
+                preamble: 'CLAUDE.md',
+                enforcement: {},
+            };
+            const result = ClientConfigSchema.safeParse(config);
+            expect(result.success).toBe(true);
+            if (result.success) {
+                expect(result.data.enforcement?.hooks).toBe(false);
+                expect(result.data.enforcement?.block_outside_worktree).toBe(false);
+                expect(result.data.enforcement?.require_wu_for_edits).toBe(false);
+                expect(result.data.enforcement?.warn_on_stop_without_wu_done).toBe(false);
+            }
+        });
+        it('should allow enforcement to be undefined', async () => {
+            const { ClientConfigSchema } = await import('@lumenflow/core/dist/lumenflow-config-schema.js');
+            const config = {
+                preamble: 'CLAUDE.md',
+            };
+            const result = ClientConfigSchema.safeParse(config);
+            expect(result.success).toBe(true);
+            if (result.success) {
+                expect(result.data.enforcement).toBeUndefined();
+            }
+        });
+    });
+});
+describe('WU-1367: Hook Generation', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    describe('generateEnforcementHooks', () => {
+        it('should generate PreToolUse hook for Write/Edit blocking when block_outside_worktree=true', async () => {
+            const { generateEnforcementHooks } = await import('../../hooks/enforcement-generator.js');
+            const config = {
+                block_outside_worktree: true,
+                require_wu_for_edits: false,
+                warn_on_stop_without_wu_done: false,
+            };
+            const hooks = generateEnforcementHooks(config);
+            expect(hooks.preToolUse).toBeDefined();
+            expect(hooks.preToolUse?.length).toBeGreaterThan(0);
+            expect(hooks.preToolUse?.[0].matcher).toBe('Write|Edit');
+        });
+        it('should generate PreToolUse hook for WU requirement when require_wu_for_edits=true', async () => {
+            const { generateEnforcementHooks } = await import('../../hooks/enforcement-generator.js');
+            const config = {
+                block_outside_worktree: false,
+                require_wu_for_edits: true,
+                warn_on_stop_without_wu_done: false,
+            };
+            const hooks = generateEnforcementHooks(config);
+            expect(hooks.preToolUse).toBeDefined();
+            expect(hooks.preToolUse?.some((h) => h.matcher === 'Write|Edit')).toBe(true);
+        });
+        it('should generate Stop hook when warn_on_stop_without_wu_done=true', async () => {
+            const { generateEnforcementHooks } = await import('../../hooks/enforcement-generator.js');
+            const config = {
+                block_outside_worktree: false,
+                require_wu_for_edits: false,
+                warn_on_stop_without_wu_done: true,
+            };
+            const hooks = generateEnforcementHooks(config);
+            expect(hooks.stop).toBeDefined();
+            expect(hooks.stop?.length).toBeGreaterThan(0);
+        });
+        it('should return empty hooks when all enforcement options are false', async () => {
+            const { generateEnforcementHooks } = await import('../../hooks/enforcement-generator.js');
+            const config = {
+                block_outside_worktree: false,
+                require_wu_for_edits: false,
+                warn_on_stop_without_wu_done: false,
+            };
+            const hooks = generateEnforcementHooks(config);
+            expect(hooks.preToolUse).toBeUndefined();
+            expect(hooks.stop).toBeUndefined();
+        });
+    });
+});
+describe('WU-1367: Integrate Command', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    describe('integrateClaudeCode', () => {
+        it('should create .claude/hooks directory when enforcement.hooks=true', async () => {
+            const mockMkdirSync = vi.mocked(fs.mkdirSync);
+            vi.mocked(fs.writeFileSync);
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            const { integrateClaudeCode } = await import('../../commands/integrate.js');
+            const config = {
+                enforcement: {
+                    hooks: true,
+                    block_outside_worktree: true,
+                    require_wu_for_edits: false,
+                    warn_on_stop_without_wu_done: false,
+                },
+            };
+            await integrateClaudeCode(TEST_PROJECT_DIR, config);
+            expect(mockMkdirSync).toHaveBeenCalledWith(expect.stringContaining('.claude/hooks'), expect.any(Object));
+        });
+        it('should generate enforce-worktree.sh hook when block_outside_worktree=true', async () => {
+            const mockWriteFileSync = vi.mocked(fs.writeFileSync);
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+            const { integrateClaudeCode } = await import('../../commands/integrate.js');
+            const config = {
+                enforcement: {
+                    hooks: true,
+                    block_outside_worktree: true,
+                    require_wu_for_edits: false,
+                    warn_on_stop_without_wu_done: false,
+                },
+            };
+            await integrateClaudeCode(TEST_PROJECT_DIR, config);
+            expect(mockWriteFileSync).toHaveBeenCalledWith(expect.stringContaining('enforce-worktree.sh'), expect.any(String), expect.any(Object));
+        });
+        it('should update settings.json with hook configuration', async () => {
+            const mockWriteFileSync = vi.mocked(fs.writeFileSync);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({
+                permissions: { allow: ['Bash'] },
+            }));
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+            const { integrateClaudeCode } = await import('../../commands/integrate.js');
+            const config = {
+                enforcement: {
+                    hooks: true,
+                    block_outside_worktree: true,
+                    require_wu_for_edits: false,
+                    warn_on_stop_without_wu_done: false,
+                },
+            };
+            await integrateClaudeCode(TEST_PROJECT_DIR, config);
+            // Should write updated settings.json with hooks config
+            const settingsCall = mockWriteFileSync.mock.calls.find((call) => String(call[0]).includes('settings.json'));
+            expect(settingsCall).toBeDefined();
+            const settingsContent = JSON.parse(settingsCall[1]);
+            expect(settingsContent.hooks).toBeDefined();
+            expect(settingsContent.hooks.PreToolUse).toBeDefined();
+        });
+    });
+});
+describe('WU-1367: Hook Graceful Degradation', () => {
+    it('should allow operation when LumenFlow state cannot be determined', async () => {
+        // The hook should fail-open if it cannot determine LumenFlow state
+        // This prevents blocking legitimate work due to infrastructure issues
+        const { checkWorktreeEnforcement } = await import('../../hooks/enforcement-checks.js');
+        // Simulate missing .lumenflow directory
+        vi.mocked(fs.existsSync).mockReturnValue(false);
+        const result = await checkWorktreeEnforcement({
+            file_path: '/some/path/file.ts',
+            tool_name: 'Write',
+        });
+        // Should not block - graceful degradation
+        expect(result.allowed).toBe(true);
+        expect(result.reason).toContain('graceful');
+    });
+    it('should allow operation when worktree detection fails', async () => {
+        const { checkWorktreeEnforcement } = await import('../../hooks/enforcement-checks.js');
+        // Simulate git command failure
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        const mockExecFileSync = vi.fn().mockImplementation(() => {
+            throw new Error('git command failed');
+        });
+        vi.doMock('node:child_process', () => ({
+            execFileSync: mockExecFileSync,
+        }));
+        const result = await checkWorktreeEnforcement({
+            file_path: '/some/path/file.ts',
+            tool_name: 'Write',
+        });
+        // Should not block - graceful degradation
+        expect(result.allowed).toBe(true);
+    });
+});
+describe('WU-1367: Setup Hook Sync', () => {
+    it('should sync hooks when enforcement.hooks=true in config', async () => {
+        // This tests that pnpm setup syncs hooks appropriately
+        const mockWriteFileSync = vi.mocked(fs.writeFileSync);
+        vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+        // Mock existsSync to return false for most paths (so dirs get created)
+        // but return true for the config file
+        vi.mocked(fs.existsSync).mockImplementation((p) => {
+            const pathStr = String(p);
+            return pathStr.endsWith(CONFIG_FILE_NAME);
+        });
+        // Config file is YAML, not JSON
+        vi.mocked(fs.readFileSync).mockImplementation((p) => {
+            const pathStr = String(p);
+            if (pathStr.endsWith(CONFIG_FILE_NAME)) {
+                return `
+agents:
+  clients:
+    claude-code:
+      enforcement:
+        hooks: true
+        block_outside_worktree: true
+`;
+            }
+            // Return empty JSON for settings.json
+            return '{}';
+        });
+        // Clear any previous calls
+        mockWriteFileSync.mockClear();
+        const { syncEnforcementHooks } = await import('../../hooks/enforcement-sync.js');
+        const result = await syncEnforcementHooks(TEST_PROJECT_DIR);
+        // Should have written hook files
+        expect(result).toBe(true);
+        expect(mockWriteFileSync).toHaveBeenCalled();
+    });
+    it('should skip hook sync when enforcement.hooks=false', async () => {
+        const mockWriteFileSync = vi.mocked(fs.writeFileSync);
+        vi.mocked(fs.existsSync).mockImplementation((p) => {
+            const pathStr = String(p);
+            return pathStr.endsWith(CONFIG_FILE_NAME);
+        });
+        vi.mocked(fs.readFileSync).mockImplementation((p) => {
+            const pathStr = String(p);
+            if (pathStr.endsWith(CONFIG_FILE_NAME)) {
+                return `
+agents:
+  clients:
+    claude-code:
+      enforcement:
+        hooks: false
+`;
+            }
+            return '{}';
+        });
+        // Clear any previous calls
+        mockWriteFileSync.mockClear();
+        const { syncEnforcementHooks } = await import('../../hooks/enforcement-sync.js');
+        const result = await syncEnforcementHooks(TEST_PROJECT_DIR);
+        // Should NOT have written hook files
+        expect(result).toBe(false);
+        expect(mockWriteFileSync).not.toHaveBeenCalled();
+    });
+});

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

@@ -0,0 +1,247 @@
+/**
+ * @file init-greenfield.test.ts
+ * Tests for greenfield onboarding with initiative-first workflow (WU-1364)
+ *
+ * Verifies:
+ * - Init output includes initiative-first workflow guidance
+ * - starting-prompt.md has 'When Starting From Product Vision' section
+ * - Init auto-creates initial commit when git repo has no commits
+ * - Init auto-sets git.requireRemote=false when no remote configured
+ * - Default lane-inference template includes Core and Feature as parent lanes
+ * - LUMENFLOW.md mentions initiatives and when to use them
+ */
+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 { execFileSync } from 'node:child_process';
+import { scaffoldProject } from '../init.js';
+// Constants to avoid duplicate strings
+const ARC42_DOCS_STRUCTURE = 'arc42';
+const STARTING_PROMPT_FILE = 'starting-prompt.md';
+const LUMENFLOW_CONFIG_FILE = '.lumenflow.config.yaml';
+const LANE_INFERENCE_FILE = '.lumenflow.lane-inference.yaml';
+describe('greenfield onboarding (WU-1364)', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-greenfield-test-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    function getOnboardingDir() {
+        return path.join(tempDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+    }
+    function getArc42Options() {
+        return {
+            force: false,
+            full: true,
+            docsStructure: ARC42_DOCS_STRUCTURE,
+        };
+    }
+    /**
+     * Initialize a git repo without commits (empty repo state)
+     * Uses execFileSync for safety (no shell injection)
+     */
+    function initEmptyGitRepo() {
+        execFileSync('git', ['init'], { cwd: tempDir, stdio: 'pipe' });
+        // Configure git user for commit (required in some environments)
+        execFileSync('git', ['config', 'user.email', 'test@example.com'], {
+            cwd: tempDir,
+            stdio: 'pipe',
+        });
+        execFileSync('git', ['config', 'user.name', 'Test User'], { cwd: tempDir, stdio: 'pipe' });
+    }
+    /**
+     * Initialize a git repo with an initial commit
+     */
+    function initGitRepoWithCommit() {
+        initEmptyGitRepo();
+        fs.writeFileSync(path.join(tempDir, '.gitkeep'), '');
+        execFileSync('git', ['add', '.gitkeep'], { cwd: tempDir, stdio: 'pipe' });
+        execFileSync('git', ['commit', '-m', 'Initial commit'], { cwd: tempDir, stdio: 'pipe' });
+    }
+    describe('AC: starting-prompt.md has initiative-first workflow section', () => {
+        it('should include "When Starting From Product Vision" section in starting-prompt.md', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const startingPromptPath = path.join(getOnboardingDir(), STARTING_PROMPT_FILE);
+            expect(fs.existsSync(startingPromptPath)).toBe(true);
+            const content = fs.readFileSync(startingPromptPath, 'utf-8');
+            expect(content).toContain('When Starting From Product Vision');
+        });
+        it('should describe 4-step initiative workflow in product vision section', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const startingPromptPath = path.join(getOnboardingDir(), STARTING_PROMPT_FILE);
+            const content = fs.readFileSync(startingPromptPath, 'utf-8');
+            // Should mention initiative creation
+            expect(content).toContain('initiative:create');
+            // Should mention phased work
+            expect(content).toMatch(/phase|INIT-/i);
+            // Should mention WU organization under initiatives
+            expect(content).toMatch(/initiative.*WU|WU.*initiative/i);
+        });
+        it('should warn against creating orphan WUs without initiative structure', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const startingPromptPath = path.join(getOnboardingDir(), STARTING_PROMPT_FILE);
+            const content = fs.readFileSync(startingPromptPath, 'utf-8');
+            // Should have guidance about when NOT to create standalone WUs
+            expect(content).toMatch(/don't|avoid|instead.*initiative/i);
+        });
+    });
+    describe('AC: Init auto-creates initial commit when git repo has no commits', () => {
+        it('should create initial commit in empty git repo', async () => {
+            initEmptyGitRepo();
+            // Verify no commits exist
+            try {
+                execFileSync('git', ['rev-parse', 'HEAD'], { cwd: tempDir, stdio: 'pipe' });
+                throw new Error('Expected HEAD to not exist');
+            }
+            catch {
+                // Expected: fatal: ambiguous argument 'HEAD'
+            }
+            await scaffoldProject(tempDir, getArc42Options());
+            // Now HEAD should exist
+            const result = execFileSync('git', ['rev-parse', 'HEAD'], {
+                cwd: tempDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            });
+            expect(result.trim()).toMatch(/^[a-f0-9]{40}$/);
+        });
+        it('should not create extra commit if repo already has commits', async () => {
+            initGitRepoWithCommit();
+            // Get initial commit count
+            const beforeCount = execFileSync('git', ['rev-list', '--count', 'HEAD'], {
+                cwd: tempDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            }).trim();
+            await scaffoldProject(tempDir, getArc42Options());
+            // Commit count should be the same (init doesn't auto-commit if commits exist)
+            const afterCount = execFileSync('git', ['rev-list', '--count', 'HEAD'], {
+                cwd: tempDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            }).trim();
+            expect(afterCount).toBe(beforeCount);
+        });
+        it('should skip auto-commit if not in a git repo', async () => {
+            // Not a git repo - just a plain directory
+            await scaffoldProject(tempDir, getArc42Options());
+            // Should not fail, just skip the git operations
+            expect(fs.existsSync(path.join(tempDir, LUMENFLOW_CONFIG_FILE))).toBe(true);
+        });
+    });
+    describe('AC: Init auto-sets git.requireRemote=false when no remote configured', () => {
+        it('should set requireRemote=false in config when no origin remote', async () => {
+            initGitRepoWithCommit();
+            // No remote added
+            await scaffoldProject(tempDir, getArc42Options());
+            const configPath = path.join(tempDir, LUMENFLOW_CONFIG_FILE);
+            const content = fs.readFileSync(configPath, 'utf-8');
+            expect(content).toContain('requireRemote: false');
+        });
+        it('should not set requireRemote=false if origin remote exists', async () => {
+            initGitRepoWithCommit();
+            // Add a remote
+            execFileSync('git', ['remote', 'add', 'origin', 'https://github.com/test/repo.git'], {
+                cwd: tempDir,
+                stdio: 'pipe',
+            });
+            await scaffoldProject(tempDir, getArc42Options());
+            const configPath = path.join(tempDir, LUMENFLOW_CONFIG_FILE);
+            const content = fs.readFileSync(configPath, 'utf-8');
+            // Should not have requireRemote: false (remote exists)
+            expect(content).not.toContain('requireRemote: false');
+        });
+        it('should skip remote check if not in a git repo', async () => {
+            // Not a git repo
+            await scaffoldProject(tempDir, getArc42Options());
+            const configPath = path.join(tempDir, LUMENFLOW_CONFIG_FILE);
+            const content = fs.readFileSync(configPath, 'utf-8');
+            // When not in a git repo, should default to requireRemote: false for safety
+            expect(content).toContain('requireRemote: false');
+        });
+    });
+    describe('AC: Default lane-inference template includes Core and Feature parent lanes', () => {
+        it('should include Core as a parent lane', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const laneInferencePath = path.join(tempDir, LANE_INFERENCE_FILE);
+            expect(fs.existsSync(laneInferencePath)).toBe(true);
+            const content = fs.readFileSync(laneInferencePath, 'utf-8');
+            // Should have Core as a top-level parent lane (not just Framework: Core)
+            expect(content).toMatch(/^Core:/m);
+        });
+        it('should include Feature as a parent lane', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const laneInferencePath = path.join(tempDir, LANE_INFERENCE_FILE);
+            const content = fs.readFileSync(laneInferencePath, 'utf-8');
+            // Should have Feature as a top-level parent lane
+            expect(content).toMatch(/^Feature:/m);
+        });
+        it('should support intuitive lane names like "Core: Platform"', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const laneInferencePath = path.join(tempDir, LANE_INFERENCE_FILE);
+            const content = fs.readFileSync(laneInferencePath, 'utf-8');
+            // Should have sublanes under Core and Feature
+            // e.g., Core: followed by sublanes like Platform, Library, etc.
+            expect(content).toMatch(/Core:\n\s+\w+:/m);
+            expect(content).toMatch(/Feature:\n\s+\w+:/m);
+        });
+    });
+    describe('AC: LUMENFLOW.md mentions initiatives and when to use them', () => {
+        it('should mention initiatives in generated LUMENFLOW.md', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const lumenflowPath = path.join(tempDir, 'LUMENFLOW.md');
+            const content = fs.readFileSync(lumenflowPath, 'utf-8');
+            expect(content).toMatch(/initiative/i);
+        });
+        it('should explain when to use initiatives vs standalone WUs', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const lumenflowPath = path.join(tempDir, 'LUMENFLOW.md');
+            const content = fs.readFileSync(lumenflowPath, 'utf-8');
+            // Should mention when to use initiatives
+            expect(content).toMatch(/multi-phase|product vision|larger|complex/i);
+        });
+        it('should reference initiative:create command', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const lumenflowPath = path.join(tempDir, 'LUMENFLOW.md');
+            const content = fs.readFileSync(lumenflowPath, 'utf-8');
+            expect(content).toContain('initiative:create');
+        });
+    });
+    describe('AC: Init output includes initiative-first workflow guidance', () => {
+        // This test verifies the console output, which requires capturing stdout
+        // We'll mock console.log to capture the output
+        it('should print initiative-first guidance in init output', async () => {
+            const consoleLogs = [];
+            const originalLog = console.log;
+            console.log = (...args) => {
+                consoleLogs.push(args.join(' '));
+            };
+            try {
+                // Import and run main() to capture console output
+                const { main } = await import('../init.js');
+                // Change to temp directory and run init
+                const originalCwd = process.cwd();
+                process.chdir(tempDir);
+                // Mock process.argv for parseInitOptions
+                const originalArgv = process.argv;
+                process.argv = ['node', 'init', '--full'];
+                try {
+                    await main();
+                }
+                finally {
+                    process.argv = originalArgv;
+                    process.chdir(originalCwd);
+                }
+                const output = consoleLogs.join('\n');
+                // Should mention initiatives in the "Next steps" or guidance section
+                expect(output).toMatch(/initiative|product vision|INIT-/i);
+            }
+            finally {
+                console.log = originalLog;
+            }
+        });
+    });
+});

package/dist/__tests__/init-quick-ref.test.js

@@ -105,7 +105,6 @@ describe('quick-ref commands', () => {
             const quickRefPath = getQuickRefPath();
             const content = fs.readFileSync(quickRefPath, 'utf-8');
             // Should have a project setup section
-            // eslint-disable-next-line sonarjs/slow-regex -- Simple alternation, no backtracking risk
             expect(content).toMatch(/##.*?Setup|##.*?Project/i);
             expect(content).toContain('lumenflow init');
         });

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

@@ -75,7 +75,6 @@ describe('template portability', () => {
             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\)/);
             }
         });

package/dist/__tests__/init.test.js

@@ -491,4 +491,31 @@ describe('lumenflow init', () => {
             });
         });
     });
+    // WU-1362: Branch guard tests for init.ts
+    describe('WU-1362: branch guard for tracked file writes', () => {
+        it('should block scaffold when on main branch and targeting main checkout', async () => {
+            // This test verifies that scaffoldProject checks branch before writing
+            // Note: This test uses a temp directory (not on main), so it should pass
+            // The actual blocking only applies when targeting main checkout on main branch
+            const options = {
+                force: false,
+                full: false,
+            };
+            // Since we're in a temp dir, not on main branch, this should work
+            const result = await scaffoldProject(tempDir, options);
+            expect(result.created.length).toBeGreaterThan(0);
+        });
+        it('should allow scaffold in worktree directory', async () => {
+            // Simulate worktree-like path by creating directory structure
+            const worktreePath = path.join(tempDir, 'worktrees', 'operations-wu-999');
+            fs.mkdirSync(worktreePath, { recursive: true });
+            const options = {
+                force: false,
+                full: false,
+            };
+            // Should succeed when in worktree-like path
+            const result = await scaffoldProject(worktreePath, options);
+            expect(result.created.length).toBeGreaterThan(0);
+        });
+    });
 });