@lumenflow/core 1.0.0 → 1.3.2

package/dist/wu-constants.js

@@ -42,6 +42,10 @@ export const GIT_REFS = {
     ORIGIN_MAIN: 'origin/main',
     /** Current HEAD ref */
     HEAD: 'HEAD',
+    /** Upstream ref */
+    UPSTREAM: '@{u}',
+    /** Range of upstream..HEAD */
+    UPSTREAM_RANGE: '@{u}..HEAD',
     /** Fetch head ref */
     FETCH_HEAD: 'FETCH_HEAD',
 };
@@ -273,6 +277,22 @@ export const CONSISTENCY_TYPES = {
     ORPHAN_WORKTREE_DONE: 'ORPHAN_WORKTREE_DONE',
     /** Stamp file exists but WU YAML status is not 'done' (partial wu:done failure) */
     STAMP_EXISTS_YAML_NOT_DONE: 'STAMP_EXISTS_YAML_NOT_DONE',
+    /** WU is claimed but its worktree directory is missing */
+    MISSING_WORKTREE_CLAIMED: 'MISSING_WORKTREE_CLAIMED',
+};
+/**
+ * Consistency check messages
+ */
+export const CONSISTENCY_MESSAGES = {
+    MISSING_WORKTREE_CLAIMED: (id, status, worktreePath) => `WU ${id} is '${status}' but worktree path is missing (${worktreePath})`,
+    MISSING_WORKTREE_CLAIMED_REPAIR: 'Recover worktree or re-claim WU',
+};
+/**
+ * Worktree warning messages
+ */
+export const WORKTREE_WARNINGS = {
+    MISSING_TRACKED_HEADER: 'Tracked worktrees missing on disk (possible manual deletion):',
+    MISSING_TRACKED_LINE: (worktreePath) => `Missing: ${worktreePath}`,
 };
 /**
  * File system constants
@@ -285,6 +305,30 @@ export const FILE_SYSTEM = {
     /** UTF-8 encoding (alias for compatibility) */
     UTF8: 'utf8',
 };
+/**
+ * Build artifact cleanup globs
+ *
+ * Centralized glob patterns for worktree artifact cleanup.
+ */
+export const BUILD_ARTIFACT_GLOBS = {
+    /** Common dist directories inside worktrees */
+    DIST_DIRS: [
+        'packages/*/dist',
+        'packages/**/dist',
+        'apps/*/dist',
+        'apps/**/dist',
+        'tools/*/dist',
+        'tools/**/dist',
+    ],
+    /** TypeScript build info files */
+    TSBUILDINFO_FILES: ['**/*.tsbuildinfo'],
+};
+/**
+ * Build artifact cleanup ignore patterns
+ *
+ * Centralized ignore globs for artifact cleanup.
+ */
+export const BUILD_ARTIFACT_IGNORES = ['**/node_modules/**', '**/.git/**', '**/.turbo/**'];
 /**
  * Process stdio constants
  *
@@ -367,12 +411,12 @@ export const DEFAULTS = {
  * YAML serialization options
  *
  * Centralized from duplicated { lineWidth: 100 } across wu-* scripts (WU-1256).
- * Use with js-yaml dump() function.
+ * Use with yaml stringify() options.
  */
 export const YAML_OPTIONS = {
     /** Standard line width for YAML dump (100 chars) */
     LINE_WIDTH: 100,
-    /** No line wrapping (-1 disables wrapping in js-yaml) */
+    /** No line wrapping (-1 disables wrapping) */
     NO_WRAP: -1,
 };
 /**
@@ -402,6 +446,62 @@ export const BOX = {
     /** Side border for content lines */
     SIDE: '║',
 };
