@lumenflow/core 2.2.2 → 2.3.1

package/dist/lane-checker.js

@@ -3,7 +3,7 @@
  * Lane Occupancy Checker
  *
  * Enforces one-WU-per-lane rule by checking status.md for active WUs in a given lane.
- * Used by wu-claim.mjs and wu-unblock.mjs to prevent WIP violations.
+ * Used by wu-claim.ts and wu-unblock.ts to prevent WIP violations.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
@@ -114,6 +114,77 @@ const SPACE = ' ';
  * @property {boolean} [strict=true] - When true, throws error for parent-only lanes with taxonomy.
  *                                     When false, only warns (for existing WU validation).
  */
+/**
+ * WU-1197: Validate colon format in lane string
+ * @throws {LumenflowError} If format is invalid
+ */
+function validateColonFormat(lane, trimmed, colonIndex) {
+    // Check for space before colon
+    if (colonIndex > 0 && trimmed[colonIndex - 1] === SPACE) {
+        throw createError(ErrorCodes.INVALID_LANE, `Invalid lane format: "${lane}" has space before colon. Expected format: "Parent: Subdomain" (space AFTER colon only)`, { lane });
+    }
+    // Check for space after colon
+    if (colonIndex + 1 >= trimmed.length || trimmed[colonIndex + 1] !== SPACE) {
+        throw createError(ErrorCodes.INVALID_LANE, `Invalid lane format: "${lane}" is missing space after colon. Expected format: "Parent: Subdomain"`, { lane });
+    }
+}
+/**
+ * WU-1197: Validate sub-lane format (Parent: Subdomain)
+ * @throws {LumenflowError} If validation fails
+ */
+function validateSubLaneFormat(lane, trimmed, colonIndex, configPath) {
+    validateColonFormat(lane, trimmed, colonIndex);
+    // Extract parent and subdomain (colonIndex + 2 = skip colon and space)
+    const parent = trimmed.substring(0, colonIndex).trim();
+    const subdomain = trimmed.substring(colonIndex + LANE_SEPARATOR.length + SPACE.length).trim();
+    // Validate parent exists in config
+    if (!isValidParentLane(parent, configPath)) {
+        throw createError(ErrorCodes.INVALID_LANE, `Unknown parent lane: "${parent}". Check ${CONFIG_FILES.LUMENFLOW_CONFIG} for valid lanes.`, { parent, lane });
+    }
+    // Validate sub-lane exists in taxonomy
+    if (hasSubLaneTaxonomy(parent)) {
+        validateSubLaneInTaxonomy(parent, subdomain);
+    }
+    else {
+        // Parent has no taxonomy - reject sub-lane format
+        throw createError(ErrorCodes.INVALID_LANE, `Parent lane "${parent}" does not support sub-lanes. Use parent-only format or extend ${CONFIG_FILES.LANE_INFERENCE}.`, { parent, lane });
+    }
+    return { valid: true, parent, error: null };
+}
+/**
+ * WU-1197: Validate that sub-lane exists in taxonomy
+ * @throws {LumenflowError} If sub-lane is not valid
+ */
+function validateSubLaneInTaxonomy(parent, subdomain) {
+    if (!isValidSubLane(parent, subdomain)) {
+        const validSubLanes = getSubLanesForParent(parent);
+        throw createError(ErrorCodes.INVALID_LANE, `Unknown sub-lane: "${subdomain}" for parent lane "${parent}".\n\n` +
+            `Valid sub-lanes: ${validSubLanes.join(', ')}`, { parent, subdomain, validSubLanes });
+    }
+}
+/**
+ * WU-1197: Validate parent-only lane format
+ * @throws {LumenflowError} If validation fails (in strict mode)
+ */
+function validateParentOnlyFormat(trimmed, configPath, strict) {
+    if (!isValidParentLane(trimmed, configPath)) {
+        throw createError(ErrorCodes.INVALID_LANE, `Unknown parent lane: "${trimmed}". Check ${CONFIG_FILES.LUMENFLOW_CONFIG} for valid lanes.`, { lane: trimmed });
+    }
+    // Block if parent has sub-lane taxonomy (sub-lane required)
+    if (hasSubLaneTaxonomy(trimmed)) {
+        const validSubLanes = getSubLanesForParent(trimmed);
+        const message = `Parent-only lane "${trimmed}" blocked. Sub-lane required. ` +
+            `Valid: ${validSubLanes.join(', ')}. ` +
+            `Format: "${trimmed}: <sublane>"`;
+        if (strict) {
+            throw createError(ErrorCodes.INVALID_LANE, message, { lane: trimmed, validSubLanes });
+        }
+        // Non-strict mode: warn only for existing WU validation
+        // eslint-disable-next-line no-console -- Intentional operational logging
+        console.warn(`${PREFIX} ⚠️  ${message}`);
+    }
+    return { valid: true, parent: trimmed, error: null };
+}
 /**
  * Validate lane format and parent existence
  * @param {string} lane - Lane name (e.g., "Operations: Tooling" or "Operations")
@@ -129,62 +200,55 @@ export function validateLaneFormat(lane, configPath = null, options = {}) {
     if (colonCount > 1) {
         throw createError(ErrorCodes.INVALID_LANE, `Invalid lane format: "${lane}" contains multiple colons. Expected format: "Parent: Subdomain" or "Parent"`, { lane });
     }
-    // Check for colon
     const colonIndex = trimmed.indexOf(LANE_SEPARATOR);
-    if (colonIndex !== -1) {
-        // Sub-lane format validation
-        // Check for space before colon
-        if (colonIndex > 0 && trimmed[colonIndex - 1] === SPACE) {
-            throw createError(ErrorCodes.INVALID_LANE, `Invalid lane format: "${lane}" has space before colon. Expected format: "Parent: Subdomain" (space AFTER colon only)`, { lane });
-        }
-        // Check for space after colon
-        if (colonIndex + 1 >= trimmed.length || trimmed[colonIndex + 1] !== SPACE) {
-            throw createError(ErrorCodes.INVALID_LANE, `Invalid lane format: "${lane}" is missing space after colon. Expected format: "Parent: Subdomain"`, { lane });
-        }
-        // Extract parent and subdomain (colonIndex + 2 = skip colon and space)
-        const parent = trimmed.substring(0, colonIndex).trim();
-        const subdomain = trimmed.substring(colonIndex + LANE_SEPARATOR.length + SPACE.length).trim();
-        // Validate parent exists in config
-        if (!isValidParentLane(parent, configPath)) {
-            throw createError(ErrorCodes.INVALID_LANE, `Unknown parent lane: "${parent}". Check ${CONFIG_FILES.LUMENFLOW_CONFIG} for valid lanes.`, { parent, lane });
-        }
-        // Validate sub-lane exists in taxonomy
-        if (hasSubLaneTaxonomy(parent)) {
-            // Parent has taxonomy - validate sub-lane
-            if (!isValidSubLane(parent, subdomain)) {
-                const validSubLanes = getSubLanesForParent(parent);
-                throw createError(ErrorCodes.INVALID_LANE, `Unknown sub-lane: "${subdomain}" for parent lane "${parent}".\n\n` +
-                    `Valid sub-lanes: ${validSubLanes.join(', ')}`, { parent, subdomain, validSubLanes });
-            }
-        }
-        else {
-            // Parent has no taxonomy - reject sub-lane format
-            throw createError(ErrorCodes.INVALID_LANE, `Parent lane "${parent}" does not support sub-lanes. Use parent-only format or extend ${CONFIG_FILES.LANE_INFERENCE}.`, { parent, lane });
-        }
-        return { valid: true, parent, error: null };
+    const isSubLaneFormat = colonIndex !== -1;
+    if (isSubLaneFormat) {
+        return validateSubLaneFormat(lane, trimmed, colonIndex, configPath);
     }
-    else {
-        // Parent-only format
-        if (!isValidParentLane(trimmed, configPath)) {
-            throw createError(ErrorCodes.INVALID_LANE, `Unknown parent lane: "${trimmed}". Check ${CONFIG_FILES.LUMENFLOW_CONFIG} for valid lanes.`, { lane: trimmed });
-        }
-        // Block if parent has sub-lane taxonomy (sub-lane required)
-        if (hasSubLaneTaxonomy(trimmed)) {
-            const validSubLanes = getSubLanesForParent(trimmed);
-            const message = `Parent-only lane "${trimmed}" blocked. Sub-lane required. ` +
-                `Valid: ${validSubLanes.join(', ')}. ` +
-                `Format: "${trimmed}: <sublane>"`;
-            if (strict) {
-                // Strict mode (default): throw error for new WUs
-                throw createError(ErrorCodes.INVALID_LANE, message, { lane: trimmed, validSubLanes });
-            }
-            else {
-                // Non-strict mode: warn only for existing WU validation
-                console.warn(`${PREFIX} ⚠️  ${message}`);
-            }
+    return validateParentOnlyFormat(trimmed, configPath, strict);
+}
+/**
+ * WU-1197: Extract lane names and parent lanes from config
+ * Handles flat array, definitions, and legacy nested formats
+ */
+function extractLanesForParentCheck(config) {
+    const allLanes = [];
+    const parentLanes = new Set();
+    if (!config.lanes) {
+        return { allLanes, parentLanes };
+    }
+    if (Array.isArray(config.lanes)) {
+        // Flat array format: lanes: [{name: "Core"}, {name: "CLI"}, ...]
+        allLanes.push(...config.lanes.map((l) => l.name));
+        return { allLanes, parentLanes };
+    }
+    // WU-1022: New format with lanes.definitions containing full "Parent: Sublane" names
+    if (config.lanes.definitions) {
+        for (const lane of config.lanes.definitions) {
+            allLanes.push(lane.name);
+            // Extract parent from full lane name for parent validation
+            const extracted = extractParent(lane.name);
+            parentLanes.add(extracted.toLowerCase().trim());
         }
-        return { valid: true, parent: trimmed, error: null };
     }
+    // Legacy nested format: lanes: {engineering: [...], business: [...]}
+    if (config.lanes.engineering) {
+        allLanes.push(...config.lanes.engineering.map((l) => l.name));
+    }
+    if (config.lanes.business) {
+        allLanes.push(...config.lanes.business.map((l) => l.name));
+    }
+    return { allLanes, parentLanes };
+}
+/**
+ * WU-1197: Resolve config path, defaulting to project root if not provided
+ */
+function resolveConfigPath(configPath) {
+    if (configPath) {
+        return configPath;
+    }
+    const projectRoot = findProjectRoot();
+    return path.join(projectRoot, CONFIG_FILES.LUMENFLOW_CONFIG);
 }
 /**
  * Check if a parent lane exists in LumenFlow config
@@ -197,12 +261,7 @@ export function validateLaneFormat(lane, configPath = null, options = {}) {
  * @returns {boolean} True if parent lane exists
  */
 function isValidParentLane(parent, configPath = null) {
-    // Determine config path
-    let resolvedConfigPath = configPath;
-    if (!resolvedConfigPath) {
-        const projectRoot = findProjectRoot();
-        resolvedConfigPath = path.join(projectRoot, CONFIG_FILES.LUMENFLOW_CONFIG);
-    }
+    const resolvedConfigPath = resolveConfigPath(configPath);
     // Read and parse config
     if (!existsSync(resolvedConfigPath)) {
         throw createError(ErrorCodes.FILE_NOT_FOUND, `Config file not found: ${resolvedConfigPath}`, {
@@ -211,34 +270,7 @@ function isValidParentLane(parent, configPath = null) {
     }
     const configContent = readFileSync(resolvedConfigPath, { encoding: 'utf-8' });
     const config = parseYAML(configContent);
-    // Extract all lane names - handle multiple config formats
-    const allLanes = [];
-    const parentLanes = new Set();
-    if (config.lanes) {
-        if (Array.isArray(config.lanes)) {
-            // Flat array format: lanes: [{name: "Core"}, {name: "CLI"}, ...]
-            allLanes.push(...config.lanes.map((l) => l.name));
-        }
-        else {
-            // WU-1022: New format with lanes.definitions containing full "Parent: Sublane" names
-            if (config.lanes.definitions) {
-                for (const lane of config.lanes.definitions) {
-                    allLanes.push(lane.name);
-                    // Extract parent from full lane name for parent validation
-                    const extractedParent = extractParent(lane.name);
-                    parentLanes.add(extractedParent.toLowerCase().trim());
-                }
-            }
-            // Legacy nested format: lanes: {engineering: [...], business: [...]}
-            if (config.lanes.engineering) {
-                allLanes.push(...config.lanes.engineering.map((l) => l.name));
-            }
-            if (config.lanes.business) {
-                allLanes.push(...config.lanes.business.map((l) => l.name));
-            }
-        }
-    }
-    // Case-insensitive comparison
+    const { allLanes, parentLanes } = extractLanesForParentCheck(config);
     const normalizedParent = parent.toLowerCase().trim();
     // WU-1022: If we have extracted parent lanes (from full lane names), check against those
     if (parentLanes.size > 0) {
@@ -285,7 +317,11 @@ export function getWipLimitForLane(lane, options = {}) {
             allLanes = config.lanes;
         }
         else {
-            // Nested format: lanes: {engineering: [...], business: [...]}
+            // 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);
             }
@@ -306,6 +342,93 @@ export function getWipLimitForLane(lane, options = {}) {
         return DEFAULT_WIP_LIMIT;
     }
 }
+/** WU-1197: Section heading marker for H2 headings */
+const SECTION_HEADING_PREFIX = '## ';
+/**
+ * WU-1197: Create an empty lane result (no WUs in progress)
+ */
+function createEmptyLaneResult(wipLimit) {
+    return {
+        free: true,
+        occupiedBy: null,
+        error: null,
+        inProgressWUs: [],
+        wipLimit,
+        currentCount: 0,
+    };
+}
+/**
+ * WU-1197: Extract In Progress section from status.md lines
+ * @returns Section content or null if not found
+ */
+function extractInProgressSection(lines) {
+    const inProgressIdx = lines.findIndex((l) => isInProgressHeader(l));
+    if (inProgressIdx === -1) {
+        return { section: '', error: 'Could not find "## In Progress" section in status.md' };
+    }
+    // Find end of In Progress section (next ## heading or end of file)
+    let endIdx = lines
+        .slice(inProgressIdx + 1)
+        .findIndex((l) => l.startsWith(SECTION_HEADING_PREFIX));
+    if (endIdx === -1) {
+        endIdx = lines.length - inProgressIdx - 1;
+    }
+    else {
+        endIdx = inProgressIdx + 1 + endIdx;
+    }
+    const section = lines.slice(inProgressIdx + 1, endIdx).join(STRING_LITERALS.NEWLINE);
+    return { section, error: null };
+}
+/**
+ * WU-1197: Check if a WU belongs to the target lane
+ * @returns The WU ID if it matches the target lane, null otherwise
+ */
+function checkWuLaneMatch(activeWuid, wuid, projectRoot, targetLane) {
+    // Skip if it's the same WU we're trying to claim
+    if (activeWuid === wuid) {
+        return null;
+    }
+    const wuPath = path.join(projectRoot, WU_PATHS.WU(activeWuid));
+    if (!existsSync(wuPath)) {
+        // eslint-disable-next-line no-console -- Intentional operational logging
+        console.warn(`${PREFIX} Warning: ${activeWuid} referenced in status.md but ${wuPath} not found`);
+        return null;
+    }
+    try {
+        const wuContent = readFileSync(wuPath, { encoding: 'utf-8' });
+        const wuDoc = parseYAML(wuContent);
+        if (!wuDoc || !wuDoc.lane) {
+            // eslint-disable-next-line no-console -- Intentional operational logging
+            console.warn(`${PREFIX} Warning: ${activeWuid} has no lane field`);
+            return null;
+        }
+        // Normalize lane names for comparison (case-insensitive, trim whitespace)
+        const activeLane = wuDoc.lane.toString().trim().toLowerCase();
+        if (activeLane === targetLane) {
+            return activeWuid;
+        }
+    }
+    catch (e) {
+        const errMessage = e instanceof Error ? e.message : String(e);
+        // eslint-disable-next-line no-console -- Intentional operational logging
+        console.warn(`${PREFIX} Warning: Failed to parse ${activeWuid} YAML: ${errMessage}`);
+    }
+    return null;
+}
+/**
+ * WU-1197: Collect WUs in the target lane from matched WU links
+ */
+function collectInProgressWUsForLane(matches, wuid, projectRoot, targetLane) {
+    const inProgressWUs = [];
+    for (const match of matches) {
+        const activeWuid = match[1]; // e.g., "WU-334"
+        const matchedWu = checkWuLaneMatch(activeWuid, wuid, projectRoot, targetLane);
+        if (matchedWu) {
+            inProgressWUs.push(matchedWu);
+        }
+    }
+    return inProgressWUs;
+}
 /**
  * Check if a lane is free (in_progress WU count is below wip_limit)
  *
@@ -320,8 +443,6 @@ export function getWipLimitForLane(lane, options = {}) {
  * @returns {{ free: boolean, occupiedBy: string | null, error: string | null, inProgressWUs?: string[], wipLimit?: number, currentCount?: number }}
  */
 export function checkLaneFree(statusPath, lane, wuid, options = {}) {
-    /** Section heading marker for H2 headings */
-    const SECTION_HEADING_PREFIX = '## ';
     try {
         // Read status.md
         if (!existsSync(statusPath)) {
@@ -329,88 +450,26 @@ export function checkLaneFree(statusPath, lane, wuid, options = {}) {
         }
         const content = readFileSync(statusPath, { encoding: 'utf-8' });
         const lines = content.split(/\r?\n/);
-        // Find "## In Progress" section
-        const inProgressIdx = lines.findIndex((l) => isInProgressHeader(l));
-        if (inProgressIdx === -1) {
-            return {
-                free: false,
-                occupiedBy: null,
-                error: 'Could not find "## In Progress" section in status.md',
-            };
+        const { section, error } = extractInProgressSection(lines);
+        if (error) {
+            return { free: false, occupiedBy: null, error };
         }
-        // Find end of In Progress section (next ## heading or end of file)
-        let endIdx = lines
-            .slice(inProgressIdx + 1)
-            .findIndex((l) => l.startsWith(SECTION_HEADING_PREFIX));
-        if (endIdx === -1)
-            endIdx = lines.length - inProgressIdx - 1;
-        else
-            endIdx = inProgressIdx + 1 + endIdx;
-        // Extract WU links from In Progress section
-        const section = lines.slice(inProgressIdx + 1, endIdx).join(STRING_LITERALS.NEWLINE);
         // WU-1016: Get WIP limit for this lane from config
         const wipLimit = getWipLimitForLane(lane, { configPath: options.configPath });
-        // Check for "No items" marker
+        // Check for "No items" marker or no WU links
         if (section.includes(NO_ITEMS_MARKER)) {
-            return {
-                free: true,
-                occupiedBy: null,
-                error: null,
-                inProgressWUs: [],
-                wipLimit,
-                currentCount: 0,
-            };
+            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 {
-                free: true,
-                occupiedBy: null,
-                error: null,
-                inProgressWUs: [],
-                wipLimit,
-                currentCount: 0,
-            };
+            return createEmptyLaneResult(wipLimit);
         }
         // Get project root from statusPath (docs/04-operations/tasks/status.md)
-        // Use path.dirname 4 times: status.md -> tasks -> 04-operations -> docs -> root
         const projectRoot = path.dirname(path.dirname(path.dirname(path.dirname(statusPath))));
-        // WU-1016: Collect all WUs in the target lane
-        const inProgressWUs = [];
         const targetLane = lane.toString().trim().toLowerCase();
-        for (const match of matches) {
-            const activeWuid = match[1]; // e.g., "WU-334"
-            // Skip if it's the same WU we're trying to claim (shouldn't happen, but be safe)
-            if (activeWuid === wuid)
-                continue;
-            // Use WU_PATHS to build the path consistently
-            const wuPath = path.join(projectRoot, WU_PATHS.WU(activeWuid));
-            if (!existsSync(wuPath)) {
-                console.warn(`${PREFIX} Warning: ${activeWuid} referenced in status.md but ${wuPath} not found`);
-                continue;
-            }
-            try {
-                const wuContent = readFileSync(wuPath, { encoding: 'utf-8' });
-                const wuDoc = parseYAML(wuContent);
-                if (!wuDoc || !wuDoc.lane) {
-                    console.warn(`${PREFIX} Warning: ${activeWuid} has no lane field`);
-                    continue;
-                }
-                // Normalize lane names for comparison (case-insensitive, trim whitespace)
-                const activeLane = wuDoc.lane.toString().trim().toLowerCase();
-                if (activeLane === targetLane) {
-                    // WU-1016: Add to list of in-progress WUs in this lane
-                    inProgressWUs.push(activeWuid);
-                }
-            }
-            catch (e) {
-                const errMessage = e instanceof Error ? e.message : String(e);
-                console.warn(`${PREFIX} Warning: Failed to parse ${activeWuid} YAML: ${errMessage}`);
-                continue;
-            }
-        }
+        const inProgressWUs = collectInProgressWUsForLane(matches, wuid, projectRoot, targetLane);
         // WU-1016: Check if lane is free based on WIP limit
         const currentCount = inProgressWUs.length;
         const isFree = currentCount < wipLimit;
@@ -428,3 +487,101 @@ export function checkLaneFree(statusPath, lane, wuid, options = {}) {
         return { free: false, occupiedBy: null, error: `Unexpected error: ${errMessage}` };
     }
 }
+/** WU-1187: Default result when no justification is required */
+const NO_JUSTIFICATION_REQUIRED = {
+    valid: true,
+    warning: null,
+    requiresJustification: false,
+};
+/**
+ * WU-1187: Extract all lanes from config (handles all config formats)
+ * @param config - Parsed LumenFlow config
+ * @returns Array of lane configs with wip settings
+ */
+function extractAllLanesFromConfig(config) {
+    if (!config.lanes) {
+        return [];
+    }
+    if (Array.isArray(config.lanes)) {
+        // Flat array format: lanes: [{name: "Core", wip_limit: 2}, ...]
+        return config.lanes;
+    }
+    // Nested formats with definitions, engineering, business
+    const allLanes = [];
+    if (config.lanes.definitions) {
+        allLanes.push(...config.lanes.definitions);
+    }
+    if (config.lanes.engineering) {
+        allLanes.push(...config.lanes.engineering);
+    }
+    if (config.lanes.business) {
+        allLanes.push(...config.lanes.business);
+    }
+    return allLanes;
+}
+/**
+ * WU-1187: Check if a lane has WIP justification when required
+ *
+ * Philosophy: If you need WIP > 1, you need better lanes, not higher limits.
+ * This is soft enforcement: logs a warning at claim time, but doesn't block.
+ *
+ * @param {string} lane - Lane name to check
+ * @param {CheckWipJustificationOptions} options - Options including configPath for testing
+ * @returns {CheckWipJustificationResult} Result with valid=true (always) and optional warning
+ */
+export function checkWipJustification(lane, options = {}) {
+    // Determine config path
+    let resolvedConfigPath = options.configPath;
+    if (!resolvedConfigPath) {
+        const projectRoot = findProjectRoot();
+        resolvedConfigPath = path.join(projectRoot, CONFIG_FILES.LUMENFLOW_CONFIG);
+    }
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Config path is validated
+    if (!existsSync(resolvedConfigPath)) {
+        return NO_JUSTIFICATION_REQUIRED;
+    }
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Config path is validated
+        const configContent = readFileSync(resolvedConfigPath, { encoding: 'utf-8' });
+        const config = parseYAML(configContent);
+        const allLanes = extractAllLanesFromConfig(config);
+        if (allLanes.length === 0) {
+            return NO_JUSTIFICATION_REQUIRED;
+        }
+        // Find matching lane (case-insensitive)
+        const normalizedLane = lane.toLowerCase().trim();
+        const matchingLane = allLanes.find((l) => l.name.toLowerCase().trim() === normalizedLane);
+        if (!matchingLane) {
+            return NO_JUSTIFICATION_REQUIRED;
+        }
+        const wipLimit = matchingLane.wip_limit ?? DEFAULT_WIP_LIMIT;
+        // WIP <= 1 doesn't need justification
+        if (wipLimit <= 1) {
+            return NO_JUSTIFICATION_REQUIRED;
+        }
+        // WIP > 1 - check for justification
+        const justification = matchingLane.wip_justification;
+        if (justification && justification.trim().length > 0) {
+            // Has justification - all good
+            return {
+                valid: true,
+                warning: null,
+                requiresJustification: false,
+                justification: justification.trim(),
+            };
+        }
+        // WIP > 1 without justification - emit warning
+        const warning = `Lane "${lane}" has WIP limit of ${wipLimit} but no wip_justification. ` +
+            `Philosophy: If you need WIP > 1, you need better lanes, not higher limits. ` +
+            `Add wip_justification to .lumenflow.config.yaml to suppress this warning.`;
+        return {
+            valid: true, // Soft enforcement - warning only, doesn't block
+            warning,
+            requiresJustification: true,
+        };
+    }
+    catch {
+        // If config parsing fails, don't block
+        return NO_JUSTIFICATION_REQUIRED;
+    }
+}

package/dist/lane-suggest-prompt.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Lane Suggestion Prompt Module (WU-1189)
+ *
+ * Generates prompts for LLM-driven lane suggestions based on codebase context.
+ * This module gathers project context and generates structured prompts for
+ * the LLM to analyze and suggest appropriate lane definitions.
+ *
+ * Design decisions:
+ * - Uses LLM for semantic understanding (not hardcoded heuristics)
+ * - Gathers context from docs, structure, and existing config
+ * - Returns structured JSON for easy parsing
+ */
+import { z } from 'zod';
+/**
+ * Schema for a single lane suggestion from the LLM
+ */
+export declare const LaneSuggestionSchema: z.ZodObject<{
+    lane: z.ZodString;
+    description: z.ZodString;
+    rationale: z.ZodString;
+    code_paths: z.ZodArray<z.ZodString>;
+    keywords: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type LaneSuggestion = z.infer<typeof LaneSuggestionSchema>;
+/**
+ * Schema for the complete LLM response
+ */
+export declare const LaneSuggestResponseSchema: z.ZodObject<{
+    suggestions: z.ZodArray<z.ZodObject<{
+        lane: z.ZodString;
+        description: z.ZodString;
+        rationale: z.ZodString;
+        code_paths: z.ZodArray<z.ZodString>;
+        keywords: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LaneSuggestResponse = z.infer<typeof LaneSuggestResponseSchema>;
+/**
+ * Project context gathered for LLM analysis
+ */
+export interface ProjectContext {
+    /** Names of packages found (for monorepos) */
+    packageNames: string[];
+    /** Top-level directory structure */
+    directoryStructure: string[];
+    /** Content of README.md if present */
+    readme: string | null;
+    /** Content of package.json if present */
+    packageJson: {
+        name?: string;
+        description?: string;
+        workspaces?: string[];
+    } | null;
+    /** Existing lane definitions if any */
+    existingLanes: string[];
+    /** Whether docs directory exists */
+    hasDocsDir: boolean;
+    /** Whether apps directory exists (common in monorepos) */
+    hasAppsDir: boolean;
+    /** Whether packages directory exists (monorepo indicator) */
+    hasPackagesDir: boolean;
+    /** Whether it's a monorepo */
+    isMonorepo: boolean;
+}
+/**
+ * Result of lane suggestion including suggestions and metadata
+ */
+export interface LaneSuggestResult {
+    suggestions: LaneSuggestion[];
+    context: {
+        packageCount: number;
+        docsFound: boolean;
+        existingConfig: boolean;
+    };
+}
+/**
+ * Gather project context from the filesystem
+ */
+export declare function gatherProjectContext(projectRoot: string): ProjectContext;
+/**
+ * Generate the system prompt for lane suggestion
+ */
+export declare function generateSystemPrompt(): string;
+/**
+ * Generate the user prompt with project context
+ */
+export declare function generateUserPrompt(context: ProjectContext): string;
+/**
+ * Parse and validate LLM response
+ */
+export declare function parseLLMResponse(response: string): LaneSuggestResponse;
+/**
+ * Validate that a lane name follows the "Parent: Sublane" format
+ */
+export declare function isValidLaneFormat(lane: string): boolean;
+/**
+ * Generate a dry-run preview of what would be sent to the LLM
+ */
+export declare function generateDryRunPreview(projectRoot: string): {
+    context: ProjectContext;
+    systemPrompt: string;
+    userPrompt: string;
+};
+/**
+ * Get default lane suggestions for a minimal project
+ * Used when LLM is not available or for dry-run
+ */
+export declare function getDefaultSuggestions(context: ProjectContext): LaneSuggestion[];