@lumenflow/core 1.0.0 → 1.3.0

package/dist/wu-done-cleanup.js

@@ -0,0 +1,122 @@
+/**
+ * Cleanup helpers for wu:done.
+ */
+import { existsSync } from 'node:fs';
+import { getGitForCwd } from './git-adapter.js';
+import { withCleanupLock } from './cleanup-lock.js';
+import { validateWorktreeOwnership } from './worktree-ownership.js';
+import { getCleanupInstallConfig, CLEANUP_INSTALL_TIMEOUT_MS } from './cleanup-install-config.js';
+import { createValidationError } from './wu-done-errors.js';
+import { defaultWorktreeFrom, defaultBranchFrom, branchExists } from './wu-done-paths.js';
+import { isBranchAlreadyMerged } from './wu-done-branch-utils.js';
+import { CLAIMED_MODES, EMOJI, LOG_PREFIX, REMOTES } from './wu-constants.js';
+import { exec as execCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(execCallback);
+/**
+ * Run cleanup operations after successful merge
+ * Removes worktree and optionally deletes lane branch
+ */
+export async function runCleanup(docMain, args) {
+    const wuId = docMain.id;
+    const worktreePath = args.worktree || (await defaultWorktreeFrom(docMain));
+    // WU-2278: Validate worktree ownership before cleanup
+    // Prevents cross-agent worktree deletion
+    if (!args.overrideOwner) {
+        const ownershipResult = validateWorktreeOwnership({ worktreePath, wuId });
+        if (!ownershipResult.valid) {
+            throw createValidationError(`${ownershipResult.error}\n\nTo override (DANGEROUS): pnpm wu:done --id ${wuId} --override-owner --reason "explanation"`, { wuId, worktreePath, error: ownershipResult.error });
+        }
+    }
+    // WU-2241: Wrap cleanup operations in cleanup lock to prevent concurrent collision
+    await withCleanupLock(wuId, async () => {
+        await runCleanupInternal(docMain, args, worktreePath);
+    }, { worktreePath });
+}
+/**
+ * Internal cleanup implementation (runs under cleanup lock)
+ */
+async function runCleanupInternal(docMain, args, worktreePath) {
+    // Step 6: Remove worktree (runs even if commit/push failed)
+    // Skip removal in PR mode (worktree needed for cleanup after PR merge)
+    const claimedMode = docMain.claimed_mode || CLAIMED_MODES.WORKTREE;
+    const requiresReview = docMain.requires_review === true;
+    const prModeEnabled = claimedMode === CLAIMED_MODES.WORKTREE_PR || args.createPR || requiresReview;
+    // WU-2241: Track branch for cleanup after worktree removal
+    const laneBranch = await defaultBranchFrom(docMain);
+    if (!args.noRemove && !prModeEnabled) {
+        if (worktreePath && existsSync(worktreePath)) {
+            try {
+                await getGitForCwd().worktreeRemove(worktreePath, { force: true });
+                console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Removed worktree ${worktreePath}`);
+                // WU-2241: Delete branch AFTER worktree removal (correct ordering)
+                // This ensures we don't leave orphan branches when worktree is removed
+                if (laneBranch && (await branchExists(laneBranch))) {
+                    await deleteBranchWithCleanup(laneBranch);
+                }
+                // WU-1743: Re-run pnpm install to fix broken symlinks
+                // When pnpm install runs in a worktree, it may create symlinks with absolute paths
+                // to the worktree. After worktree removal, these symlinks break.
+                // Re-running pnpm install regenerates them with correct paths.
+                // WU-2278: Use timeout and CI=true to prevent hangs
+                console.log(`${LOG_PREFIX.DONE} Reinstalling dependencies to fix symlinks...`);
+                try {
+                    const installConfig = getCleanupInstallConfig();
+                    await execAsync(installConfig.command, {
+                        timeout: installConfig.timeout,
+                        env: installConfig.env,
+                    });
+                    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Dependencies reinstalled`);
+                }
+                catch (installErr) {
+                    // Non-fatal: warn but don't fail wu:done
+                    // WU-2278: Include timeout info in error message
+                    const isTimeout = installErr.killed || installErr.signal === 'SIGTERM';
+                    const errorMsg = isTimeout
+                        ? `pnpm install timed out after ${CLEANUP_INSTALL_TIMEOUT_MS / 1000}s`
+                        : `pnpm install failed: ${installErr.message}`;
+                    console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} ${errorMsg}`);
+                }
+            }
+            catch (e) {
+                console.warn(`${LOG_PREFIX.DONE} Could not remove worktree ${worktreePath}: ${e.message}`);
+            }
+        }
+        else {
+            console.log(`${LOG_PREFIX.DONE} Worktree not found; skipping removal`);
+            // WU-2241: Still cleanup branch if worktree doesn't exist (orphan branch scenario)
+            if (!prModeEnabled && laneBranch && (await branchExists(laneBranch))) {
+                await deleteBranchWithCleanup(laneBranch);
+            }
+        }
+    }
+    else if (prModeEnabled) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Worktree preserved (PR mode - run wu:cleanup after PR merge)`);
+    }
+}
+/**
+ * WU-2241: Delete both local and remote branch with proper error handling
+ */
+async function deleteBranchWithCleanup(laneBranch) {
+    const gitAdapter = getGitForCwd();
+    // WU-1440: Check if branch is merged before deletion
+    // Use -D (force) when confirmed merged to handle rebased branches
+    const isMerged = await isBranchAlreadyMerged(laneBranch);
+    try {
+        await gitAdapter.deleteBranch(laneBranch, { force: isMerged });
+        const modeIndicator = isMerged ? ' (force: merged)' : '';
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Deleted local branch ${laneBranch}${modeIndicator}`);
+        // Also delete remote if it exists
+        try {
+            await gitAdapter.raw(['push', REMOTES.ORIGIN, '--delete', laneBranch]);
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Deleted remote branch ${laneBranch}`);
+        }
+        catch (e) {
+            // WU-2241: Non-fatal - remote branch may already be deleted or never existed
+            console.warn(`${LOG_PREFIX.DONE} Could not delete remote branch: ${e.message}`);
+        }
+    }
+    catch (e) {
+        console.warn(`${LOG_PREFIX.DONE} Could not delete branch ${laneBranch}: ${e.message}`);
+    }
+}