+/**
+ * Cleanup guard constants
+ */
+export const CLEANUP_GUARD = {
+    REASONS: {
+        UNCOMMITTED_CHANGES: 'UNCOMMITTED_CHANGES',
+        UNPUSHED_COMMITS: 'UNPUSHED_COMMITS',
+        STATUS_NOT_DONE: 'STATUS_NOT_DONE',
+        MISSING_STAMP: 'MISSING_STAMP',
+        PR_NOT_MERGED: 'PR_NOT_MERGED',
+    },
+    TITLES: {
+        BLOCKED: 'CLEANUP BLOCKED',
+        NEXT_STEPS: 'Next steps:',
+    },
+    MESSAGES: {
+        UNCOMMITTED_CHANGES: 'Worktree has uncommitted changes. Refusing to delete.',
+        UNPUSHED_COMMITS: 'Worktree has unpushed commits. Refusing to delete.',
+        STATUS_NOT_DONE: 'WU YAML status is not done. Refusing to delete.',
+        MISSING_STAMP: 'WU stamp is missing. Refusing to delete.',
+        PR_NOT_MERGED: 'PR is not merged (or cannot be verified). Refusing to delete.',
+    },
+    NEXT_STEPS: {
+        DEFAULT: [
+            { text: '1. Resolve the issue above', appendId: false },
+            { text: '2. Re-run: pnpm wu:cleanup --id', appendId: true },
+        ],
+        UNCOMMITTED_CHANGES: [
+            { text: '1. Commit or stash changes in the worktree', appendId: false },
+            { text: '2. Re-run: pnpm wu:cleanup --id', appendId: true },
+        ],
+        UNPUSHED_COMMITS: [
+            { text: '1. Push the lane branch to origin', appendId: false },
+            { text: '2. Re-run: pnpm wu:cleanup --id', appendId: true },
+        ],
+        STATUS_NOT_DONE: [
+            {
+                text: `1. Complete the WU with ${LOG_PREFIX.DONE} (creates stamp + done status)`,
+                appendId: false,
+            },
+            { text: '2. Re-run: pnpm wu:cleanup --id', appendId: true },
+        ],
+        MISSING_STAMP: [
+            { text: '1. Run wu:done to create the stamp file', appendId: false },
+            { text: '2. Re-run: pnpm wu:cleanup --id', appendId: true },
+        ],
+        PR_NOT_MERGED: [
+            { text: '1. Merge the PR in GitHub', appendId: false },
+            { text: '2. Re-run: pnpm wu:cleanup --id', appendId: true },
+        ],
+    },
+    PR_CHECK: {
+        START: 'Verifying PR merge status...',
+        RESULT: 'PR merge verification via',
+    },
+};
 /**
  * Git display constants
  *
@@ -469,6 +569,8 @@ export const GIT_FLAGS = {
     NO_VERIFY: '--no-verify',
     /** No GPG sign flag (skip commit signing) */
     NO_GPG_SIGN: '--no-gpg-sign',
+    /** One-line log format */
+    ONELINE: '--oneline',
 };
 /**
  * Git commands
@@ -485,6 +587,8 @@ export const GIT_COMMANDS = {
     LS_TREE: 'ls-tree',
     /** Git diff command */
     DIFF: 'diff',
+    /** Git log command */
+    LOG: 'log',
     /** Git merge-base command */
     MERGE_BASE: 'merge-base',
     /** Git rev-parse command */
@@ -951,7 +1055,6 @@ export const ESLINT_DEFAULTS = {
      *
      * WU-1866: Temporarily increased from 0 to 100 to unblock gates.
      * There are ~82 pre-existing warnings that need proper fixes.
-     * TODO: Create follow-up WU to fix warnings and restore zero-warnings policy.
      */
     MAX_WARNINGS: '100',
 };
