@lumenflow/core 2.4.0 → 2.5.0

package/dist/lumenflow-config-schema.js

@@ -11,6 +11,24 @@ import { z } from 'zod';
 import { GatesExecutionConfigSchema } from './gates-config.js';
 // WU-1259: Import methodology config schema for resolvePolicy()
 import { MethodologyConfigSchema } from './resolve-policy.js';
+/**
+ * WU-1325: Lock policy for lane-level WIP enforcement
+ *
+ * Controls how lane locks behave:
+ * - 'all' (default): Lock acquired on claim, held through block, released on done
+ * - 'active': Lock acquired on claim, released on block, re-acquired on unblock
+ * - 'none': No lock files created, WIP checking disabled
+ *
+ * @example
+ * ```yaml
+ * lanes:
+ *   definitions:
+ *     - name: 'Content: Documentation'
+ *       wip_limit: 4
+ *       lock_policy: 'none'  # Docs don't need lock coordination
+ * ```
+ */
+export const LockPolicySchema = z.enum(['all', 'active', 'none']).default('all');
 /**
  * Event archival configuration (WU-1207)
  *
@@ -69,6 +87,10 @@ export const DirectoriesSchema = z.object({
     agentsDir: z.string().default('.claude/agents'),
     /** Plans directory (default: 'docs/04-operations/plans') - WU-1301 */
     plansDir: z.string().default('docs/04-operations/plans'),
+    /** Templates directory (default: '.lumenflow/templates') - WU-1310 */
+    templatesDir: z.string().default('.lumenflow/templates'),
+    /** Onboarding directory (default: 'docs/04-operations/_frameworks/lumenflow/agent/onboarding') - WU-1310 */
+    onboardingDir: z.string().default('docs/04-operations/_frameworks/lumenflow/agent/onboarding'),
 });
 /**
  * Beacon paths configuration (.lumenflow directory structure)
@@ -100,6 +122,45 @@ export const BeaconPathsSchema = z.object({
      */
     eventArchival: EventArchivalConfigSchema.default(() => EventArchivalConfigSchema.parse({})),
 });
+/**
+ * WU-1332: Push retry configuration for micro-worktree operations
+ *
+ * When non-fast-forward push errors occur (origin/main moved during operation),
+ * retry with exponential backoff. Uses p-retry for robust retry behavior.
+ */
+export const PushRetryConfigSchema = z.object({
+    /**
+     * Enable push retry with rebase on non-fast-forward errors.
+     * When true, failed pushes trigger automatic rebase and retry.
+     * When false, the original error is thrown immediately.
+     * @default true
+     */
+    enabled: z.boolean().default(true),
+    /**
+     * Maximum number of retry attempts (including the initial attempt).
+     * After this many failures, the operation fails with clear guidance.
+     * @default 3
+     */
+    retries: z.number().int().positive().default(3),
+    /**
+     * Minimum delay in milliseconds between retries.
+     * Used as the base for exponential backoff.
+     * @default 100
+     */
+    min_delay_ms: z.number().int().nonnegative().default(100),
+    /**
+     * Maximum delay in milliseconds between retries.
+     * Caps the exponential backoff to prevent excessive waits.
+     * @default 1000
+     */
+    max_delay_ms: z.number().int().positive().default(1000),
+    /**
+     * Add randomization to retry delays (recommended for concurrent agents).
+     * Helps prevent thundering herd when multiple agents retry simultaneously.
+     * @default true
+     */
+    jitter: z.boolean().default(true),
+});
 /**
  * Git configuration
  */
