@lumenflow/core 1.3.0 → 1.3.2

package/dist/spec-branch-helpers.js

@@ -0,0 +1,192 @@
+/**
+ * Spec Branch Helpers
+ *
+ * WU-1062: External plan storage and no-main-write mode
+ *
+ * Provides helpers for working with spec branches (spec/wu-XXXX).
+ * wu:create writes to spec branches by default; wu:claim merges them to main.
+ *
+ * @module
+ */
+import { WU_PATHS } from './wu-paths.js';
+/**
+ * Spec branch prefix
+ */
+export const SPEC_BRANCH_PREFIX = 'spec/';
+/**
+ * WU source location constants
+ */
+export const WU_SOURCE = {
+    /** WU exists on main branch only */
+    MAIN: 'main',
+    /** WU exists on spec branch only */
+    SPEC_BRANCH: 'spec_branch',
+    /** WU exists on both main and spec branch */
+    BOTH: 'both',
+    /** WU not found anywhere */
+    NOT_FOUND: 'not_found',
+};
+/**
+ * Get the spec branch name for a WU
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Spec branch name (e.g., 'spec/wu-1062')
+ *
+ * @example
+ * getSpecBranchName('WU-1062') // 'spec/wu-1062'
+ */
+export function getSpecBranchName(wuId) {
+    return `${SPEC_BRANCH_PREFIX}${wuId.toLowerCase()}`;
+}
+/**
+ * Get the origin-qualified spec branch name
+ *
+ * @param {string} wuId - Work Unit ID
+ * @returns {string} Origin-qualified branch name (e.g., 'origin/spec/wu-1062')
+ */
+export function getOriginSpecBranch(wuId) {
+    return `origin/${getSpecBranchName(wuId)}`;
+}
+/**
+ * Check if a spec branch exists on origin
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<boolean>} True if spec branch exists
+ *
+ * @example
+ * const exists = await specBranchExists('WU-1062', git);
+ */
+export async function specBranchExists(wuId, git) {
+    try {
+        const originBranch = getOriginSpecBranch(wuId);
+        // Use branchExists if available, otherwise check with ls-remote
+        if ('branchExists' in git && typeof git.branchExists === 'function') {
+            return await git.branchExists(originBranch);
+        }
+        // Fallback: use ls-remote to check if branch exists
+        const result = await git.raw(['ls-remote', '--heads', 'origin', getSpecBranchName(wuId)]);
+        return result.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a WU exists on main branch
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<boolean>} True if WU YAML exists on main
+ */
+export async function isWUOnMain(wuId, git) {
+    try {
+        const wuPath = WU_PATHS.WU(wuId);
+        // Check if file exists on origin/main
+        await git.raw(['ls-tree', 'origin/main', '--', wuPath]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Merge spec branch to main branch (fast-forward only)
+ *
+ * This is used by wu:claim when a WU exists only on a spec branch.
+ * The spec branch is merged to main before creating the worktree.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @throws {Error} If merge fails (e.g., due to conflicts)
+ *
+ * @example
+ * await mergeSpecBranchToMain('WU-1062', git);
+ */
+export async function mergeSpecBranchToMain(wuId, git) {
+    const specBranch = getSpecBranchName(wuId);
+    const originSpecBranch = getOriginSpecBranch(wuId);
+    // Fetch the spec branch
+    await git.fetch('origin', specBranch);
+    // Merge with fast-forward only (safe merge)
+    await git.merge([originSpecBranch, '--ff-only']);
+}
+/**
+ * Delete spec branch after merge
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export async function deleteSpecBranch(wuId, git) {
+    const specBranch = getSpecBranchName(wuId);
+    try {
+        // Delete local branch if exists
+        await git.branch(['-d', specBranch]);
+    }
+    catch {
+        // Ignore if local branch doesn't exist
+    }
+    try {
+        // Delete remote branch
+        await git.push(['origin', '--delete', specBranch]);
+    }
+    catch {
+        // Ignore if remote branch doesn't exist
+    }
+}
+/**
+ * Determine the source of a WU (main, spec branch, both, or not found)
+ *
+ * Used by wu:claim to decide whether to merge spec branch before creating worktree.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<WUSourceType>} Source location constant
+ *
+ * @example
+ * const source = await getWUSource('WU-1062', git);
+ * if (source === WU_SOURCE.SPEC_BRANCH) {
+ *   await mergeSpecBranchToMain('WU-1062', git);
+ * }
+ */
+export async function getWUSource(wuId, git) {
+    // Check both locations in parallel for efficiency
+    const [onMain, hasSpecBranch] = await Promise.all([
+        isWUOnMain(wuId, git),
+        specBranchExists(wuId, git),
+    ]);
+    if (onMain && hasSpecBranch) {
+        return WU_SOURCE.BOTH;
+    }
+    if (onMain) {
+        return WU_SOURCE.MAIN;
+    }
+    if (hasSpecBranch) {
+        return WU_SOURCE.SPEC_BRANCH;
+    }
+    return WU_SOURCE.NOT_FOUND;
+}
+/**
+ * Create a spec branch from current HEAD
+ *
+ * Used by wu:create in default mode (no --direct flag).
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export async function createSpecBranch(wuId, git) {
+    const specBranch = getSpecBranchName(wuId);
+    // Create local branch
+    await git.checkoutLocalBranch(specBranch);
+}
+/**
+ * Push spec branch to origin
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export async function pushSpecBranch(wuId, git) {
+    const specBranch = getSpecBranchName(wuId);
+    // Push to origin
+    await git.push(['origin', specBranch]);
+}

package/dist/wu-consistency-checker.d.ts

@@ -30,6 +30,7 @@ export declare function checkWUConsistency(id: any, projectRoot?: string): Promi
         backlogInProgress?: undefined;
         statusInProgress?: undefined;
         hasWorktree?: undefined;
+        worktreePathExists?: undefined;
     };
 } | {
     valid: boolean;
@@ -41,6 +42,7 @@ export declare function checkWUConsistency(id: any, projectRoot?: string): Promi
         backlogInProgress: boolean;
         statusInProgress: boolean;
         hasWorktree: boolean;
+        worktreePathExists: boolean;
         wuExists?: undefined;
     };
 }>;

package/dist/wu-consistency-checker.js

@@ -17,7 +17,7 @@ import { constants } from 'node:fs';
 import path from 'node:path';
 import { parseYAML, stringifyYAML } from './wu-yaml.js';
 import { WU_PATHS } from './wu-paths.js';
-import { CONSISTENCY_TYPES, LOG_PREFIX, REMOTES, STRING_LITERALS, toKebab, WU_STATUS, YAML_OPTIONS, } from './wu-constants.js';
+import { CONSISTENCY_TYPES, CONSISTENCY_MESSAGES, LOG_PREFIX, REMOTES, STRING_LITERALS, toKebab, WU_STATUS, YAML_OPTIONS, } from './wu-constants.js';
 import { todayISO } from './date-utils.js';
 import { createGitForPath } from './git-adapter.js';
 /**
@@ -45,6 +45,7 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
     const yamlStatus = wuDoc?.status || 'unknown';
     const lane = wuDoc?.lane || '';
     const title = wuDoc?.title || '';
+    const worktreePathFromYaml = wuDoc?.worktree_path || '';
     // Check stamp existence
     let hasStamp = false;
     try {
@@ -74,6 +75,7 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
     const { inProgress: statusInProgress } = parseStatusSections(statusContent, id);
     // Check for worktree
     const hasWorktree = await checkWorktreeExists(id, projectRoot);
+    const worktreePathExists = await checkWorktreePathExists(worktreePathFromYaml);
     // Detection logic
     // 1. YAML done but in status.md In Progress
     if (yamlStatus === WU_STATUS.DONE && statusInProgress) {
@@ -129,6 +131,19 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
             canAutoRepair: true,
         });
     }
+    // 6. Claimed WU missing worktree directory
+    if (worktreePathFromYaml &&
+        !worktreePathExists &&
+        (yamlStatus === WU_STATUS.IN_PROGRESS || yamlStatus === WU_STATUS.BLOCKED)) {
+        errors.push({
+            type: CONSISTENCY_TYPES.MISSING_WORKTREE_CLAIMED,
+            wuId: id,
+            title,
+            description: CONSISTENCY_MESSAGES.MISSING_WORKTREE_CLAIMED(id, yamlStatus, worktreePathFromYaml),
+            repairAction: CONSISTENCY_MESSAGES.MISSING_WORKTREE_CLAIMED_REPAIR,
+            canAutoRepair: false,
+        });
+    }
     return {
         valid: errors.length === 0,
         errors,
@@ -139,6 +154,7 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
             backlogInProgress,
             statusInProgress,
             hasWorktree,
+            worktreePathExists,
         },
     };
 }
@@ -565,3 +581,21 @@ async function checkWorktreeExists(id, projectRoot) {
         return false;
     }
 }
+/**
+ * Check whether a worktree path exists on disk
+ *
+ * @param {string} worktreePath - Worktree path from WU YAML
+ * @returns {Promise<boolean>} True if path exists
+ */
+async function checkWorktreePathExists(worktreePath) {
+    if (!worktreePath) {
+        return false;
+    }
+    try {
+        await access(worktreePath, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/wu-constants.d.ts

@@ -40,6 +40,10 @@ export declare const GIT_REFS: {
     ORIGIN_MAIN: string;
     /** Current HEAD ref */
     HEAD: string;
+    /** Upstream ref */
+    UPSTREAM: string;
+    /** Range of upstream..HEAD */
+    UPSTREAM_RANGE: string;
     /** Fetch head ref */
     FETCH_HEAD: string;
 };
@@ -258,6 +262,22 @@ export declare const CONSISTENCY_TYPES: {
     ORPHAN_WORKTREE_DONE: string;
     /** Stamp file exists but WU YAML status is not 'done' (partial wu:done failure) */
     STAMP_EXISTS_YAML_NOT_DONE: string;
+    /** WU is claimed but its worktree directory is missing */
+    MISSING_WORKTREE_CLAIMED: string;
+};
+/**
+ * Consistency check messages
+ */
+export declare const CONSISTENCY_MESSAGES: {
+    MISSING_WORKTREE_CLAIMED: (id: any, status: any, worktreePath: any) => string;
+    MISSING_WORKTREE_CLAIMED_REPAIR: string;
+};
+/**
+ * Worktree warning messages
+ */
+export declare const WORKTREE_WARNINGS: {
+    MISSING_TRACKED_HEADER: string;
+    MISSING_TRACKED_LINE: (worktreePath: any) => string;
 };
 /**
  * File system constants
@@ -404,6 +424,59 @@ export declare const BOX: {
     /** Side border for content lines */
     SIDE: string;
 };
+/**
+ * Cleanup guard constants
+ */
+export declare const CLEANUP_GUARD: {
+    REASONS: {
+        UNCOMMITTED_CHANGES: string;
+        UNPUSHED_COMMITS: string;
+        STATUS_NOT_DONE: string;
+        MISSING_STAMP: string;
+        PR_NOT_MERGED: string;
+    };
+    TITLES: {
+        BLOCKED: string;
+        NEXT_STEPS: string;
+    };
+    MESSAGES: {
+        UNCOMMITTED_CHANGES: string;
+        UNPUSHED_COMMITS: string;
+        STATUS_NOT_DONE: string;
+        MISSING_STAMP: string;
+        PR_NOT_MERGED: string;
+    };
+    NEXT_STEPS: {
+        DEFAULT: {
+            text: string;
+            appendId: boolean;
+        }[];
+        UNCOMMITTED_CHANGES: {
+            text: string;
+            appendId: boolean;
+        }[];
+        UNPUSHED_COMMITS: {
+            text: string;
+            appendId: boolean;
+        }[];
+        STATUS_NOT_DONE: {
+            text: string;
+            appendId: boolean;
+        }[];
+        MISSING_STAMP: {
+            text: string;
+            appendId: boolean;
+        }[];
+        PR_NOT_MERGED: {
+            text: string;
+            appendId: boolean;
+        }[];
+    };
+    PR_CHECK: {
+        START: string;
+        RESULT: string;
+    };
+};
 /**
  * Git display constants
  *
@@ -471,6 +544,8 @@ export declare const GIT_FLAGS: {
     NO_VERIFY: string;
     /** No GPG sign flag (skip commit signing) */
     NO_GPG_SIGN: string;
+    /** One-line log format */
+    ONELINE: string;
 };
 /**
  * Git commands
@@ -487,6 +562,8 @@ export declare const GIT_COMMANDS: {
     LS_TREE: string;
     /** Git diff command */
     DIFF: string;
+    /** Git log command */
+    LOG: string;
     /** Git merge-base command */
     MERGE_BASE: string;
     /** Git rev-parse command */

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
@@ -426,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
  *
@@ -493,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
@@ -509,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 */

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,