package/dist/wu-done-docs-only.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Docs-only detection utilities for wu:done
+ *
+ * WU-1234 + WU-1255 + WU-1539: Detect docs-only WUs from code_paths.
+ */
+/**
+ * Detect docs-only WU from code_paths.
+ * Returns true if all code_paths are documentation paths only.
+ *
+ * Docs-only paths: docs/, ai/, .claude/, memory-bank/, README*, CLAUDE*.md
+ * NOT docs-only: tools/, scripts/ (these are code, not documentation)
+ *
+ * WU-1539: Fixed misclassification where tools/ was treated as docs-only
+ * but then rejected by validateDocsOnly(). tools/ should skip web tests
+ * but NOT be classified as docs-only.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if WU is docs-only (all paths are documentation)
+ */
+export declare function detectDocsOnlyByPaths(codePaths: any): boolean;

package/dist/wu-done-docs-only.js

@@ -0,0 +1,65 @@
+/**
+ * Docs-only detection utilities for wu:done
+ *
+ * WU-1234 + WU-1255 + WU-1539: Detect docs-only WUs from code_paths.
+ */
+/**
+ * Prefixes for paths that qualify as "docs-only" (no code changes).
+ * Unlike SKIP_TESTS_PREFIXES, this excludes tools/ and scripts/ because
+ * those contain code files that require full gate validation.
+ *
+ * WU-1539: Split from shouldSkipWebTests to fix docs-only misclassification.
+ * @constant {string[]}
+ */
+const DOCS_ONLY_PREFIXES = Object.freeze(['docs/', 'ai/', '.claude/', 'memory-bank/']);
+/**
+ * Root file patterns that qualify as docs-only.
+ * @constant {string[]}
+ */
+const DOCS_ONLY_ROOT_FILES = Object.freeze(['readme', 'claude']);
+/**
+ * Detect docs-only WU from code_paths.
+ * Returns true if all code_paths are documentation paths only.
+ *
+ * Docs-only paths: docs/, ai/, .claude/, memory-bank/, README*, CLAUDE*.md
+ * NOT docs-only: tools/, scripts/ (these are code, not documentation)
+ *
+ * WU-1539: Fixed misclassification where tools/ was treated as docs-only
+ * but then rejected by validateDocsOnly(). tools/ should skip web tests
+ * but NOT be classified as docs-only.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if WU is docs-only (all paths are documentation)
+ */
+export function detectDocsOnlyByPaths(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return false;
+    }
+    return codePaths.every((filePath) => {
+        if (!filePath || typeof filePath !== 'string') {
+            return false;
+        }
+        const path = filePath.trim();
+        if (path.length === 0) {
+            return false;
+        }
+        // Check docs-only prefixes (docs/, ai/, .claude/, memory-bank/)
+        for (const prefix of DOCS_ONLY_PREFIXES) {
+            if (path.startsWith(prefix)) {
+                return true;
+            }
+        }
+        // Check if it's a markdown file (*.md)
+        if (path.endsWith('.md')) {
+            return true;
+        }
+        // Check root file patterns (README*, CLAUDE*.md)
+        const lowerPath = path.toLowerCase();
+        for (const pattern of DOCS_ONLY_ROOT_FILES) {
+            if (lowerPath.startsWith(pattern)) {
+                return true;
+            }
+        }
+        return false;
+    });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Error helpers for wu:done validators
+ *
+ * WU-1049: Standardize error handling patterns across wu-done validator paths.
+ */
+/**
+ * Create a validation error for wu:done validators.
+ */
+export declare function createValidationError(message: any, details?: {}): import("./error-handler.js").WUError;
+/**
+ * Create a file-not-found error for wu:done validators.
+ */
+export declare function createFileNotFoundError(message: any, details?: {}): import("./error-handler.js").WUError;
+/**
+ * Create a recovery error for wu:done recovery flows.
+ */
+export declare function createRecoveryError(message: any, details?: {}): import("./error-handler.js").WUError;

