@lumenflow/cli 3.8.7 → 3.9.0

package/dist/wu-done.js

@@ -42,70 +42,56 @@ import { wuDoneMachine, WU_DONE_EVENTS } from '@lumenflow/core/wu-done-machine';
 // The guard runs in executeWorktreeCompletion() before metadata transaction
 // See: packages/@lumenflow/core/src/wu-done-validation.ts
 import { execSync } from 'node:child_process';
-import prettyMs from 'pretty-ms';
 import { runGates } from './gates.js';
+import { executeGates } from './wu-done-gates.js';
 // WU-2102: Import scoped test resolver for wu:done gate fallback
 import { resolveScopedUnitTestsForPrep } from './wu-prep.js';
-import { resolveWuDonePreCommitGateDecision } from '@lumenflow/core/gates-agent-mode';
 import { buildClaimRepairCommand } from './wu-claim-repair-guidance.js';
 import { resolveStateDir, resolveWuEventsRelativePath } from './state-path-resolvers.js';
-import { getGitForCwd, createGitForPath } from '@lumenflow/core/git-adapter';
-import { die, getErrorMessage, createError, ErrorCodes } from '@lumenflow/core/error-handler';
+import { appendClaimSessionOverrideAuditEvent, auditOwnershipOverride, checkBacklogConsistencyForWU, checkOwnership, computeBranchOnlyFallback, runWuDoneStagedValidation, } from './wu-done-preflight.js';
+import { getGitForCwd } from '@lumenflow/core/git-adapter';
+import { die, getErrorMessage } from '@lumenflow/core/error-handler';
 // WU-1223: Location detection for worktree check
 import { resolveLocation } from '@lumenflow/core/context/location-resolver';
-import { existsSync, readFileSync, mkdirSync, appendFileSync, unlinkSync, statSync, readdirSync, } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, appendFileSync, unlinkSync, readdirSync, } from 'node:fs';
 import path from 'node:path';
 // WU-1825: Import from unified code-path-validator (consolidates 3 validators)
 import { validateWUCodePaths } from '@lumenflow/core/code-path-validator';
 import { rollbackFiles } from '@lumenflow/core/rollback-utils';
