@lumenflow/core 2.4.0 → 2.5.1

package/dist/arg-parser.d.ts

@@ -32,6 +32,13 @@ export declare const WU_OPTIONS: Record<string, WUOption>;
  * These options control how wu:create handles external plan storage.
  */
 export declare const WU_CREATE_OPTIONS: Record<string, WUOption>;
+/**
+ * Negated options that commander handles specially.
+ * --no-foo creates opts.foo = false. We convert to noFoo = true.
+ *
+ * WU-1329: Export for testing purposes.
+ */
+export declare const NEGATED_OPTIONS: string[];
 /**
  * Create a commander-based CLI parser for a WU script.
  *

package/dist/arg-parser.js

@@ -438,6 +438,14 @@ export const WU_OPTIONS = {
         flags: '--skip-setup',
         description: 'Skip automatic pnpm install in worktree after creation (faster claims when deps already built)',
     },
+    // WU-1329: Strict validation options
+    // NOTE: --no-strict is the opt-out flag; strict is the default behavior
+    noStrict: {
+        name: 'noStrict',
+        flags: '--no-strict',
+        description: 'Bypass strict validation (skip code_paths/test_paths existence checks, treat warnings as advisory). Logged when used.',
+        isNegated: true,
+    },
 };
 /**
  * WU-1062: Additional options for wu:create command
@@ -458,8 +466,10 @@ export const WU_CREATE_OPTIONS = {
 /**
  * Negated options that commander handles specially.
  * --no-foo creates opts.foo = false. We convert to noFoo = true.
+ *
+ * WU-1329: Export for testing purposes.
  */
-const NEGATED_OPTIONS = ['auto', 'remove', 'merge', 'autoRebase', 'push'];
+export const NEGATED_OPTIONS = ['auto', 'remove', 'merge', 'autoRebase', 'push', 'strict'];
 /**
  * Post-process commander opts to handle negated boolean options.
  * Commander's --no-* flags create opts.foo = false.

package/dist/lane-checker.d.ts

@@ -6,6 +6,7 @@
  * Used by wu-claim.ts and wu-unblock.ts to prevent WIP violations.
  */
 import { getSubLanesForParent } from './lane-inference.js';
+import type { LockPolicy } from './lumenflow-config-schema.js';
 interface ValidateLaneOptions {
     strict?: boolean;
 }
