@lumenflow/core 1.0.0 → 1.3.2

package/dist/arg-parser.d.ts

@@ -21,6 +21,12 @@ interface WUOption {
     isRepeatable?: boolean;
 }
 export declare const WU_OPTIONS: Record<string, WUOption>;
+/**
+ * WU-1062: Additional options for wu:create command
+ *
+ * These options control how wu:create handles spec storage and branch creation.
+ */
+export declare const WU_CREATE_OPTIONS: Record<string, WUOption>;
 /**
  * Create a commander-based CLI parser for a WU script.
  *

package/dist/arg-parser.js

@@ -15,6 +15,16 @@ function collectRepeatable(value, previous) {
 }
 export const WU_OPTIONS = {
     // String options (require values)
+    client: {
+        name: 'client',
+        flags: '--client <client>',
+        description: 'Client name (claude-code, gemini-cli, etc)',
+    },
+    vendor: {
+        name: 'vendor',
+        flags: '--vendor <vendor>',
+        description: 'Deprecated alias for --client',
+    },
     id: {
         name: 'id',
         flags: '-i, --id <wuId>',
@@ -124,6 +134,11 @@ export const WU_OPTIONS = {
         flags: '--skip-gates',
         description: 'Skip gates check (requires --reason and --fix-wu)',
     },
+    docsOnly: {
+        name: 'docsOnly',
+        flags: '--docs-only',
+        description: 'Run docs-only gates (requires exposure: documentation or docs-only code_paths)',
+    },
     allowTodo: {
         name: 'allowTodo',
         flags: '--allow-todo',
@@ -154,6 +169,12 @@ export const WU_OPTIONS = {
         flags: '--fix',
         description: 'Auto-fix common YAML validation issues (WU-1359)',
     },
+    noPush: {
+        name: 'noPush',
+        flags: '--no-push',
+        description: 'Skip pushing claim branch or canonical updates (air-gapped/offline)',
+        isNegated: true,
+    },
     createPr: {
         name: 'createPr',
         flags: '--create-pr',
@@ -368,12 +389,44 @@ export const WU_OPTIONS = {
         flags: '--resume',
         description: 'Resume a WU from a crashed/killed agent (handoff) by taking over the existing worktree and updating the lock with new PID. Fails if original PID is still running (safety) or worktree does not exist.',
     },
+    // WU-1023: Skip auto-setup for fast claims
+    skipSetup: {
+        name: 'skipSetup',
+        flags: '--skip-setup',
+        description: 'Skip automatic pnpm install in worktree after creation (faster claims when deps already built)',
+    },
+};
+/**
+ * WU-1062: Additional options for wu:create command
+ *
+ * These options control how wu:create handles spec storage and branch creation.
+ */
+export const WU_CREATE_OPTIONS = {
+    /**
+     * Create plan template in $LUMENFLOW_HOME/plans/
+     * Used with spec branch mode to store plans externally.
+     */
+    plan: {
+        name: 'plan',
+        flags: '--plan',
+        description: 'Create plan template in $LUMENFLOW_HOME/plans/ (external plan storage for traceability)',
+    },
+    /**
+     * Direct main-write mode (legacy behavior)
+     * Writes WU spec directly to main branch instead of spec branch.
+     * Use for emergency/hotfix scenarios or when spec branch workflow is not desired.
+     */
+    direct: {
+        name: 'direct',
+        flags: '--direct',
+        description: 'Write to main directly (legacy behavior). Default is spec branch mode (spec/wu-XXXX)',
+    },
 };
 /**
  * Negated options that commander handles specially.
  * --no-foo creates opts.foo = false. We convert to noFoo = true.
  */
