@lumenflow/core 1.0.0

package/dist/domain/orchestration.types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Orchestration Domain Types
+ *
+ * TypeScript types inferred from Zod schemas.
+ * Single source of truth - schemas validate at runtime, types at compile time.
+ *
+ * @module orchestration.types
+ * @see {@link ./orchestration.schemas.mjs} - Schemas these types are inferred from
+ * @see {@link ./orchestration.constants.mjs} - Constants and derived types
+ */
+import type { z } from 'zod';
+import type { GlobalStatusSchema, AgentMetricSchema, WUProgressSchema, TimelineEventSchema, AlertSchema, SuggestionSchema, ExecutionPlanSchema, UserChoiceSchema, DashboardDataSchema } from './orchestration.schemas.js';
+export type { Lane, AgentName, SeverityLevel, AgentResultStatus, TimelineEventType, EventSeverityLevel, UserChoiceOption, MandatoryAgentName, } from './orchestration.constants.js';
+export { LANES, AGENT_NAMES, SEVERITY_LEVELS, AGENT_RESULT_STATUSES, TIMELINE_EVENT_TYPES, EVENT_SEVERITY_LEVELS, USER_CHOICE_OPTIONS, MANDATORY_AGENT_NAMES, } from './orchestration.constants.js';
+/**
+ * Global orchestration status.
+ * Shows high-level dashboard metrics at a glance.
+ *
+ * @example
+ * const status: GlobalStatus = {
+ *   activeWUs: 2,
+ *   completed24h: 5,
+ *   blocked: 1,
+ *   gatesFailing: 0,
+ *   longestRunning: { wuId: 'WU-1234', lane: 'Intelligence', durationMs: 2700000 },
+ *   pendingMandatory: [{ wuId: 'WU-1235', agent: 'security-auditor' }],
+ * };
+ */
+export type GlobalStatus = z.infer<typeof GlobalStatusSchema>;
+/**
+ * Per-agent metrics for dashboard display.
+ * Tracks invocation counts, pass rates, and timing.
+ *
+ * @example
+ * const metric: AgentMetric = {
+ *   invoked: 3,
+ *   passRate: 100,
+ *   avgDurationMs: 120000,
+ *   lastRun: { wuId: 'WU-1234', timestamp: '2025-01-15T10:00:00Z', result: 'pass' },
+ * };
+ */
+export type AgentMetric = z.infer<typeof AgentMetricSchema>;
+/**
+ * Work Unit progress for dashboard display.
+ * Shows DoD progress and agent status per WU.
+ *
+ * @example
+ * const progress: WUProgress = {
+ *   wuId: 'WU-1234',
+ *   lane: 'Intelligence',
+ *   title: 'LLM Classification Feature',
+ *   dodProgress: 8,
+ *   dodTotal: 11,
+ *   agents: { 'beacon-guardian': 'pass', 'code-reviewer': 'pending' },
+ *   headline: 'Blocked on code-reviewer - awaiting approval',
+ * };
+ */
+export type WUProgress = z.infer<typeof WUProgressSchema>;
+/**
+ * Timeline event for orchestration history.
+ * Records key events for dashboard display.
+ *
+ * @example
+ * const event: TimelineEvent = {
+ *   timestamp: '2025-01-15T09:00:00Z',
+ *   event: 'claim',
+ *   wuId: 'WU-1234',
+ *   detail: 'Claimed for Intelligence lane',
+ *   severity: 'info',
+ * };
+ */
+export type TimelineEvent = z.infer<typeof TimelineEventSchema>;
+/**
+ * Dashboard alert for items requiring attention.
+ *
+ * @example
+ * const alert: Alert = {
+ *   severity: 'high',
+ *   message: 'Mandatory agent not yet invoked',
+ *   wuId: 'WU-1235',
+ *   action: 'Run security-auditor before wu:done',
+ * };
+ */
+export type Alert = z.infer<typeof AlertSchema>;
+/**
+ * Orchestration suggestion for next actions.
+ *
+ * @example
+ * const suggestion: Suggestion = {
+ *   id: 'sug-001',
+ *   priority: 'high',
+ *   action: 'Run security-auditor',
+ *   reason: 'WU touches auth paths',
+ *   command: 'pnpm orchestrate:run security-auditor',
+ * };
+ */
+export type Suggestion = z.infer<typeof SuggestionSchema>;
+/**
+ * Execution plan for proposed orchestration actions.
+ *
+ * @example
+ * const plan: ExecutionPlan = {
+ *   wuId: 'WU-1234',
+ *   steps: [
+ *     { order: 1, agent: 'beacon-guardian', status: 'pending' },
+ *     { order: 2, action: 'gates', status: 'pending' },
+ *   ],
+ *   estimatedTokens: 5000,
+ * };
+ */
+export type ExecutionPlan = z.infer<typeof ExecutionPlanSchema>;
+/**
+ * User choice on execution plan confirmation.
+ *
+ * @example
+ * const choice: UserChoice = { choice: 'approve' };
+ * const editChoice: UserChoice = { choice: 'edit', modifications: ['Skip step 2'] };
+ */
+export type UserChoice = z.infer<typeof UserChoiceSchema>;
+/**
+ * Complete dashboard data aggregating all metrics.
+ * This is the main data structure passed to renderers.
+ *
+ * @example
+ * const data: DashboardData = {
+ *   globalStatus: { ... },
+ *   agentMetrics: { 'security-auditor': { ... } },
+ *   wuProgress: [{ ... }],
+ *   timeline: [{ ... }],
+ *   alerts: [{ ... }],
+ * };
+ */
+export type DashboardData = z.infer<typeof DashboardDataSchema>;

