@lumenflow/core 1.0.0

package/dist/wu-done-messages.js

@@ -0,0 +1,185 @@
+/**
+ * @file wu-done-messages.mjs
+ * @description Constants and message templates for wu-done operations
+ * WU-1159: Eliminate string literals (DRY/SOLID compliance)
+ * WU-1281: Use centralized LOG_PREFIX and EMOJI from wu-constants.mjs
+ *
+ * All log messages, error messages, and text templates extracted to constants.
+ * Prevents duplication and makes text maintainable.
+ */
+import { LOG_PREFIX, EMOJI, REMOTES, BRANCHES } from './wu-constants.js';
+// Re-export LOG_PREFIX for backwards compatibility
+export { LOG_PREFIX };
+/**
+ * Recovery mode messages (WU-1159)
+ */
+export const RECOVERY = {
+    DETECTED: `${LOG_PREFIX.DONE} ${EMOJI.WARNING} RECOVERY MODE: Status is already "done" but worktree exists.`,
+    RESUMING: `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Resuming cleanup to complete the WU...`,
+    EXPLANATION: `${LOG_PREFIX.DONE} This typically happens when a previous wu:done crashed mid-completion.`,
+    CREATING_STAMP: `${LOG_PREFIX.DONE} Creating missing stamp file...`,
+    STAMP_CREATED: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Stamp file created`,
+    UPDATING_YAML: `${LOG_PREFIX.DONE} Updating WU YAML to ensure completion markers...`,
+    YAML_UPDATED: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} WU YAML updated with completion markers`,
+    UPDATING_DOCS: `${LOG_PREFIX.DONE} Ensuring status.md and backlog.md are updated...`,
+    DOCS_UPDATED: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Documentation files verified`,
+    COMMITTING: `${LOG_PREFIX.DONE} Committing recovery changes to prevent data loss...`,
+    COMMIT_SUCCESS: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Recovery changes committed to main`,
+    COMMIT_FAILED: (error) => `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not commit recovery changes: ${error} (metadata still on disk)`,
+    MARKERS_VERIFIED: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Recovery mode: All completion markers verified`,
+    PROCEEDING_CLEANUP: `${LOG_PREFIX.DONE} Proceeding to cleanup (worktree removal and branch deletion)...`,
+    SUCCESS: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Recovery mode successful - zombie state cleaned up`,
+};
+/**
+ * Worktree operations
+ */
+export const WORKTREE = {
+    REMOVED: (path) => `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Removed worktree ${path}`,
+    NOT_FOUND: `${LOG_PREFIX.DONE} Worktree not found; skipping removal`,
+    REMOVE_FAILED: (path, error) => `${LOG_PREFIX.DONE} Could not remove worktree ${path}: ${error}`,
+    PRESERVED_PR_MODE: `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Worktree preserved (PR mode - run wu:cleanup after PR merge)`,
+};
+/**
+ * Branch operations
+ */
+export const BRANCH = {
+    DELETED_LOCAL: (branch) => `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Deleted local branch ${branch}`,
+    DELETED_REMOTE: (branch) => `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Deleted remote branch ${branch}`,
+    DELETE_FAILED: (branch, error) => `${LOG_PREFIX.DONE} Could not delete branch ${branch}: ${error}`,
+    DELETE_REMOTE_FAILED: (error) => `${LOG_PREFIX.DONE} Could not delete remote branch: ${error}`,
+    PRESERVED_PR_MODE: `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Branch preserved (PR mode - delete manually after merge)`,
+};
+/**
+ * Completion messages
+ */
+export const COMPLETION = {
+    SUCCESS_HEADER: (id, title) => `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Marked done, pushed, and cleaned up.\n- WU: ${id} — ${title}`,
+    TRANSACTION_COMMIT: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Transaction COMMIT - all steps succeeded (WU-755)`,
+};
+/**
+ * State transition errors
+ */
+export const STATE_TRANSITION = {
+    VALIDATION_FAILED: (error) => `State transition validation failed: ${error}`,
+};
+/**
+ * Auto-rebase messages (WU-1303)
+ */
+export const REBASE = {
+    STARTING: (branch, mainBranch) => `${LOG_PREFIX.DONE} ${EMOJI.WRENCH} Auto-rebasing ${branch} onto ${mainBranch}...`,
+    SUCCESS: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Auto-rebase completed successfully`,
+    FAILED: (error) => `${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Auto-rebase failed: ${error}`,
+    ABORTED: `${LOG_PREFIX.DONE} ${EMOJI.INFO} Rebase aborted - worktree left clean`,
+    MANUAL_FIX: (worktreePath, remote, mainBranch, branch) => `Auto-rebase failed due to conflicts.\n\n` +
+        `Manual resolution required:\n` +
+        `  1. cd ${worktreePath}\n` +
+        `  2. git fetch ${remote} ${mainBranch}\n` +
+        `  3. git rebase ${remote}/${mainBranch}\n` +
+        `  4. Resolve conflicts and run: git rebase --continue\n` +
+        `  5. git push --force-with-lease ${remote} ${branch}\n` +
+        `  6. Return to main checkout and retry: pnpm wu:done --id <WU-ID>`,
+};
+/**
+ * Pre-flight check messages (WU-755, WU-1303, WU-1370)
+ */
+export const PREFLIGHT = {
+    RUNNING: `\n${LOG_PREFIX.DONE} Running pre-flight checks (WU-755)...`,
+    BRANCH_BEHIND: (commitsBehind, threshold) => `${LOG_PREFIX.DONE} ${EMOJI.INFO} Branch is ${commitsBehind} commits behind main (threshold: ${threshold})`,
+    // WU-1370: Graduated drift warning messages
+    BRANCH_DRIFT_INFO: (commitsBehind) => `${LOG_PREFIX.DONE} ${EMOJI.INFO} Branch is ${commitsBehind} commits behind main. Consider rebasing to reduce merge conflicts.`,
+    BRANCH_DRIFT_WARNING: (commitsBehind) => `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Branch is ${commitsBehind} commits behind main. Rebase recommended before completing.`,
+    DIVERGENCE_DETECTED: (commitCount) => `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Branch divergence detected: main is ${commitCount} commit(s) ahead`,
+    NO_DIVERGENCE: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Pre-flight: No branch divergence (main has not advanced)`,
+    NO_CONFLICTS: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Pre-flight: No merge conflicts detected`,
+    ALREADY_MERGED: `\n${LOG_PREFIX.DONE} ${EMOJI.INFO} Branch already merged to main - proceeding with metadata-only completion`,
+    ALREADY_MERGED_EXPLANATION: `         This is normal when code was merged via emergency fix or manual merge.`,
+    BRANCH_INFO: (branch, branchTip, mergeBase, mainHead) => `${LOG_PREFIX.DONE} ${EMOJI.INFO} Branch ${branch} is already merged to main\n` +
+        `         Branch tip: ${branchTip}\n` +
+        `         Merge-base: ${mergeBase}\n` +
+        `         Main HEAD:  ${mainHead}`,
+    BRANCH_DRIFT_ERROR: (mainAhead, threshold, remote, mainBranch) => `⚠️  BRANCH DRIFT DETECTED (WU-755 pre-flight check)\n\n` +
+        `Your branch is ${mainAhead} commits behind main (threshold: ${threshold} commits).\n` +
+        `This increases risk of merge conflicts at completion.\n\n` +
+        `REQUIRED: Rebase your branch before completing:\n` +
+        `  1. cd into your worktree\n` +
+        `  2. Run: git fetch ${remote} ${mainBranch} && git rebase ${remote}/${mainBranch}\n` +
+        `  3. Resolve any conflicts that arise\n` +
+        `  4. Return to main checkout and retry: pnpm wu:done --id <WU-ID>`,
+    DIVERGENCE_ERROR: (commitCount, remote, mainBranch, branch) => `⚠️  BRANCH DIVERGENCE DETECTED (emergency fix protection)\n\n` +
+        `Main has advanced ${commitCount} commit(s) since your branch was created.\n` +
+        `Fast-forward merge is impossible.\n\n` +
+        `REQUIRED: Rebase your branch onto current main:\n` +
+        `  1. cd into your worktree\n` +
+        `  2. Fetch latest main: git fetch ${remote} ${mainBranch}\n` +
+        `  3. Rebase onto main: git rebase ${remote}/${mainBranch}\n` +
+        `  4. Force-push lane branch: git push --force-with-lease ${remote} ${branch}\n` +
+        `  5. Return to main checkout and retry`,
+    CONFLICT_ERROR: (remote = REMOTES.ORIGIN, mainBranch = BRANCHES.MAIN) => `⚠️  MERGE CONFLICTS DETECTED (WU-755 pre-flight check)\n\n` +
+        `Cannot complete WU - merge conflicts found between main and your branch.\n\n` +
+        `REQUIRED: Resolve conflicts before completing:\n` +
+        `  1. cd into your worktree\n` +
+        `  2. Run: git fetch ${remote} ${mainBranch} && git rebase ${remote}/${mainBranch}\n` +
+        `  3. Resolve conflicts that arise during rebase\n` +
+        `  4. Run: git rebase --continue after resolving each conflict\n` +
+        `  5. Return to main checkout and retry`,
+    // WU-1384: Merge commit detection for linear history enforcement
+    MERGE_COMMITS_DETECTED: (count) => `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Detected ${count} merge commit(s) in lane branch (GitHub requires linear history)`,
+    MERGE_COMMITS_REBASING: `${LOG_PREFIX.DONE} ${EMOJI.WRENCH} Rebasing to eliminate merge commits and maintain linear history...`,
+    NO_MERGE_COMMITS: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Pre-flight: No merge commits in branch (linear history)`,
+    // WU-1456: Empty merge detection - prevents completing WUs with no actual work
+    EMPTY_MERGE_WARNING: (commitCount) => `\n${LOG_PREFIX.DONE} ⚠️  WARNING: Only ${commitCount} commit(s) on lane branch beyond claim.\n` +
+        `         This may indicate no code changes were committed before running wu:done.\n` +
+        `         If this is intentional (docs-only or metadata update), you may proceed.\n` +
+        `         Otherwise, check that your changes were committed in the worktree.\n`,
+    EMPTY_MERGE_CHECK: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Pre-flight: Branch has work commits beyond claim`,
+    // WU-1460: code_paths blocker - prevents completing WUs with code_paths defined but files not modified
+    CODE_PATHS_NOT_MODIFIED: (missingFiles) => `Cannot complete WU - code_paths files were NOT modified in any commits.\n\n` +
+        `This WU defines code_paths that should have been implemented:\n` +
+        missingFiles.map((f) => `  - ${f}`).join('\n') +
+        `\n\nThis error prevents completing a WU without actually committing the code.\n` +
+        `The worktree would be deleted and your work would be lost.\n\n` +
+        `REQUIRED: Commit your code changes before running wu:done:\n` +
+        `  1. cd into your worktree\n` +
+        `  2. git add <your files>\n` +
+        `  3. git commit -m "feat: <description>"\n` +
+        `  4. Return to main and retry: pnpm wu:done --id <WU-ID>`,
+    CODE_PATHS_VERIFIED: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Pre-flight: code_paths files modified in commits`,
+};
+/**
+ * Merge operation messages (WU-1303)
+ */
+export const MERGE = {
+    STARTING: (branch) => `\n${LOG_PREFIX.DONE} Merging lane branch to main (metadata + code)...`,
+    BRANCH_MERGE: (branch) => `\n${LOG_PREFIX.DONE} Merging branch ${branch} to main (fast-forward only)...`,
+    SUCCESS: (branch) => `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Merged ${branch} successfully (fast-forward)`,
+    ATOMIC_SUCCESS: `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Metadata and code merged to main atomically`,
+    FF_FAILED_RETRY: `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Fast-forward failed, updating main and retrying...`,
+    UPDATED_MAIN: (remote) => `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Updated main from ${remote}, retrying merge...`,
+    PUSHED: (remote, mainBranch) => `${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Pushed to ${remote}/${mainBranch}`,
+    FF_MERGE_ERROR: (branch, mergeError, pullError, remote = REMOTES.ORIGIN, mainBranch = BRANCHES.MAIN) => `Fast-forward merge failed and retry with git pull also failed.\n\n` +
+        `Original merge error: ${mergeError}\n` +
+        `Pull error: ${pullError}\n\n` +
+        `Manual fix required:\n` +
+        `  1. git pull ${remote} ${mainBranch}\n` +
+        `  2. Resolve any conflicts\n` +
+        `  3. Switch to your worktree and rebase onto ${mainBranch}\n` +
+        `  4. Return to main checkout and retry`,
+    FF_DIVERGED_ERROR: (branch, originalError, mainBranch = BRANCHES.MAIN) => `Fast-forward merge failed for ${branch}.\n\n` +
+        `This means your branch has diverged from ${mainBranch}.\n` +
+        `To fix:\n` +
+        `  1. Switch to your worktree: cd <worktree-path>\n` +
+        `  2. Rebase onto ${mainBranch}: git rebase ${mainBranch}\n` +
+        `  3. Return to main checkout and retry`,
+    FF_FAILED_NON_DIVERGED_ERROR: (branch, originalError, mainBranch = BRANCHES.MAIN) => `Fast-forward merge failed for ${branch}, but ${mainBranch} is an ancestor.\n\n` +
+        `This indicates the merge did not fail due to divergence.\n` +
+        `Underlying git error: ${originalError}\n\n` +
+        `Next steps:\n` +
+        `  1. Re-run: pnpm wu:done --id <WU-ID>\n` +
+        `  2. If it repeats, check for concurrent git activity and retry after a short wait`,
+};
+/**
+ * Pre-push gate messages (WU-1303)
+ */
+export const PREPUSH = {
+    WORKTREE_SKIP: '[pre-push] Worktree detected - skipping gates (validated at merge via wu:done)',
+};

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * PR mode completion workflow for wu:done
+ * Extracted from wu-done.mjs (WU-1215 refactoring)
+ *
+ * PR mode creates a GitHub PR instead of auto-merging to main.
+ * Used for:
+ * - External agents requiring review (claimed_mode: worktree-pr)
+ * - High-risk WUs (requires_review: true in WU YAML)
+ * - One-off PR creation (--create-pr flag)
+ */
+/**
+ * @typedef {Object} PRContext
+ * @property {string} branch - Lane branch name
+ * @property {string} id - WU ID (e.g., "WU-1215")
+ * @property {string} title - WU title for PR title
+ * @property {Object} doc - WU YAML document
+ * @property {boolean} [draft] - Whether to create as draft PR
+ */
+/**
+ * @typedef {Object} PRResult
+ * @property {boolean} success - Whether PR creation succeeded
+ * @property {string|null} prUrl - URL of created PR (null if gh CLI unavailable)
+ * @property {boolean} ghAvailable - Whether gh CLI is available
+ */
+/**
+ * Check if PR mode is enabled for this WU
+ *
+ * @param {Object} doc - WU YAML document
+ * @param {Object} args - CLI arguments
+ * @returns {boolean} Whether PR mode is enabled
+ */
+export declare function isPRModeEnabled(doc: any, args: any): any;
+/**
+ * Check if gh CLI is available
+ *
+ * @returns {boolean} Whether gh CLI is available
+ */
+export declare function isGhCliAvailable(): boolean;
+/**
+ * Create a GitHub PR for the lane branch
+ *
+ * @param {PRContext} context - PR context
+ * @returns {Promise<PRResult>} PR creation result
+ */
+export declare function createPR(context: any): Promise<{
+    success: boolean;
+    prUrl: string;
+    ghAvailable: boolean;
+}>;
+/**
+ * Build the PR body from WU document
+ *
+ * @param {Object} doc - WU YAML document
+ * @param {string} id - WU ID
+ * @returns {string} PR body markdown
+ */
+export declare function buildPRBody(doc: any, id: any): string;
+/**
+ * Print message when gh CLI is not available
+ *
+ * @param {string} branch - Lane branch name
+ * @param {string} id - WU ID
+ */
+export declare function printGhCliMissingMessage(branch: any, id: any): void;
+/**
+ * Print success message with next steps after PR creation
+ *
+ * @param {string} prUrl - URL of created PR
+ * @param {string} id - WU ID
+ */
+export declare function printPRCreatedMessage(prUrl: any, id: any): void;

package/dist/wu-done-pr.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * PR mode completion workflow for wu:done
+ * Extracted from wu-done.mjs (WU-1215 refactoring)
+ *
+ * PR mode creates a GitHub PR instead of auto-merging to main.
+ * Used for:
+ * - External agents requiring review (claimed_mode: worktree-pr)
+ * - High-risk WUs (requires_review: true in WU YAML)
+ * - One-off PR creation (--create-pr flag)
+ */
+import { execSync } from 'node:child_process';
+import { getGitForCwd } from './git-adapter.js';
+import { createError, ErrorCodes } from './error-handler.js';
+import { LOG_PREFIX, EMOJI, REMOTES, STDIO } from './wu-constants.js';
+/**
+ * @typedef {Object} PRContext
+ * @property {string} branch - Lane branch name
+ * @property {string} id - WU ID (e.g., "WU-1215")
+ * @property {string} title - WU title for PR title
+ * @property {Object} doc - WU YAML document
+ * @property {boolean} [draft] - Whether to create as draft PR
+ */
+/**
+ * @typedef {Object} PRResult
+ * @property {boolean} success - Whether PR creation succeeded
+ * @property {string|null} prUrl - URL of created PR (null if gh CLI unavailable)
+ * @property {boolean} ghAvailable - Whether gh CLI is available
+ */
+/**
+ * Check if PR mode is enabled for this WU
+ *
+ * @param {Object} doc - WU YAML document
+ * @param {Object} args - CLI arguments
+ * @returns {boolean} Whether PR mode is enabled
+ */
+export function isPRModeEnabled(doc, args) {
+    const claimedMode = doc.claimed_mode || 'worktree';
+    const requiresReview = doc.requires_review === true;
+    return claimedMode === 'worktree-pr' || args.createPR || requiresReview;
+}
+/**
+ * Check if gh CLI is available
+ *
+ * @returns {boolean} Whether gh CLI is available
+ */
+export function isGhCliAvailable() {
+    try {
+        execSync('gh --version', { encoding: 'utf-8', stdio: STDIO.IGNORE });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create a GitHub PR for the lane branch
+ *
+ * @param {PRContext} context - PR context
+ * @returns {Promise<PRResult>} PR creation result
+ */
+export async function createPR(context) {
+    const { branch, id, title, doc, draft = false } = context;
+    console.log(`\n${LOG_PREFIX.DONE} Creating PR for ${branch}...`);
+    // Check if gh CLI is available
+    if (!isGhCliAvailable()) {
+        printGhCliMissingMessage(branch, id);
+        return { success: false, prUrl: null, ghAvailable: false };
+    }
+    // Push branch to remote
+    try {
+        await getGitForCwd().push(REMOTES.ORIGIN, branch);
+    }
+    catch (e) {
+        throw createError(ErrorCodes.GIT_ERROR, `Failed to push branch ${branch}: ${e.message}`, {
+            branch,
+            operation: 'push',
+            originalError: e.message,
+        });
+    }
+    // Build PR body
+    const body = buildPRBody(doc, id);
+    const prTitle = `${id}: ${title}`;
+    const draftFlag = draft ? '--draft' : '';
+    // Create PR via gh CLI
+    try {
+        const prUrl = execSync(`gh pr create --title ${JSON.stringify(prTitle)} --body ${JSON.stringify(body)} ${draftFlag} --head ${JSON.stringify(branch)} --base main`, { encoding: 'utf-8' }).trim();
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} PR created: ${prUrl}`);
+        return { success: true, prUrl, ghAvailable: true };
+    }
+    catch (e) {
+        throw createError(ErrorCodes.GIT_ERROR, `Failed to create PR: ${e.message}`, {
+            branch,
+            id,
+            operation: 'pr-create',
+            originalError: e.message,
+        });
+    }
+}
+/**
+ * Build the PR body from WU document
+ *
+ * @param {Object} doc - WU YAML document
+ * @param {string} id - WU ID
+ * @returns {string} PR body markdown
+ */
+export function buildPRBody(doc, id) {
+    const wuPath = `docs/04-operations/tasks/wu/${id}.yaml`;
+    const description = doc.description || doc.problem || '';
+    const acceptance = doc.acceptance_criteria || doc.acceptance || {};
+    let body = `## Summary\n\n${description}\n\n`;
+    if (Object.keys(acceptance).length > 0) {
+        body += `## Acceptance Criteria\n\n`;
+        for (const [key, criteria] of Object.entries(acceptance)) {
+            body += `**${key}:**\n`;
+            if (Array.isArray(criteria)) {
+                for (const item of criteria) {
+                    body += `- ${item}\n`;
+                }
+            }
+            else if (typeof criteria === 'object') {
+                for (const [subkey, items] of Object.entries(criteria)) {
+                    body += `- ${subkey}:\n`;
+                    if (Array.isArray(items)) {
+                        for (const item of items) {
+                            body += `  - ${item}\n`;
+                        }
+                    }
+                }
+            }
+            body += `\n`;
+        }
+    }
+    body += `\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n`;
+    body += `WU YAML: ${wuPath}`;
+    return body;
+}
+/**
+ * Print message when gh CLI is not available
+ *
+ * @param {string} branch - Lane branch name
+ * @param {string} id - WU ID
+ */
+export function printGhCliMissingMessage(branch, id) {
+    console.error();
+    console.error('╔═══════════════════════════════════════════════════════════════════╗');
+    console.error('║  GH CLI NOT AVAILABLE');
+    console.error('╠═══════════════════════════════════════════════════════════════════╣');
+    console.error('║  The gh CLI tool is required to create PRs.');
+    console.error('║');
+    console.error('║  Manual PR creation steps:');
+    console.error(`║  1. Push branch: git push origin ${branch}`);
+    console.error('║  2. Create PR in GitHub UI');
+    console.error(`║  3. After merge, run: pnpm wu:cleanup --id ${id}`);
+    console.error('╚═══════════════════════════════════════════════════════════════════╝');
+}
+/**
+ * Print success message with next steps after PR creation
+ *
+ * @param {string} prUrl - URL of created PR
+ * @param {string} id - WU ID
+ */
+export function printPRCreatedMessage(prUrl, id) {
+    console.log('\n╔═══════════════════════════════════════════════════════════════════╗');
+    console.log('║  PR CREATED - NEXT STEPS');
+    console.log('╠═══════════════════════════════════════════════════════════════════╣');
+    console.log(`║  PR URL: ${prUrl}`);
+    console.log('║');
+    console.log('║  Next steps:');
+    console.log('║  1. Review the PR in GitHub UI');
+    console.log('║  2. Merge the PR when ready');
+    console.log(`║  3. Run cleanup: pnpm wu:cleanup --id ${id}`);
+    console.log('╚═══════════════════════════════════════════════════════════════════╝');
+}