-import { validateInputs, detectModeAndPaths, defaultBranchFrom, runCleanup, validateSpecCompleteness, runPreflightTasksValidation, buildPreflightErrorMessage, 
+import { validateInputs, detectModeAndPaths, defaultBranchFrom, runCleanup, validateSpecCompleteness, 
 // WU-1805: Preflight code_paths validation before gates
 executePreflightCodePathValidation, buildPreflightCodePathErrorMessage, 
-// WU-2308: Pre-commit hooks with worktree context
-validateAllPreCommitHooks, 
 // WU-2310: Type vs code_paths preflight validation
 validateTypeVsCodePathsPreflight, buildTypeVsCodePathsErrorMessage, } from '@lumenflow/core/wu-done-validators';
 import { formatPreflightWarnings } from '@lumenflow/core/wu-preflight-validators';
 // WU-1825: validateCodePathsExist moved to unified code-path-validator
 import { validateCodePathsExist } from '@lumenflow/core/code-path-validator';
-import { BRANCHES, PATTERNS, DEFAULTS, LOG_PREFIX, EMOJI, GIT, SESSION, WU_STATUS, PKG_MANAGER, SCRIPTS, CLI_FLAGS, FILE_SYSTEM, EXIT_CODES, STRING_LITERALS, MICRO_WORKTREE_OPERATIONS, TELEMETRY_STEPS, SKIP_GATES_REASONS, CHECKPOINT_MESSAGES, ENV_VARS, getWUStatusDisplay, 
+import { BRANCHES, PATTERNS, DEFAULTS, LOG_PREFIX, EMOJI, GIT, SESSION, WU_STATUS, FILE_SYSTEM, EXIT_CODES, STRING_LITERALS, MICRO_WORKTREE_OPERATIONS, TELEMETRY_STEPS, ENV_VARS, getWUStatusDisplay, 
 // WU-1223: Location types for worktree detection
 CONTEXT_VALIDATION, } from '@lumenflow/core/wu-constants';
 import { getDocsOnlyPrefixes, DOCS_ONLY_ROOT_FILES } from '@lumenflow/core';
-import { printGateFailureBox, printStatusPreview } from '@lumenflow/core/wu-done-ui';
+import { printStatusPreview } from '@lumenflow/core/wu-done-ui';
 import { ensureOnMain } from '@lumenflow/core/wu-helpers';
 import { WU_PATHS } from '@lumenflow/core/wu-paths';
 import { getConfig, clearConfigCache } from '@lumenflow/core/config';
 import { writeWU, appendNote, parseYAML } from '@lumenflow/core/wu-yaml';
 import { PLACEHOLDER_SENTINEL, validateWU, validateDoneWU, validateApprovalGates, } from '@lumenflow/core/wu-schema';
-import { validateBacklogSync } from '@lumenflow/core/backlog-sync-validator';
-import { executeBranchOnlyCompletion, 
-// WU-1492: Import branch-pr completion path
-executeBranchPRCompletion, } from '@lumenflow/core/wu-done-branch-only';
-import { executeWorktreeCompletion, autoRebaseBranch } from '@lumenflow/core/wu-done-worktree';
-// WU-1746: Already-merged worktree resilience
-// WU-2248: Removed executeAlreadyMergedCompletion (wrote directly to local main).
-// Both code paths now use executeAlreadyMergedFinalizeFromModule (micro-worktree isolation).
-import { detectAlreadyMergedNoWorktree } from '@lumenflow/core/wu-done-merged-worktree';
+import { autoRebaseBranch } from '@lumenflow/core/wu-done-worktree';
 // WU-2211: --already-merged finalize-only mode
 import { verifyCodePathsOnMainHead, executeAlreadyMergedFinalize as executeAlreadyMergedFinalizeFromModule, } from './wu-done-already-merged.js';
+import { executeModeSpecificCompletion } from './wu-done-mode-execution.js';
 import { checkWUConsistency } from '@lumenflow/core/wu-consistency-checker';
 // WU-1542: Use blocking mode compliance check (replaces non-blocking checkMandatoryAgentsCompliance)
 import { checkMandatoryAgentsComplianceBlocking } from '@lumenflow/core/orchestration-rules';
 import { endSessionForWU, getCurrentSessionForWU } from '@lumenflow/agent/auto-session';
 import { runBackgroundProcessCheck } from '@lumenflow/core/process-detector';
 import { WUStateStore } from '@lumenflow/core/wu-state-store';
-// WU-1588: INIT-007 memory layer integration
-import { createCheckpoint } from '@lumenflow/memory/checkpoint';
-import { createSignal, loadSignals } from '@lumenflow/memory/signal';
 // WU-1763: Memory store for loading discoveries (lifecycle nudges)
-import { loadMemory, queryByWu } from '@lumenflow/memory/store';
-// WU-1943: Checkpoint warning helper
-import { hasSessionCheckpoints } from '@lumenflow/core/wu-done-worktree';
+import { loadMemory } from '@lumenflow/memory/store';
 // WU-1603: Atomic lane locking - release lock on WU completion
 import { releaseLaneLock } from '@lumenflow/core/lane-lock';
 // WU-1747: Checkpoint and lock for concurrent load resilience
-import { createPreGatesCheckpoint as createWU1747Checkpoint, markGatesPassed, canSkipGates, clearCheckpoint, } from '@lumenflow/core/wu-checkpoint';
+import { canSkipGates, clearCheckpoint } from '@lumenflow/core/wu-checkpoint';
 // WU-1946: Spawn registry for tracking sub-agent spawns
 import { DelegationRegistryStore } from '@lumenflow/core/delegation-registry-store';
 import { DelegationStatus } from '@lumenflow/core/delegation-registry-schema';
@@ -121,77 +107,15 @@ import { evaluateMainDirtyMutationGuard } from './hooks/dirty-guard.js';
 // WU-1474: Decay policy invocation during completion lifecycle
 import { runDecayOnDone } from './wu-done-decay.js';
 import { validateClaimSessionOwnership } from './wu-done-ownership.js';
+import { broadcastCompletionSignal, checkInboxForRecentSignals, createPreGatesCheckpoint, emitTelemetry, enforceCheckpointGateForDone, resolveCheckpointGateMode, } from './wu-done-memory-telemetry.js';
 import { enforceSpawnProvenanceForDone, enforceWuBriefEvidenceForDone, printExposureWarnings, validateAccessibilityOrDie, validateDocsOnlyFlag, } from './wu-done-policies.js';
 import { detectParallelCompletions, ensureNoAutoStagedOrNoop, runTripwireCheck, validateBranchOnlyMode, validateStagedFiles, } from './wu-done-git-ops.js';
 import { flushWuLifecycleSync } from './wu-lifecycle-sync/service.js';
 import { WU_LIFECYCLE_COMMANDS } from './wu-lifecycle-sync/constants.js';
 export { buildGatesCommand, buildMissingSpawnPickupEvidenceMessage, buildMissingSpawnProvenanceMessage, buildMissingWuBriefEvidenceMessage, enforceSpawnProvenanceForDone, enforceWuBriefEvidenceForDone, hasSpawnPickupEvidence, printExposureWarnings, shouldEnforceSpawnProvenance, shouldEnforceWuBriefEvidence, validateAccessibilityOrDie, validateDocsOnlyFlag, } from './wu-done-policies.js';
 export { isBranchAlreadyMerged } from './wu-done-git-ops.js';
-// WU-1588: Memory layer constants
-const MEMORY_SIGNAL_TYPES = {
-    WU_COMPLETION: 'wu_completion',
-};
-const MEMORY_CHECKPOINT_NOTES = {
-    PRE_GATES: 'Pre-gates checkpoint for recovery if gates fail',
-};
-const MEMORY_SIGNAL_WINDOW_MS = 60 * 60 * 1000; // 1 hour for recent signals
-export const CHECKPOINT_GATE_MODES = {
-    OFF: 'off',
-    WARN: 'warn',
-    BLOCK: 'block',
-};
-const CHECKPOINT_GATE_CONFIG = {
-    PATH: 'memory.enforcement.require_checkpoint_for_done',
-    COMMAND_PREFIX: 'pnpm mem:checkpoint --wu',
-    WARN_TAG: 'WU-1998',
-};
-function buildCheckpointGateBlockMessage(id) {
-    return (`${STRING_LITERALS.NEWLINE}${LOG_PREFIX.DONE} ${EMOJI.FAILURE} No checkpoints found for ${id} session.${STRING_LITERALS.NEWLINE}` +
-        `${LOG_PREFIX.DONE} ${CHECKPOINT_GATE_CONFIG.PATH} is set to '${CHECKPOINT_GATE_MODES.BLOCK}'.${STRING_LITERALS.NEWLINE}` +
-        `${LOG_PREFIX.DONE} Create a checkpoint before completing: ${CHECKPOINT_GATE_CONFIG.COMMAND_PREFIX} ${id}${STRING_LITERALS.NEWLINE}`);
-}
-function buildCheckpointGateWarnMessages(id) {
-    return [
-        `${STRING_LITERALS.NEWLINE}${LOG_PREFIX.DONE} ${EMOJI.INFO} ${CHECKPOINT_GATE_CONFIG.WARN_TAG}: No prior checkpoints recorded for ${id} in this session.`,
-        `${LOG_PREFIX.DONE} A pre-gates checkpoint will be created automatically by wu:done.`,
-        `${LOG_PREFIX.DONE} For earlier crash recovery, run '${CHECKPOINT_GATE_CONFIG.COMMAND_PREFIX} ${id}' after each acceptance criterion, before gates, or every 30 tool calls.${STRING_LITERALS.NEWLINE}`,
-    ];
-}
-export function resolveCheckpointGateMode(mode) {
-    if (mode === CHECKPOINT_GATE_MODES.OFF) {
-        return CHECKPOINT_GATE_MODES.OFF;
-    }
-    if (mode === CHECKPOINT_GATE_MODES.BLOCK) {
-        return CHECKPOINT_GATE_MODES.BLOCK;
-    }
-    return CHECKPOINT_GATE_MODES.WARN;
-}
-export async function enforceCheckpointGateForDone({ id, workspacePath, mode, queryByWuFn = queryByWu, hasSessionCheckpointsFn = hasSessionCheckpoints, log = console.log, blocker = (message) => {
-    die(message);
-}, }) {
-    if (mode === CHECKPOINT_GATE_MODES.OFF) {
-        return;
-    }
-    let wuNodes;
-    try {
-        wuNodes = await queryByWuFn(workspacePath, id);
-        if (hasSessionCheckpointsFn(id, wuNodes)) {
-            return;
-        }
-    }
-    catch {
-        // Fail-open: checkpoint discovery issues should not block wu:done.
-        return;
-    }
-    if (mode === CHECKPOINT_GATE_MODES.BLOCK) {
-        blocker(buildCheckpointGateBlockMessage(id));
-        return;
-    }
-    const warnMessages = buildCheckpointGateWarnMessages(id);
-    for (const message of warnMessages) {
-        log(message);
-    }
-}
+export { checkBacklogConsistencyForWU, computeBranchOnlyFallback, normalizeUsername, } from './wu-done-preflight.js';
+export { CHECKPOINT_GATE_MODES, enforceCheckpointGateForDone, resolveCheckpointGateMode, } from './wu-done-memory-telemetry.js';
 const WU_FILE_NAME_PATTERN = /^WU-\d+\.ya?ml$/;
 function normalizeRepoRelativePathForYaml(rawPath) {
     return rawPath.replaceAll('\\', '/').replace(/^\.\/+/, '');
@@ -364,91 +288,6 @@ async function _assertWorktreeWUInProgressInStateStore(id, worktreePath) {
             `Fix the claim/state log first, then rerun wu:done.`);
     }
 }
-/**
- * WU-1588: Create pre-gates checkpoint for recovery if gates fail.
- * Non-blocking wrapper around mem:checkpoint - failures logged as warnings.
- *
- * @param {string} id - WU ID
- * @param {string|null} worktreePath - Path to worktree
- * @param {string} baseDir - Base directory for memory layer
- * @returns {Promise<void>}
- */
-async function createPreGatesCheckpoint(id, worktreePath, baseDir = process.cwd()) {
-    try {
-        const result = await createCheckpoint(baseDir, {
-            note: MEMORY_CHECKPOINT_NOTES.PRE_GATES,
-            wuId: id,
-            progress: `Starting gates execution for ${id}`,
-            nextSteps: worktreePath
-                ? `Gates running in worktree: ${worktreePath}`
-                : 'Gates running in branch-only mode',
-            trigger: 'wu-done-pre-gates',
-        });
-        if (result.success) {
-            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Pre-gates checkpoint created (${result.checkpoint.id})`);
-        }
-    }
-    catch (err) {
-        // Non-blocking: checkpoint failure should not block wu:done
-        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not create pre-gates checkpoint: ${getErrorMessage(err)}`);
-    }
-}
-/**
- * WU-1588: Broadcast completion signal to parallel agents.
- * Non-blocking wrapper around mem:signal - failures logged as warnings.
- *
- * @param {string} id - WU ID
- * @param {string} title - WU title
- * @param {string} baseDir - Base directory for memory layer
- * @returns {Promise<void>}
- */
-async function broadcastCompletionSignal(id, title, baseDir = process.cwd()) {
-    try {
-        const result = await createSignal(baseDir, {
-            message: `${MEMORY_SIGNAL_TYPES.WU_COMPLETION}: ${id} - ${title}`,
-            wuId: id,
-        });
-        if (result.success) {
-            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Completion signal broadcast (${result.signal.id})`);
-        }
-    }
-    catch (err) {
-        // Non-blocking: signal failure should not block wu:done
-        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not broadcast completion signal: ${getErrorMessage(err)}`);
-    }
-}
-/**
- * WU-1588: Check inbox for recent signals from parallel agents.
- * Non-blocking wrapper around loadSignals - failures logged as warnings.
- *
- * @param {string} id - Current WU ID (for filtering)
- * @param {string} baseDir - Base directory for memory layer
- * @returns {Promise<void>}
- */
-async function checkInboxForRecentSignals(id, baseDir = process.cwd()) {
-    try {
-        const since = new Date(Date.now() - MEMORY_SIGNAL_WINDOW_MS);
-        const signals = await loadSignals(baseDir, { since, unreadOnly: true });
-        // Filter out signals for current WU
-        const relevantSignals = signals.filter((s) => s.wu_id !== id);
-        if (relevantSignals.length > 0) {
-            console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.INFO} Recent signals from parallel agents:`);
-            for (const signal of relevantSignals.slice(0, 5)) {
-                // Show at most 5
-                const timestamp = new Date(signal.created_at).toLocaleTimeString();
-                console.log(`  - [${timestamp}] ${signal.message}`);
-            }
-            if (relevantSignals.length > 5) {
-                console.log(`  ... and ${relevantSignals.length - 5} more`);
-            }
-            console.log(`  Run 'pnpm mem:inbox' for full list\n`);
-        }
-    }
-    catch (err) {
-        // Non-blocking: inbox check failure should not block wu:done
-        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not check inbox for signals: ${getErrorMessage(err)}`);
-    }
-}
 /**
  * WU-1946: Update spawn registry on WU completion.
  * Non-blocking wrapper - failures logged as warnings.
@@ -490,64 +329,10 @@ const GIT_CONFIG_USER_NAME = 'user.name';
 const GIT_CONFIG_USER_EMAIL = 'user.email';
 // Default fallback messages
 const DEFAULT_NO_REASON = '(no reason provided)';
-/**
- * WU-1234: Normalize username for ownership comparison
- * Extracts username from email address for comparison.
- * This allows tom@hellm.ai to match 'tom' assigned_to field.
- *
- * @param {string|null|undefined} value - Email address or username
- * @returns {string} Normalized username (lowercase)
- */
-export function normalizeUsername(value) {
-    if (!value)
-        return '';
-    const str = String(value).trim();
-    // Extract username from email: tom@hellm.ai -> tom
-    // WU-1281: Using string split instead of regex
-    const atIndex = str.indexOf('@');
-    const username = atIndex > 0 ? str.slice(0, atIndex) : str;
-    return username.toLowerCase();
-}
 // WU-1281: isDocsOnlyByPaths removed - use shouldSkipWebTests from path-classifiers.ts
 // The validators already use shouldSkipWebTests via detectDocsOnlyByPaths wrapper.
 // Keeping the export for backward compatibility but re-exporting the canonical function.
 export { shouldSkipWebTests as isDocsOnlyByPaths } from '@lumenflow/core/path-classifiers';
