@lumenflow/cli 2.2.2 → 2.3.1

package/dist/wu-create.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
 /**
  * WU Create Helper (WU-1262, WU-1439)
  *
@@ -30,7 +31,7 @@ import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-// WU-1352: Use centralized YAML functions from wu-yaml.mjs
+// WU-1352: Use centralized YAML functions from wu-yaml.ts
 import { stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
 // WU-1428: Use date-utils for consistent YYYY-MM-DD format (library-first)
 import { todayISO } from '@lumenflow/core/dist/date-utils.js';
@@ -48,6 +49,8 @@ import { COMMIT_FORMATS, FILE_SYSTEM, READINESS_UI, STRING_LITERALS, } from '@lu
 import { ensureOnMain, validateWUIDFormat } from '@lumenflow/core/dist/wu-helpers.js';
 // WU-1439: Use shared micro-worktree helper
 import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+// WU-1246: Auto-generate WU IDs when --id not provided
+import { generateWuIdWithRetry } from '@lumenflow/core/dist/wu-id-generator.js';
 // WU-1620: Import spec completeness validator for readiness summary
 import { validateSpecCompleteness } from '@lumenflow/core/dist/wu-done-validators.js';
 // WU-1620: Import readWU to read back created YAML for validation
@@ -56,6 +59,8 @@ import { readWU } from '@lumenflow/core/dist/wu-yaml.js';
 import { lintWUSpec, formatLintErrors } from '@lumenflow/core/dist/wu-lint.js';
 // WU-1025: Import placeholder validator for inline content validation
 import { validateNoPlaceholders, buildPlaceholderErrorMessage, } from '@lumenflow/core/dist/wu-validator.js';
+// WU-1211: Import initiative validation for phase check
+import { checkInitiativePhases, findInitiative } from '@lumenflow/initiatives/dist/index.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[wu:create]';
 /** Micro-worktree operation name */
@@ -77,21 +82,16 @@ const MIN_CONFIDENCE_FOR_WARNING = 30;
  * Non-blocking - just logs a warning if a better lane is suggested.
  *
  * @param {string} providedLane - Lane provided by the user
- * @param {string|undefined} codePathsRaw - Comma-separated code paths
+ * @param {string[]|undefined} codePathsArray - Code paths array from Commander
  * @param {string} title - WU title (used as fallback description)
  * @param {string|undefined} description - WU description
  */