package/dist/domain/orchestration.types.js

@@ -0,0 +1,12 @@
+/**
+ * Orchestration Domain Types
+ *
+ * TypeScript types inferred from Zod schemas.
+ * Single source of truth - schemas validate at runtime, types at compile time.
+ *
+ * @module orchestration.types
+ * @see {@link ./orchestration.schemas.mjs} - Schemas these types are inferred from
+ * @see {@link ./orchestration.constants.mjs} - Constants and derived types
+ */
+// Re-export const values as well
+export { LANES, AGENT_NAMES, SEVERITY_LEVELS, AGENT_RESULT_STATUSES, TIMELINE_EVENT_TYPES, EVENT_SEVERITY_LEVELS, USER_CHOICE_OPTIONS, MANDATORY_AGENT_NAMES, } from './orchestration.constants.js';

package/dist/error-handler.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @file error-handler.mjs
+ * @description Structured error handling with error codes
+ * WU-1082: Extract shared utilities (eliminate die() duplication)
+ *
+ * Replaces die() function in:
+ * - tools/wu-claim.mjs
+ * - tools/wu-done.mjs
+ * - tools/wu-block.mjs
+ * - tools/wu-unblock.mjs
+ * - tools/wu-create.mjs
+ * - tools/wu-cleanup.mjs
+ * - tools/gates-pre-commit.mjs
+ * - tools/validate.mjs
+ * - tools/guard-worktree-commit.mjs
+ */
+/**
+ * Structured error class with error codes and details
+ * @class WUError
+ * @extends Error
+ */
+export declare class WUError extends Error {
+    /** Error code (e.g., 'WU_NOT_FOUND') */
+    code: string;
+    /** Additional error context */
+    details: Record<string, unknown>;
+    /** Suggested commands or actions to try (optional) */
+    tryNext?: string[];
+    /** Alias for details for agent-friendly access */
+    context?: Record<string, unknown>;
+    /**
+     * Create a WU error
+     * @param {string} code - Error code (e.g., 'WU_NOT_FOUND')
+     * @param {string} message - Human-readable error message
+     * @param {object} [details={}] - Additional error context
+     */
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Exit process with error message (replaces die() function)
+ * Auto-detects script name from process.argv[1] - no string literals needed!
+ * @param {string} message - Error message to log
+ * @param {number} [exitCode=1] - Process exit code
+ * @example
+ * die('WU file not found');
+ * die('Gates failed', 2);
+ */
+export declare function die(message: any, exitCode?: number): void;
+/**
+ * Create a WUError instance (factory function)
+ * @param {string} code - Error code
+ * @param {string} message - Error message
+ * @param {object} [details={}] - Error details
+ * @returns {WUError} Structured error instance
+ * @example
+ * throw createError('WU_NOT_FOUND', 'WU-123 not found', { id: 'WU-123' });
+ */
+export declare function createError(code: any, message: any, details?: {}): WUError;
+/**
+ * Options for creating agent-friendly errors
+ */
+export interface AgentFriendlyErrorOptions {
+    /** Array of suggested commands or actions to try */
+    tryNext?: string[];
+    /** Additional context information */
+    context?: Record<string, unknown>;
+}
+/**
+ * Create an agent-friendly error with try-next command suggestions
+ * WU-1339: Agent-friendly error messages and hints (AX3)
+ *
+ * @param {string} code - Error code from ErrorCodes
+ * @param {string} message - Human-readable error message
+ * @param {AgentFriendlyErrorOptions} options - Options object
+ * @returns {WUError} Error instance with tryNext property and context
+ * @example
+ * throw createAgentFriendlyError(
+ *   ErrorCodes.WU_NOT_FOUND,
+ *   'WU-1234 not found',
+ *   {
+ *     tryNext: ['pnpm wu:create --id WU-1234 --lane "<lane>" --title "..."'],
+ *     context: { wuId: 'WU-1234' }
+ *   }
+ * );
+ */
+export declare function createAgentFriendlyError(code: any, message: any, options?: AgentFriendlyErrorOptions): WUError;
+/**
+ * Common error codes for WU operations
+ */
+export declare const ErrorCodes: {
+    WU_NOT_FOUND: string;
+    WU_ALREADY_CLAIMED: string;
+    WU_NOT_CLAIMED: string;
+    INVALID_WU_ID: string;
+    INVALID_LANE: string;
+    GATES_FAILED: string;
+    GIT_ERROR: string;
+    VALIDATION_ERROR: string;
+    FILE_NOT_FOUND: string;
+    YAML_PARSE_ERROR: string;
+    PARSE_ERROR: string;
+    WORKTREE_ERROR: string;
+    BRANCH_ERROR: string;
+    STATE_ERROR: string;
+    SECTION_NOT_FOUND: string;
+    INTERNAL_ERROR: string;
+    RECOVERY_ERROR: string;
+    TRANSACTION_ERROR: string;
+    LOCK_ERROR: string;
+    INIT_NOT_FOUND: string;
+    INIT_ALREADY_EXISTS: string;
+    INVALID_INIT_ID: string;
+    INVALID_SLUG: string;
+    INVALID_PHASE: string;
+    DEPENDENCY_CYCLE: string;
+};

package/dist/error-handler.js

@@ -0,0 +1,136 @@
+/**
+ * @file error-handler.mjs
+ * @description Structured error handling with error codes
+ * WU-1082: Extract shared utilities (eliminate die() duplication)
+ *
+ * Replaces die() function in:
+ * - tools/wu-claim.mjs
+ * - tools/wu-done.mjs
+ * - tools/wu-block.mjs
+ * - tools/wu-unblock.mjs
+ * - tools/wu-create.mjs
+ * - tools/wu-cleanup.mjs
+ * - tools/gates-pre-commit.mjs
+ * - tools/validate.mjs
+ * - tools/guard-worktree-commit.mjs
+ */
+/**
+ * Structured error class with error codes and details
+ * @class WUError
+ * @extends Error
+ */
+export class WUError extends Error {
+    /** Error code (e.g., 'WU_NOT_FOUND') */
+    code;
+    /** Additional error context */
+    details;
+    /** Suggested commands or actions to try (optional) */
+    tryNext;
+    /** Alias for details for agent-friendly access */
+    context;
+    /**
+     * Create a WU error
+     * @param {string} code - Error code (e.g., 'WU_NOT_FOUND')
+     * @param {string} message - Human-readable error message
+     * @param {object} [details={}] - Additional error context
+     */
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'WUError';
+        this.code = code;
+        this.details = details;
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, WUError);
+        }
+    }
+}
+/**
+ * Exit process with error message (replaces die() function)
+ * Auto-detects script name from process.argv[1] - no string literals needed!
+ * @param {string} message - Error message to log
+ * @param {number} [exitCode=1] - Process exit code
+ * @example
+ * die('WU file not found');
+ * die('Gates failed', 2);
+ */
+export function die(message, exitCode = 1) {
+    // Auto-detect script name from process.argv[1] (eliminates string literal duplication)
+    const scriptPath = process.argv[1] || 'unknown';
+    const scriptName = scriptPath.split('/').pop().replace('.js', '');
+    console.error(`[${scriptName}] ${message}`);
+    process.exit(exitCode);
+}
+/**
+ * Create a WUError instance (factory function)
+ * @param {string} code - Error code
+ * @param {string} message - Error message
+ * @param {object} [details={}] - Error details
+ * @returns {WUError} Structured error instance
+ * @example
+ * throw createError('WU_NOT_FOUND', 'WU-123 not found', { id: 'WU-123' });
+ */
+export function createError(code, message, details = {}) {
+    return new WUError(code, message, details);
+}
+/**
+ * Create an agent-friendly error with try-next command suggestions
+ * WU-1339: Agent-friendly error messages and hints (AX3)
+ *
+ * @param {string} code - Error code from ErrorCodes
+ * @param {string} message - Human-readable error message
+ * @param {AgentFriendlyErrorOptions} options - Options object
+ * @returns {WUError} Error instance with tryNext property and context
+ * @example
+ * throw createAgentFriendlyError(
+ *   ErrorCodes.WU_NOT_FOUND,
+ *   'WU-1234 not found',
+ *   {
+ *     tryNext: ['pnpm wu:create --id WU-1234 --lane "<lane>" --title "..."'],
+ *     context: { wuId: 'WU-1234' }
+ *   }
+ * );
+ */
+export function createAgentFriendlyError(code, message, options = {}) {
+    const { tryNext, context = {} } = options;
+    const error = createError(code, message, context);
+    // Add tryNext suggestions if provided
+    if (tryNext && Array.isArray(tryNext) && tryNext.length > 0) {
+        error.tryNext = tryNext;
+    }
+    // Expose details as context for agent-friendly access
+    // (WUError stores context in details property, but we expose it as context for clarity)
+    error.context = error.details;
+    return error;
+}
+/**
+ * Common error codes for WU operations
+ */
+export const ErrorCodes = {
+    WU_NOT_FOUND: 'WU_NOT_FOUND',
+    WU_ALREADY_CLAIMED: 'WU_ALREADY_CLAIMED',
+    WU_NOT_CLAIMED: 'WU_NOT_CLAIMED',
+    INVALID_WU_ID: 'INVALID_WU_ID',
+    INVALID_LANE: 'INVALID_LANE',
+    GATES_FAILED: 'GATES_FAILED',
+    GIT_ERROR: 'GIT_ERROR',
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+    YAML_PARSE_ERROR: 'YAML_PARSE_ERROR',
+    PARSE_ERROR: 'PARSE_ERROR',
+    WORKTREE_ERROR: 'WORKTREE_ERROR',
+    BRANCH_ERROR: 'BRANCH_ERROR',
+    STATE_ERROR: 'STATE_ERROR',
+    SECTION_NOT_FOUND: 'SECTION_NOT_FOUND',
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    RECOVERY_ERROR: 'RECOVERY_ERROR',
+    TRANSACTION_ERROR: 'TRANSACTION_ERROR', // WU-1369: Atomic transaction errors
+    LOCK_ERROR: 'LOCK_ERROR', // WU-1747: Merge lock errors
+    // Initiative system error codes (WU-1247)
+    INIT_NOT_FOUND: 'INIT_NOT_FOUND',
+    INIT_ALREADY_EXISTS: 'INIT_ALREADY_EXISTS',
+    INVALID_INIT_ID: 'INVALID_INIT_ID',
+    INVALID_SLUG: 'INVALID_SLUG',
+    INVALID_PHASE: 'INVALID_PHASE',
+    DEPENDENCY_CYCLE: 'DEPENDENCY_CYCLE',
+};

package/dist/file-classifiers.d.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * File Classifiers
+ *
+ * Shared utilities for classifying file types.
+ * Consolidates duplicated classification logic from wu-validator.mjs
+ * and code-path-validator.mjs.
+ *
+ * WU-1848: DRY Consolidation - Eliminate duplicated code patterns
+ *
+ * @see tools/lib/wu-validator.mjs - Original isTestFile, isMarkdownFile
+ * @see tools/lib/code-path-validator.mjs - Duplicated implementations
+ */
+/**
+ * Prefixes for paths that qualify as documentation-only.
+ * @constant {string[]}
+ */
+declare const DOCS_ONLY_PREFIXES: readonly string[];
+/**
+ * Root file patterns that qualify as docs-only.
+ * @constant {string[]}
+ */
+declare const DOCS_ONLY_ROOT_FILES: readonly string[];
+/**
+ * Test file patterns for detection
+ * @constant {RegExp[]}
+ */
+declare const TEST_FILE_PATTERNS: readonly RegExp[];
+/**
+ * Check if a file path is a test file
+ *
+ * Detects test files by extension and directory patterns:
+ * - *.test.ts, *.test.tsx, *.test.js, *.test.jsx, *.test.mjs
+ * - *.spec.ts, *.spec.tsx, *.spec.js, *.spec.jsx, *.spec.mjs
+ * - Files in __tests__ directories
+ * - *.test-utils.* files
+ * - *.mock.* files
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a test file
+ */
+export declare function isTestFile(filePath: any): boolean;
+/**
+ * Check if a file path is a markdown file
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a markdown file (.md extension)
+ */
+export declare function isMarkdownFile(filePath: any): boolean;
+/**
+ * Check if a file path is a documentation-only path
+ *
+ * Documentation paths include:
+ * - docs/, ai/, .claude/, memory-bank/ directories
+ * - README* files at root
+ * - CLAUDE*.md files at root
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is in a documentation path
+ */
+export declare function isDocumentationPath(filePath: any): boolean;
+export { DOCS_ONLY_PREFIXES, DOCS_ONLY_ROOT_FILES, TEST_FILE_PATTERNS };

