@lumenflow/cli 2.8.0 → 2.9.0

package/dist/init.js

@@ -19,6 +19,8 @@ import { GATE_PRESETS } from '@lumenflow/core/dist/gates-config.js';
 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
@@ -70,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
@@ -321,9 +326,24 @@ const DEFAULT_LANE_DEFINITIONS = [
  * 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, gitConfigOverride) {
-    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
@@ -344,6 +364,22 @@ function generateLumenflowConfigYaml(gatePreset, gitConfigOverride) {
             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);
 }
 /**
@@ -453,7 +489,78 @@ const LUMENFLOW_MD_TEMPLATE = `# LumenFlow Workflow Guide\n\n**Last updated:** {
 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",
@@ -1095,9 +1202,19 @@ Choose the safer path:
 `;
 // 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.
@@ -1363,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
 
@@ -1751,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
@@ -2127,8 +2335,17 @@ export async function scaffoldProject(targetDir, options) {
     };
     // 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, gitConfigOverride), 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');
@@ -2382,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
@@ -2559,8 +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() {
+    // 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...');
@@ -2603,6 +2833,18 @@ 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:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -99,6 +99,7 @@
     "lumenflow-init": "./dist/init.js",
     "lumenflow": "./dist/init.js",
     "lumenflow-doctor": "./dist/doctor.js",
+    "lumenflow-commands": "./dist/commands.js",
     "lumenflow-release": "./dist/release.js",
     "lumenflow-docs-sync": "./dist/docs-sync.js",
     "lumenflow-sync-templates": "./dist/sync-templates.js",
@@ -150,11 +151,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "2.8.0",
-    "@lumenflow/memory": "2.8.0",
-    "@lumenflow/metrics": "2.8.0",
-    "@lumenflow/agent": "2.8.0",
-    "@lumenflow/initiatives": "2.8.0"
+    "@lumenflow/core": "2.9.0",
+    "@lumenflow/metrics": "2.9.0",
+    "@lumenflow/memory": "2.9.0",
+    "@lumenflow/agent": "2.9.0",
+    "@lumenflow/initiatives": "2.9.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",