@lumenflow/cli 2.5.0 → 2.5.1

package/dist/sync-templates.js

@@ -8,9 +8,16 @@
  * - Claude skills -> templates/vendors/claude/.claude/skills/
  * - Core docs (LUMENFLOW.md, constraints.md) -> templates/core/
  */
+/* eslint-disable no-console -- CLI tool requires console output */
+/* eslint-disable security/detect-non-literal-fs-filename -- CLI tool syncs templates from known paths */
+/* eslint-disable security/detect-non-literal-regexp -- Dynamic date pattern for template substitution */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { createWUParser } from '@lumenflow/core';
+// Directory name constants to avoid duplicate strings
+const LUMENFLOW_DIR = '.lumenflow';
+const CLAUDE_DIR = '.claude';
+const SKILLS_DIR = 'skills';
 // Template variable patterns
 const DATE_PATTERN = /\d{4}-\d{2}-\d{2}/g;
 /**
@@ -29,6 +36,12 @@ const SYNC_TEMPLATES_OPTIONS = {
         description: 'Show detailed output',
         default: false,
     },
+    checkDrift: {
+        name: 'check-drift',
+        flags: '--check-drift',
+        description: 'Check for template drift without syncing (CI mode)',
+        default: false,
+    },
 };
 /**
  * Parse sync-templates command options
@@ -42,6 +55,7 @@ export function parseSyncTemplatesOptions() {
     return {
         dryRun: opts['dry-run'] ?? false,
         verbose: opts.verbose ?? false,
+        checkDrift: opts['check-drift'] ?? false,
     };
 }
 /**
@@ -119,8 +133,8 @@ export async function syncOnboardingDocs(projectRoot, dryRun = false) {
  */
 export async function syncSkillsToTemplates(projectRoot, dryRun = false) {
     const result = { synced: [], errors: [] };
-    const sourceDir = path.join(projectRoot, '.claude', 'skills');
-    const targetDir = path.join(getTemplatesDir(projectRoot), 'vendors', 'claude', '.claude', 'skills');
+    const sourceDir = path.join(projectRoot, CLAUDE_DIR, SKILLS_DIR);
+    const targetDir = path.join(getTemplatesDir(projectRoot), 'vendors', 'claude', CLAUDE_DIR, SKILLS_DIR);
     if (!fs.existsSync(sourceDir)) {
         result.errors.push(`Skills source directory not found: ${sourceDir}`);
         return result;
@@ -153,8 +167,8 @@ export async function syncCoreDocs(projectRoot, dryRun = false) {
     const lumenflowTarget = path.join(templatesDir, 'core', 'LUMENFLOW.md.template');
     syncFile(lumenflowSource, lumenflowTarget, projectRoot, result, dryRun);
     // Sync constraints.md
-    const constraintsSource = path.join(projectRoot, '.lumenflow', 'constraints.md');
-    const constraintsTarget = path.join(templatesDir, 'core', '.lumenflow', 'constraints.md.template');
+    const constraintsSource = path.join(projectRoot, LUMENFLOW_DIR, 'constraints.md');
+    const constraintsTarget = path.join(templatesDir, 'core', LUMENFLOW_DIR, 'constraints.md.template');
     syncFile(constraintsSource, constraintsTarget, projectRoot, result, dryRun);
     return result;
 }
@@ -167,12 +181,130 @@ export async function syncTemplates(projectRoot, dryRun = false) {
     const core = await syncCoreDocs(projectRoot, dryRun);
     return { onboarding, skills, core };
 }
+/**
+ * Compare source file content with template content (ignoring date placeholders)
+ */
+function compareContent(sourceContent, templateContent, projectRoot) {
+    // Convert source to template format for comparison
+    const convertedSource = convertToTemplate(sourceContent, projectRoot);
+    return convertedSource === templateContent;
+}
+/**
+ * Check if a single template file is in sync with its source
+ */
+function checkFileDrift(sourcePath, templatePath, projectRoot) {
+    const relativePath = path.relative(projectRoot, templatePath);
+    if (!fs.existsSync(sourcePath)) {
+        return { isDrifting: false, relativePath }; // Source doesn't exist, can't drift
+    }
+    if (!fs.existsSync(templatePath)) {
+        return { isDrifting: true, relativePath }; // Template missing, definitely drifting
+    }
+    const sourceContent = fs.readFileSync(sourcePath, 'utf-8');
+    const templateContent = fs.readFileSync(templatePath, 'utf-8');
+    const isDrifting = !compareContent(sourceContent, templateContent, projectRoot);
+    return { isDrifting, relativePath };
+}
+/**
+ * Check for template drift - compares source docs with templates (WU-1353)
+ *
+ * This function compares source documents with their template counterparts
+ * to detect if templates have drifted out of sync. Used by CI to warn
+ * when templates need to be re-synced.
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Multi-category drift check requires nested iteration
+export async function checkTemplateDrift(projectRoot) {
+    const driftingFiles = [];
+    const checkedFiles = [];
+    const templatesDir = getTemplatesDir(projectRoot);
+    // Check core docs
+    const coreChecks = [
+        {
+            source: path.join(projectRoot, 'LUMENFLOW.md'),
+            template: path.join(templatesDir, 'core', 'LUMENFLOW.md.template'),
+        },
+        {
+            source: path.join(projectRoot, LUMENFLOW_DIR, 'constraints.md'),
+            template: path.join(templatesDir, 'core', LUMENFLOW_DIR, 'constraints.md.template'),
+        },
+    ];
+    for (const check of coreChecks) {
+        const result = checkFileDrift(check.source, check.template, projectRoot);
+        checkedFiles.push(result.relativePath);
+        if (result.isDrifting) {
+            driftingFiles.push(result.relativePath);
+        }
+    }
+    // Check onboarding docs
+    const onboardingSourceDir = path.join(projectRoot, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+    const onboardingTargetDir = path.join(templatesDir, 'core', 'ai', 'onboarding');
+    if (fs.existsSync(onboardingSourceDir)) {
+        const files = fs.readdirSync(onboardingSourceDir).filter((f) => f.endsWith('.md'));
+        for (const file of files) {
+            const sourcePath = path.join(onboardingSourceDir, file);
+            const templatePath = path.join(onboardingTargetDir, `${file}.template`);
+            const result = checkFileDrift(sourcePath, templatePath, projectRoot);
+            checkedFiles.push(result.relativePath);
+            if (result.isDrifting) {
+                driftingFiles.push(result.relativePath);
+            }
+        }
+    }
+    // Check skills
+    const skillsSourceDir = path.join(projectRoot, CLAUDE_DIR, SKILLS_DIR);
+    const skillsTargetDir = path.join(templatesDir, 'vendors', 'claude', CLAUDE_DIR, SKILLS_DIR);
+    if (fs.existsSync(skillsSourceDir)) {
+        const skillDirs = fs
+            .readdirSync(skillsSourceDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+        for (const skillName of skillDirs) {
+            const skillFile = path.join(skillsSourceDir, skillName, 'SKILL.md');
+            const templatePath = path.join(skillsTargetDir, skillName, 'SKILL.md.template');
+            if (fs.existsSync(skillFile)) {
+                const result = checkFileDrift(skillFile, templatePath, projectRoot);
+                checkedFiles.push(result.relativePath);
+                if (result.isDrifting) {
+                    driftingFiles.push(result.relativePath);
+                }
+            }
+        }
+    }
+    return {
+        hasDrift: driftingFiles.length > 0,
+        driftingFiles,
+        checkedFiles,
+    };
+}
 /**
  * CLI entry point
  */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- CLI main() handles multiple modes and output formatting
 export async function main() {
     const opts = parseSyncTemplatesOptions();
     const projectRoot = process.cwd();
+    // Check-drift mode: verify templates match source without syncing
+    if (opts.checkDrift) {
+        console.log('[sync-templates] Checking for template drift...');
+        const drift = await checkTemplateDrift(projectRoot);
+        if (opts.verbose) {
+            console.log(`  Checked ${drift.checkedFiles.length} files`);
+        }
+        if (drift.hasDrift) {
+            console.log('\n[sync-templates] WARNING: Template drift detected!');
+            console.log('  The following templates are out of sync with their source:');
+            for (const file of drift.driftingFiles) {
+                console.log(`    - ${file}`);
+            }
+            console.log('\n  Run `pnpm sync:templates` to update templates.');
+            process.exitCode = 1;
+        }
+        else {
+            console.log('[sync-templates] All templates are in sync.');
+        }
+        return;
+    }
+    // Sync mode: update templates from source
     console.log('[sync-templates] Syncing internal docs to CLI templates...');
     if (opts.dryRun) {
         console.log('  (dry-run mode - no files will be written)');
@@ -208,5 +340,5 @@ export async function main() {
 // CLI entry point
 import { runCLI } from './cli-entry-point.js';
 if (import.meta.main) {
-    runCLI(main);
+    void runCLI(main);
 }

package/dist/wu-prep.js

@@ -1,21 +1,28 @@
 #!/usr/bin/env node
+/* eslint-disable no-console -- CLI command uses console for status output */
 /**
  * WU Prep Helper (WU-1223)
  *
  * Prepares a WU for completion by running gates and generating docs in the worktree.
  * After successful prep, prints copy-paste instruction to run wu:done from main.
  *
+ * WU-1344: When gates fail on spec:linter due to pre-existing WU validation errors
+ * (not caused by the current WU), prints a ready-to-copy wu:done --skip-gates
+ * command with reason and fix-wu placeholders.
+ *
  * Workflow:
  * 1. Verify we're in a worktree (error if in main checkout)
  * 2. Run gates in the worktree
- * 3. Generate docs (if applicable)
- * 4. Print copy-paste instruction for wu:done from main
+ * 3. If gates fail, check if failures are pre-existing on main
+ * 4. If pre-existing, print skip-gates command; otherwise, print fix guidance
+ * 5. On success, print copy-paste instruction for wu:done from main
  *
  * Usage:
  *   pnpm wu:prep --id WU-XXX [--docs-only]
  *
  * @module
  */
+import { spawnSync } from 'node:child_process';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { resolveLocation } from '@lumenflow/core/dist/context/location-resolver.js';
@@ -39,6 +46,84 @@ const PREP_OPTIONS = {
         description: 'Run docs-only gates (format, spec-linter)',
     },
 };
+/**
+ * WU-1344: Check if a gate name is the spec:linter gate.
+ * Used to identify when spec:linter fails so we can check for pre-existing failures.
+ *
+ * @param gateName - Name of the gate that failed
+ * @returns true if this is the spec:linter gate
+ */
+export function isPreExistingSpecLinterFailure(gateName) {
+    const normalizedName = gateName.toLowerCase().replace(/[:-]/g, '');
+    return normalizedName === 'speclinter';
+}
+/**
+ * WU-1344: Format a skip-gates command for wu:done.
+ * Includes --reason and --fix-wu placeholders.
+ *
+ * @param options - Configuration options
+ * @param options.wuId - The WU ID being completed
+ * @param options.mainCheckout - Path to main checkout
+ * @returns Formatted command string ready to copy-paste
+ */
+export function formatSkipGatesCommand(options) {
+    const { wuId, mainCheckout } = options;
+    return `cd ${mainCheckout} && pnpm wu:done --id ${wuId} --skip-gates --reason "pre-existing on main" --fix-wu WU-XXXX`;
+}
+/**
+ * WU-1344: Default implementation of execOnMain using spawnSync.
+ * Uses spawnSync with pnpm executable for safety (no shell injection risk).
+ */
+function defaultExecOnMain(mainCheckout) {
+    return async (cmd) => {
+        // Parse command to extract pnpm script name and args
+        // Expected format: "pnpm spec:linter" or similar
+        const parts = cmd.split(/\s+/);
+        const executable = parts[0];
+        const args = parts.slice(1);
+        const result = spawnSync(executable, args, {
+            cwd: mainCheckout,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return {
+            exitCode: result.status ?? 1,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+        };
+    };
+}
+/**
+ * WU-1344: Check if spec:linter failures are pre-existing on main branch.
+ *
+ * Runs spec:linter on the main checkout to determine if the failures
+ * already exist there (i.e., not caused by the current WU).
+ *
+ * @param options - Configuration options
+ * @param options.mainCheckout - Path to main checkout
+ * @param options.execOnMain - Optional function to execute commands on main (for testing)
+ * @returns Result indicating whether failures are pre-existing
+ */
+export async function checkPreExistingFailures(options) {
+    const { mainCheckout, execOnMain = defaultExecOnMain(mainCheckout) } = options;
+    try {
+        // Run spec:linter on main checkout
+        const result = await execOnMain('pnpm spec:linter');
+        // If spec:linter fails on main, the failures are pre-existing
+        if (result.exitCode !== 0) {
+            return { hasPreExisting: true };
+        }
+        return { hasPreExisting: false };
+    }
+    catch (error) {
+        // If we can't check main, assume failures are NOT pre-existing
+        // (safer to require fixing rather than skipping)
+        return {
+            hasPreExisting: false,
+            error: error.message,
+        };
+    }
+}
 /**
  * Print success message with copy-paste instruction.
  */
@@ -106,6 +191,34 @@ async function main() {
     console.log(`${PREP_PREFIX} Location: ${location.cwd}`);
     console.log(`${PREP_PREFIX} Main checkout: ${location.mainCheckout}`);
     console.log('');
+    // WU-1344: Check for pre-existing spec:linter failures on main BEFORE running gates.
+    // We do this first because runGates() calls die() on failure, which exits the process
+    // before we can check. By checking first, we can set up an exit handler to show
+    // the skip-gates command if gates fail.
+    console.log(`${PREP_PREFIX} Checking for pre-existing spec:linter failures on main...`);
+    const preExistingCheck = await checkPreExistingFailures({
+        mainCheckout: location.mainCheckout,
+    });
+    if (preExistingCheck.hasPreExisting) {
+        console.log(`${PREP_PREFIX} ${EMOJI.WARNING} Pre-existing failures detected on main.`);
+        // Set up an exit handler to print the skip-gates command when gates fail
+        // This runs before process.exit() fully terminates the process
+        process.on('exit', (code) => {
+            if (code !== EXIT_CODES.SUCCESS) {
+                console.log('');
+                console.log(`${PREP_PREFIX} ${EMOJI.WARNING} Since failures are pre-existing on main, you can skip gates:`);
+                console.log('');
+                console.log(`    ${formatSkipGatesCommand({ wuId: id, mainCheckout: location.mainCheckout })}`);
+                console.log('');
+                console.log(`${PREP_PREFIX} Replace WU-XXXX with the WU that will fix these spec issues.`);
+                console.log('');
+            }
+        });
+    }
+    else {
+        console.log(`${PREP_PREFIX} No pre-existing failures on main.`);
+    }
+    console.log('');
     // Run gates in the worktree
     console.log(`${PREP_PREFIX} Running gates in worktree...`);
     const gatesResult = await runGates({
@@ -113,13 +226,23 @@ async function main() {
         docsOnly: args.docsOnly,
     });
     if (!gatesResult) {
-        die(`${EMOJI.FAILURE} Gates failed in worktree.\n\n` +
-            `Fix the gate failures and run wu:prep again.`);
+        // Gates failed - if pre-existing check was already done and showed failures,
+        // the exit handler above will print the skip-gates command.
+        // Otherwise, tell the user to fix the failures.
+        if (!preExistingCheck.hasPreExisting) {
+            die(`${EMOJI.FAILURE} Gates failed in worktree.\n\n` +
+                `Fix the gate failures and run wu:prep again.`);
+        }
+        // Pre-existing failures - exit with error, handler will print skip-gates command
+        process.exit(EXIT_CODES.ERROR);
     }
     // Success - print copy-paste instruction
     printSuccessMessage(id, location.mainCheckout);
 }
-main().catch((e) => {
-    console.error(e.message);
-    process.exit(EXIT_CODES.ERROR);
-});
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    void runCLI(main);
+}

package/dist/wu-spawn.js

@@ -38,11 +38,12 @@ import { WU_STATUS, PATTERNS, FILE_SYSTEM, EMOJI } from '@lumenflow/core/dist/wu
 // WU-1603: Check lane lock status before spawning
 // WU-1325: Import lock policy getter for lane availability check
 import { checkLaneLock } from '@lumenflow/core/dist/lane-lock.js';
-import { getLockPolicyForLane } from '@lumenflow/core/dist/lane-checker.js';
+import { getLockPolicyForLane, getWipLimitForLane } from '@lumenflow/core/dist/lane-checker.js';
 import { minimatch } from 'minimatch';
 // WU-2252: Import invariants loader for spawn output injection
 import { loadInvariants, INVARIANT_TYPES } from '@lumenflow/core/dist/invariants-runner.js';
 import { validateSpawnArgs, generateExecutionModeSection, generateThinkToolGuidance, recordSpawnToRegistry, formatSpawnRecordedMessage, } from '@lumenflow/core/dist/wu-spawn-helpers.js';
+// eslint-disable-next-line sonarjs/deprecation -- legacy factory used by CLI spawns
 import { SpawnStrategyFactory } from '@lumenflow/core/dist/spawn-strategy.js';
 import { getConfig } from '@lumenflow/core/dist/lumenflow-config.js';
 import { generateClientSkillsGuidance, generateSkillsSelectionSection, resolveClientConfig, } from '@lumenflow/core/dist/wu-spawn-skills.js';
@@ -1168,7 +1169,10 @@ export function checkLaneOccupation(lane) {
 export function generateLaneOccupationWarning(lockMetadata, targetWuId, options = {}) {
     const { isStale = false } = options;
     let warning = `⚠️  Lane "${lockMetadata.lane}" is occupied by ${lockMetadata.wuId}\n`;
-    warning += `   This violates WIP=1 (Work In Progress limit of 1 per lane).\n\n`;
+    // WU-1346: Use injected values if provided, otherwise look up from config
+    const lockPolicy = options.lockPolicy ?? getLockPolicyForLane(lockMetadata.lane);
+    const wipLimit = options.wipLimit ?? getWipLimitForLane(lockMetadata.lane);
+    warning += `   This violates WIP=${wipLimit} (lock_policy=${lockPolicy}).\n\n`;
     if (isStale) {
         warning += `   ⏰ This lock is STALE (>24 hours old) - the WU may be abandoned.\n`;
         warning += `   Consider using pnpm wu:block --id ${lockMetadata.wuId} if work is stalled.\n\n`;
@@ -1327,6 +1331,7 @@ async function main() {
         }
     }
     // Create strategy
+    // eslint-disable-next-line sonarjs/deprecation -- legacy factory used by CLI spawns
     const strategy = SpawnStrategyFactory.create(clientName);
     const clientContext = { name: clientName, config: resolveClientConfig(config, clientName) };
     if (clientName === 'codex-cli' || args.codex) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -74,7 +74,7 @@
     "initiative-status": "./dist/initiative-status.js",
     "initiative-add-wu": "./dist/initiative-add-wu.js",
     "initiative-plan": "./dist/initiative-plan.js",
-    "init-plan": "./dist/init-plan.js",
+    "init-plan": "./dist/initiative-plan.js",
     "plan-create": "./dist/plan-create.js",
     "plan-link": "./dist/plan-link.js",
     "plan-edit": "./dist/plan-edit.js",
@@ -148,11 +148,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "2.5.0",
-    "@lumenflow/initiatives": "2.5.0",
-    "@lumenflow/memory": "2.5.0",
-    "@lumenflow/agent": "2.5.0",
-    "@lumenflow/metrics": "2.5.0"
+    "@lumenflow/metrics": "2.5.1",
+    "@lumenflow/core": "2.5.1",
+    "@lumenflow/initiatives": "2.5.1",
+    "@lumenflow/agent": "2.5.1",
+    "@lumenflow/memory": "2.5.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",

package/templates/core/.lumenflow/constraints.md.template

@@ -1,13 +1,13 @@
 # LumenFlow Constraints Capsule
 
-**Version:** 1.0
+**Version:** 1.1
 **Last updated:** {{DATE}}
 
-This document contains the 6 non-negotiable constraints that every agent must keep "in working memory" from first plan through `wu:done`.
+This document contains the 7 non-negotiable constraints that every agent must keep "in working memory" from first plan through `wu:done`.
 
 ---
 
-## The 6 Non-Negotiable Constraints
+## The 7 Non-Negotiable Constraints
 
 ### 1. Worktree Discipline and Git Safety
 
@@ -19,8 +19,40 @@ This document contains the 6 non-negotiable constraints that every agent must ke
 - Hooks block WU commits from main checkout
 - Forbidden commands on main: `git reset --hard`, `git stash`, `git clean -fd`, `git push --force`
 
+**MANDATORY PRE-WRITE CHECK**
+
+Before ANY Write/Edit/Read operation:
+
+1. **Verify worktree location**:
+
+   ```bash
+   pwd
+   # Must show: .../worktrees/<lane>-wu-xxx
+   ```
+
+2. **Verify relative paths only**:
+   - ✅ `docs/...`, `packages/...`, `apps/...`, `./...`
+   - ❌ `/home/...`, `/Users/...`, or full repo paths
+
+3. **Docs-only exception (documentation WUs)**:
+   - You may run **read-only** commands from main (e.g., `pnpm gates --docs-only`).
+   - **All file writes still require a worktree**. If no worktree exists, claim one first.
+
 **Why:** Worktree isolation prevents cross-contamination between parallel WUs and protects the main branch.
 
+**NEVER "QUICK FIX" ON MAIN**
+
+If you see something broken on main (failing gates, format issues, typos, lint errors):
+
+- ❌ **Don't** fix it directly, even if it seems small or helpful
+- ❌ **Don't** run `prettier --write`, `pnpm lint --fix`, or any command that modifies files
+- ✅ **Do** report the issue to the user
+- ✅ **Do** create a WU if a fix is needed
+
+**Why this matters:** The "helpful fix" instinct causes agents to modify files on main without a worktree. While commits are blocked by hooks, the files are still modified, requiring manual cleanup. Every change—no matter how small—needs a worktree.
+
+**If you're on main and want to change something: STOP. Create a WU first.**
+
 ---
 
 ### 2. WUs Are Specs, Not Code
@@ -94,6 +126,32 @@ This document contains the 6 non-negotiable constraints that every agent must ke
 
 ---
 
+### 7. Test Ratchet Pattern (WU-1253)
+
+**Rule:** NEW test failures block gates; pre-existing failures (in baseline) warn but do not block.
+
+**Baseline File:** `.lumenflow/test-baseline.json`
+
+**Enforcement:**
+
+- Gates compare current test results against baseline
+- NEW failures (not in baseline) = **BLOCK** (must fix or add to baseline)
+- Pre-existing failures (in baseline) = **WARNING** (continue, do not block WU)
+- Fixed tests auto-removed from baseline (ratchet forward)
+
+**When gates fail due to tests:**
+
+1. Check baseline: `cat .lumenflow/test-baseline.json`
+2. If failure is pre-existing: warning shown, WU proceeds
+3. If failure is NEW: fix the test or add to baseline with:
+   ```bash
+   pnpm baseline:add --test "<test_name>" --reason "<why>" --fix-wu WU-XXXX
+   ```
+
+**Why:** Agents should not be blocked by unrelated failures. The ratchet ensures quality improves over time (failures can only be removed, never added without justification).
+
+---
+
 ## Mini Audit Checklist
 
 Before running `wu:done`, verify: