@lumenflow/core 1.0.0

package/dist/wu-done-retry-helpers.js

@@ -0,0 +1,172 @@
+/**
+ * WU-1584: Retry and recovery helpers for wu:done
+ *
+ * Handles:
+ * - Squashing duplicate completion commits from retry attempts
+ * - Detecting and counting previous completion attempts
+ * - Preparing zombie recovery with squash
+ * - Handling parallel completions with auto-rebase
+ *
+ * @module wu-done-retry-helpers
+ */
+import { LOG_PREFIX, EMOJI, GIT, GIT_COMMANDS, GIT_FLAGS, GIT_REFS, STRING_LITERALS, } from './wu-constants.js';
+import { createError, ErrorCodes } from './error-handler.js';
+/**
+ * Regex to match wu:done completion commit messages
+ * Format: wu(<id>): done - <title>
+ *
+ * Note: Does not use ^ anchor to allow matching within git log --oneline output
+ * which includes commit hash prefix: "abc1234 wu(wu-500): done - title"
+ *
+ * @constant {RegExp}
+ */
+const COMPLETION_COMMIT_PATTERN = /wu\(([^)]+)\):\s*done\s*-/i;
+/**
+ * Count previous completion attempt commits for a WU on the current branch
+ *
+ * WU-1584 Fix #1: Detect duplicate commits from retries
+ *
+ * Searches commit history for commits matching the completion pattern
+ * for the specified WU ID.
+ *
+ * @param {string} wuId - WU ID (e.g., 'WU-1584')
+ * @param {object} gitAdapter - Git adapter instance
+ * @returns {Promise<number>} Number of completion attempt commits found
+ */
+export async function countPreviousCompletionAttempts(wuId, gitAdapter) {
+    const normalizedId = wuId.toLowerCase();
+    try {
+        // Get recent commit history (limit to reasonable amount)
+        const log = await gitAdapter.log({ maxCount: GIT.LOG_MAX_COUNT });
+        if (!log || !log.all) {
+            return 0;
+        }
+        // Count trailing completion attempts on the branch tip only.
+        // This avoids accidentally squashing unrelated commits if the history contains
+        // older completion commits that are not part of the current retry chain.
+        let trailingCount = 0;
+        for (const commit of log.all) {
+            const match = commit.message.match(COMPLETION_COMMIT_PATTERN);
+            if (!match)
+                break;
+            const commitWuId = match[1].toLowerCase();
+            if (commitWuId !== normalizedId)
+                break;
+            trailingCount += 1;
+        }
+        return trailingCount;
+    }
+    catch (error) {
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not count previous attempts: ${error.message}`);
+        return 0;
+    }
+}
+export async function squashPreviousCompletionAttempts(wuId, count, gitAdapter, options = {}) {
+    const { preserveIndex = true } = options;
+    if (count === 0) {
+        return { squashed: false, count: 0 };
+    }
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Detected ${count} previous completion attempt commit(s)`);
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Squashing previous attempts to avoid duplicate commits...`);
+    try {
+        // In the normal retry flow we need to preserve the staged metadata transaction,
+        // so we use --soft (index/working tree unchanged).
+        //
+        // In zombie recovery we want to drop prior completion commits cleanly and start
+        // from a known-good state, so we use --hard (index/working tree reset).
+        if (!preserveIndex) {
+            const status = (await gitAdapter.getStatus())?.trim?.() ?? '';
+            if (status) {
+                throw createError(ErrorCodes.RECOVERY_ERROR, `Cannot squash previous attempts: worktree has uncommitted changes.${STRING_LITERALS.NEWLINE}${STRING_LITERALS.NEWLINE}` +
+                    `Fix: In your worktree, run:${STRING_LITERALS.NEWLINE}` +
+                    `  ${GIT_COMMANDS.GIT} status${STRING_LITERALS.NEWLINE}` +
+                    `  ${GIT_COMMANDS.GIT} restore -SW .${STRING_LITERALS.NEWLINE}` +
+                    `Then retry wu:done.${STRING_LITERALS.NEWLINE}`, { wuId, count, preserveIndex, status });
+            }
+        }
+        const resetMode = preserveIndex ? GIT_FLAGS.SOFT : GIT_FLAGS.HARD;
+        const headBackRef = `${GIT_REFS.HEAD}~${count}`;
+        await gitAdapter.raw([GIT_COMMANDS.RESET, resetMode, headBackRef]);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Squashed ${count} previous attempt(s) - will create single completion commit`);
+        return { squashed: true, count };
+    }
+    catch (error) {
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not squash previous attempts: ${error.message}`);
+        return { squashed: false, count: 0 };
+    }
+}
+/**
+ * Prepare zombie recovery with squash of previous attempts
+ *
+ * WU-1584 Fix #2: Recovery loop should squash previous attempt commits
+ *
+ * When recovering from zombie state (status=done but worktree exists),
+ * first squash any previous completion attempts to avoid "rebase hell".
+ *
+ * @param {string} wuId - WU ID
+ * @param {object} gitAdapter - Git adapter instance
+ * @returns {Promise<{ squashedCount: number }>} Result
+ */
+export async function prepareRecoveryWithSquash(wuId, gitAdapter) {
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Checking for previous completion attempts before recovery...`);
+    const previousCount = await countPreviousCompletionAttempts(wuId, gitAdapter);
+    if (previousCount > 0) {
+        console.log(`${LOG_PREFIX.DONE} Squashing ${previousCount} previous completion attempt(s) for clean recovery`);
+        // Recovery: do not preserve index; reset to a clean state before continuing.
+        const result = await squashPreviousCompletionAttempts(wuId, previousCount, gitAdapter, {
+            preserveIndex: false,
+        });
+        return { squashedCount: result.squashed ? result.count : 0 };
+    }
+    return { squashedCount: 0 };
+}
+export async function handleParallelCompletions(wuId, doc, gitAdapter, options = {}) {
+    const { worktreePath, autoRebase = true } = options;
+    // Fetch latest from origin
+    await gitAdapter.fetch();
+    // Get current origin/main SHA
+    const currentMainSha = await gitAdapter.getCommitHash('origin/main');
+    // Get baseline SHA from when WU was claimed
+    const baselineSha = doc.baseline_main_sha;
+    if (!baselineSha || currentMainSha === baselineSha) {
+        // No parallel completions - main hasn't changed since claim
+        return { parallelDetected: false, rebaseTriggered: false };
+    }
+    // Check if changes since baseline include other WU completions
+    const newCommits = await gitAdapter.raw([
+        'log',
+        '--oneline',
+        `${baselineSha}..origin/main`,
+        '--',
+    ]);
+    const hasParallelCompletions = newCommits && newCommits.trim() && COMPLETION_COMMIT_PATTERN.test(newCommits);
+    if (!hasParallelCompletions) {
+        // Changes exist but are not WU completions - proceed normally
+        return { parallelDetected: false, rebaseTriggered: false };
+    }
+    // Parallel completions detected
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Parallel completion(s) detected on main since WU claim`);
+    if (!autoRebase) {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `Parallel completions detected on main since ${wuId} was claimed.\n` +
+            `This would cause merge conflicts during wu:done.\n\n` +
+            `Fix: Run 'git fetch origin && git rebase origin/main' in your worktree,\n` +
+            `then retry wu:done.\n\n` +
+            `Or use --no-auto-rebase to disable this check (not recommended).`, { wuId, baselineSha, currentMainSha });
+    }
+    // Trigger auto-rebase
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Triggering auto-rebase to incorporate parallel completions...`);
+    try {
+        // Rebase the current branch onto origin/main
+        await gitAdapter.rebase('origin/main');
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Auto-rebase complete - parallel completions incorporated`);
+        return { parallelDetected: true, rebaseTriggered: true };
+    }
+    catch (error) {
+        throw createError(ErrorCodes.GIT_ERROR, `Auto-rebase failed: ${error.message}\n\n` +
+            `Manual resolution required:\n` +
+            `1. cd ${worktreePath || 'your-worktree'}\n` +
+            `2. git fetch origin && git rebase origin/main\n` +
+            `3. Resolve conflicts if any\n` +
+            `4. Retry wu:done`, { wuId, originalError: error.message });
+    }
+}

package/dist/wu-done-ui.d.ts

@@ -0,0 +1,37 @@
+/**
+ * WU Done UI Helpers
+ *
+ * WU-1281: Extracted display helpers to consolidate DRY violations
+ * and use library-first duration formatting.
+ *
+ * @see {@link tools/wu-done.mjs} - Primary consumer
+ * @see {@link tools/lib/wu-constants.mjs} - UI constants
+ */
+/**
+ * Print prominent gate failure box
+ *
+ * Consolidated from two duplicate implementations in wu-done.mjs
+ * (worktree mode and branch-only mode). Uses pretty-ms for
+ * human-readable duration formatting.
+ *
+ * @param {object} options - Failure info
+ * @param {string} options.id - WU ID (e.g., 'WU-123')
+ * @param {string} options.location - Location description (worktree path or 'Branch-Only')
+ * @param {number} options.durationMs - Duration in milliseconds
+ * @param {boolean} [options.isWorktreeMode=true] - True for worktree mode, false for branch-only
+ */
+export declare function printGateFailureBox({ id, location, durationMs, isWorktreeMode }: {
+    id: any;
+    location: any;
+    durationMs: any;
+    isWorktreeMode?: boolean;
+}): void;
+/**
+ * Print git status preview with truncation
+ *
+ * Shows first N lines of git status output with indication
+ * of how many more files exist. Parses output once (not three times).
+ *
+ * @param {string} statusOutput - Raw git status --porcelain output
+ */
+export declare function printStatusPreview(statusOutput: any): void;

package/dist/wu-done-ui.js

@@ -0,0 +1,69 @@
+/**
+ * WU Done UI Helpers
+ *
+ * WU-1281: Extracted display helpers to consolidate DRY violations
+ * and use library-first duration formatting.
+ *
+ * @see {@link tools/wu-done.mjs} - Primary consumer
+ * @see {@link tools/lib/wu-constants.mjs} - UI constants
+ */
+import prettyMs from 'pretty-ms';
+import { UI, LOG_PREFIX, STRING_LITERALS } from './wu-constants.js';
+/**
+ * Print prominent gate failure box
+ *
+ * Consolidated from two duplicate implementations in wu-done.mjs
+ * (worktree mode and branch-only mode). Uses pretty-ms for
+ * human-readable duration formatting.
+ *
+ * @param {object} options - Failure info
+ * @param {string} options.id - WU ID (e.g., 'WU-123')
+ * @param {string} options.location - Location description (worktree path or 'Branch-Only')
+ * @param {number} options.durationMs - Duration in milliseconds
+ * @param {boolean} [options.isWorktreeMode=true] - True for worktree mode, false for branch-only
+ */
+export function printGateFailureBox({ id, location, durationMs, isWorktreeMode = true }) {
+    const width = UI.ERROR_BOX_WIDTH;
+    const duration = prettyMs(durationMs, { secondsDecimalDigits: 0 });
+    console.error(`\n${'═'.repeat(width)}`);
+    console.error('❌ WU:DONE FAILED - GATES DID NOT PASS');
+    console.error('═'.repeat(width));
+    console.error(`WU ID:     ${id}`);
+    console.error(`${isWorktreeMode ? 'Worktree' : 'Mode'}:  ${isWorktreeMode ? location : 'Branch-Only'}`);
+    console.error(`Duration:  ${duration}`);
+    console.error('─'.repeat(width));
+    console.error('Next steps:');
+    if (isWorktreeMode) {
+        console.error(`  1. cd ${location}`);
+        console.error('  2. Review gate output above to identify failures');
+        console.error('  3. Fix issues in the worktree');
+        console.error('  4. Run: pnpm gates');
+        console.error(`  5. cd back to main and re-run: pnpm wu:done --id ${id}`);
+    }
+    else {
+        console.error('  1. Review gate output above to identify failures');
+        console.error('  2. Fix issues on the lane branch');
+        console.error('  3. Run: pnpm gates');
+        console.error(`  4. Re-run: pnpm wu:done --id ${id}`);
+    }
+    console.error(`${'═'.repeat(width)}\n`);
+}
+/**
+ * Print git status preview with truncation
+ *
+ * Shows first N lines of git status output with indication
+ * of how many more files exist. Parses output once (not three times).
+ *
+ * @param {string} statusOutput - Raw git status --porcelain output
+ */
+export function printStatusPreview(statusOutput) {
+    const lines = statusOutput.split(STRING_LITERALS.NEWLINE).filter((line) => line.trim());
+    const previewLimit = UI.STATUS_PREVIEW_LINES;
+    const preview = lines.slice(0, previewLimit);
+    console.warn(`${LOG_PREFIX.DONE} ⚠️  Working tree still has changes after rollback:`);
+    console.warn(preview.join(STRING_LITERALS.NEWLINE));
+    if (lines.length > previewLimit) {
+        console.warn(`  ... and ${lines.length - previewLimit} more files`);
+    }
+    console.warn(`${LOG_PREFIX.DONE} Run "git status" for full details`);
+}

package/dist/wu-done-validators.d.ts

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+/**
+ * Validation functions for wu:done workflow
+ * Extracted from wu-done.mjs (WU-1215 refactoring)
+ */
+import { execSync as execSyncImport } from 'node:child_process';
+import { validateAutomatedTestRequirement } from './manual-test-validator.js';
+import { validatePreflight } from './wu-preflight-validators.js';
+/**
+ * Validates command-line inputs and WU ID format
+ * @param {string[]} argv - Process arguments
+ * @returns {{ args: object, id: string }} Parsed args and validated WU ID
+ */
+export declare function validateInputs(argv: any): {
+    args: import("commander").OptionValues;
+    id: any;
+};
+/**
+ * Read WU YAML preferring worktree version over main version
+ *
+ * WU-1584 Fix #4: Added diagnostic logging to confirm which YAML file is being
+ * read for code_paths validation. This helps debug issues where worktree YAML
+ * differs from main checkout YAML.
+ *
+ * @param {string} id - WU ID
+ * @param {string|null} worktreePath - Worktree path (null if branch-only mode)
+ * @param {string} mainWUPath - Path to WU YAML in main checkout
+ * @returns {object} Parsed WU document
+ */
+export declare function readWUPreferWorktree(id: any, worktreePath: any, mainWUPath: any): any;
+/**
+ * Detect if currently running inside a worktree
+ * Checks for .git file (not directory) which indicates a worktree
+ * @returns {string|null} Current directory path if inside worktree, null otherwise
+ */
+export declare function detectCurrentWorktree(): string;
+/**
+ * Resolve worktree path from WU YAML
+ * Originally implemented in WU-1226, extracted to validators module in WU-1215
+ * Priority:
+ * 1. Read worktree_path field (set at claim time, immune to lane field changes)
+ * 2. Fall back to calculating from lane field (for old WUs without worktree_path)
+ * 3. Use git worktree list to find actual path (defensive fallback)
+ * @param {object} doc - WU YAML document
+ * @returns {Promise<string|null>} - Worktree path or null if not found
+ */
+export declare function defaultWorktreeFrom(doc: any): Promise<any>;
+/**
+ * Detect workspace mode from WU YAML
+ * @param {object} doc - WU YAML document
+ * @returns {'worktree' | 'branch-only'}
+ */
+export declare function detectWorkspaceMode(doc: any): string;
+/**
+ * Calculate lane branch name from WU YAML
+ * @param {object} doc - WU YAML document
+ * @returns {string|null} Lane branch name (e.g., lane/operations-tooling/wu-1215)
+ */
+export declare function defaultBranchFrom(doc: any): string;
+/**
+ * Check if a branch exists
+ * @param {string} branch - Branch name to check
+ * @returns {Promise<boolean>} True if branch exists
+ */
+export declare function branchExists(branch: any): Promise<boolean>;
+/**
+ * Detect workspace mode and calculate all relevant paths
+ * @param {string} id - WU ID
+ * @param {object} args - Parsed command-line arguments
+ * @returns {Promise<object>} Object containing paths, mode info, and WU document
+ */
+export declare function detectModeAndPaths(id: any, args: any): Promise<{
+    WU_PATH: string;
+    STATUS_PATH: string;
+    BACKLOG_PATH: string;
+    STAMPS_DIR: string;
+    docMain: any;
+    workspaceMode: string;
+    isBranchOnly: boolean;
+    derivedWorktree: any;
+    docForValidation: any;
+    isDocsOnly: boolean;
+}>;
+/**
+ * Generate commit message for WU completion
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * @param {string} id - WU ID (e.g., "WU-1215")
+ * @param {string} title - WU title
+ * @param {number} maxLength - Maximum commit header length from commitlint config
+ * @returns {string} Formatted commit message
+ * @throws {Error} If generated message exceeds maxLength
+ */
+export declare function generateCommitMessage(id: any, title: any, maxLength?: number): string;
+/**
+ * Validate that required metadata files exist before updating
+ * WU-1275: Fail fast before mutations to prevent partial state
+ *
+ * @param {object} params - Parameters object
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @throws {WUError} If any required file is missing
+ */
+export declare function validateMetadataFilesExist({ statusPath, backlogPath }: {
+    statusPath: any;
+    backlogPath: any;
+}): void;
+/**
+ * Update all metadata files for WU completion
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * WU-1572: Made async for WUStateStore integration
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID
+ * @param {string} params.title - WU title
+ * @param {object} params.doc - WU YAML document to update
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ */
+export declare function updateMetadataFiles({ id, title, doc, wuPath, statusPath, backlogPath }: {
+    id: any;
+    title: any;
+    doc: any;
+    wuPath: any;
+    statusPath: any;
+    backlogPath: any;
+}): Promise<void>;
+/**
+ * Collect metadata updates to a transaction (WU-1369: Atomic pattern)
+ *
+ * This is the atomic version of updateMetadataFiles.
+ * Instead of writing files immediately, it collects all changes
+ * into a WUTransaction object for atomic commit.
+ *
+ * Usage:
+ * ```js
+ * const tx = new WUTransaction(id);
+ * collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction: tx });
+ * // All changes are now in tx.pendingWrites
+ * // Validate, then commit or abort
+ * tx.commit();
+ * ```
+ *
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID
+ * @param {string} params.title - WU title
+ * @param {object} params.doc - WU YAML document to update (will be mutated)
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @param {string} params.stampPath - Path to stamp file
+ * @param {WUTransaction} params.transaction - Transaction to add writes to
+ */
+export declare function collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction, }: {
+    id: any;
+    title: any;
+    doc: any;
+    wuPath: any;
+    statusPath: any;
+    backlogPath: any;
+    stampPath: any;
+    transaction: any;
+}): Promise<void>;
+/**
+ * Stage and format metadata files
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID (for error reporting)
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @param {string} params.stampsDir - Path to stamps directory
+ * @throws {Error} If formatting fails
+ */
+export declare function stageAndFormatMetadata({ id, wuPath, statusPath, backlogPath, stampsDir }: {
+    id: any;
+    wuPath: any;
+    statusPath: any;
+    backlogPath: any;
+    stampsDir: any;
+}): Promise<void>;
+/**
+ * Run cleanup operations after successful merge
+ * Removes worktree and optionally deletes lane branch
+ * Extracted from wu-done.mjs (WU-1215 Phase 1 Extraction #3)
+ *
+ * WU-2241: Now wrapped with cleanup lock to prevent concurrent collision
+ *          when multiple wu:done commands complete simultaneously.
+ *
+ * @param {object} docMain - WU YAML document
+ * @param {object} args - Parsed CLI arguments
+ */
+export declare function runCleanup(docMain: any, args: any): Promise<void>;
+/**
+ * WU-1351: Validate code_paths files exist on main branch
+ *
+ * Prevents false completions by ensuring all code_paths entries
+ * actually exist on the target branch (main or lane branch).
+ *
+ * This guards against:
+ * - Stamps being created for WUs where code never merged
+ * - Metadata becoming desynchronized from actual code
+ *
+ * @param {object} doc - WU YAML document
+ * @param {string} id - WU ID
+ * @param {ValidateCodePathsExistOptions} options - Options
+ * @returns {Promise<{ valid: boolean, errors: string[], missing: string[] }>} Validation result
+ */
+export interface ValidateCodePathsExistOptions {
+    /** Branch to check files against (default: 'main') */
+    targetBranch?: string;
+    /** Worktree path for worktree mode */
+    worktreePath?: string | null;
+}
+export declare function validateCodePathsExist(doc: any, id: any, options?: ValidateCodePathsExistOptions): Promise<{
+    valid: boolean;
+    errors: any[];
+    missing: any[];
+}>;
+/**
+ * Validate WU spec completeness (WU-1162, WU-1280)
+ *
+ * Ensures WU specifications are complete before allowing wu:done to proceed.
+ * Prevents placeholder WUs from being marked as done.
+ *
+ * WU-1280: Added tests array validation to catch empty tests.manual early
+ * (previously only validated in pre-commit hook, causing late failures).
+ *
+ * @param {object} doc - WU YAML document
+ * @param {string} id - WU ID
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+export declare function validateSpecCompleteness(doc: any, _id: any): {
+    valid: boolean;
+    errors: any[];
+};
+export { validateAutomatedTestRequirement };
+/**
+ * WU-1617: Post-mutation validation for wu:done
+ *
+ * Validates that metadata files written by tx.commit() are valid:
+ * 1. WU YAML has completed_at field with valid ISO datetime
+ * 2. WU YAML has locked: true
+ * 3. Stamp file exists
+ *
+ * This catches schema violations that could persist silently after
+ * transaction commit.
+ *
+ * @param {object} params - Validation parameters
+ * @param {string} params.id - WU ID
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.stampPath - Path to stamp file
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+export declare function validatePostMutation({ id, wuPath, stampPath }: {
+    id: any;
+    wuPath: any;
+    stampPath: any;
+}): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * WU-1781: Build preflight error message with actionable guidance
+ *
+ * Creates a formatted error message for preflight validation failures,
+ * including specific guidance for stamp-status mismatch errors.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {string[]} errors - List of validation errors
+ * @returns {string} Formatted error message with fix options
+ */
+export declare function buildPreflightErrorMessage(id: any, errors: any): string;
+/**
+ * WU-1805: Execute preflight code_paths and test_paths validation
+ *
+ * Validates that all code_paths and test file paths specified in the WU YAML
+ * actually exist before running gates. This catches YAML mismatches early,
+ * saving time compared to discovering issues after a full gate run.
+ *
+ * This is run as the FIRST validation step in wu:done, before gates.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {object} paths - Path options
+ * @param {string} paths.rootDir - Root directory for YAML lookup
+ * @param {string} paths.worktreePath - Worktree path for file existence checks
+ * @param {ExecutePreflightCodePathValidationOptions} options - Options for testing
+ * @returns {Promise<{ valid: boolean, errors: string[], missingCodePaths: string[], missingTestPaths: string[], abortedBeforeGates: boolean }>}
+ */
+interface ExecutePreflightCodePathValidationOptions {
+    /** Override validatePreflight for testing */
+    validatePreflightFn?: typeof validatePreflight;
+}
+export declare function executePreflightCodePathValidation(id: any, paths: any, options?: ExecutePreflightCodePathValidationOptions): Promise<{
+    valid: boolean;
+    errors: any[];
+    missingCodePaths: any[];
+    missingTestPaths: any[];
+    abortedBeforeGates: boolean;
+}>;
+/**
+ * WU-1805: Build preflight code_paths error message with actionable guidance
+ *
+ * Creates a formatted error message for preflight code_paths validation failures,
+ * including specific guidance for fixing missing files.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {object} result - Preflight validation result
+ * @param {string[]} result.errors - List of validation errors
+ * @param {string[]} result.missingCodePaths - Missing code_paths files
+ * @param {string[]} result.missingTestPaths - Missing test files
+ * @returns {string} Formatted error message with fix options
+ */
+export declare function buildPreflightCodePathErrorMessage(id: any, result: any): string;
+/**
+ * WU-1781: Run tasks:validate as preflight check before any git operations
+ *
+ * This prevents deadlocks where wu:done completes merge but then pre-push
+ * fails on tasks:validate, leaving local main ahead of origin.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {ExecSyncOverrideOptions} options - Options for testing
+ * @returns {{ valid: boolean, errors: string[], abortedBeforeMerge: boolean, localMainModified: boolean, hasStampStatusError: boolean }}
+ */
+interface ExecSyncOverrideOptions {
+    /** Override execSync for testing (default: child_process.execSync) */
+    execSyncFn?: typeof execSyncImport;
+}
+export declare function runPreflightTasksValidation(id: any, options?: ExecSyncOverrideOptions): {
+    valid: boolean;
+    errors: any;
+    abortedBeforeMerge: boolean;
+    localMainModified: boolean;
+    hasStampStatusError: any;
+};
+/**
+ * WU-2308: Validate all pre-commit hooks with worktree context
+ *
+ * Runs pre-commit validation gates from the worktree directory when provided.
+ * This ensures that dependency audits check the worktree's dependencies
+ * (with any fixes) rather than main's potentially stale dependencies.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {string|null} worktreePath - Path to worktree (null = run from current dir)
+ * @param {ExecSyncOverrideOptions} options - Options for testing
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export declare function validateAllPreCommitHooks(id: any, worktreePath?: any, options?: ExecSyncOverrideOptions): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * WU-2242: Validate that test_paths is required for non-doc WUs
+ *
+ * Enforces that WUs with code changes (non-documentation types with code_paths
+ * that contain actual code) have at least one test path specified.
+ *
+ * Returns valid: true in the following cases:
+ * - WU type is 'documentation' or 'process'
+ * - code_paths is empty or only contains documentation paths
+ * - tests object has at least one test (unit, e2e, manual, or integration)
+ *
+ * @param {object} wu - WU document
+ * @param {string} wu.id - WU ID
+ * @param {string} wu.type - WU type (feature, bug, documentation, etc.)
+ * @param {object} wu.tests - Tests object with unit, e2e, manual, integration arrays
+ * @param {string[]} wu.code_paths - Array of code paths
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export declare function validateTestPathsRequired(wu: any): {
+    valid: boolean;
+    error?: undefined;
+} | {
+    valid: boolean;
+    error: string;
+};
+/**
+ * WU-2310: Validate type vs code_paths at preflight (before transaction starts).
+ *
+ * This catches the documentation WU + code file mismatch BEFORE any transaction
+ * begins, preventing the scenario where:
+ * 1. Transaction commits files (stamp, status, backlog)
+ * 2. Git commit fails due to pre-commit hook (gateDocsOnlyPathEnforcement)
+ * 3. Files are left in inconsistent state
+ *
+ * By running this validation at preflight, we fail fast with a clear error
+ * message before any file mutations occur.
+ *
+ * @param {object} wu - WU document
+ * @param {string} wu.id - WU ID
+ * @param {string} wu.type - WU type (documentation, feature, bug, etc.)
+ * @param {string[]} [wu.code_paths] - Array of code paths
+ * @returns {{ valid: boolean, errors: string[], blockedPaths: string[], abortedBeforeTransaction: boolean }}
+ */
+export declare function validateTypeVsCodePathsPreflight(wu: any): {
+    valid: boolean;
+    errors: any[];
+    blockedPaths: any[];
+    abortedBeforeTransaction: boolean;
+};
+/**
+ * WU-2310: Build error message for type vs code_paths preflight failure.
+ *
+ * Provides actionable guidance for fixing the mismatch:
+ * 1. Change WU type to 'engineering' or appropriate type
+ * 2. Update code_paths to only include documentation files
+ *
+ * @param {string} id - WU ID
+ * @param {string[]} blockedPaths - Paths that would be blocked
+ * @returns {string} Formatted error message
+ */
+export declare function buildTypeVsCodePathsErrorMessage(id: any, blockedPaths: any): string;