-export function warnIfBetterLaneExists(providedLane, codePathsRaw, title, description) {
-    if (!codePathsRaw && !description) {
+export function warnIfBetterLaneExists(providedLane, codePathsArray, title, description) {
+    if (!codePathsArray?.length && !description) {
         return;
     }
     try {
-        const codePaths = codePathsRaw
-            ? codePathsRaw
-                .split(',')
-                .map((s) => s.trim())
-                .filter(Boolean)
-            : [];
+        const codePaths = codePathsArray ?? [];
         const descForInference = description || title;
         const suggestion = inferSubLane(codePaths, descForInference);
         // Only warn if suggestion differs and confidence is meaningful
@@ -105,7 +105,7 @@ export function warnIfBetterLaneExists(providedLane, codePathsRaw, title, descri
         const isDifferentLane = providedParent !== suggestedParent;
         if (isMoreSpecific || isDifferentLane) {
             console.warn(`${LOG_PREFIX} Consider using "${suggestion.lane}" (${suggestion.confidence}% match) instead of "${providedLane}"`);
-            console.warn(`${LOG_PREFIX}    Run: pnpm wu:infer-lane --paths "${codePathsRaw || ''}" --desc "${title}"`);
+            console.warn(`${LOG_PREFIX}    Run: pnpm wu:infer-lane --paths "${codePaths.join(' ')}" --desc "${title}"`);
         }
     }
     catch {
@@ -179,19 +179,12 @@ function displayReadinessSummary(id) {
         console.warn(`${LOG_PREFIX} ⚠️  Could not validate readiness: ${err.message}`);
     }
 }
-// Helper to parse comma-separated strings into arrays (DRY)
-const parseCommaSeparated = (value) => value
-    ? value
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean)
-    : [];
 function mergeSpecRefs(specRefs, extraRef) {
-    const refs = parseCommaSeparated(specRefs);
+    const refs = specRefs ? [...specRefs] : [];
     if (extraRef && !refs.includes(extraRef)) {
         refs.push(extraRef);
     }
-    return refs.length > 0 ? refs.join(',') : undefined;
+    return refs;
 }
 function createPlanTemplate(wuId, title) {
     const plansDir = getPlansDir();
@@ -218,11 +211,12 @@ function createPlanTemplate(wuId, title) {
 }
 function buildWUContent({ id, lane, title, priority, type, created, opts, }) {
     const { description, acceptance, codePaths, testPathsManual, testPathsUnit, testPathsE2e, initiative, phase, blockedBy, blocks, labels, assignedTo, exposure, userJourney, uiPairingWus, specRefs, } = opts;
-    const code_paths = parseCommaSeparated(codePaths);
+    // Arrays come directly from Commander.js repeatable options - no parsing needed
+    const code_paths = codePaths ?? [];
     const tests = {
-        manual: parseCommaSeparated(testPathsManual),
-        unit: parseCommaSeparated(testPathsUnit),
-        e2e: parseCommaSeparated(testPathsE2e),
+        manual: testPathsManual ?? [],
+        unit: testPathsUnit ?? [],
+        e2e: testPathsE2e ?? [],
     };
     return {
         id,
@@ -243,14 +237,14 @@ function buildWUContent({ id, lane, title, priority, type, created, opts, }) {
         requires_review: false,
         ...(initiative && { initiative }),
         ...(phase && { phase: parseInt(phase, 10) }),
-        ...(blockedBy && { blocked_by: blockedBy.split(',').map((s) => s.trim()) }),
-        ...(blocks && { blocks: blocks.split(',').map((s) => s.trim()) }),
-        ...(labels && { labels: labels.split(',').map((s) => s.trim()) }),
+        ...(blockedBy?.length && { blocked_by: blockedBy }),
+        ...(blocks?.length && { blocks }),
+        ...(labels?.length && { labels }),
         ...(assignedTo && { assigned_to: assignedTo }),
         ...(exposure && { exposure }),
         ...(userJourney && { user_journey: userJourney }),
-        ...(uiPairingWus && { ui_pairing_wus: parseCommaSeparated(uiPairingWus) }),
-        ...(specRefs && { spec_refs: parseCommaSeparated(specRefs) }),
+        ...(uiPairingWus?.length && { ui_pairing_wus: uiPairingWus }),
+        ...(specRefs?.length && { spec_refs: specRefs }),
     };
 }
 export function validateCreateSpec({ id, lane, title, priority, type, opts, }) {
@@ -453,6 +447,7 @@ async function getDefaultAssignedTo() {
         return '';
     }
 }
+// eslint-disable-next-line sonarjs/cognitive-complexity -- main() orchestrates multi-step WU creation workflow
 async function main() {
     const args = createWUParser({
         name: 'wu-create',
@@ -488,12 +483,32 @@ async function main() {
             // WU-1062: External plan options for wu:create
             WU_CREATE_OPTIONS.plan,
         ],
-        required: ['id', 'lane', 'title'],
+        required: ['lane', 'title'], // WU-1246: --id is now optional (auto-generated if not provided)
         allowPositionalId: false,
     });
-    console.log(`${LOG_PREFIX} Creating WU ${args.id} in ${args.lane} lane...`);
-    // Pre-flight checks (validation only - no main modification)
-    validateWUIDFormat(args.id);
+    // WU-1246: Auto-generate WU ID if not provided
+    let wuId;
+    if (args.id) {
+        wuId = args.id;
+        // Validate explicitly provided ID
+        validateWUIDFormat(wuId);
+    }
+    else {
+        // Auto-generate next sequential ID
+        console.log(`${LOG_PREFIX} Auto-generating WU ID...`);
+        try {
+            wuId = await generateWuIdWithRetry();
+            console.log(`${LOG_PREFIX} Generated WU ID: ${wuId}`);
+        }
+        catch (error) {
+            die(`Failed to auto-generate WU ID: ${error.message}\n\n` +
+                `Options:\n` +
+                `  1. Retry the command (transient file system issue)\n` +
+                `  2. Provide an explicit ID: --id WU-XXXX\n` +
+                `  3. Check for race conditions if running parallel wu:create`);
+        }
+    }
+    console.log(`${LOG_PREFIX} Creating WU ${wuId} in ${args.lane} lane...`);
     // Validate lane format (sub-lane or parent-only)
     try {
         validateLaneFormat(args.lane);
@@ -512,16 +527,16 @@ async function main() {
     // WU-2330: Warn if a more specific sub-lane matches code_paths or description
     warnIfBetterLaneExists(args.lane, args.codePaths, args.title, args.description);
     await ensureOnMain(getGitForCwd());
-    checkWUExists(args.id);
+    checkWUExists(wuId);
     // WU-1368: Get assigned_to from flag or git config user.email
     const assignedTo = args.assignedTo || (await getDefaultAssignedTo());
     if (!assignedTo) {
         console.warn(`${LOG_PREFIX} ⚠️  No assigned_to set - WU will need manual assignment`);
     }
-    const planSpecRef = args.plan ? getPlanProtocolRef(args.id) : undefined;
+    const planSpecRef = args.plan ? getPlanProtocolRef(wuId) : undefined;
     const mergedSpecRefs = mergeSpecRefs(args.specRefs, planSpecRef);
     const createSpecValidation = validateCreateSpec({
-        id: args.id,
+        id: wuId,
         lane: args.lane,
         title: args.title,
         priority: args.priority || DEFAULT_PRIORITY,
@@ -552,7 +567,17 @@ async function main() {
         die(`${LOG_PREFIX} ❌ Spec validation failed:\n\n${errorList}`);
     }
     console.log(`${LOG_PREFIX} ✅ Spec validation passed`);
-    const specRefsList = parseCommaSeparated(mergedSpecRefs);
+    // WU-1211: Warn if linking to initiative with no phases defined
+    if (args.initiative) {
+        const initiative = findInitiative(args.initiative);
+        if (initiative) {
+            const phaseCheck = checkInitiativePhases(initiative.doc);
+            if (!phaseCheck.hasPhases && phaseCheck.warning) {
+                console.warn(`${LOG_PREFIX} ⚠️  ${phaseCheck.warning}`);
+            }
+        }
+    }
+    const specRefsList = mergedSpecRefs;
     const specRefsValidation = validateSpecRefs(specRefsList);
     if (!specRefsValidation.valid) {
         const errorList = specRefsValidation.errors
@@ -566,7 +591,7 @@ async function main() {
         }
     }
     if (args.plan) {
-        createPlanTemplate(args.id, args.title);
+        createPlanTemplate(wuId, args.title);
     }
     // Transaction: micro-worktree isolation (WU-1439)
     try {
@@ -577,11 +602,11 @@ async function main() {
         try {
             await withMicroWorktree({
                 operation: OPERATION_NAME,
-                id: args.id,
+                id: wuId,
                 logPrefix: LOG_PREFIX,
                 execute: async ({ worktreePath }) => {
                     // Create WU YAML in micro-worktree
-                    const wuPath = createWUYamlInWorktree(worktreePath, args.id, args.lane, args.title, priority, type, {
+                    const wuPath = createWUYamlInWorktree(worktreePath, wuId, args.lane, args.title, priority, type, {
                         // Initiative system fields (WU-1247)
                         initiative: args.initiative,
                         phase: args.phase,
@@ -605,10 +630,10 @@ async function main() {
                         specRefs: mergedSpecRefs,
                     });
                     // Update backlog.md in micro-worktree
-                    const backlogPath = updateBacklogInWorktree(worktreePath, args.id, args.lane, args.title);
+                    const backlogPath = updateBacklogInWorktree(worktreePath, wuId, args.lane, args.title);
                     // Build commit message
                     const shortTitle = truncateTitle(args.title);
-                    const commitMessage = COMMIT_FORMATS.CREATE(args.id, shortTitle);
+                    const commitMessage = COMMIT_FORMATS.CREATE(wuId, shortTitle);
                     // Return commit message and files to commit
                     return {
                         commitMessage,
@@ -626,12 +651,12 @@ async function main() {
             }
         }
         console.log(`\n${LOG_PREFIX} ✅ Transaction complete!`);
-        console.log(`\nWU ${args.id} created successfully:`);
-        console.log(`  File: ${WU_PATHS.WU(args.id)}`);
+        console.log(`\nWU ${wuId} created successfully:`);
+        console.log(`  File: ${WU_PATHS.WU(wuId)}`);
         console.log(`  Lane: ${args.lane}`);
         console.log(`  Status: ready`);
         // WU-1620: Display readiness summary
-        displayReadinessSummary(args.id);
+        displayReadinessSummary(wuId);
     }
     catch (error) {
         die(`Transaction failed: ${error.message}\n\n` +
@@ -645,5 +670,5 @@ async function main() {
 // path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
 if (import.meta.main) {
-    runCLI(main);
+    void runCLI(main);
 }

package/dist/wu-delete.js

@@ -122,35 +122,49 @@ async function deleteSingleWU(id, dryRun) {
     await ensureCleanWorkingTree();
     await ensureMainUpToDate(getGitForCwd(), 'wu:delete');
     console.log(`${PREFIX} Deleting via micro-worktree...`);
-    await withMicroWorktree({
-        operation: MICRO_WORKTREE_OPERATIONS.WU_DELETE,
-        id: id,
-        logPrefix: PREFIX,
-        execute: async ({ worktreePath, gitWorktree }) => {
-            const wuFilePath = join(worktreePath, wuPath);
-            const backlogFilePath = join(worktreePath, WU_PATHS.BACKLOG());
-            unlinkSync(wuFilePath);
-            console.log(`${PREFIX} ✅ Deleted ${id}.yaml`);
-            const stampPath = join(worktreePath, getStampPath(id));
-            if (existsSync(stampPath)) {
-                unlinkSync(stampPath);
-                console.log(`${PREFIX} ✅ Deleted stamp ${id}.done`);
-            }
-            const removedFromBacklog = removeFromBacklog(backlogFilePath, id);
-            if (removedFromBacklog) {
-                console.log(`${PREFIX} ✅ Removed ${id} from backlog.md`);
-            }
-            else {
-                console.log(`${PREFIX} ℹ️  ${id} was not found in backlog.md`);
-            }
-            await gitWorktree.add('.');
-            const commitMessage = `docs: delete ${id.toLowerCase()}`;
-            return {
-                commitMessage,
-                files: [],
-            };
-        },
-    });
+    // WU-1245: Set LUMENFLOW_WU_TOOL for pre-push hook allowlist
+    const previousWuTool = process.env.LUMENFLOW_WU_TOOL;
+    process.env.LUMENFLOW_WU_TOOL = MICRO_WORKTREE_OPERATIONS.WU_DELETE;
+    try {
+        await withMicroWorktree({
+            operation: MICRO_WORKTREE_OPERATIONS.WU_DELETE,
+            id: id,
+            logPrefix: PREFIX,
+            execute: async ({ worktreePath, gitWorktree }) => {
+                const wuFilePath = join(worktreePath, wuPath);
+                const backlogFilePath = join(worktreePath, WU_PATHS.BACKLOG());
+                unlinkSync(wuFilePath);
+                console.log(`${PREFIX} ✅ Deleted ${id}.yaml`);
+                const stampPath = join(worktreePath, getStampPath(id));
+                if (existsSync(stampPath)) {
+                    unlinkSync(stampPath);
+                    console.log(`${PREFIX} ✅ Deleted stamp ${id}.done`);
+                }
+                const removedFromBacklog = removeFromBacklog(backlogFilePath, id);
+                if (removedFromBacklog) {
+                    console.log(`${PREFIX} ✅ Removed ${id} from backlog.md`);
+                }
+                else {
+                    console.log(`${PREFIX} ℹ️  ${id} was not found in backlog.md`);
+                }
+                await gitWorktree.add('.');
+                const commitMessage = `docs: delete ${id.toLowerCase()}`;
+                return {
+                    commitMessage,
+                    files: [],
+                };
+            },
+        });
+    }
+    finally {
+        // Restore previous LUMENFLOW_WU_TOOL value
+        if (previousWuTool === undefined) {
+            delete process.env.LUMENFLOW_WU_TOOL;
+        }
+        else {
+            process.env.LUMENFLOW_WU_TOOL = previousWuTool;
+        }
+    }
     console.log(`${PREFIX} ✅ Successfully deleted ${id}`);
     console.log(`${PREFIX} Changes pushed to origin/main`);
 }
@@ -179,39 +193,53 @@ async function deleteBatchWUs(ids, dryRun) {
     await ensureCleanWorkingTree();
     await ensureMainUpToDate(getGitForCwd(), 'wu:delete --batch');
     console.log(`${PREFIX} Deleting ${ids.length} WU(s) via micro-worktree...`);
-    await withMicroWorktree({
-        operation: MICRO_WORKTREE_OPERATIONS.WU_DELETE,
-        id: `batch-${ids.length}`,
-        logPrefix: PREFIX,
-        execute: async ({ worktreePath, gitWorktree }) => {
-            const backlogFilePath = join(worktreePath, WU_PATHS.BACKLOG());
-            for (const { id, wuPath } of wusToDelete) {
-                const wuFilePath = join(worktreePath, wuPath);
-                unlinkSync(wuFilePath);
-                console.log(`${PREFIX} ✅ Deleted ${id}.yaml`);
-            }
-            for (const id of stampsToDelete) {
-                const stampPath = join(worktreePath, getStampPath(id));
-                if (existsSync(stampPath)) {
-                    unlinkSync(stampPath);
-                    console.log(`${PREFIX} ✅ Deleted stamp ${id}.done`);
+    // WU-1245: Set LUMENFLOW_WU_TOOL for pre-push hook allowlist
+    const previousWuTool = process.env.LUMENFLOW_WU_TOOL;
+    process.env.LUMENFLOW_WU_TOOL = MICRO_WORKTREE_OPERATIONS.WU_DELETE;
+    try {
+        await withMicroWorktree({
+            operation: MICRO_WORKTREE_OPERATIONS.WU_DELETE,
+            id: `batch-${ids.length}`,
+            logPrefix: PREFIX,
+            execute: async ({ worktreePath, gitWorktree }) => {
+                const backlogFilePath = join(worktreePath, WU_PATHS.BACKLOG());
+                for (const { id, wuPath } of wusToDelete) {
+                    const wuFilePath = join(worktreePath, wuPath);
+                    unlinkSync(wuFilePath);
+                    console.log(`${PREFIX} ✅ Deleted ${id}.yaml`);
                 }
-            }
-            for (const { id } of wusToDelete) {
-                const removed = removeFromBacklog(backlogFilePath, id);
-                if (removed) {
-                    console.log(`${PREFIX} ✅ Removed ${id} from backlog.md`);
+                for (const id of stampsToDelete) {
+                    const stampPath = join(worktreePath, getStampPath(id));
+                    if (existsSync(stampPath)) {
+                        unlinkSync(stampPath);
+                        console.log(`${PREFIX} ✅ Deleted stamp ${id}.done`);
+                    }
                 }
-            }
-            await gitWorktree.add('.');
-            const idList = ids.map((id) => id.toLowerCase()).join(', ');
-            const commitMessage = `chore(repair): delete ${ids.length} orphaned wus (${idList})`;
-            return {
-                commitMessage,
-                files: [],
-            };
-        },
-    });
+                for (const { id } of wusToDelete) {
+                    const removed = removeFromBacklog(backlogFilePath, id);
+                    if (removed) {
+                        console.log(`${PREFIX} ✅ Removed ${id} from backlog.md`);
+                    }
+                }
+                await gitWorktree.add('.');
+                const idList = ids.map((id) => id.toLowerCase()).join(', ');
+                const commitMessage = `chore(repair): delete ${ids.length} orphaned wus (${idList})`;
+                return {
+                    commitMessage,
+                    files: [],
+                };
+            },
+        });
+    }
+    finally {
+        // Restore previous LUMENFLOW_WU_TOOL value
+        if (previousWuTool === undefined) {
+            delete process.env.LUMENFLOW_WU_TOOL;
+        }
+        else {
+            process.env.LUMENFLOW_WU_TOOL = previousWuTool;
+        }
+    }
     console.log(`${PREFIX} ✅ Successfully deleted ${ids.length} WU(s)`);
     console.log(`${PREFIX} Changes pushed to origin/main`);
 }

package/dist/wu-deps.js

@@ -12,7 +12,7 @@
  */
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
-import { buildDependencyGraph, renderASCII, renderMermaid, validateGraph, } from '@lumenflow/core/dist/dependency-graph.js';
+import { buildDependencyGraphAsync, renderASCII, renderMermaid, validateGraph, } from '@lumenflow/core/dist/dependency-graph.js';
 import { OUTPUT_FORMATS } from '@lumenflow/initiatives/dist/initiative-constants.js';
 import { PATTERNS } from '@lumenflow/core/dist/wu-constants.js';
 async function main() {
@@ -31,7 +31,7 @@ async function main() {
         die(`Invalid WU ID format: "${wuId}"\n\nExpected format: WU-<number> (e.g., WU-1247)`);
     }
     console.log(`[wu:deps] Building dependency graph...`);
-    const graph = buildDependencyGraph();
+    const graph = await buildDependencyGraphAsync();
     if (!graph.has(wuId)) {
         die(`WU not found in graph: ${wuId}\n\nEnsure the WU exists in docs/04-operations/tasks/wu/`);
     }
@@ -112,9 +112,10 @@ function renderGraphJSON(graph, rootId, depth, direction) {
     }
     return JSON.stringify(output, null, 2);
 }
-// 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-done-check.js

@@ -0,0 +1,34 @@
+import { createGitForPath } from '@lumenflow/core/git-adapter';
+import { die } from '@lumenflow/core/error-handler';
+import { LOG_PREFIX } from '@lumenflow/core/dist/wu-constants.js';
+/**
+ * WU-1169: Ensure worktree is clean before wu:done operations.
+ *
+ * Prevents WU-1943 rollback loops where uncommitted changes in the worktree
+ * cause auto-rebase to fail, triggering an expensive restoration that wipes
+ * the uncommitted changes.
+ *
+ * This check HALTS wu:done immediately if the worktree is dirty.
+ *
+ * @param {string} worktreePath - Absolute path to the worktree
+ */
+export async function ensureCleanWorktree(worktreePath) {
+    try {
+        const git = createGitForPath(worktreePath);
+        const status = await git.getStatus();
+        if (status.trim()) {
+            die(`Worktree has uncommitted changes. Cannot proceed with wu:done.\n\n` +
+                `Path: ${worktreePath}\n\n` +
+                `Uncommitted changes:\n${status}\n\n` +
+                `❌ BLOCKING: Uncommitted changes would be lost during auto-rebase.\n\n` +
+                `Fix:\n` +
+                `  1. cd worktrees/<lane>-wu-xxx\n` +
+                `  2. git add . && git commit -m "wip: ..."\n` +
+                `  3. Retry pnpm wu:done --id WU-XXXX`);
+        }
+    }
+    catch (err) {
+        // If worktree is missing or git fails, let the flow continue (handled by other checks)
+        console.warn(`${LOG_PREFIX.DONE} Warning: Could not check worktree status: ${err.message}`);
+    }
+}

package/dist/wu-done.js

@@ -31,11 +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)
@@ -54,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';
@@ -86,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',
@@ -148,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
@@ -445,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';
@@ -501,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.
  *
@@ -719,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();
@@ -764,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)
@@ -847,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
@@ -1000,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
@@ -1862,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.');
@@ -1915,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;
@@ -1940,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,