@lumenflow/core 1.0.0 → 1.3.2

package/dist/lane-checker.js

@@ -7,7 +7,7 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import yaml from 'js-yaml';
+import { parseYAML } from './wu-yaml.js';
 import { getSubLanesForParent } from './lane-inference.js';
 import { createError, ErrorCodes } from './error-handler.js';
 import { isInProgressHeader, WU_LINK_PATTERN } from './constants/backlog-patterns.js';
@@ -48,7 +48,7 @@ function hasSubLaneTaxonomy(parent) {
     }
     try {
         const taxonomyContent = readFileSync(taxonomyPath, { encoding: 'utf-8' });
-        const taxonomy = yaml.load(taxonomyContent);
+        const taxonomy = parseYAML(taxonomyContent);
         // Check if parent exists as top-level key in taxonomy
         const normalizedParent = parent.trim();
         return Object.keys(taxonomy).some((key) => key.toLowerCase().trim() === normalizedParent.toLowerCase());
@@ -71,7 +71,7 @@ function isValidSubLane(parent, subdomain) {
     }
     try {
         const taxonomyContent = readFileSync(taxonomyPath, { encoding: 'utf-8' });
-        const taxonomy = yaml.load(taxonomyContent);
+        const taxonomy = parseYAML(taxonomyContent);
         // Find parent key (case-insensitive)
         const normalizedParent = parent.trim().toLowerCase();
         const parentKey = Object.keys(taxonomy).find((key) => key.toLowerCase().trim() === normalizedParent);
@@ -188,6 +188,10 @@ export function validateLaneFormat(lane, configPath = null, options = {}) {
 }
 /**
  * Check if a parent lane exists in LumenFlow config
+ *
+ * WU-1022: Updated to support lanes.definitions with full "Parent: Sublane" format.
+ * When lanes.definitions exists, parent lanes are extracted from full lane names.
+ *
  * @param {string} parent - Parent lane name to check
  * @param {string} configPath - Path to config file (optional)
  * @returns {boolean} True if parent lane exists
@@ -206,16 +210,26 @@ function isValidParentLane(parent, configPath = null) {
         });
     }
     const configContent = readFileSync(resolvedConfigPath, { encoding: 'utf-8' });
-    const config = yaml.load(configContent);
-    // Extract all lane names - handle both flat array and nested engineering/business formats
+    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 {
-            // Nested format: lanes: {engineering: [...], business: [...]}
+            // 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));
             }
@@ -226,16 +240,86 @@ function isValidParentLane(parent, configPath = null) {
     }
     // Case-insensitive comparison
     const normalizedParent = parent.toLowerCase().trim();
+    // WU-1022: If we have extracted parent lanes (from full lane names), check against those
+    if (parentLanes.size > 0) {
+        return parentLanes.has(normalizedParent);
+    }
+    // Legacy: check against direct lane names
     return allLanes.some((lane) => lane.toLowerCase().trim() === normalizedParent);
 }
+/** WU-1016: Default WIP limit when not specified in config */
+const DEFAULT_WIP_LIMIT = 1;
 /**
- * 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 function getWipLimitForLane(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_WIP_LIMIT;
+    }
+    try {
+        const configContent = readFileSync(resolvedConfigPath, { encoding: 'utf-8' });
+        const config = parseYAML(configContent);
+        if (!config.lanes) {
+            return DEFAULT_WIP_LIMIT;
+        }
+        // Normalize lane name for case-insensitive comparison
+        const normalizedLane = lane.toLowerCase().trim();
+        // Extract all lanes with their wip_limit
+        let allLanes = [];
+        if (Array.isArray(config.lanes)) {
+            // Flat array format: lanes: [{name: "Core", wip_limit: 2}, ...]
+            allLanes = config.lanes;
+        }
+        else {
+            // 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_WIP_LIMIT;
+        }
+        // Return wip_limit if specified, otherwise default
+        return matchingLane.wip_limit ?? DEFAULT_WIP_LIMIT;
+    }
+    catch {
+        // If config parsing fails, return default
+        return DEFAULT_WIP_LIMIT;
+    }
+}
+/**
+ * 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 function checkLaneFree(statusPath, lane, wuid) {
+export function checkLaneFree(statusPath, lane, wuid, options = {}) {
     /** Section heading marker for H2 headings */
     const SECTION_HEADING_PREFIX = '## ';
     try {
@@ -264,19 +348,38 @@ export function checkLaneFree(statusPath, lane, wuid) {
             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
         if (section.includes(NO_ITEMS_MARKER)) {
-            return { free: true, occupiedBy: null, error: null };
+            return {
+                free: true,
+                occupiedBy: null,
+                error: null,
+                inProgressWUs: [],
+                wipLimit,
+                currentCount: 0,
+            };
         }
         // 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 };
+            return {
+                free: true,
+                occupiedBy: null,
+                error: null,
+                inProgressWUs: [],
+                wipLimit,
+                currentCount: 0,
+            };
         }
         // 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)
@@ -290,17 +393,16 @@ export function checkLaneFree(statusPath, lane, wuid) {
             }
             try {
                 const wuContent = readFileSync(wuPath, { encoding: 'utf-8' });
-                const wuDoc = yaml.load(wuContent);
+                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();
-                const targetLane = lane.toString().trim().toLowerCase();
                 if (activeLane === targetLane) {
-                    // Lane is occupied!
-                    return { free: false, occupiedBy: activeWuid, error: null };
+                    // WU-1016: Add to list of in-progress WUs in this lane
+                    inProgressWUs.push(activeWuid);
                 }
             }
             catch (e) {
@@ -309,8 +411,17 @@ export function checkLaneFree(statusPath, lane, wuid) {
                 continue;
             }
         }
-        // No WUs found in target lane
-        return { free: true, occupiedBy: null, error: null };
+        // WU-1016: Check if lane is free based on WIP limit
+        const currentCount = inProgressWUs.length;
+        const isFree = currentCount < wipLimit;
+        return {
+            free: isFree,
+            occupiedBy: isFree ? null : inProgressWUs[0] || null,
+            error: null,
+            inProgressWUs,
+            wipLimit,
+            currentCount,
+        };
     }
     catch (error) {
         const errMessage = error instanceof Error ? error.message : String(error);

package/dist/lane-inference.js

@@ -12,12 +12,12 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import YAML from 'yaml'; // Modern YAML library (not js-yaml)
 import micromatch from 'micromatch'; // Industry-standard glob matching (CommonJS)
 import { extractParent } from './lane-checker.js'; // Shared utility (WU-1137: consolidation)
 import { createError, ErrorCodes } from './error-handler.js';
 import { WEIGHTS, CONFIDENCE } from './wu-validation-constants.js';
+import { findProjectRoot } from './lumenflow-config.js';
 /**
  * Load lane inference config from project root
  * @param {string|null} configPath - Optional path to config file (defaults to project root)
@@ -26,9 +26,8 @@ import { WEIGHTS, CONFIDENCE } from './wu-validation-constants.js';
  */
 function loadConfig(configPath = null) {
     if (!configPath) {
-        // Default to project root
-        const currentDir = path.dirname(fileURLToPath(import.meta.url));
-        const projectRoot = path.resolve(currentDir, '../..');
+        // Use findProjectRoot() to locate config from cwd
+        const projectRoot = findProjectRoot();
         configPath = path.join(projectRoot, '.lumenflow.lane-inference.yaml');
     }
     if (!existsSync(configPath)) {

package/dist/lumenflow-config-schema.d.ts

@@ -52,6 +52,7 @@ export declare const GitConfigSchema: z.ZodObject<{
     maxBranchDrift: z.ZodDefault<z.ZodNumber>;
     branchDriftWarning: z.ZodDefault<z.ZodNumber>;
     branchDriftInfo: z.ZodDefault<z.ZodNumber>;
+    agentBranchPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 /**
  * WU (Work Unit) configuration
@@ -91,12 +92,84 @@ export declare const UiConfigSchema: z.ZodObject<{
     statusPreviewLines: z.ZodDefault<z.ZodNumber>;
     readinessBoxWidth: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * YAML serialization configuration
+ */
 /**
  * YAML serialization configuration
  */
 export declare const YamlConfigSchema: z.ZodObject<{
     lineWidth: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * Methodology defaults (agent-facing project defaults)
+ */
+export declare const DEFAULT_METHODOLOGY_PRINCIPLES: string[];
+export declare const MethodologyDefaultsSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    enforcement: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        recommended: "recommended";
+    }>>;
+    principles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Client-specific blocks (agent-facing spawn blocks)
+ */
+export declare const ClientBlockSchema: z.ZodObject<{
+    title: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Client-specific skills guidance
+ */
+export declare const ClientSkillsSchema: z.ZodObject<{
+    instructions: z.ZodOptional<z.ZodString>;
+    recommended: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Client configuration (per-client settings)
+ */
+export declare const ClientConfigSchema: z.ZodObject<{
+    preamble: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
+    skillsDir: z.ZodOptional<z.ZodString>;
+    blocks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>>>;
+    skills: z.ZodOptional<z.ZodObject<{
+        instructions: z.ZodOptional<z.ZodString>;
+        recommended: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Agents configuration
+ */
+export declare const AgentsConfigSchema: z.ZodObject<{
+    defaultClient: z.ZodDefault<z.ZodString>;
+    clients: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        preamble: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
+        skillsDir: z.ZodOptional<z.ZodString>;
+        blocks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strip>>>;
+        skills: z.ZodOptional<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+            recommended: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    methodology: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        enforcement: z.ZodDefault<z.ZodEnum<{
+            required: "required";
+            recommended: "recommended";
+        }>>;
+        principles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /**
  * Complete LumenFlow configuration schema
  */
@@ -138,6 +211,7 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
         maxBranchDrift: z.ZodDefault<z.ZodNumber>;
         branchDriftWarning: z.ZodDefault<z.ZodNumber>;
         branchDriftInfo: z.ZodDefault<z.ZodNumber>;
+        agentBranchPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     wu: z.ZodDefault<z.ZodObject<{
         idPattern: z.ZodDefault<z.ZodString>;
@@ -168,6 +242,30 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
     yaml: z.ZodDefault<z.ZodObject<{
         lineWidth: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    agents: z.ZodDefault<z.ZodObject<{
+        defaultClient: z.ZodDefault<z.ZodString>;
+        clients: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            preamble: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
+            skillsDir: z.ZodOptional<z.ZodString>;
+            blocks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strip>>>;
+            skills: z.ZodOptional<z.ZodObject<{
+                instructions: z.ZodOptional<z.ZodString>;
+                recommended: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        methodology: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            enforcement: z.ZodDefault<z.ZodEnum<{
+                required: "required";
+                recommended: "recommended";
+            }>>;
+            principles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            notes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * TypeScript types inferred from schemas
@@ -180,6 +278,11 @@ export type GatesConfig = z.infer<typeof GatesConfigSchema>;
 export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
 export type UiConfig = z.infer<typeof UiConfigSchema>;
 export type YamlConfig = z.infer<typeof YamlConfigSchema>;
+export type MethodologyDefaults = z.infer<typeof MethodologyDefaultsSchema>;
+export type ClientBlock = z.infer<typeof ClientBlockSchema>;
+export type ClientSkills = z.infer<typeof ClientSkillsSchema>;
+export type ClientConfig = z.infer<typeof ClientConfigSchema>;
+export type AgentsConfig = z.infer<typeof AgentsConfigSchema>;
 export type LumenFlowConfig = z.infer<typeof LumenFlowConfigSchema>;
 /**
  * Validate configuration data
@@ -225,6 +328,7 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
         maxBranchDrift: number;
         branchDriftWarning: number;
         branchDriftInfo: number;
+        agentBranchPatterns: string[];
     };
     wu: {
         idPattern: string;
@@ -255,6 +359,27 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
     yaml: {
         lineWidth: number;
     };
+    agents: {
+        defaultClient: string;
+        clients: Record<string, {
+            blocks: {
+                title: string;
+                content: string;
+            }[];
+            preamble?: string | boolean;
+            skillsDir?: string;
+            skills?: {
+                recommended: string[];
+                instructions?: string;
+            };
+        }>;
+        methodology: {
+            enabled: boolean;
+            enforcement: "required" | "recommended";
+            principles: string[];
+            notes?: string;
+        };
+    };
 }>;
 /**
  * Parse configuration with defaults

package/dist/lumenflow-config-schema.js

@@ -83,6 +83,13 @@ export const GitConfigSchema = z.object({
     branchDriftWarning: z.number().int().positive().default(15),
     /** Info threshold for branch drift */
     branchDriftInfo: z.number().int().positive().default(10),
+    /**
+     * Agent branch patterns that bypass worktree requirements.
+     * Branches matching these glob patterns can work in the main checkout.
+     * Default: ['agent/*'] - narrow default, add vendor patterns as needed.
+     * Protected branches (mainBranch + 'master') are NEVER bypassed.
+     */
+    agentBranchPatterns: z.array(z.string()).default(['agent/*']),
 });
 /**
  * WU (Work Unit) configuration
@@ -148,6 +155,9 @@ export const UiConfigSchema = z.object({
     /** Readiness box width (default: 50) */
     readinessBoxWidth: z.number().int().positive().default(50),
 });
+/**
+ * YAML serialization configuration
+ */
 /**
  * YAML serialization configuration
  */
@@ -155,6 +165,70 @@ export const YamlConfigSchema = z.object({
     /** Line width for YAML output (default: 100, -1 for no wrap) */
     lineWidth: z.number().int().default(100),
 });
+/**
+ * Methodology defaults (agent-facing project defaults)
+ */
+export const DEFAULT_METHODOLOGY_PRINCIPLES = [
+    'TDD',
+    'Hexagonal Architecture',
+    'SOLID',
+    'DRY',
+    'YAGNI',
+    'KISS',
+    'Library-First',
+];
+export const MethodologyDefaultsSchema = z.object({
+    /** Enable or disable project defaults output */
+    enabled: z.boolean().default(true),
+    /** Whether defaults are required or recommended */
+    enforcement: z.enum(['required', 'recommended']).default('required'),
+    /** Default methodology principles to apply */
+    principles: z.array(z.string()).default(DEFAULT_METHODOLOGY_PRINCIPLES),
+    /** Optional notes appended to Project Defaults */
+    notes: z.string().optional(),
+});
+/**
+ * Client-specific blocks (agent-facing spawn blocks)
+ */
+export const ClientBlockSchema = z.object({
+    /** Block title */
+    title: z.string(),
+    /** Block content (markdown allowed) */
+    content: z.string(),
+});
+/**
+ * Client-specific skills guidance
+ */
+export const ClientSkillsSchema = z.object({
+    /** Optional skills selection guidance text */
+    instructions: z.string().optional(),
+    /** Recommended skills to load for this client */
+    recommended: z.array(z.string()).default([]),
+});
+/**
+ * Client configuration (per-client settings)
+ */
+export const ClientConfigSchema = z.object({
+    /** Preamble file path (e.g. 'CLAUDE.md') or false to disable */
+    preamble: z.union([z.string(), z.boolean()]).optional(),
+    /** Skills directory path */
+    skillsDir: z.string().optional(),
+    /** Client-specific blocks injected into wu:spawn output */
+    blocks: z.array(ClientBlockSchema).default([]),
+    /** Client-specific skills guidance for wu:spawn */
+    skills: ClientSkillsSchema.optional(),
+});
+/**
+ * Agents configuration
+ */
+export const AgentsConfigSchema = z.object({
+    /** Default client to use if not specified (default: 'claude-code') */
+    defaultClient: z.string().default('claude-code'),
+    /** Client-specific configurations */
+    clients: z.record(z.string(), ClientConfigSchema).default({}),
+    /** Project methodology defaults (agent-facing) */
+    methodology: MethodologyDefaultsSchema.default(() => MethodologyDefaultsSchema.parse({})),
+});
 /**
  * Complete LumenFlow configuration schema
  */
@@ -177,6 +251,8 @@ export const LumenFlowConfigSchema = z.object({
     ui: UiConfigSchema.default(() => UiConfigSchema.parse({})),
     /** YAML configuration */
     yaml: YamlConfigSchema.default(() => YamlConfigSchema.parse({})),
+    /** Agents configuration */
+    agents: AgentsConfigSchema.default(() => AgentsConfigSchema.parse({})),
 });
 /**
  * Validate configuration data

package/dist/lumenflow-home.d.ts

@@ -0,0 +1,130 @@
+/**
+ * LumenFlow Home Directory Resolution
+ *
+ * WU-1062: External plan storage and no-main-write mode
+ *
+ * Provides helpers for resolving the $LUMENFLOW_HOME directory and related paths.
+ * Plans are stored externally in $LUMENFLOW_HOME/plans/ instead of in the repo.
+ *
+ * Default: ~/.lumenflow/
+ * Override: Set $LUMENFLOW_HOME environment variable
+ *
+ * @module
+ */
+/**
+ * Environment variable name for LumenFlow home directory
+ */
+export declare const LUMENFLOW_HOME_ENV = "LUMENFLOW_HOME";
+/**
+ * Default LumenFlow home directory name
+ */
+export declare const DEFAULT_LUMENFLOW_DIR = ".lumenflow";
+/**
+ * Plans subdirectory name
+ */
+export declare const PLANS_SUBDIR = "plans";
+/**
+ * Custom protocol for external LumenFlow paths
+ */
+export declare const LUMENFLOW_PROTOCOL = "lumenflow://";
+/**
+ * Environment variable prefix for spec_refs
+ */
+export declare const LUMENFLOW_HOME_VAR_PREFIX = "$LUMENFLOW_HOME";
+/**
+ * Get the LumenFlow home directory path
+ *
+ * Resolution order:
+ * 1. $LUMENFLOW_HOME environment variable (with ~ expansion)
+ * 2. ~/.lumenflow/ default
+ *
+ * @returns {string} Absolute path to LumenFlow home directory
+ *
+ * @example
+ * // With LUMENFLOW_HOME=/custom/path
+ * getLumenflowHome() // '/custom/path'
+ *
+ * @example
+ * // With LUMENFLOW_HOME=~/.custom-lumenflow
+ * getLumenflowHome() // '/home/user/.custom-lumenflow'
+ *
+ * @example
+ * // Without LUMENFLOW_HOME set
+ * getLumenflowHome() // '/home/user/.lumenflow'
+ */
+export declare function getLumenflowHome(): string;
+/**
+ * Get the plans directory path
+ *
+ * Plans are stored in $LUMENFLOW_HOME/plans/
+ *
+ * @returns {string} Absolute path to plans directory
+ *
+ * @example
+ * getPlansDir() // '/home/user/.lumenflow/plans'
+ */
+export declare function getPlansDir(): string;
+/**
+ * Check if a path is an external (non-repo) path
+ *
+ * External paths include:
+ * - Paths starting with ~/
+ * - Paths starting with $LUMENFLOW_HOME
+ * - Paths using lumenflow:// protocol
+ * - Absolute paths (starting with /)
+ *
+ * @param {string} path - Path to check
+ * @returns {boolean} True if path is external
+ *
+ * @example
+ * isExternalPath('~/.lumenflow/plans/plan.md') // true
+ * isExternalPath('$LUMENFLOW_HOME/plans/plan.md') // true
+ * isExternalPath('lumenflow://plans/plan.md') // true
+ * isExternalPath('/home/user/.lumenflow/plans/plan.md') // true
+ * isExternalPath('docs/04-operations/plans/plan.md') // false
+ */
+export declare function isExternalPath(path: string): boolean;
+/**
+ * Normalize a spec_ref path by expanding variables and protocols
+ *
+ * Expands:
+ * - lumenflow://path -> $LUMENFLOW_HOME/path
+ * - ~/path -> /home/user/path
+ * - $LUMENFLOW_HOME/path -> actual LUMENFLOW_HOME value
+ *
+ * Repo-relative paths are returned unchanged.
+ *
+ * @param {string} specRef - Spec reference path
+ * @returns {string} Normalized absolute path or unchanged relative path
+ *
+ * @example
+ * normalizeSpecRef('lumenflow://plans/WU-1062-plan.md')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ *
+ * @example
+ * normalizeSpecRef('docs/04-operations/plans/plan.md')
+ * // 'docs/04-operations/plans/plan.md' (unchanged)
+ */
+export declare function normalizeSpecRef(specRef: string): string;
+/**
+ * Get the full path for a plan file given a WU ID
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Full path to the plan file
+ *
+ * @example
+ * getPlanPath('WU-1062')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ */
+export declare function getPlanPath(wuId: string): string;
+/**
+ * Get the lumenflow:// protocol reference for a plan
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Protocol reference (e.g., 'lumenflow://plans/WU-1062-plan.md')
+ *
+ * @example
+ * getPlanProtocolRef('WU-1062')
+ * // 'lumenflow://plans/WU-1062-plan.md'
+ */
+export declare function getPlanProtocolRef(wuId: string): string;