package/dist/wu-done-retry-helpers.d.ts

@@ -0,0 +1,85 @@
+/**
+ * WU-1584: Retry and recovery helpers for wu:done
+ *
+ * Handles:
+ * - Squashing duplicate completion commits from retry attempts
+ * - Detecting and counting previous completion attempts
+ * - Preparing zombie recovery with squash
+ * - Handling parallel completions with auto-rebase
+ *
+ * @module wu-done-retry-helpers
+ */
+/**
+ * Count previous completion attempt commits for a WU on the current branch
+ *
+ * WU-1584 Fix #1: Detect duplicate commits from retries
+ *
+ * Searches commit history for commits matching the completion pattern
+ * for the specified WU ID.
+ *
+ * @param {string} wuId - WU ID (e.g., 'WU-1584')
+ * @param {object} gitAdapter - Git adapter instance
+ * @returns {Promise<number>} Number of completion attempt commits found
+ */
+export declare function countPreviousCompletionAttempts(wuId: any, gitAdapter: any): Promise<number>;
+/**
+ * Squash previous completion attempt commits into a single commit
+ *
+ * WU-1584 Fix #1: Running wu:done N times should result in exactly 1 completion commit
+ *
+ * Uses git reset --soft to combine multiple completion attempts while
+ * preserving the staged changes for the new completion commit.
+ *
+ * @param {string} wuId - WU ID for logging
+ * @param {number} count - Number of commits to squash
+ * @param {object} gitAdapter - Git adapter instance
+ * @param {SquashCompletionAttemptsOptions} [options] - Options
+ * @returns {Promise<{ squashed: boolean, count: number }>} Result
+ */
+export interface SquashCompletionAttemptsOptions {
+    /** Use --soft when true; --hard when false (recovery) */
+    preserveIndex?: boolean;
+}
+export declare function squashPreviousCompletionAttempts(wuId: any, count: any, gitAdapter: any, options?: SquashCompletionAttemptsOptions): Promise<{
+    squashed: boolean;
+    count: any;
+}>;
+/**
+ * Prepare zombie recovery with squash of previous attempts
+ *
+ * WU-1584 Fix #2: Recovery loop should squash previous attempt commits
+ *
+ * When recovering from zombie state (status=done but worktree exists),
+ * first squash any previous completion attempts to avoid "rebase hell".
+ *
+ * @param {string} wuId - WU ID
+ * @param {object} gitAdapter - Git adapter instance
+ * @returns {Promise<{ squashedCount: number }>} Result
+ */
+export declare function prepareRecoveryWithSquash(wuId: any, gitAdapter: any): Promise<{
+    squashedCount: any;
+}>;
+/**
+ * Handle parallel completions with auto-rebase
+ *
+ * WU-1584 Fix #3: detectParallelCompletions() should trigger rebase, not just warn
+ *
+ * When parallel completions are detected (main has advanced since claim),
+ * triggers auto-rebase instead of proceeding with merge that will fail.
+ *
+ * @param {string} wuId - WU ID
+ * @param {object} doc - WU YAML document containing baseline_main_sha
+ * @param {object} gitAdapter - Git adapter instance
+ * @param {HandleParallelCompletionsOptions} options - Options
+ * @returns {Promise<{ parallelDetected: boolean, rebaseTriggered: boolean }>}
+ */
+export interface HandleParallelCompletionsOptions {
+    /** Path to worktree */
+    worktreePath?: string;
+    /** Whether auto-rebase is enabled (default: true) */
+    autoRebase?: boolean;
+}
+export declare function handleParallelCompletions(wuId: any, doc: any, gitAdapter: any, options?: HandleParallelCompletionsOptions): Promise<{
+    parallelDetected: boolean;
+    rebaseTriggered: boolean;
+}>;