@@ -61,13 +62,39 @@ export declare function validateLaneFormat(lane: string, configPath?: string | n
  * @returns {number} The WIP limit for the lane (default: 1)
  */
 export declare function getWipLimitForLane(lane: string, options?: GetWipLimitOptions): number;
+/** WU-1325: Options for getLockPolicyForLane */
+interface GetLockPolicyOptions {
+    /** Path to .lumenflow.config.yaml (for testing) */
+    configPath?: string;
+}
 /**
- * Check if a lane is free (in_progress WU count is below wip_limit)
+ * WU-1325: Get lock policy for a lane from config
+ *
+ * Reads the lock_policy field from .lumenflow.config.yaml for the specified lane.
+ * Returns DEFAULT_LOCK_POLICY ('all') if the lane is not found or lock_policy is not specified.
+ *
+ * Lock policies:
+ * - 'all' (default): Lock held through entire WU lifecycle (claim to done)
+ * - 'active': Lock released on block, re-acquired on unblock
+ * - 'none': No lock files created, WIP checking disabled for this lane
+ *
+ * @param {string} lane - Lane name (e.g., "Framework: Core", "Content: Documentation")
+ * @param {GetLockPolicyOptions} options - Options including configPath for testing
+ * @returns {LockPolicy} The lock policy for the lane (default: 'all')
+ */
+export declare function getLockPolicyForLane(lane: string, options?: GetLockPolicyOptions): LockPolicy;
+/**
+ * Check if a lane is free (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.
+ * Lane is considered "free" if current WU count < wip_limit.
  * Default wip_limit is 1 if not specified in config (backward compatible).
  *
+ * WU-1324: Now respects lock_policy for WIP counting:
+ * - 'all' (default): Count in_progress + blocked WUs toward WIP limit
+ * - 'active': Count only in_progress WUs (blocked WUs release lane lock)
+ * - 'none': Disable WIP checking entirely (lane always free)
+ *
  * @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")

package/dist/lane-checker.js

@@ -35,6 +35,15 @@ export function extractParent(lane) {
     // Sub-lane format: extract parent before colon
     return trimmed.substring(0, colonIndex).trim();
 }
+/**
+ * WU-1308: Check if lane-inference.yaml file exists
+ * @returns {boolean} True if the file exists
+ */
+function laneInferenceFileExists() {
+    const projectRoot = findProjectRoot();
+    const taxonomyPath = path.join(projectRoot, CONFIG_FILES.LANE_INFERENCE);
+    return existsSync(taxonomyPath);
+}
 /**
  * Check if a parent lane has sub-lane taxonomy defined
  * @param {string} parent - Parent lane name
@@ -141,6 +150,17 @@ function validateSubLaneFormat(lane, trimmed, colonIndex, configPath) {
     if (!isValidParentLane(parent, configPath)) {
         throw createError(ErrorCodes.INVALID_LANE, `Unknown parent lane: "${parent}". Check ${CONFIG_FILES.LUMENFLOW_CONFIG} for valid lanes.`, { parent, lane });
     }
+    // WU-1308: Check if lane-inference file exists before validating sub-lanes
+    // This provides a clear error message when the file is missing
+    if (!laneInferenceFileExists()) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Sub-lane validation requires ${CONFIG_FILES.LANE_INFERENCE} which is missing.\n\n` +
+            `The file "${CONFIG_FILES.LANE_INFERENCE}" defines the lane taxonomy for sub-lane validation.\n\n` +
+            `To fix this:\n` +
+            `  1. Generate a lane taxonomy from your codebase:\n` +
+            `     pnpm lane:suggest --output ${CONFIG_FILES.LANE_INFERENCE}\n\n` +
+            `  2. Or copy from an example project and customize.\n\n` +
+            `See: LUMENFLOW.md "Setup Notes" section for details.`, { lane, parent, subdomain, missingFile: CONFIG_FILES.LANE_INFERENCE });
+    }
     // Validate sub-lane exists in taxonomy
     if (hasSubLaneTaxonomy(parent)) {
         validateSubLaneInTaxonomy(parent, subdomain);
@@ -342,6 +362,78 @@ export function getWipLimitForLane(lane, options = {}) {
         return DEFAULT_WIP_LIMIT;
     }
 }
+/** WU-1325: Default lock policy when not specified in config */
+const DEFAULT_LOCK_POLICY = 'all';
+/**
+ * WU-1325: Get lock policy for a lane from config
+ *
+ * Reads the lock_policy field from .lumenflow.config.yaml for the specified lane.
+ * Returns DEFAULT_LOCK_POLICY ('all') if the lane is not found or lock_policy is not specified.
+ *
+ * Lock policies:
+ * - 'all' (default): Lock held through entire WU lifecycle (claim to done)
+ * - 'active': Lock released on block, re-acquired on unblock
+ * - 'none': No lock files created, WIP checking disabled for this lane
+ *
+ * @param {string} lane - Lane name (e.g., "Framework: Core", "Content: Documentation")
+ * @param {GetLockPolicyOptions} options - Options including configPath for testing
+ * @returns {LockPolicy} The lock policy for the lane (default: 'all')
+ */
+export function getLockPolicyForLane(lane, options = {}) {
+    // Determine config path
+    let resolvedConfigPath = options.configPath;
+    if (!resolvedConfigPath) {
+        const projectRoot = findProjectRoot();
+        resolvedConfigPath = path.join(projectRoot, CONFIG_FILES.LUMENFLOW_CONFIG);
+    }
+    // Check if config file exists
+    if (!existsSync(resolvedConfigPath)) {
+        return DEFAULT_LOCK_POLICY;
+    }
+    try {
+        const configContent = readFileSync(resolvedConfigPath, { encoding: 'utf-8' });
+        const config = parseYAML(configContent);
+        if (!config.lanes) {
+            return DEFAULT_LOCK_POLICY;
+        }
+        // Normalize lane name for case-insensitive comparison
+        const normalizedLane = lane.toLowerCase().trim();
+        // Extract all lanes with their lock_policy
+        let allLanes = [];
+        if (Array.isArray(config.lanes)) {
+            // Flat array format: lanes: [{name: "Core", lock_policy: "none"}, ...]
+            allLanes = config.lanes;
+        }
+        else {
+            // New format with definitions
+            if (config.lanes.definitions) {
+                allLanes.push(...config.lanes.definitions);
+            }
+            // Legacy nested format: lanes: {engineering: [...], business: [...]}
+            if (config.lanes.engineering) {
+                allLanes.push(...config.lanes.engineering);
+            }
+            if (config.lanes.business) {
+                allLanes.push(...config.lanes.business);
+            }
+        }
+        // Find matching lane (case-insensitive)
+        const matchingLane = allLanes.find((l) => l.name.toLowerCase().trim() === normalizedLane);
+        if (!matchingLane) {
+            return DEFAULT_LOCK_POLICY;
+        }
+        // Return lock_policy if specified and valid, otherwise default
+        const policy = matchingLane.lock_policy;
+        if (policy === 'all' || policy === 'active' || policy === 'none') {
+            return policy;
+        }
+        return DEFAULT_LOCK_POLICY;
+    }
+    catch {
+        // If config parsing fails, return default
+        return DEFAULT_LOCK_POLICY;
+    }
+}
 /** WU-1197: Section heading marker for H2 headings */
 const SECTION_HEADING_PREFIX = '## ';
 /**
@@ -379,6 +471,38 @@ function extractInProgressSection(lines) {
     const section = lines.slice(inProgressIdx + 1, endIdx).join(STRING_LITERALS.NEWLINE);
     return { section, error: null };
 }
+/** WU-1324: Blocked section header patterns */
+const BLOCKED_HEADERS = ['## blocked', '## ⛔ blocked'];
+/**
+ * WU-1324: Check if a line matches a Blocked section header.
+ * @param {string} line - Line to check (will be trimmed and lowercased)
+ * @returns {boolean} True if line is a Blocked header
+ */
+function isBlockedHeader(line) {
+    const normalized = line.trim().toLowerCase();
+    return BLOCKED_HEADERS.some((header) => normalized === header || normalized.startsWith(header));
+}
+/**
+ * WU-1324: Extract Blocked section from status.md lines
+ * @returns Section content (may be empty if section doesn't exist)
+ */
+function extractBlockedSection(lines) {
+    const blockedIdx = lines.findIndex((l) => isBlockedHeader(l));
+    if (blockedIdx === -1) {
+        // Blocked section doesn't exist - return empty
+        return { section: '' };
+    }
+    // Find end of Blocked section (next ## heading or end of file)
+    let endIdx = lines.slice(blockedIdx + 1).findIndex((l) => l.startsWith(SECTION_HEADING_PREFIX));
+    if (endIdx === -1) {
+        endIdx = lines.length - blockedIdx - 1;
+    }
+    else {
+        endIdx = blockedIdx + 1 + endIdx;
+    }
+    const section = lines.slice(blockedIdx + 1, endIdx).join(STRING_LITERALS.NEWLINE);
+    return { section };
+}
 /**
  * WU-1197: Check if a WU belongs to the target lane
  * @returns The WU ID if it matches the target lane, null otherwise
@@ -430,12 +554,37 @@ function collectInProgressWUsForLane(matches, wuid, projectRoot, targetLane) {
     return inProgressWUs;
 }
 /**
- * Check if a lane is free (in_progress WU count is below wip_limit)
+ * WU-1324: Extract WU IDs from a section's WU links and filter by target lane
+ * @param section - Section content from status.md
+ * @param wuid - WU ID being claimed (excluded from results)
+ * @param projectRoot - Project root path
+ * @param targetLane - Target lane name (normalized lowercase)
+ * @returns Array of WU IDs in the target lane
+ */
+function extractWUsFromSection(section, wuid, projectRoot, targetLane) {
+    if (!section || section.includes(NO_ITEMS_MARKER)) {
+        return [];
+    }
+    // Extract WU IDs from links like [WU-334 — Title](wu/WU-334.yaml)
+    WU_LINK_PATTERN.lastIndex = 0; // Reset global regex state
+    const matches = [...section.matchAll(WU_LINK_PATTERN)];
+    if (matches.length === 0) {
+        return [];
+    }
+    return collectInProgressWUsForLane(matches, wuid, projectRoot, targetLane);
+}
+/**
+ * Check if a lane is free (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.
+ * Lane is considered "free" if current WU count < wip_limit.
  * Default wip_limit is 1 if not specified in config (backward compatible).
  *
+ * WU-1324: Now respects lock_policy for WIP counting:
+ * - 'all' (default): Count in_progress + blocked WUs toward WIP limit
+ * - 'active': Count only in_progress WUs (blocked WUs release lane lock)
+ * - 'none': Disable WIP checking entirely (lane always free)
+ *
  * @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")
@@ -444,40 +593,47 @@ function collectInProgressWUsForLane(matches, wuid, projectRoot, targetLane) {
  */
 export function checkLaneFree(statusPath, lane, wuid, options = {}) {
     try {
+        // WU-1016: Get WIP limit for this lane from config
+        const wipLimit = getWipLimitForLane(lane, { configPath: options.configPath });
+        // WU-1324: Get lock policy for this lane from config
+        const lockPolicy = getLockPolicyForLane(lane, { configPath: options.configPath });
+        // WU-1324: If policy is 'none', WIP checking is disabled - lane is always free
+        if (lockPolicy === 'none') {
+            return createEmptyLaneResult(wipLimit);
+        }
         // Read status.md
         if (!existsSync(statusPath)) {
             return { free: false, occupiedBy: null, error: `status.md not found: ${statusPath}` };
         }
         const content = readFileSync(statusPath, { encoding: 'utf-8' });
         const lines = content.split(/\r?\n/);
-        const { section, error } = extractInProgressSection(lines);
+        // Extract In Progress section
+        const { section: inProgressSection, error } = extractInProgressSection(lines);
         if (error) {
             return { free: false, occupiedBy: null, error };
         }
-        // WU-1016: Get WIP limit for this lane from config
-        const wipLimit = getWipLimitForLane(lane, { configPath: options.configPath });
-        // Check for "No items" marker or no WU links
-        if (section.includes(NO_ITEMS_MARKER)) {
-            return createEmptyLaneResult(wipLimit);
-        }
-        // Extract WU IDs from links like [WU-334 — Title](wu/WU-334.yaml)
-        WU_LINK_PATTERN.lastIndex = 0; // Reset global regex state
-        const matches = [...section.matchAll(WU_LINK_PATTERN)];
-        if (matches.length === 0) {
-            return createEmptyLaneResult(wipLimit);
-        }
         // Get project root from statusPath (docs/04-operations/tasks/status.md)
         const projectRoot = path.dirname(path.dirname(path.dirname(path.dirname(statusPath))));
         const targetLane = lane.toString().trim().toLowerCase();
-        const inProgressWUs = collectInProgressWUsForLane(matches, wuid, projectRoot, targetLane);
-        // WU-1016: Check if lane is free based on WIP limit
-        const currentCount = inProgressWUs.length;
+        // Collect in_progress WUs
+        const inProgressWUs = extractWUsFromSection(inProgressSection, wuid, projectRoot, targetLane);
+        // WU-1324: If policy is 'all', also count blocked WUs
+        let blockedWUs = [];
+        if (lockPolicy === 'all') {
+            const { section: blockedSection } = extractBlockedSection(lines);
+            blockedWUs = extractWUsFromSection(blockedSection, wuid, projectRoot, targetLane);
+        }
+        // WU-1324: Calculate total count based on policy
+        // - 'all': in_progress + blocked
+        // - 'active': in_progress only
+        const allCountedWUs = [...inProgressWUs, ...blockedWUs];
+        const currentCount = allCountedWUs.length;
         const isFree = currentCount < wipLimit;
         return {
             free: isFree,
-            occupiedBy: isFree ? null : inProgressWUs[0] || null,
+            occupiedBy: isFree ? null : allCountedWUs[0] || null,
             error: null,
-            inProgressWUs,
+            inProgressWUs: allCountedWUs, // Include all counted WUs for visibility
             wipLimit,
             currentCount,
         };

package/dist/lane-lock.d.ts

@@ -12,7 +12,13 @@
  * Lock file location: .lumenflow/locks/<lane-kebab>.lock
  * Lock file format: JSON with wuId, timestamp, agentSession, pid
  *
+ * Lock policy support (WU-1323):
+ * - 'all' (default): Lock held through entire WU lifecycle
+ * - 'active': Lock released on block, re-acquired on unblock (CLI behavior)
+ * - 'none': No lock files created, WIP checking disabled for the lane
+ *
  * @see WU-1603 - Race condition fix for wu:claim
+ * @see WU-1323 - Lock policy integration tests
  */
 export interface LockMetadata {
     wuId: string;
@@ -26,6 +32,8 @@ interface LockResult {
     error: string | null;
     existingLock: LockMetadata | null;
     isStale: boolean;
+    /** WU-1325: True if lock acquisition was skipped due to lock_policy=none */
+    skipped?: boolean;
 }
 interface UnlockResult {
     released: boolean;

package/dist/lane-lock.js

@@ -12,11 +12,19 @@
  * Lock file location: .lumenflow/locks/<lane-kebab>.lock
  * Lock file format: JSON with wuId, timestamp, agentSession, pid
  *
+ * Lock policy support (WU-1323):
+ * - 'all' (default): Lock held through entire WU lifecycle
+ * - 'active': Lock released on block, re-acquired on unblock (CLI behavior)
+ * - 'none': No lock files created, WIP checking disabled for the lane
+ *
  * @see WU-1603 - Race condition fix for wu:claim
+ * @see WU-1323 - Lock policy integration tests
  */
 import { openSync, closeSync, writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync, } from 'node:fs';
 import path from 'node:path';
 import { toKebab, LUMENFLOW_PATHS, getProjectRoot } from './wu-constants.js';
+// WU-1325: Import lock policy getter
+import { getLockPolicyForLane } from './lane-checker.js';
 /** Log prefix for lane-lock messages */
 const LOG_PREFIX = '[lane-lock]';
 /** Directory for lock files relative to project root */
@@ -169,6 +177,19 @@ export function readLockMetadata(lockPath) {
 // eslint-disable-next-line sonarjs/cognitive-complexity -- WU-1808: Added zombie lock detection increases complexity but all paths are necessary
 export function acquireLaneLock(lane, wuId, options = {}) {
     const { agentSession = null, baseDir = null } = options;
+    // WU-1325: Check lock policy before acquiring
+    const lockPolicy = getLockPolicyForLane(lane);
+    if (lockPolicy === 'none') {
+        // eslint-disable-next-line no-console -- CLI tool status message
+        console.log(`${LOG_PREFIX} Skipping lock acquisition for "${lane}" (lock_policy=none)`);
+        return {
+            acquired: true,
+            error: null,
+            existingLock: null,
+            isStale: false,
+            skipped: true,
+        };
+    }
     try {
         ensureLocksDir(baseDir);
         const lockPath = getLockFilePath(lane, baseDir);