@@ -1030,6 +1133,8 @@ export const GITLEAKS_ARGS = {
 export const PRETTIER_ARGS = {
     /** Check formatting without writing */
     CHECK: '--check',
+    /** List files with formatting differences */
+    LIST_DIFFERENT: '--list-different',
 };
 /**
  * Audit command arguments

package/dist/wu-create-validators.d.ts

@@ -1,11 +1,16 @@
 /**
- * WU Create Validators (WU-2107)
+ * WU Create Validators (WU-2107, WU-1062)
  *
- * Validation helpers for wu:create, including lane inference surfacing.
+ * Validation helpers for wu:create, including:
+ * - Lane inference surfacing (WU-2107)
+ * - External spec_refs validation (WU-1062)
  *
  * When agents create WUs, this module helps surface lane inference suggestions
  * to guide better lane selection and improve parallelization.
  *
+ * WU-1062: Validates spec_refs paths, accepting both repo-relative paths
+ * and external paths (lumenflow://, ~/.lumenflow/, $LUMENFLOW_HOME/).
+ *
  * NOTE: This is domain-specific WU workflow code, not a general utility.
  * No external library exists for LumenFlow lane inference validation.
  */
@@ -40,3 +45,36 @@ export declare function validateLaneWithInference(providedLane: any, codePaths:
     inferredLane: any;
     confidence: any;
 };
+/**
+ * WU-1062: Validate spec_refs paths
+ *
+ * Accepts:
+ * - Repo-relative paths: docs/04-operations/plans/WU-XXX-plan.md
+ * - External paths: lumenflow://plans/WU-XXX-plan.md
+ * - Tilde paths: ~/.lumenflow/plans/WU-XXX-plan.md
+ * - Env var paths: $LUMENFLOW_HOME/plans/WU-XXX-plan.md
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }} Validation result
+ */
+export declare function validateSpecRefs(specRefs: string[]): {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+};
+/**
+ * WU-1062: Check if spec_refs contains external paths
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {boolean} True if any spec_ref is an external path
+ */
+export declare function hasExternalSpecRefs(specRefs: string[]): boolean;
+/**
+ * WU-1062: Normalize all spec_refs paths
+ *
+ * Expands external paths to absolute paths while keeping repo-relative paths unchanged.
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {string[]} Normalized paths
+ */
+export declare function normalizeSpecRefs(specRefs: string[]): string[];

package/dist/wu-create-validators.js

@@ -1,14 +1,20 @@
 /**
- * WU Create Validators (WU-2107)
+ * WU Create Validators (WU-2107, WU-1062)
  *
- * Validation helpers for wu:create, including lane inference surfacing.
+ * Validation helpers for wu:create, including:
+ * - Lane inference surfacing (WU-2107)
+ * - External spec_refs validation (WU-1062)
  *
  * When agents create WUs, this module helps surface lane inference suggestions
  * to guide better lane selection and improve parallelization.
  *
+ * WU-1062: Validates spec_refs paths, accepting both repo-relative paths
+ * and external paths (lumenflow://, ~/.lumenflow/, $LUMENFLOW_HOME/).
+ *
  * NOTE: This is domain-specific WU workflow code, not a general utility.
  * No external library exists for LumenFlow lane inference validation.
  */
+import { isExternalPath, normalizeSpecRef } from './lumenflow-home.js';
 /** Confidence threshold for showing suggestion (percentage) */
 const CONFIDENCE_THRESHOLD_LOW = 30;
 /**
@@ -91,3 +97,71 @@ export function validateLaneWithInference(providedLane, codePaths, description,
         return { shouldWarn: false, warning: '' };
     }
 }
+/**
+ * WU-1062: Validate spec_refs paths
+ *
+ * Accepts:
+ * - Repo-relative paths: docs/04-operations/plans/WU-XXX-plan.md
+ * - External paths: lumenflow://plans/WU-XXX-plan.md
+ * - Tilde paths: ~/.lumenflow/plans/WU-XXX-plan.md
+ * - Env var paths: $LUMENFLOW_HOME/plans/WU-XXX-plan.md
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }} Validation result
+ */
+export function validateSpecRefs(specRefs) {
+    const errors = [];
+    const warnings = [];
+    if (!specRefs || specRefs.length === 0) {
+        return { valid: true, errors, warnings };
+    }
+    for (const ref of specRefs) {
+        // Check for empty refs
+        if (!ref || ref.trim().length === 0) {
+            errors.push('Empty spec_ref detected');
+            continue;
+        }
+        // External paths are valid (will be resolved at runtime)
+        if (isExternalPath(ref)) {
+            // Add informational warning about external paths
+            warnings.push(`External spec_ref: "${ref}" - ensure plan exists at ${normalizeSpecRef(ref)}`);
+            continue;
+        }
+        // Repo-relative paths should follow conventions
+        const isValidRepoPath = ref.startsWith('docs/') || ref.startsWith('./docs/') || ref.endsWith('.md');
+        if (!isValidRepoPath) {
+            warnings.push(`Unconventional spec_ref path: "${ref}" - consider using docs/04-operations/plans/ or lumenflow://plans/`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * WU-1062: Check if spec_refs contains external paths
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {boolean} True if any spec_ref is an external path
+ */
+export function hasExternalSpecRefs(specRefs) {
+    if (!specRefs || specRefs.length === 0) {
+        return false;
+    }
+    return specRefs.some((ref) => isExternalPath(ref));
+}
+/**
+ * WU-1062: Normalize all spec_refs paths
+ *
+ * Expands external paths to absolute paths while keeping repo-relative paths unchanged.
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {string[]} Normalized paths
+ */
+export function normalizeSpecRefs(specRefs) {
+    if (!specRefs || specRefs.length === 0) {
+        return [];
+    }
+    return specRefs.map((ref) => normalizeSpecRef(ref));
+}

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

@@ -23,6 +23,8 @@ import { die, createError, ErrorCodes } from './error-handler.js';
 import { validateWU, validateDoneWU } from './wu-schema.js';
 import { assertTransition } from './state-machine.js';
 import { detectZombieState, recoverZombieState } from './wu-recovery.js';
+// WU-1061: Import docs regeneration utilities
+import { maybeRegenerateAndStageDocs } from './wu-done-docs-generate.js';
 /**
  * @typedef {Object} BranchOnlyContext
  * @property {string} id - WU ID (e.g., "WU-1215")
@@ -119,6 +121,13 @@ export async function executeBranchOnlyCompletion(context) {
             statusPath: metadataStatusPath,
             backlogPath: metadataBacklogPath,
         });
+        // WU-1061: Regenerate docs if doc-source files changed
+        // This runs BEFORE stageAndFormatMetadata to include doc outputs
+        // in the single atomic commit
+        await maybeRegenerateAndStageDocs({
+            baseBranch: BRANCHES.MAIN,
+            repoRoot: metadataBasePath,
+        });
         // Step 7: Stage and format files
         await stageAndFormatMetadata({
             id,

package/dist/wu-done-branch-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Branch utilities for wu:done workflows.
+ */
+/**
+ * Check if branch is already merged to main
+ *
+ * @param {string} branch - Lane branch name
+ * @returns {Promise<boolean>} Whether branch is already merged
+ */
+export declare function isBranchAlreadyMerged(branch: any): Promise<boolean>;

package/dist/wu-done-branch-utils.js

@@ -0,0 +1,31 @@
+/**
+ * Branch utilities for wu:done workflows.
+ */
+import { getGitForCwd } from './git-adapter.js';
+import { BRANCHES, LOG_PREFIX } from './wu-constants.js';
+import { PREFLIGHT } from './wu-done-messages.js';
+/** @constant {number} SHA_SHORT_LENGTH - Length of shortened git SHA hashes for display */
+const SHA_SHORT_LENGTH = 8;
+/**
+ * Check if branch is already merged to main
+ *
+ * @param {string} branch - Lane branch name
+ * @returns {Promise<boolean>} Whether branch is already merged
+ */
+export async function isBranchAlreadyMerged(branch) {
+    const gitAdapter = getGitForCwd();
+    try {
+        const branchTip = (await gitAdapter.getCommitHash(branch)).trim();
+        const mergeBase = (await gitAdapter.mergeBase(BRANCHES.MAIN, branch)).trim();
+        const mainHead = (await gitAdapter.getCommitHash(BRANCHES.MAIN)).trim();
+        if (branchTip === mergeBase) {
+            console.log(PREFLIGHT.BRANCH_INFO(branch, branchTip.substring(0, SHA_SHORT_LENGTH), mergeBase.substring(0, SHA_SHORT_LENGTH), mainHead.substring(0, SHA_SHORT_LENGTH)));
+            return true;
+        }
+        return false;
+    }
+    catch (e) {
+        console.warn(`${LOG_PREFIX.DONE} Warning: Could not check if branch is merged: ${e.message}`);
+        return false;
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Cleanup helpers for wu:done.
+ */
+/**
+ * Run cleanup operations after successful merge
+ * Removes worktree and optionally deletes lane branch
+ */
+export declare function runCleanup(docMain: any, args: any): Promise<void>;

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-generate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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).
+ */
+/**
+ * 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 declare const DOC_SOURCE_PATHSPECS: readonly ["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 declare const DOC_OUTPUT_FILES: readonly ["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 declare function hasDocSourceChanges(baseBranch: string): Promise<boolean>;
+/**
+ * Stage doc output files for the metadata commit.
+ *
+ * @returns Promise<void>
+ */
+export declare function stageDocOutputs(): Promise<void>;
+/**
+ * Run turbo docs:generate to regenerate documentation.
+ * Turbo handles build dependencies and caching.
+ *
+ * @param repoRoot - Repository root directory
+ * @returns void
+ */
+export declare function runDocsGenerate(repoRoot: string): void;
+/**
+ * Result of the docs regeneration check.
+ */
+export interface DocsRegenerationResult {
+    /** Whether doc-source files changed */
+    docsChanged: boolean;
+    /** Whether docs were regenerated */
+    regenerated: boolean;
+}
+/**
+ * Options for maybeRegenerateAndStageDocs.
+ */
+export interface MaybeRegenerateDocsOptions {
+    /** Base branch for comparison (e.g., 'main', calculated from defaultBranchFrom) */
+    baseBranch: string;
+    /** Repository root directory for running turbo */
+    repoRoot: string;
+}
+/**
+ * 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 declare function maybeRegenerateAndStageDocs(options: MaybeRegenerateDocsOptions): Promise<DocsRegenerationResult>;