-const NEGATED_OPTIONS = ['auto', 'remove', 'merge', 'autoRebase'];
+const NEGATED_OPTIONS = ['auto', 'remove', 'merge', 'autoRebase', 'push'];
 /**
  * Post-process commander opts to handle negated boolean options.
  * Commander's --no-* flags create opts.foo = false.
@@ -527,6 +580,7 @@ export function parseWUArgs(argv) {
         WU_OPTIONS.noMerge,
         WU_OPTIONS.help,
         WU_OPTIONS.skipGates,
+        WU_OPTIONS.docsOnly,
         WU_OPTIONS.allowTodo,
         WU_OPTIONS.skipExposureCheck,
         WU_OPTIONS.skipAccessibilityCheck,
@@ -535,6 +589,8 @@ export function parseWUArgs(argv) {
         WU_OPTIONS.overrideOwner,
         WU_OPTIONS.noAutoRebase,
         WU_OPTIONS.requireAgents,
+        WU_OPTIONS.client,
+        WU_OPTIONS.vendor,
     ];
     for (const opt of allOptions) {
         program.option(opt.flags, opt.description, opt.default);

package/dist/backlog-generator.js

@@ -54,7 +54,7 @@ sections:
     insertion: after_heading_blank_line
 ---
 
-> Agent: Read **ai/onboarding/starting-prompt.md** first, then follow **docs/04-operations/\\_frameworks/lumenflow/lumenflow-complete.md** for execution.
+> Agent: Read **docs/04-operations/_frameworks/lumenflow/agent/onboarding/starting-prompt.md** first, then follow **docs/04-operations/\\_frameworks/lumenflow/lumenflow-complete.md** for execution.
 
 # Backlog (single source of truth)
 

package/dist/backlog-sync-validator.js

@@ -7,7 +7,7 @@
  */
 import { readFileSync, writeFileSync, existsSync, copyFileSync } from 'node:fs';
 import path from 'node:path';
-import yaml from 'js-yaml';
+import { parseYAML } from './wu-yaml.js';
 import { parseBacklogFrontmatter, getSectionHeadings } from './backlog-parser.js';
 import { extractParent } from './lane-checker.js';
 import { CONFIG_FILES, STRING_LITERALS, getProjectRoot, } from './wu-constants.js';
@@ -24,7 +24,7 @@ function hasSubLaneTaxonomy(parent, projectRoot) {
     }
     try {
         const taxonomyContent = readFileSync(taxonomyPath, { encoding: 'utf-8' });
-        const taxonomy = yaml.load(taxonomyContent);
+        const taxonomy = parseYAML(taxonomyContent);
         const normalizedParent = parent.trim().toLowerCase();
         return Object.keys(taxonomy).some((key) => key.toLowerCase().trim() === normalizedParent);
     }