-/**
- * WU-1234: Pre-flight check for backlog state consistency
- * Fails fast if the WU appears in both Done and In Progress sections.
- *
- * @param {string} id - WU ID to check
- * @param {string} backlogPath - Path to backlog.md
- * @returns {{ valid: boolean, error: string|null }}
- */
-export function checkBacklogConsistencyForWU(id, backlogPath) {
-    try {
-        const result = validateBacklogSync(backlogPath);
-        // Check if this specific WU is in both Done and In Progress
-        if (!result.valid) {
-            for (const error of result.errors) {
-                // Check if the error mentions both Done and In Progress AND mentions our WU
-                if (error.includes('Done and In Progress') && error.includes(id)) {
-                    return {
-                        valid: false,
-                        error: `❌ BACKLOG STATE INCONSISTENCY: ${id} found in both Done and In Progress sections.\n\n` +
-                            `This is an invalid state that must be fixed manually before wu:done can proceed.\n\n` +
-                            `Fix options:\n` +
-                            `  1. If ${id} is truly done: Remove from In Progress in backlog.md\n` +
-                            `  2. If ${id} needs more work: Remove from Done in backlog.md, update WU YAML status\n\n` +
-                            `After fixing backlog.md, retry: pnpm wu:done --id ${id}`,
-                    };
-                }
-            }
-        }
-        return { valid: true, error: null };
-    }
-    catch (e) {
-        // If validation fails (e.g., file not found), warn but don't block
-        console.warn(`${LOG_PREFIX.DONE} Warning: Could not validate backlog consistency: ${getErrorMessage(e)}`);
-        return { valid: true, error: null };
-    }
-}
 /**
  * Read commitlint header-max-length from config, fallback to DEFAULTS.MAX_COMMIT_SUBJECT
  * WU-1281: Using centralized constant instead of hardcoded 100
@@ -565,14 +350,6 @@ function getCommitHeaderLimit() {
     }
 }
 // ensureOnMain() moved to wu-helpers.ts (WU-1256)
-export function emitTelemetry(event) {
-    const logPath = path.join('.lumenflow', 'flow.log');
-    const logDir = path.dirname(logPath);
-    if (!existsSync(logDir))
-        mkdirSync(logDir, { recursive: true });
-    const line = JSON.stringify({ timestamp: new Date().toISOString(), ...event });
-    appendFileSync(logPath, `${line}\n`, { encoding: FILE_SYSTEM.UTF8 });
-}
 async function auditSkipGates(id, reason, fixWU, worktreePath) {
     const auditBaseDir = worktreePath || process.cwd();
     const auditPath = path.join(auditBaseDir, '.lumenflow', 'skip-gates-audit.log');
@@ -626,117 +403,6 @@ async function auditSkipCosGates(id, reason, worktreePath) {
 }
 // WU-2308: validateAllPreCommitHooks moved to wu-done-validators.ts
 // Now accepts worktreePath parameter to run audit from worktree context
-/**
- * Check if node_modules in worktree may be stale
- * Detects when package.json differs between main and worktree, which indicates
- * dependencies were added/removed but pnpm install may not have run in worktree.
- * This prevents confusing typecheck failures due to missing dependencies.
- * @param {string} worktreePath - Path to worktree
- */
-function checkNodeModulesStaleness(worktreePath) {
-    try {
-        const mainPackageJson = path.resolve('package.json');
-        const worktreePackageJson = path.resolve(worktreePath, 'package.json');
-        if (!existsSync(mainPackageJson) || !existsSync(worktreePackageJson)) {
-            // No package.json to compare
-            return;
-        }
-        const mainContent = readFileSync(mainPackageJson, {
-            encoding: FILE_SYSTEM.UTF8,
-        });
-        const worktreeContent = readFileSync(worktreePackageJson, {
-            encoding: FILE_SYSTEM.UTF8,
-        });
-        // Compare package.json files
-        if (mainContent !== worktreeContent) {
-            const worktreeNodeModules = path.resolve(worktreePath, 'node_modules');
-            // Check if node_modules exists and when it was last modified
-            if (existsSync(worktreeNodeModules)) {
-                const nodeModulesStat = statSync(worktreeNodeModules);
-                const packageJsonStat = statSync(worktreePackageJson);
-                // If package.json is newer than node_modules, dependencies may be stale
-                if (packageJsonStat.mtimeMs > nodeModulesStat.mtimeMs) {
-                    console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} WARNING: Potentially stale node_modules detected\n\n` +
-                        `  package.json in worktree differs from main checkout\n` +
-                        `  node_modules was last modified: ${nodeModulesStat.mtime.toISOString()}\n` +
-                        `  package.json was last modified: ${packageJsonStat.mtime.toISOString()}\n\n` +
-                        `  If gates fail with missing dependencies/types, run:\n` +
-                        `    cd ${worktreePath}\n` +
-                        `    pnpm install\n` +
-                        `    cd -\n` +
-                        `    pnpm wu:done --id <WU-ID>\n`);
-                }
-            }
-            else {
-                // node_modules doesn't exist at all
-                console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} WARNING: node_modules missing in worktree\n\n` +
-                    `  package.json in worktree differs from main checkout\n` +
-                    `  but node_modules directory does not exist\n\n` +
-                    `  If gates fail with missing dependencies/types, run:\n` +
-                    `    cd ${worktreePath}\n` +
-                    `    pnpm install\n` +
-                    `    cd -\n` +
-                    `    pnpm wu:done --id <WU-ID>\n`);
-            }
-        }
-    }
-    catch (e) {
-        // Non-critical check - just warn if it fails
-        console.warn(`${LOG_PREFIX.DONE} Could not check node_modules staleness: ${getErrorMessage(e)}`);
-    }
-}
-/**
- * Run gates in worktree
- * @param {string} worktreePath - Path to worktree
- * @param {string} id - WU ID
- * @param {object} options - Gates options
- * @param {boolean} options.isDocsOnly - Auto-detected docs-only from code_paths
- * @param {boolean} options.docsOnly - Explicit --docs-only flag from CLI
- */
-async function runGatesInWorktree(worktreePath, id, options = {}) {
-    const { isDocsOnly = false, docsOnly = false, scopedTestPaths } = options;
-    console.log(`\n${LOG_PREFIX.DONE} Running gates in worktree: ${worktreePath}`);
-    // Check for stale node_modules before running gates (prevents confusing failures)
-    checkNodeModulesStaleness(worktreePath);
-    // WU-1012: Use docs-only gates if explicit --docs-only flag OR auto-detected
-    const useDocsOnlyGates = docsOnly || isDocsOnly;
-    if (useDocsOnlyGates) {
-        console.log(`${LOG_PREFIX.DONE} Using docs-only gates (skipping lint/typecheck/tests)`);
-        if (docsOnly) {
-            console.log(`${LOG_PREFIX.DONE} (explicit --docs-only flag)`);
-        }
-    }
-    const startTime = Date.now();
-    try {
-        const ok = Boolean(await runGates({
-            cwd: worktreePath,
-            docsOnly: useDocsOnlyGates,
-            coverageMode: undefined,
-            scopedTestPaths,
-        }));
-        if (!ok) {
-            throw createError(ErrorCodes.GATES_FAILED, 'Gates failed');
-        }
-        const duration = Date.now() - startTime;
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Gates passed in ${prettyMs(duration)}`);
-        emitTelemetry({ script: 'wu-done', wu_id: id, step: 'gates', ok: true, duration_ms: duration });
-        return true;
-    }
-    catch {
-        const duration = Date.now() - startTime;
-        emitTelemetry({
-            script: 'wu-done',
-            wu_id: id,
-            step: 'gates',
-            ok: false,
-            duration_ms: duration,
-        });
-        // WU-1280: Prominent error summary box (visible after ~130k chars of gate output)
-        // WU-1281: Extracted to helper using pretty-ms for duration formatting
-        printGateFailureBox({ id, location: worktreePath, durationMs: duration, isWorktreeMode: true });
-        die(`Gates failed in ${worktreePath}. Fix issues in the worktree and try again.`);
-    }
-}
 // Note: updateStatusRemoveInProgress, addToStatusCompleted, and moveWUToDoneBacklog
 // have been extracted to tools/lib/wu-status-updater.ts and imported above (WU-1163)
 //
@@ -955,155 +621,6 @@ function runWUValidator(doc, id, allowTodo = false, worktreePath = null) {
     }
     console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} WU validator passed`);
 }
