@lumenflow/cli 3.5.0 → 3.6.0

package/dist/wu-done.js

@@ -57,8 +57,6 @@ import { existsSync, readFileSync, mkdirSync, appendFileSync, unlinkSync, statSy
 import path from 'node:path';
 // WU-1825: Import from unified code-path-validator (consolidates 3 validators)
 import { validateWUCodePaths } from '@lumenflow/core/code-path-validator';
-import { validateDocsOnly, getAllowedPathsDescription } from '@lumenflow/core/docs-path-validator';
-import { scanLogForViolations, rotateLog } from '@lumenflow/core/commands-logger';
 import { rollbackFiles } from '@lumenflow/core/rollback-utils';
 import { validateInputs, detectModeAndPaths, defaultBranchFrom, runCleanup, validateSpecCompleteness, runPreflightTasksValidation, buildPreflightErrorMessage, 
 // WU-1805: Preflight code_paths validation before gates
@@ -70,10 +68,9 @@ validateTypeVsCodePathsPreflight, buildTypeVsCodePathsErrorMessage, } from '@lum
 import { formatPreflightWarnings } from '@lumenflow/core/wu-preflight-validators';
 // WU-1825: validateCodePathsExist moved to unified code-path-validator
 import { validateCodePathsExist } from '@lumenflow/core/code-path-validator';
-import { BRANCHES, REMOTES, PATTERNS, DEFAULTS, LOG_PREFIX, EMOJI, GIT, SESSION, WU_STATUS, WU_EXPOSURE, WU_TYPES, PKG_MANAGER, SCRIPTS, CLI_FLAGS, FILE_SYSTEM, EXIT_CODES, STRING_LITERALS, MICRO_WORKTREE_OPERATIONS, TELEMETRY_STEPS, SKIP_GATES_REASONS, CHECKPOINT_MESSAGES, LUMENFLOW_PATHS, ENV_VARS, getWUStatusDisplay, 
+import { BRANCHES, PATTERNS, DEFAULTS, LOG_PREFIX, EMOJI, GIT, SESSION, WU_STATUS, PKG_MANAGER, SCRIPTS, CLI_FLAGS, FILE_SYSTEM, EXIT_CODES, STRING_LITERALS, MICRO_WORKTREE_OPERATIONS, TELEMETRY_STEPS, SKIP_GATES_REASONS, CHECKPOINT_MESSAGES, ENV_VARS, getWUStatusDisplay, 
 // WU-1223: Location types for worktree detection
 CONTEXT_VALIDATION, } from '@lumenflow/core/wu-constants';
-import { isDocumentationType } from '@lumenflow/core/wu-type-helpers';
 import { getDocsOnlyPrefixes, DOCS_ONLY_ROOT_FILES } from '@lumenflow/core';
 import { printGateFailureBox, printStatusPreview } from '@lumenflow/core/wu-done-ui';
 import { ensureOnMain } from '@lumenflow/core/wu-helpers';
@@ -88,12 +85,14 @@ executeBranchPRCompletion, } from '@lumenflow/core/wu-done-branch-only';
 import { executeWorktreeCompletion, autoRebaseBranch } from '@lumenflow/core/wu-done-worktree';
 // WU-1746: Already-merged worktree resilience
 import { detectAlreadyMergedNoWorktree, executeAlreadyMergedCompletion, } from '@lumenflow/core/wu-done-merged-worktree';
+// WU-2211: --already-merged finalize-only mode
+import { verifyCodePathsOnMainHead, executeAlreadyMergedFinalize as executeAlreadyMergedFinalizeFromModule, } from './wu-done-already-merged.js';
 import { checkWUConsistency } from '@lumenflow/core/wu-consistency-checker';
 // WU-1542: Use blocking mode compliance check (replaces non-blocking checkMandatoryAgentsCompliance)
 import { checkMandatoryAgentsComplianceBlocking } from '@lumenflow/core/orchestration-rules';
 import { endSessionForWU } from '@lumenflow/agent/auto-session';
 import { runBackgroundProcessCheck } from '@lumenflow/core/process-detector';
-import { WUStateStore, getLatestWuBriefEvidence } from '@lumenflow/core/wu-state-store';
+import { WUStateStore } from '@lumenflow/core/wu-state-store';
 // WU-1588: INIT-007 memory layer integration
 import { createCheckpoint } from '@lumenflow/memory/checkpoint';
 import { createSignal, loadSignals } from '@lumenflow/memory/signal';
@@ -108,9 +107,6 @@ import { createPreGatesCheckpoint as createWU1747Checkpoint, markGatesPassed, ca
 // WU-1946: Spawn registry for tracking sub-agent spawns
 import { DelegationRegistryStore } from '@lumenflow/core/delegation-registry-store';
 import { DelegationStatus } from '@lumenflow/core/delegation-registry-schema';
-// WU-1999: Exposure validation for UI pairing
-// WU-2022: Feature accessibility validation (blocking)
-import { validateExposure, validateFeatureAccessibility } from '@lumenflow/core/wu-validation';
 import { ensureCleanWorktree } from './wu-done-check.js';
 // WU-1366: Auto cleanup after wu:done success
 // WU-1533: commitCleanupChanges auto-commits dirty state files after cleanup
@@ -122,6 +118,10 @@ import { markCompletedWUSignalsAsRead } from './hooks/enforcement-generator.js';
 import { evaluateMainDirtyMutationGuard } from './hooks/dirty-guard.js';
 // WU-1474: Decay policy invocation during completion lifecycle
 import { runDecayOnDone } from './wu-done-decay.js';
+import { enforceSpawnProvenanceForDone, enforceWuBriefEvidenceForDone, printExposureWarnings, validateAccessibilityOrDie, validateDocsOnlyFlag, } from './wu-done-policies.js';
+import { detectParallelCompletions, ensureNoAutoStagedOrNoop, runTripwireCheck, validateBranchOnlyMode, validateStagedFiles, } from './wu-done-git-ops.js';
+export { buildGatesCommand, buildMissingSpawnPickupEvidenceMessage, buildMissingSpawnProvenanceMessage, buildMissingWuBriefEvidenceMessage, enforceSpawnProvenanceForDone, enforceWuBriefEvidenceForDone, hasSpawnPickupEvidence, printExposureWarnings, shouldEnforceSpawnProvenance, shouldEnforceWuBriefEvidence, validateAccessibilityOrDie, validateDocsOnlyFlag, } from './wu-done-policies.js';
+export { isBranchAlreadyMerged } from './wu-done-git-ops.js';
 // WU-1588: Memory layer constants
 const MEMORY_SIGNAL_TYPES = {
     WU_COMPLETION: 'wu_completion',
@@ -253,101 +253,6 @@ async function validateClaimMetadataBeforeGates(id, worktreePath, yamlStatus) {
         `  pnpm wu:done --id ${id}\n\n` +
         `See: https://lumenflow.dev/reference/troubleshooting-wu-done/ for more recovery options.`);
 }
-export function printExposureWarnings(wu, options = {}) {
-    // Validate exposure
-    const result = validateExposure(wu, { skipExposureCheck: options.skipExposureCheck });
-    // Print warnings if present
-    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.`);
-    }
-}
-export function validateDocsOnlyFlag(wu, args) {
-    // If --docs-only flag is not used, no validation needed
-    if (!args.docsOnly) {
-        return { valid: true, errors: [] };
-    }
-    const wuId = wu.id || 'unknown';
-    const exposure = wu.exposure;
-    const type = wu.type;
-    const codePaths = wu.code_paths;
-    // Check 1: exposure is 'documentation'
-    if (exposure === WU_EXPOSURE.DOCUMENTATION) {
-        return { valid: true, errors: [] };
-    }
-    // Check 2: type is 'documentation'
-    if (isDocumentationType(type)) {
-        return { valid: true, errors: [] };
-    }
-    // Check 3: all code_paths are documentation paths
-    const docsOnlyPrefixes = getDocsOnlyPrefixes().map((prefix) => prefix.toLowerCase());
-    const isDocsPath = (p) => {
-        const path = p.trim().toLowerCase();
-        // Check docs prefixes
-        for (const prefix of docsOnlyPrefixes) {
-            if (path.startsWith(prefix))
-                return true;
-        }
-        // Check markdown files
-        if (path.endsWith('.md'))
-            return true;
-        // Check root file patterns
-        for (const pattern of DOCS_ONLY_ROOT_FILES) {
-            if (path.startsWith(pattern))
-                return true;
-        }
-        return false;
-    };
-    if (codePaths && Array.isArray(codePaths) && codePaths.length > 0) {
-        const allDocsOnly = codePaths.every((p) => typeof p === 'string' && isDocsPath(p));
-        if (allDocsOnly) {
-            return { valid: true, errors: [] };
-        }
-    }
-    // Validation failed - provide clear error message
-    const currentExposure = exposure || 'not set';
-    const currentType = type || 'not set';
-    return {
-        valid: false,
-        errors: [
-            `--docs-only flag used on ${wuId} but WU is not documentation-focused.\n\n` +
-                `Current exposure: ${currentExposure}\n` +
-                `Current type: ${currentType}\n\n` +
-                `--docs-only requires one of:\n` +
-                `  1. exposure: documentation\n` +
-                `  2. type: documentation\n` +
-                `  3. All code_paths under configured docs prefixes (${docsOnlyPrefixes.join(', ')}), or *.md files\n\n` +
-                `To fix, either:\n` +
-                `  - Remove --docs-only flag and run full gates\n` +
-                `  - Change WU exposure to 'documentation' if this is truly a docs-only change`,
-        ],
-    };
-}
-export function buildGatesCommand(options) {
-    const { docsOnly = false, isDocsOnly = false } = options;
-    // Use docs-only gates if either explicit flag or auto-detected
-    const shouldUseDocsOnly = docsOnly || isDocsOnly;
-    if (shouldUseDocsOnly) {
-        return `${PKG_MANAGER} ${SCRIPTS.GATES} -- ${CLI_FLAGS.DOCS_ONLY}`;
-    }
-    return `${PKG_MANAGER} ${SCRIPTS.GATES}`;
-}
 async function _assertWorktreeWUInProgressInStateStore(id, worktreePath) {
     const resolvedWorktreePath = path.resolve(worktreePath);
     const stateDir = resolveStateDir(resolvedWorktreePath);
@@ -456,159 +361,6 @@ async function checkInboxForRecentSignals(id, baseDir = process.cwd()) {
         console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not check inbox for signals: ${getErrorMessage(err)}`);
     }
 }
