@lumenflow/cli 2.7.0 → 2.9.0

package/dist/init.js

@@ -5,6 +5,7 @@
  * WU-1028: Vendor-agnostic core + vendor overlays
  * WU-1085: Added createWUParser for proper --help support
  * WU-1171: Added --merge mode, --client flag, AGENTS.md, updated vendor paths
+ * WU-1362: Added branch guard to check branch before writing tracked files
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -16,6 +17,10 @@ import { getDefaultConfig, createWUParser, WU_OPTIONS } from '@lumenflow/core';
 import { GATE_PRESETS } from '@lumenflow/core/dist/gates-config.js';
 // WU-1171: Import merge block utilities
 import { updateMergeBlock } from './merge-block.js';
+// WU-1362: Import worktree guard utilities for branch checking
+import { isMainBranch, isInWorktree } from '@lumenflow/core/dist/core/worktree-guard.js';
+// WU-1386: Import doctor for auto-run after init
+import { runDoctorForInit } from './doctor.js';
 /**
  * WU-1085: CLI option definitions for init command
  * WU-1171: Added --merge and --client options
@@ -67,9 +72,12 @@ const INIT_OPTIONS = {
  * Provides proper --help, --version, and option parsing
  */
 export function parseInitOptions() {
+    // WU-1378: Description includes subcommand hint
     const opts = createWUParser({
         name: 'lumenflow-init',
-        description: 'Initialize LumenFlow in a project',
+        description: 'Initialize LumenFlow in a project\n\n' +
+            'Subcommands:\n' +
+            '  lumenflow commands    List all available CLI commands',
         options: Object.values(INIT_OPTIONS),
     });
     // WU-1171: --client takes precedence, --vendor is alias
@@ -131,6 +139,44 @@ const LUMENFLOW_DIR = '.lumenflow';
 const LUMENFLOW_AGENTS_DIR = `${LUMENFLOW_DIR}/agents`;
 const CLAUDE_DIR = '.claude';
 const CLAUDE_AGENTS_DIR = path.join(CLAUDE_DIR, 'agents');
+/**
+ * WU-1362: Check branch guard before writing tracked files
+ *
+ * Warns (but does not block) if:
+ * - On main branch AND
+ * - Not in a worktree directory AND
+ * - Git repository exists (has .git)
+ *
+ * This prevents accidental main branch pollution during init operations.
+ * Uses warning instead of error to allow initial project setup.
+ *
+ * @param targetDir - Directory where files will be written
+ * @param result - ScaffoldResult to add warnings to
+ */
+async function checkBranchGuard(targetDir, result) {
+    result.warnings = result.warnings ?? [];
+    // Only check if target is a git repository
+    const gitDir = path.join(targetDir, '.git');
+    if (!fs.existsSync(gitDir)) {
+        // Not a git repo - allow scaffold (initial setup)
+        return;
+    }
+    // Check if we're in a worktree (always allow)
+    if (isInWorktree({ cwd: targetDir })) {
+        return;
+    }
+    // Check if on main branch
+    try {
+        const onMain = await isMainBranch();
+        if (onMain) {
+            result.warnings.push('Running init on main branch in main checkout. ' +
+                'Consider using a worktree for changes to tracked files.');
+        }
+    }
+    catch {
+        // Git error (e.g., not initialized) - silently allow
+    }
+}
 /**
  * WU-1177: Detect IDE environment from environment variables
  * Auto-detects which AI coding assistant is running
@@ -279,9 +325,25 @@ const DEFAULT_LANE_DEFINITIONS = [
  * Generate YAML configuration with header comment
  * WU-1067: Supports --preset option for config-driven gates
  * WU-1307: Includes default lane definitions for onboarding
+ * WU-1364: Supports git config overrides (requireRemote)
+ * WU-1383: Adds enforcement hooks config for Claude client by default
  */
-function generateLumenflowConfigYaml(gatePreset) {
-    const header = `# LumenFlow Configuration\n# Generated by: lumenflow init\n# Customize paths based on your project structure\n\n`;
+function generateLumenflowConfigYaml(gatePreset, gitConfigOverride, client) {
+    // WU-1382: Add managed file header to prevent manual edits
+    const header = `# ============================================================================
+# LUMENFLOW MANAGED FILE - DO NOT EDIT MANUALLY
+# ============================================================================
+# Generated by: lumenflow init
+# Regenerate with: pnpm exec lumenflow init --force
+#
+# This file is managed by LumenFlow tooling. Manual edits may be overwritten.
+# To customize, use the CLI commands or edit the appropriate source templates.
+# ============================================================================
+
+# LumenFlow Configuration
+# Customize paths based on your project structure
+
+`;
     const config = getDefaultConfig();
     config.directories.agentsDir = LUMENFLOW_AGENTS_DIR;
     // WU-1067: Add gates.execution section with preset if specified
@@ -296,6 +358,28 @@ function generateLumenflowConfigYaml(gatePreset) {
     config.lanes = {
         definitions: DEFAULT_LANE_DEFINITIONS,
     };
+    // WU-1364: Add git config overrides (e.g., requireRemote: false for local-only)
+    if (gitConfigOverride) {
+        config.git = {
+            requireRemote: gitConfigOverride.requireRemote,
+        };
+    }
+    // WU-1383: Add enforcement hooks for Claude client by default
+    // This prevents agents from working on main and editing config files manually
+    if (client === 'claude') {
+        config.agents = {
+            clients: {
+                'claude-code': {
+                    enforcement: {
+                        hooks: true,
+                        block_outside_worktree: true,
+                        require_wu_for_edits: true,
+                        warn_on_stop_without_wu_done: true,
+                    },
+                },
+            },
+        };
+    }
     return header + yaml.stringify(config);
 }
 /**
@@ -314,7 +398,6 @@ function normalizeFrameworkName(framework) {
         .replace(/[^a-z0-9_-]+/g, '-')
         // Remove leading dashes and trailing dashes separately (explicit precedence)
         .replace(/^-+/, '')
-        // eslint-disable-next-line sonarjs/slow-regex -- Simple pattern, no catastrophic backtracking risk
         .replace(/-+$/, '');
     if (!slug) {
         throw new Error(`Invalid framework name: "${framework}"`);
@@ -400,12 +483,84 @@ This file provides universal guidance for all AI agents. Additional vendor-speci
 `;
 // Template for LUMENFLOW.md (main entry point)
 // WU-1309: Use <project-root> placeholder for portability
-const LUMENFLOW_MD_TEMPLATE = `# LumenFlow Workflow Guide\n\n**Last updated:** {{DATE}}\n\nLumenFlow is a vendor-agnostic workflow framework for AI-native software development.\n\n---\n\n## Critical Rule: ALWAYS Run wu:done\n\n**After completing work on a WU, you MUST run \`pnpm wu:done --id WU-XXXX\` from the main checkout.**\n\nThis is the single most forgotten step. Do NOT:\n- Write "To Complete: pnpm wu:done" and stop\n- Ask if you should run wu:done\n- Forget to run wu:done\n\n**DO**: Run \`pnpm wu:done --id WU-XXXX\` immediately after gates pass.\n\n---\n\n## Quick Start\n\n\`\`\`bash\n# 1. Create a WU\npnpm wu:create --id WU-XXXX --lane <Lane> --title "Title"\n\n# 2. Edit WU spec with acceptance criteria, then claim:\npnpm wu:claim --id WU-XXXX --lane <Lane>\ncd worktrees/<lane>-wu-xxxx\n\n# 3. Implement in worktree\n\n# 4. Run gates\npnpm gates --docs-only  # for docs changes\npnpm gates              # for code changes\n\n# 5. Complete (from main checkout)\ncd <project-root>\npnpm wu:done --id WU-XXXX\n\`\`\`\n\n---\n\n## Core Principles\n\n1. **TDD**: Failing test -> implementation -> passing test (>=90% coverage on new code)\n2. **Library-First**: Search existing libraries before custom code\n3. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings\n4. **Worktree Discipline**: After \`wu:claim\`, work ONLY in the worktree\n5. **Gates Before Done**: All gates must pass before \`wu:done\`\n6. **Do Not Bypass Hooks**: No \`--no-verify\`, fix issues properly\n7. **Always wu:done**: Complete every WU by running \`pnpm wu:done\`\n\n---\n\n## Documentation Structure\n\n### Core (Vendor-Agnostic)\n\n- **LUMENFLOW.md** - This file, main entry point\n- **.lumenflow/constraints.md** - Non-negotiable workflow constraints\n- **.lumenflow/agents/** - Agent instructions (vendor-agnostic)\n- **.lumenflow.config.yaml** - Workflow configuration\n\n### Optional Overlays\n\n- **CLAUDE.md + .claude/agents/** - Claude Code overlay (auto if Claude Code detected)\n- **{{DOCS_TASKS_PATH}}** - Task boards and WU storage (\`lumenflow init --full\`)\n- **{{DOCS_ONBOARDING_PATH}}** - Agent onboarding docs\n- **.lumenflow.framework.yaml** - Framework hint file (created with \`--framework\`)\n\n---\n\n## Worktree Discipline (IMMUTABLE LAW)\n\nAfter claiming a WU, you MUST work in its worktree:\n\n\`\`\`bash\n# 1. Claim creates worktree\npnpm wu:claim --id WU-XXX --lane <lane>\n\n# 2. IMMEDIATELY cd to worktree\ncd worktrees/<lane>-wu-xxx\n\n# 3. ALL work happens here\n\n# 4. Return to main ONLY to complete\ncd <project-root>\npnpm wu:done --id WU-XXX\n\`\`\`\n\n---\n\n## Definition of Done\n\n- Acceptance criteria satisfied\n- Gates green (\`pnpm gates\` or \`pnpm gates --docs-only\`)\n- WU YAML status = \`done\`\n- \`wu:done\` has been run\n\n---\n\n## Commands Reference\n\n| Command           | Description                         |\n| ----------------- | ----------------------------------- |\n| \`pnpm wu:create\` | Create new WU spec                  |\n| \`pnpm wu:claim\`  | Claim WU and create worktree        |\n| \`pnpm wu:done\`   | Complete WU (merge, stamp, cleanup) |\n| \`pnpm gates\`     | Run quality gates                   |\n\n---\n\n## Constraints\n\nSee [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 6 non-negotiable rules.\n\n---\n\n## Agent Onboarding\n\n- Start with **CLAUDE.md** if present (Claude Code overlay).\n- Add vendor-agnostic guidance in **.lumenflow/agents/**.\n- Check the onboarding docs in **{{DOCS_ONBOARDING_PATH}}** for detailed guidance.\n`;
+// WU-1364: Added initiative workflow section
+const LUMENFLOW_MD_TEMPLATE = `# LumenFlow Workflow Guide\n\n**Last updated:** {{DATE}}\n\nLumenFlow is a vendor-agnostic workflow framework for AI-native software development.\n\n---\n\n## Critical Rule: ALWAYS Run wu:done\n\n**After completing work on a WU, you MUST run \`pnpm wu:done --id WU-XXXX\` from the main checkout.**\n\nThis is the single most forgotten step. Do NOT:\n- Write "To Complete: pnpm wu:done" and stop\n- Ask if you should run wu:done\n- Forget to run wu:done\n\n**DO**: Run \`pnpm wu:done --id WU-XXXX\` immediately after gates pass.\n\n---\n\n## When to Use Initiatives\n\nUse **Initiatives** for multi-phase work spanning multiple WUs:\n\n- **Product visions**: "Build a task management app"\n- **Larger features**: Work requiring multiple WUs across lanes\n- **Complex projects**: Anything that needs phased delivery\n\n\`\`\`bash\n# Create an initiative for multi-phase work\npnpm initiative:create --id INIT-001 --title "Feature Name" \\\\\n  --description "..." --phase "Phase 1: MVP" --phase "Phase 2: Polish"\n\n# Add WUs to the initiative\npnpm initiative:add-wu --initiative INIT-001 --wu WU-XXX --phase 1\n\n# Track progress\npnpm initiative:status --id INIT-001\n\`\`\`\n\n**Skip initiatives** for: single-file bug fixes, small docs updates, isolated refactoring.\n\n---\n\n## Quick Start\n\n\`\`\`bash\n# 1. Create a WU\npnpm wu:create --id WU-XXXX --lane <Lane> --title "Title"\n\n# 2. Edit WU spec with acceptance criteria, then claim:\npnpm wu:claim --id WU-XXXX --lane <Lane>\ncd worktrees/<lane>-wu-xxxx\n\n# 3. Implement in worktree\n\n# 4. Run gates\npnpm gates --docs-only  # for docs changes\npnpm gates              # for code changes\n\n# 5. Complete (from main checkout)\ncd <project-root>\npnpm wu:done --id WU-XXXX\n\`\`\`\n\n---\n\n## Core Principles\n\n1. **TDD**: Failing test -> implementation -> passing test (>=90% coverage on new code)\n2. **Library-First**: Search existing libraries before custom code\n3. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings\n4. **Worktree Discipline**: After \`wu:claim\`, work ONLY in the worktree\n5. **Gates Before Done**: All gates must pass before \`wu:done\`\n6. **Do Not Bypass Hooks**: No \`--no-verify\`, fix issues properly\n7. **Always wu:done**: Complete every WU by running \`pnpm wu:done\`\n\n---\n\n## Documentation Structure\n\n### Core (Vendor-Agnostic)\n\n- **LUMENFLOW.md** - This file, main entry point\n- **.lumenflow/constraints.md** - Non-negotiable workflow constraints\n- **.lumenflow/agents/** - Agent instructions (vendor-agnostic)\n- **.lumenflow.config.yaml** - Workflow configuration\n\n### Optional Overlays\n\n- **CLAUDE.md + .claude/agents/** - Claude Code overlay (auto if Claude Code detected)\n- **{{DOCS_TASKS_PATH}}** - Task boards and WU storage (\`lumenflow init --full\`)\n- **{{DOCS_ONBOARDING_PATH}}** - Agent onboarding docs\n- **.lumenflow.framework.yaml** - Framework hint file (created with \`--framework\`)\n\n---\n\n## Worktree Discipline (IMMUTABLE LAW)\n\nAfter claiming a WU, you MUST work in its worktree:\n\n\`\`\`bash\n# 1. Claim creates worktree\npnpm wu:claim --id WU-XXX --lane <lane>\n\n# 2. IMMEDIATELY cd to worktree\ncd worktrees/<lane>-wu-xxx\n\n# 3. ALL work happens here\n\n# 4. Return to main ONLY to complete\ncd <project-root>\npnpm wu:done --id WU-XXX\n\`\`\`\n\n---\n\n## Definition of Done\n\n- Acceptance criteria satisfied\n- Gates green (\`pnpm gates\` or \`pnpm gates --docs-only\`)\n- WU YAML status = \`done\`\n- \`wu:done\` has been run\n\n---\n\n## Commands Reference\n\n| Command           | Description                         |\n| ----------------- | ----------------------------------- |\n| \`pnpm wu:create\` | Create new WU spec                  |\n| \`pnpm wu:claim\`  | Claim WU and create worktree        |\n| \`pnpm wu:done\`   | Complete WU (merge, stamp, cleanup) |\n| \`pnpm gates\`     | Run quality gates                   |\n| \`pnpm initiative:create\` | Create multi-phase initiative |\n| \`pnpm initiative:status\` | View initiative progress |\n\n---\n\n## Constraints\n\nSee [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 6 non-negotiable rules.\n\n---\n\n## Agent Onboarding\n\n- Start with **CLAUDE.md** if present (Claude Code overlay).\n- Add vendor-agnostic guidance in **.lumenflow/agents/**.\n- Check the onboarding docs in **{{DOCS_ONBOARDING_PATH}}** for detailed guidance.\n`;
 // Template for .lumenflow/constraints.md
 const CONSTRAINTS_MD_TEMPLATE = `# LumenFlow Constraints Capsule\n\n**Version:** 1.0\n**Last updated:** {{DATE}}\n\n## The 6 Non-Negotiable Constraints\n\n### 1. Worktree Discipline and Git Safety\nWork only in worktrees, treat main as read-only, never run destructive git commands on main.\n\n### 2. WUs Are Specs, Not Code\nRespect code_paths boundaries, no feature creep, no code blocks in WU YAML files.\n\n### 3. Docs-Only vs Code WUs\nDocumentation WUs use \`--docs-only\` gates, code WUs run full gates.\n\n### 4. LLM-First, Zero-Fallback Inference\nUse LLMs for semantic tasks, fall back to safe defaults (never regex/keywords).\n\n### 5. Gates and Skip-Gates\nComplete via \`pnpm wu:done\`; skip-gates only for pre-existing failures with \`--reason\` and \`--fix-wu\`.\n\n### 6. Safety and Governance\nRespect privacy rules, approved sources, security policies; when uncertain, choose safer path.\n\n---\n\n## Mini Audit Checklist\n\nBefore running \`wu:done\`, verify:\n\n- [ ] Working in worktree (not main)\n- [ ] Only modified files in \`code_paths\`\n- [ ] Gates pass\n- [ ] No forbidden git commands used\n- [ ] Acceptance criteria satisfied\n\n---\n\n## Escalation Triggers\n\nStop and ask a human when:\n- Same error repeats 3 times\n- Auth or permissions changes required\n- PII/PHI/safety issues discovered\n- Cloud spend or secrets involved\n`;
 // Template for root CLAUDE.md
 // WU-1309: Use <project-root> placeholder for portability
-const CLAUDE_MD_TEMPLATE = `# Claude Code Instructions\n\n**Last updated:** {{DATE}}\n\nThis project uses LumenFlow workflow. For workflow documentation, see [LUMENFLOW.md](LUMENFLOW.md).\n\n---\n\n## Quick Start\n\n\`\`\`bash\n# 1. Claim a WU\npnpm wu:claim --id WU-XXXX --lane <Lane>\ncd worktrees/<lane>-wu-xxxx\n\n# 2. Work in worktree, run gates\npnpm gates\n\n# 3. Complete (ALWAYS run this!)\ncd <project-root>\npnpm wu:done --id WU-XXXX\n\`\`\`\n\n---\n\n## Critical: Always wu:done\n\nAfter completing work, ALWAYS run \`pnpm wu:done --id WU-XXXX\`.\n\nSee [LUMENFLOW.md](LUMENFLOW.md) for full workflow documentation.\n`;
+// WU-1382: Expanded with CLI commands table and warning about manual YAML editing
+const CLAUDE_MD_TEMPLATE = `# Claude Code Instructions
+
+**Last updated:** {{DATE}}
+
+This project uses LumenFlow workflow. For workflow documentation, see [LUMENFLOW.md](LUMENFLOW.md).
+
+---
+
+## Quick Start
+
+\`\`\`bash
+# 1. Claim a WU
+pnpm wu:claim --id WU-XXXX --lane <Lane>
+cd worktrees/<lane>-wu-xxxx
+
+# 2. Work in worktree, run gates
+pnpm gates
+
+# 3. Complete (ALWAYS run this!)
+cd <project-root>
+pnpm wu:done --id WU-XXXX
+\`\`\`
+
+---
+
+## CLI Commands Reference
+
+### WU Lifecycle
+
+| Command                                   | Description                              |
+| ----------------------------------------- | ---------------------------------------- |
+| \`pnpm wu:status --id WU-XXX\`              | Show WU status, location, valid commands |
+| \`pnpm wu:claim --id WU-XXX --lane <Lane>\` | Claim WU and create worktree             |
+| \`pnpm wu:prep --id WU-XXX\`                | Run gates in worktree, prep for wu:done  |
+| \`pnpm wu:done --id WU-XXX\`                | Complete WU (from main checkout)         |
+| \`pnpm wu:block --id WU-XXX --reason "..."\`| Block WU with reason                     |
+| \`pnpm wu:unblock --id WU-XXX\`             | Unblock WU                               |
+
+### Gates & Quality
+
+| Command                  | Description                |
+| ------------------------ | -------------------------- |
+| \`pnpm gates\`             | Run all quality gates      |
+| \`pnpm gates --docs-only\` | Run gates for docs changes |
+| \`pnpm format\`            | Format all files           |
+| \`pnpm lint\`              | Run linter                 |
+| \`pnpm typecheck\`         | Run TypeScript check       |
+| \`pnpm test\`              | Run tests                  |
+
+---
+
+## Critical: Always wu:done
+
+After completing work, ALWAYS run \`pnpm wu:done --id WU-XXXX\` from the main checkout.
+
+See [LUMENFLOW.md](LUMENFLOW.md) for full workflow documentation.
+
+---
+
+## Warning: Do Not Edit WU YAML Files Manually
+
+**Never manually edit WU YAML files** in \`docs/.../tasks/wu/WU-XXX.yaml\`.
+
+Use CLI commands instead:
+
+- \`pnpm wu:create ...\` to create new WUs
+- \`pnpm wu:edit --id WU-XXX ...\` to modify WU fields
+- \`pnpm wu:claim\` / \`wu:block\` / \`wu:done\` for status changes
+
+Manual edits bypass validation and can corrupt workflow state.
+`;
 // Template for .claude/settings.json
 const CLAUDE_SETTINGS_TEMPLATE = `{
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
@@ -1046,17 +1201,84 @@ Choose the safer path:
 - Ask rather than assume
 `;
 // WU-1307: Lane inference configuration template (hierarchical Parent→Sublane format)
+// WU-1364: Added Core and Feature as parent lanes for intuitive naming
+// WU-1382: Added managed file header to prevent manual edits
 // This format is required by lane-inference.ts and lane-checker.ts
-const LANE_INFERENCE_TEMPLATE = `# Lane Inference Configuration
+const LANE_INFERENCE_TEMPLATE = `# ============================================================================
+# LUMENFLOW MANAGED FILE - DO NOT EDIT MANUALLY
+# ============================================================================
 # Generated by: lumenflow init
+# Regenerate with: pnpm exec lumenflow init --force
+#
+# This file is managed by LumenFlow tooling. Manual edits may be overwritten.
+# To customize lanes, use: pnpm lane:suggest --output .lumenflow.lane-inference.yaml
+# ============================================================================
+
+# Lane Inference Configuration
 #
 # Hierarchical format: Parent -> Sublane -> { code_paths, keywords }
 # This format is required by lane-inference.ts for proper sub-lane suggestion.
+#
+# Common parent lanes: Core, Feature, Framework, Experience, Operations, Content
+
+# Core Lane: Platform foundations, shared libraries, base infrastructure
+Core:
+  Platform:
+    description: 'Core platform: shared utilities, base infrastructure, common libraries'
+    code_paths:
+      - 'packages/**/core/**'
+      - 'src/core/**'
+      - 'src/lib/**'
+      - 'lib/**'
+    keywords:
+      - 'platform'
+      - 'core'
+      - 'infrastructure'
+      - 'foundation'
+
+  Library:
+    description: 'Shared libraries and utilities'
+    code_paths:
+      - 'packages/**/lib/**'
+      - 'src/utils/**'
+      - 'src/helpers/**'
+    keywords:
+      - 'library'
+      - 'utility'
+      - 'helper'
+      - 'shared'
+
+# Feature Lane: Product features and user-facing functionality
+Feature:
+  Backend:
+    description: 'Backend features: APIs, services, business logic'
+    code_paths:
+      - 'src/api/**'
+      - 'src/services/**'
+      - 'packages/**/api/**'
+    keywords:
+      - 'api'
+      - 'service'
+      - 'backend'
+      - 'business logic'
+
+  Frontend:
+    description: 'Frontend features: UI, components, pages'
+    code_paths:
+      - 'src/components/**'
+      - 'src/pages/**'
+      - 'src/app/**'
+      - 'apps/web/**'
+    keywords:
+      - 'frontend'
+      - 'ui'
+      - 'component'
+      - 'page'
 
-# Framework Lane: Core packages and libraries
+# Framework Lane: Framework-specific code and tooling
 Framework:
   Core:
-    description: 'Core library: business logic, domain models, utilities'
+    description: 'Core framework: business logic, domain models, utilities'
     code_paths:
       - 'packages/**/core/**'
       - 'src/core/**'
@@ -1151,6 +1373,7 @@ Content:
 {{FRAMEWORK_LANES}}
 `;
 // WU-1300: Starting prompt template for agent onboarding
+// WU-1364: Added "When Starting From Product Vision" section for initiative-first workflow
 const STARTING_PROMPT_TEMPLATE = `# Starting Prompt for LumenFlow Agents
 
 **Last updated:** {{DATE}}
@@ -1159,6 +1382,48 @@ This document provides the initial context for AI agents working on this project
 
 ---
 
+## When Starting From Product Vision
+
+If you are starting a new project or feature from a product vision (e.g., "Build a task management app"), **do NOT create standalone WUs immediately**. Instead, follow the initiative-first workflow:
+
+### 4-Step Initiative Workflow
+
+1. **Create an Initiative**: Capture the vision as an initiative
+   \`\`\`bash
+   pnpm initiative:create --id INIT-001 --title "Task Management App" \\
+     --description "Build a task management application with..." \\
+     --phase "Phase 1: Core MVP" --phase "Phase 2: Collaboration"
+   \`\`\`
+
+2. **Define Phases**: Break the vision into logical phases (MVP, iteration, polish)
+
+3. **Create WUs under the Initiative**: Each WU belongs to a phase
+   \`\`\`bash
+   pnpm wu:create --lane "Core: Platform" --title "Add task model" \\
+     --description "..." --acceptance "..." --code-paths "..." \\
+     && pnpm initiative:add-wu --initiative INIT-001 --wu WU-XXX --phase 1
+   \`\`\`
+
+4. **Track Progress**: Use \`pnpm initiative:status --id INIT-001\` to see overall progress
+
+### Why Initiatives Matter
+
+- **Avoid orphan WUs**: Without initiative structure, agents create disconnected WUs that lack coherent scope
+- **Better coordination**: Phases enable parallel work across lanes
+- **Clear completion criteria**: The initiative tracks when all phases are done
+- **Visibility**: Stakeholders can see multi-phase progress
+
+### When to Skip Initiatives
+
+Only skip initiatives for:
+- Single-file bug fixes
+- Small documentation updates
+- Isolated refactoring tasks
+
+If work spans multiple WUs or multiple days, create an initiative first.
+
+---
+
 ## Step 1: Read Core Documentation
 
 Before starting any work, read these documents in order:
@@ -1197,6 +1462,8 @@ LumenFlow uses Work Units (WUs) to track all changes:
 | \`pnpm gates\` | Run quality gates |
 | \`pnpm wu:done --id WU-XXX\` | Complete WU |
 | \`pnpm wu:status --id WU-XXX\` | Check WU status |
+| \`pnpm initiative:create ...\` | Create a new initiative |
+| \`pnpm initiative:status --id INIT-XXX\` | Check initiative progress |
 
 ---
 
@@ -1213,6 +1480,7 @@ LumenFlow uses Work Units (WUs) to track all changes:
 - [quick-ref-commands.md](quick-ref-commands.md) - Complete command reference
 - [agent-safety-card.md](agent-safety-card.md) - Safety guidelines
 - [wu-create-checklist.md](wu-create-checklist.md) - WU creation guide
+- [wu-sizing-guide.md](wu-sizing-guide.md) - WU complexity and context management
 `;
 const WU_CREATE_CHECKLIST_TEMPLATE = `# WU Creation Checklist
 
@@ -1601,6 +1869,96 @@ This detects:
 - Overlapping code paths between lanes
 - Code files not covered by any lane
 `;
+// WU-1385: WU sizing guide template for agent onboarding
+const WU_SIZING_GUIDE_TEMPLATE = `# Work Unit Sizing & Strategy Guide
+
+**Last updated:** {{DATE}}
+
+**Purpose:** Decision framework for agents to determine execution strategy based on task complexity.
+
+**Status:** Active — Thresholds are **mandatory limits**, not guidelines.
+
+---
+
+## Complexity Assessment Matrix
+
+Before claiming a WU, estimate its "weight" using these heuristics.
+
+| Complexity    | Files | Tool Calls | Context Budget | Strategy                                     |
+| :------------ | :---- | :--------- | :------------- | :------------------------------------------- |
+| **Simple**    | <20   | <50        | <30%           | **Single Session** (Tier 2 Context)          |
+| **Medium**    | 20-50 | 50-100     | 30-50%         | **Checkpoint-Resume** (Standard Handoff)     |
+| **Complex**   | 50+   | 100+       | >50%           | **Orchestrator-Worker** OR **Decomposition** |
+| **Oversized** | 100+  | 200+       | —              | **MUST Split** (See Patterns below)          |
+
+**These thresholds are mandatory.** Exceeding them leads to context exhaustion and rule loss. Agents operate in context windows and tool calls, not clock time.
+
+---
+
+## Context Safety Triggers
+
+If you hit ANY of these triggers during a session, you MUST checkpoint and spawn fresh:
+
+- **Token Limit:** Context usage hits **50% (Warning)** or **80% (Critical)**.
+- **Tool Volume:** **50+ tool calls** in current session.
+- **File Volume:** **20+ files** modified in \`git status\`.
+- **Session Staleness:** Repeated redundant queries or forgotten context.
+
+---
+
+## Spawn Fresh, Don't Continue
+
+**When approaching context limits, spawn a fresh agent instead of continuing after compaction.**
+
+Context compaction causes agents to lose critical rules. The disciplined approach:
+
+1. Checkpoint your progress: \`pnpm mem:checkpoint --wu WU-XXX\`
+2. Commit and push work
+3. Generate fresh agent prompt: \`pnpm wu:spawn --id WU-XXX\`
+4. EXIT current session (do NOT continue after compaction)
+
+---
+
+## Splitting Patterns
+
+When a WU is Oversized or Complex, split it using approved patterns:
+
+- **Tracer Bullet**: WU-1 proves skeleton works, WU-2 implements real logic
+- **Layer Split**: WU-1 for ports/application, WU-2 for infrastructure
+- **UI/Logic Split**: WU-1 for backend, WU-2 for frontend
+- **Feature Flag**: WU-1 behind flag, WU-2 removes flag
+
+---
+
+## Quick Reference
+
+| Scenario                            | Strategy            | Action                                       |
+| :---------------------------------- | :------------------ | :------------------------------------------- |
+| Bug fix, single file, <20 calls     | Simple              | Claim, fix, commit, \`wu:done\`              |
+| Feature 50-100 calls, clear phases  | Checkpoint-Resume   | Phase 1 → checkpoint → Phase 2 → done        |
+| Multi-domain, must land atomically  | Orchestrator-Worker | Main agent coordinates, spawns sub-agents    |
+| Large refactor 100+ calls           | Feature Flag Split  | WU-A: New behind flag → WU-B: Remove flag    |
+
+---
+
+## Documentation-Only Exception
+
+Documentation WUs (\`type: documentation\`) have relaxed file count thresholds:
+
+| Complexity | Files (docs) | Tool Calls | Strategy          |
+| :--------- | :----------- | :--------- | :---------------- |
+| **Simple** | <40          | <50        | Single Session    |
+| **Medium** | 40-80        | 50-100     | Checkpoint-Resume |
+
+**Applies when ALL true:**
+- WU \`type: documentation\`
+- Only modifies: \`docs/**\`, \`*.md\`
+- Does NOT touch code paths
+
+---
+
+For complete sizing guidance, see the canonical [wu-sizing-guide.md](https://lumenflow.dev/reference/wu-sizing-guide/) documentation.
+`;
 // WU-1083: Claude skills templates
 const WU_LIFECYCLE_SKILL_TEMPLATE = `---
 name: wu-lifecycle
@@ -1835,6 +2193,85 @@ function getFileMode(options) {
     }
     return 'skip';
 }
+/**
+ * WU-1364: Check if directory is a git repository
+ */
+function isGitRepo(targetDir) {
+    try {
+        execFileSync('git', ['rev-parse', '--git-dir'], {
+            cwd: targetDir,
+            stdio: 'pipe',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * WU-1364: Check if git repo has any commits
+ */
+function hasGitCommits(targetDir) {
+    try {
+        execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: targetDir,
+            stdio: 'pipe',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * WU-1364: Check if git repo has an origin remote
+ */
+function hasOriginRemote(targetDir) {
+    try {
+        const result = execFileSync('git', ['remote', 'get-url', 'origin'], {
+            cwd: targetDir,
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        });
+        return result.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * WU-1364: Create initial commit if git repo has no commits
+ */
+function createInitialCommitIfNeeded(targetDir) {
+    if (!isGitRepo(targetDir) || hasGitCommits(targetDir)) {
+        return false;
+    }
+    try {
+        // Stage all files
+        execFileSync('git', ['add', '.'], { cwd: targetDir, stdio: 'pipe' });
+        // Create initial commit
+        execFileSync('git', ['commit', '-m', 'chore: initialize LumenFlow project'], {
+            cwd: targetDir,
+            stdio: 'pipe',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function detectGitStateConfig(targetDir) {
+    // If not a git repo, default to local-only mode for safety
+    if (!isGitRepo(targetDir)) {
+        return { requireRemote: false };
+    }
+    // If git repo but no origin remote, set requireRemote: false
+    if (!hasOriginRemote(targetDir)) {
+        return { requireRemote: false };
+    }
+    // Has origin remote - use default (requireRemote: true)
+    return null;
+}
 /**
  * WU-1171: Get templates directory path
  */
@@ -1862,6 +2299,7 @@ function loadTemplate(templatePath) {
 /**
  * Scaffold a new LumenFlow project
  * WU-1171: Added AGENTS.md, --merge mode, updated vendor/client handling
+ * WU-1362: Added branch guard to prevent main branch pollution
  */
 export async function scaffoldProject(targetDir, options) {
     const result = {
@@ -1870,9 +2308,12 @@ export async function scaffoldProject(targetDir, options) {
         merged: [],
         warnings: [],
     };
+    // WU-1362: Check branch before writing tracked files
+    // Only block if we're on main branch AND not in a worktree
+    // This allows scaffold to run in worktrees and during initial setup
+    await checkBranchGuard(targetDir, result);
     const defaultClient = options.defaultClient ?? detectDefaultClient();
     // WU-1171: Use resolveClientType with both client and vendor (vendor is deprecated but kept for backwards compat)
-    // eslint-disable-next-line sonarjs/deprecation -- Intentional backwards compatibility
     const client = resolveClientType(options.client, options.vendor, defaultClient);
     const fileMode = getFileMode(options);
     // Ensure target directory exists
@@ -1882,6 +2323,8 @@ export async function scaffoldProject(targetDir, options) {
     // WU-1309: Detect or use specified docs structure
     const docsStructure = options.docsStructure ?? detectDocsStructure(targetDir);
     const docsPaths = getDocsPath(docsStructure);
+    // WU-1364: Detect git state for config generation
+    const gitConfigOverride = detectGitStateConfig(targetDir);
     const tokenDefaults = {
         DATE: getCurrentDate(),
         PROJECT_ROOT: '<project-root>', // WU-1309: Use portable placeholder
@@ -1891,8 +2334,18 @@ export async function scaffoldProject(targetDir, options) {
         DOCS_ONBOARDING_PATH: docsPaths.onboarding,
     };
     // Create .lumenflow.config.yaml (WU-1067: includes gate preset if specified)
+    // WU-1364: Includes git config overrides (e.g., requireRemote: false for local-only)
+    // WU-1383: Includes enforcement hooks for Claude client
     // Note: Config files don't use merge mode (always skip or force)
-    await createFile(path.join(targetDir, CONFIG_FILE_NAME), generateLumenflowConfigYaml(options.gatePreset), options.force ? 'force' : 'skip', result, targetDir);
+    const configPath = path.join(targetDir, CONFIG_FILE_NAME);
+    // WU-1383: Warn if config already exists to discourage manual editing
+    if (fs.existsSync(configPath) && !options.force) {
+        result.warnings = result.warnings ?? [];
+        result.warnings.push(`${CONFIG_FILE_NAME} already exists. ` +
+            'To modify configuration, use CLI commands (e.g., pnpm lumenflow:init --force) ' +
+            'instead of manual editing.');
+    }
+    await createFile(configPath, generateLumenflowConfigYaml(options.gatePreset, gitConfigOverride, client), options.force ? 'force' : 'skip', result, targetDir);
     // WU-1171: Create AGENTS.md (universal entry point for all agents)
     try {
         const agentsTemplate = loadTemplate('core/AGENTS.md.template');
@@ -1925,6 +2378,12 @@ export async function scaffoldProject(targetDir, options) {
     if (options.full) {
         await injectPackageJsonScripts(targetDir, options, result);
     }
+    // WU-1364: Create initial commit if git repo has no commits
+    // This must be done after all files are created
+    const createdInitialCommit = createInitialCommitIfNeeded(targetDir);
+    if (createdInitialCommit) {
+        result.created.push('Initial git commit');
+    }
     return result;
 }
 /**
@@ -2140,6 +2599,8 @@ async function scaffoldAgentOnboardingDocs(targetDir, options, result, tokens) {
     await createFile(path.join(onboardingDir, 'troubleshooting-wu-done.md'), processTemplate(TROUBLESHOOTING_WU_DONE_TEMPLATE, tokens), options.force, result, targetDir);
     await createFile(path.join(onboardingDir, 'agent-safety-card.md'), processTemplate(AGENT_SAFETY_CARD_TEMPLATE, tokens), options.force, result, targetDir);
     await createFile(path.join(onboardingDir, 'wu-create-checklist.md'), processTemplate(WU_CREATE_CHECKLIST_TEMPLATE, tokens), options.force, result, targetDir);
+    // WU-1385: Add wu-sizing-guide.md to onboarding docs
+    await createFile(path.join(onboardingDir, 'wu-sizing-guide.md'), processTemplate(WU_SIZING_GUIDE_TEMPLATE, tokens), options.force, result, targetDir);
 }
 /**
  * WU-1083: Scaffold Claude skills
@@ -2317,9 +2778,19 @@ function writeNewFile(filePath, content, result, relativePath) {
  * CLI entry point
  * WU-1085: Updated to use parseInitOptions for proper --help support
  * WU-1171: Added --merge and --client support
+ * WU-1378: Added subcommand routing for 'commands' subcommand
  */
 export async function main() {
-    /* eslint-disable no-console -- CLI tool requires console output for user feedback */
+    // WU-1378: Check for subcommands before parsing init options
+    const subcommand = process.argv[2];
+    if (subcommand === 'commands') {
+        // Route to commands subcommand
+        const { main: commandsMain } = await import('./commands.js');
+        // Remove 'commands' from argv so the subcommand parser sees clean args
+        process.argv.splice(2, 1);
+        await commandsMain();
+        return;
+    }
     const opts = parseInitOptions();
     const targetDir = process.cwd();
     console.log('[lumenflow init] Scaffolding LumenFlow project...');
@@ -2362,13 +2833,29 @@ export async function main() {
         console.log('\nWarnings:');
         result.warnings.forEach((w) => console.log(`  ⚠ ${w}`));
     }
+    // WU-1386: Run doctor auto-check (non-blocking)
+    // This provides feedback on workflow health without failing init
+    try {
+        const doctorResult = await runDoctorForInit(targetDir);
+        if (doctorResult.output) {
+            console.log('');
+            console.log(doctorResult.output);
+        }
+    }
+    catch {
+        // Doctor check is non-blocking - if it fails, continue with init
+    }
     // WU-1359: Show complete lifecycle with auto-ID (no --id flag required)
+    // WU-1364: Added initiative-first guidance for product visions
     console.log('\n[lumenflow init] Done! Next steps:');
     console.log('  1. Review AGENTS.md and LUMENFLOW.md for workflow documentation');
     console.log(`  2. Edit ${CONFIG_FILE_NAME} to match your project structure`);
-    console.log('  3. Start your first WU:');
     console.log('');
-    console.log('     # Create (auto-generates ID):');
+    console.log('  For a product vision (multi-phase work):');
+    console.log('     pnpm initiative:create --id INIT-001 --title "Project Name" \\');
+    console.log('       --phase "Phase 1: MVP" --phase "Phase 2: Polish"');
+    console.log('');
+    console.log('  For a single WU:');
     console.log('     pnpm wu:create --lane <lane> --title "First WU" \\');
     console.log('       --description "Context: ... Problem: ... Solution: ..." \\');
     console.log('       --acceptance "Criterion 1" --code-paths "src/..." --exposure backend-only');
@@ -2376,14 +2863,12 @@ export async function main() {
     console.log('     # Or for rapid prototyping (minimal validation):');
     console.log('     pnpm wu:proto --lane <lane> --title "Quick experiment"');
     console.log('');
-    console.log('  4. Full lifecycle: wu:create -> wu:claim -> wu:prep -> wu:done');
-    /* eslint-enable no-console */
+    console.log('  Full lifecycle: wu:create -> wu:claim -> wu:prep -> wu:done');
 }
 // WU-1297: Use import.meta.main instead of exporting main() without calling it
 // This ensures main() runs when the script is executed as a CLI entry point
 if (import.meta.main) {
     main().catch((err) => {
-        // eslint-disable-next-line no-console -- CLI error output
         console.error('[lumenflow init] Error:', err instanceof Error ? err.message : String(err));
         process.exit(1);
     });