@lumenflow/core 1.0.0 → 1.3.2

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

@@ -0,0 +1,108 @@
+/**
+ * @file wu-done-docs-generate.ts
+ * @description Documentation regeneration utilities for wu:done
+ *
+ * WU-1061: Integrate docs:generate into wu:done for @lumenflow/* changes
+ *
+ * Detects changes to files that affect generated documentation and triggers
+ * regeneration during wu:done (after gates pass, before metadata commit).
+ */
+import { execSync } from 'node:child_process';
+import { getGitForCwd } from './git-adapter.js';
+import { STDIO } from './wu-constants.js';
+/**
+ * Pathspecs for files that affect generated documentation.
+ * When any of these files change, docs:generate should be run.
+ *
+ * Based on .husky/hooks/docs-sync.mjs patterns, expanded to match
+ * all files that can affect CLI/config documentation.
+ */
+export const DOC_SOURCE_PATHSPECS = [
+    'tools/generate-cli-docs.ts',
+    'packages/@lumenflow/core/src/arg-parser.ts',
+    'packages/@lumenflow/core/src/lumenflow-config-schema.ts',
+    'packages/@lumenflow/core/src/index.ts',
+    'packages/@lumenflow/cli/package.json',
+    'packages/@lumenflow/cli/src/',
+];
+/**
+ * Output files generated by docs:generate.
+ * These files are staged before the metadata commit.
+ */
+export const DOC_OUTPUT_FILES = [
+    'apps/docs/src/content/docs/reference/cli.mdx',
+    'apps/docs/src/content/docs/reference/config.mdx',
+];
+/**
+ * Check if any doc-source files changed compared to the base branch.
+ * Uses git diff with pathspecs for efficient detection.
+ *
+ * @param baseBranch - Base branch for comparison (e.g., 'main', 'origin/main')
+ * @returns Promise<boolean> - True if doc-source files changed
+ */
+export async function hasDocSourceChanges(baseBranch) {
+    try {
+        const gitAdapter = getGitForCwd();
+        const diff = await gitAdapter.raw([
+            'diff',
+            `${baseBranch}...HEAD`,
+            '--name-only',
+            '--',
+            ...DOC_SOURCE_PATHSPECS,
+        ]);
+        return diff.trim().length > 0;
+    }
+    catch {
+        // Fail-safe: don't regenerate on git errors
+        return false;
+    }
+}
+/**
+ * Stage doc output files for the metadata commit.
+ *
+ * @returns Promise<void>
+ */
+export async function stageDocOutputs() {
+    const gitAdapter = getGitForCwd();
+    await gitAdapter.add([...DOC_OUTPUT_FILES]);
+}
+/**
+ * Run turbo docs:generate to regenerate documentation.
+ * Turbo handles build dependencies and caching.
+ *
+ * @param repoRoot - Repository root directory
+ * @returns void
+ */
+export function runDocsGenerate(repoRoot) {
+    execSync('pnpm turbo docs:generate', {
+        cwd: repoRoot,
+        stdio: STDIO.INHERIT,
+        encoding: 'utf-8',
+    });
+}
+/**
+ * Detect doc-source changes and regenerate docs if needed.
+ * This is the main integration point for wu:done.
+ *
+ * Call this BEFORE stageAndFormatMetadata() to include doc outputs
+ * in the single atomic commit.
+ *
+ * @param options - Detection and regeneration options
+ * @returns Promise<DocsRegenerationResult> - Whether docs changed and were regenerated
+ */
+export async function maybeRegenerateAndStageDocs(options) {
+    const { baseBranch, repoRoot } = options;
+    // Check if doc-source files changed
+    const docsChanged = await hasDocSourceChanges(baseBranch);
+    if (!docsChanged) {
+        console.log('[wu:done] No doc-source changes detected, skipping docs:generate');
+        return { docsChanged: false, regenerated: false };
+    }
+    console.log('[wu:done] Doc-source changes detected, running turbo docs:generate...');
+    // Run turbo docs:generate (Turbo handles caching and dependencies)
+    runDocsGenerate(repoRoot);
+    // Stage the doc output files
+    await stageDocOutputs();
+    console.log('[wu:done] Documentation regenerated and staged');
+    return { docsChanged: true, regenerated: true };
+}

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,
+        });
+    }
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Path and workspace detection helpers for wu:done.
+ */
+/**
+ * Read WU YAML preferring worktree version over main version
+ *
+ * WU-1584 Fix #4: Added diagnostic logging to confirm which YAML file is being
+ * read for code_paths validation. This helps debug issues where worktree YAML
+ * differs from main checkout YAML.
+ *
+ * @param {string} id - WU ID
+ * @param {string|null} worktreePath - Worktree path (null if branch-only mode)
+ * @param {string} mainWUPath - Path to WU YAML in main checkout
+ * @returns {object} Parsed WU document
+ */
+export declare function readWUPreferWorktree(id: any, worktreePath: any, mainWUPath: any): any;
+/**
+ * Detect if currently running inside a worktree
+ * Checks for .git file (not directory) which indicates a worktree
+ * @returns {string|null} Current directory path if inside worktree, null otherwise
+ */
+export declare function detectCurrentWorktree(): string;
+/**
+ * Resolve worktree path from WU YAML
+ * Originally implemented in WU-1226, extracted to validators module in WU-1215
+ * Priority:
+ * 1. Read worktree_path field (set at claim time, immune to lane field changes)
+ * 2. Fall back to calculating from lane field (for old WUs without worktree_path)
+ * 3. Use git worktree list to find actual path (defensive fallback)
+ * @param {object} doc - WU YAML document
+ * @returns {Promise<string|null>} - Worktree path or null if not found
+ */
+export declare function defaultWorktreeFrom(doc: any): Promise<any>;
+/**
+ * Detect workspace mode from WU YAML
+ * @param {object} doc - WU YAML document
+ * @returns {'worktree' | 'branch-only'}
+ */
+export declare function detectWorkspaceMode(doc: any): string;
+/**
+ * Calculate lane branch name from WU YAML
+ * @param {object} doc - WU YAML document
+ * @returns {string|null} Lane branch name (e.g., lane/operations-tooling/wu-1215)
+ */
+export declare function defaultBranchFrom(doc: any): string;
+/**
+ * Check if a branch exists
+ * @param {string} branch - Branch name to check
+ * @returns {Promise<boolean>} True if branch exists
+ */
+export declare function branchExists(branch: any): Promise<boolean>;
+/**
+ * Detect workspace mode and calculate all relevant paths
+ * @param {string} id - WU ID
+ * @param {object} args - Parsed command-line arguments
+ * @returns {Promise<object>} Object containing paths, mode info, and WU document
+ */
+export declare function detectModeAndPaths(id: any, args: any): Promise<{
+    WU_PATH: string;
+    STATUS_PATH: string;
+    BACKLOG_PATH: string;
+    STAMPS_DIR: string;
+    docMain: any;
+    workspaceMode: string;
+    isBranchOnly: boolean;
+    derivedWorktree: any;
+    docForValidation: any;
+    isDocsOnly: boolean;
+}>;