-/**
- * Enforce wu:brief evidence for feature and bug WUs.
- */
-export function shouldEnforceWuBriefEvidence(doc) {
-    return doc.type === WU_TYPES.FEATURE || doc.type === WU_TYPES.BUG;
-}
-/**
- * Build remediation guidance when wu:brief evidence is missing.
- */
-export function buildMissingWuBriefEvidenceMessage(id) {
-    return (`Missing wu:brief evidence for ${id}.\n\n` +
-        `Completion policy requires an auditable wu:brief execution record for feature/bug WUs.\n\n` +
-        `Fix options:\n` +
-        `  1. Run wu:brief in the claimed workspace:\n` +
-        `     pnpm wu:brief --id ${id}\n` +
-        `  2. Retry completion:\n` +
-        `     pnpm wu:done --id ${id}\n` +
-        `  3. Legacy/manual override (audited):\n` +
-        `     pnpm wu:done --id ${id} --force`);
-}
-function buildWuBriefEvidenceReadFailureMessage(id, stateDir, error) {
-    return (`Could not verify wu:brief evidence for ${id}.\n\n` +
-        `State path: ${stateDir}\n` +
-        `Error: ${getErrorMessage(error)}\n\n` +
-        `Fix options:\n` +
-        `  1. Repair/restore state store, then rerun wu:done\n` +
-        `  2. Use --force for audited override when recovery is not possible`);
-}
-export async function enforceWuBriefEvidenceForDone(id, doc, options = {}) {
-    if (!shouldEnforceWuBriefEvidence(doc)) {
-        return;
-    }
-    const baseDir = options.baseDir ?? process.cwd();
-    const force = options.force === true;
-    const stateDir = resolveStateDir(baseDir);
-    const getBriefEvidenceFn = options.getBriefEvidenceFn ?? getLatestWuBriefEvidence;
-    const blocker = options.blocker ?? ((message) => die(message));
-    const warn = options.warn ?? console.warn;
-    let evidence;
-    try {
-        evidence = await getBriefEvidenceFn(stateDir, id);
-    }
-    catch (error) {
-        if (!force) {
-            blocker(buildWuBriefEvidenceReadFailureMessage(id, stateDir, error));
-            return;
-        }
-        warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-2132: brief evidence verification failed for ${id}, override accepted via --force`);
-        return;
-    }
-    if (evidence) {
-        return;
-    }
-    if (!force) {
-        blocker(buildMissingWuBriefEvidenceMessage(id));
-        return;
-    }
-    warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-2132: brief evidence override accepted for ${id} via --force`);
-}
-/**
- * Returns true when completion should enforce spawn provenance.
- * Initiative-linked WUs are expected to carry machine-verifiable spawn lineage.
- */
-export function shouldEnforceSpawnProvenance(doc) {
-    return typeof doc?.initiative === 'string' && doc.initiative.trim().length > 0;
-}
-/**
- * Build actionable remediation guidance for missing spawn provenance.
- */
-export function buildMissingSpawnProvenanceMessage(id, initiativeId) {
-    return (`Missing spawn provenance for initiative-governed WU ${id} (${initiativeId}).\n\n` +
-        `This completion path enforces auditable delegation lineage for initiative work.\n\n` +
-        `Fix options:\n` +
-        `  1. Re-run with --force for an audited override (legacy/manual workflow)\n` +
-        `  2. Register spawn lineage before completion (preferred):\n` +
-        `     pnpm wu:delegate --id ${id} --parent-wu WU-XXXX --client codex-cli\n\n` +
-        `Then retry: pnpm wu:done --id ${id}`);
-}
-/**
- * Build actionable remediation guidance for intent-only spawn provenance
- * (delegation intent exists but claim-time pickup evidence is missing).
- */
-export function buildMissingSpawnPickupEvidenceMessage(id, initiativeId) {
-    return (`Missing pickup evidence for initiative-governed WU ${id} (${initiativeId}).\n\n` +
-        `Delegation intent exists, but this WU has no claim-time pickup handshake.\n` +
-        `Completion policy requires both intent and pickup evidence.\n\n` +
-        `Fix options:\n` +
-        `  1. Re-run with --force for an audited override (legacy/manual claim)\n` +
-        `  2. Ensure future delegated work is picked up via wu:claim (records handshake automatically)\n\n` +
-        `Then retry: pnpm wu:done --id ${id}`);
-}
-/**
- * Returns true when spawn provenance includes claim-time pickup evidence.
- */
-export function hasSpawnPickupEvidence(spawnEntry) {
-    const pickedUpAt = typeof spawnEntry?.pickedUpAt === 'string' && spawnEntry.pickedUpAt.trim().length > 0
-        ? spawnEntry.pickedUpAt
-        : '';
-    const pickedUpBy = typeof spawnEntry?.pickedUpBy === 'string' && spawnEntry.pickedUpBy.trim().length > 0
-        ? spawnEntry.pickedUpBy
-        : '';
-    return pickedUpAt.length > 0 && pickedUpBy.length > 0;
-}
-/**
- * Record forced spawn-provenance bypass in memory signals for auditability.
- */
-async function recordSpawnProvenanceOverride(id, doc, baseDir = process.cwd()) {
-    try {
-        const initiativeId = typeof doc?.initiative === 'string' ? doc.initiative.trim() : 'unknown';
-        const lane = typeof doc?.lane === 'string' ? doc.lane : undefined;
-        const result = await createSignal(baseDir, {
-            message: `spawn-provenance override used for ${id} in ${initiativeId} via --force`,
-            wuId: id,
-            lane,
-        });
-        if (result.success) {
-            console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Spawn-provenance override recorded (${result.signal.id})`);
-        }
-    }
-    catch (err) {
-        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not record spawn-provenance override: ${getErrorMessage(err)}`);
-    }
-}
-/**
- * Enforce spawn provenance policy for initiative-governed WUs before completion.
- */
-export async function enforceSpawnProvenanceForDone(id, doc, options = {}) {
-    if (!shouldEnforceSpawnProvenance(doc)) {
-        return;
-    }
-    const initiativeId = typeof doc.initiative === 'string' && doc.initiative.trim() ? doc.initiative.trim() : 'unknown';
-    const baseDir = options.baseDir ?? process.cwd();
-    const force = options.force === true;
-    const store = new DelegationRegistryStore(resolveStateDir(baseDir));
-    await store.load();
-    const spawnEntry = store.getByTarget(id);
-    if (!spawnEntry) {
-        if (!force) {
-            die(buildMissingSpawnProvenanceMessage(id, initiativeId));
-        }
-        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-1599: spawn provenance override accepted for ${id} (${initiativeId}) via --force`);
-        await recordSpawnProvenanceOverride(id, doc, baseDir);
-        return;
-    }
-    if (hasSpawnPickupEvidence(spawnEntry)) {
-        return;
-    }
-    if (!force) {
-        die(buildMissingSpawnPickupEvidenceMessage(id, initiativeId));
-    }
-    console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-1605: pickup evidence override accepted for ${id} (${initiativeId}) via --force`);
-    await recordSpawnProvenanceOverride(id, doc, baseDir);
-}
 /**
  * WU-1946: Update spawn registry on WU completion.
  * Non-blocking wrapper - failures logged as warnings.
@@ -668,38 +420,6 @@ export function normalizeUsername(value) {
     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: ${getErrorMessage(e)}`);
-        return false;
-    }
-}
 // WU-1281: isDocsOnlyByPaths removed - use shouldSkipWebTests from path-classifiers.ts
 // The validators already use shouldSkipWebTests via detectDocsOnlyByPaths wrapper.
 // Keeping the export for backward compatibility but re-exporting the canonical function.
@@ -757,278 +477,6 @@ function getCommitHeaderLimit() {
     }
 }
 // ensureOnMain() moved to wu-helpers.ts (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 other 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: ${getErrorMessage(err)}`);
-        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: ${getErrorMessage(err)}`);
-        console.warn(`${LOG_PREFIX.DONE} Proceeding anyway (network issue or no remote)`);
-    }
-}
-/**
- * Tripwire check: Scan commands log for violations (WU-630 detective layer)
- *
- * Scans .lumenflow/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: https://lumenflow.dev/reference/playbook/ §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 remaining untracked files');
-        console.error('   3. Escalate to human if critical files were deleted\n');
-    }
-    console.error('📖 See detailed recovery steps:');
-    console.error('   https://lumenflow.dev/reference/playbook/ §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(gitAdapter) {
-    // WU-1541: Use explicit gitAdapter if provided, otherwise fall back to getGitForCwd()
-    // WU-1235: getGitForCwd() captures current directory (legacy behavior)
-    const gitCwd = gitAdapter ?? 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 definedPaths = paths.filter((p) => typeof p === 'string' && p.length > 0);
-    const present = definedPaths.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 = definedPaths.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('.lumenflow', 'flow.log');
     const logDir = path.dirname(logPath);
@@ -1201,56 +649,6 @@ async function runGatesInWorktree(worktreePath, id, options = {}) {
         die(`Gates failed in ${worktreePath}. Fix issues in the worktree and try again.`);
     }
 }
-async function validateStagedFiles(id, isDocsOnly = false, gitAdapter, options = {}) {
-    // WU-1541: Accept optional gitAdapter to avoid process.chdir dependency
-    const staged = await listStaged(gitAdapter);
-    // WU-1311: Use config-based paths instead of hardcoded docs-layout paths
-    const config = getConfig();
-    const wuPath = `${config.directories.wuDir}/${id}.yaml`;
-    // WU-1740: Include wu-events.jsonl to persist state store events
-    const whitelist = [
-        wuPath,
-        config.directories.statusPath,
-        config.directories.backlogPath,
-        resolveWuEventsRelativePath(process.cwd()),
-    ];
-    const metadataAllowlist = (options.metadataAllowlist ?? []).filter((file) => typeof file === 'string' && file.length > 0);
-    const whitelistSet = new Set([...whitelist, ...metadataAllowlist]);
-    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 (whitelistSet.has(file))
-            return false;
-        // Whitelist stamps directory pattern
-        if (file.startsWith(`${LUMENFLOW_PATHS.STAMPS_DIR}/`))
-            return false;
-        // WU-1072: Whitelist apps/docs/**/*.mdx for auto-generated docs from turbo docs:generate
-        if (file.startsWith('apps/docs/') && file.endsWith('.mdx'))
-            return false;
-        return true;
-    });
-    if (unexpected.length > 0) {
-        // WU-1311: Use config-based pattern for WU YAML detection
-        const wuDirPattern = config.directories.wuDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        // eslint-disable-next-line security/detect-non-literal-regexp -- config path escaped for regex; not user input
-        const wuYamlRegex = new RegExp(`^${wuDirPattern}/WU-\\d+\\.yaml$`);
-        const otherWuYamlOnly = unexpected.every((f) => wuYamlRegex.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 metadata, current parent initiative YAML, and .lumenflow/stamps/<id>.done allowed):\n  ${unexpected.join(`${STRING_LITERALS.NEWLINE}  `)}`);
-        }
-    }
-}
 // Note: updateStatusRemoveInProgress, addToStatusCompleted, and moveWUToDoneBacklog
 // have been extracted to tools/lib/wu-status-updater.ts and imported above (WU-1163)
 //
@@ -1259,39 +657,6 @@ async function validateStagedFiles(id, isDocsOnly = false, gitAdapter, options =
 // Note: readWUPreferWorktree, detectCurrentWorktree, defaultWorktreeFrom, detectWorkspaceMode,
 // defaultBranchFrom, branchExists, runCleanup have been extracted to
 // tools/lib/wu-done-validators.ts 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
@@ -1757,8 +1122,6 @@ async function executePreFlightChecks({ id, args, isBranchOnly, isDocsOnly, docM
     else {
         // Worktree mode: must be on main
         await ensureOnMain(getGitForCwd());
-        // 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"
@@ -2233,6 +1596,62 @@ export async function main() {
     const initialDocForValidation = normalizeWUDocLike(initialDocForValidationRaw);
     // Capture main checkout path once. process.cwd() may drift later during recovery flows.
     const mainCheckoutPath = process.cwd();
+    // ──────────────────────────────────────────────
+    // WU-2211: --already-merged early exit path
+    // Skips merge phase, gates, worktree detection. Only writes metadata.
+    // ──────────────────────────────────────────────
+    if (args.alreadyMerged) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} WU-2211: --already-merged mode activated`);
+        // Safety check: verify code_paths exist on HEAD of main
+        const codePaths = docMain.code_paths || [];
+        const verification = await verifyCodePathsOnMainHead(codePaths);
+        if (!verification.valid) {
+            die(`${EMOJI.FAILURE} --already-merged safety check failed\n\n` +
+                `${verification.error}\n\n` +
+                `Cannot finalize ${id}: code_paths must exist on HEAD before using --already-merged.`);
+        }
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Safety check passed: all ${codePaths.length} code_paths verified on HEAD`);
+        // Execute finalize-only path
+        const title = String(docMain.title || id);
+        const lane = String(docMain.lane || '');
+        const finalizeResult = await executeAlreadyMergedFinalizeFromModule({
+            id,
+            title,
+            lane,
+            doc: docMain,
+        });
+        if (!finalizeResult.success) {
+            die(`${EMOJI.FAILURE} --already-merged finalization failed\n\n` +
+                `Errors:\n${finalizeResult.errors.map((e) => `  - ${e}`).join('\n')}\n\n` +
+                `Partial state may remain. Rerun: pnpm wu:done --id ${id} --already-merged`);
+        }
+        // Release lane lock (non-blocking, same as normal wu:done)
+        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}"`);
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`${LOG_PREFIX.DONE} Warning: Could not release lane lock: ${getErrorMessage(err)}`);
+        }
+        // End agent session (non-blocking)
+        try {
+            endSessionForWU();
+        }
+        catch {
+            // Non-blocking
+        }
+        // Broadcast completion signal (non-blocking)
+        await broadcastCompletionSignal(id, title);
+        console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} ${id} finalized via --already-merged`);
+        console.log(`- WU: ${id} -- ${title}`);
+        clearConfigCache();
+        process.exit(EXIT_CODES.SUCCESS);
+    }
     // WU-1663: Determine prepPassed early for pipeline actor input.
     // canSkipGates checks if wu:prep already ran gates successfully via checkpoint.
     // This drives the isPrepPassed guard on the GATES_SKIPPED transition.