package/dist/wu-done-errors.js

@@ -0,0 +1,24 @@
+/**
+ * Error helpers for wu:done validators
+ *
+ * WU-1049: Standardize error handling patterns across wu-done validator paths.
+ */
+import { createError, ErrorCodes } from './error-handler.js';
+/**
+ * Create a validation error for wu:done validators.
+ */
+export function createValidationError(message, details = {}) {
+    return createError(ErrorCodes.VALIDATION_ERROR, message, details);
+}
+/**
+ * Create a file-not-found error for wu:done validators.
+ */
+export function createFileNotFoundError(message, details = {}) {
+    return createError(ErrorCodes.FILE_NOT_FOUND, message, details);
+}
+/**
+ * Create a recovery error for wu:done recovery flows.
+ */
+export function createRecoveryError(message, details = {}) {
+    return createError(ErrorCodes.RECOVERY_ERROR, message, details);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Input parsing for wu:done validators.
+ */
+/**
+ * Validates command-line inputs and WU ID format
+ * @param {string[]} argv - Process arguments
+ * @returns {{ args: object, id: string }} Parsed args and validated WU ID
+ */
+export declare function validateInputs(argv: any): {
+    args: import("commander").OptionValues;
+    id: any;
+};

package/dist/wu-done-inputs.js

@@ -0,0 +1,51 @@
+/**
+ * Input parsing for wu:done validators.
+ */
+import { parseWUArgs } from './arg-parser.js';
+import { die } from './error-handler.js';
+import { EXIT_CODES, PATTERNS } from './wu-constants.js';
+/**
+ * Validates command-line inputs and WU ID format
+ * @param {string[]} argv - Process arguments
+ * @returns {{ args: object, id: string }} Parsed args and validated WU ID
+ */
+export function validateInputs(argv) {
+    const args = parseWUArgs(argv);
+    if (args.help || !args.id) {
+        console.log('Usage: pnpm wu:done --id WU-334 [OPTIONS]\n\n' +
+            'Options:\n' +
+            '  --worktree <path>   Override worktree path (default: worktrees/<lane>-<wu-id>)\n' +
+            '  --no-auto           Skip auto-updating YAML/backlog/status (you staged manually)\n' +
+            '  --no-remove         Skip worktree removal\n' +
+            '  --no-merge          Skip auto-merging lane branch to main\n' +
+            '  --delete-branch     Delete lane branch after merge (both local and remote)\n' +
+            '  --create-pr         Create PR instead of auto-merge (requires gh CLI)\n' +
+            '  --pr-draft          Create PR as draft (use with --create-pr)\n' +
+            '  --skip-gates        Skip gates check (USE WITH EXTREME CAUTION)\n' +
+            '  --docs-only         Run docs-only gates (requires exposure: documentation)\n' +
+            '  --reason "<text>"   Required with --skip-gates or --override-owner\n' +
+            '  --fix-wu WU-{id}    Required with --skip-gates: WU ID that will fix the failures\n' +
+            '  --allow-todo        Allow TODO comments in code (requires justification in WU notes)\n' +
+            '  --override-owner    Override ownership check (requires --reason, audited)\n' +
+            '  --no-auto-rebase    Disable auto-rebase on branch divergence (WU-1303)\n' +
+            '  --require-agents    Block completion if mandatory agents not invoked (WU-1542)\n' +
+            '  --help, -h          Show this help\n\n' +
+            '⚠️  SKIP-GATES WARNING:\n' +
+            '  Only use --skip-gates when:\n' +
+            '    • Test failures are confirmed pre-existing (not introduced by your WU)\n' +
+            '    • A separate WU exists to fix those failures (specify with --fix-wu)\n' +
+            '    • Your WU work is genuinely complete\n\n' +
+            '  NEVER use --skip-gates for failures introduced by your WU!\n' +
+            '  All skip-gates events are logged to .beacon/skip-gates-audit.log\n\n' +
+            '📝 WU VALIDATOR:\n' +
+            '  Automatically scans code_paths for:\n' +
+            '    • TODO/FIXME/HACK/XXX comments (fails validation unless --allow-todo)\n' +
+            '    • Mock/Stub/Fake classes in production code (warning only)\n' +
+            '  Use --allow-todo only for legitimate cases with justification in WU notes.\n');
+        process.exit(args.help ? EXIT_CODES.SUCCESS : EXIT_CODES.ERROR);
+    }
+    const id = args.id.toUpperCase();
+    if (!PATTERNS.WU_ID.test(id))
+        die(`Invalid WU id '${args.id}'. Expected format WU-123`);
+    return { args, id };
+}

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

@@ -0,0 +1,100 @@
+/**
+ * Metadata update helpers for wu:done.
+ */
+/**
+ * Generate commit message for WU completion
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * @param {string} id - WU ID (e.g., "WU-1215")
+ * @param {string} title - WU title
+ * @param {number} maxLength - Maximum commit header length from commitlint config
+ * @returns {string} Formatted commit message
+ * @throws {Error} If generated message exceeds maxLength
+ */
+export declare function generateCommitMessage(id: any, title: any, maxLength?: number): string;
+/**
+ * Validate that required metadata files exist before updating
+ * WU-1275: Fail fast before mutations to prevent partial state
+ *
+ * @param {object} params - Parameters object
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @throws {WUError} If any required file is missing
+ */
+export declare function validateMetadataFilesExist({ statusPath, backlogPath }: {
+    statusPath: any;
+    backlogPath: any;
+}): void;
+/**
+ * Update all metadata files for WU completion
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * WU-1572: Made async for WUStateStore integration
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID
+ * @param {string} params.title - WU title
+ * @param {object} params.doc - WU YAML document to update
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ */
+export declare function updateMetadataFiles({ id, title, doc, wuPath, statusPath, backlogPath }: {
+    id: any;
+    title: any;
+    doc: any;
+    wuPath: any;
+    statusPath: any;
+    backlogPath: any;
+}): Promise<void>;
+/**
+ * Collect metadata updates to a transaction (WU-1369: Atomic pattern)
+ *
+ * This is the atomic version of updateMetadataFiles.
+ * Instead of writing files immediately, it collects all changes
+ * into a WUTransaction object for atomic commit.
+ *
+ * Usage:
+ * ```js
+ * const tx = new WUTransaction(id);
+ * collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction: tx });
+ * // All changes are now in tx.pendingWrites
+ * // Validate, then commit or abort
+ * tx.commit();
+ * ```
+ *
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID
+ * @param {string} params.title - WU title
+ * @param {object} params.doc - WU YAML document to update (will be mutated)
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @param {string} params.stampPath - Path to stamp file
+ * @param {WUTransaction} params.transaction - Transaction to add writes to
+ */
+export declare function collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction, }: {
+    id: any;
+    title: any;
+    doc: any;
+    wuPath: any;
+    statusPath: any;
+    backlogPath: any;
+    stampPath: any;
+    transaction: any;
+}): Promise<void>;
+/**
+ * Stage and format metadata files
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID (for error reporting)
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @param {string} params.stampsDir - Path to stamps directory
+ * @throws {Error} If formatting fails
+ */
+export declare function stageAndFormatMetadata({ id, wuPath, statusPath, backlogPath, stampsDir }: {
+    id: any;
+    wuPath: any;
+    statusPath: any;
+    backlogPath: any;
+    stampsDir: any;
+}): Promise<void>;

