@lumenflow/cli 2.6.0 → 2.8.0

package/dist/wu-preflight.js

@@ -27,7 +27,6 @@ import { PATTERNS, EXIT_CODES, LOG_PREFIX, EMOJI } from '@lumenflow/core/dist/wu
 import { defaultWorktreeFrom, WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { readWURaw } from '@lumenflow/core/dist/wu-yaml.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
-/* eslint-disable security/detect-non-literal-fs-filename */
 /**
  * Detect worktree path from WU YAML or calculate from lane
  * @param {string} id - WU ID

package/dist/wu-prep.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-/* eslint-disable no-console -- CLI command uses console for status output */
 /**
  * WU Prep Helper (WU-1223)
  *

package/dist/wu-proto.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+/**
+ * WU Proto Helper (WU-1359)
+ *
+ * Convenience command for rapid prototyping that creates a WU with
+ * type: prototype and relaxed validation, then immediately claims it.
+ *
+ * Key differences from wu:create:
+ * - type: prototype (not feature)
+ * - No --acceptance required
+ * - No --exposure required
+ * - No --code-paths required
+ * - No --test-paths required
+ * - No --spec-refs required
+ * - Automatically claims the WU after creation
+ * - Prints cd command to worktree
+ *
+ * Usage:
+ *   pnpm wu:proto --lane "Framework: CLI" --title "Quick experiment"
+ *
+ * Context: WU-1359 (enhance init output and add wu:proto command)
+ */
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { todayISO } from '@lumenflow/core/dist/date-utils.js';
+import { validateLaneFormat } from '@lumenflow/core/dist/lane-checker.js';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { validateWU } from '@lumenflow/core/dist/wu-schema.js';
+import { COMMIT_FORMATS, FILE_SYSTEM, STRING_LITERALS } from '@lumenflow/core/dist/wu-constants.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { generateWuIdWithRetry } from '@lumenflow/core/dist/wu-id-generator.js';
+import { parseBacklogFrontmatter } from '@lumenflow/core/dist/backlog-parser.js';
+import { execFileSync } from 'node:child_process';
+/** Log prefix for console output */
+const LOG_PREFIX = '[wu:proto]';
+/** Micro-worktree operation name */
+const OPERATION_NAME = 'wu-proto';
+/** Default priority for prototype WUs */
+const DEFAULT_PRIORITY = 'P3';
+/** Prototype WU type */
+const PROTOTYPE_TYPE = 'prototype';
+/**
+ * Validate prototype WU spec (relaxed validation)
+ *
+ * Unlike wu:create, this has minimal requirements:
+ * - lane is required
+ * - title is required
+ * - Everything else is optional
+ *
+ * @param params - Validation parameters
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateProtoSpec({ id: _id, lane, title, opts: _opts = {}, }) {
+    const errors = [];
+    if (!lane || lane.trim() === '') {
+        errors.push('--lane is required');
+    }
+    if (!title || title.trim() === '') {
+        errors.push('--title is required');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Build prototype WU content
+ * @returns WU content object for YAML serialization
+ */
+function buildProtoWUContent({ id, lane, title, priority, created, opts, }) {
+    const { description, codePaths, labels, assignedTo } = opts;
+    return {
+        id,
+        title,
+        lane,
+        type: PROTOTYPE_TYPE,
+        status: 'ready',
+        priority,
+        created,
+        description: description || '',
+        // Prototype WUs have minimal default acceptance
+        acceptance: ['Prototype demonstrates concept'],
+        code_paths: codePaths ?? [],
+        tests: {
+            manual: [],
+            unit: [],
+            e2e: [],
+        },
+        artifacts: [`.lumenflow/stamps/${id}.done`],
+        dependencies: [],
+        risks: [],
+        notes: 'Prototype WU - relaxed validation applies',
+        requires_review: false,
+        ...(labels?.length && { labels }),
+        ...(assignedTo && { assigned_to: assignedTo }),
+        // WU-1359: Prototype WUs set exposure to backend-only by default
+        exposure: 'backend-only',
+    };
+}
+/**
+ * Create prototype WU YAML in micro-worktree
+ * @returns Relative path to created WU YAML file
+ */
+function createProtoWUYamlInWorktree(worktreePath, id, lane, title, priority, opts) {
+    const wuRelativePath = WU_PATHS.WU(id);
+    const wuAbsolutePath = join(worktreePath, wuRelativePath);
+    const wuDir = join(worktreePath, WU_PATHS.WU_DIR());
+    if (!existsSync(wuDir)) {
+        mkdirSync(wuDir, { recursive: true });
+    }
+    const today = todayISO();
+    const wuContent = buildProtoWUContent({
+        id,
+        lane,
+        title,
+        priority,
+        created: today,
+        opts,
+    });
+    // Validate WU structure before writing
+    const validationResult = validateWU(wuContent);
+    if (!validationResult.success) {
+        const errors = validationResult.error.issues
+            .map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`)
+            .join(STRING_LITERALS.NEWLINE);
+        die(`${LOG_PREFIX} WU validation failed:\n\n${errors}`);
+    }
+    const yamlContent = stringifyYAML(validationResult.data, { lineWidth: -1 });
+    writeFileSync(wuAbsolutePath, yamlContent, { encoding: FILE_SYSTEM.UTF8 });
+    console.log(`${LOG_PREFIX} Created ${id}.yaml in micro-worktree`);
+    return wuRelativePath;
+}
+/**
+ * Update backlog.md in micro-worktree
+ * @returns Relative path to updated backlog file
+ */
+function updateBacklogInWorktree(worktreePath, id, lane, title) {
+    const backlogRelativePath = WU_PATHS.BACKLOG();
+    const backlogAbsolutePath = join(worktreePath, backlogRelativePath);
+    if (!existsSync(backlogAbsolutePath)) {
+        die(`Backlog not found: ${backlogAbsolutePath}`);
+    }
+    const { frontmatter, markdown } = parseBacklogFrontmatter(backlogAbsolutePath);
+    if (!frontmatter?.sections?.ready?.heading) {
+        die('Invalid backlog frontmatter: Missing sections.ready.heading');
+    }
+    const readyHeading = frontmatter.sections.ready.heading;
+    const lines = markdown.split(STRING_LITERALS.NEWLINE);
+    const headingIndex = lines.findIndex((line) => line === readyHeading);
+    if (headingIndex === -1) {
+        die(`Could not find Ready section heading: '${readyHeading}'`);
+    }
+    const insertionIndex = headingIndex + 2;
+    const newEntry = `- [${id} - ${title}](wu/${id}.yaml) - ${lane}`;
+    lines.splice(insertionIndex, 0, newEntry);
+    const updatedMarkdown = lines.join(STRING_LITERALS.NEWLINE);
+    const updatedBacklog = `---\n${stringifyYAML(frontmatter, { lineWidth: -1 })}---\n${updatedMarkdown}`;
+    writeFileSync(backlogAbsolutePath, updatedBacklog, {
+        encoding: FILE_SYSTEM.UTF8,
+    });
+    console.log(`${LOG_PREFIX} Updated backlog.md in micro-worktree`);
+    return backlogRelativePath;
+}
+/**
+ * Get default assigned_to value from git config user.email
+ */
+async function getDefaultAssignedTo() {
+    try {
+        const email = await getGitForCwd().getConfigValue('user.email');
+        return email || '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Regex to extract worktree path from wu:claim output */
+const WORKTREE_PATH_REGEX = /Worktree:\s*(\S+)/;
+/**
+ * Claim the WU after creation using execFileSync (safe from shell injection)
+ * @returns Path to the created worktree
+ */
+function claimWU(wuId, lane) {
+    console.log(`${LOG_PREFIX} Claiming WU ${wuId}...`);
+    try {
+        // Use execFileSync for safety (no shell injection risk)
+        // Use process.execPath to get absolute path to node, then run pnpm via npx
+        const result = execFileSync(process.execPath, [
+            '--no-warnings',
+            '--experimental-import-meta-resolve',
+            ...process.execArgv.filter((a) => !a.startsWith('--inspect')),
+            require.resolve('.bin/wu-claim'),
+            '--id',
+            wuId,
+            '--lane',
+            lane,
+        ], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            cwd: process.cwd(),
+        });
+        // Extract worktree path from output using regex exec (sonarjs/prefer-regexp-exec)
+        const worktreeMatch = WORKTREE_PATH_REGEX.exec(result);
+        if (worktreeMatch) {
+            return worktreeMatch[1];
+        }
+        // Fallback: construct expected worktree path
+        const laneSuffix = lane.toLowerCase().replace(/[:\s]+/g, '-');
+        return `worktrees/${laneSuffix}-${wuId.toLowerCase()}`;
+    }
+    catch (error) {
+        die(`Failed to claim WU: ${error.message}`);
+    }
+}
+async function main() {
+    const args = createWUParser({
+        name: 'wu-proto',
+        description: 'Create and claim a prototype WU with relaxed validation (rapid prototyping)',
+        options: [
+            WU_OPTIONS.lane,
+            WU_OPTIONS.title,
+            WU_OPTIONS.description,
+            WU_OPTIONS.codePaths,
+            WU_OPTIONS.labels,
+            WU_OPTIONS.assignedTo,
+        ],
+        required: ['lane', 'title'],
+        allowPositionalId: false,
+    });
+    console.log(`${LOG_PREFIX} Creating prototype WU in ${args.lane} lane...`);
+    // Validate lane format
+    try {
+        validateLaneFormat(args.lane);
+    }
+    catch (error) {
+        die(`Invalid lane format: ${error.message}`);
+    }
+    await ensureOnMain(getGitForCwd());
+    // Auto-generate WU ID
+    console.log(`${LOG_PREFIX} Auto-generating WU ID...`);
+    let wuId;
+    try {
+        wuId = await generateWuIdWithRetry();
+        console.log(`${LOG_PREFIX} Generated WU ID: ${wuId}`);
+    }
+    catch (error) {
+        die(`Failed to auto-generate WU ID: ${error.message}`);
+    }
+    // Check if WU already exists
+    const wuPath = WU_PATHS.WU(wuId);
+    if (existsSync(wuPath)) {
+        die(`WU already exists: ${wuPath}`);
+    }
+    // Get assigned_to from flag or git config
+    const assignedTo = args.assignedTo || (await getDefaultAssignedTo());
+    // Validate proto spec
+    const validation = validateProtoSpec({
+        id: wuId,
+        lane: args.lane,
+        title: args.title,
+        opts: {
+            description: args.description,
+            codePaths: args.codePaths,
+            labels: args.labels,
+            assignedTo,
+        },
+    });
+    if (!validation.valid) {
+        const errorList = validation.errors.map((e) => `  - ${e}`).join(STRING_LITERALS.NEWLINE);
+        die(`${LOG_PREFIX} Validation failed:\n\n${errorList}`);
+    }
+    // WU-1255: Set LUMENFLOW_WU_TOOL to allow pre-push hook bypass
+    const previousWuTool = process.env.LUMENFLOW_WU_TOOL;
+    process.env.LUMENFLOW_WU_TOOL = OPERATION_NAME;
+    try {
+        await withMicroWorktree({
+            operation: OPERATION_NAME,
+            id: wuId,
+            logPrefix: LOG_PREFIX,
+            execute: async ({ worktreePath }) => {
+                // Create WU YAML
+                const wuRelativePath = createProtoWUYamlInWorktree(worktreePath, wuId, args.lane, args.title, DEFAULT_PRIORITY, {
+                    description: args.description,
+                    codePaths: args.codePaths,
+                    labels: args.labels,
+                    assignedTo,
+                });
+                // Update backlog
+                const backlogPath = updateBacklogInWorktree(worktreePath, wuId, args.lane, args.title);
+                return {
+                    commitMessage: COMMIT_FORMATS.CREATE(wuId, args.title),
+                    files: [wuRelativePath, backlogPath],
+                };
+            },
+        });
+        console.log(`\n${LOG_PREFIX} WU created!`);
+        console.log(`  ID:     ${wuId}`);
+        console.log(`  Title:  ${args.title}`);
+        console.log(`  Lane:   ${args.lane}`);
+        console.log(`  Type:   ${PROTOTYPE_TYPE}`);
+        console.log(`  File:   ${WU_PATHS.WU(wuId)}`);
+        // Immediately claim the WU
+        const worktreePath = claimWU(wuId, args.lane);
+        console.log(`\n${LOG_PREFIX} WU claimed and worktree created!`);
+        console.log(`\nNext step:`);
+        console.log(`  cd ${worktreePath}`);
+    }
+    catch (error) {
+        die(`Transaction failed: ${error.message}`);
+    }
+    finally {
+        // Restore LUMENFLOW_WU_TOOL
+        if (previousWuTool === undefined) {
+            delete process.env.LUMENFLOW_WU_TOOL;
+        }
+        else {
+            process.env.LUMENFLOW_WU_TOOL = previousWuTool;
+        }
+    }
+}
+// Run CLI
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    void runCLI(main);
+}

package/dist/wu-spawn.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-/* eslint-disable no-console -- CLI tool requires console output */
 /**
  * WU Spawn Helper
  *
@@ -43,7 +42,6 @@ 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';
@@ -1331,7 +1329,6 @@ 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/dist/wu-unblock.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-/* eslint-disable no-console -- CLI tool requires console output */
 /**
  * WU Unblock Helper
  *
@@ -55,7 +54,6 @@ function branchExists(branch) {
 function createWorktree(doc, worktreePath, branchName) {
     if (!worktreePath)
         die('Worktree path required to create a worktree');
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool checks worktree
     if (existsSync(worktreePath)) {
         console.warn(`${PREFIX} Worktree ${worktreePath} already exists; skipping creation.`);
         return;

package/dist/wu-validate.js

@@ -112,7 +112,6 @@ function validateAllWUs({ strict = true } = {}) {
 /**
  * Main entry point
  */
-// eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
 async function main() {
     const args = createWUParser({
         name: 'wu-validate',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -40,6 +40,7 @@
     "wu-block": "./dist/wu-block.js",
     "wu-unblock": "./dist/wu-unblock.js",
     "wu-create": "./dist/wu-create.js",
+    "wu-proto": "./dist/wu-proto.js",
     "wu-edit": "./dist/wu-edit.js",
     "wu-spawn": "./dist/wu-spawn.js",
     "wu-validate": "./dist/wu-validate.js",
@@ -130,7 +131,8 @@
     "lane-health": "./dist/lane-health.js",
     "lane-suggest": "./dist/lane-suggest.js",
     "state-cleanup": "./dist/state-cleanup.js",
-    "state-doctor": "./dist/state-doctor.js"
+    "state-doctor": "./dist/state-doctor.js",
+    "lumenflow-integrate": "./dist/commands/integrate.js"
   },
   "files": [
     "dist",
@@ -148,11 +150,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "2.6.0",
-    "@lumenflow/initiatives": "2.6.0",
-    "@lumenflow/metrics": "2.6.0",
-    "@lumenflow/agent": "2.6.0",
-    "@lumenflow/memory": "2.6.0"
+    "@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"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",

package/templates/core/.husky/pre-commit.template

@@ -0,0 +1,93 @@
+#!/bin/sh
+#
+# LumenFlow Pre-Commit Hook (Vendor-Agnostic)
+#
+# This hook enforces worktree discipline for all users and AI agents.
+# It blocks direct commits to main/master branches.
+#
+# Rules:
+#   1. BLOCK commits to main/master (use WU workflow instead)
+#   2. ALLOW commits on lane branches (lane/*/wu-*)
+#   3. ALLOW commits on tmp/* branches (CLI micro-worktrees)
+#
+# Escape hatch (logged, emergency only):
+#   LUMENFLOW_FORCE=1 LUMENFLOW_FORCE_REASON="reason" git commit ...
+#
+# Configuration:
+#   Package manager is configured in .lumenflow.config.yaml (package_manager)
+#   Default: pnpm (examples below use pnpm - adjust for your project)
+#
+# For documentation on the WU workflow, see:
+#   - LUMENFLOW.md
+#   - docs/_frameworks/lumenflow/agent/onboarding/starting-prompt.md
+#
+
+# Skip on tmp/* branches (CLI micro-worktrees in /tmp with no node_modules)
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+case "$BRANCH" in tmp/*) exit 0 ;; esac
+
+# Check for force bypass (logged for audit)
+if [ "$LUMENFLOW_FORCE" = "1" ]; then
+  if [ -z "$LUMENFLOW_FORCE_REASON" ]; then
+    echo "" >&2
+    echo "[pre-commit] Warning: LUMENFLOW_FORCE_REASON not set." >&2
+    echo "Consider: LUMENFLOW_FORCE_REASON=\"reason\" LUMENFLOW_FORCE=1 git commit ..." >&2
+    echo "" >&2
+  fi
+  # Log bypass to .beacon/ for audit trail
+  BEACON_DIR="$(git rev-parse --show-toplevel 2>/dev/null)/.beacon"
+  if [ -n "$BEACON_DIR" ]; then
+    mkdir -p "$BEACON_DIR"
+    TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    USER=$(git config user.name 2>/dev/null || echo "unknown")
+    echo "${TIMESTAMP} | pre-commit | ${USER} | ${BRANCH} | ${LUMENFLOW_FORCE_REASON:-no reason} | $(pwd)" >> "${BEACON_DIR}/force-bypasses.log"
+  fi
+  exit 0
+fi
+
+# Block direct commits to main/master
+case "$BRANCH" in
+  main|master)
+    echo "" >&2
+    echo "==================================================================" >&2
+    echo "  DIRECT COMMIT TO ${BRANCH} BLOCKED" >&2
+    echo "==================================================================" >&2
+    echo "" >&2
+    echo "WHY THIS HAPPENS" >&2
+    echo "------------------------------------------------------------------" >&2
+    echo "LumenFlow protects main from direct commits to ensure:" >&2
+    echo "  - All work is tracked in Work Units (WUs)" >&2
+    echo "  - Changes can be reviewed and coordinated" >&2
+    echo "  - Parallel work across lanes stays isolated" >&2
+    echo "" >&2
+    echo "WHAT TO DO" >&2
+    echo "------------------------------------------------------------------" >&2
+    echo "" >&2
+    echo "1. If you have a Work Unit to implement:" >&2
+    echo "     pnpm wu:claim --id WU-XXXX --lane \"<Lane>\"" >&2
+    echo "     cd worktrees/<lane>-wu-xxxx" >&2
+    echo "   Then make your commits in the worktree" >&2
+    echo "" >&2
+    echo "2. If you need to create a new Work Unit:" >&2
+    echo "     pnpm wu:create --lane \"<Lane>\" --title \"Your task\"" >&2
+    echo "   This generates a WU ID, then claim it as above" >&2
+    echo "" >&2
+    echo "NEED HELP?" >&2
+    echo "------------------------------------------------------------------" >&2
+    echo "  - Read: LUMENFLOW.md (workflow overview)" >&2
+    echo "  - Read: docs/_frameworks/lumenflow/agent/onboarding/" >&2
+    echo "  - Run:  pnpm wu:help" >&2
+    echo "" >&2
+    echo "------------------------------------------------------------------" >&2
+    echo "EMERGENCY BYPASS (last resort, logged)" >&2
+    echo "------------------------------------------------------------------" >&2
+    echo "Bypasses are audit-logged. Only use for genuine emergencies." >&2
+    echo "  LUMENFLOW_FORCE=1 LUMENFLOW_FORCE_REASON=\"<reason>\" git commit ..." >&2
+    echo "------------------------------------------------------------------" >&2
+    echo "" >&2
+    exit 1
+    ;;
+esac
+
+# Allow commits on lane branches and other branches
+exit 0

package/templates/core/ai/onboarding/quick-ref-commands.md.template

@@ -6,6 +6,33 @@ Complete reference for all CLI commands. Organized by category for quick discove
 
 ---
 
+## Quick Start (Essential Commands)
+
+Most common workflow in 4 commands:
+
+```bash
+# 1. Claim WU and create isolated workspace
+pnpm wu:claim --id WU-XXX --lane "Lane Name"
+cd worktrees/<lane>-wu-xxx
+
+# 2. Work in worktree, then run gates
+pnpm gates                    # For code changes
+pnpm gates --docs-only        # For documentation only
+
+# 3. Prepare for completion (from worktree)
+pnpm wu:prep --id WU-XXX
+
+# 4. Complete (from main - copy command from wu:prep output)
+cd /path/to/main && pnpm wu:done --id WU-XXX
+```
+
+**Key rules:**
+- Always work in worktrees, never on main
+- Always run `wu:done` to complete (not just documenting it)
+- Use `wu:prep` first (runs gates), then `wu:done` (merges)
+
+---
+
 ## Setup & Development
 
 **For this monorepo (development):**