@lumenflow/core 1.0.0 → 1.3.0

package/dist/wu-done-validators.js

@@ -1,1229 +1,13 @@
 #!/usr/bin/env node
 /**
- * Validation functions for wu:done workflow
- * Extracted from wu-done.mjs (WU-1215 refactoring)
- */
-/* eslint-disable security/detect-non-literal-fs-filename, security/detect-object-injection */
-import { parseWUArgs } from './arg-parser.js';
-import { die, createError, ErrorCodes } from './error-handler.js';
-import { WU_PATHS } from './wu-paths.js';
-import { EXIT_CODES } from './wu-constants.js';
-// WU-1352: Use centralized YAML functions from wu-yaml.mjs
-import { readWU, writeWU, parseYAML } from './wu-yaml.js';
-import { getGitForCwd } from './git-adapter.js';
-import path from 'node:path';
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { access } from 'node:fs/promises';
-import { exec as execCallback, execSync as execSyncImport } from 'node:child_process';
-import { promisify } from 'node:util';
-import { updateStatusRemoveInProgress, addToStatusCompleted } from './wu-status-updater.js';
-import { moveWUToDoneBacklog } from './wu-backlog-updater.js';
-import { createStamp } from './stamp-utils.js';
-import { WU_EVENTS_FILE_NAME } from './wu-state-store.js';
-import { computeWUYAMLContent, computeStatusContent, computeBacklogContent, computeWUEventsContentAfterComplete, computeStampContent, } from './wu-transaction-collectors.js';
-const execAsync = promisify(execCallback);
-import { PATTERNS, REMOTES, toKebab, VALIDATION, WU_TYPES, TEST_TYPES, DEFAULTS, LOG_PREFIX, EMOJI, CLAIMED_MODES, PKG_MANAGER, SCRIPTS, PRETTIER_FLAGS, GIT_COMMANDS, BRANCHES, STRING_LITERALS, BEACON_PATHS, STDIO, } from './wu-constants.js';
-import { PLACEHOLDER_SENTINEL } from './wu-schema.js';
-// WU-1433: Manual test escape hatch validator
-import { validateAutomatedTestRequirement } from './manual-test-validator.js';
-// WU-1440: Import merged check for branch deletion
-import { isBranchAlreadyMerged } from './wu-done-worktree.js';
-// WU-2241: Import cleanup lock for concurrent collision prevention
-import { withCleanupLock } from './cleanup-lock.js';
-// WU-1805: Import preflight validators for code_paths validation
-import { validatePreflight } from './wu-preflight-validators.js';
-// WU-2242: Import isDocumentationPath for test_paths enforcement
-import { isDocumentationPath } from './file-classifiers.js';
-// WU-2278: Import ownership validation for cross-agent protection
-import { validateWorktreeOwnership } from './worktree-ownership.js';
-// WU-2278: Import cleanup install config for timeout and CI mode
-import { getCleanupInstallConfig, CLEANUP_INSTALL_TIMEOUT_MS } from './cleanup-install-config.js';
-/**
- * Prefixes for paths that qualify as "docs-only" (no code changes).
- * Unlike SKIP_TESTS_PREFIXES, this excludes tools/ and scripts/ because
- * those contain code files that require full gate validation.
- *
- * WU-1539: Split from shouldSkipWebTests to fix docs-only misclassification.
- * @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']);
-/**
- * WU-1234 + WU-1255 + WU-1539: Detect docs-only WU from code_paths
- * Returns true if all code_paths are documentation paths only.
- *
- * Docs-only paths: docs/, ai/, .claude/, memory-bank/, README*, CLAUDE*.md
- * NOT docs-only: tools/, scripts/ (these are code, not documentation)
- *
- * WU-1539: Fixed misclassification where tools/ was treated as docs-only
- * but then rejected by validateDocsOnly(). tools/ should skip web tests
- * but NOT be classified as docs-only.
- *
- * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
- * @returns {boolean} True if WU is docs-only (all paths are documentation)
- */
-function detectDocsOnlyByPaths(codePaths) {
-    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
-        return false;
-    }
-    return codePaths.every((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 (path.endsWith('.md')) {
-            return true;
-        }
-        // 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;
-    });
-}
-/**
- * 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 function validateInputs(argv) {
-    const args = parseWUArgs(argv);
-    if (args.help || !args.id) {
-        console.log('Usage: pnpm wu:done --id WU-334 [OPTIONS]\n\n' +
-            'Options:\n' +
-            '  --worktree <path>   Override worktree path (default: worktrees/<lane>-<wu-id>)\n' +
-            '  --no-auto           Skip auto-updating YAML/backlog/status (you staged manually)\n' +
-            '  --no-remove         Skip worktree removal\n' +
-            '  --no-merge          Skip auto-merging lane branch to main\n' +
-            '  --delete-branch     Delete lane branch after merge (both local and remote)\n' +
-            '  --create-pr         Create PR instead of auto-merge (requires gh CLI)\n' +
-            '  --pr-draft          Create PR as draft (use with --create-pr)\n' +
-            '  --skip-gates        Skip gates check (USE WITH EXTREME CAUTION)\n' +
-            '  --reason "<text>"   Required with --skip-gates or --override-owner\n' +
-            '  --fix-wu WU-{id}    Required with --skip-gates: WU ID that will fix the failures\n' +
-            '  --allow-todo        Allow TODO comments in code (requires justification in WU notes)\n' +
-            '  --override-owner    Override ownership check (requires --reason, audited)\n' +
-            '  --no-auto-rebase    Disable auto-rebase on branch divergence (WU-1303)\n' +
-            '  --require-agents    Block completion if mandatory agents not invoked (WU-1542)\n' +
-            '  --help, -h          Show this help\n\n' +
-            '⚠️  SKIP-GATES WARNING:\n' +
-            '  Only use --skip-gates when:\n' +
-            '    • Test failures are confirmed pre-existing (not introduced by your WU)\n' +
-            '    • A separate WU exists to fix those failures (specify with --fix-wu)\n' +
-            '    • Your WU work is genuinely complete\n\n' +
-            '  NEVER use --skip-gates for failures introduced by your WU!\n' +
-            '  All skip-gates events are logged to .beacon/skip-gates-audit.log\n\n' +
-            '📝 WU VALIDATOR:\n' +
-            '  Automatically scans code_paths for:\n' +
-            '    • TODO/FIXME/HACK/XXX comments (fails validation unless --allow-todo)\n' +
-            '    • Mock/Stub/Fake classes in production code (warning only)\n' +
-            '  Use --allow-todo only for legitimate cases with justification in WU notes.\n');
-        process.exit(args.help ? EXIT_CODES.SUCCESS : EXIT_CODES.ERROR);
-    }
-    const id = args.id.toUpperCase();
-    if (!PATTERNS.WU_ID.test(id))
-        die(`Invalid WU id '${args.id}'. Expected format WU-123`);
-    return { args, id };
-}
-/**
- * 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 function readWUPreferWorktree(id, worktreePath, mainWUPath) {
-    if (worktreePath) {
-        const wtWUPath = path.join(worktreePath, WU_PATHS.WU(id));
-        if (existsSync(wtWUPath)) {
-            try {
-                const text = readFileSync(wtWUPath, { encoding: 'utf-8' });
-                const doc = parseYAML(text);
-                if (doc && doc.id === id) {
-                    // WU-1584: Log source file for validation debugging
-                    console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Reading WU YAML from worktree: ${wtWUPath}`);
-                    if (doc.code_paths && doc.code_paths.length > 0) {
-                        console.log(`${LOG_PREFIX.DONE}   code_paths source: worktree (${doc.code_paths.length} path(s))`);
-                    }
-                    return doc;
-                }
-                // If ID mismatch, log warning but continue
-                console.warn(`${LOG_PREFIX.DONE} Warning: Worktree YAML ID mismatch (expected ${id}, got ${doc?.id})`);
-            }
-            catch (err) {
-                // Log parse errors for debugging
-                console.warn(`${LOG_PREFIX.DONE} Warning: Failed to read worktree YAML: ${err.message}`);
-            }
-        }
-        else {
-            // Log missing worktree YAML for debugging
-            console.warn(`${LOG_PREFIX.DONE} Warning: Worktree YAML not found at ${wtWUPath}`);
-        }
-    }
-    // WU-1584: Log when falling back to main checkout YAML
-    console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Reading WU YAML from main: ${mainWUPath}`);
-    const doc = readWU(mainWUPath, id);
-    if (doc.code_paths && doc.code_paths.length > 0) {
-        console.log(`${LOG_PREFIX.DONE}   code_paths source: main checkout (${doc.code_paths.length} path(s))`);
-    }
-    return doc;
-}
-/**
- * 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 function detectCurrentWorktree() {
-    const cwd = process.cwd();
-    const gitPath = path.join(cwd, '.git');
-    // Check if .git exists and is a file (worktrees have .git file, main has .git directory)
-    if (!existsSync(gitPath))
-        return null;
-    try {
-        const stats = statSync(gitPath);
-        if (stats.isFile()) {
-            // Parse .git file to verify it points to main repo's worktrees
-            const gitContent = readFileSync(gitPath, { encoding: 'utf-8' });
-            const match = gitContent.match(/^gitdir:\s*(.+)$/m);
-            if (match && match[1].includes('.git/worktrees/')) {
-                console.log(`${LOG_PREFIX.DONE} ${EMOJI.TARGET} Auto-detected worktree from process.cwd(): ${cwd}`);
-                return cwd;
-            }
-        }
-    }
-    catch (err) {
-        // Ignore errors, fall back to calculated path
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Failed to detect worktree: ${err.message}`);
-    }
-    return null;
-}
-/**
- * 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 async function defaultWorktreeFrom(doc) {
-    // Priority 1 - use recorded worktree_path if available
-    if (doc.worktree_path) {
-        return doc.worktree_path;
-    }
-    // Priority 2 - calculate from current lane field (legacy behavior)
-    const lane = (doc.lane || '').toString();
-    const laneK = toKebab(lane);
-    const idK = (doc.id || '').toLowerCase();
-    if (!laneK || !idK)
-        return null;
-    const calculated = `worktrees/${laneK}-${idK}`;
-    // Priority 3 - verify calculated path exists, or find actual path via git worktree list
-    let calculatedExists = true;
-    try {
-        await access(calculated);
-    }
-    catch {
-        calculatedExists = false;
-    }
-    if (!calculatedExists) {
-        try {
-            const worktreeList = await getGitForCwd().worktreeList();
-            const lines = worktreeList.split(STRING_LITERALS.NEWLINE);
-            const branch = `lane/${laneK}/${idK}`;
-            for (let i = 0; i < lines.length; i++) {
-                if (lines[i].startsWith('branch ') && lines[i].includes(branch)) {
-                    // Found the branch, now get the worktree path from previous line
-                    for (let j = i - 1; j >= 0; j--) {
-                        if (lines[j].startsWith('worktree ')) {
-                            const fullPath = lines[j].substring('worktree '.length);
-                            // Convert absolute path to relative path from repo root
-                            const repoRoot = process.cwd();
-                            const relativePath = path.relative(repoRoot, fullPath);
-                            console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Worktree path mismatch detected:\n` +
-                                `  Expected: ${calculated}\n` +
-                                `  Actual:   ${relativePath}\n` +
-                                `  Using actual path from git worktree list`);
-                            return relativePath;
-                        }
-                    }
-                }
-            }
-        }
-        catch (e) {
-            console.warn(`${LOG_PREFIX.DONE} Could not query git worktree list: ${e.message}`);
-        }
-    }
-    return calculated;
-}
-/**
- * Detect workspace mode from WU YAML
- * @param {object} doc - WU YAML document
- * @returns {'worktree' | 'branch-only'}
- */
-export function detectWorkspaceMode(doc) {
-    // Explicit mode field takes precedence
-    if (doc.claimed_mode === CLAIMED_MODES.BRANCH_ONLY)
-        return CLAIMED_MODES.BRANCH_ONLY;
-    if (doc.claimed_mode === CLAIMED_MODES.WORKTREE)
-        return CLAIMED_MODES.WORKTREE;
-    // Backward compatibility: if claimed_mode is missing, assume worktree mode
-    // (all WUs claimed before WU-510 used worktree mode)
-    return CLAIMED_MODES.WORKTREE;
-}
-/**
- * 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 function defaultBranchFrom(doc) {
-    const lane = (doc.lane || '').toString();
-    const laneK = toKebab(lane);
-    const idK = (doc.id || '').toLowerCase();
-    if (!laneK || !idK)
-        return null;
-    return `lane/${laneK}/${idK}`;
-}
-/**
- * Check if a branch exists
- * @param {string} branch - Branch name to check
- * @returns {Promise<boolean>} True if branch exists
- */
-export async function branchExists(branch) {
-    return await getGitForCwd().branchExists(branch);
-}
-/**
- * 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 async function detectModeAndPaths(id, args) {
-    const WU_PATH = WU_PATHS.WU(id);
-    const STATUS_PATH = WU_PATHS.STATUS();
-    const BACKLOG_PATH = WU_PATHS.BACKLOG();
-    const STAMPS_DIR = WU_PATHS.STAMPS_DIR();
-    // Read WU YAML to detect workspace mode
-    let docMain = readWU(WU_PATH, id);
-    const workspaceMode = detectWorkspaceMode(docMain);
-    const isBranchOnly = workspaceMode === CLAIMED_MODES.BRANCH_ONLY;
-    console.log(`\n${LOG_PREFIX.DONE} Detected workspace mode: ${workspaceMode}`);
-    // Determine candidate worktree path early (only relevant for Worktree mode)
-    // Priority: 1) Auto-detect from cwd 2) Explicit --worktree arg 3) Calculate from YAML
-    const detectedWorktree = detectCurrentWorktree();
-    const worktreePathGuess = args.worktree || null;
-    // For Worktree mode: prefer auto-detected worktree, then explicit arg, then calculated path
-    // For Branch-Only mode: use main checkout version (no worktree exists)
-    const derivedWorktree = isBranchOnly
-        ? null
-        : detectedWorktree || worktreePathGuess || (await defaultWorktreeFrom(docMain));
-    if (!isBranchOnly && derivedWorktree && !detectedWorktree) {
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.FOLDER} Calculated worktree path from YAML: ${derivedWorktree}`);
-    }
-    // Read the actual WU YAML for validation (prefer worktree version over main)
-    const docForValidation = isBranchOnly
-        ? docMain
-        : readWUPreferWorktree(id, derivedWorktree, WU_PATH);
-    // WU-1234: Detect docs-only by type OR by code_paths
-    // Auto-detect if all code_paths are under docs/, ai/, .claude/, or are README/CLAUDE files
-    const isDocsOnlyByType = docForValidation.type === 'documentation';
-    const isDocsOnlyByPaths = detectDocsOnlyByPaths(docForValidation.code_paths);
-    const isDocsOnly = isDocsOnlyByType || isDocsOnlyByPaths;
-    if (isDocsOnlyByPaths && !isDocsOnlyByType) {
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Auto-detected docs-only WU from code_paths (type: ${docForValidation.type || 'unset'})`);
-    }
-    return {
-        WU_PATH,
-        STATUS_PATH,
-        BACKLOG_PATH,
-        STAMPS_DIR,
-        docMain,
-        workspaceMode,
-        isBranchOnly,
-        derivedWorktree,
-        docForValidation,
-        isDocsOnly,
-    };
-}
-/**
- * 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 function generateCommitMessage(id, title, maxLength = DEFAULTS.MAX_COMMIT_SUBJECT) {
-    const prefix = `wu(${id.toLowerCase()}): done - `;
-    const safe = String(title).trim().toLowerCase().replace(/\s+/g, ' ');
-    const room = Math.max(0, maxLength - prefix.length);
-    const short = safe.length > room ? `${safe.slice(0, room - 1)}…` : safe;
-    const msg = `${prefix}${short}`;
-    if (msg.length > maxLength) {
-        const error = new Error(`Commit message too long (${msg.length}/${maxLength}).\n` +
-            `Fix: Shorten WU title\n` +
-            `Current title: "${title}" (${title.length} chars)\n` +
-            `Suggested max: ~${maxLength - prefix.length} chars`);
-        error.code = 'COMMIT_MESSAGE_TOO_LONG';
-        error.data = {
-            title,
-            titleLength: title.length,
-            messageLength: msg.length,
-            maxLength,
-            suggestedMax: maxLength - prefix.length,
-        };
-        throw error;
-    }
-    return msg;
-}
-/**
- * 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 function validateMetadataFilesExist({ statusPath, backlogPath }) {
-    const missing = [];
-    if (!existsSync(statusPath)) {
-        missing.push(`Status: ${statusPath}`);
-    }
-    if (!existsSync(backlogPath)) {
-        missing.push(`Backlog: ${backlogPath}`);
-    }
-    if (missing.length > 0) {
-        throw createError(ErrorCodes.FILE_NOT_FOUND, `Required metadata files missing:\n  ${missing.join('\n  ')}\n\nCannot complete WU - verify worktree has latest metadata files.`, { missingFiles: missing });
-    }
-}
-/**
- * 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 async function updateMetadataFiles({ id, title, doc, wuPath, statusPath, backlogPath }) {
-    // WU-1275: Fail fast before any mutations
-    validateMetadataFilesExist({ statusPath, backlogPath });
-    // Update WU YAML (mark as done, lock, set completion timestamp)
-    doc.status = 'done';
-    doc.locked = true;
-    doc.completed_at = new Date().toISOString();
-    writeWU(wuPath, doc);
-    // Update status.md (remove from In Progress, add to Completed)
-    updateStatusRemoveInProgress(statusPath, id);
-    addToStatusCompleted(statusPath, id, title);
-    // Update backlog.md (move to Done section)
-    // WU-1572: Now async for state store integration
-    await moveWUToDoneBacklog(backlogPath, id, title);
-    // Create completion stamp
-    createStamp({ id, title });
-}
-/**
- * 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
- */
-// WU-1574: Made async for computeBacklogContent
-export async function collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction, }) {
-    // WU-1369: Fail fast before any computations
-    validateMetadataFilesExist({ statusPath, backlogPath });
-    // Compute WU YAML content (mutates doc, returns YAML string)
-    const wuYAMLContent = computeWUYAMLContent(doc);
-    transaction.addWrite(wuPath, wuYAMLContent, 'WU YAML');
-    // Compute status.md content
-    const statusContent = computeStatusContent(statusPath, id, title);
-    transaction.addWrite(statusPath, statusContent, 'status.md');
-    // Compute backlog.md content (WU-1574: now async)
-    const backlogContent = await computeBacklogContent(backlogPath, id, title);
-    transaction.addWrite(backlogPath, backlogContent, 'backlog.md');
-    const wuEventsUpdate = await computeWUEventsContentAfterComplete(backlogPath, id);
-    if (wuEventsUpdate) {
-        transaction.addWrite(wuEventsUpdate.eventsPath, wuEventsUpdate.content, 'wu-events.jsonl');
-    }
-    // Compute stamp content
-    const stampContent = computeStampContent(id, title);
-    transaction.addWrite(stampPath, stampContent, 'completion stamp');
-    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Collected ${transaction.size} metadata updates for atomic commit`);
-}
-/**
- * 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 async function stageAndFormatMetadata({ id, wuPath, statusPath, backlogPath, stampsDir }) {
-    // WU-1235: Use getGitForCwd() to capture current directory (worktree after chdir)
-    // The singleton git adapter captures cwd at import time, which is wrong after process.chdir()
-    const gitCwd = getGitForCwd();
-    // Stage files
-    const wuEventsPath = path.join(BEACON_PATHS.STATE_DIR, WU_EVENTS_FILE_NAME);
-    const filesToStage = [wuPath, statusPath, backlogPath, stampsDir];
-    if (existsSync(wuEventsPath)) {
-        filesToStage.push(wuEventsPath);
-    }
-    await gitCwd.add(filesToStage);
-    // Format documentation
-    console.log(`${LOG_PREFIX.DONE} Formatting auto-generated documentation...`);
-    try {
-        const prettierCmd = `${PKG_MANAGER} ${SCRIPTS.PRETTIER} ${PRETTIER_FLAGS.WRITE} "${wuPath}" "${statusPath}" "${backlogPath}"`;
-        await execAsync(prettierCmd);
-        await gitCwd.add([wuPath, statusPath, backlogPath]);
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Documentation formatted`);
-    }
-    catch (err) {
-        throw createError(ErrorCodes.VALIDATION_ERROR, `Failed to format documentation: ${err.message}`, { wuId: id, error: err.message });
-    }
-}
-/**
- * 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 async function runCleanup(docMain, args) {
-    const wuId = docMain.id;
-    const worktreePath = args.worktree || (await defaultWorktreeFrom(docMain));
-    // WU-2278: Validate worktree ownership before cleanup
-    // Prevents cross-agent worktree deletion
-    if (!args.overrideOwner) {
-        const ownershipResult = validateWorktreeOwnership({ worktreePath, wuId });
-        if (!ownershipResult.valid) {
-            throw createError(ErrorCodes.VALIDATION_ERROR, `${ownershipResult.error}\n\nTo override (DANGEROUS): pnpm wu:done --id ${wuId} --override-owner --reason "explanation"`, { wuId, worktreePath, error: ownershipResult.error });
-        }
-    }
-    // WU-2241: Wrap cleanup operations in cleanup lock to prevent concurrent collision
-    await withCleanupLock(wuId, async () => {
-        await runCleanupInternal(docMain, args, worktreePath);
-    }, { worktreePath });
-}
-/**
- * Internal cleanup implementation (runs under cleanup lock)
- *
- * @param {object} docMain - WU YAML document
- * @param {object} args - Parsed CLI arguments
- * @param {string|null} worktreePath - Path to worktree
- */
-async function runCleanupInternal(docMain, args, worktreePath) {
-    // Step 6: Remove worktree (runs even if commit/push failed)
-    // Skip removal in PR mode (worktree needed for cleanup after PR merge)
-    const claimedMode = docMain.claimed_mode || CLAIMED_MODES.WORKTREE;
-    const requiresReview = docMain.requires_review === true;
-    const prModeEnabled = claimedMode === CLAIMED_MODES.WORKTREE_PR || args.createPR || requiresReview;
-    // WU-2241: Track branch for cleanup after worktree removal
-    const laneBranch = await defaultBranchFrom(docMain);
-    if (!args.noRemove && !prModeEnabled) {
-        if (worktreePath && existsSync(worktreePath)) {
-            try {
-                await getGitForCwd().worktreeRemove(worktreePath, { force: true });
-                console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Removed worktree ${worktreePath}`);
-                // WU-2241: Delete branch AFTER worktree removal (correct ordering)
-                // This ensures we don't leave orphan branches when worktree is removed
-                if (laneBranch && (await branchExists(laneBranch))) {
-                    await deleteBranchWithCleanup(laneBranch);
-                }
-                // WU-1743: Re-run pnpm install to fix broken symlinks
-                // When pnpm install runs in a worktree, it may create symlinks with absolute paths
-                // to the worktree. After worktree removal, these symlinks break.
-                // Re-running pnpm install regenerates them with correct paths.
-                // WU-2278: Use timeout and CI=true to prevent hangs
-                console.log(`${LOG_PREFIX.DONE} Reinstalling dependencies to fix symlinks...`);
-                try {
-                    const installConfig = getCleanupInstallConfig();
-                    await execAsync(installConfig.command, {
-                        timeout: installConfig.timeout,
-                        env: installConfig.env,
-                    });
-                    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Dependencies reinstalled`);
-                }
-                catch (installErr) {
-                    // Non-fatal: warn but don't fail wu:done
-                    // WU-2278: Include timeout info in error message
-                    const isTimeout = installErr.killed || installErr.signal === 'SIGTERM';
-                    const errorMsg = isTimeout
-                        ? `pnpm install timed out after ${CLEANUP_INSTALL_TIMEOUT_MS / 1000}s`
-                        : `pnpm install failed: ${installErr.message}`;
-                    console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} ${errorMsg}`);
-                }
-            }
-            catch (e) {
-                console.warn(`${LOG_PREFIX.DONE} Could not remove worktree ${worktreePath}: ${e.message}`);
-            }
-        }
-        else {
-            console.log(`${LOG_PREFIX.DONE} Worktree not found; skipping removal`);
-            // WU-2241: Still cleanup branch if worktree doesn't exist (orphan branch scenario)
-            if (!prModeEnabled && laneBranch && (await branchExists(laneBranch))) {
-                await deleteBranchWithCleanup(laneBranch);
-            }
-        }
-    }
-    else if (prModeEnabled) {
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Worktree preserved (PR mode - run wu:cleanup after PR merge)`);
-    }
-}
-/**
- * WU-2241: Delete both local and remote branch with proper error handling
- *
- * @param {string} laneBranch - Branch name to delete
- */
-async function deleteBranchWithCleanup(laneBranch) {
-    const gitAdapter = getGitForCwd();
-    // WU-1440: Check if branch is merged before deletion
-    // Use -D (force) when confirmed merged to handle rebased branches
-    const isMerged = await isBranchAlreadyMerged(laneBranch);
-    try {
-        await gitAdapter.deleteBranch(laneBranch, { force: isMerged });
-        const modeIndicator = isMerged ? ' (force: merged)' : '';
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Deleted local branch ${laneBranch}${modeIndicator}`);
-        // Also delete remote if it exists
-        try {
-            await gitAdapter.raw(['push', REMOTES.ORIGIN, '--delete', laneBranch]);
-            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Deleted remote branch ${laneBranch}`);
-        }
-        catch (e) {
-            // WU-2241: Non-fatal - remote branch may already be deleted or never existed
-            console.warn(`${LOG_PREFIX.DONE} Could not delete remote branch: ${e.message}`);
-        }
-    }
-    catch (e) {
-        console.warn(`${LOG_PREFIX.DONE} Could not delete branch ${laneBranch}: ${e.message}`);
-    }
-}
-export async function validateCodePathsExist(doc, id, options = {}) {
-    const { targetBranch = BRANCHES.MAIN, worktreePath = null } = options;
-    const errors = [];
-    const missing = [];
-    const codePaths = doc.code_paths || [];
-    // Skip validation for WUs without code_paths (docs-only, process WUs)
-    if (codePaths.length === 0) {
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} No code_paths to validate for ${id}`);
-        return { valid: true, errors: [], missing: [] };
-    }
-    console.log(`${LOG_PREFIX.DONE} Validating ${codePaths.length} code_paths exist...`);
-    // For worktree mode, check files exist in the worktree (will be merged)
-    // For branch-only mode or post-merge validation, check files exist on target branch
-    if (worktreePath && existsSync(worktreePath)) {
-        // Worktree mode: validate files exist in worktree
-        for (const filePath of codePaths) {
-            const fullPath = path.join(worktreePath, filePath);
-            if (!existsSync(fullPath)) {
-                missing.push(filePath);
-            }
-        }
-        if (missing.length > 0) {
-            errors.push(`code_paths validation failed - ${missing.length} file(s) not found in worktree:\n${missing
-                .map((p) => `  - ${p}`)
-                .join(STRING_LITERALS.NEWLINE)}\n\nEnsure all files listed in code_paths exist before running wu:done.`);
-        }
-    }
-    else {
-        // Branch-only or post-merge: use git ls-tree to check files on target branch
-        try {
-            const gitAdapter = getGitForCwd();
-            for (const filePath of codePaths) {
-                try {
-                    // git ls-tree returns empty for non-existent files
-                    const result = await gitAdapter.raw([GIT_COMMANDS.LS_TREE, targetBranch, '--', filePath]);
-                    if (!result || result.trim() === '') {
-                        missing.push(filePath);
-                    }
-                }
-                catch {
-                    // git ls-tree fails for non-existent paths
-                    missing.push(filePath);
-                }
-            }
-            if (missing.length > 0) {
-                errors.push(`code_paths validation failed - ${missing.length} file(s) not found on ${targetBranch}:\n${missing
-                    .map((p) => `  - ${p}`)
-                    .join(STRING_LITERALS.NEWLINE)}\n\n❌ POTENTIAL FALSE COMPLETION DETECTED\n\n` +
-                    `These files are listed in code_paths but do not exist on ${targetBranch}.\n` +
-                    `This prevents creating a stamp for incomplete work.\n\n` +
-                    `Fix options:\n` +
-                    `  1. Ensure all code is committed and merged to ${targetBranch}\n` +
-                    `  2. Update code_paths in ${id}.yaml to match actual files\n` +
-                    `  3. Remove files that were intentionally not created\n\n` +
-                    `Context: WU-1351 prevents false completions from INIT-WORKFLOW-INTEGRITY`);
-            }
-        }
-        catch (err) {
-            // Non-fatal: warn but don't block if git command fails
-            console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not validate code_paths: ${err.message}`);
-            return { valid: true, errors: [], missing: [] };
-        }
-    }
-    if (errors.length > 0) {
-        return { valid: false, errors, missing };
-    }
-    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All ${codePaths.length} code_paths verified`);
-    return { valid: true, errors: [], missing: [] };
-}
-/**
- * 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 function validateSpecCompleteness(doc, _id) {
-    const errors = [];
-    // Check for placeholder text in description
-    if (doc.description && doc.description.includes(PLACEHOLDER_SENTINEL)) {
-        errors.push(`Description contains ${PLACEHOLDER_SENTINEL} marker`);
-    }
-    // Handle both array and object formats for acceptance criteria
-    if (doc.acceptance) {
-        const hasPlaceholder = (value) => {
-            if (typeof value === 'string') {
-                return value.includes(PLACEHOLDER_SENTINEL);
-            }
-            if (Array.isArray(value)) {
-                return value.some((item) => hasPlaceholder(item));
-            }
-            if (typeof value === 'object' && value !== null) {
-                return Object.values(value).some((item) => hasPlaceholder(item));
-            }
-            return false;
-        };
-        if (hasPlaceholder(doc.acceptance)) {
-            errors.push(`Acceptance criteria contain ${PLACEHOLDER_SENTINEL} markers`);
-        }
-    }
-    // Check minimum description length
-    // WU-1281: Using centralized constant from wu-constants.mjs
-    if (!doc.description || doc.description.trim().length < VALIDATION.MIN_DESCRIPTION_LENGTH) {
-        errors.push(`Description too short (${doc.description?.trim().length || 0} chars, minimum ${VALIDATION.MIN_DESCRIPTION_LENGTH})`);
-    }
-    // Check code_paths for non-documentation WUs
-    // WU-1281: Using centralized type constants from wu-constants.mjs
-    if (doc.type !== WU_TYPES.DOCUMENTATION && doc.type !== WU_TYPES.PROCESS) {
-        if (!doc.code_paths || doc.code_paths.length === 0) {
-            errors.push('Code paths required for non-documentation WUs');
-        }
-        // WU-1280: Check tests array for non-documentation WUs
-        // Support both tests: (current) and test_paths: (legacy)
-        const testObj = doc.tests || doc.test_paths || {};
-        // Helper to check if array has items
-        const hasItems = (arr) => Array.isArray(arr) && arr.length > 0;
-        // WU-1281: Using centralized test type constants from wu-constants.mjs
-        const hasUnitTests = hasItems(testObj[TEST_TYPES.UNIT]);
-        const hasE2ETests = hasItems(testObj[TEST_TYPES.E2E]);
-        const hasManualTests = hasItems(testObj[TEST_TYPES.MANUAL]);
-        const hasIntegrationTests = hasItems(testObj[TEST_TYPES.INTEGRATION]);
-        if (!(hasUnitTests || hasE2ETests || hasManualTests || hasIntegrationTests)) {
-            errors.push('At least one test path required (unit, e2e, integration, or manual)');
-        }
-        // WU-2332: Require automated tests for code file changes
-        // Manual-only tests are not sufficient when code_paths contain actual code files
-        const automatedTestResult = validateAutomatedTestRequirement(doc);
-        if (!automatedTestResult.valid) {
-            errors.push(...automatedTestResult.errors);
-        }
-    }
-    return { valid: errors.length === 0, errors };
-}
-// WU-1433: Re-export manual test validator for use in wu:done workflow
-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 function validatePostMutation({ id, wuPath, stampPath }) {
-    const errors = [];
-    // Check stamp file exists
-    if (!existsSync(stampPath)) {
-        errors.push(`Stamp file not created: ${stampPath}`);
-    }
-    // Read and validate WU YAML after mutation
-    if (!existsSync(wuPath)) {
-        errors.push(`WU YAML not found after mutation: ${wuPath}`);
-        return { valid: false, errors };
-    }
-    try {
-        const content = readFileSync(wuPath, { encoding: 'utf-8' });
-        const doc = parseYAML(content);
-        // Verify completed_at exists and is valid ISO datetime
-        if (!doc.completed_at) {
-            errors.push(`Missing required field 'completed_at' in ${id}.yaml`);
-        }
-        else {
-            // Validate ISO datetime format (YYYY-MM-DDTHH:mm:ss.sssZ or similar)
-            const timestamp = new Date(doc.completed_at);
-            if (isNaN(timestamp.getTime())) {
-                errors.push(`Invalid completed_at timestamp: ${doc.completed_at}`);
-            }
-        }
-        // Verify locked is true
-        if (doc.locked !== true) {
-            errors.push(`Missing or invalid 'locked' field in ${id}.yaml (expected: true, got: ${doc.locked})`);
-        }
-        // Verify status is done
-        if (doc.status !== 'done') {
-            errors.push(`Invalid status in ${id}.yaml (expected: 'done', got: '${doc.status}')`);
-        }
-    }
-    catch (err) {
-        errors.push(`Failed to parse WU YAML after mutation: ${err.message}`);
-    }
-    return { valid: errors.length === 0, errors };
-}
-/**
- * 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 function buildPreflightErrorMessage(id, errors) {
-    const hasStampStatusError = errors.some((e) => e.includes('stamp but status is not done'));
-    let message = `
-❌ PREFLIGHT VALIDATION FAILED
-
-tasks:validate found errors that would block pre-push hooks.
-Aborting wu:done BEFORE any merge operations to prevent deadlocks.
-
-Errors:
-${errors.map((e) => `  - ${e}`).join('\n')}
-
-Fix options:
-`;
-    if (hasStampStatusError) {
-        message += `
-  For stamp-status mismatch errors:
-  1. Fix the WU status to match the stamp (set status: done, locked: true)
-  2. Or add the WU ID to .lumenflow.config.yaml > exemptions > stamp_status_mismatch
-
-`;
-    }
-    message += `
-  General fixes:
-  1. Run: pnpm tasks:validate to see full errors
-  2. Fix the validation errors
-  3. Retry: pnpm wu:done --id ${id}
-
-This preflight check prevents wu:done from leaving main in a stuck state
-where husky pre-push would block all further operations.
-`;
-    return message;
-}
-export async function executePreflightCodePathValidation(id, paths, options = {}) {
-    // Use injected validator for testability, default to actual implementation
-    const validatePreflightFn = options.validatePreflightFn || validatePreflight;
-    console.log(`\n${LOG_PREFIX.DONE} 🔍 Preflight: validating code_paths and test paths...`);
-    const result = await validatePreflightFn(id, {
-        rootDir: paths.rootDir,
-        worktreePath: paths.worktreePath,
-    });
-    if (result.valid) {
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Preflight code_paths validation passed`);
-        return {
-            valid: true,
-            errors: [],
-            missingCodePaths: [],
-            missingTestPaths: [],
-            abortedBeforeGates: false,
-        };
-    }
-    console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Preflight code_paths validation failed`);
-    return {
-        valid: false,
-        errors: result.errors,
-        missingCodePaths: result.missingCodePaths || [],
-        missingTestPaths: result.missingTestPaths || [],
-        abortedBeforeGates: true,
-    };
-}
-/**
- * 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 function buildPreflightCodePathErrorMessage(id, result) {
-    const { errors, missingCodePaths = [], missingTestPaths = [] } = result;
-    let message = `
-❌ PREFLIGHT CODE_PATHS VALIDATION FAILED
-
-code_paths/test_paths validation found errors that would cause gates to fail.
-Aborting wu:done BEFORE running gates to save time.
-
-Errors:
-${errors.map((e) => `  ${e}`).join('\n')}
-
-`;
-    if (missingCodePaths.length > 0) {
-        message += `
-Fix options for missing code_paths:
-  1. Create the missing files in your worktree
-  2. Update code_paths in ${id}.yaml using: pnpm wu:edit --id ${id} --code-paths "<corrected-paths>"
-  3. Remove paths that were intentionally not created
-
-`;
-    }
-    if (missingTestPaths.length > 0) {
-        message += `
-Fix options for missing test_paths:
-  1. Create the missing test files
-  2. Update test paths in ${id}.yaml using wu:edit
-  3. Use tests.manual for descriptions instead of file paths
-
-`;
-    }
-    message += `
-After fixing, retry:
-  pnpm wu:done --id ${id}
-
-This preflight check runs BEFORE gates to catch YAML mismatches early.
-See: ai/onboarding/troubleshooting-wu-done.md for more recovery options.
-`;
-    return message;
-}
-export function runPreflightTasksValidation(id, options = {}) {
-    // Use injected execSync for testability, default to node's child_process
-    const execSyncFn = options.execSyncFn || execSyncImport;
-    console.log(`\n${LOG_PREFIX.DONE} 🔍 Preflight: running tasks:validate...`);
-    try {
-        // Run tasks:validate with WU_ID context (single-WU validation mode)
-        execSyncFn('node tools/validate.js', {
-            stdio: STDIO.PIPE,
-            encoding: 'utf-8',
-            env: { ...process.env, WU_ID: id },
-        });
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Preflight tasks:validate passed`);
-        return {
-            valid: true,
-            errors: [],
-            abortedBeforeMerge: false,
-            localMainModified: false,
-            hasStampStatusError: false,
-        };
-    }
-    catch (err) {
-        // Validation failed - extract errors from output
-        const output = err.stdout || err.message || 'Unknown validation error';
-        const errors = output
-            .split('\n')
-            .filter((line) => line.includes('[') && line.includes(']'))
-            .map((line) => line.trim());
-        const hasStampStatusError = errors.some((e) => e.includes('stamp but status is not done'));
-        console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Preflight tasks:validate failed`);
-        return {
-            valid: false,
-            errors: errors.length > 0 ? errors : [output],
-            abortedBeforeMerge: true,
-            localMainModified: false,
-            hasStampStatusError,
-        };
-    }
-}
-/**
- * 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 function validateAllPreCommitHooks(id, worktreePath = null, options = {}) {
-    const execSyncFn = options.execSyncFn || execSyncImport;
-    console.log(`\n${LOG_PREFIX.DONE} 🔍 Pre-flight: validating all pre-commit hooks...`);
-    const errors = [];
-    try {
-        // WU-2308: Run from worktree context when provided to ensure audit checks
-        // the worktree's dependencies (with fixes) not main's stale dependencies
-        const execOptions = {
-            stdio: STDIO.INHERIT,
-            encoding: 'utf-8',
-        };
-        // Only set cwd when worktreePath is provided
-        if (worktreePath) {
-            execOptions.cwd = worktreePath;
-        }
-        // Run the gates-pre-commit script that contains all validation gates
-        execSyncFn('node tools/gates-pre-commit.js', execOptions);
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All pre-commit hooks passed`);
-        return { valid: true, errors: [] };
-    }
-    catch {
-        // Pre-commit hooks failed
-        errors.push('Pre-commit hook validation failed. Fix these issues before wu:done:');
-        errors.push('');
-        errors.push('Common fixes:');
-        errors.push('  • Formatting issues: Run pnpm format');
-        errors.push('  • Lint errors: Run pnpm lint:fix');
-        errors.push('  • Type errors: Check pnpm typecheck output');
-        errors.push('  • Audit issues: Check pnpm audit output');
-        errors.push('');
-        errors.push(`After fixing, re-run: pnpm wu:done --id ${id}`);
-        return { valid: false, errors };
-    }
-}
-/**
- * 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 function validateTestPathsRequired(wu) {
-    // Skip validation for documentation and process WUs
-    if (wu.type === WU_TYPES.DOCUMENTATION || wu.type === WU_TYPES.PROCESS) {
-        return { valid: true };
-    }
-    // Skip if code_paths is empty or undefined
-    const codePaths = wu.code_paths || [];
-    if (codePaths.length === 0) {
-        return { valid: true };
-    }
-    // Skip if all code_paths are documentation paths
-    const hasCodeChanges = codePaths.some((p) => !isDocumentationPath(p));
-    if (!hasCodeChanges) {
-        return { valid: true };
-    }
-    // Check if tests object exists and has at least one test
-    const testObj = wu.tests || {};
-    // Helper to check if array has items
-    const hasItems = (arr) => Array.isArray(arr) && arr.length > 0;
-    const hasUnitTests = hasItems(testObj[TEST_TYPES.UNIT]);
-    const hasE2ETests = hasItems(testObj[TEST_TYPES.E2E]);
-    const hasManualTests = hasItems(testObj[TEST_TYPES.MANUAL]);
-    const hasIntegrationTests = hasItems(testObj[TEST_TYPES.INTEGRATION]);
-    // No tests at all - fail
-    if (!(hasUnitTests || hasE2ETests || hasManualTests || hasIntegrationTests)) {
-        return {
-            valid: false,
-            error: `${wu.id} requires test_paths: WU has code_paths but no tests specified. Add unit, e2e, integration, or manual tests.`,
-        };
-    }
-    // WU-2332: If we have tests, also check automated test requirement for code files
-    // Manual-only tests are not sufficient for code changes
-    const automatedTestResult = validateAutomatedTestRequirement(wu);
-    if (!automatedTestResult.valid) {
-        // Extract the first error line for the single-error format of this function
-        const errorSummary = automatedTestResult.errors[0]?.split('\n')[0] || 'Automated tests required';
-        return {
-            valid: false,
-            error: `${wu.id}: ${errorSummary}`,
-        };
-    }
-    return { valid: true };
-}
-/**
- * WU-2310: Allowed path patterns for documentation WUs.
- * Mirrors the patterns in gates-pre-commit.mjs gateDocsOnlyPathEnforcement()
- * to enable early validation at preflight (before transaction starts).
- *
- * @constant {RegExp[]}
- */
-const DOCS_ONLY_ALLOWED_PATTERNS = [
-    /^memory-bank\//i,
-    /^docs\//i,
-    /\.md$/i,
-    /^\.beacon\/stamps\//i,
-    /^\.claude\//i,
-    /^ai\//i,
-    /^README\.md$/i,
-    /^CLAUDE\.md$/i,
-];
-/**
- * WU-2310: Check if a path is allowed for documentation WUs.
- *
- * @param {string} filePath - File path to check
- * @returns {boolean} True if path is allowed for docs WUs
- */
-function isAllowedDocsPath(filePath) {
-    if (!filePath || typeof filePath !== 'string')
-        return false;
-    return DOCS_ONLY_ALLOWED_PATTERNS.some((pattern) => pattern.test(filePath));
-}
-/**
- * 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 function validateTypeVsCodePathsPreflight(wu) {
-    const errors = [];
-    const blockedPaths = [];
-    // Only validate documentation WUs
-    if (wu.type !== WU_TYPES.DOCUMENTATION) {
-        return { valid: true, errors: [], blockedPaths: [], abortedBeforeTransaction: false };
-    }
-    // Skip if no code_paths
-    const codePaths = wu.code_paths;
-    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
-        return { valid: true, errors: [], blockedPaths: [], abortedBeforeTransaction: false };
-    }
-    // Check each code_path against allowed patterns
-    for (const filePath of codePaths) {
-        if (!isAllowedDocsPath(filePath)) {
-            blockedPaths.push(filePath);
-        }
-    }
-    if (blockedPaths.length > 0) {
-        const pathsList = blockedPaths.map((p) => `  - ${p}`).join('\n');
-        errors.push(`Documentation WU ${wu.id} has code_paths that would fail pre-commit hook:\n${pathsList}`);
-        return { valid: false, errors, blockedPaths, abortedBeforeTransaction: true };
-    }
-    return { valid: true, errors: [], blockedPaths: [], abortedBeforeTransaction: false };
-}
-/**
- * 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
+ * wu:done validators - aggregated exports
  *
- * @param {string} id - WU ID
- * @param {string[]} blockedPaths - Paths that would be blocked
- * @returns {string} Formatted error message
+ * WU-1049: Split validators into focused modules while preserving exports.
  */
