@lumenflow/cli 1.0.0

package/dist/wu-done.js

@@ -0,0 +1,2096 @@
+#!/usr/bin/env node
+/**
+ * WU Done Helper
+ *
+ * Canonical sequence (Worktree mode - DEFAULT):
+ * 1) Run gates in lane worktree (validates the change, not just main)
+ * 2) Pre-flight validation: run ALL pre-commit hooks before merge (prevents partial completion)
+ * 3) cd into worktree
+ * 4) Auto-update WU YAML/backlog/status to Done in worktree (unless --no-auto)
+ * 5) Create `.beacon/stamps/WU-{id}.done` in worktree
+ * 6) Validate staged files against whitelist
+ * 7) Commit metadata changes in worktree (on lane branch)
+ * 8) cd back to main
+ * 9) Merge lane branch to main with --ff-only (metadata + code merged atomically)
+ * 10) Push to `main`
+ * 11) Remove the associated worktree (unless --no-remove)
+ * 12) Optionally delete the lane branch (with --delete-branch)
+ * 13) Emit telemetry to .beacon/flow.log
+ *
+ * Canonical sequence (Branch-Only mode - LEGACY):
+ * 1) Run gates on lane branch (in main checkout)
+ * 2) Pre-flight validation
+ * 3) Merge lane branch to main
+ * 4) Update metadata on main
+ * 5) Commit and push
+ * 6) Delete lane branch
+ *
+ * Usage:
+ *   pnpm wu:done --id WU-334 [--worktree worktrees/intelligence-wu-334] [--no-auto] [--no-remove] [--no-merge] [--delete-branch]
+ *
+ * WU-2542: This script imports utilities from @lumenflow/core package.
+ * Full migration to thin shim pending @lumenflow/core CLI export implementation.
+ */
+import { execSync } from 'node:child_process';
+import prettyMs from 'pretty-ms';
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { existsSync, readFileSync, mkdirSync, appendFileSync, unlinkSync, statSync } from 'node:fs';
+import path from 'node:path';
+// WU-1825: Import from unified code-path-validator (consolidates 3 validators)
+import { validateWUCodePaths } from '@lumenflow/core/dist/code-path-validator.js';
+// WU-1983: Migration deployment utilities
+import { discoverLocalMigrations, hasMigrationChanges, } from '@lumenflow/core/dist/migration-deployer.js';
+import { validateDocsOnly, getAllowedPathsDescription, } from '@lumenflow/core/dist/docs-path-validator.js';
+import { scanLogForViolations, rotateLog } from '@lumenflow/core/dist/commands-logger.js';
+import { rollbackFiles } from '@lumenflow/core/dist/rollback-utils.js';
+import { validateInputs, detectModeAndPaths, defaultBranchFrom, runCleanup, validateSpecCompleteness, runPreflightTasksValidation, buildPreflightErrorMessage, 
+// 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/dist/wu-done-validators.js';
+// WU-1825: validateCodePathsExist moved to unified code-path-validator
+import { validateCodePathsExist } from '@lumenflow/core/dist/code-path-validator.js';
+import { BRANCHES, REMOTES, 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, } from '@lumenflow/core/dist/wu-constants.js';
+import { printGateFailureBox, printStatusPreview } from '@lumenflow/core/dist/wu-done-ui.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { writeWU, appendNote, parseYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { PLACEHOLDER_SENTINEL, validateWU, validateDoneWU, validateApprovalGates, } from '@lumenflow/core/dist/wu-schema.js';
+import { validateBacklogSync } from '@lumenflow/core/dist/backlog-sync-validator.js';
+import { executeBranchOnlyCompletion } from '@lumenflow/core/dist/wu-done-branch-only.js';
+import { executeWorktreeCompletion, autoRebaseBranch, } from '@lumenflow/core/dist/wu-done-worktree.js';
+import { checkWUConsistency } from '@lumenflow/core/dist/wu-consistency-checker.js';
+// WU-1542: Use blocking mode compliance check (replaces non-blocking checkMandatoryAgentsCompliance)
+import { checkMandatoryAgentsComplianceBlocking } from '@lumenflow/core/dist/orchestration-rules.js';
+import { endSessionForWU } from '@lumenflow/agent/dist/auto-session-integration.js';
+import { runBackgroundProcessCheck } from '@lumenflow/core/dist/process-detector.js';
+import { WUStateStore } from '@lumenflow/core/dist/wu-state-store.js';
+// WU-1588: INIT-007 memory layer integration
+import { createCheckpoint } from '@lumenflow/memory/dist/mem-checkpoint-core.js';
+import { createSignal, loadSignals } from '@lumenflow/memory/dist/mem-signal-core.js';
+// WU-1763: Memory store for loading discoveries (lifecycle nudges)
+import { loadMemory, queryByWu } from '@lumenflow/memory/dist/memory-store.js';
+// WU-1943: Checkpoint warning helper
+import { hasSessionCheckpoints } from '@lumenflow/core/dist/wu-done-worktree.js';
+// WU-1603: Atomic lane locking - release lock on WU completion
+import { releaseLaneLock } from '@lumenflow/core/dist/lane-lock.js';
+// WU-1747: Checkpoint and lock for concurrent load resilience
+import { createPreGatesCheckpoint as createWU1747Checkpoint, markGatesPassed, canSkipGates, clearCheckpoint, } from '@lumenflow/core/dist/wu-checkpoint.js';
+// WU-1946: Spawn registry for tracking sub-agent spawns
+import { SpawnRegistryStore } from '@lumenflow/core/dist/spawn-registry-store.js';
+import { SpawnStatus } from '@lumenflow/core/dist/spawn-registry-schema.js';
+// WU-1999: Exposure validation for UI pairing
+// WU-2022: Feature accessibility validation (blocking)
+import { validateExposure, validateFeatureAccessibility, } from '@lumenflow/core/dist/wu-validation.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
+// Path constant for wu-events.jsonl (used in multiple places)
+const WU_EVENTS_PATH = '.beacon/state/wu-events.jsonl';
+/**
+ * WU-1804: Preflight validation for claim metadata before gates.
+ *
+ * Validates that the WU is properly claimed before running gates:
+ * 1. Worktree YAML status must be 'in_progress'
+ * 2. State store must show WU as 'in_progress'
+ *
+ * If either fails, exits before gates with actionable guidance to run wu:repair-claim.
+ * This prevents burning tokens on gates that will ultimately fail.
+ *
+ * @param {string} id - WU ID
+ * @param {string} worktreePath - Path to the worktree
+ * @param {string} yamlStatus - Current status from worktree YAML
+ * @returns {Promise<void>}
+ */
+async function validateClaimMetadataBeforeGates(id, worktreePath, yamlStatus) {
+    const errors = [];
+    // Check 1: YAML status must be in_progress
+    if (yamlStatus !== WU_STATUS.IN_PROGRESS) {
+        errors.push(`Worktree YAML status is '${yamlStatus}', expected '${WU_STATUS.IN_PROGRESS}'`);
+    }
+    // Check 2: State store must show WU as in_progress
+    const resolvedWorktreePath = path.resolve(worktreePath);
+    const stateDir = path.join(resolvedWorktreePath, '.beacon', 'state');
+    const eventsPath = path.join(resolvedWorktreePath, WU_EVENTS_PATH);
+    try {
+        const store = new WUStateStore(stateDir);
+        await store.load();
+        const inProgress = store.getByStatus(WU_STATUS.IN_PROGRESS);
+        if (!inProgress.has(id)) {
+            errors.push(`State store does not show ${id} as in_progress (path: ${eventsPath})`);
+        }
+    }
+    catch (err) {
+        errors.push(`Cannot read state store: ${err.message} (path: ${eventsPath})`);
+    }
+    // If no errors, we're good
+    if (errors.length === 0) {
+        return;
+    }
+    // Build actionable error message with wu:repair-claim guidance
+    die(`❌ CLAIM METADATA VALIDATION FAILED (WU-1804)\n\n` +
+        `Cannot proceed with wu:done - the WU is not properly claimed.\n\n` +
+        `Issues detected:\n${errors.map((e) => `  - ${e}`).join('\n')}\n\n` +
+        `This typically happens when:\n` +
+        `  • A crash/rebase interrupted worktree creation\n` +
+        `  • The claim transaction was partially completed\n` +
+        `  • Another process modified the WU state\n\n` +
+        `Next step:\n` +
+        `  pnpm wu:repair-claim --id ${id}\n\n` +
+        `After repair, retry:\n` +
+        `  pnpm wu:done --id ${id}\n\n` +
+        `See: ai/onboarding/troubleshooting-wu-done.md for more recovery options.`);
+}
+export function printExposureWarnings(wu, options = {}) {
+    // Validate exposure
+    const result = validateExposure(wu, { skipExposureCheck: options.skipExposureCheck });
+    // Print warnings if any
+    if (result.warnings.length > 0) {
+        console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-1999: Exposure validation warnings:`);
+        for (const warning of result.warnings) {
+            console.log(`${LOG_PREFIX.DONE}   ${warning}`);
+        }
+        console.log(`${LOG_PREFIX.DONE} These are non-blocking warnings. ` +
+            `To skip, use --skip-exposure-check flag.\n`);
+    }
+}
+export function validateAccessibilityOrDie(wu, options = {}) {
+    const result = validateFeatureAccessibility(wu, {
+        skipAccessibilityCheck: options.skipAccessibilityCheck,
+    });
+    if (!result.valid) {
+        console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} WU-2022: Feature accessibility validation failed`);
+        die(`❌ FEATURE ACCESSIBILITY VALIDATION FAILED (WU-2022)\n\n` +
+            `Cannot complete wu:done - UI feature accessibility not verified.\n\n` +
+            `${result.errors.join('\n\n')}\n\n` +
+            `This gate prevents "orphaned code" - features that exist but users cannot access.`);
+    }
+}
+async function assertWorktreeWUInProgressInStateStore(id, worktreePath) {
+    const resolvedWorktreePath = path.resolve(worktreePath);
+    const stateDir = path.join(resolvedWorktreePath, '.beacon', 'state');
+    const eventsPath = path.join(resolvedWorktreePath, WU_EVENTS_PATH);
+    const store = new WUStateStore(stateDir);
+    try {
+        await store.load();
+    }
+    catch (err) {
+        die(`Cannot read WU state store for ${id}.\n\n` +
+            `Path: ${eventsPath}\n\n` +
+            `Error: ${err.message}\n\n` +
+            `If this WU was claimed on an older tool version or the event log is missing/corrupt,\n` +
+            `repair the worktree state store before rerunning wu:done.`);
+    }
+    const inProgress = store.getByStatus(WU_STATUS.IN_PROGRESS);
+    if (!inProgress.has(id)) {
+        die(`WU ${id} is not in_progress in the worktree state store.\n\n` +
+            `Path: ${eventsPath}\n\n` +
+            `This will fail later when wu:done tries to append a complete event and regenerate backlog/status.\n` +
+            `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: ${err.message}`);
+    }
+}
+/**
+ * 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: ${err.message}`);
+    }
+}
+/**
+ * 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: ${err.message}`);
+    }
+}
+/**
+ * WU-1946: Update spawn registry on WU completion.
+ * Non-blocking wrapper - failures logged as warnings.
+ *
+ * When a WU is completed via wu:done, this function updates the spawn registry
+ * to mark the spawned entry as completed (if one exists). This allows orchestrators
+ * to track sub-agent spawn completion status.
+ *
+ * Gracefully skips if:
+ * - No spawn entry found for this WU (legacy WU created before registry)
+ * - Registry file doesn't exist
+ * - Any error during update
+ *
+ * @param {string} id - WU ID being completed
+ * @param {string} baseDir - Base directory containing .beacon/state/
+ * @returns {Promise<void>}
+ */
+export async function updateSpawnRegistryOnCompletion(id, baseDir = process.cwd()) {
+    try {
+        const store = new SpawnRegistryStore(path.join(baseDir, '.beacon', 'state'));
+        await store.load();
+        const spawnEntry = store.getByTarget(id);
+        // Graceful skip if no spawn entry found (legacy WU)
+        if (!spawnEntry) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} No spawn registry entry found for ${id} (legacy WU or not spawned)`);
+            return;
+        }
+        // Update status to completed with completedAt timestamp
+        await store.updateStatus(spawnEntry.id, SpawnStatus.COMPLETED);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Spawn registry updated: ${id} marked as completed`);
+    }
+    catch (err) {
+        // Non-blocking: spawn registry update failure should not block wu:done
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not update spawn registry for ${id}: ${err.message}`);
+    }
+}
+// Git config keys used for user identification
+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-1234: Detect if branch is already merged to main
+ * Checks if branch tip is an ancestor of main HEAD (i.e., already merged).
+ * This prevents merge loops when code was merged via emergency fix or manual merge.
+ *
+ * @param {string} branch - Lane branch name
+ * @returns {Promise<boolean>} True if branch is already merged to main
+ */
+export async function isBranchAlreadyMerged(branch) {
+    try {
+        const gitAdapter = getGitForCwd();
+        const branchTip = (await gitAdapter.getCommitHash(branch)).trim();
+        const mergeBase = (await gitAdapter.mergeBase(BRANCHES.MAIN, branch)).trim();
+        const mainHead = (await gitAdapter.getCommitHash(BRANCHES.MAIN)).trim();
+        // Branch is already merged if:
+        // 1. Branch tip equals merge-base (branch has been rebased/merged onto main)
+        // 2. Branch tip is an ancestor of main HEAD
+        if (branchTip === mergeBase) {
+            // Emergency fix Session 2: Use GIT.SHA_SHORT_LENGTH constant
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Branch ${branch} is already merged to main\n` +
+                `         Branch tip: ${branchTip.substring(0, GIT.SHA_SHORT_LENGTH)}\n` +
+                `         Merge-base: ${mergeBase.substring(0, GIT.SHA_SHORT_LENGTH)}\n` +
+                `         Main HEAD:  ${mainHead.substring(0, GIT.SHA_SHORT_LENGTH)}`);
+            return true;
+        }
+        return false;
+    }
+    catch (e) {
+        console.warn(`${LOG_PREFIX.DONE} Could not check if branch is already merged: ${e.message}`);
+        return false;
+    }
+}
+// WU-1281: isDocsOnlyByPaths removed - use shouldSkipWebTests from path-classifiers.mjs
+// 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/dist/path-classifiers.js';
+/**
+ * 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: ${e.message}`);
+        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
+ */
+function getCommitHeaderLimit() {
+    try {
+        const configPath = path.join(process.cwd(), '.commitlintrc.json');
+        if (!existsSync(configPath))
+            return DEFAULTS.MAX_COMMIT_SUBJECT;
+        const cfg = JSON.parse(readFileSync(configPath, { encoding: FILE_SYSTEM.UTF8 }));
+        return cfg?.rules?.['header-max-length']?.[2] ?? DEFAULTS.MAX_COMMIT_SUBJECT;
+    }
+    catch {
+        return DEFAULTS.MAX_COMMIT_SUBJECT; // Fallback if config is malformed or missing
+    }
+}
+// ensureOnMain() moved to wu-helpers.mjs (WU-1256)
+/**
+ * Ensure working tree is clean before wu:done operations.
+ *
+ * Prevents multi-agent data loss: If uncommitted files exist in main
+ * checkout, wu:done operations may fail mid-workflow. Agents then
+ * automatically "clean up" by running git reset/clean, destroying
+ * other agents' uncommitted work.
+ *
+ * This check HALTS wu:done immediately and guides the agent to verify
+ * ownership before proceeding.
+ *
+ * Context: WU-635 (multi-agent coordination)
+ * See: CLAUDE.md §2.2
+ */
+async function ensureCleanWorkingTree() {
+    const status = await getGitForCwd().getStatus();
+    if (status.trim()) {
+        die(`Working tree is not clean. Cannot proceed with wu:done.\n\n` +
+            `Uncommitted changes in main checkout:\n${status}\n\n` +
+            `⚠️  CRITICAL: These may be another agent's work!\n\n` +
+            `Before proceeding:\n` +
+            `1. Check if these are YOUR changes (forgot to commit in main)\n` +
+            `   → If yes: Commit them now, then retry wu:done\n\n` +
+            `2. Check if these are ANOTHER AGENT's changes\n` +
+            `   → If yes: STOP. Coordinate with user before proceeding\n` +
+            `   → NEVER remove another agent's uncommitted work\n\n` +
+            `Multi-agent coordination: See CLAUDE.md §2.2\n\n` +
+            `Common causes:\n` +
+            `  - You forgot to commit changes before claiming a different WU\n` +
+            `  - Another agent is actively working in main checkout\n` +
+            `  - Leftover changes from previous session`);
+    }
+}
+/**
+ * Extract completed WU IDs from git log output.
+ * @param {string} logOutput - Git log output (one commit per line)
+ * @param {string} currentId - Current WU ID to exclude
+ * @returns {string[]} Array of completed WU IDs
+ */
+function extractCompletedWUIds(logOutput, currentId) {
+    const wuPattern = /wu\((wu-\d+)\):/gi;
+    const seenIds = new Set();
+    const completedWUs = [];
+    for (const line of logOutput.split(STRING_LITERALS.NEWLINE)) {
+        // Only process "done" commits
+        if (!line.toLowerCase().includes('done'))
+            continue;
+        let match;
+        while ((match = wuPattern.exec(line)) !== null) {
+            const wuId = match[1].toUpperCase();
+            // Skip current WU and duplicates
+            if (wuId !== currentId && !seenIds.has(wuId)) {
+                seenIds.add(wuId);
+                completedWUs.push(wuId);
+            }
+        }
+    }
+    return completedWUs;
+}
+/**
+ * Build warning message for parallel completions.
+ */
+function buildParallelWarning(id, completedWUs, baselineSha, currentSha) {
+    const wuList = completedWUs.map((wu) => `  • ${wu}`).join(STRING_LITERALS.NEWLINE);
+    return `
+${EMOJI.WARNING}  PARALLEL COMPLETIONS DETECTED ${EMOJI.WARNING}
+
+The following WUs were completed and merged to main since you claimed ${id}:
+
+${wuList}
+
+This may cause rebase conflicts when wu:done attempts to merge.
+
+Options:
+  1. Proceed anyway - rebase will attempt to resolve conflicts
+  2. Abort and manually rebase: git fetch origin main && git rebase origin/main
+  3. Check if any completed WUs touched the same files
+
+Baseline: ${baselineSha.substring(0, 8)}
+Current:  ${currentSha.substring(0, 8)}
+`;
+}
+/**
+ * WU-1382: Detect parallel WU completions since claim time.
+ *
+ * When multiple agents work in parallel, one may complete a WU and merge to main
+ * while another is still working. This function detects such completions early,
+ * before wu:done attempts the merge, allowing the agent to decide whether to
+ * proceed (with potential rebase conflicts) or abort.
+ *
+ * @param {string} id - Current WU ID
+ * @param {object} doc - WU YAML document (from worktree or main)
+ * @returns {Promise<{hasParallelCompletions: boolean, completedWUs: string[], warning: string|null}>}
+ */
+async function detectParallelCompletions(id, doc) {
+    const noParallel = { hasParallelCompletions: false, completedWUs: [], warning: null };
+    const baselineSha = doc.baseline_main_sha;
+    // If no baseline recorded (legacy WU), skip detection
+    if (!baselineSha) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} No baseline_main_sha recorded (legacy WU) - skipping parallel detection`);
+        return noParallel;
+    }
+    try {
+        const gitAdapter = getGitForCwd();
+        await gitAdapter.fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
+        const currentSha = (await gitAdapter.getCommitHash(`${REMOTES.ORIGIN}/${BRANCHES.MAIN}`)).trim();
+        if (currentSha === baselineSha) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} No parallel completions detected (main unchanged since claim)`);
+            return noParallel;
+        }
+        const logOutput = await gitAdapter.raw([
+            'log',
+            '--oneline',
+            '--grep=^wu(wu-',
+            `${baselineSha}..${REMOTES.ORIGIN}/${BRANCHES.MAIN}`,
+        ]);
+        if (!logOutput?.trim()) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Main advanced since claim but no WU completions detected`);
+            return noParallel;
+        }
+        const completedWUs = extractCompletedWUIds(logOutput, id);
+        if (completedWUs.length === 0) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Main advanced since claim but no other WU completions`);
+            return noParallel;
+        }
+        const warning = buildParallelWarning(id, completedWUs, baselineSha, currentSha);
+        return { hasParallelCompletions: true, completedWUs, warning };
+    }
+    catch (err) {
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not detect parallel completions: ${err.message}`);
+        return noParallel;
+    }
+}
+/**
+ * Ensure main branch is up-to-date with origin before merge operations.
+ *
+ * Prevents coordination failures when Agent A pushes to main while Agent B
+ * is working. Without this check, Agent B's wu:done would fail with cryptic
+ * fast-forward errors when trying to merge.
+ *
+ * Context: WU-705 (fix agent coordination failures)
+ * See: CLAUDE.md §2.7
+ */
+async function ensureMainUpToDate() {
+    console.log(`${LOG_PREFIX.DONE} Checking if main is up-to-date with origin...`);
+    try {
+        // Fetch latest without merging
+        const gitAdapter = getGitForCwd();
+        await gitAdapter.fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
+        const localMain = await gitAdapter.getCommitHash(BRANCHES.MAIN);
+        const remoteMain = await gitAdapter.getCommitHash(`${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+        if (localMain !== remoteMain) {
+            const behind = await gitAdapter.revList([
+                '--count',
+                `${BRANCHES.MAIN}..${REMOTES.ORIGIN}/${BRANCHES.MAIN}`,
+            ]);
+            const ahead = await gitAdapter.revList([
+                '--count',
+                `${REMOTES.ORIGIN}/${BRANCHES.MAIN}..${BRANCHES.MAIN}`,
+            ]);
+            die(`Main branch is out of sync with ${REMOTES.ORIGIN}.\n\n` +
+                `Local ${BRANCHES.MAIN} is ${behind} commits behind and ${ahead} commits ahead of ${REMOTES.ORIGIN}/${BRANCHES.MAIN}.\n\n` +
+                `Update main before running wu:done:\n` +
+                `  git pull origin main\n` +
+                `  # Then retry:\n` +
+                `  pnpm wu:done --id ${process.argv.find((a) => a.startsWith('WU-')) || 'WU-XXX'}\n\n` +
+                `This prevents fast-forward merge failures during wu:done completion.\n\n` +
+                `Why this happens:\n` +
+                `  - Another agent completed a WU and pushed to main\n` +
+                `  - Your main checkout is now behind origin/main\n` +
+                `  - The fast-forward merge will fail without updating first\n\n` +
+                `Multi-agent coordination: See CLAUDE.md §2.7`);
+        }
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Main is up-to-date with origin`);
+    }
+    catch (err) {
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not verify main sync: ${err.message}`);
+        console.warn(`${LOG_PREFIX.DONE} Proceeding anyway (network issue or no remote)`);
+    }
+}
+/**
+ * Tripwire check: Scan commands log for violations (WU-630 detective layer)
+ *
+ * Scans .beacon/commands.log for destructive git commands executed during
+ * this agent session. If violations are found, aborts wu:done and displays
+ * remediation guidance.
+ *
+ * This is defense-in-depth: catches violations even if git shim was bypassed
+ * by calling /usr/bin/git directly or if PATH was not set up correctly.
+ *
+ * Context: WU-630 (detective layer, Layer 3 of 4)
+ * See: docs/04-operations/_frameworks/lumenflow/02-playbook.md §4.6
+ */
+function runTripwireCheck() {
+    const violations = scanLogForViolations();
+    if (violations.length === 0) {
+        return; // All clear
+    }
+    // Violations detected - format error message with remediation
+    console.error('\n⛔ VIOLATION DETECTED: Destructive Git Commands on Main\n');
+    console.error('The following forbidden git commands were executed during this session:\n');
+    violations.forEach((v, i) => {
+        console.error(`  ${i + 1}. ${v.command}`);
+        console.error(`     Branch: ${v.branch}`);
+        console.error(`     Worktree: ${v.worktree}`);
+        console.error(`     Time: ${v.timestamp}\n`);
+    });
+    console.error(`\nTotal: ${violations.length} violations\n`);
+    // Remediation guidance based on violation type
+    console.error("⚠️  CRITICAL: These commands may have destroyed other agents' work!\n");
+    console.error('Remediation Steps:\n');
+    const hasReset = violations.some((v) => v.command.includes('reset --hard'));
+    const hasStash = violations.some((v) => v.command.includes('stash'));
+    const hasClean = violations.some((v) => v.command.includes('clean'));
+    if (hasReset) {
+        console.error('📋 git reset --hard detected:');
+        console.error('   1. Check git reflog to recover lost commits:');
+        console.error('      git reflog');
+        console.error('      git reset --hard HEAD@{N}  (where N is the commit before reset)');
+        console.error('   2. If reflog shows lost work, restore it immediately\n');
+    }
+    if (hasStash) {
+        console.error('📋 git stash detected:');
+        console.error("   1. Check if stash contains other agents' work:");
+        console.error('      git stash list');
+        console.error('      git stash show -p stash@{0}');
+        console.error('   2. If stash contains work, pop it back:');
+        console.error('      git stash pop\n');
+    }
+    if (hasClean) {
+        console.error('📋 git clean detected:');
+        console.error('   1. Deleted files may not be recoverable');
+        console.error('   2. Check git status for any remaining untracked files');
+        console.error('   3. Escalate to human if critical files were deleted\n');
+    }
+    console.error('📖 See detailed recovery steps:');
+    console.error('   docs/04-operations/_frameworks/lumenflow/02-playbook.md §4.6\n');
+    console.error('🚫 DO NOT proceed with wu:done until violations are remediated.\n');
+    console.error('Fix violations first, then retry wu:done.\n');
+    // Also rotate log (cleanup old entries)
+    rotateLog();
+    process.exit(EXIT_CODES.ERROR);
+}
+async function listStaged() {
+    // WU-1235: Use getGitForCwd() to capture current directory (worktree after chdir)
+    const gitCwd = getGitForCwd();
+    const raw = await gitCwd.raw(['diff', '--cached', '--name-only']);
+    return raw ? raw.split(/\r?\n/).filter(Boolean) : [];
+}
+// In --no-auto mode, allow a safe no-op: if NONE of the expected files are staged,
+// treat as already-synchronised and continue. If SOME are staged and SOME missing,
+// still fail with guidance.
+async function ensureNoAutoStagedOrNoop(paths) {
+    const staged = await listStaged();
+    const isStaged = (p) => staged.some((name) => name === p || name.startsWith(`${p}/`));
+    const present = paths.filter(Boolean).filter((p) => isStaged(p));
+    if (present.length === 0) {
+        console.log(`${LOG_PREFIX.DONE} No staged changes detected for --no-auto; treating as no-op finalisation (repo already in done state)`);
+        return { noop: true };
+    }
+    const missing = paths.filter(Boolean).filter((p) => !isStaged(p));
+    if (missing.length > 0) {
+        die(`Stage updates for: ${missing.join(', ')}`);
+    }
+    return { noop: false };
+}
+export function emitTelemetry(event) {
+    const logPath = path.join('.beacon', '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 auditPath = path.join('.beacon', 'skip-gates-audit.log');
+    const auditDir = path.dirname(auditPath);
+    if (!existsSync(auditDir))
+        mkdirSync(auditDir, { recursive: true });
+    const gitAdapter = getGitForCwd();
+    const userName = await gitAdapter.getConfigValue(GIT_CONFIG_USER_NAME);
+    const userEmail = await gitAdapter.getConfigValue(GIT_CONFIG_USER_EMAIL);
+    const commitHash = await gitAdapter.getCommitHash();
+    const entry = {
+        timestamp: new Date().toISOString(),
+        wu_id: id,
+        reason: reason || DEFAULT_NO_REASON,
+        fix_wu: fixWU || '(no fix WU specified)',
+        worktree: worktreePath || '(unknown)',
+        git_user: `${userName.trim()} <${userEmail.trim()}>`,
+        git_commit: commitHash.trim(),
+    };
+    const line = JSON.stringify(entry);
+    appendFileSync(auditPath, `${line}\n`, { encoding: FILE_SYSTEM.UTF8 });
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.MEMO} Skip-gates event logged to ${auditPath}`);
+}
+/**
+ * Audit trail for --skip-cos-gates (COS v1.3 §7)
+ */
+async function auditSkipCosGates(id, reason) {
+    const auditPath = path.join('.beacon', 'skip-cos-gates-audit.log');
+    const auditDir = path.dirname(auditPath);
+    if (!existsSync(auditDir))
+        mkdirSync(auditDir, { recursive: true });
+    const gitAdapter = getGitForCwd();
+    const userName = await gitAdapter.getConfigValue(GIT_CONFIG_USER_NAME);
+    const userEmail = await gitAdapter.getConfigValue(GIT_CONFIG_USER_EMAIL);
+    const commitHash = await gitAdapter.getCommitHash();
+    const entry = {
+        timestamp: new Date().toISOString(),
+        wu_id: id,
+        reason: reason || DEFAULT_NO_REASON,
+        git_user: `${userName.trim()} <${userEmail.trim()}>`,
+        git_commit: commitHash.trim(),
+    };
+    const line = JSON.stringify(entry);
+    appendFileSync(auditPath, `${line}\n`, { encoding: FILE_SYSTEM.UTF8 });
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.MEMO} Skip-COS-gates event logged to ${auditPath}`);
+}
+// WU-2308: validateAllPreCommitHooks moved to wu-done-validators.mjs
+// 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: ${e.message}`);
+    }
+}
+function runGatesInWorktree(worktreePath, id, isDocsOnly = false) {
+    console.log(`\n${LOG_PREFIX.DONE} Running gates in worktree: ${worktreePath}`);
+    // Check for stale node_modules before running gates (prevents confusing failures)
+    checkNodeModulesStaleness(worktreePath);
+    const gatesCmd = isDocsOnly
+        ? `${PKG_MANAGER} ${SCRIPTS.GATES} -- ${CLI_FLAGS.DOCS_ONLY}`
+        : `${PKG_MANAGER} ${SCRIPTS.GATES}`;
+    if (isDocsOnly) {
+        console.log(`${LOG_PREFIX.DONE} Using docs-only gates (skipping lint/typecheck/tests)`);
+    }
+    const startTime = Date.now();
+    try {
+        // WU-1230: Pass WU_ID to validator for context-aware validation
+        execSync(gatesCmd, {
+            cwd: worktreePath,
+            stdio: 'inherit',
+            env: { ...process.env, WU_ID: id },
+        });
+        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.`);
+    }
+}
+async function validateStagedFiles(id, isDocsOnly = false) {
+    const staged = await listStaged();
+    // WU-1740: Include wu-events.jsonl to persist state store events
+    const whitelist = [
+        `docs/04-operations/tasks/wu/${id}.yaml`,
+        'docs/04-operations/tasks/status.md',
+        'docs/04-operations/tasks/backlog.md',
+        WU_EVENTS_PATH,
+    ];
+    if (isDocsOnly) {
+        // For docs-only WUs, validate that all staged files are in allowed paths
+        const docsResult = validateDocsOnly(staged);
+        if (!docsResult.valid) {
+            die(`Docs-only WU cannot modify code files:\n  ${docsResult.violations.join(`${STRING_LITERALS.NEWLINE}  `)}\n\n${getAllowedPathsDescription()}`);
+        }
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Docs-only path validation passed`);
+        return;
+    }
+    const unexpected = staged.filter((file) => {
+        // Whitelist exact matches
+        if (whitelist.includes(file))
+            return false;
+        // Whitelist .beacon/stamps/** pattern
+        if (file.startsWith('.beacon/stamps/'))
+            return false;
+        return true;
+    });
+    if (unexpected.length > 0) {
+        const otherWuYamlOnly = unexpected.every((f) => /^docs\/04-operations\/tasks\/wu\/WU-\d+\.yaml$/.test(f));
+        if (otherWuYamlOnly) {
+            console.warn(`${LOG_PREFIX.DONE} Warning: other WU YAMLs are staged; proceeding and committing only current WU files.`);
+        }
+        else {
+            die(`Unexpected files staged (only current WU YAML, status.md, backlog.md, .beacon/stamps/<id>.done allowed):\n  ${unexpected.join(`${STRING_LITERALS.NEWLINE}  `)}`);
+        }
+    }
+}
+// Note: updateStatusRemoveInProgress, addToStatusCompleted, and moveWUToDoneBacklog
+// have been extracted to tools/lib/wu-status-updater.mjs and imported above (WU-1163)
+//
+// Note: ensureStamp has been replaced with createStamp from tools/lib/stamp-utils.mjs (WU-1163)
+//
+// Note: readWUPreferWorktree, detectCurrentWorktree, defaultWorktreeFrom, detectWorkspaceMode,
+// defaultBranchFrom, branchExists, runCleanup have been extracted to
+// tools/lib/wu-done-validators.mjs and imported above (WU-1215)
+/**
+ * Validate Branch-Only mode requirements before proceeding
+ * @param {string} laneBranch - Expected lane branch name
+ * @returns {{valid: boolean, error: string|null}}
+ */
+async function validateBranchOnlyMode(laneBranch) {
+    // Check we're on the correct lane branch
+    const gitAdapter = getGitForCwd();
+    const currentBranch = await gitAdapter.getCurrentBranch();
+    if (currentBranch !== laneBranch) {
+        return {
+            valid: false,
+            error: `Branch-Only mode error: Not on the lane branch.\n\n` +
+                `Expected branch: ${laneBranch}\n` +
+                `Current branch: ${currentBranch}\n\n` +
+                `Fix: git checkout ${laneBranch}`,
+        };
+    }
+    // Check working directory is clean
+    const status = await gitAdapter.getStatus();
+    if (status) {
+        return {
+            valid: false,
+            error: `Branch-Only mode error: Working directory is not clean.\n\n` +
+                `Uncommitted changes detected:\n${status}\n\n` +
+                `Fix: Commit all changes before running wu:done\n` +
+                `  git add -A\n` +
+                `  git commit -m "wu(wu-xxx): ..."\n` +
+                `  git push origin ${laneBranch}`,
+        };
+    }
+    return { valid: true, error: null };
+}
+/**
+ * WU-755 + WU-1230: Record transaction state for rollback
+ * @param {string} id - WU ID
+ * @param {string} wuPath - Path to WU YAML
+ * @param {string} stampPath - Path to stamp file
+ * @param {string} backlogPath - Path to backlog.md (WU-1230)
+ * @param {string} statusPath - Path to status.md (WU-1230)
+ * @returns {object} - Transaction state for rollback
+ */
+function recordTransactionState(id, wuPath, stampPath, backlogPath, statusPath) {
+    const gitAdapter = getGitForCwd();
+    return {
+        id,
+        timestamp: new Date().toISOString(),
+        wuYamlContent: existsSync(wuPath)
+            ? readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 })
+            : null,
+        stampExisted: existsSync(stampPath),
+        backlogContent: existsSync(backlogPath)
+            ? readFileSync(backlogPath, { encoding: FILE_SYSTEM.UTF8 })
+            : null,
+        statusContent: existsSync(statusPath)
+            ? readFileSync(statusPath, { encoding: FILE_SYSTEM.UTF8 })
+            : null,
+        mainSHA: gitAdapter.getCommitHash(),
+        laneBranch: gitAdapter.getCurrentBranch(),
+    };
+}
+/**
+ * WU-755 + WU-1230: Rollback transaction on failure
+ * @param {object} txState - Transaction state from recordTransactionState
+ * @param {string} wuPath - Path to WU YAML
+ * @param {string} stampPath - Path to stamp file
+ * @param {string} backlogPath - Path to backlog.md (WU-1230)
+ * @param {string} statusPath - Path to status.md (WU-1230)
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
+async function rollbackTransaction(txState, wuPath, stampPath, backlogPath, statusPath) {
+    console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} ROLLING BACK TRANSACTION (WU-755 + WU-1230 + WU-1255 + WU-1280)...`);
+    // WU-1280: ATOMIC ROLLBACK - Clean git state FIRST, then restore files
+    // Previous order (restore → git checkout) caused issues:
+    // - git checkout -- . would UNDO file restorations
+    // - Left messy state with staged + unstaged conflicts
+    //
+    // New order:
+    // 1. Unstage everything (git reset HEAD)
+    // 2. Discard working tree changes (git checkout -- .)
+    // 3. Remove stamp if created
+    // 4. THEN restore files from txState
+    // Step 1: Unstage any staged files FIRST
+    // Emergency fix Session 2: Use git-adapter instead of raw execSync
+    try {
+        const gitAdapter = getGitForCwd();
+        await gitAdapter.raw(['reset', 'HEAD']);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Unstaged all files`);
+    }
+    catch {
+        // Ignore - may not have anything staged
+    }
+    // Step 2: Discard working directory changes (reset to last commit)
+    // Emergency fix Session 2: Use git-adapter instead of raw execSync
+    try {
+        const gitAdapter = getGitForCwd();
+        await gitAdapter.raw(['checkout', '--', '.']);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Reset working tree to HEAD`);
+    }
+    catch {
+        // Ignore - may not have anything to discard
+    }
+    // Step 3: Remove stamp unconditionally if it exists (WU-1440)
+    // Previous behavior only removed if !stampExisted, but that flag could be wrong
+    // due to edge cases. Unconditional removal ensures clean rollback state.
+    if (existsSync(stampPath)) {
+        try {
+            unlinkSync(stampPath);
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Removed ${stampPath}`);
+        }
+        catch (err) {
+            console.error(`${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Failed to remove stamp: ${err.message}`);
+        }
+    }
+    // Step 4: Restore files from txState (AFTER git cleanup)
+    // Build list of files to restore with per-file error tracking (ref: WU-1255)
+    const filesToRestore = [];
+    // Restore backlog.md (ref: WU-1230)
+    if (txState.backlogContent && existsSync(backlogPath)) {
+        filesToRestore.push({ name: 'backlog.md', path: backlogPath, content: txState.backlogContent });
+    }
+    // Restore status.md (ref: WU-1230)
+    if (txState.statusContent && existsSync(statusPath)) {
+        filesToRestore.push({ name: 'status.md', path: statusPath, content: txState.statusContent });
+    }
+    // Restore WU YAML if it was modified
+    if (txState.wuYamlContent && existsSync(wuPath)) {
+        filesToRestore.push({ name: 'WU YAML', path: wuPath, content: txState.wuYamlContent });
+    }
+    // WU-1255: Use rollbackFiles utility for per-file error tracking
+    const restoreResult = rollbackFiles(filesToRestore);
+    // Log results
+    for (const name of restoreResult.restored) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Restored ${name}`);
+    }
+    for (const err of restoreResult.errors) {
+        console.error(`${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Failed to restore ${err.name}: ${err.error}`);
+    }
+    // Reset main to original SHA if we're on main
+    try {
+        const gitAdapter = getGitForCwd();
+        const currentBranch = await gitAdapter.getCurrentBranch();
+        if (currentBranch === BRANCHES.MAIN) {
+            const currentSHA = await gitAdapter.getCommitHash();
+            if (currentSHA !== txState.mainSHA) {
+                await gitAdapter.reset(txState.mainSHA, { hard: true });
+                // Emergency fix Session 2: Use GIT.SHA_SHORT_LENGTH constant
+                console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Reset main to ${txState.mainSHA.slice(0, GIT.SHA_SHORT_LENGTH)}`);
+            }
+        }
+    }
+    catch (e) {
+        console.warn(`${LOG_PREFIX.DONE} Warning: Could not reset main: ${e.message}`);
+    }
+    // WU-1280: Verify clean git status after rollback
+    // WU-1281: Extracted to helper to fix repeated parsing and magic number
+    // Emergency fix Session 2: Use git-adapter instead of raw execSync
+    try {
+        const gitAdapter = getGitForCwd();
+        const statusOutput = (await gitAdapter.raw(['status', '--porcelain'])).trim();
+        if (statusOutput) {
+            printStatusPreview(statusOutput);
+        }
+        else {
+            console.log(`${LOG_PREFIX.DONE} ✅ Working tree is clean`);
+        }
+    }
+    catch {
+        // Ignore - git status may fail in edge cases
+    }
+    // WU-1255: Report final status with all errors
+    if (restoreResult.errors.length > 0) {
+        console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} Rollback completed with ${restoreResult.errors.length} error(s):`);
+        for (const err of restoreResult.errors) {
+            console.error(`  - ${err.name}: ${err.error}`);
+        }
+        console.error(`${LOG_PREFIX.DONE} Manual intervention required for failed files`);
+        console.error(`${LOG_PREFIX.DONE} See playbook.md section 12 "Scenario D" for recovery steps`);
+    }
+    else {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Rollback complete - WU state fully reverted (no infinite loop)`);
+    }
+}
+/**
+ * Validate WU code paths for incomplete work markers and Mock classes
+ * @param {object} doc - WU YAML document
+ * @param {string} id - WU ID
+ * @param {boolean} allowTodo - Allow incomplete work markers (with warning)
+ * @param {string|null} worktreePath - Path to worktree to validate files from
+ */
+function runWUValidator(doc, id, allowTodo = false, worktreePath = null) {
+    console.log(`\n${LOG_PREFIX.DONE} Running WU validator for ${id}...`);
+    // Check if WU has code_paths defined
+    const codePaths = doc.code_paths || [];
+    if (codePaths.length === 0) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} No code_paths defined in WU YAML, skipping validator`);
+        return;
+    }
+    // Check if incomplete work flag requires justification in notes
+    if (allowTodo) {
+        // Handle both string and array formats for notes (WU-654)
+        let notesText = '';
+        if (typeof doc.notes === 'string') {
+            notesText = doc.notes;
+        }
+        else if (Array.isArray(doc.notes)) {
+            notesText = doc.notes.join(STRING_LITERALS.NEWLINE);
+        }
+        const hasJustification = notesText.toLowerCase().includes('todo') || notesText.toLowerCase().includes('allow-todo');
+        if (!hasJustification) {
+            die('--allow-todo flag requires justification in WU YAML notes field.\n' +
+                'Add a note explaining why TODOs are acceptable for this WU.');
+        }
+    }
+    // Validate from worktree if available (ensures we check the lane branch code)
+    const validateOptions = { allowTodos: allowTodo };
+    if (worktreePath && existsSync(worktreePath)) {
+        validateOptions.worktreePath = worktreePath;
+        console.log(`${LOG_PREFIX.DONE} Validating code paths from worktree: ${worktreePath}`);
+    }
+    // Run validation
+    const result = validateWUCodePaths(codePaths, validateOptions);
+    // Display warnings
+    if (result.warnings.length > 0) {
+        console.log('\n⚠️  WU VALIDATOR WARNINGS:');
+        result.warnings.forEach((warning) => console.log(warning));
+    }
+    // Handle errors
+    if (!result.valid) {
+        console.log('\n❌ WU VALIDATOR FAILED:');
+        result.errors.forEach((error) => console.log(error));
+        console.log('\nFix these issues before marking WU as done.');
+        console.log('Alternatively, use --allow-todo if TODOs are acceptable (requires justification in notes).');
+        die('WU validation failed. See errors above.');
+    }
+    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}}
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
+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: ${err.message}`);
+            }
+        }
+    }
+    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 = null;
+    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('.beacon', '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)
+ * @param {object} params - Parameters
+ * @param {string} params.id - WU ID
+ * @param {object} params.args - Parsed CLI arguments
+ * @param {boolean} params.isBranchOnly - Whether in branch-only mode
+ * @param {boolean} params.isDocsOnly - Whether this is a docs-only WU
+ * @param {object} params.docMain - Main WU YAML document
+ * @param {object} params.docForValidation - WU YAML document to validate (worktree or main)
+ * @param {string|null} params.derivedWorktree - Derived worktree path
+ * @returns {Promise<{title: string, docForValidation: object}>} Updated title and doc
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
+async function executePreFlightChecks({ id, args, isBranchOnly, isDocsOnly, docMain, docForValidation, derivedWorktree, }) {
+    // YAML schema validation
+    console.log(`${LOG_PREFIX.DONE} Validating WU YAML structure...`);
+    const schemaResult = validateWU(docForValidation);
+    if (!schemaResult.success) {
+        const errors = schemaResult.error.issues
+            .map((issue) => `  ${issue.path.join('.')}: ${issue.message}`)
+            .join(STRING_LITERALS.NEWLINE);
+        die(`❌ WU YAML validation failed:\n\n${errors}\n\nFix these issues before running wu:done`);
+    }
+    // Additional done-specific validation
+    if (docForValidation.status === WU_STATUS.DONE) {
+        const doneResult = validateDoneWU(schemaResult.data);
+        if (!doneResult.valid) {
+            die(`❌ WU not ready for done status:\n\n${doneResult.errors.map((e) => `  - ${e}`).join(STRING_LITERALS.NEWLINE)}`);
+        }
+    }
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} WU YAML validation passed`);
+    // WU-2079: Approval gate validation
+    // Ensures required approvals are present before allowing completion
+    console.log(`${LOG_PREFIX.DONE} Checking approval gates...`);
+    const approvalResult = validateApprovalGates(schemaResult.data);
+    if (!approvalResult.valid) {
+        die(`❌ Approval gates not satisfied:\n\n${approvalResult.errors.map((e) => `  - ${e}`).join(STRING_LITERALS.NEWLINE)}\n\n` +
+            `📋 To fix:\n` +
+            `   1. Request approval from the required role(s)\n` +
+            `   2. Add their email(s) to the 'approved_by' field in the WU YAML\n` +
+            `   3. Re-run: pnpm wu:done --id ${id}\n\n` +
+            `   See docs/04-operations/governance/project-governance.md for role definitions.`);
+    }
+    // Log advisory warnings (non-blocking)
+    if (approvalResult.warnings.length > 0) {
+        approvalResult.warnings.forEach((w) => {
+            console.warn(`${LOG_PREFIX.DONE} ⚠️  ${w}`);
+        });
+    }
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Approval gates passed`);
+    // WU-1805: Preflight code_paths and test_paths validation
+    // Run BEFORE gates to catch YAML mismatches early (saves time vs. discovering after full gate run)
+    const preflightResult = await executePreflightCodePathValidation(id, {
+        rootDir: process.cwd(),
+        worktreePath: derivedWorktree,
+    });
+    if (!preflightResult.valid) {
+        const errorMessage = buildPreflightCodePathErrorMessage(id, preflightResult);
+        die(errorMessage);
+    }
+    // WU-2310: Preflight type vs code_paths validation
+    // Run BEFORE transaction to prevent documentation WUs with code paths from failing at git commit
+    console.log(`${LOG_PREFIX.DONE} Validating type vs code_paths (WU-2310)...`);
+    const typeVsCodePathsResult = validateTypeVsCodePathsPreflight(docForValidation);
+    if (!typeVsCodePathsResult.valid) {
+        const errorMessage = buildTypeVsCodePathsErrorMessage(id, typeVsCodePathsResult.blockedPaths);
+        die(errorMessage);
+    }
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Type vs code_paths validation passed`);
+    // Tripwire: Scan commands log for violations
+    runTripwireCheck();
+    // WU-1234: Pre-flight backlog consistency check
+    // Fail fast if WU is in both Done and In Progress sections
+    console.log(`${LOG_PREFIX.DONE} Checking backlog consistency...`);
+    const backlogPath = WU_PATHS.BACKLOG();
+    const backlogConsistency = checkBacklogConsistencyForWU(id, backlogPath);
+    if (!backlogConsistency.valid) {
+        die(backlogConsistency.error);
+    }
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Backlog consistency check passed`);
+    // WU-1276: Pre-flight WU state consistency check
+    // Layer 2 defense-in-depth: fail fast if WU has pre-existing inconsistencies
+    console.log(`${LOG_PREFIX.DONE} Checking WU state consistency...`);
+    const stateCheck = await checkWUConsistency(id);
+    if (!stateCheck.valid) {
+        const errors = stateCheck.errors
+            .map((e) => `  - ${e.type}: ${e.description}`)
+            .join(STRING_LITERALS.NEWLINE);
+        die(`Pre-existing inconsistencies for ${id}:\n${errors}\n\n` +
+            `Fix with: pnpm wu:repair --id ${id}`);
+    }
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} WU state consistency check passed`);
+    // Branch-Only mode validation
+    if (isBranchOnly) {
+        const laneBranch = await defaultBranchFrom(docMain);
+        if (!laneBranch)
+            die('Cannot determine lane branch from WU YAML');
+        const validation = await validateBranchOnlyMode(laneBranch);
+        if (!validation.valid) {
+            die(validation.error);
+        }
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Branch-Only mode validation passed`);
+        console.log(`${LOG_PREFIX.DONE} Working on branch: ${laneBranch}`);
+    }
+    else {
+        // Worktree mode: must be on main
+        await ensureOnMain(getGitForCwd());
+        // Prevent multi-agent data loss by ensuring clean working tree
+        await ensureCleanWorkingTree();
+        // Prevent coordination failures by ensuring main is up-to-date
+        await ensureMainUpToDate();
+        // P0 EMERGENCY FIX Part 1: Restore wu-events.jsonl BEFORE parallel completion check
+        // Previous wu:done runs or memory layer writes may have left this file dirty,
+        // which causes the auto-rebase to fail with "You have unstaged changes"
+        if (derivedWorktree) {
+            try {
+                execSync(`git -C "${derivedWorktree}" restore "${WU_EVENTS_PATH}"`);
+            }
+            catch {
+                // Non-fatal: file might not exist or already clean
+            }
+        }
+        // WU-1382: Detect parallel completions and warn
+        // WU-1584 Fix #3: Trigger auto-rebase instead of just warning
+        console.log(`${LOG_PREFIX.DONE} Checking for parallel WU completions...`);
+        const parallelResult = await detectParallelCompletions(id, docForValidation);
+        if (parallelResult.hasParallelCompletions) {
+            console.warn(parallelResult.warning);
+            // Emit telemetry for parallel detection
+            emitTelemetry({
+                script: 'wu-done',
+                wu_id: id,
+                step: 'parallel_detection',
+                parallel_wus: parallelResult.completedWUs,
+                count: parallelResult.completedWUs.length,
+            });
+            // WU-1588: Check inbox for recent signals from parallel agents
+            // Non-blocking: failures handled internally by checkInboxForRecentSignals
+            await checkInboxForRecentSignals(id);
+            // WU-1584: Instead of proceeding with warning, trigger auto-rebase
+            // This prevents merge conflicts that would fail downstream
+            if (derivedWorktree && !args.noAutoRebase) {
+                console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} WU-1584: Triggering auto-rebase to incorporate parallel completions...`);
+                const laneBranch = await defaultBranchFrom(docForValidation);
+                if (laneBranch) {
+                    const rebaseResult = await autoRebaseBranch(laneBranch, derivedWorktree, id);
+                    if (rebaseResult.success) {
+                        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} WU-1584: Auto-rebase complete - parallel completions incorporated`);
+                        emitTelemetry({
+                            script: MICRO_WORKTREE_OPERATIONS.WU_DONE,
+                            wu_id: id,
+                            step: TELEMETRY_STEPS.PARALLEL_AUTO_REBASE,
+                            parallel_wus: parallelResult.completedWUs,
+                            count: parallelResult.completedWUs.length,
+                        });
+                    }
+                    else {
+                        // Rebase failed - provide detailed instructions
+                        console.error(`${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Auto-rebase failed`);
+                        console.error(rebaseResult.error);
+                        die(`WU-1584: Auto-rebase failed after detecting parallel completions.\n` +
+                            `Manual resolution required - see instructions above.`);
+                    }
+                }
+            }
+            else if (!args.noAutoRebase) {
+                // No worktree path available - warn and proceed (legacy behavior)
+                console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Cannot auto-rebase (no worktree path) - proceeding with caution`);
+            }
+            else {
+                // Auto-rebase disabled - warn and proceed
+                console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Auto-rebase disabled (--no-auto-rebase) - proceeding with caution`);
+            }
+        }
+        // WU-1381: Detect background processes that might interfere with gates
+        // Non-blocking warning - helps agents understand mixed stdout/stderr output
+        if (derivedWorktree) {
+            await runBackgroundProcessCheck(derivedWorktree);
+        }
+        // WU-1804: Fail fast before gates with comprehensive claim metadata check.
+        // Validates both YAML status AND state store BEFORE gates, not just one of them.
+        // Provides actionable guidance to run wu:repair-claim if validation fails.
+        if (derivedWorktree) {
+            await validateClaimMetadataBeforeGates(id, derivedWorktree, docForValidation.status);
+        }
+    }
+    // Use worktree title for commit message (not stale main title)
+    const title = docForValidation.title || docMain.title || '';
+    if (isDocsOnly) {
+        console.log('\n📝 Docs-only WU detected');
+        console.log('   - Gates will skip lint/typecheck/tests');
+        console.log('   - Only docs/markdown paths allowed\n');
+    }
+    if (isBranchOnly) {
+        console.log('\n🌿 Branch-Only mode detected');
+        console.log('   - Gates run in main checkout on lane branch');
+        console.log('   - No worktree to remove\n');
+    }
+    // Ownership check (skip in branch-only mode)
+    if (!isBranchOnly) {
+        const ownershipCheck = await checkOwnership(id, docForValidation, derivedWorktree, args.overrideOwner, args.reason);
+        if (!ownershipCheck.valid) {
+            die(ownershipCheck.error);
+        }
+        // If override was used, log to audit trail and add to WU notes
+        if (ownershipCheck.auditEntry) {
+            auditOwnershipOverride(ownershipCheck.auditEntry);
+            // Add override reason to WU notes (schema requires string, not array)
+            const overrideNote = `Ownership override: Completed by ${ownershipCheck.auditEntry.completed_by} (assigned to ${ownershipCheck.auditEntry.assigned_to}). Reason: ${args.reason}`;
+            appendNote(docForValidation, overrideNote);
+            // Write updated WU YAML back to worktree
+            if (derivedWorktree) {
+                const wtWUPath = path.join(derivedWorktree, 'docs', '04-operations', 'tasks', 'wu', `${id}.yaml`);
+                if (existsSync(wtWUPath)) {
+                    writeWU(wtWUPath, docForValidation);
+                }
+            }
+        }
+    }
+    // WU-1280: Early spec completeness validation (before gates)
+    // Catches missing tests.manual, empty code_paths, etc. BEFORE 2min gate run
+    console.log(`\n${LOG_PREFIX.DONE} Validating spec completeness for ${id}...`);
+    const specResult = validateSpecCompleteness(docForValidation, id);
+    if (!specResult.valid) {
+        console.error(`\n❌ Spec completeness validation failed for ${id}:\n`);
+        specResult.errors.forEach((err) => console.error(`  - ${err}`));
+        console.error(`\nFix these issues before running wu:done:\n` +
+            `  1. Update docs/04-operations/tasks/wu/${id}.yaml\n` +
+            `  2. Fill description with Context/Problem/Solution\n` +
+            `  3. Replace ${PLACEHOLDER_SENTINEL} text with specific criteria\n` +
+            `  4. List all modified files in code_paths\n` +
+            `  5. Add at least one test path (unit, e2e, integration, or manual)\n` +
+            `  6. Re-run: pnpm wu:done --id ${id}\n\n` +
+            `See: CLAUDE.md §2.7 "WUs are specs, not code"\n`);
+        die(`Cannot mark ${id} as done - spec incomplete`);
+    }
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Spec completeness check passed`);
+    // WU-1351: Validate code_paths files exist (prevents false completions)
+    // In worktree mode: validate files exist in worktree (will be merged)
+    // In branch-only mode: validate files exist on current branch
+    console.log(`\n${LOG_PREFIX.DONE} Validating code_paths existence for ${id}...`);
+    const codePathsResult = await validateCodePathsExist(docForValidation, id, {
+        worktreePath: derivedWorktree,
+        targetBranch: isBranchOnly ? 'HEAD' : BRANCHES.MAIN,
+    });
+    if ('valid' in codePathsResult && !codePathsResult.valid) {
+        console.error(`\n❌ code_paths validation failed for ${id}:\n`);
+        if ('errors' in codePathsResult) {
+            codePathsResult.errors.forEach((err) => console.error(err));
+        }
+        die(`Cannot mark ${id} as done - code_paths missing from target branch`);
+    }
+    // WU-1324 + WU-1542: Check mandatory agent compliance
+    // WU-1542: --require-agents makes this a BLOCKING check
+    const codePaths = docForValidation.code_paths || [];
+    const compliance = checkMandatoryAgentsComplianceBlocking(codePaths, id, {
+        blocking: Boolean(args.requireAgents),
+    });
+    if (compliance.blocking && compliance.errorMessage) {
+        // WU-1542: Blocking mode - fail wu:done with detailed error
+        die(compliance.errorMessage);
+    }
+    else if (!compliance.compliant) {
+        // Non-blocking mode - show warning (original WU-1324 behavior)
+        console.warn(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} MANDATORY AGENT WARNING`);
+        console.warn(`The following mandatory agents were not confirmed as invoked:`);
+        for (const agent of compliance.missing) {
+            console.warn(`  • ${agent}`);
+        }
+        console.warn(`\nThis is a NON-BLOCKING warning.`);
+        console.warn(`Use --require-agents to make this a blocking error.\n`);
+    }
+    // WU-1999: Exposure validation (NON-BLOCKING warning)
+    printExposureWarnings(docForValidation, { skipExposureCheck: args.skipExposureCheck });
+    // WU-2022: Feature accessibility validation (BLOCKING)
+    validateAccessibilityOrDie(docForValidation, {
+        skipAccessibilityCheck: args.skipAccessibilityCheck,
+    });
+    // Run WU validator
+    runWUValidator(docForValidation, id, args.allowTodo, derivedWorktree);
+    // Validate skip-gates requirements
+    if (args.skipGates) {
+        if (!args.reason) {
+            die('--skip-gates requires --reason "<explanation of why gates are being skipped>"');
+        }
+        if (!args.fixWu) {
+            die('--skip-gates requires --fix-wu WU-{id} (the WU that will fix the failing tests)');
+        }
+        if (!PATTERNS.WU_ID.test(args.fixWu.toUpperCase())) {
+            die(`Invalid --fix-wu value '${args.fixWu}'. Expected format: WU-123`);
+        }
+    }
+    return { title, docForValidation };
+}
+async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath, branchName, }) {
+    // WU-1747: Check if gates can be skipped based on valid checkpoint
+    // This allows resuming wu:done without re-running gates if nothing changed
+    const skipResult = canSkipGates(id, { currentHeadSha: undefined });
+    if (skipResult.canSkip) {
+        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; // 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}: ${err.message}`);
+        }
+    }
+    // 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);
+    // 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 "${WU_EVENTS_PATH}"`);
+        }
+        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/dist/invariants-runner.js');
+    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)`);
+        const gatesCmd = isDocsOnly
+            ? `${PKG_MANAGER} ${SCRIPTS.GATES} -- ${CLI_FLAGS.DOCS_ONLY}`
+            : `${PKG_MANAGER} ${SCRIPTS.GATES}`;
+        if (isDocsOnly) {
+            console.log(`${LOG_PREFIX.DONE} Using docs-only gates (skipping lint/typecheck/tests)`);
+        }
+        const startTime = Date.now();
+        try {
+            execSync(gatesCmd, { stdio: 'inherit' });
+            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.`);
+        }
+    }
+    else if (worktreePath && existsSync(worktreePath)) {
+        // Worktree mode: run gates in the dedicated worktree
+        runGatesInWorktree(worktreePath, id, isDocsOnly);
+    }
+    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 use --skip-gates 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: docs/04-operations/_frameworks/cos/evidence-format.md');
+            console.error('\nEmergency bypass (creates audit trail):');
+            console.error(`  pnpm wu:done --id ${id} --skip-cos-gates --reason "explanation"`);
+            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);
+        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);
+}
+/**
+ * Print State HUD for visibility
+ * Extracted from main() to reduce complexity (WU-1215 Phase 2 Extraction #4)
+ * @param {object} params - Parameters
+ * @param {string} params.id - WU ID
+ * @param {object} params.docMain - Main WU YAML document
+ * @param {boolean} params.isBranchOnly - Whether in branch-only mode
+ * @param {boolean} params.isDocsOnly - Whether this is a docs-only WU
+ * @param {string|null} params.derivedWorktree - Derived worktree path
+ * @param {string} params.STAMPS_DIR - Stamps directory path
+ */
+function printStateHUD({ id, docMain, isBranchOnly, isDocsOnly, derivedWorktree, STAMPS_DIR }) {
+    const stampExists = existsSync(path.join(STAMPS_DIR, `${id}.done`)) ? 'yes' : 'no';
+    const yamlStatus = docMain.status || 'unknown';
+    const yamlLocked = docMain.locked === true ? 'true' : 'false';
+    const mode = isBranchOnly ? 'branch-only' : isDocsOnly ? 'docs-only' : 'worktree';
+    const branch = defaultBranchFrom(docMain) || 'n/a';
+    const worktreeDisplay = isBranchOnly ? 'none' : derivedWorktree || 'none';
+    console.log(`\n${LOG_PREFIX.DONE} HUD: WU=${id} status=${yamlStatus} stamp=${stampExists} locked=${yamlLocked} mode=${mode} branch=${branch} worktree=${worktreeDisplay}`);
+}
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
+async function main() {
+    // Validate CLI arguments and WU ID format (extracted to wu-done-validators.mjs)
+    const { args, id } = validateInputs(process.argv);
+    // Detect workspace mode and calculate paths (WU-1215: extracted to validators module)
+    const pathInfo = await detectModeAndPaths(id, args);
+    const { WU_PATH, STATUS_PATH, BACKLOG_PATH, STAMPS_DIR, docMain, isBranchOnly, derivedWorktree, docForValidation: initialDocForValidation, isDocsOnly, } = pathInfo;
+    // Capture main checkout path once. process.cwd() may drift later during recovery flows.
+    const mainCheckoutPath = process.cwd();
+    // Pre-flight checks (WU-1215: extracted to executePreFlightChecks function)
+    const preFlightResult = await executePreFlightChecks({
+        id,
+        args,
+        isBranchOnly,
+        isDocsOnly,
+        docMain,
+        docForValidation: initialDocForValidation,
+        derivedWorktree,
+    });
+    const title = preFlightResult.title;
+    // Note: docForValidation is returned but not used after pre-flight checks
+    // The metadata transaction uses docForUpdate instead
+    // Step 0: Run gates (WU-1215: extracted to executeGates function)
+    const worktreePath = derivedWorktree && !isBranchOnly
+        ? path.isAbsolute(derivedWorktree)
+            ? derivedWorktree
+            : path.resolve(mainCheckoutPath, derivedWorktree)
+        : null;
+    // WU-1943: Check if any checkpoints exist for this WU session
+    // Warn (don't block) if no checkpoints - agent should have been checkpointing periodically
+    try {
+        const wuNodes = await queryByWu(worktreePath || mainCheckoutPath, id);
+        if (!hasSessionCheckpoints(id, wuNodes)) {
+            console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-1943: No checkpoints found for ${id} session.`);
+            console.log(`${LOG_PREFIX.DONE} Consider using 'pnpm mem:checkpoint --wu ${id}' periodically for crash recovery.`);
+            console.log(`${LOG_PREFIX.DONE} Checkpoint triggers: after each acceptance criterion, before gates, every 30 tool calls.\n`);
+        }
+    }
+    catch {
+        // Non-blocking: checkpoint check failure should not block wu:done
+    }
+    await executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath });
+    // Print State HUD for visibility (WU-1215: extracted to printStateHUD function)
+    printStateHUD({ id, docMain, isBranchOnly, isDocsOnly, derivedWorktree, STAMPS_DIR });
+    // Step 0.5: Pre-flight validation - run ALL pre-commit hooks BEFORE merge
+    // This prevents partial completion states where merge succeeds but commit fails
+    // Validates all 8 gates: secrets, file size, ESLint, Prettier, TypeScript, audit, architecture, tasks
+    // WU-2308: Pass worktreePath to run audit from worktree (checks fixed deps, not stale main deps)
+    const hookResult = validateAllPreCommitHooks(id, worktreePath);
+    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
+    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 = {
+            id,
+            args,
+            docMain,
+            title,
+            isDocsOnly,
+            maxCommitLength: getCommitHeaderLimit(),
+            validateStagedFiles,
+        };
+        try {
+            if (isBranchOnly) {
+                // 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
+                const worktreeContext = {
+                    ...baseContext,
+                    worktreePath,
+                };
+                completionResult = await executeWorktreeCompletion(worktreeContext);
+            }
+            // 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 { }
+                process.exit(EXIT_CODES.SUCCESS);
+            }
+        }
+        catch (err) {
+            // P0 FIX: Release lane lock before error exit
+            try {
+                const lane = docMain.lane;
+                if (lane)
+                    releaseLaneLock(lane, { wuId: id });
+            }
+            catch { }
+            // WU-1811: Check if cleanup is safe before removing worktree
+            // If cleanupSafe is false (or undefined), preserve worktree for recovery
+            if (err.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);
+        }
+    }
+    else {
+        await ensureNoAutoStagedOrNoop([WU_PATH, STATUS_PATH, BACKLOG_PATH, STAMPS_DIR]);
+    }
+    // Step 6 & 7: Cleanup (remove worktree, delete branch) - WU-1215
+    // WU-1811: Only run cleanup if all completion steps succeeded
+    if (completionResult.cleanupSafe !== false) {
+        await runCleanup(docMain, args);
+    }
+    else {
+        console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-1811: Skipping worktree cleanup - metadata/push incomplete`);
+    }
+    // WU-1603: Release lane lock after successful completion
+    // This allows the lane to be claimed by another WU
+    try {
+        const lane = docMain.lane;
+        if (lane) {
+            const releaseResult = releaseLaneLock(lane, { wuId: id });
+            if (releaseResult.released && !releaseResult.notFound) {
+                console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Lane lock released for "${lane}"`);
+            }
+            // Silent if notFound - lock may not exist (older WUs, manual cleanup)
+        }
+    }
+    catch (err) {
+        // Non-blocking: lock release failure should not block completion
+        console.warn(`${LOG_PREFIX.DONE} Warning: Could not release lane lock: ${err.message}`);
+    }
+    // WU-1438: Auto-end agent session
+    try {
+        const sessionResult = endSessionForWU();
+        if (sessionResult.ended) {
+            // Emergency fix Session 2: Use SESSION.ID_DISPLAY_LENGTH constant
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Agent session ended (${sessionResult.summary.session_id.slice(0, SESSION.ID_DISPLAY_LENGTH)}...)`);
+        }
+        // No warning if no active session - silent no-op is expected
+    }
+    catch (err) {
+        // Non-blocking: session end failure should not block completion
+        console.warn(`${LOG_PREFIX.DONE} Warning: Could not end agent session: ${err.message}`);
+    }
+    // WU-1588: Broadcast completion signal after session end
+    // Non-blocking: failures handled internally by broadcastCompletionSignal
+    await broadcastCompletionSignal(id, title);
+    // WU-1946: Update spawn registry to mark WU as completed
+    // Non-blocking: failures handled internally by updateSpawnRegistryOnCompletion
+    // Works in both worktree and branch-only modes (called after completionResult)
+    await updateSpawnRegistryOnCompletion(id, mainCheckoutPath);
+    // WU-1747: Clear checkpoint on successful completion
+    // Checkpoint is no longer needed once WU is fully complete
+    clearCheckpoint(id);
+    console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Transaction COMMIT - all steps succeeded (WU-755)`);
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Marked done, pushed, and cleaned up.`);
+    console.log(`- WU: ${id} — ${title}`);
+    // WU-1763: Print lifecycle nudges (conditional, non-blocking)
+    // Discovery summary nudge - only if discoveries exist
+    const discoveries = await loadDiscoveriesForWU(mainCheckoutPath, id);
+    printDiscoveryNudge(id, discoveries.count, discoveries.ids);
+    // Documentation validation nudge - only if docs changed
+    // Use worktreePath if available, otherwise skip (branch-only mode has no worktree)
+    if (worktreePath) {
+        const changedDocs = await detectChangedDocPaths(worktreePath, BRANCHES.MAIN);
+        printDocValidationNudge(id, changedDocs);
+    }
+    // WU-1983: Migration deployment nudge - only if supabase paths in code_paths
+    const codePaths = docMain.code_paths || [];
+    await printMigrationDeploymentNudge(codePaths, mainCheckoutPath);
+}
+/**
+ * WU-1983: Print migration deployment nudge when WU includes supabase changes.
+ * Notifies agent to deploy new migrations to production via MCP tools.
+ * Conditional output - only prints when migrations are in scope and new migrations exist.
+ *
+ * @param {string[]} codePaths - WU code_paths array
+ * @param {string} baseDir - Base directory for migration discovery
+ * @returns {Promise<void>}
+ */
+export async function printMigrationDeploymentNudge(codePaths, baseDir) {
+    // Only check if WU includes supabase paths
+    if (!hasMigrationChanges(codePaths)) {
+        return;
+    }
+    try {
+        const { files: migrations, errors } = discoverLocalMigrations(baseDir);
+        if (errors.length > 0) {
+            console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Migration discovery errors: ${errors.join(', ')}`);
+        }
+        if (migrations.length > 0) {
+            console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.INFO} WU includes supabase migrations.`);
+            console.log(`${LOG_PREFIX.DONE} ${migrations.length} local migration(s) detected.`);
+            console.log(`${LOG_PREFIX.DONE} To sync with production:`);
+            console.log(`   1. mcp__supabase__list_migrations (check production state)`);
+            console.log(`   2. pnpm db:sync --production-file <output.json> (detect drift)`);
+            console.log(`   3. mcp__supabase__apply_migration (deploy new migrations)`);
+            console.log(`   See: docs/02-technical/database/migration-workflow.md\n`);
+        }
+    }
+    catch (err) {
+        // Non-blocking: migration check failure should not block wu:done
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not check migrations: ${err.message}`);
+    }
+}
+/**
+ * WU-1763: Print discovery summary nudge when discoveries exist for this WU.
+ * Conditional output - only prints when discoveryCount > 0.
+ * Non-blocking, single-line output to avoid flooding the console.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {number} discoveryCount - Number of open discoveries for this WU
+ * @param {string[]} discoveryIds - List of discovery IDs (limited to 5 in output)
+ */
+export function printDiscoveryNudge(id, discoveryCount, discoveryIds) {
+    if (discoveryCount > 0) {
+        const displayIds = discoveryIds.slice(0, 5).join(', ');
+        const moreText = discoveryCount > 5 ? ` (+${discoveryCount - 5} more)` : '';
+        console.log(`\n${LOG_PREFIX.DONE} 💡 ${discoveryCount} open discoveries: ${displayIds}${moreText}`);
+        console.log(`   Triage with: pnpm mem:triage --wu ${id}`);
+    }
+}
+/**
+ * WU-1763: Print documentation validation nudge when docs changed.
+ * Conditional output - only prints when changedDocPaths.length > 0.
+ * Non-blocking, single-line output to avoid flooding the console.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {string[]} changedDocPaths - List of documentation paths that changed
+ */
+export function printDocValidationNudge(id, changedDocPaths) {
+    if (changedDocPaths.length > 0) {
+        console.log(`\n${LOG_PREFIX.DONE} 💡 Documentation changed (${changedDocPaths.length} files).`);
+        console.log(`   Consider: pnpm validate:context && pnpm docs:linkcheck`);
+    }
+}
+/**
+ * WU-1763: Load discoveries for a WU from memory store.
+ * Non-blocking - returns empty array on errors.
+ *
+ * @param {string} baseDir - Base directory containing .beacon/memory/
+ * @param {string} wuId - WU ID to load discoveries for
+ * @returns {Promise<{count: number, ids: string[]}>} Discovery count and IDs
+ */
+async function loadDiscoveriesForWU(baseDir, wuId) {
+    try {
+        const memory = await loadMemory(path.join(baseDir, '.beacon/memory'));
+        const wuNodes = memory.byWu.get(wuId) || [];
+        const discoveries = wuNodes.filter((node) => node.type === 'discovery');
+        return {
+            count: discoveries.length,
+            ids: discoveries.map((d) => d.id),
+        };
+    }
+    catch {
+        // Non-blocking: return empty on errors
+        return { count: 0, ids: [] };
+    }
+}
+/**
+ * WU-1763: Detect documentation paths from changed files.
+ * Non-blocking - returns empty array on errors.
+ *
+ * @param {string} worktreePath - Path to worktree
+ * @param {string} baseBranch - Base branch to compare against
+ * @returns {Promise<string[]>} List of changed documentation paths
+ */
+async function detectChangedDocPaths(worktreePath, baseBranch) {
+    try {
+        const git = getGitForCwd();
+        // Get files changed in this branch vs base
+        const diff = await git.raw(['diff', '--name-only', baseBranch]);
+        const changedFiles = diff.split('\n').filter(Boolean);
+        // Filter to docs: ai/onboarding/, docs/, CLAUDE.md, README.md, *.md in root
+        const docPatterns = [
+            /^ai\/onboarding\//,
+            /^docs\//,
+            /^\.claude\//,
+            /^CLAUDE\.md$/,
+            /^README\.md$/,
+        ];
+        return changedFiles.filter((f) => docPatterns.some((p) => p.test(f)));
+    }
+    catch {
+        // Non-blocking: return empty on errors
+        return [];
+    }
+}
+// Guard main() execution for testability (WU-1366)
+// When imported as a module for testing, main() should not auto-run
+import { fileURLToPath } from 'node:url';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main();
+}