@@ -126,7 +126,7 @@ export function validateBacklogSync(backlogPath) {
         }
         try {
             const wuContent = readFileSync(wuPath, { encoding: 'utf-8' });
-            const wuDoc = yaml.load(wuContent);
+            const wuDoc = parseYAML(wuContent);
             if (wuDoc && wuDoc.lane) {
                 const lane = wuDoc.lane.toString().trim();
                 const hasColon = lane.includes(':');

package/dist/branch-check.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Branch-aware bypass detection for cloud/automation agents.
+ *
+ * Provides functions to check if a branch is an agent branch that can
+ * bypass worktree requirements, and if headless mode is allowed.
+ *
+ * @module branch-check
+ */
+/**
+ * Check if branch is an agent branch that can bypass worktree requirements.
+ * Uses the existing config loader (which handles caching/validation).
+ *
+ * @param branch - Branch name to check
+ * @returns True if branch matches agent patterns
+ */
+export declare function isAgentBranch(branch: string | null | undefined): boolean;
+/**
+ * Check if headless mode is allowed (guarded).
+ * Requires LUMENFLOW_HEADLESS=1 AND (LUMENFLOW_ADMIN=1 OR CI truthy OR GITHUB_ACTIONS truthy)
+ */
+export declare function isHeadlessAllowed(): boolean;

package/dist/branch-check.js

@@ -0,0 +1,77 @@
+/**
+ * Branch-aware bypass detection for cloud/automation agents.
+ *
+ * Provides functions to check if a branch is an agent branch that can
+ * bypass worktree requirements, and if headless mode is allowed.
+ *
+ * @module branch-check
+ */
+import micromatch from 'micromatch';
+import { getConfig } from './lumenflow-config.js';
+/** Default agent branch patterns (narrow: just agent/*) */
+const DEFAULT_AGENT_BRANCH_PATTERNS = ['agent/*'];
+/** Legacy protected branch (always protected regardless of mainBranch setting) */
+const LEGACY_PROTECTED = 'master';
+/**
+ * Get lane branch pattern from config (or default).
+ * Lane branches always require worktrees - never bypassed.
+ */
+function getLaneBranchPattern() {
+    const config = getConfig();
+    const prefix = config?.git?.laneBranchPrefix ?? 'lane/';
+    // Escape regex special chars in prefix, then anchor to start
+    const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^${escaped}`);
+}
+/**
+ * Get protected branches derived from config.
+ * Returns [mainBranch, 'master'] to avoid config duplication.
+ */
+function getProtectedBranches() {
+    const config = getConfig();
+    const mainBranch = config?.git?.mainBranch ?? 'main';
+    // Deduplicate in case mainBranch is 'master'
+    const protectedSet = new Set([mainBranch, LEGACY_PROTECTED]);
+    return Array.from(protectedSet);
+}
+/**
+ * Check if branch is an agent branch that can bypass worktree requirements.
+ * Uses the existing config loader (which handles caching/validation).
+ *
+ * @param branch - Branch name to check
+ * @returns True if branch matches agent patterns
+ */
+export function isAgentBranch(branch) {
+    // Fail-closed: no branch = protected
+    if (!branch)
+        return false;
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD')
+        return false;
+    // Load config (uses existing loader with caching)
+    const config = getConfig();
+    const protectedBranches = getProtectedBranches();
+    const patterns = config?.git?.agentBranchPatterns?.length > 0
+        ? config.git.agentBranchPatterns
+        : DEFAULT_AGENT_BRANCH_PATTERNS;
+    // Protected branches are NEVER bypassed (mainBranch + 'master')
+    if (protectedBranches.includes(branch))
+        return false;
+    // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
+    if (getLaneBranchPattern().test(branch))
+        return false;
+    // Use micromatch for proper glob matching
+    return micromatch.isMatch(branch, patterns);
+}
+/**
+ * Check if headless mode is allowed (guarded).
+ * Requires LUMENFLOW_HEADLESS=1 AND (LUMENFLOW_ADMIN=1 OR CI truthy OR GITHUB_ACTIONS truthy)
+ */
+export function isHeadlessAllowed() {
+    if (process.env.LUMENFLOW_HEADLESS !== '1')
+        return false;
+    return (process.env.LUMENFLOW_ADMIN === '1' ||
+        Boolean(process.env.CI) || // Any truthy CI value (true, 1, yes, etc.)
+        Boolean(process.env.GITHUB_ACTIONS) // Any truthy value
+    );
+}

package/dist/cli/is-agent-branch.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI helper for bash hooks to check if branch is an agent branch.
+ * Uses the same isAgentBranch() logic as TypeScript code.
+ *
+ * Usage: node dist/cli/is-agent-branch.js [branch-name]
+ * Exit codes: 0 = agent branch (allowed), 1 = not agent branch (protected)
+ *
+ * @module cli/is-agent-branch
+ */
+export {};

package/dist/cli/is-agent-branch.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * CLI helper for bash hooks to check if branch is an agent branch.
+ * Uses the same isAgentBranch() logic as TypeScript code.
+ *
+ * Usage: node dist/cli/is-agent-branch.js [branch-name]
+ * Exit codes: 0 = agent branch (allowed), 1 = not agent branch (protected)
+ *
+ * @module cli/is-agent-branch
+ */
+import { isAgentBranch } from '../branch-check.js';
+const branch = process.argv[2] || null;
+const result = isAgentBranch(branch);
+// Exit 0 = agent branch (truthy), Exit 1 = not agent branch
+process.exit(result ? 0 : 1);

package/dist/code-paths-overlap.js

@@ -9,7 +9,7 @@
  */
 import { readFileSync, existsSync } from 'fs';
 import path from 'path';
-import yaml from 'js-yaml';
+import { parseYAML } from './wu-yaml.js';
 import fg from 'fast-glob';
 import micromatch from 'micromatch';
 import { STATUS_SECTIONS, BACKLOG_SECTIONS, STRING_LITERALS } from './wu-constants.js';
@@ -166,7 +166,7 @@ export function detectConflicts(statusPath, claimingPaths, claimingWU) {
             continue; // Skip if YAML doesn't exist
         }
         const wuContent = readFileSync(wuPath, { encoding: 'utf-8' });
-        const wuDoc = yaml.load(wuContent);
+        const wuDoc = parseYAML(wuContent);
         // Extract code_paths (skip if not defined)
         const existingPaths = wuDoc?.code_paths;
         if (!existingPaths || existingPaths.length === 0) {

package/dist/error-handler.d.ts

@@ -2,6 +2,7 @@
  * @file error-handler.mjs
  * @description Structured error handling with error codes
  * WU-1082: Extract shared utilities (eliminate die() duplication)
+ * WU-1006: Library-First - use path.basename() instead of manual split
  *
  * Replaces die() function in:
  * - tools/wu-claim.mjs

package/dist/error-handler.js

@@ -2,6 +2,7 @@
  * @file error-handler.mjs
  * @description Structured error handling with error codes
  * WU-1082: Extract shared utilities (eliminate die() duplication)
+ * WU-1006: Library-First - use path.basename() instead of manual split
  *
  * Replaces die() function in:
  * - tools/wu-claim.mjs
@@ -14,6 +15,7 @@
  * - tools/validate.mjs
  * - tools/guard-worktree-commit.mjs
  */
+import path from 'node:path';
 /**
  * Structured error class with error codes and details
  * @class WUError
@@ -56,8 +58,9 @@ export class WUError extends Error {
  */
 export function die(message, exitCode = 1) {
     // Auto-detect script name from process.argv[1] (eliminates string literal duplication)
+    // WU-1006: Use path.basename() instead of manual split (Library-First principle)
     const scriptPath = process.argv[1] || 'unknown';
-    const scriptName = scriptPath.split('/').pop().replace('.js', '');
+    const scriptName = path.basename(scriptPath, '.js');
     console.error(`[${scriptName}] ${message}`);
     process.exit(exitCode);
 }

package/dist/git-adapter.d.ts

@@ -66,6 +66,13 @@ export declare class GitAdapter {
      * await git.getStatus(); // " M file.txt\n?? untracked.txt"
      */
     getStatus(): Promise<string>;
+    /**
+     * Get unpushed commits (compared to upstream)
+     * @returns {Promise<string>} Oneline log output for unpushed commits
+     * @example
+     * await git.getUnpushedCommits(); // "abc123 fix: ...\n"
+     */
+    getUnpushedCommits(): Promise<string>;
     /**
      * Check if a branch exists
      * @param {string} branch - Branch name
@@ -77,6 +84,17 @@ export declare class GitAdapter {
      * await git.branchExists('nonexistent'); // false
      */
     branchExists(branch: string): Promise<boolean>;
+    /**
+     * Check if a remote branch exists via git ls-remote --heads
+     * @param {string} remote - Remote name (e.g., 'origin')
+     * @param {string} branch - Branch name
+     * @returns {Promise<boolean>} True if remote branch exists
+     * @throws {TypeError} If remote or branch is not a string
+     * @throws {Error} If remote or branch is empty
+     * @example
+     * await git.remoteBranchExists('origin', 'lane/operations/wu-123'); // true/false
+     */
+    remoteBranchExists(remote: string, branch: string): Promise<boolean>;
     /**
      * Fetch from remote
      * @param {string} [remote] - Remote name (defaults to fetching all)
@@ -391,5 +409,10 @@ export declare function createGitForPath(baseDir: string): GitAdapter;
  * const git = getGitForCwd(); // Uses new directory
  */
 export declare function getGitForCwd(): GitAdapter;
+/**
+ * Reset singleton warning flag (for testing only)
+ * @internal
+ */
+export declare function _resetSingletonWarning(): void;
 export declare const git: GitAdapter;
 export {};

package/dist/git-adapter.js

@@ -18,7 +18,7 @@
  */
 import { simpleGit } from 'simple-git';
 import { existsSync, rmSync } from 'node:fs';
-import { GIT_FLAGS } from './wu-constants.js';
+import { GIT_COMMANDS, GIT_FLAGS, GIT_REFS } from './wu-constants.js';
 // WU-2242: Runtime assertion helpers
 /**
  * Assert that a value is a non-empty string
@@ -117,6 +117,20 @@ export class GitAdapter {
         const result = await this.git.raw(['status', GIT_FLAGS.PORCELAIN]);
         return result.trim();
     }
+    /**
+     * Get unpushed commits (compared to upstream)
+     * @returns {Promise<string>} Oneline log output for unpushed commits
+     * @example
+     * await git.getUnpushedCommits(); // "abc123 fix: ...\n"
+     */
+    async getUnpushedCommits() {
+        const result = await this.git.raw([
+            GIT_COMMANDS.LOG,
+            GIT_REFS.UPSTREAM_RANGE,
+            GIT_FLAGS.ONELINE,
+        ]);
+        return result.trim();
+    }
     /**
      * Check if a branch exists
      * @param {string} branch - Branch name
@@ -137,6 +151,22 @@ export class GitAdapter {
             return false;
         }
     }
+    /**
+     * Check if a remote branch exists via git ls-remote --heads
+     * @param {string} remote - Remote name (e.g., 'origin')
+     * @param {string} branch - Branch name
+     * @returns {Promise<boolean>} True if remote branch exists
+     * @throws {TypeError} If remote or branch is not a string
+     * @throws {Error} If remote or branch is empty
+     * @example
+     * await git.remoteBranchExists('origin', 'lane/operations/wu-123'); // true/false
+     */
+    async remoteBranchExists(remote, branch) {
+        assertNonEmptyString(remote, 'remote');
+        assertNonEmptyString(branch, 'branch');
+        const result = await this.git.raw(['ls-remote', '--heads', remote, branch]);
+        return result.trim().length > 0;
+    }
     /**
      * Fetch from remote
      * @param {string} [remote] - Remote name (defaults to fetching all)
@@ -465,7 +495,13 @@ export class GitAdapter {
         // This handles edge cases where git worktree remove succeeds but leaves the directory
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool with validated worktree path
         if (existsSync(worktreePath)) {
-            rmSync(worktreePath, { recursive: true, force: true });
+            try {
+                rmSync(worktreePath, { recursive: true, force: true });
+            }
+            catch (rmErr) {
+                // WU-1014: Log but don't throw - git worktree remove succeeded, directory cleanup is best-effort
+                console.warn(`[git-adapter] worktreeRemove: git succeeded but directory cleanup failed for ${worktreePath}: ${rmErr instanceof Error ? rmErr.message : String(rmErr)}`);
+            }
         }
     }
     /**

package/dist/index.d.ts

@@ -40,3 +40,6 @@ export * from './dependency-guard.js';
 export * from './stamp-utils.js';
 export * from './lumenflow-config.js';
 export * from './lumenflow-config-schema.js';
+export * from './branch-check.js';
+export * from './lumenflow-home.js';
+export * from './spec-branch-helpers.js';

package/dist/index.js

@@ -59,3 +59,8 @@ export * from './stamp-utils.js';
 // Configuration
 export * from './lumenflow-config.js';
 export * from './lumenflow-config-schema.js';
+// Branch check utilities
+export * from './branch-check.js';
+// WU-1062: External plan storage and spec branch helpers
+export * from './lumenflow-home.js';
+export * from './spec-branch-helpers.js';

package/dist/lane-checker.d.ts

@@ -18,6 +18,22 @@ interface CheckLaneFreeResult {
     free: boolean;
     occupiedBy: string | null;
     error: string | null;
+    /** WU-1016: List of WU IDs currently in progress in this lane */
+    inProgressWUs?: string[];
+    /** WU-1016: The configured WIP limit for this lane */
+    wipLimit?: number;
+    /** WU-1016: Current count of in-progress WUs in this lane */
+    currentCount?: number;
+}
+/** WU-1016: Options for checkLaneFree */
+interface CheckLaneFreeOptions {
+    /** Path to .lumenflow.config.yaml (for testing) */
+    configPath?: string;
+}
+/** WU-1016: Options for getWipLimitForLane */
+interface GetWipLimitOptions {
+    /** Path to .lumenflow.config.yaml (for testing) */
+    configPath?: string;
 }
 export { getSubLanesForParent };
 /**
@@ -41,10 +57,27 @@ export declare function extractParent(lane: string): string;
  */
 export declare function validateLaneFormat(lane: string, configPath?: string | null, options?: ValidateLaneOptions): ValidateLaneResult;
 /**
- * Check if a lane is free (no in_progress WU currently in that lane)
+ * WU-1016: Get WIP limit for a lane from config
+ *
+ * Reads the wip_limit field from .lumenflow.config.yaml for the specified lane.
+ * Returns DEFAULT_WIP_LIMIT (1) if the lane is not found or wip_limit is not specified.
+ *
+ * @param {string} lane - Lane name (e.g., "Core", "CLI")
+ * @param {GetWipLimitOptions} options - Options including configPath for testing
+ * @returns {number} The WIP limit for the lane (default: 1)
+ */
+export declare function getWipLimitForLane(lane: string, options?: GetWipLimitOptions): number;
+/**
+ * Check if a lane is free (in_progress WU count is below wip_limit)
+ *
+ * WU-1016: Now respects configurable wip_limit per lane from .lumenflow.config.yaml.
+ * Lane is considered "free" if current in_progress count < wip_limit.
+ * Default wip_limit is 1 if not specified in config (backward compatible).
+ *
  * @param {string} statusPath - Path to status.md
  * @param {string} lane - Lane name (e.g., "Operations", "Intelligence")
  * @param {string} wuid - WU ID being claimed (e.g., "WU-419")
- * @returns {{ free: boolean, occupiedBy: string | null, error: string | null }}
+ * @param {CheckLaneFreeOptions} options - Options including configPath for testing
+ * @returns {{ free: boolean, occupiedBy: string | null, error: string | null, inProgressWUs?: string[], wipLimit?: number, currentCount?: number }}
  */
-export declare function checkLaneFree(statusPath: string, lane: string, wuid: string): CheckLaneFreeResult;
+export declare function checkLaneFree(statusPath: string, lane: string, wuid: string, options?: CheckLaneFreeOptions): CheckLaneFreeResult;