package/dist/file-classifiers.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * File Classifiers
+ *
+ * Shared utilities for classifying file types.
+ * Consolidates duplicated classification logic from wu-validator.mjs
+ * and code-path-validator.mjs.
+ *
+ * WU-1848: DRY Consolidation - Eliminate duplicated code patterns
+ *
+ * @see tools/lib/wu-validator.mjs - Original isTestFile, isMarkdownFile
+ * @see tools/lib/code-path-validator.mjs - Duplicated implementations
+ */
+/**
+ * Prefixes for paths that qualify as documentation-only.
+ * @constant {string[]}
+ */
+const DOCS_ONLY_PREFIXES = Object.freeze(['docs/', 'ai/', '.claude/', 'memory-bank/']);
+/**
+ * Root file patterns that qualify as docs-only.
+ * @constant {string[]}
+ */
+const DOCS_ONLY_ROOT_FILES = Object.freeze(['readme', 'claude']);
+/**
+ * Test file patterns for detection
+ * @constant {RegExp[]}
+ */
+const TEST_FILE_PATTERNS = Object.freeze([
+    /\.test\.(ts|tsx|js|jsx|mjs)$/,
+    /\.spec\.(ts|tsx|js|jsx|mjs)$/,
+    /__tests__\//,
+    /\.test-utils\./,
+    /\.mock\./,
+]);
+/**
+ * Check if a file path is a test file
+ *
+ * Detects test files by extension and directory patterns:
+ * - *.test.ts, *.test.tsx, *.test.js, *.test.jsx, *.test.mjs
+ * - *.spec.ts, *.spec.tsx, *.spec.js, *.spec.jsx, *.spec.mjs
+ * - Files in __tests__ directories
+ * - *.test-utils.* files
+ * - *.mock.* files
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a test file
+ */
+export function isTestFile(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    // Normalise Windows paths to forward slashes
+    const normalized = filePath.replace(/\\/g, '/');
+    return TEST_FILE_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+/**
+ * Check if a file path is a markdown file
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a markdown file (.md extension)
+ */
+export function isMarkdownFile(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    // Normalise Windows paths to forward slashes
+    const normalized = filePath.replace(/\\/g, '/');
+    return /\.md$/i.test(normalized);
+}
+/**
+ * Check if a file path is a documentation-only path
+ *
+ * Documentation paths include:
+ * - docs/, ai/, .claude/, memory-bank/ directories
+ * - README* files at root
+ * - CLAUDE*.md files at root
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is in a documentation path
+ */
+export function isDocumentationPath(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    const path = filePath.trim();
+    if (path.length === 0) {
+        return false;
+    }
+    // Check docs-only prefixes (docs/, ai/, .claude/, memory-bank/)
+    for (const prefix of DOCS_ONLY_PREFIXES) {
+        if (path.startsWith(prefix)) {
+            return true;
+        }
+    }
+    // Check if it's a markdown file (*.md)
+    if (isMarkdownFile(path)) {
+        // Check root file patterns (README*, CLAUDE*.md)
+        const lowerPath = path.toLowerCase();
+        for (const pattern of DOCS_ONLY_ROOT_FILES) {
+            if (lowerPath.startsWith(pattern)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+// Export constants for external use
+export { DOCS_ONLY_PREFIXES, DOCS_ONLY_ROOT_FILES, TEST_FILE_PATTERNS };

package/dist/gates-agent-mode.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Options for agent mode detection
+ */
+interface GatesAgentModeOptions {
+    /** Command line arguments */
+    argv?: string[];
+    /** Environment variables */
+    env?: Record<string, string | undefined>;
+    /** stdout stream */
+    stdout?: {
+        isTTY?: boolean;
+    };
+}
+/**
+ * Options for log path functions
+ */
+interface GatesLogOptions {
+    /** Working directory */
+    cwd: string;
+    /** Environment variables */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Options for building gate log path
+ */
+interface BuildGatesLogPathOptions extends GatesLogOptions {
+    /** WU ID */
+    wuId?: string;
+    /** Lane name */
+    lane?: string;
+    /** Current timestamp */
+    now?: Date;
+}
+/**
+ * Options for updating symlink
+ */
+interface UpdateGatesLatestSymlinkOptions extends GatesLogOptions {
+    /** Path to the actual gate log file */
+    logPath: string;
+}
+/**
+ * Determine whether gates should run in low-noise "agent mode".
+ *
+ * Agent mode is intended for Claude Code sessions, where tool output is injected into the
+ * conversation context and can trigger "prompt too long".
+ *
+ * Detection strategy (WU-1827):
+ * 1. --verbose flag always forces full output (returns false)
+ * 2. CLAUDE_PROJECT_DIR env var is a strong hint (returns true if set)
+ * 3. TTY check: non-TTY + non-CI = likely agent mode (returns true)
+ * 4. Interactive TTY = human user (returns false)
+ *
+ * @param {GatesAgentModeOptions} options
+ * @returns {boolean} True if gates should run in agent mode
+ */
+export declare function shouldUseGatesAgentMode({ argv, env, stdout }?: GatesAgentModeOptions): boolean;
+export declare function getGatesLogDir({ cwd, env }: GatesLogOptions): string;
+export declare function buildGatesLogPath({ cwd, env, wuId, lane, now, }: BuildGatesLogPathOptions): string;
+/**
+ * Get the path to the gates-latest.log symlink (WU-2064)
+ *
+ * @param {Object} options
+ * @param {string} options.cwd - Working directory
+ * @param {Object} [options.env] - Environment variables
+ * @returns {string} Path to the symlink
+ */
+export declare function getGatesLatestSymlinkPath({ cwd, env }: GatesLogOptions): string;
+/**
+ * Create or update the gates-latest.log symlink to point to the most recent gate run (WU-2064)
+ *
+ * This provides a stable path for agents to access the most recent gate log
+ * without needing to know the timestamp-based filename.
+ *
+ * @param {Object} options
+ * @param {string} options.logPath - Path to the actual gate log file
+ * @param {string} options.cwd - Working directory
+ * @param {Object} [options.env] - Environment variables
+ * @returns {boolean} True if symlink was created/updated successfully
+ */
+export declare function updateGatesLatestSymlink({ logPath, cwd, env }: UpdateGatesLatestSymlinkOptions): boolean;
+export {};