-/**
- * GUARDRAIL 2: Enforce ownership semantics in wu:done
- *
- * Validates that the current user owns the WU before allowing completion.
- * Prevents agents/humans from finishing WUs they do not own.
- *
- * @param {string} id - WU ID
- * @param {object} doc - WU YAML document
- * @param {string|null} worktreePath - Expected worktree path
- * @param {boolean} overrideOwner - Override flag (requires reason)
- * @param {string|null} overrideReason - Reason for override
- * @returns {{valid: boolean, error: string|null, auditEntry: object|null}}
- */
-async function appendClaimSessionOverrideAuditEvent({ wuId, claimedSessionId, activeSessionId, reason, worktreePath, }) {
-    const stateDir = resolveStateDir(worktreePath);
-    const stateStore = new WUStateStore(stateDir);
-    await stateStore.load();
-    await stateStore.checkpoint(wuId, `[wu:done] force ownership override claimed_session=${claimedSessionId} active_session=${activeSessionId || 'none'}`, {
-        progress: 'wu:done ownership override',
-        nextSteps: reason,
-    });
-}
-async function checkOwnership(id, doc, worktreePath, overrideOwner = false, overrideReason = null) {
-    // Missing worktree means WU was not claimed properly (unless escape hatch applies)
-    if (!worktreePath || !existsSync(worktreePath)) {
-        return {
-            valid: false,
-            error: `Missing worktree for ${id}.\n\n` +
-                `Expected worktree at: ${worktreePath || 'unknown'}\n\n` +
-                `Worktrees are required for proper WU completion in Worktree mode.\n` +
-                `If the worktree was removed, recreate it and retry, or use --skip-gates with justification.`,
-            auditEntry: null,
-        };
-    }
-    // Get assigned owner from WU YAML - read directly from worktree to ensure we get the lane branch version
-    let assignedTo = doc.assigned_to || null;
-    if (!assignedTo && worktreePath) {
-        // Fallback: Read directly from worktree YAML if not present in doc (fixes WU-1106)
-        const wtWUPath = path.join(worktreePath, WU_PATHS.WU(id));
-        if (existsSync(wtWUPath)) {
-            try {
-                const text = readFileSync(wtWUPath, { encoding: FILE_SYSTEM.UTF8 });
-                const wtDoc = parseYAML(text);
-                assignedTo = wtDoc?.assigned_to || null;
-                if (assignedTo) {
-                    console.log(`${LOG_PREFIX.DONE} Note: Read assigned_to from worktree YAML (not found in main)`);
-                }
-            }
-            catch (err) {
-                console.warn(`${LOG_PREFIX.DONE} Warning: Failed to read assigned_to from worktree: ${getErrorMessage(err)}`);
-            }
-        }
-    }
-    if (!assignedTo) {
-        return {
-            valid: false,
-            error: `WU ${id} has no assigned_to field.\n\n` +
-                `This WU was claimed before ownership tracking was implemented.\n` +
-                `To complete this WU:\n` +
-                `  1. Add assigned_to: <your-email> to ${id}.yaml\n` +
-                `  2. Commit the change\n` +
-                `  3. Re-run: pnpm wu:done --id ${id}`,
-            auditEntry: null,
-        };
-    }
-    // Get current user identity
-    let currentUser;
-    try {
-        currentUser = (await getGitForCwd().getConfigValue(GIT_CONFIG_USER_EMAIL)).trim();
-    }
-    catch {
-        // Fallback to environment variable
-        currentUser = process.env.GIT_USER || process.env.USER || null;
-    }
-    if (!currentUser) {
-        return {
-            valid: false,
-            error: `Cannot determine current user identity.\n\n` +
-                `Set git user.email or GIT_USER environment variable.`,
-            auditEntry: null,
-        };
-    }
-    // WU-1234: Normalize usernames for comparison (allows email vs username match)
-    // e.g., tom@hellm.ai matches 'tom' assigned_to field
-    const normalizedAssigned = normalizeUsername(assignedTo);
-    const normalizedCurrent = normalizeUsername(currentUser);
-    const isOwner = normalizedAssigned === normalizedCurrent;
-    if (isOwner) {
-        // Owner is completing their own WU - allow
-        if (assignedTo !== currentUser) {
-            console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Ownership match via normalization: "${assignedTo}" == "${currentUser}"`);
-        }
-        return { valid: true, error: null, auditEntry: null };
-    }
-    // Not the owner - check for override
-    if (overrideOwner) {
-        if (!overrideReason) {
-            return {
-                valid: false,
-                error: `--override-owner requires --reason "<why you're completing someone else's WU>"`,
-                auditEntry: null,
-            };
-        }
-        // Create audit entry
-        const auditEntry = {
-            timestamp: new Date().toISOString(),
-            wu_id: id,
-            assigned_to: assignedTo,
-            completed_by: currentUser,
-            reason: overrideReason,
-            git_commit: (await getGitForCwd().getCommitHash()).trim(),
-        };
-        console.log(`\n⚠️  --override-owner: Completing WU assigned to someone else`);
-        console.log(`   Assigned to: ${assignedTo}`);
-        console.log(`   Completed by: ${currentUser}`);
-        console.log(`   Reason: ${overrideReason}\n`);
-        return { valid: true, error: null, auditEntry };
-    }
-    // Not the owner and no override - block
-    return {
-        valid: false,
-        error: `\n❌ OWNERSHIP VIOLATION: ${id} is assigned to someone else\n\n` +
-            `   Assigned to: ${assignedTo}\n` +
-            `   Current user: ${currentUser}\n\n` +
-            `   You cannot complete WUs you do not own.\n\n` +
-            `   📋 Options:\n` +
-            `      1. Contact ${assignedTo} to complete the WU\n` +
-            `      2. Reassign the WU to yourself in ${id}.yaml (requires approval)\n` +
-            `      3. Add co_assigned field for pairing (requires approval)\n\n` +
-            `   ⚠️  To override (use with extreme caution):\n` +
-            `      pnpm wu:done --id ${id} --override-owner --reason "<why>"\n\n` +
-            `   AGENTS: NEVER use --override-owner without explicit instruction.\n` +
-            `   Language protocol: "pick up WU-${id.replace('WU-', '')}" = READ ONLY.\n`,
-        auditEntry: null,
-    };
-}
-/**
- * Log ownership override to audit trail
- * @param {object} auditEntry - Audit entry to log
- */
-function auditOwnershipOverride(auditEntry) {
-    const auditPath = path.join('.lumenflow', 'ownership-override-audit.log');
-    const auditDir = path.dirname(auditPath);
-    if (!existsSync(auditDir))
-        mkdirSync(auditDir, { recursive: true });
-    const line = JSON.stringify(auditEntry);
-    appendFileSync(auditPath, `${line}\n`, { encoding: FILE_SYSTEM.UTF8 });
-    console.log(`${LOG_PREFIX.DONE} ${EMOJI.MEMO} Ownership override logged to ${auditPath}`);
-}
 /**
  * Execute pre-flight checks before gates
  * Extracted from main() to reduce complexity (WU-1215 Phase 2 Extraction #3)
@@ -1431,222 +948,6 @@ async function executePreFlightChecks({ id, args, isBranchOnly, isDocsOnly, docM
     }
     return { title, docForValidation };
 }
-async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath, branchName, scopedTestPaths, }) {
-    const gateResult = {
-        fullGatesRanInCurrentRun: false,
-        skippedByCheckpoint: false,
-        checkpointId: null,
-    };
-    // WU-1747: Check if gates can be skipped based on valid checkpoint
-    // This allows resuming wu:done without re-running gates if nothing changed
-    // WU-2102: Look for checkpoint in worktree (where wu:prep writes it)
-    const skipResult = canSkipGates(id, {
-        currentHeadSha: undefined,
-        baseDir: worktreePath || undefined,
-    });
-    if (skipResult.canSkip) {
-        gateResult.skippedByCheckpoint = true;
-        gateResult.checkpointId = skipResult.checkpoint.checkpointId;
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} ${CHECKPOINT_MESSAGES.SKIPPING_GATES_VALID}`);
-        console.log(`${LOG_PREFIX.DONE} ${CHECKPOINT_MESSAGES.CHECKPOINT_LABEL}: ${skipResult.checkpoint.checkpointId}`);
-        console.log(`${LOG_PREFIX.DONE} ${CHECKPOINT_MESSAGES.GATES_PASSED_AT}: ${skipResult.checkpoint.gatesPassedAt}`);
-        emitTelemetry({
-            script: TELEMETRY_STEPS.GATES,
-            wu_id: id,
-            step: TELEMETRY_STEPS.GATES,
-            skipped: true,
-            reason: SKIP_GATES_REASONS.CHECKPOINT_VALID,
-            checkpoint_id: skipResult.checkpoint.checkpointId,
-        });
-        return gateResult; // Skip gates entirely
-    }
-    // WU-1747: Create checkpoint before gates for resumption on failure
-    if (worktreePath && branchName) {
-        try {
-            await createWU1747Checkpoint({ wuId: id, worktreePath, branchName }, { gatesPassed: false });
-        }
-        catch (err) {
-            // Non-blocking: checkpoint failure should not block wu:done
-            console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} ${CHECKPOINT_MESSAGES.COULD_NOT_CREATE}: ${getErrorMessage(err)}`);
-        }
-    }
-    // WU-1588: Create pre-gates checkpoint for recovery if gates fail
-    // Non-blocking: failures handled internally by createPreGatesCheckpoint
-    // WU-1749 Bug 5: Pass worktreePath as baseDir to write to worktree's wu-events.jsonl, not main's
-    await createPreGatesCheckpoint(id, worktreePath, worktreePath || process.cwd());
-    // P0 EMERGENCY FIX: Restore wu-events.jsonl after checkpoint creation
-    // WU-1748 added checkpoint persistence to wu-events.jsonl but doesn't commit it,
-    // leaving unstaged changes that cause "git rebase" to fail with "You have unstaged changes"
-    // This restores the file to HEAD state - checkpoint data is preserved in memory store
-    if (worktreePath) {
-        try {
-            execSync(`git -C "${worktreePath}" restore "${resolveWuEventsRelativePath(worktreePath)}"`);
-        }
-        catch {
-            // Non-fatal: file might not exist or already clean
-        }
-    }
-    // Step 0a: Run invariants check (WU-2252: NON-BYPASSABLE, runs even with --skip-gates)
-    // This ensures repo invariants are never violated, regardless of skip-gates flag
-    // WU-2253: Run against worktreePath (when present) to catch violations that only exist in the worktree
-    // WU-2425: Pass wuId to scope WU-specific invariants to just the completing WU
-    const invariantsBaseDir = worktreePath || process.cwd();
-    console.log(`\n${LOG_PREFIX.DONE} Running invariants check (non-bypassable)...`);
-    console.log(`${LOG_PREFIX.DONE} Checking invariants in: ${invariantsBaseDir}`);
-    const { runInvariants } = await import('@lumenflow/core/invariants-runner');
-    const invariantsResult = runInvariants({ baseDir: invariantsBaseDir, silent: false, wuId: id });
-    if (!invariantsResult.success) {
-        emitTelemetry({
-            script: 'wu-done',
-            wu_id: id,
-            step: 'invariants',
-            ok: false,
-        });
-        die(`Invariants check failed. Fix violations before completing WU.\n\n${invariantsResult.formatted}`);
-    }
-    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Invariants check passed`);
-    emitTelemetry({
-        script: 'wu-done',
-        wu_id: id,
-        step: 'invariants',
-        ok: true,
-    });
-    // Step 0b: Run gates BEFORE merge (or skip with audit trail)
-    if (args.skipGates) {
-        console.log(`\n${EMOJI.WARNING}  ${EMOJI.WARNING}  ${EMOJI.WARNING}  SKIP-GATES MODE ACTIVE ${EMOJI.WARNING}  ${EMOJI.WARNING}  ${EMOJI.WARNING}\n`);
-        console.log(`${LOG_PREFIX.DONE} Skipping gates check as requested`);
-        console.log(`${LOG_PREFIX.DONE} Reason: ${args.reason}`);
-        console.log(`${LOG_PREFIX.DONE} Fix WU: ${args.fixWu}`);
-        console.log(`${LOG_PREFIX.DONE} Worktree: ${worktreePath || 'Branch-Only mode (no worktree)'}`);
-        await auditSkipGates(id, args.reason, args.fixWu, worktreePath);
-        console.log('\n⚠️  Ensure test failures are truly pre-existing!\n');
-        emitTelemetry({
-            script: 'wu-done',
-            wu_id: id,
-            step: 'gates',
-            skipped: true,
-            reason: args.reason,
-            fix_wu: args.fixWu,
-        });
-    }
-    else if (isBranchOnly) {
-        // Branch-Only mode: run gates in-place (current directory on lane branch)
-        console.log(`\n${LOG_PREFIX.DONE} Running gates in Branch-Only mode (in-place on lane branch)`);
-        // WU-1012: Use docs-only gates if explicit --docs-only flag OR auto-detected
-        const useDocsOnlyGates = Boolean(args.docsOnly) || Boolean(isDocsOnly);
-        if (useDocsOnlyGates) {
-            console.log(`${LOG_PREFIX.DONE} Using docs-only gates (skipping lint/typecheck/tests)`);
-            if (args.docsOnly) {
-                console.log(`${LOG_PREFIX.DONE} (explicit --docs-only flag)`);
-            }
-        }
-        const startTime = Date.now();
-        try {
-            const ok = Boolean(await runGates({ docsOnly: useDocsOnlyGates }));
-            if (!ok) {
-                throw createError(ErrorCodes.GATES_FAILED, 'Gates failed');
-            }
-            const duration = Date.now() - startTime;
-            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Gates passed in ${prettyMs(duration)}`);
-            emitTelemetry({
-                script: 'wu-done',
-                wu_id: id,
-                step: 'gates',
-                ok: true,
-                duration_ms: duration,
-            });
-        }
-        catch {
-            const duration = Date.now() - startTime;
-            emitTelemetry({
-                script: 'wu-done',
-                wu_id: id,
-                step: 'gates',
-                ok: false,
-                duration_ms: duration,
-            });
-            // WU-1280: Prominent error summary box (Branch-Only mode)
-            // WU-1281: Extracted to helper using pretty-ms for duration formatting
-            printGateFailureBox({
-                id,
-                location: 'Branch-Only',
-                durationMs: duration,
-                isWorktreeMode: false,
-            });
-            die(`Gates failed in Branch-Only mode. Fix issues and try again.`);
-        }
-        gateResult.fullGatesRanInCurrentRun = true;
-    }
-    else if (worktreePath && existsSync(worktreePath)) {
-        // Worktree mode: run gates in the dedicated worktree
-        // WU-1012: Pass both auto-detected and explicit docs-only flags
-        // WU-2102: Forward scopedTestPaths so wu:done uses scoped tests when no checkpoint skip
-        await runGatesInWorktree(worktreePath, id, {
-            isDocsOnly,
-            docsOnly: Boolean(args.docsOnly),
-            scopedTestPaths,
-        });
-        gateResult.fullGatesRanInCurrentRun = true;
-    }
-    else {
-        die(`Worktree not found (${worktreePath || 'unknown'}). Gates must run in the lane worktree.\n` +
-            `If the worktree was removed, recreate it and retry, or rerun with --branch-only when the lane branch exists.\n` +
-            `Use --skip-gates only with justification.`);
-    }
-    // Step 0.75: Run COS governance gates (WU-614, COS v1.3 §7)
-    if (!args.skipCosGates) {
-        console.log(`\n${LOG_PREFIX.DONE} Running COS governance gates...`);
-        const startTime = Date.now();
-        try {
-            execSync(`${PKG_MANAGER} ${SCRIPTS.COS_GATES} ${CLI_FLAGS.WU} ${id}`, {
-                stdio: 'inherit',
-            });
-            const duration = Date.now() - startTime;
-            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} COS gates passed in ${prettyMs(duration)}`);
-            emitTelemetry({
-                script: 'wu-done',
-                wu_id: id,
-                step: 'cos-gates',
-                ok: true,
-                duration_ms: duration,
-            });
-        }
-        catch {
-            const duration = Date.now() - startTime;
-            emitTelemetry({
-                script: 'wu-done',
-                wu_id: id,
-                step: 'cos-gates',
-                ok: false,
-                duration_ms: duration,
-            });
-            console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} COS governance gates failed`);
-            console.error('\nTo fix:');
-            console.error('  1. Add required evidence to governance.evidence field in WU YAML');
-            console.error('  2. See: https://lumenflow.dev/reference/evidence-format/');
-            console.error('\nEmergency bypass (creates audit trail):');
-            // WU-1852: Reference --skip-gates (the actual CLI flag), not the non-existent --skip-cos-gates
-            console.error(`  pnpm wu:done --id ${id} --skip-gates --reason "COS evidence pending" --fix-wu WU-XXXX`);
-            die('Abort: WU not completed. Fix governance evidence and retry pnpm wu:done.');
-        }
-    }
-    else {
-        console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} Skipping COS governance gates as requested`);
-        console.log(`${LOG_PREFIX.DONE} Reason: ${args.reason || DEFAULT_NO_REASON}`);
-        await auditSkipCosGates(id, args.reason, worktreePath);
-        emitTelemetry({
-            script: 'wu-done',
-            wu_id: id,
-            step: 'cos-gates',
-            skipped: true,
-            reason: args.reason,
-        });
-    }
-    // WU-1747: Mark checkpoint as gates passed for resumption on failure
-    // This allows subsequent wu:done attempts to skip gates if nothing changed
-    markGatesPassed(id, { baseDir: worktreePath || undefined });
-    return gateResult;
-}
 /**
  * Print State HUD for visibility
  * Extracted from main() to reduce complexity (WU-1215 Phase 2 Extraction #4)
@@ -1658,13 +959,6 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
  * @param {string|null} params.derivedWorktree - Derived worktree path
  * @param {string} params.STAMPS_DIR - Stamps directory path
  */
