@lumenflow/core 1.4.0 → 1.5.0

package/README.md

@@ -70,23 +70,54 @@ await worktrees.remove('worktrees/operations-wu-123');
 
 ### Agent Branch Patterns
 
-Check if a branch is an agent branch that can bypass worktree requirements. Patterns are fetched from a central registry with 7-day caching.
+Check if a branch is an agent branch that can bypass worktree requirements. Patterns are fetched from a central registry with 7-day caching, and can be configured via `.lumenflow.config.yaml`.
 
 ```typescript
-import { isAgentBranch, getAgentPatterns } from '@lumenflow/core';
+import { isAgentBranch, isAgentBranchWithDetails, resolveAgentPatterns } from '@lumenflow/core';
 
 // Check if branch can bypass worktree requirements (async, uses registry)
 if (await isAgentBranch('claude/session-12345')) {
   console.log('Agent branch - bypass allowed');
 }
 
-// Get the current list of agent patterns
-const patterns = await getAgentPatterns();
-// ['agent/*', 'claude/*', 'codex/*', 'copilot/*', 'cursor/*', ...]
+// Get detailed result for observability
+const result = await isAgentBranchWithDetails('claude/session-123');
+if (result.isMatch) {
+  console.log(`Matched via ${result.patternResult.source}`); // 'registry', 'merged', 'override', 'config', 'defaults'
+  console.log(`Registry fetched: ${result.patternResult.registryFetched}`);
+}
+
+// Resolve patterns with custom options (useful for testing)
+const resolved = await resolveAgentPatterns({
+  configPatterns: ['my-agent/*'], // Merge with registry
+  // overridePatterns: ['only-this/*'], // Replace registry entirely
+  // disableAgentPatternRegistry: true, // Airgapped mode
+});
+console.log(resolved.patterns, resolved.source);
 
 // Synchronous version (uses local config only, no registry fetch)
 import { isAgentBranchSync } from '@lumenflow/core';
-const result = isAgentBranchSync('agent/task-123');
+const syncResult = isAgentBranchSync('agent/task-123');
+```
+
+#### Configuration Options
+
+In `.lumenflow.config.yaml`:
+
+```yaml
+git:
+  # Patterns to MERGE with registry (default: [])
+  agentBranchPatterns:
+    - 'my-custom-agent/*'
+    - 'internal-tool/*'
+
+  # Patterns that REPLACE registry entirely (optional)
+  # agentBranchPatternsOverride:
+  #   - 'claude/*'
+  #   - 'codex/*'
+
+  # Disable registry fetch for airgapped environments (default: false)
+  # disableAgentPatternRegistry: true
 ```
 
 Protected branches (main, master, lane/\*) are **never** bypassed, regardless of patterns.

package/dist/agent-patterns-registry.d.ts

@@ -5,6 +5,8 @@
  * that bypass worktree requirements. Static JSON served from lumenflow.dev,
  * cached locally for 7 days with fallback to defaults.
  *
+ * WU-1089: Added merge/override/airgapped modes via resolveAgentPatterns()
+ *
  * @module agent-patterns-registry
  */
 /** Default agent branch patterns (narrow: just agent/*) */
@@ -16,12 +18,48 @@ export declare const CACHE_TTL_MS: number;
 /**
  * Options for getAgentPatterns
  */
