@lumenflow/cli 2.2.1 → 2.3.1

package/dist/wu-done.js

@@ -31,10 +31,16 @@
  * WU-2542: This script imports utilities from @lumenflow/core package.
  * Full migration to thin shim pending @lumenflow/core CLI export implementation.
  */
+// WU-1153: wu:done guard for uncommitted code_paths is implemented in core package
+// The guard runs in executeWorktreeCompletion() before metadata transaction
+// See: packages/@lumenflow/core/src/wu-done-validation.ts
 import { execSync } from 'node:child_process';
 import prettyMs from 'pretty-ms';
+import { runGates } from './gates.js';
 import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
+// WU-1223: Location detection for worktree check
+import { resolveLocation } from '@lumenflow/core/dist/context/location-resolver.js';
 import { existsSync, readFileSync, mkdirSync, appendFileSync, unlinkSync, statSync } from 'node:fs';
 import path from 'node:path';
 // WU-1825: Import from unified code-path-validator (consolidates 3 validators)
@@ -53,7 +59,9 @@ validateAllPreCommitHooks,
 validateTypeVsCodePathsPreflight, buildTypeVsCodePathsErrorMessage, } from '@lumenflow/core/dist/wu-done-validators.js';
 // WU-1825: validateCodePathsExist moved to unified code-path-validator
 import { validateCodePathsExist } from '@lumenflow/core/dist/code-path-validator.js';
-import { BRANCHES, REMOTES, PATTERNS, DEFAULTS, LOG_PREFIX, EMOJI, GIT, SESSION, WU_STATUS, PKG_MANAGER, SCRIPTS, CLI_FLAGS, FILE_SYSTEM, EXIT_CODES, STRING_LITERALS, MICRO_WORKTREE_OPERATIONS, TELEMETRY_STEPS, SKIP_GATES_REASONS, CHECKPOINT_MESSAGES, } from '@lumenflow/core/dist/wu-constants.js';
+import { BRANCHES, REMOTES, PATTERNS, DEFAULTS, LOG_PREFIX, EMOJI, GIT, SESSION, WU_STATUS, PKG_MANAGER, SCRIPTS, CLI_FLAGS, FILE_SYSTEM, EXIT_CODES, STRING_LITERALS, MICRO_WORKTREE_OPERATIONS, TELEMETRY_STEPS, SKIP_GATES_REASONS, CHECKPOINT_MESSAGES, 
+// WU-1223: Location types for worktree detection
+CONTEXT_VALIDATION, } from '@lumenflow/core/dist/wu-constants.js';
 import { printGateFailureBox, printStatusPreview } from '@lumenflow/core/dist/wu-done-ui.js';
 import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
 import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
@@ -85,6 +93,7 @@ import { SpawnStatus } from '@lumenflow/core/dist/spawn-registry-schema.js';
 // WU-1999: Exposure validation for UI pairing
 // WU-2022: Feature accessibility validation (blocking)
 import { validateExposure, validateFeatureAccessibility, } from '@lumenflow/core/dist/wu-validation.js';
+import { ensureCleanWorktree } from './wu-done-check.js';
 // WU-1588: Memory layer constants
 const MEMORY_SIGNAL_TYPES = {
     WU_COMPLETION: 'wu_completion',
@@ -147,7 +156,7 @@ async function validateClaimMetadataBeforeGates(id, worktreePath, yamlStatus) {
         `  pnpm wu:repair-claim --id ${id}\n\n` +
         `After repair, retry:\n` +
         `  pnpm wu:done --id ${id}\n\n` +
-        `See: docs/04-operations/_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md for more recovery options.`);
+        `See: https://lumenflow.dev/reference/troubleshooting-wu-done/ for more recovery options.`);
 }
 export function printExposureWarnings(wu, options = {}) {
     // Validate exposure
@@ -444,7 +453,7 @@ export async function isBranchAlreadyMerged(branch) {
         return false;
     }
 }