-export function buildTypeVsCodePathsErrorMessage(id, blockedPaths) {
-    return `
-PREFLIGHT VALIDATION FAILED (WU-2310)
-
-WU ${id} is type: documentation but has code_paths that are not allowed:
-
-${blockedPaths.map((p) => `  - ${p}`).join('\n')}
-
-This would fail at git commit time (pre-commit hook: gateDocsOnlyPathEnforcement).
-Aborting BEFORE transaction to prevent inconsistent state.
-
-Fix options:
-
-  1. Change WU type to 'engineering' (or 'feature', 'bug', etc.):
-     pnpm wu:edit --id ${id} --type engineering
-
-  2. Update code_paths to only include documentation files:
-     pnpm wu:edit --id ${id} --code-paths "docs/..." "*.md"
-
-Allowed paths for documentation WUs:
-  - docs/
-  - ai/
-  - .claude/
-  - memory-bank/
-  - .beacon/stamps/
-  - *.md files
-
-After fixing, retry: pnpm wu:done --id ${id}
-`;
-}
+export { validateInputs } from './wu-done-inputs.js';
+export { readWUPreferWorktree, detectCurrentWorktree, defaultWorktreeFrom, detectWorkspaceMode, defaultBranchFrom, branchExists, detectModeAndPaths, } from './wu-done-paths.js';
+export { generateCommitMessage, validateMetadataFilesExist, updateMetadataFiles, collectMetadataToTransaction, stageAndFormatMetadata, } from './wu-done-metadata.js';
+export { runCleanup } from './wu-done-cleanup.js';
+export { applyExposureDefaults, validateCodePathsExist, validateSpecCompleteness, validatePostMutation, validateTestPathsRequired, validateTypeVsCodePathsPreflight, buildTypeVsCodePathsErrorMessage, } from './wu-done-validation.js';
+export { buildPreflightErrorMessage, executePreflightCodePathValidation, buildPreflightCodePathErrorMessage, runPreflightTasksValidation, validateAllPreCommitHooks, } from './wu-done-preflight.js';
+export { validateAutomatedTestRequirement } from './manual-test-validator.js';