@lumenflow/core 1.3.6 → 1.5.0

package/dist/branch-check.js

@@ -4,12 +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';
-/** Default agent branch patterns (narrow: just agent/*) */
-const DEFAULT_AGENT_BRANCH_PATTERNS = ['agent/*'];
+import { resolveAgentPatterns, DEFAULT_AGENT_PATTERNS, } from './agent-patterns-registry.js';
 /** Legacy protected branch (always protected regardless of mainBranch setting) */
 const LEGACY_PROTECTED = 'master';
 /**
@@ -36,12 +37,121 @@ function getProtectedBranches() {
 }
 /**
  * Check if branch is an agent branch that can bypass worktree requirements.
- * Uses the existing config loader (which handles caching/validation).
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * if (await isAgentBranch('claude/session-123')) {
+ *   // Allow bypass for agent branch
+ * }
+ * ```
+ */
+export async function isAgentBranch(branch) {
+    // Fail-closed: no branch = protected
+    if (!branch)
+        return false;
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD')
+        return false;
+    // Load config (uses existing loader with caching)
+    const config = getConfig();
+    const protectedBranches = getProtectedBranches();
+    // Protected branches are NEVER bypassed (mainBranch + 'master')
+    if (protectedBranches.includes(branch))
+        return false;
+    // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
+    if (getLaneBranchPattern().test(branch))
+        return false;
+    // 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 },
+        };
+    }
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD') {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
+    }
+    // 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.
+ *
+ * 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
+ *
+ * @deprecated Use async isAgentBranch() instead for registry support
  */
-export function isAgentBranch(branch) {
+export function isAgentBranchSync(branch) {
     // Fail-closed: no branch = protected
     if (!branch)
         return false;
@@ -51,15 +161,21 @@ export function isAgentBranch(branch) {
     // Load config (uses existing loader with caching)
     const config = getConfig();
     const protectedBranches = getProtectedBranches();
-    const patterns = config?.git?.agentBranchPatterns?.length > 0
-        ? config.git.agentBranchPatterns
-        : DEFAULT_AGENT_BRANCH_PATTERNS;
     // Protected branches are NEVER bypassed (mainBranch + 'master')
     if (protectedBranches.includes(branch))
         return false;
     // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
     if (getLaneBranchPattern().test(branch))
         return false;
+    // 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;
     // Use micromatch for proper glob matching
     return micromatch.isMatch(branch, patterns);
 }

package/dist/cli/is-agent-branch.d.ts

@@ -3,6 +3,8 @@
  * CLI helper for bash hooks to check if branch is an agent branch.
  * Uses the same isAgentBranch() logic as TypeScript code.
  *
+ * Now async to support registry pattern lookup with fetch + cache.
+ *
  * Usage: node dist/cli/is-agent-branch.js [branch-name]
  * Exit codes: 0 = agent branch (allowed), 1 = not agent branch (protected)
  *

package/dist/cli/is-agent-branch.js

@@ -3,13 +3,22 @@
  * CLI helper for bash hooks to check if branch is an agent branch.
  * Uses the same isAgentBranch() logic as TypeScript code.
  *
+ * Now async to support registry pattern lookup with fetch + cache.
+ *
  * Usage: node dist/cli/is-agent-branch.js [branch-name]
  * Exit codes: 0 = agent branch (allowed), 1 = not agent branch (protected)
  *
  * @module cli/is-agent-branch
  */
 import { isAgentBranch } from '../branch-check.js';
-const branch = process.argv[2] || null;
-const result = isAgentBranch(branch);
-// Exit 0 = agent branch (truthy), Exit 1 = not agent branch
-process.exit(result ? 0 : 1);
+async function main() {
+    const branch = process.argv[2] || null;
+    const result = await isAgentBranch(branch);
+    // Exit 0 = agent branch (truthy), Exit 1 = not agent branch
+    process.exit(result ? 0 : 1);
+}
+main().catch((error) => {
+    console.error('Error checking agent branch:', error.message);
+    // Fail-closed: error = not allowed
+    process.exit(1);
+});

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';
@@ -43,6 +44,8 @@ export * from './lumenflow-config.js';
 export * from './lumenflow-config-schema.js';
 export * from './gates-config.js';
 export * from './branch-check.js';
+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
@@ -65,9 +67,13 @@ export * from './lumenflow-config-schema.js';
 export * from './gates-config.js';
 // Branch check utilities
 export * from './branch-check.js';
+// WU-1082: Agent patterns registry (fetch + cache)
+export * from './agent-patterns-registry.js';
 // WU-1062: External plan storage
 export * from './lumenflow-home.js';
 // WU-1070: Force bypass audit logging
 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/micro-worktree.d.ts

@@ -27,6 +27,7 @@
  * @see {@link tools/wu-edit.mjs} - Spec edits (WU-1274)
  * @see {@link tools/initiative-create.mjs} - Initiative creation (WU-1439)
  */
+import type { GitAdapter } from './git-adapter.js';
 /**
  * Maximum retry attempts for ff-only merge when main moves
  *
@@ -34,6 +35,18 @@
  * concurrently. Each retry fetches latest main and rebases.
  */
 export declare const MAX_MERGE_RETRIES = 3;
+/**
+ * Environment variable name for LUMENFLOW_FORCE bypass
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export declare const LUMENFLOW_FORCE_ENV = "LUMENFLOW_FORCE";
+/**
+ * Environment variable name for LUMENFLOW_FORCE_REASON audit trail
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export declare const LUMENFLOW_FORCE_REASON_ENV = "LUMENFLOW_FORCE_REASON";
 /**
  * Default log prefix for micro-worktree operations
  *
@@ -135,6 +148,25 @@ export declare function formatFiles(files: any, worktreePath: any, logPrefix?: s
  * @throws {Error} If merge fails after all retries
  */
 export declare function mergeWithRetry(tempBranchName: any, microWorktreePath: any, logPrefix?: string): Promise<void>;
+/**
+ * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
+ *
+ * WU-1081: Micro-worktree pushes to origin/main need to bypass pre-push hooks
+ * because they operate from temp branches in /tmp directories, which would
+ * otherwise be blocked by hook validation.
+ *
+ * Sets LUMENFLOW_FORCE=1 and LUMENFLOW_FORCE_REASON during the push,
+ * then restores original environment values (even on error).
+ *
+ * @param {GitAdapter} gitAdapter - GitAdapter instance to use for push
+ * @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
+ * @returns {Promise<void>}
+ * @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>;
 /**
  * Execute an operation in a micro-worktree with full isolation
  *