package/dist/wu-done-metadata.js

@@ -0,0 +1,193 @@
+/**
+ * Metadata update helpers for wu:done.
+ */
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { exec as execCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { getGitForCwd } from './git-adapter.js';
+import { updateStatusRemoveInProgress, addToStatusCompleted } from './wu-status-updater.js';
+import { moveWUToDoneBacklog } from './wu-backlog-updater.js';
+import { createStamp } from './stamp-utils.js';
+import { WU_EVENTS_FILE_NAME } from './wu-state-store.js';
+import { computeWUYAMLContent, computeStatusContent, computeBacklogContent, computeWUEventsContentAfterComplete, computeStampContent, } from './wu-transaction-collectors.js';
+import { DEFAULTS, LOG_PREFIX, EMOJI, PKG_MANAGER, SCRIPTS, PRETTIER_FLAGS, BEACON_PATHS, } from './wu-constants.js';
+import { applyExposureDefaults } from './wu-done-validation.js';
+import { createFileNotFoundError, createValidationError } from './wu-done-errors.js';
+import { writeWU } from './wu-yaml.js';
+const execAsync = promisify(execCallback);
+/**
+ * Generate commit message for WU completion
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * @param {string} id - WU ID (e.g., "WU-1215")
+ * @param {string} title - WU title
+ * @param {number} maxLength - Maximum commit header length from commitlint config
+ * @returns {string} Formatted commit message
+ * @throws {Error} If generated message exceeds maxLength
+ */
+export function generateCommitMessage(id, title, maxLength = DEFAULTS.MAX_COMMIT_SUBJECT) {
+    const prefix = `wu(${id.toLowerCase()}): done - `;
+    const safe = String(title).trim().toLowerCase().replace(/\s+/g, ' ');
+    const room = Math.max(0, maxLength - prefix.length);
+    const short = safe.length > room ? `${safe.slice(0, room - 1)}…` : safe;
+    const msg = `${prefix}${short}`;
+    if (msg.length > maxLength) {
+        const error = new Error(`Commit message too long (${msg.length}/${maxLength}).\n` +
+            `Fix: Shorten WU title\n` +
+            `Current title: "${title}" (${title.length} chars)\n` +
+            `Suggested max: ~${maxLength - prefix.length} chars`);
+        error.code = 'COMMIT_MESSAGE_TOO_LONG';
+        error.data = {
+            title,
+            titleLength: title.length,
+            messageLength: msg.length,
+            maxLength,
+            suggestedMax: maxLength - prefix.length,
+        };
+        throw error;
+    }
+    return msg;
+}
+/**
+ * Validate that required metadata files exist before updating
+ * WU-1275: Fail fast before mutations to prevent partial state
+ *
+ * @param {object} params - Parameters object
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @throws {WUError} If any required file is missing
+ */
+export function validateMetadataFilesExist({ statusPath, backlogPath }) {
+    const missing = [];
+    if (!existsSync(statusPath)) {
+        missing.push(`Status: ${statusPath}`);
+    }
+    if (!existsSync(backlogPath)) {
+        missing.push(`Backlog: ${backlogPath}`);
+    }
+    if (missing.length > 0) {
+        throw createFileNotFoundError(`Required metadata files missing:\n  ${missing.join('\n  ')}\n\nCannot complete WU - verify worktree has latest metadata files.`, { missingFiles: missing });
+    }
+}
+/**
+ * Update all metadata files for WU completion
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * WU-1572: Made async for WUStateStore integration
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID
+ * @param {string} params.title - WU title
+ * @param {object} params.doc - WU YAML document to update
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ */
+export async function updateMetadataFiles({ id, title, doc, wuPath, statusPath, backlogPath }) {
+    // WU-1275: Fail fast before any mutations
+    validateMetadataFilesExist({ statusPath, backlogPath });
+    const exposureUpdate = applyExposureDefaults(doc);
+    if (exposureUpdate.applied) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Auto-set exposure to ${exposureUpdate.exposure} for ${id}`);
+    }
+    // Update WU YAML (mark as done, lock, set completion timestamp)
+    doc.status = 'done';
+    doc.locked = true;
+    doc.completed_at = new Date().toISOString();
+    writeWU(wuPath, doc);
+    // Update status.md (remove from In Progress, add to Completed)
+    updateStatusRemoveInProgress(statusPath, id);
+    addToStatusCompleted(statusPath, id, title);
+    // Update backlog.md (move to Done section)
+    // WU-1572: Now async for state store integration
+    await moveWUToDoneBacklog(backlogPath, id, title);
+    // Create completion stamp
+    createStamp({ id, title });
+}
+/**
+ * Collect metadata updates to a transaction (WU-1369: Atomic pattern)
+ *
+ * This is the atomic version of updateMetadataFiles.
+ * Instead of writing files immediately, it collects all changes
+ * into a WUTransaction object for atomic commit.
+ *
+ * Usage:
+ * ```js
+ * const tx = new WUTransaction(id);
+ * collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction: tx });
+ * // All changes are now in tx.pendingWrites
+ * // Validate, then commit or abort
+ * tx.commit();
+ * ```
+ *
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID
+ * @param {string} params.title - WU title
+ * @param {object} params.doc - WU YAML document to update (will be mutated)
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @param {string} params.stampPath - Path to stamp file
+ * @param {WUTransaction} params.transaction - Transaction to add writes to
+ */
+// WU-1574: Made async for computeBacklogContent
+export async function collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction, }) {
+    // WU-1369: Fail fast before any computations
+    validateMetadataFilesExist({ statusPath, backlogPath });
+    const exposureUpdate = applyExposureDefaults(doc);
+    if (exposureUpdate.applied) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Auto-set exposure to ${exposureUpdate.exposure} for ${id}`);
+    }
+    // Compute WU YAML content (mutates doc, returns YAML string)
+    const wuYAMLContent = computeWUYAMLContent(doc);
+    transaction.addWrite(wuPath, wuYAMLContent, 'WU YAML');
+    // Compute status.md content
+    const statusContent = computeStatusContent(statusPath, id, title);
+    transaction.addWrite(statusPath, statusContent, 'status.md');
+    // Compute backlog.md content (WU-1574: now async)
+    const backlogContent = await computeBacklogContent(backlogPath, id, title);
+    transaction.addWrite(backlogPath, backlogContent, 'backlog.md');
+    const wuEventsUpdate = await computeWUEventsContentAfterComplete(backlogPath, id);
+    if (wuEventsUpdate) {
+        transaction.addWrite(wuEventsUpdate.eventsPath, wuEventsUpdate.content, 'wu-events.jsonl');
+    }
+    // Compute stamp content
+    const stampContent = computeStampContent(id, title);
+    transaction.addWrite(stampPath, stampContent, 'completion stamp');
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Collected ${transaction.size} metadata updates for atomic commit`);
+}
+/**
+ * Stage and format metadata files
+ * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
+ * @param {object} params - Parameters object
+ * @param {string} params.id - WU ID (for error reporting)
+ * @param {string} params.wuPath - Path to WU YAML file
+ * @param {string} params.statusPath - Path to status.md file
+ * @param {string} params.backlogPath - Path to backlog.md file
+ * @param {string} params.stampsDir - Path to stamps directory
+ * @throws {Error} If formatting fails
+ */
+export async function stageAndFormatMetadata({ id, wuPath, statusPath, backlogPath, stampsDir }) {
+    // WU-1235: Use getGitForCwd() to capture current directory (worktree after chdir)
+    // The singleton git adapter captures cwd at import time, which is wrong after process.chdir()
+    const gitCwd = getGitForCwd();
+    // Stage files
+    const wuEventsPath = path.join(BEACON_PATHS.STATE_DIR, WU_EVENTS_FILE_NAME);
+    const filesToStage = [wuPath, statusPath, backlogPath, stampsDir];
+    if (existsSync(wuEventsPath)) {
+        filesToStage.push(wuEventsPath);
+    }
+    await gitCwd.add(filesToStage);
+    // Format documentation
+    console.log(`${LOG_PREFIX.DONE} Formatting auto-generated documentation...`);
+    try {
+        const prettierCmd = `${PKG_MANAGER} ${SCRIPTS.PRETTIER} ${PRETTIER_FLAGS.WRITE} "${wuPath}" "${statusPath}" "${backlogPath}"`;
+        await execAsync(prettierCmd);
+        await gitCwd.add([wuPath, statusPath, backlogPath]);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Documentation formatted`);
+    }
+    catch (err) {
+        throw createValidationError(`Failed to format documentation: ${err.message}`, {
+            wuId: id,
+            error: err.message,
+        });
+    }
+}