@@ -189,6 +250,23 @@ export const GitConfigSchema = z.object({
      * ```
      */
     disableAgentPatternRegistry: z.boolean().default(false),
+    /**
+     * WU-1332: Push retry configuration for micro-worktree operations.
+     * When push fails due to non-fast-forward (origin moved), automatically
+     * rebase and retry with exponential backoff.
+     *
+     * @example
+     * ```yaml
+     * git:
+     *   push_retry:
+     *     enabled: true
+     *     retries: 5        # Try 5 times total
+     *     min_delay_ms: 200 # Start with 200ms delay
+     *     max_delay_ms: 2000 # Cap at 2 second delay
+     *     jitter: true      # Add randomization
+     * ```
+     */
+    push_retry: PushRetryConfigSchema.default(() => PushRetryConfigSchema.parse({})),
 });
 /**
  * WU (Work Unit) configuration
@@ -504,6 +582,40 @@ export const TelemetryConfigSchema = z.object({
      */
     methodology: MethodologyTelemetryConfigSchema.default(() => MethodologyTelemetryConfigSchema.parse({})),
 });
+/**
+ * WU-1322: Lane definition schema for .lumenflow.config.yaml
+ *
+ * Extends the existing lane configuration with lock_policy field.
+ * Compatible with WU-1016 (wip_limit) and WU-1187 (wip_justification).
+ */
+export const LaneDefinitionSchema = z.object({
+    /** Lane name in "Parent: Sublane" format (e.g., "Framework: Core") */
+    name: z.string(),
+    /** WU-1016: Maximum WUs allowed in progress concurrently for this lane */
+    wip_limit: z.number().int().positive().optional(),
+    /** WU-1187: Required justification when wip_limit > 1 */
+    wip_justification: z.string().optional(),
+    /**
+     * WU-1322: Lock policy for this lane.
+     * - 'all': Lock lane for all other agents (default)
+     * - 'active': Lock only for agents with overlapping code_paths
+     * - 'none': No locking (suitable for documentation lanes)
+     *
+     * @default 'all'
+     *
+     * @example
+     * ```yaml
+     * lanes:
+     *   definitions:
+     *     - name: 'Content: Documentation'
+     *       wip_limit: 4
+     *       lock_policy: 'none'  # Docs can be worked in parallel
+     * ```
+     */
+    lock_policy: LockPolicySchema.default('all'),
+    /** Code paths associated with this lane (glob patterns) */
+    code_paths: z.array(z.string()).optional(),
+});
 /**
  * Complete LumenFlow configuration schema
  */

package/dist/lumenflow-config.d.ts

@@ -72,6 +72,8 @@ export declare function getResolvedPaths(options?: {
     agentsDir: string;
     memoryBank: string;
     plansDir: string;
+    templatesDir: string;
+    onboardingDir: string;
 };
 /**
  * Validate a config file
@@ -93,5 +95,5 @@ export declare function validateConfigFile(configPath: string): {
 export declare function createSampleConfig(outputPath: string, options?: {
     includeComments?: boolean;
 }): void;
-export type { LumenFlowConfig, Directories, BeaconPaths, GitConfig, WuConfig, GatesConfig, MemoryConfig, UiConfig, YamlConfig, } from './lumenflow-config-schema.js';
+export type { LumenFlowConfig, Directories, BeaconPaths, PushRetryConfig, GitConfig, WuConfig, GatesConfig, MemoryConfig, UiConfig, YamlConfig, } from './lumenflow-config-schema.js';
 export { getDefaultConfig } from './lumenflow-config-schema.js';

package/dist/lumenflow-config.js

@@ -55,6 +55,7 @@ function loadConfigFile(projectRoot) {
         return data || {};
     }
     catch (error) {
+        // eslint-disable-next-line no-console -- Config loading runs before logger init
         console.warn(`Warning: Failed to parse ${CONFIG_FILE_NAME}:`, error);
         return null;
     }
@@ -145,6 +146,8 @@ export function getResolvedPaths(options = {}) {
         agentsDir: path.join(projectRoot, config.directories.agentsDir),
         memoryBank: path.join(projectRoot, config.directories.memoryBank),
         plansDir: path.join(projectRoot, config.directories.plansDir),
+        templatesDir: path.join(projectRoot, config.directories.templatesDir),
+        onboardingDir: path.join(projectRoot, config.directories.onboardingDir),
     };
 }
 /**
@@ -206,6 +209,12 @@ directories:
   skillsDir: "${defaultConfig.directories.skillsDir}"
   # Agents directory
   agentsDir: "${defaultConfig.directories.agentsDir}"
+  # Plans directory
+  plansDir: "${defaultConfig.directories.plansDir}"
+  # Templates directory
+  templatesDir: "${defaultConfig.directories.templatesDir}"
+  # Onboarding directory
+  onboardingDir: "${defaultConfig.directories.onboardingDir}"
 
 # Beacon paths (.lumenflow directory structure)
 beacon:

package/dist/micro-worktree.d.ts

@@ -28,6 +28,7 @@
  * @see {@link packages/@lumenflow/cli/src/initiative-create.ts} - Initiative creation (WU-1439)
  */
 import type { GitAdapter } from './git-adapter.js';
+import type { PushRetryConfig } from './lumenflow-config-schema.js';
 /**
  * Context passed to the execute function in withMicroWorktree
  */
@@ -81,8 +82,17 @@ export declare const MAX_MERGE_RETRIES = 3;
  * WU-1179: When push fails due to race condition (origin advanced while we
  * were working), rollback local main to origin/main and retry.
  * Each retry: fetch -> rebase temp branch -> re-merge -> push.
+ *
+ * @deprecated Use DEFAULT_PUSH_RETRY_CONFIG.retries instead (WU-1332)
  */
 export declare const MAX_PUSH_RETRIES = 3;
+/**
+ * WU-1332: Default push retry configuration
+ *
+ * Provides sensible defaults for micro-worktree push operations.
+ * Can be overridden via .lumenflow.config.yaml git.push_retry section.
+ */
+export declare const DEFAULT_PUSH_RETRY_CONFIG: PushRetryConfig;
 /**
  * Environment variable name for LUMENFLOW_FORCE bypass
  *
@@ -101,6 +111,102 @@ export declare const LUMENFLOW_FORCE_REASON_ENV = "LUMENFLOW_FORCE_REASON";
  * Extracted to constant to satisfy sonarjs/no-duplicate-string rule.
  */
 export declare const DEFAULT_LOG_PREFIX = "[micro-wt]";
+/**
+ * WU-1336: Typed error for retry exhaustion in micro-worktree operations
+ *
+ * Thrown when push retries are exhausted due to race conditions with parallel agents.
+ * CLI commands should use `isRetryExhaustionError` to detect this error type and
+ * `formatRetryExhaustionError` to generate actionable user-facing messages.
+ *
+ * This centralizes retry exhaustion handling so CLI commands do not need to
+ * duplicate detection logic or error formatting.
+ *
+ * @example
+ * ```typescript
+ * import { RetryExhaustionError, isRetryExhaustionError, formatRetryExhaustionError } from '@lumenflow/core';
+ *
+ * try {
+ *   await withMicroWorktree({ ... });
+ * } catch (error) {
+ *   if (isRetryExhaustionError(error)) {
+ *     console.error(formatRetryExhaustionError(error, { command: 'pnpm initiative:add-wu ...' }));
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export declare class RetryExhaustionError extends Error {
+    /** Name of the error class (for instanceof checks across module boundaries) */
+    readonly name = "RetryExhaustionError";
+    /** Operation that was being performed (e.g., 'initiative-add-wu') */
+    readonly operation: string;
+    /** Number of retry attempts that were exhausted */
+    readonly retries: number;
+    constructor(operation: string, retries: number);
+}
+/**
+ * WU-1336: Options for formatting retry exhaustion error messages
+ */
+export interface FormatRetryExhaustionOptions {
+    /** Command to suggest for retrying (e.g., 'pnpm initiative:add-wu --wu WU-123 --initiative INIT-001') */
+    command: string;
+}
+/**
+ * WU-1336: Type guard to check if an error is a retry exhaustion error
+ *
+ * Detects both the typed `RetryExhaustionError` class and legacy error messages
+ * that match the "Push failed after N attempts" pattern.
+ *
+ * @param {unknown} error - Error to check
+ * @returns {boolean} True if this is a retry exhaustion error
+ *
+ * @example
+ * ```typescript
+ * if (isRetryExhaustionError(error)) {
+ *   // Handle retry exhaustion
+ * }
+ * ```
+ */
+export declare function isRetryExhaustionError(error: unknown): error is Error;
+/**
+ * WU-1336: Format retry exhaustion error with actionable next steps
+ *
+ * When push retries are exhausted, provides clear guidance on how to proceed.
+ * CLI commands should use this instead of duplicating error formatting logic.
+ *
+ * @param {Error} error - The retry exhaustion error
+ * @param {FormatRetryExhaustionOptions} options - Formatting options
+ * @returns {string} Formatted error message with next steps
+ *
+ * @example
+ * ```typescript
+ * const message = formatRetryExhaustionError(error, {
+ *   command: 'pnpm initiative:add-wu --wu WU-123 --initiative INIT-001',
+ * });
+ * console.error(message);
+ * ```
+ */
+export declare function formatRetryExhaustionError(error: Error, options: FormatRetryExhaustionOptions): string;
+/**
+ * WU-1308: Check if remote operations should be skipped based on git.requireRemote config
+ *
+ * When git.requireRemote is false, micro-worktree operations skip:
+ * - Fetching origin/main before starting
+ * - Pushing to origin/main after completion
+ *
+ * This enables local-only development without a remote repository.
+ *
+ * @returns {boolean} True if remote operations should be skipped (requireRemote=false)
+ *
+ * @example
+ * ```yaml
+ * # .lumenflow.config.yaml
+ * git:
+ *   requireRemote: false  # Enable local-only mode
+ * ```
+ */
+export declare function shouldSkipRemoteOperations(): boolean;
 /**
  * Temp branch prefix for micro-worktree operations
  *
@@ -215,6 +321,23 @@ export declare function mergeWithRetry(tempBranchName: string, microWorktreePath
  * @throws {Error} If push fails after all retries
  */
 export declare function pushWithRetry(mainGit: GitAdapter, worktreeGit: GitAdapter, remote: string, branch: string, tempBranchName: string, logPrefix?: string): Promise<void>;
+/**
+ * WU-1332: Push to origin with configurable retry using p-retry
+ *
+ * Enhanced version of pushWithRetry that uses p-retry for exponential backoff
+ * and supports configuration via PushRetryConfig. When push fails due to
+ * non-fast-forward (origin moved), automatically rebases and retries.
+ *
+ * @param {Object} mainGit - GitAdapter instance for main checkout
+ * @param {Object} worktreeGit - GitAdapter instance for micro-worktree
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} branch - Branch name (e.g., 'main')
+ * @param {string} tempBranchName - Temp branch that was merged (for rebase)
+ * @param {string} logPrefix - Log prefix for console output
+ * @param {PushRetryConfig} config - Push retry configuration
+ * @throws {Error} If push fails after all retries or if retry is disabled
+ */
+export declare function pushWithRetryConfig(mainGit: GitAdapter, worktreeGit: GitAdapter, remote: string, branch: string, tempBranchName: string, logPrefix?: string, config?: PushRetryConfig): Promise<void>;
 /**
  * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
  *
@@ -234,6 +357,33 @@ export declare function pushWithRetry(mainGit: GitAdapter, worktreeGit: GitAdapt
  * @throws {Error} If push fails (env vars still restored)
  */
 export declare function pushRefspecWithForce(gitAdapter: GitAdapter, remote: string, localRef: string, remoteRef: string, reason: string): Promise<void>;
+/**
+ * WU-1337: Push using refspec with LUMENFLOW_FORCE and retry logic
+ *
+ * Enhanced version of pushRefspecWithForce that adds retry with rebase
+ * on non-fast-forward errors. Uses p-retry for exponential backoff and
+ * respects git.push_retry configuration.
+ *
+ * On each retry:
+ * 1. Fetch origin/main to get latest state
+ * 2. Rebase the temp branch onto the updated main
+ * 3. Retry the push with LUMENFLOW_FORCE
+ *
+ * This is used by pushOnly mode in withMicroWorktree to handle race conditions
+ * when multiple agents are pushing to origin/main concurrently.
+ *
+ * @param {GitAdapter} gitWorktree - GitAdapter instance for the worktree (for rebase)
+ * @param {GitAdapter} mainGit - GitAdapter instance for main checkout (for fetch)
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} localRef - Local ref to push (e.g., 'tmp/wu-claim/wu-123')
+ * @param {string} remoteRef - Remote ref to update (e.g., 'main')
+ * @param {string} reason - Audit reason for the LUMENFLOW_FORCE bypass
+ * @param {string} logPrefix - Log prefix for console output
+ * @param {PushRetryConfig} config - Push retry configuration
+ * @returns {Promise<void>}
+ * @throws {RetryExhaustionError} If push fails after all retries
+ */
+export declare function pushRefspecWithRetry(gitWorktree: GitAdapter, mainGit: GitAdapter, remote: string, localRef: string, remoteRef: string, reason: string, logPrefix?: string, config?: PushRetryConfig): Promise<void>;
 /**
  * Execute an operation in a micro-worktree with full isolation
  *
@@ -243,6 +393,7 @@ export declare function pushRefspecWithForce(gitAdapter: GitAdapter, remote: str
  *
  * WU-1435: Added pushOnly option to keep local main pristine.
  * WU-2237: Added pre-creation cleanup of orphaned temp branches/worktrees.
+ * WU-1337: Push-only path now uses retry with rebase.
  *
  * @param {Object} options - Options for the operation
  * @param {string} options.operation - Operation name (e.g., 'wu-create', 'wu-edit')