-export function computeBranchOnlyFallback({ isBranchOnly, branchOnlyRequested, worktreeExists, derivedWorktree, }) {
-    const allowFallback = Boolean(branchOnlyRequested) && !isBranchOnly && !worktreeExists && Boolean(derivedWorktree);
-    return {
-        allowFallback,
-        effectiveBranchOnly: isBranchOnly || allowFallback,
-    };
-}
 export function getYamlStatusForDisplay(status) {
     return getWUStatusDisplay(status);
 }
@@ -1896,6 +1190,11 @@ export async function main() {
             isDocsOnly,
             worktreePath,
             scopedTestPaths: scopedTestPathsForDone,
+        }, {
+            auditSkipGates,
+            auditSkipCosGates,
+            createPreGatesCheckpoint,
+            emitTelemetry,
         });
     }
     catch (gateErr) {
@@ -1923,183 +1222,44 @@ export async function main() {
         derivedWorktree: effectiveDerivedWorktree,
         STAMPS_DIR,
     });
-    // Step 0.5: Pre-flight hook validation policy.
-    // WU-1659: Reuse Step 0 gate attestation/checkpoint and avoid duplicate full-suite execution.
-    const preCommitGateDecision = resolveWuDonePreCommitGateDecision({
+    // Step 0.5 + 0.6: Pre-flight staged validation policy and tasks:validate guard.
+    await runWuDoneStagedValidation({
+        id,
+        worktreePath,
+        gateResult: {
+            fullGatesRanInCurrentRun: gateExecutionResult.fullGatesRanInCurrentRun,
+            skippedByCheckpoint: gateExecutionResult.skippedByCheckpoint,
+            checkpointId: gateExecutionResult.checkpointId,
+        },
         skipGates: Boolean(args.skipGates),
-        fullGatesRanInCurrentRun: gateExecutionResult.fullGatesRanInCurrentRun,
-        skippedByCheckpoint: gateExecutionResult.skippedByCheckpoint,
-        checkpointId: gateExecutionResult.checkpointId,
+        runGatesFn: ({ cwd }) => runGates({ cwd, docsOnly: false }),
     });
-    console.log(`${LOG_PREFIX.DONE} ${preCommitGateDecision.message}`);
-    // Fallback path remains available if gate attestation is missing for any reason.
-    if (preCommitGateDecision.runPreCommitFullSuite) {
-        const hookResult = await validateAllPreCommitHooks(id, worktreePath, {
-            runGates: ({ cwd }) => runGates({ cwd, docsOnly: false }),
-        });
-        if (!hookResult.valid) {
-            die('Pre-flight validation failed. Fix hook issues and try again.');
-        }
-    }
-    // Step 0.6: WU-1781 - Run tasks:validate preflight BEFORE any merge/push operations
-    // This prevents deadlocks where validation fails after merge, leaving local main ahead of origin
-    // Specifically catches stamp-status mismatches from legacy WUs that would block pre-push hooks
-    const tasksValidationResult = runPreflightTasksValidation(id);
-    if (!tasksValidationResult.valid) {
-        const errorMessage = buildPreflightErrorMessage(id, tasksValidationResult.errors);
-        console.error(errorMessage);
-        die('Preflight tasks:validate failed. See errors above for fix options.');
-    }
-    // Step 1: Execute mode-specific completion workflow (WU-1215: extracted to mode modules)
-    // Worktree mode: Update metadata in worktree → commit → merge to main
-    // Branch-Only mode: Merge to main → update metadata on main → commit
-    // WU-1811: Track cleanupSafe flag to conditionally skip worktree removal on failure
-    let completionResult = { cleanupSafe: true }; // Default to safe for no-auto mode
+    // Step 1: Execute mode-specific completion workflow (WU-2167)
+    // Main remains orchestration-only; execution details live in wu-done-mode-execution.ts.
+    let completionResult = { cleanupSafe: true };
     if (!args.noAuto) {
-        // Build context for mode-specific execution
-        // WU-1369: Worktree mode uses atomic transaction pattern (no recordTransactionState/rollbackTransaction)
-        // Branch-only mode still uses the old rollback mechanism
-        const baseContext = {
+        completionResult = await executeModeSpecificCompletion({
             id,
             args,
             docMain,
             title,
             isDocsOnly,
             maxCommitLength: getCommitHeaderLimit(),
+            isBranchPR,
+            effectiveBranchOnly,
+            worktreePath,
+            resolvedWorktreePath,
+            pipelineActor: {
+                send: (event) => pipelineActor.send(event),
+                stop: () => pipelineActor.stop(),
+                getSnapshot: () => pipelineActor.getSnapshot(),
+            },
             validateStagedFiles,
-        };
-        try {
-            if (isBranchPR) {
-                // WU-1492: Branch-PR mode: commit metadata on lane branch, push, create PR
-                // Never checks out or merges to main
-                const laneBranch = defaultBranchFrom(docMain);
-                const branchPRContext = {
-                    ...baseContext,
-                    laneBranch,
-                };
-                completionResult = await executeBranchPRCompletion(branchPRContext);
-            }
-            else if (effectiveBranchOnly) {
-                // Branch-Only mode: merge first, then update metadata on main
-                // NOTE: Branch-only still uses old rollback mechanism
-                const branchOnlyContext = {
-                    ...baseContext,
-                    recordTransactionState,
-                    rollbackTransaction,
-                };
-                completionResult = await executeBranchOnlyCompletion(branchOnlyContext);
-            }
-            else {
-                // Worktree mode: update in worktree, commit, then merge or create PR
-                // WU-1369: Uses atomic transaction pattern
-                // WU-1541: Create worktree-aware validateStagedFiles to avoid process.chdir dependency
-                if (!worktreePath) {
-                    // WU-1746: Before dying, check if branch is already merged to main
-                    // This handles the case where worktree was manually deleted after branch was merged
-                    const laneBranch = defaultBranchFrom(docMain);
-                    const mergedDetection = await detectAlreadyMergedNoWorktree({
-                        wuId: id,
-                        laneBranch: laneBranch || '',
-                        worktreePath: resolvedWorktreePath,
-                    });
-                    if (mergedDetection.merged && !mergedDetection.worktreeExists) {
-                        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} WU-1746: Worktree missing but branch already merged to main`);
-                        // WU-2248: Use micro-worktree isolation (same as --already-merged flag path)
-                        // Previously called executeAlreadyMergedCompletion which wrote directly to local main.
-                        const mergedTitle = title || String(docMain.title || id);
-                        const mergedResult = await executeAlreadyMergedFinalizeFromModule({
-                            id,
-                            title: mergedTitle,
-                            lane: String(docMain.lane || ''),
-                            doc: docMain,
-                        });
-                        completionResult = {
-                            success: mergedResult.success,
-                            committed: true,
-                            pushed: true,
-                            merged: true,
-                            cleanupSafe: true,
-                        };
-                    }
-                    else {
-                        die(`Missing worktree path for ${id} completion in worktree mode`);
-                    }
-                }
-                else {
-                    const worktreeGitForValidation = createGitForPath(worktreePath);
-                    const worktreeContext = {
-                        ...baseContext,
-                        worktreePath,
-                        validateStagedFiles: (wuId, docsOnly, options) => validateStagedFiles(wuId, docsOnly, worktreeGitForValidation, options),
-                    };
-                    completionResult = await executeWorktreeCompletion(worktreeContext);
-                }
-            }
-            // WU-1663: Mode-specific completion succeeded - send pipeline events.
-            // The completion modules handle commit, merge, and push internally.
-            // We send the corresponding pipeline events based on the completion result.
-            pipelineActor.send({ type: WU_DONE_EVENTS.COMMIT_COMPLETE });
-            pipelineActor.send({ type: WU_DONE_EVENTS.MERGE_COMPLETE });
-            pipelineActor.send({ type: WU_DONE_EVENTS.PUSH_COMPLETE });
-            // Handle recovery mode (zombie state cleanup completed)
-            if ('recovered' in completionResult && completionResult.recovered) {
-                // P0 FIX: Release lane lock before early exit
-                try {
-                    const lane = docMain.lane;
-                    if (lane)
-                        releaseLaneLock(lane, { wuId: id });
-                }
-                catch {
-                    // Intentionally ignore lock release errors during cleanup
-                }
-                pipelineActor.stop();
-                process.exit(EXIT_CODES.SUCCESS);
-            }
-        }
-        catch (err) {
-            // WU-1663: Mode execution failed - determine which stage failed
-            // based on completion result flags and send appropriate failure event.
-            const failureStage = completionResult.committed === false
-                ? WU_DONE_EVENTS.COMMIT_FAILED
-                : completionResult.merged === false
-                    ? WU_DONE_EVENTS.MERGE_FAILED
-                    : completionResult.pushed === false
-                        ? WU_DONE_EVENTS.PUSH_FAILED
-                        : WU_DONE_EVENTS.COMMIT_FAILED; // Default to commit as earliest possible failure
-            pipelineActor.send({
-                type: failureStage,
-                error: getErrorMessage(err),
-            });
-            // WU-1663: Log pipeline state for diagnostics
-            const failedSnapshot = pipelineActor.getSnapshot();
-            console.error(`${LOG_PREFIX.DONE} Pipeline state: ${failedSnapshot.value} (failedAt: ${failedSnapshot.context.failedAt})`);
-            pipelineActor.stop();
-            // P0 FIX: Release lane lock before error exit
-            try {
-                const lane = docMain.lane;
-                if (lane)
-                    releaseLaneLock(lane, { wuId: id });
-            }
-            catch {
-                // Intentionally ignore lock release errors during error handling
-            }
-            console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Mode execution failed: ${getErrorMessage(err)}`);
-            console.error(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Next step: resolve the reported error and retry: pnpm wu:done --id ${id}`);
-            // WU-1811: Check if cleanup is safe before removing worktree
-            // If cleanupSafe is false (or undefined), preserve worktree for recovery
-            const cleanupSafe = typeof err === 'object' &&
-                err !== null &&
-                'cleanupSafe' in err &&
-                typeof err.cleanupSafe === 'boolean'
-                ? err.cleanupSafe
-                : undefined;
-            if (cleanupSafe === false) {
-                console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-1811: Worktree preserved - rerun wu:done to recover`);
-            }
-            // Mode modules handle rollback internally, we just need to exit
-            // Exit code 1 = recoverable (rebase/fix and retry)
-            process.exit(EXIT_CODES.ERROR);
-        }
+            defaultBranchFrom: (doc) => defaultBranchFrom(doc),
+            executeAlreadyMergedFinalize: executeAlreadyMergedFinalizeFromModule,
+            recordTransactionState,
+            rollbackTransaction,
+        });
     }
     else {
         await ensureNoAutoStagedOrNoop([WU_PATH, STATUS_PATH, BACKLOG_PATH, STAMPS_DIR]);