-interface GetAgentPatternsOptions {
+export interface GetAgentPatternsOptions {
     /** Override cache directory (default: ~/.lumenflow/cache) */
     cacheDir?: string;
     /** Fetch timeout in milliseconds (default: 5000) */
     timeoutMs?: number;
 }
+/**
+ * Source of agent patterns for observability
+ */
+export type AgentPatternSource = 'registry' | 'merged' | 'override' | 'config' | 'defaults';
+/**
+ * Result of resolveAgentPatterns with observability fields
+ */
+export interface AgentPatternResult {
+    /** Resolved patterns to use for agent branch matching */
+    patterns: string[];
+    /** Source of the patterns for observability */
+    source: AgentPatternSource;
+    /** Whether the registry was successfully fetched */
+    registryFetched: boolean;
+}
+/**
+ * Type for injectable registry fetcher function
+ */
+export type RegistryFetcher = (options: GetAgentPatternsOptions) => Promise<string[]>;
+/**
+ * Options for resolveAgentPatterns (WU-1089)
+ */
+export interface ResolveAgentPatternsOptions {
+    /** Injectable registry fetcher for testing (uses getAgentPatterns by default) */
+    registryFetcher?: RegistryFetcher;
+    /** Patterns from config.git.agentBranchPatterns (merged with registry by default) */
+    configPatterns?: string[];
+    /** Patterns from config.git.agentBranchPatternsOverride (replaces everything if set) */
+    overridePatterns?: string[];
+    /** config.git.disableAgentPatternRegistry - skips network fetch (airgapped mode) */
+    disableAgentPatternRegistry?: boolean;
+    /** Override cache directory (passed to fetcher) */
+    cacheDir?: string;
+    /** Fetch timeout in milliseconds (passed to fetcher) */
+    timeoutMs?: number;
+}
 /**
  * Get the default cache directory
  *
@@ -44,10 +82,70 @@ export declare function getCacheDir(): string;
  * ```
  */
 export declare function getAgentPatterns(options?: GetAgentPatternsOptions): Promise<string[]>;
+/**
+ * Resolve agent branch patterns based on config with merge/override/airgapped support
+ *
+ * Behavior matrix (WU-1089):
+ *
+ * | disableRegistry | override patterns | config patterns | Result                 | Source        |
+ * |-----------------|-------------------|-----------------|------------------------|---------------|
+ * | false           | undefined         | undefined/[]    | registry               | 'registry'    |
+ * | false           | undefined         | ['custom/*']    | config + registry      | 'merged'      |
+ * | false           | ['only/*']        | any             | override only          | 'override'    |
+ * | true            | undefined         | undefined/[]    | defaults               | 'defaults'    |
+ * | true            | undefined         | ['custom/*']    | config only            | 'config'      |
+ * | true            | ['only/*']        | any             | override only          | 'override'    |
+ *
+ * When registry fetch fails:
+ * - Falls back to config patterns if provided, source = 'config'
+ * - Falls back to defaults if no config, source = 'defaults'
+ *
+ * @param options - Resolution options
+ * @returns Result with patterns, source, and registryFetched flag
+ *
+ * @example Default (fetch from registry)
+ * ```typescript
+ * const result = await resolveAgentPatterns({});
+ * // result.patterns = ['claude/*', 'codex/*', ...] (from registry)
+ * // result.source = 'registry'
+ * // result.registryFetched = true
+ * ```
+ *
+ * @example Merge mode (config + registry)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   configPatterns: ['my-agent/*'],
+ * });
+ * // result.patterns = ['my-agent/*', 'claude/*', 'codex/*', ...]
+ * // result.source = 'merged'
+ * // result.registryFetched = true
+ * ```
+ *
+ * @example Override mode (explicit replacement)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   overridePatterns: ['only-this/*'],
+ * });
+ * // result.patterns = ['only-this/*']
+ * // result.source = 'override'
+ * // result.registryFetched = false
+ * ```
+ *
+ * @example Airgapped mode (no network)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   disableAgentPatternRegistry: true,
+ *   configPatterns: ['my-agent/*'],
+ * });
+ * // result.patterns = ['my-agent/*']
+ * // result.source = 'config'
+ * // result.registryFetched = false
+ * ```
+ */
+export declare function resolveAgentPatterns(options?: ResolveAgentPatternsOptions): Promise<AgentPatternResult>;
 /**
  * Clear the in-memory cache
  *
  * Used primarily for testing.
  */
 export declare function clearCache(): void;
-export {};

package/dist/agent-patterns-registry.js

@@ -5,6 +5,8 @@
  * that bypass worktree requirements. Static JSON served from lumenflow.dev,
  * cached locally for 7 days with fallback to defaults.
  *
+ * WU-1089: Added merge/override/airgapped modes via resolveAgentPatterns()
+ *
  * @module agent-patterns-registry
  */
 import * as fs from 'node:fs';
@@ -179,6 +181,128 @@ export async function getAgentPatterns(options = {}) {
     // No cache, no network - use defaults
     return DEFAULT_AGENT_PATTERNS;
 }
+/**
+ * Resolve agent branch patterns based on config with merge/override/airgapped support
+ *
+ * Behavior matrix (WU-1089):
+ *
+ * | disableRegistry | override patterns | config patterns | Result                 | Source        |
+ * |-----------------|-------------------|-----------------|------------------------|---------------|
+ * | false           | undefined         | undefined/[]    | registry               | 'registry'    |
+ * | false           | undefined         | ['custom/*']    | config + registry      | 'merged'      |
+ * | false           | ['only/*']        | any             | override only          | 'override'    |
+ * | true            | undefined         | undefined/[]    | defaults               | 'defaults'    |
+ * | true            | undefined         | ['custom/*']    | config only            | 'config'      |
+ * | true            | ['only/*']        | any             | override only          | 'override'    |
+ *
+ * When registry fetch fails:
+ * - Falls back to config patterns if provided, source = 'config'
+ * - Falls back to defaults if no config, source = 'defaults'
+ *
+ * @param options - Resolution options
+ * @returns Result with patterns, source, and registryFetched flag
+ *
+ * @example Default (fetch from registry)
+ * ```typescript
+ * const result = await resolveAgentPatterns({});
+ * // result.patterns = ['claude/*', 'codex/*', ...] (from registry)
+ * // result.source = 'registry'
+ * // result.registryFetched = true
+ * ```
+ *
+ * @example Merge mode (config + registry)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   configPatterns: ['my-agent/*'],
+ * });
+ * // result.patterns = ['my-agent/*', 'claude/*', 'codex/*', ...]
+ * // result.source = 'merged'
+ * // result.registryFetched = true
+ * ```
+ *
+ * @example Override mode (explicit replacement)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   overridePatterns: ['only-this/*'],
+ * });
+ * // result.patterns = ['only-this/*']
+ * // result.source = 'override'
+ * // result.registryFetched = false
+ * ```
+ *
+ * @example Airgapped mode (no network)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   disableAgentPatternRegistry: true,
+ *   configPatterns: ['my-agent/*'],
+ * });
+ * // result.patterns = ['my-agent/*']
+ * // result.source = 'config'
+ * // result.registryFetched = false
+ * ```
+ */
+export async function resolveAgentPatterns(options = {}) {
+    const { registryFetcher = getAgentPatterns, configPatterns, overridePatterns, disableAgentPatternRegistry = false, cacheDir, timeoutMs, } = options;
+    // Scenario 3/6: Override mode - overridePatterns replaces everything
+    if (overridePatterns && overridePatterns.length > 0) {
+        return {
+            patterns: overridePatterns,
+            source: 'override',
+            registryFetched: false,
+        };
+    }
+    // Scenario 4/5: Airgapped mode - disableAgentPatternRegistry skips network
+    if (disableAgentPatternRegistry) {
+        const hasConfigPatterns = configPatterns && configPatterns.length > 0;
+        return {
+            patterns: hasConfigPatterns ? configPatterns : DEFAULT_AGENT_PATTERNS,
+            source: hasConfigPatterns ? 'config' : 'defaults',
+            registryFetched: false,
+        };
+    }
+    // Scenario 1/2: Normal mode - fetch from registry, optionally merge with config
+    const hasConfigPatterns = configPatterns && configPatterns.length > 0;
+    // Try to fetch from registry
+    let registryPatterns = null;
+    let fetchedSuccessfully = false;
+    try {
+        registryPatterns = await registryFetcher({ cacheDir, timeoutMs });
+        fetchedSuccessfully = registryPatterns !== null && registryPatterns.length > 0;
+    }
+    catch {
+        // Fetch failed - will use fallback below
+        fetchedSuccessfully = false;
+    }
+    // If registry fetch succeeded
+    if (fetchedSuccessfully && registryPatterns) {
+        if (hasConfigPatterns) {
+            // Scenario 2: Merge mode - config first, then registry (deduplicated)
+            const merged = [...configPatterns];
+            for (const pattern of registryPatterns) {
+                if (!merged.includes(pattern)) {
+                    merged.push(pattern);
+                }
+            }
+            return {
+                patterns: merged,
+                source: 'merged',
+                registryFetched: true,
+            };
+        }
+        // Scenario 1: Registry only
+        return {
+            patterns: registryPatterns,
+            source: 'registry',
+            registryFetched: true,
+        };
+    }
+    // Registry fetch failed - fallback to config or defaults
+    return {
+        patterns: hasConfigPatterns ? configPatterns : DEFAULT_AGENT_PATTERNS,
+        source: hasConfigPatterns ? 'config' : 'defaults',
+        registryFetched: false,
+    };
+}
 /**
  * Clear the in-memory cache
  *

package/dist/arg-parser.js

@@ -247,6 +247,13 @@ export const WU_OPTIONS = {
         flags: '--color',
         description: 'Enable colored output',
     },
+    // WU-1085: NO_COLOR standard support (https://no-color.org/)
+    noColor: {
+        name: 'noColor',
+        flags: '--no-color',
+        description: 'Disable colored output (respects NO_COLOR env var)',
+        isNegated: true,
+    },
     status: {
         name: 'status',
         flags: '--status <status>',

package/dist/branch-check.d.ts

@@ -4,14 +4,19 @@
  * Provides functions to check if a branch is an agent branch that can
  * bypass worktree requirements, and if headless mode is allowed.
  *
+ * WU-1089: Updated to use resolveAgentPatterns with merge/override/airgapped support.
+ *
  * @module branch-check
  */
+import { type AgentPatternResult } from './agent-patterns-registry.js';
 /**
  * Check if branch is an agent branch that can bypass worktree requirements.
  *
- * Uses the central registry for agent patterns (fetched from lumenflow.dev
- * with 7-day cache), falling back to config patterns if specified, then
- * to defaults.
+ * WU-1089: Now uses resolveAgentPatterns with proper merge/override/airgapped support:
+ * - Default: Fetches from registry (lumenflow.dev) with 7-day cache
+ * - Config patterns merge with registry patterns (config first)
+ * - Override patterns (agentBranchPatternsOverride) replace everything
+ * - Airgapped mode (disableAgentPatternRegistry) skips network fetch
  *
  * @param branch - Branch name to check
  * @returns Promise<true> if branch matches agent patterns
@@ -24,12 +29,36 @@
  * ```
  */
 export declare function isAgentBranch(branch: string | null | undefined): Promise<boolean>;
+/**
+ * Check if branch is an agent branch with full result details.
+ *
+ * Same as isAgentBranch but returns the full AgentPatternResult
+ * for observability and debugging.
+ *
+ * @param branch - Branch name to check
+ * @returns Promise with match result and pattern resolution details
+ *
+ * @example
+ * ```typescript
+ * const result = await isAgentBranchWithDetails('claude/session-123');
+ * if (result.isMatch) {
+ *   console.log(`Matched via ${result.patternResult.source}`);
+ *   console.log(`Registry fetched: ${result.patternResult.registryFetched}`);
+ * }
+ * ```
+ */
+export declare function isAgentBranchWithDetails(branch: string | null | undefined): Promise<{
+    isMatch: boolean;
+    patternResult: AgentPatternResult;
+}>;
 /**
  * Synchronous version of isAgentBranch for backwards compatibility.
  *
  * Uses only local config patterns or defaults - does NOT fetch from registry.
  * Prefer async isAgentBranch() when possible.
  *
+ * WU-1089: Updated to respect override and disable flags, but cannot fetch from registry.
+ *
  * @param branch - Branch name to check
  * @returns True if branch matches agent patterns
  *

package/dist/branch-check.js

@@ -4,11 +4,13 @@
  * Provides functions to check if a branch is an agent branch that can
  * bypass worktree requirements, and if headless mode is allowed.
  *
+ * WU-1089: Updated to use resolveAgentPatterns with merge/override/airgapped support.
+ *
  * @module branch-check
  */
 import micromatch from 'micromatch';
 import { getConfig } from './lumenflow-config.js';
-import { getAgentPatterns, DEFAULT_AGENT_PATTERNS } from './agent-patterns-registry.js';
+import { resolveAgentPatterns, DEFAULT_AGENT_PATTERNS, } from './agent-patterns-registry.js';
 /** Legacy protected branch (always protected regardless of mainBranch setting) */
 const LEGACY_PROTECTED = 'master';
 /**
@@ -36,9 +38,11 @@ function getProtectedBranches() {
 /**
  * Check if branch is an agent branch that can bypass worktree requirements.
  *
- * Uses the central registry for agent patterns (fetched from lumenflow.dev
- * with 7-day cache), falling back to config patterns if specified, then
- * to defaults.
+ * WU-1089: Now uses resolveAgentPatterns with proper merge/override/airgapped support:
+ * - Default: Fetches from registry (lumenflow.dev) with 7-day cache
+ * - Config patterns merge with registry patterns (config first)
+ * - Override patterns (agentBranchPatternsOverride) replace everything
+ * - Airgapped mode (disableAgentPatternRegistry) skips network fetch
  *
  * @param branch - Branch name to check
  * @returns Promise<true> if branch matches agent patterns
@@ -66,18 +70,73 @@ export async function isAgentBranch(branch) {
     // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
     if (getLaneBranchPattern().test(branch))
         return false;
-    // Get patterns: prefer config override, then registry, then defaults
-    let patterns;
-    if (config?.git?.agentBranchPatterns?.length > 0) {
-        // Config has explicit patterns - use those
-        patterns = config.git.agentBranchPatterns;
+    // WU-1089: Use resolveAgentPatterns with full merge/override/airgapped support
+    const result = await resolveAgentPatterns({
+        configPatterns: config?.git?.agentBranchPatterns,
+        overridePatterns: config?.git?.agentBranchPatternsOverride,
+        disableAgentPatternRegistry: config?.git?.disableAgentPatternRegistry,
+    });
+    // Use micromatch for proper glob matching
+    return micromatch.isMatch(branch, result.patterns);
+}
+/**
+ * Check if branch is an agent branch with full result details.
+ *
+ * Same as isAgentBranch but returns the full AgentPatternResult
+ * for observability and debugging.
+ *
+ * @param branch - Branch name to check
+ * @returns Promise with match result and pattern resolution details
+ *
+ * @example
+ * ```typescript
+ * const result = await isAgentBranchWithDetails('claude/session-123');
+ * if (result.isMatch) {
+ *   console.log(`Matched via ${result.patternResult.source}`);
+ *   console.log(`Registry fetched: ${result.patternResult.registryFetched}`);
+ * }
+ * ```
+ */
+export async function isAgentBranchWithDetails(branch) {
+    // Fail-closed: no branch = protected
+    if (!branch) {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
     }
-    else {
-        // Fetch from registry (with caching and fallback to defaults)
-        patterns = await getAgentPatterns();
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD') {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
     }
-    // Use micromatch for proper glob matching
-    return micromatch.isMatch(branch, patterns);
+    // Load config
+    const config = getConfig();
+    const protectedBranches = getProtectedBranches();
+    // Protected branches are NEVER bypassed
+    if (protectedBranches.includes(branch)) {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
+    }
+    // Lane branches require worktrees
+    if (getLaneBranchPattern().test(branch)) {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
+    }
+    // Resolve patterns with full details
+    const patternResult = await resolveAgentPatterns({
+        configPatterns: config?.git?.agentBranchPatterns,
+        overridePatterns: config?.git?.agentBranchPatternsOverride,
+        disableAgentPatternRegistry: config?.git?.disableAgentPatternRegistry,
+    });
+    const isMatch = micromatch.isMatch(branch, patternResult.patterns);
+    return { isMatch, patternResult };
 }
 /**
  * Synchronous version of isAgentBranch for backwards compatibility.
@@ -85,6 +144,8 @@ export async function isAgentBranch(branch) {
  * Uses only local config patterns or defaults - does NOT fetch from registry.
  * Prefer async isAgentBranch() when possible.
  *
+ * WU-1089: Updated to respect override and disable flags, but cannot fetch from registry.
+ *
  * @param branch - Branch name to check
  * @returns True if branch matches agent patterns
  *
@@ -106,7 +167,12 @@ export function isAgentBranchSync(branch) {
     // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
     if (getLaneBranchPattern().test(branch))
         return false;
-    // Use config patterns or defaults (no registry fetch in sync version)
+    // WU-1089: Check override first
+    if (config?.git?.agentBranchPatternsOverride?.length) {
+        return micromatch.isMatch(branch, config.git.agentBranchPatternsOverride);
+    }
+    // Use config patterns if provided, otherwise defaults
+    // Note: sync version cannot fetch from registry
     const patterns = config?.git?.agentBranchPatterns?.length > 0
         ? config.git.agentBranchPatterns
         : DEFAULT_AGENT_PATTERNS;

package/dist/color-support.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file color-support.ts
+ * Color control for CLI commands (WU-1085)
+ *
+ * Respects standard environment variables and CLI flags:
+ * - NO_COLOR: Disable colors (https://no-color.org/)
+ * - FORCE_COLOR: Override color level 0-3 (chalk standard)
+ * - --no-color: CLI flag to disable colors
+ *
+ * @see https://no-color.org/
+ * @see https://github.com/chalk/chalk#supportscolor
+ */
+/**
+ * Get the current color level.
+ * @returns Color level 0-3 (0 = no colors, 3 = full 16m colors)
+ */
+export declare function getColorLevel(): number;
+/**
+ * Initialize color support respecting NO_COLOR and FORCE_COLOR standards.
+ * Call this before any colored output.
+ *
+ * Priority order:
+ * 1. NO_COLOR env var (always wins, per spec)
+ * 2. --no-color CLI flag
+ * 3. FORCE_COLOR env var
+ * 4. Default chalk detection
+ *
+ * @param argv - Command line arguments (defaults to process.argv)
+ * @see https://no-color.org/
+ * @see https://github.com/chalk/chalk#supportscolor
+ */
+export declare function initColorSupport(argv?: string[]): void;

package/dist/color-support.js

@@ -0,0 +1,64 @@
+/**
+ * @file color-support.ts
+ * Color control for CLI commands (WU-1085)
+ *
+ * Respects standard environment variables and CLI flags:
+ * - NO_COLOR: Disable colors (https://no-color.org/)
+ * - FORCE_COLOR: Override color level 0-3 (chalk standard)
+ * - --no-color: CLI flag to disable colors
+ *
+ * @see https://no-color.org/
+ * @see https://github.com/chalk/chalk#supportscolor
+ */
+import chalk from 'chalk';
+/** Internal storage for color level (allows testing without chalk singleton issues) */
+let currentColorLevel = chalk.level;
+/**
+ * Get the current color level.
+ * @returns Color level 0-3 (0 = no colors, 3 = full 16m colors)
+ */
+export function getColorLevel() {
+    return currentColorLevel;
+}
+/**
+ * Initialize color support respecting NO_COLOR and FORCE_COLOR standards.
+ * Call this before any colored output.
+ *
+ * Priority order:
+ * 1. NO_COLOR env var (always wins, per spec)
+ * 2. --no-color CLI flag
+ * 3. FORCE_COLOR env var
+ * 4. Default chalk detection
+ *
+ * @param argv - Command line arguments (defaults to process.argv)
+ * @see https://no-color.org/
+ * @see https://github.com/chalk/chalk#supportscolor
+ */
+export function initColorSupport(argv = process.argv) {
+    // NO_COLOR standard (https://no-color.org/)
+    // "When set (to any value, including empty string), it should disable colors"
+    if (process.env.NO_COLOR !== undefined) {
+        chalk.level = 0;
+        currentColorLevel = 0;
+        return;
+    }
+    // CLI --no-color flag
+    if (argv.includes('--no-color')) {
+        chalk.level = 0;
+        currentColorLevel = 0;
+        return;
+    }
+    // FORCE_COLOR override (chalk standard)
+    // Values: 0 = no color, 1 = basic, 2 = 256, 3 = 16m
+    if (process.env.FORCE_COLOR !== undefined) {
+        const level = parseInt(process.env.FORCE_COLOR, 10);
+        if (!isNaN(level) && level >= 0 && level <= 3) {
+            chalk.level = level;
+            currentColorLevel = level;
+        }
+        // Invalid values are ignored, keep default
+        return;
+    }
+    // Use chalk's default detection
+    currentColorLevel = chalk.level;
+}

package/dist/cycle-detector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cycle Detection Module (WU-1088)
+ *
+ * Provides cycle detection for WU dependency graphs.
+ * Extracted from @lumenflow/initiatives to break circular dependency.
+ *
+ * @module @lumenflow/core/cycle-detector
+ */
+/**
+ * WU object interface for validation and cycle detection
+ * Note: This interface is shared with @lumenflow/initiatives for backward compatibility
+ */
+export interface WUObject {
+    id?: string;
+    blocks?: string[];
+    blocked_by?: string[];
+    initiative?: string;
+    phase?: number;
+    [key: string]: unknown;
+}
+/**
+ * Result of cycle detection
+ */
+export interface CycleResult {
+    hasCycle: boolean;
+    cycles: string[][];
+}
+/**
+ * Detects circular dependencies in WU dependency graph using DFS
+ *
+ * Uses standard cycle detection: tracks visited nodes and nodes in current
+ * recursion stack. If we encounter a node already in the recursion stack,
+ * we've found a cycle.
+ *
+ * Note: This function treats both `blocks` and `blocked_by` as edges for
+ * traversal. This means if WU-A blocks WU-B, and WU-B's blocked_by includes
+ * WU-A, following both directions will find a path back to WU-A.
+ *
+ * @param wuMap - Map of WU ID to WU object
+ * @returns Cycle detection result with hasCycle boolean and cycles array
+ *
+ * @example
+ * const wuMap = new Map([
+ *   ['WU-001', { id: 'WU-001', blocks: ['WU-002'] }],
+ *   ['WU-002', { id: 'WU-002', blocks: ['WU-001'] }],
+ * ]);
+ * const result = detectCycles(wuMap);
+ * // result.hasCycle === true
+ * // result.cycles contains the cycle path
+ */
+export declare function detectCycles(wuMap: Map<string, WUObject>): CycleResult;

package/dist/cycle-detector.js

@@ -0,0 +1,89 @@
+/**
+ * Cycle Detection Module (WU-1088)
+ *
+ * Provides cycle detection for WU dependency graphs.
+ * Extracted from @lumenflow/initiatives to break circular dependency.
+ *
+ * @module @lumenflow/core/cycle-detector
+ */
+/**
+ * Detects circular dependencies in WU dependency graph using DFS
+ *
+ * Uses standard cycle detection: tracks visited nodes and nodes in current
+ * recursion stack. If we encounter a node already in the recursion stack,
+ * we've found a cycle.
+ *
+ * Note: This function treats both `blocks` and `blocked_by` as edges for
+ * traversal. This means if WU-A blocks WU-B, and WU-B's blocked_by includes
+ * WU-A, following both directions will find a path back to WU-A.
+ *
+ * @param wuMap - Map of WU ID to WU object
+ * @returns Cycle detection result with hasCycle boolean and cycles array
+ *
+ * @example
+ * const wuMap = new Map([
+ *   ['WU-001', { id: 'WU-001', blocks: ['WU-002'] }],
+ *   ['WU-002', { id: 'WU-002', blocks: ['WU-001'] }],
+ * ]);
+ * const result = detectCycles(wuMap);
+ * // result.hasCycle === true
+ * // result.cycles contains the cycle path
+ */
+export function detectCycles(wuMap) {
+    const visited = new Set();
+    const recursionStack = new Set();
+    const cycles = [];
+    /**
+     * DFS traversal to detect cycles
+     * @param wuId - Current WU ID
+     * @param path - Current path from root
+     * @returns True if cycle found
+     */
+    function dfs(wuId, path) {
+        // If node is in recursion stack, we found a cycle
+        if (recursionStack.has(wuId)) {
+            const cycleStart = path.indexOf(wuId);
+            if (cycleStart !== -1) {
+                cycles.push([...path.slice(cycleStart), wuId]);
+            }
+            else {
+                // Self-reference case
+                cycles.push([wuId, wuId]);
+            }
+            return true;
+        }
+        // If already fully visited, skip
+        if (visited.has(wuId)) {
+            return false;
+        }
+        // Mark as being processed
+        visited.add(wuId);
+        recursionStack.add(wuId);
+        // Get dependencies (both blocks and blocked_by create edges)
+        // Only use arrays - ignore legacy string format for backward compatibility
+        const wu = wuMap.get(wuId);
+        const blocks = Array.isArray(wu?.blocks) ? wu.blocks : [];
+        const blockedBy = Array.isArray(wu?.blocked_by) ? wu.blocked_by : [];
+        const deps = [...blocks, ...blockedBy];
+        // Visit all dependencies
+        for (const dep of deps) {
+            // Only traverse if the dependency exists in our map
+            if (wuMap.has(dep)) {
+                dfs(dep, [...path, wuId]);
+            }
+        }
+        // Remove from recursion stack (done processing)
+        recursionStack.delete(wuId);
+        return false;
+    }
+    // Run DFS from each node to find all cycles
+    for (const wuId of wuMap.keys()) {
+        if (!visited.has(wuId)) {
+            dfs(wuId, []);
+        }
+    }
+    return {
+        hasCycle: cycles.length > 0,
+        cycles,
+    };
+}

package/dist/dependency-graph.js

@@ -3,17 +3,7 @@ import path from 'node:path';
 import { readWU } from './wu-yaml.js';
 import { WU_PATHS } from './wu-paths.js';
 import { STRING_LITERALS, WU_STATUS } from './wu-constants.js';
-// Optional import from @lumenflow/initiatives - if not available, provide stub
-let detectCycles;
-try {
-    // Dynamic import for optional peer dependency
-    const module = await import('@lumenflow/initiatives');
-    detectCycles = module.detectCycles;
-}
-catch {
-    // Fallback stub if @lumenflow/initiatives is not available
-    detectCycles = () => ({ hasCycle: false, cycles: [] });
-}
+import { detectCycles } from './cycle-detector.js';
 /**
  * Dependency Graph Module (WU-1247, WU-1568)
  *

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './date-utils.js';
 export * from './error-handler.js';
 export * from './retry-strategy.js';
 export * from './beacon-migration.js';
+export * from './cycle-detector.js';
 export { DEFAULT_DOMAIN, inferDefaultDomain, normalizeToEmail, isValidEmail, } from './user-normalizer.js';
 export * from './git-adapter.js';
 export * from './state-machine.js';
@@ -47,3 +48,4 @@ export * from './agent-patterns-registry.js';
 export * from './lumenflow-home.js';
 export * from './force-bypass-audit.js';
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';
+export * from './color-support.js';

package/dist/index.js

@@ -11,6 +11,8 @@ export * from './error-handler.js';
 export * from './retry-strategy.js';
 // Migration utilities (WU-1075)
 export * from './beacon-migration.js';
+// Cycle detection (WU-1088 - extracted from initiatives to break circular dependency)
+export * from './cycle-detector.js';
 // User normalizer (explicit exports to avoid conflicts)
 export { DEFAULT_DOMAIN, inferDefaultDomain, normalizeToEmail, isValidEmail, } from './user-normalizer.js';
 // Git operations
@@ -73,3 +75,5 @@ export * from './lumenflow-home.js';
 export * from './force-bypass-audit.js';
 // WU-1075: LumenFlow directory paths (exported from wu-constants)
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';
+// WU-1085: Color support for NO_COLOR/FORCE_COLOR/--no-color
+export * from './color-support.js';

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

@@ -53,6 +53,8 @@ export declare const GitConfigSchema: z.ZodObject<{
     branchDriftWarning: z.ZodDefault<z.ZodNumber>;
     branchDriftInfo: z.ZodDefault<z.ZodNumber>;
     agentBranchPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    agentBranchPatternsOverride: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disableAgentPatternRegistry: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * WU (Work Unit) configuration
@@ -245,6 +247,8 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
         branchDriftWarning: z.ZodDefault<z.ZodNumber>;
         branchDriftInfo: z.ZodDefault<z.ZodNumber>;
         agentBranchPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        agentBranchPatternsOverride: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        disableAgentPatternRegistry: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     wu: z.ZodDefault<z.ZodObject<{
         idPattern: z.ZodDefault<z.ZodString>;
@@ -394,6 +398,8 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
         branchDriftWarning: number;
         branchDriftInfo: number;
         agentBranchPatterns: string[];
+        disableAgentPatternRegistry: boolean;
+        agentBranchPatternsOverride?: string[];
     };
     wu: {
         idPattern: string;

package/dist/lumenflow-config-schema.js

@@ -86,12 +86,55 @@ export const GitConfigSchema = z.object({
     /** 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.
+     * Agent branch patterns to MERGE with the registry patterns.
+     * These patterns are merged with patterns from lumenflow.dev/registry/agent-patterns.json.
+     * Use this to add custom patterns that should work alongside the standard vendor patterns.
      * Protected branches (mainBranch + 'master') are NEVER bypassed.
+     *
+     * WU-1089: Changed default from ['agent/*'] to [] to allow registry to be used by default.
+     *
+     * @example
+     * ```yaml
+     * git:
+     *   agentBranchPatterns:
+     *     - 'my-custom-agent/*'
+     *     - 'internal-tool/*'
+     * ```
      */
-    agentBranchPatterns: z.array(z.string()).default(['agent/*']),
+    agentBranchPatterns: z.array(z.string()).default([]),
+    /**
+     * Agent branch patterns that REPLACE the registry patterns entirely.
+     * When set, these patterns are used instead of fetching from the registry.
+     * The agentBranchPatterns field is ignored when this is set.
+     *
+     * Use this for strict control over which agent patterns are allowed.
+     *
+     * @example
+     * ```yaml
+     * git:
+     *   agentBranchPatternsOverride:
+     *     - 'claude/*'
+     *     - 'codex/*'
+     * ```
+     */
+    agentBranchPatternsOverride: z.array(z.string()).optional(),
+    /**
+     * Disable fetching agent patterns from the registry (airgapped mode).
+     * When true, only uses agentBranchPatterns from config or defaults to ['agent/*'].
+     * Useful for environments without network access or strict security requirements.
+     *
+     * @default false
+     *
+     * @example
+     * ```yaml
+     * git:
+     *   disableAgentPatternRegistry: true
+     *   agentBranchPatterns:
+     *     - 'claude/*'
+     *     - 'cursor/*'
+     * ```
+     */
+    disableAgentPatternRegistry: z.boolean().default(false),
 });
 /**
  * WU (Work Unit) configuration

package/dist/wu-done-preflight.js

@@ -2,6 +2,7 @@
  * Preflight validation helpers for wu:done.
  */
 import { execSync as execSyncImport } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { validatePreflight } from './wu-preflight-validators.js';
 import { LOG_PREFIX, EMOJI, STDIO } from './wu-constants.js';
 /**
@@ -164,8 +165,14 @@ export function validateAllPreCommitHooks(id, worktreePath = null, options = {})
         if (worktreePath) {
             execOptions.cwd = worktreePath;
         }
+        // WU-1086: Check for .mjs extension first, fall back to .js for backwards compatibility
+        const basePath = worktreePath || '.';
+        const mjsPath = `${basePath}/tools/gates-pre-commit.mjs`;
+        const gateScript = existsSync(mjsPath)
+            ? 'tools/gates-pre-commit.mjs'
+            : 'tools/gates-pre-commit.js';
         // Run the gates-pre-commit script that contains all validation gates
-        execSyncFn('node tools/gates-pre-commit.js', execOptions);
+        execSyncFn(`node ${gateScript}`, execOptions);
         console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All pre-commit hooks passed`);
         return { valid: true, errors: [] };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Core WU lifecycle tools for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -66,6 +66,7 @@
     "README.md"
   ],
   "dependencies": {
+    "chalk": "^5.6.2",
     "change-case": "^5.4.4",
     "cli-progress": "^3.12.0",
     "cli-table3": "^0.6.5",
@@ -91,15 +92,11 @@
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "@lumenflow/memory": "1.4.0",
-    "@lumenflow/initiatives": "1.4.0"
+    "@lumenflow/memory": "1.5.0"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {
       "optional": true
-    },
-    "@lumenflow/initiatives": {
-      "optional": true
     }
   },
   "engines": {