-// WU-1281: isDocsOnlyByPaths removed - use shouldSkipWebTests from path-classifiers.mjs
+// WU-1281: isDocsOnlyByPaths removed - use shouldSkipWebTests from path-classifiers.ts
 // The validators already use shouldSkipWebTests via detectDocsOnlyByPaths wrapper.
 // Keeping the export for backward compatibility but re-exporting the canonical function.
 export { shouldSkipWebTests as isDocsOnlyByPaths } from '@lumenflow/core/dist/path-classifiers.js';
@@ -500,7 +509,7 @@ function getCommitHeaderLimit() {
         return DEFAULTS.MAX_COMMIT_SUBJECT; // Fallback if config is malformed or missing
     }
 }
-// ensureOnMain() moved to wu-helpers.mjs (WU-1256)
+// ensureOnMain() moved to wu-helpers.ts (WU-1256)
 /**
  * Ensure working tree is clean before wu:done operations.
  *
@@ -718,7 +727,7 @@ async function ensureMainUpToDate() {
  * by calling /usr/bin/git directly or if PATH was not set up correctly.
  *
  * Context: WU-630 (detective layer, Layer 3 of 4)
- * See: docs/04-operations/_frameworks/lumenflow/02-playbook.md §4.6
+ * See: https://lumenflow.dev/reference/playbook/ §4.6
  */
 function runTripwireCheck() {
     const violations = scanLogForViolations();
@@ -763,7 +772,7 @@ function runTripwireCheck() {
         console.error('   3. Escalate to human if critical files were deleted\n');
     }
     console.error('📖 See detailed recovery steps:');
-    console.error('   docs/04-operations/_frameworks/lumenflow/02-playbook.md §4.6\n');
+    console.error('   https://lumenflow.dev/reference/playbook/ §4.6\n');
     console.error('🚫 DO NOT proceed with wu:done until violations are remediated.\n');
     console.error('Fix violations first, then retry wu:done.\n');
     // Also rotate log (cleanup old entries)
@@ -846,7 +855,7 @@ async function auditSkipCosGates(id, reason) {
     appendFileSync(auditPath, `${line}\n`, { encoding: FILE_SYSTEM.UTF8 });
     console.log(`${LOG_PREFIX.DONE} ${EMOJI.MEMO} Skip-COS-gates event logged to ${auditPath}`);
 }
-// WU-2308: validateAllPreCommitHooks moved to wu-done-validators.mjs
+// WU-2308: validateAllPreCommitHooks moved to wu-done-validators.ts
 // Now accepts worktreePath parameter to run audit from worktree context
 /**
  * Check if node_modules in worktree may be stale
@@ -915,14 +924,13 @@ function checkNodeModulesStaleness(worktreePath) {
  * @param {boolean} options.isDocsOnly - Auto-detected docs-only from code_paths
  * @param {boolean} options.docsOnly - Explicit --docs-only flag from CLI
  */
-function runGatesInWorktree(worktreePath, id, options = {}) {
+async function runGatesInWorktree(worktreePath, id, options = {}) {
     const { isDocsOnly = false, docsOnly = false } = options;
     console.log(`\n${LOG_PREFIX.DONE} Running gates in worktree: ${worktreePath}`);
     // Check for stale node_modules before running gates (prevents confusing failures)
     checkNodeModulesStaleness(worktreePath);
     // WU-1012: Use docs-only gates if explicit --docs-only flag OR auto-detected
     const useDocsOnlyGates = docsOnly || isDocsOnly;
-    const gatesCmd = buildGatesCommand({ docsOnly, isDocsOnly });
     if (useDocsOnlyGates) {
         console.log(`${LOG_PREFIX.DONE} Using docs-only gates (skipping lint/typecheck/tests)`);
         if (docsOnly) {
@@ -931,12 +939,14 @@ function runGatesInWorktree(worktreePath, id, options = {}) {
     }
     const startTime = Date.now();
     try {
-        // WU-1230: Pass WU_ID to validator for context-aware validation
-        execSync(gatesCmd, {
+        const ok = Boolean(await runGates({
             cwd: worktreePath,
-            stdio: 'inherit',
-            env: { ...process.env, WU_ID: id },
-        });
+            docsOnly: useDocsOnlyGates,
+            coverageMode: undefined,
+        }));
+        if (!ok) {
+            throw new Error('Gates failed');
+        }
         const duration = Date.now() - startTime;
         console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Gates passed in ${prettyMs(duration)}`);
         emitTelemetry({ script: 'wu-done', wu_id: id, step: 'gates', ok: true, duration_ms: duration });
@@ -998,13 +1008,13 @@ async function validateStagedFiles(id, isDocsOnly = false) {
     }
 }
 // Note: updateStatusRemoveInProgress, addToStatusCompleted, and moveWUToDoneBacklog
-// have been extracted to tools/lib/wu-status-updater.mjs and imported above (WU-1163)
+// have been extracted to tools/lib/wu-status-updater.ts and imported above (WU-1163)
 //
-// Note: ensureStamp has been replaced with createStamp from tools/lib/stamp-utils.mjs (WU-1163)
+// Note: ensureStamp has been replaced with createStamp from tools/lib/stamp-utils.ts (WU-1163)
 //
 // Note: readWUPreferWorktree, detectCurrentWorktree, defaultWorktreeFrom, detectWorkspaceMode,
 // defaultBranchFrom, branchExists, runCleanup have been extracted to
-// tools/lib/wu-done-validators.mjs and imported above (WU-1215)
+// tools/lib/wu-done-validators.ts and imported above (WU-1215)
 /**
  * Validate Branch-Only mode requirements before proceeding
  * @param {string} laneBranch - Expected lane branch name
@@ -1774,8 +1784,7 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
         // Branch-Only mode: run gates in-place (current directory on lane branch)
         console.log(`\n${LOG_PREFIX.DONE} Running gates in Branch-Only mode (in-place on lane branch)`);
         // WU-1012: Use docs-only gates if explicit --docs-only flag OR auto-detected
-        const useDocsOnlyGates = args.docsOnly || isDocsOnly;
-        const gatesCmd = buildGatesCommand({ docsOnly: Boolean(args.docsOnly), isDocsOnly });
+        const useDocsOnlyGates = Boolean(args.docsOnly) || Boolean(isDocsOnly);
         if (useDocsOnlyGates) {
             console.log(`${LOG_PREFIX.DONE} Using docs-only gates (skipping lint/typecheck/tests)`);
             if (args.docsOnly) {
@@ -1784,7 +1793,10 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
         }
         const startTime = Date.now();
         try {
-            execSync(gatesCmd, { stdio: 'inherit' });
+            const ok = Boolean(await runGates({ docsOnly: useDocsOnlyGates }));
+            if (!ok) {
+                throw new Error('Gates failed');
+            }
             const duration = Date.now() - startTime;
             console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Gates passed in ${prettyMs(duration)}`);
             emitTelemetry({
@@ -1818,7 +1830,10 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
     else if (worktreePath && existsSync(worktreePath)) {
         // Worktree mode: run gates in the dedicated worktree
         // WU-1012: Pass both auto-detected and explicit docs-only flags
-        runGatesInWorktree(worktreePath, id, { isDocsOnly, docsOnly: Boolean(args.docsOnly) });
+        await runGatesInWorktree(worktreePath, id, {
+            isDocsOnly,
+            docsOnly: Boolean(args.docsOnly),
+        });
     }
     else {
         die(`Worktree not found (${worktreePath || 'unknown'}). Gates must run in the lane worktree.\n` +
@@ -1855,7 +1870,7 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
             console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} COS governance gates failed`);
             console.error('\nTo fix:');
             console.error('  1. Add required evidence to governance.evidence field in WU YAML');
-            console.error('  2. See: docs/04-operations/_frameworks/cos/evidence-format.md');
+            console.error('  2. See: https://lumenflow.dev/reference/evidence-format/');
             console.error('\nEmergency bypass (creates audit trail):');
             console.error(`  pnpm wu:done --id ${id} --skip-cos-gates --reason "explanation"`);
             die('Abort: WU not completed. Fix governance evidence and retry pnpm wu:done.');
@@ -1908,8 +1923,22 @@ function printStateHUD({ id, docMain, isBranchOnly, isDocsOnly, derivedWorktree,
 async function main() {
     // Allow pre-push hook to recognize wu:done automation (WU-1030)
     process.env.LUMENFLOW_WU_TOOL = 'wu-done';
-    // Validate CLI arguments and WU ID format (extracted to wu-done-validators.mjs)
+    // Validate CLI arguments and WU ID format (extracted to wu-done-validators.ts)
     const { args, id } = validateInputs(process.argv);
+    // WU-1223: Check if running from worktree - wu:done now requires main checkout
+    // Agents should use wu:prep from worktree, then wu:done from main
+    const { LOCATION_TYPES } = CONTEXT_VALIDATION;
+    const currentLocation = await resolveLocation();
+    if (currentLocation.type === LOCATION_TYPES.WORKTREE) {
+        die(`${EMOJI.FAILURE} wu:done must be run from main checkout, not from a worktree.\n\n` +
+            `Current location: ${currentLocation.cwd}\n\n` +
+            `WU-1223 NEW WORKFLOW:\n` +
+            `  1. From worktree, run: pnpm wu:prep --id ${id}\n` +
+            `     (This runs gates and prepares for completion)\n\n` +
+            `  2. From main, run: cd ${currentLocation.mainCheckout} && pnpm wu:done --id ${id}\n` +
+            `     (This does merge + cleanup only)\n\n` +
+            `Use wu:prep to run gates in the worktree, then wu:done from main for merge/cleanup.`);
+    }
     // Detect workspace mode and calculate paths (WU-1215: extracted to validators module)
     const pathInfo = await detectModeAndPaths(id, args);
     const { WU_PATH, STATUS_PATH, BACKLOG_PATH, STAMPS_DIR, docMain, isBranchOnly, derivedWorktree, docForValidation: initialDocForValidation, isDocsOnly, } = pathInfo;
@@ -1933,6 +1962,11 @@ async function main() {
     }
     const effectiveDerivedWorktree = effectiveBranchOnly ? null : derivedWorktree;
     const effectiveWorktreePath = effectiveBranchOnly ? null : resolvedWorktreePath;
+    // WU-1169: Ensure worktree is clean before proceeding
+    // This prevents WU-1943 rollback loops if rebase fails due to dirty state
+    if (effectiveWorktreePath && existsSync(effectiveWorktreePath)) {
+        await ensureCleanWorktree(effectiveWorktreePath);
+    }
     // Pre-flight checks (WU-1215: extracted to executePreFlightChecks function)
     const preFlightResult = await executePreFlightChecks({
         id,
@@ -1977,7 +2011,9 @@ async function main() {
     // WU-2308: Pass worktreePath to run audit from worktree (checks fixed deps, not stale main deps)
     // WU-1145: Skip pre-flight when skipGates is true (pre-flight runs gates which was already skipped)
     if (!args.skipGates) {
-        const hookResult = validateAllPreCommitHooks(id, worktreePath);
+        const hookResult = await validateAllPreCommitHooks(id, worktreePath, {
+            runGates: ({ cwd }) => runGates({ cwd, docsOnly: false }),
+        });
         if (!hookResult.valid) {
             die('Pre-flight validation failed. Fix hook issues and try again.');
         }

package/dist/wu-edit.js

@@ -24,9 +24,8 @@
  *   pnpm wu:edit --id WU-123 --acceptance "Criterion 1" --acceptance "Criterion 2"
  *
  * Part of WU-1274: Add wu:edit command for spec-only changes
- * @see {@link tools/lib/micro-worktree.mjs} - Shared micro-worktree logic
+ * @see {@link packages/@lumenflow/cli/src/lib/micro-worktree.ts} - Shared micro-worktree logic
  */
-import { fileURLToPath } from 'node:url';
 import { getGitForCwd, createGitForPath } from '@lumenflow/core/dist/git-adapter.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
@@ -182,19 +181,30 @@ const EDIT_OPTIONS = {
     codePaths: {
         name: 'codePaths',
         flags: '--code-paths <path>',
-        description: 'Code path (repeatable, replaces existing; use --append to add)',
+        description: 'Code path (repeatable, appends to existing; use --replace-code-paths to overwrite)',
         isRepeatable: true,
     },
+    replaceCodePaths: {
+        name: 'replaceCodePaths',
+        flags: '--replace-code-paths',
+        description: 'Replace existing code_paths instead of appending',
+    },
     risks: {
         name: 'risks',
         flags: '--risks <risk>',
-        description: 'Risk entry (repeatable, replaces existing; use --append to add)',
+        description: 'Risk entry (repeatable, appends to existing; use --replace-risks to overwrite)',
         isRepeatable: true,
     },
+    replaceRisks: {
+        name: 'replaceRisks',
+        flags: '--replace-risks',
+        description: 'Replace existing risks instead of appending',
+    },
+    // WU-1225: Deprecated --append flag (kept for backwards compatibility)
     append: {
         name: 'append',
         flags: '--append',
-        description: 'Append to existing array values instead of replacing (for --code-paths, --test-paths-*, --blocked-by, --add-dep)',
+        description: '[DEPRECATED] Arrays now append by default. Use --replace-* flags to replace.',
     },
     // WU-1456: Add lane reassignment support
     lane: {
@@ -228,12 +238,22 @@ const EDIT_OPTIONS = {
     blockedBy: {
         name: 'blockedBy',
         flags: '--blocked-by <wuIds>',
-        description: 'Comma-separated WU IDs that block this WU (replaces existing; use --append to add)',
+        description: 'Comma-separated WU IDs that block this WU (appends to existing; use --replace-blocked-by to overwrite)',
+    },
+    replaceBlockedBy: {
+        name: 'replaceBlockedBy',
+        flags: '--replace-blocked-by',
+        description: 'Replace existing blocked_by instead of appending',
     },
     addDep: {
         name: 'addDep',
         flags: '--add-dep <wuIds>',
-        description: 'Comma-separated WU IDs to add to dependencies array (replaces existing; use --append to add)',
+        description: 'Comma-separated WU IDs to add to dependencies array (appends to existing; use --replace-dependencies to overwrite)',
+    },
+    replaceDependencies: {
+        name: 'replaceDependencies',
+        flags: '--replace-dependencies',
+        description: 'Replace existing dependencies instead of appending',
     },
 };
 /**
@@ -334,7 +354,9 @@ function parseArgs() {
             EDIT_OPTIONS.replaceNotes,
             EDIT_OPTIONS.replaceAcceptance,
             EDIT_OPTIONS.codePaths,
+            EDIT_OPTIONS.replaceCodePaths,
             EDIT_OPTIONS.risks,
+            EDIT_OPTIONS.replaceRisks,
             EDIT_OPTIONS.append,
             // WU-1390: Add test path flags
             WU_OPTIONS.testPathsManual,
@@ -350,7 +372,9 @@ function parseArgs() {
             EDIT_OPTIONS.phase,
             // WU-2564: Add blocked_by and dependencies
             EDIT_OPTIONS.blockedBy,
+            EDIT_OPTIONS.replaceBlockedBy,
             EDIT_OPTIONS.addDep,
+            EDIT_OPTIONS.replaceDependencies,
             // WU-1039: Add exposure for done WU metadata updates
             WU_OPTIONS.exposure,
         ],
@@ -702,7 +726,7 @@ export function applyEdits(wu, opts) {
         }
         updated.phase = phaseNum;
     }
-    // Handle repeatable --code-paths flags (WU-1388: replace by default, append with --append)
+    // Handle repeatable --code-paths flags (WU-1225: append by default, replace with --replace-code-paths)
     // WU-1816: Split comma-separated string into array (same pattern as test paths)
     // WU-1870: Fix to split comma-separated values WITHIN array elements (Commander passes ['a,b'] not 'a,b')
     if (opts.codePaths && opts.codePaths.length > 0) {
@@ -716,9 +740,12 @@ export function applyEdits(wu, opts) {
                 .split(',')
                 .map((p) => p.trim())
                 .filter(Boolean);
-        updated.code_paths = mergeArrayField(wu.code_paths, codePaths, opts.append);
+        // WU-1225: Invert logic - append by default, replace with --replace-code-paths
+        // Also support legacy --append flag for backwards compatibility
+        const shouldAppend = !opts.replaceCodePaths || opts.append;
+        updated.code_paths = mergeArrayField(wu.code_paths, codePaths, shouldAppend);
     }
-    // WU-1073: Handle repeatable --risks flags (replace by default, append with --append)
+    // WU-1225: Handle repeatable --risks flags (append by default, replace with --replace-risks)
     // Split comma-separated values within each entry for consistency with other list fields
     if (opts.risks && opts.risks.length > 0) {
         const rawRisks = opts.risks;
@@ -731,9 +758,12 @@ export function applyEdits(wu, opts) {
                 .split(',')
                 .map((risk) => risk.trim())
                 .filter(Boolean);
-        updated.risks = mergeArrayField(wu.risks, risks, opts.append);
+        // WU-1225: Invert logic - append by default
+        const shouldAppend = !opts.replaceRisks || opts.append;
+        updated.risks = mergeArrayField(wu.risks, risks, shouldAppend);
     }
     // WU-1390: Handle test path flags (DRY refactor)
+    // WU-1225: Test paths now append by default (consistent with --acceptance and --code-paths)
     const testPathMappings = [
         { optKey: 'testPathsManual', field: 'manual' },
         { optKey: 'testPathsUnit', field: 'unit' },
@@ -754,28 +784,32 @@ export function applyEdits(wu, opts) {
                     .map((p) => p.trim())
                     .filter(Boolean);
             updated.tests = updated.tests || {};
-            updated.tests[field] = mergeArrayField(wu.tests?.[field], paths, opts.append);
+            // WU-1225: Append by default (no individual replace flags for test paths yet)
+            const shouldAppend = true;
+            updated.tests[field] = mergeArrayField(wu.tests?.[field], paths, shouldAppend);
         }
     }
     // WU-2564: Handle --blocked-by flag
-    // Comma-separated WU IDs that block this WU
+    // WU-1225: Append by default, replace with --replace-blocked-by
     if (opts.blockedBy) {
         const rawBlockedBy = opts.blockedBy;
         const blockedByIds = rawBlockedBy
             .split(',')
             .map((id) => id.trim())
             .filter(Boolean);
-        updated.blocked_by = mergeArrayField(wu.blocked_by, blockedByIds, opts.append);
+        const shouldAppend = !opts.replaceBlockedBy || opts.append;
+        updated.blocked_by = mergeArrayField(wu.blocked_by, blockedByIds, shouldAppend);
     }
     // WU-2564: Handle --add-dep flag
-    // Comma-separated WU IDs to add to dependencies array
+    // WU-1225: Append by default, replace with --replace-dependencies
     if (opts.addDep) {
         const rawAddDep = opts.addDep;
         const depIds = rawAddDep
             .split(',')
             .map((id) => id.trim())
             .filter(Boolean);
-        updated.dependencies = mergeArrayField(wu.dependencies, depIds, opts.append);
+        const shouldAppend = !opts.replaceDependencies || opts.append;
+        updated.dependencies = mergeArrayField(wu.dependencies, depIds, shouldAppend);
     }
     // WU-1039: Handle --exposure flag with validation
     if (opts.exposure) {
@@ -845,21 +879,20 @@ async function main() {
             '  --description <text>      Update description field\n' +
             '  --acceptance <text>       Append acceptance criteria (repeatable; use --replace-acceptance to overwrite)\n' +
             '  --notes <text>            Append to notes (use --replace-notes to overwrite)\n' +
-            '  --replace-notes           Replace existing notes instead of appending\n' +
-            '  --replace-acceptance      Replace existing acceptance instead of appending\n' +
-            '  --code-paths <paths>      Replace code paths (repeatable; use --append to add)\n' +
-            '  --risks <risk>            Replace risks (repeatable; use --append to add)\n' +
+            '  --code-paths <paths>      Append code paths (repeatable; use --replace-code-paths to overwrite)\n' +
+            '  --risks <risk>            Append risks (repeatable; use --replace-risks to overwrite)\n' +
             '  --lane <lane>             Update lane assignment (e.g., "Operations: Tooling")\n' +
             '  --type <type>             Update WU type (feature, bug, refactor, documentation)\n' +
             '  --priority <priority>     Update priority (P0, P1, P2, P3)\n' +
             '  --initiative <initId>     Update initiative (bidirectional update)\n' +
             '  --phase <number>          Update phase within initiative\n' +
-            '  --test-paths-manual <t>   Add manual test descriptions (repeatable; use --append to add)\n' +
-            '  --test-paths-unit <path>  Add unit test paths (repeatable; use --append to add)\n' +
-            '  --test-paths-e2e <path>   Add e2e test paths (repeatable; use --append to add)\n' +
-            '  --blocked-by <wuIds>      WU IDs that block this WU (comma-separated; use --append to add)\n' +
-            '  --add-dep <wuIds>         Add WU IDs to dependencies (comma-separated; use --append to add)\n' +
-            '  --exposure <type>         Update exposure level (ui, api, backend-only, documentation)');
+            '  --test-paths-manual <t>   Append manual test descriptions (repeatable)\n' +
+            '  --test-paths-unit <path>  Append unit test paths (repeatable)\n' +
+            '  --test-paths-e2e <path>   Append e2e test paths (repeatable)\n' +
+            '  --blocked-by <wuIds>      Append WU IDs that block this WU (use --replace-blocked-by to overwrite)\n' +
+            '  --add-dep <wuIds>         Append WU IDs to dependencies (use --replace-dependencies to overwrite)\n' +
+            '  --exposure <type>         Update exposure level (ui, api, backend-only, documentation)\n\n' +
+            'Note: All array fields now append by default (WU-1225). Use --replace-* flags to overwrite.');
     }
     // Apply edits to get updated WU
     const updatedWU = applyEdits(originalWU, opts);
@@ -1001,8 +1034,10 @@ async function main() {
         displayReadinessSummary(id);
     }
 }
-// Guard main() execution for testability (WU-1366)
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+if (import.meta.main) {
     main().catch((err) => {
         console.error(`${PREFIX} ❌ ${err.message}`);
         process.exit(EXIT_CODES.ERROR);

package/dist/wu-infer-lane.js

@@ -3,14 +3,14 @@
  * WU Lane Inference CLI (WU-908)
  *
  * Suggests sub-lane for a WU based on code paths and description.
- * Wrapper around lib/lane-inference.mjs for standalone CLI usage.
+ * Wrapper around lib/lane-inference.ts for standalone CLI usage.
  *
  * Usage:
  *   # Infer from existing WU
- *   node tools/wu-infer-lane.mjs --id WU-123
+ *   node tools/wu-infer-lane.ts --id WU-123
  *
  *   # Infer from manual inputs
- *   node tools/wu-infer-lane.mjs --paths "tools/**" "docs/**" --desc "Tooling improvements"
+ *   node tools/wu-infer-lane.ts --paths "tools/**" "docs/**" --desc "Tooling improvements"
  *
  * Returns suggested lane and confidence score (0-100).
  */
@@ -128,9 +128,10 @@ async function main() {
         die(`Lane inference failed: ${err.message}`);
     }
 }
-// Guard main() for testability (WU-1366)
-import { fileURLToPath } from 'node:url';
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }

package/dist/wu-preflight.js

@@ -5,6 +5,9 @@
  * WU-1803: Fast validation of code_paths and test paths before gates run.
  * Completes in under 5 seconds vs 2+ minutes for full gates.
  *
+ * WU-1180: Migrated from deprecated parseWUArgs to createWUParser for
+ * proper Commander --help output and consistency with other WU commands.
+ *
  * This catches YAML mismatches early, preventing wasted time running full
  * gates only to fail on code_paths validation at the end of wu:done.
  *
@@ -17,78 +20,14 @@
  *   - test file paths exist (unit, e2e, integration)
  *   - WU YAML schema is valid
  */
-import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
-import { parseWUArgs } from '@lumenflow/core/dist/arg-parser.js';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { validatePreflight, formatPreflightResult, } from '@lumenflow/core/dist/wu-preflight-validators.js';
 import { PATTERNS, EXIT_CODES, LOG_PREFIX, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
 import { defaultWorktreeFrom, WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { readWURaw } from '@lumenflow/core/dist/wu-yaml.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
 /* eslint-disable security/detect-non-literal-fs-filename */
-/**
- * Parse command-line arguments
- * @param {string[]} argv - Process arguments
- * @returns {object} Parsed arguments
- */
-function parseArgs(argv) {
-    const args = parseWUArgs(argv);
-    // Handle help
-    if (args.help) {
-        return { help: true };
-    }
-    // Validate WU ID
-    if (!args.id) {
-        return { error: 'Missing required argument: --id WU-XXX' };
-    }
-    const id = args.id.toUpperCase();
-    if (!PATTERNS.WU_ID.test(id)) {
-        return { error: `Invalid WU ID format: ${args.id}. Expected WU-NNN` };
-    }
-    return {
-        id,
-        worktree: args.worktree || null,
-        help: false,
-    };
-}
-/**
- * Display help message
- */
-function showHelp() {
-    console.log(`
-WU Preflight Validation - Fast code_paths and test paths check
-
-Usage:
-  pnpm wu:preflight --id WU-XXX [OPTIONS]
-
-Options:
-  --id <WU-ID>           WU ID to validate (required)
-  --worktree <path>      Worktree path to validate files in (auto-detected if not provided)
-  --help, -h             Show this help
-
-Description:
-  Validates code_paths and test file paths exist BEFORE running full gates.
-  Completes in under 5 seconds vs 2+ minutes for gates.
-
-  This prevents wasting time running full gates only to fail on
-  code_paths validation at the end of wu:done.
-
-Checks performed:
-  ${EMOJI.SUCCESS} code_paths files exist in worktree/main
-  ${EMOJI.SUCCESS} Test file paths exist (unit, e2e, integration)
-  ${EMOJI.SUCCESS} WU YAML schema is valid (required fields present)
-  ${EMOJI.SUCCESS} Manual tests are skipped (descriptions, not files)
-
-Recommended workflow:
-  1. Implement feature/fix
-  2. Run: pnpm wu:preflight --id WU-XXX  (fast check)
-  3. Run: pnpm gates                      (full validation)
-  4. Run: pnpm wu:done --id WU-XXX        (complete WU)
-
-Example:
-  pnpm wu:preflight --id WU-1803
-  pnpm wu:preflight --id WU-1803 --worktree worktrees/operations-gates-wu-1803
-`);
-}
 /**
  * Detect worktree path from WU YAML or calculate from lane
  * @param {string} id - WU ID
@@ -116,23 +55,23 @@ function detectWorktreePath(id) {
  */
 async function main() {
     const PREFIX = LOG_PREFIX.PREFLIGHT;
-    const args = parseArgs(process.argv);
-    // Handle help
-    if (args.help) {
-        showHelp();
-        process.exit(EXIT_CODES.SUCCESS);
-    }
-    // Handle parse errors
-    if (args.error) {
-        console.error(`${PREFIX} ${EMOJI.FAILURE} ${args.error}`);
-        console.error(`${PREFIX} Run: pnpm wu:preflight --help for usage`);
-        process.exit(EXIT_CODES.ERROR);
+    // WU-1180: Use createWUParser for proper Commander help output
+    const args = createWUParser({
+        name: 'wu-preflight',
+        description: 'Fast validation of code_paths and test paths before gates run. ' +
+            'Completes in under 5 seconds vs 2+ minutes for full gates.',
+        options: [WU_OPTIONS.id, WU_OPTIONS.worktree],
+        required: ['id'],
+        allowPositionalId: true,
+    });
+    const id = args.id.toUpperCase();
+    if (!PATTERNS.WU_ID.test(id)) {
+        die(`Invalid WU ID format: ${args.id}. Expected WU-NNN`);
     }
-    const { id, worktree } = args;
     console.log(`${PREFIX} Preflight Validation for ${id}`);
     console.log(`${PREFIX} ${'='.repeat(30)}\n`);
     // Determine worktree path
-    let worktreePath = worktree;
+    let worktreePath = args.worktree || null;
     if (!worktreePath) {
         worktreePath = detectWorktreePath(id);
         if (worktreePath) {
@@ -160,9 +99,12 @@ async function main() {
     process.exit(EXIT_CODES.SUCCESS);
 }
 // Guard main() for testability
+// WU-1071: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }
 // Export for testing
-export { parseArgs, detectWorktreePath };
+export { detectWorktreePath };