@lumenflow/cli 1.1.0 → 1.3.2

package/dist/wu-cleanup.js

@@ -5,7 +5,7 @@
  * Cleans up worktree and branch after PR merge (PR-based completion workflow).
  *
  * Sequence:
- * 1) Verify PR is merged (via gh API or git merge-base fallback)
+ * 1) Verify PR is merged (via gh API; no merge-base fallback)
  * 2) Remove worktree (if exists)
  * 3) Delete lane branch (local + remote)
  *
@@ -13,33 +13,60 @@
  *
  * Usage:
  *   pnpm wu:cleanup --id WU-703
+ *   pnpm wu:cleanup --artifacts
  */
 import { execSync } from 'node:child_process';
-import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { createGitForPath, getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { cleanupWorktreeBuildArtifacts } from '@lumenflow/core/dist/rebase-artifact-cleanup.js';
+import { detectCurrentWorktree } from '@lumenflow/core/dist/wu-done-validators.js';
 import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { readWU } from '@lumenflow/core/dist/wu-yaml.js';
-import { BRANCHES, EXIT_CODES, FILE_SYSTEM, REMOTES, GIT_REFS, } from '@lumenflow/core/dist/wu-constants.js';
+import { isGhCliAvailable } from '@lumenflow/core/dist/wu-done-pr.js';
+import { BOX, CLEANUP_GUARD, EXIT_CODES, FILE_SYSTEM, LOG_PREFIX, REMOTES, STRING_LITERALS, WU_STATUS, } from '@lumenflow/core/dist/wu-constants.js';
 // WU-2278: Import ownership validation for cross-agent protection
 import { validateWorktreeOwnership } from '@lumenflow/core/dist/worktree-ownership.js';
 /* eslint-disable security/detect-non-literal-fs-filename */
-// Box drawing characters for consistent output
-const BOX = {
-    TOP: '╔═══════════════════════════════════════════════════════════════════╗',
-    MID: '╠═══════════════════════════════════════════════════════════════════╣',
-    BOT: '╚═══════════════════════════════════════════════════════════════════╝',
+const CLEANUP_OPTIONS = {
+    artifacts: {
+        name: 'artifacts',
+        flags: '--artifacts',
+        description: 'Remove build artifacts (dist, tsbuildinfo) in current worktree',
+    },
 };
+export const CLEANUP_GUARD_REASONS = CLEANUP_GUARD.REASONS;
+export function evaluateCleanupGuards({ hasUncommittedChanges, hasUnpushedCommits, hasStamp, yamlStatus, ghAvailable, prMerged, }) {
+    if (hasUncommittedChanges) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.UNCOMMITTED_CHANGES };
+    }
+    if (hasUnpushedCommits) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.UNPUSHED_COMMITS };
+    }
+    if (yamlStatus !== WU_STATUS.DONE) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.STATUS_NOT_DONE };
+    }
+    if (!hasStamp) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.MISSING_STAMP };
+    }
+    if (ghAvailable && prMerged !== true) {
+        return { allowed: false, reason: CLEANUP_GUARD_REASONS.PR_NOT_MERGED };
+    }
+    return { allowed: true, reason: null };
+}
 // Help text is now auto-generated by commander via createWUParser
 async function verifyPRMerged(laneBranch) {
-    // Try gh API first (most reliable)
+    if (!isGhCliAvailable()) {
+        return { merged: null, method: 'gh_unavailable' };
+    }
     let ghResult;
     try {
         ghResult = execSync(`gh api repos/:owner/:repo/pulls -q '.[] | select(.head.ref == "${laneBranch}") | .merged'`, { encoding: FILE_SYSTEM.UTF8 }).trim();
     }
     catch {
-        ghResult = '';
+        ghResult = STRING_LITERALS.EMPTY;
     }
     if (ghResult === 'true') {
         return { merged: true, method: 'gh_api' };
@@ -47,37 +74,7 @@ async function verifyPRMerged(laneBranch) {
     if (ghResult === 'false') {
         return { merged: false, method: 'gh_api' };
     }
-    // Fallback: git merge-base --is-ancestor
-    // Always fetch origin/main first for accurate merge-base check
-    await getGitForCwd().fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
-    const localBranchExists = await getGitForCwd().branchExists(laneBranch);
-    if (!localBranchExists) {
-        // Branch doesn't exist locally - check if it exists remotely
-        const remoteBranchExists = await getGitForCwd().raw([
-            'ls-remote',
-            '--heads',
-            REMOTES.ORIGIN,
-            laneBranch,
-        ]);
-        if (!remoteBranchExists) {
-            // Branch is gone both locally and remotely - assume merged
-            return { merged: true, method: 'branch_deleted' };
-        }
-        // Branch exists remotely but not locally - need to fetch
-        await getGitForCwd().fetch(REMOTES.ORIGIN, laneBranch);
-    }
-    let isAncestor;
-    try {
-        await getGitForCwd().raw(['merge-base', '--is-ancestor', laneBranch, GIT_REFS.ORIGIN_MAIN]);
-        isAncestor = true;
-    }
-    catch {
-        isAncestor = false;
-    }
-    if (isAncestor) {
-        return { merged: true, method: 'git_merge_base' };
-    }
-    return { merged: false, method: 'git_merge_base' };
+    return { merged: null, method: 'gh_api' };
 }
 async function removeWorktree(worktreePath) {
     if (!existsSync(worktreePath)) {
@@ -115,14 +112,74 @@ async function deleteBranch(laneBranch) {
         console.log(`[wu-cleanup] ✓ Remote branch already deleted: ${laneBranch}`);
     }
 }
+async function cleanupArtifactsInWorktree() {
+    const worktreePath = detectCurrentWorktree();
+    if (!worktreePath) {
+        die(`${LOG_PREFIX.CLEANUP} Not in a worktree.\n\n` +
+            'Run this command from inside a worktree:\n' +
+            '  cd worktrees/<lane>-wu-xxx\n' +
+            '  pnpm wu:cleanup --artifacts\n');
+    }
+    console.log(`${LOG_PREFIX.CLEANUP} Cleaning build artifacts in ${worktreePath}`);
+    const result = await cleanupWorktreeBuildArtifacts(worktreePath);
+    if (result.removedCount === 0) {
+        console.log(`${LOG_PREFIX.CLEANUP} ✓ No build artifacts found`);
+        return;
+    }
+    if (result.distDirectories.length > 0) {
+        console.log(`${LOG_PREFIX.CLEANUP} Removed dist directories:`);
+        for (const dir of result.distDirectories) {
+            console.log(`  - ${dir}`);
+        }
+    }
+    if (result.tsbuildinfoFiles.length > 0) {
+        console.log(`${LOG_PREFIX.CLEANUP} Removed tsbuildinfo files:`);
+        for (const file of result.tsbuildinfoFiles) {
+            console.log(`  - ${file}`);
+        }
+    }
+    console.log(`${LOG_PREFIX.CLEANUP} ✓ Build artifact cleanup complete`);
+}
+async function hasUncommittedChanges(worktreePath) {
+    if (!existsSync(worktreePath)) {
+        return false;
+    }
+    const git = createGitForPath(worktreePath);
+    const status = await git.getStatus();
+    return status.length > 0;
+}
+async function hasUnpushedCommits(worktreePath) {
+    if (!existsSync(worktreePath)) {
+        return false;
+    }
+    const git = createGitForPath(worktreePath);
+    try {
+        const unpushed = await git.getUnpushedCommits();
+        return unpushed.length > 0;
+    }
+    catch {
+        return true;
+    }
+}
+function hasStampFile(wuId) {
+    const stampPath = path.join(process.cwd(), WU_PATHS.STAMP(wuId));
+    return existsSync(stampPath);
+}
 async function main() {
     const args = createWUParser({
         name: 'wu-cleanup',
         description: 'Clean up worktree and branch after PR merge (PR-based completion workflow)',
-        options: [WU_OPTIONS.id],
-        required: ['id'],
+        options: [WU_OPTIONS.id, CLEANUP_OPTIONS.artifacts],
+        required: [],
         allowPositionalId: true,
     });
+    if (args.artifacts) {
+        await cleanupArtifactsInWorktree();
+        return;
+    }
+    if (!args.id) {
+        die(`${LOG_PREFIX.CLEANUP} Missing required --id (or use --artifacts).`);
+    }
     const id = args.id.toUpperCase();
     const wu = readWU(WU_PATHS.WU(id), id);
     // Use kebab-case lane naming (match wu-claim.mjs logic)
@@ -135,6 +192,7 @@ async function main() {
     const idK = args.id.toLowerCase();
     const laneBranch = `lane/${laneK}/${idK}`;
     const worktreePath = path.join('worktrees', `${laneK}-${idK}`);
+    const absoluteWorktreePath = path.resolve(worktreePath);
     console.log(`[wu-cleanup] Cleaning up ${args.id} (${wu.title})`);
     console.log(`[wu-cleanup] Lane: ${wu.lane}`);
     console.log(`[wu-cleanup] Branch: ${laneBranch}`);
@@ -154,25 +212,38 @@ async function main() {
         console.error(BOX.BOT);
         process.exit(EXIT_CODES.ERROR);
     }
-    // 1. Verify PR is merged
-    console.log('[wu-cleanup] Verifying PR merge status...');
-    const { merged, method } = await verifyPRMerged(laneBranch);
-    if (!merged) {
+    const cleanupCheck = {
+        hasUncommittedChanges: await hasUncommittedChanges(absoluteWorktreePath),
+        hasUnpushedCommits: await hasUnpushedCommits(absoluteWorktreePath),
+        hasStamp: hasStampFile(id),
+        yamlStatus: wu.status,
+        ghAvailable: isGhCliAvailable(),
+        prMerged: null,
+    };
+    if (cleanupCheck.ghAvailable) {
+        console.log(`${LOG_PREFIX.CLEANUP} ${CLEANUP_GUARD.PR_CHECK.START}`);
+        const { merged, method } = await verifyPRMerged(laneBranch);
+        cleanupCheck.prMerged = merged;
+        console.log(`${LOG_PREFIX.CLEANUP} ${CLEANUP_GUARD.PR_CHECK.RESULT} ${method}`);
+        console.log();
+    }
+    const guardResult = evaluateCleanupGuards(cleanupCheck);
+    if (!guardResult.allowed) {
         console.error();
         console.error(BOX.TOP);
-        console.error('║  PR NOT MERGED');
+        console.error(`${BOX.SIDE}  ${CLEANUP_GUARD.TITLES.BLOCKED}`);
         console.error(BOX.MID);
-        console.error(`║  Branch ${laneBranch} has not been merged to main yet.`);
-        console.error('║');
-        console.error('║  Next steps:');
-        console.error('║  1. Review the PR in GitHub UI');
-        console.error('║  2. Merge the PR');
-        console.error(`║  3. Re-run: pnpm wu:cleanup --id ${args.id}`);
+        console.error(`${BOX.SIDE}  ${CLEANUP_GUARD.MESSAGES[guardResult.reason]}`);
+        console.error(`${BOX.SIDE}`);
+        console.error(`${BOX.SIDE}  ${CLEANUP_GUARD.TITLES.NEXT_STEPS}`);
+        const steps = CLEANUP_GUARD.NEXT_STEPS[guardResult.reason] || CLEANUP_GUARD.NEXT_STEPS.DEFAULT;
+        for (const step of steps) {
+            const line = step.appendId ? `${step.text} ${args.id}` : step.text;
+            console.error(`${BOX.SIDE}  ${line}`);
+        }
         console.error(BOX.BOT);
         process.exit(EXIT_CODES.ERROR);
     }
-    console.log(`[wu-cleanup] ✓ PR merged (verified via ${method})`);
-    console.log();
     // 2. Remove worktree
     await removeWorktree(worktreePath);
     console.log();
@@ -189,6 +260,7 @@ async function main() {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }

package/dist/wu-create.js

@@ -40,7 +40,7 @@ import { inferSubLane } from '@lumenflow/core/dist/lane-inference.js';
 import { parseBacklogFrontmatter } from '@lumenflow/core/dist/backlog-parser.js';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
-import { PLACEHOLDER_SENTINEL, validateReadyWU } from '@lumenflow/core/dist/wu-schema.js';
+import { validateWU } from '@lumenflow/core/dist/wu-schema.js';
 import { COMMIT_FORMATS, FILE_SYSTEM, STRING_LITERALS, READINESS_UI, } from '@lumenflow/core/dist/wu-constants.js';
 // WU-1593: Use centralized validateWUIDFormat (DRY)
 import { ensureOnMain, validateWUIDFormat } from '@lumenflow/core/dist/wu-helpers.js';
@@ -52,6 +52,8 @@ import { validateSpecCompleteness } from '@lumenflow/core/dist/wu-done-validator
 import { readWU } from '@lumenflow/core/dist/wu-yaml.js';
 // WU-2253: Import WU spec linter for acceptance/code_paths validation
 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';
 /** Log prefix for console output */
 const LOG_PREFIX = '[wu:create]';
 /** Micro-worktree operation name */
@@ -175,67 +177,29 @@ function displayReadinessSummary(id) {
         console.warn(`${LOG_PREFIX} ⚠️  Could not validate readiness: ${err.message}`);
     }
 }
-/**
- * Create WU YAML file in micro-worktree
- *
- * @param {string} worktreePath - Path to micro-worktree
- * @param {string} id - WU ID
- * @param {string} lane - WU lane
- * @param {string} title - WU title
- * @param {string} priority - WU priority
- * @param {string} type - WU type
- * @param {Object} opts - Additional options
- * @returns {string} Relative path to created YAML file
- */
-function createWUYamlInWorktree(worktreePath, id, lane, title, priority, type, opts = {}) {
-    const wuRelativePath = WU_PATHS.WU(id);
-    const wuAbsolutePath = join(worktreePath, wuRelativePath);
-    const wuDir = join(worktreePath, WU_PATHS.WU_DIR());
-    mkdirSync(wuDir, { recursive: true });
-    // WU-1428: Use todayISO() for consistent YYYY-MM-DD format (library-first)
-    const today = todayISO();
-    // Parse initiative system fields from opts (WU-1247) and assigned_to (WU-1368)
-    const { initiative, phase, blockedBy, blocks, labels, assignedTo } = opts;
-    // WU-1364: Parse full spec inline options
-    const { description: inlineDescription, acceptance: inlineAcceptance, codePaths, testPathsManual, testPathsUnit, testPathsE2e, } = opts;
-    // WU-1998: Parse exposure field options
-    const { exposure, userJourney, uiPairingWus } = opts;
-    // WU-2320: Parse spec_refs option
-    const { specRefs } = opts;
-    // Helper to parse comma-separated strings into arrays (DRY)
-    const parseCommaSeparated = (value) => value
-        ? value
-            .split(',')
-            .map((s) => s.trim())
-            .filter(Boolean)
-        : [];
-    // WU-1364: Build description (inline or placeholder)
-    const description = inlineDescription
-        ? inlineDescription
-        : `${PLACEHOLDER_SENTINEL} Describe the work to be done.\n\nContext: ...\nProblem: ...\nSolution: ...\n`;
-    // WU-1364: Build acceptance (inline array or placeholder)
-    const acceptance = inlineAcceptance && inlineAcceptance.length > 0
-        ? inlineAcceptance
-        : [
-            `${PLACEHOLDER_SENTINEL} Define acceptance criteria`,
-            'pnpm format, lint, typecheck → PASS',
-        ];
-    // WU-1364: Build code_paths from inline flag
+// Helper to parse comma-separated strings into arrays (DRY)
+const parseCommaSeparated = (value) => value
+    ? value
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+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);
-    // WU-1364: Build tests object from inline flags
     const tests = {
         manual: parseCommaSeparated(testPathsManual),
         unit: parseCommaSeparated(testPathsUnit),
         e2e: parseCommaSeparated(testPathsE2e),
     };
-    const wuContent = {
+    return {
         id,
         title,
         lane,
         type,
         status: 'ready',
         priority,
-        created: today,
+        created,
         description,
         acceptance,
         code_paths,
@@ -245,24 +209,107 @@ function createWUYamlInWorktree(worktreePath, id, lane, title, priority, type, o
         risks: [],
         notes: '',
         requires_review: false,
-        // Initiative system fields - only include if provided (WU-1247)
         ...(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()) }),
-        // WU-1368: Default assigned_to from git config user.email
         ...(assignedTo && { assigned_to: assignedTo }),
-        // WU-1998: Exposure field options - only include if provided
         ...(exposure && { exposure }),
         ...(userJourney && { user_journey: userJourney }),
         ...(uiPairingWus && { ui_pairing_wus: parseCommaSeparated(uiPairingWus) }),
-        // WU-2320: Spec references - only include if provided
         ...(specRefs && { spec_refs: parseCommaSeparated(specRefs) }),
     };
-    // WU-1539: Validate WU structure before writing (fail-fast, allows placeholders)
+}
+export function validateCreateSpec({ id, lane, title, priority, type, opts, }) {
+    const errors = [];
+    const effectiveType = type || DEFAULT_TYPE;
+    if (!opts.description) {
+        errors.push('--description is required');
+    }
+    if (!opts.acceptance || opts.acceptance.length === 0) {
+        errors.push('--acceptance is required (repeatable)');
+    }
+    if (!opts.exposure) {
+        errors.push('--exposure is required');
+    }
+    const hasTestPaths = opts.testPathsManual || opts.testPathsUnit || opts.testPathsE2e;
+    if (effectiveType !== 'documentation' && effectiveType !== 'process') {
+        if (!opts.codePaths) {
+            errors.push('--code-paths is required for non-documentation WUs');
+        }
+        if (!hasTestPaths) {
+            errors.push('At least one test path flag is required (--test-paths-manual, --test-paths-unit, or --test-paths-e2e)');
+        }
+    }
+    if (effectiveType === 'feature' && !opts.specRefs) {
+        errors.push('--spec-refs is required for type: feature WUs');
+    }
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+    const placeholderResult = validateNoPlaceholders({
+        description: opts.description,
+        acceptance: opts.acceptance,
+    });
+    if (!placeholderResult.valid) {
+        return {
+            valid: false,
+            errors: [buildPlaceholderErrorMessage('wu:create', placeholderResult)],
+        };
+    }
+    const today = todayISO();
+    const wuContent = buildWUContent({
+        id,
+        lane,
+        title,
+        priority,
+        type: effectiveType,
+        created: today,
+        opts,
+    });
+    const schemaResult = validateWU(wuContent);
+    if (!schemaResult.success) {
+        const schemaErrors = schemaResult.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+        return { valid: false, errors: schemaErrors };
+    }
+    const completeness = validateSpecCompleteness(wuContent, id);
+    if (!completeness.valid) {
+        return { valid: false, errors: completeness.errors };
+    }
+    return { valid: true, errors: [] };
+}
+/**
+ * Create WU YAML file in micro-worktree
+ *
+ * @param {string} worktreePath - Path to micro-worktree
+ * @param {string} id - WU ID
+ * @param {string} lane - WU lane
+ * @param {string} title - WU title
+ * @param {string} priority - WU priority
+ * @param {string} type - WU type
+ * @param {Object} opts - Additional options
+ * @returns {string} Relative path to created YAML file
+ */
+function createWUYamlInWorktree(worktreePath, id, lane, title, priority, type, opts = {}) {
+    const wuRelativePath = WU_PATHS.WU(id);
+    const wuAbsolutePath = join(worktreePath, wuRelativePath);
+    const wuDir = join(worktreePath, WU_PATHS.WU_DIR());
+    mkdirSync(wuDir, { recursive: true });
+    // WU-1428: Use todayISO() for consistent YYYY-MM-DD format (library-first)
+    const today = todayISO();
+    const wuContent = buildWUContent({
+        id,
+        lane,
+        title,
+        priority,
+        type,
+        created: today,
+        opts,
+    });
+    // WU-1539: Validate WU structure before writing (fail-fast, no placeholders)
     // WU-1750: Zod transforms normalize embedded newlines in arrays and strings
-    const validationResult = validateReadyWU(wuContent);
+    const validationResult = validateWU(wuContent);
     if (!validationResult.success) {
         const errors = validationResult.error.issues
             .map((issue) => `  • ${issue.path.join('.')}: ${issue.message}`)
@@ -270,6 +317,14 @@ function createWUYamlInWorktree(worktreePath, id, lane, title, priority, type, o
         die(`${LOG_PREFIX} ❌ WU YAML validation failed:\n\n${errors}\n\n` +
             `Fix the issues above and retry.`);
     }
+    const completenessResult = validateSpecCompleteness(wuContent, id);
+    if (!completenessResult.valid) {
+        const errorList = completenessResult.errors
+            .map((error) => `  • ${error}`)
+            .join(STRING_LITERALS.NEWLINE);
+        die(`${LOG_PREFIX} ❌ WU SPEC INCOMPLETE:\n\n${errorList}\n\n` +
+            `Provide the missing fields and retry.`);
+    }
     // WU-2253: Validate acceptance/code_paths consistency and invariants compliance
     // This blocks WU creation if acceptance references paths not in code_paths
     // or if code_paths conflicts with tools/invariants.yml
@@ -429,76 +484,95 @@ async function main() {
     if (!assignedTo) {
         console.warn(`${LOG_PREFIX} ⚠️  No assigned_to set - WU will need manual assignment`);
     }
-    // WU-1364: Validate spec completeness when --validate is set
-    if (args.validate) {
-        const validationErrors = [];
-        if (!args.description) {
-            validationErrors.push('--description is required when --validate is set');
-        }
-        // acceptance is an array from repeatable flag (empty array if not provided)
-        if (!args.acceptance || args.acceptance.length === 0) {
-            validationErrors.push('--acceptance is required when --validate is set (use multiple times)');
-        }
-        const hasTestPaths = args.testPathsManual || args.testPathsUnit || args.testPathsE2e;
-        if (!hasTestPaths) {
-            validationErrors.push('--validate requires at least one test path flag (--test-paths-manual, --test-paths-unit, or --test-paths-e2e)');
-        }
-        // WU-2320: spec_refs required for feature WUs (type defaults to feature)
-        const effectiveType = args.type || DEFAULT_TYPE;
-        if (effectiveType === 'feature' && !args.specRefs) {
-            validationErrors.push('--spec-refs is required for type: feature WUs (link to plan file in docs/04-operations/plans/)');
-        }
-        if (validationErrors.length > 0) {
-            const errorList = validationErrors.map((e) => `  • ${e}`).join(STRING_LITERALS.NEWLINE);
-            die(`Spec validation failed:\n\n${errorList}\n\nTo create without validation, omit the --validate flag.`);
-        }
-        console.log(`${LOG_PREFIX} ✅ Spec validation passed`);
+    const createSpecValidation = validateCreateSpec({
+        id: args.id,
+        lane: args.lane,
+        title: args.title,
+        priority: args.priority || DEFAULT_PRIORITY,
+        type: args.type || DEFAULT_TYPE,
+        opts: {
+            description: args.description,
+            acceptance: args.acceptance,
+            codePaths: args.codePaths,
+            testPathsManual: args.testPathsManual,
+            testPathsUnit: args.testPathsUnit,
+            testPathsE2e: args.testPathsE2e,
+            exposure: args.exposure,
+            userJourney: args.userJourney,
+            uiPairingWus: args.uiPairingWus,
+            specRefs: args.specRefs,
+            initiative: args.initiative,
+            phase: args.phase,
+            blockedBy: args.blockedBy,
+            blocks: args.blocks,
+            labels: args.labels,
+            assignedTo,
+        },
+    });
+    if (!createSpecValidation.valid) {
+        const errorList = createSpecValidation.errors
+            .map((error) => `  • ${error}`)
+            .join(STRING_LITERALS.NEWLINE);
+        die(`${LOG_PREFIX} ❌ Spec validation failed:\n\n${errorList}`);
     }
+    console.log(`${LOG_PREFIX} ✅ Spec validation passed`);
     // Transaction: micro-worktree isolation (WU-1439)
     try {
         const priority = args.priority || DEFAULT_PRIORITY;
         const type = args.type || DEFAULT_TYPE;
-        await withMicroWorktree({
-            operation: OPERATION_NAME,
-            id: args.id,
-            logPrefix: LOG_PREFIX,
-            execute: async ({ worktreePath }) => {
-                // Create WU YAML in micro-worktree
-                const wuPath = createWUYamlInWorktree(worktreePath, args.id, args.lane, args.title, priority, type, {
-                    // Initiative system fields (WU-1247)
-                    initiative: args.initiative,
-                    phase: args.phase,
-                    blockedBy: args.blockedBy,
-                    blocks: args.blocks,
-                    labels: args.labels,
-                    // WU-1368: Assigned to
-                    assignedTo,
-                    // WU-1364: Full spec inline options
-                    description: args.description,
-                    acceptance: args.acceptance,
-                    codePaths: args.codePaths,
-                    testPathsManual: args.testPathsManual,
-                    testPathsUnit: args.testPathsUnit,
-                    testPathsE2e: args.testPathsE2e,
-                    // WU-1998: Exposure field options
-                    exposure: args.exposure,
-                    userJourney: args.userJourney,
-                    uiPairingWus: args.uiPairingWus,
-                    // WU-2320: Spec references
-                    specRefs: args.specRefs,
-                });
-                // Update backlog.md in micro-worktree
-                const backlogPath = updateBacklogInWorktree(worktreePath, args.id, args.lane, args.title);
-                // Build commit message
-                const shortTitle = truncateTitle(args.title);
-                const commitMessage = COMMIT_FORMATS.CREATE(args.id, shortTitle);
-                // Return commit message and files to commit
-                return {
-                    commitMessage,
-                    files: [wuPath, backlogPath],
-                };
-            },
-        });
+        const previousWuTool = process.env.LUMENFLOW_WU_TOOL;
+        process.env.LUMENFLOW_WU_TOOL = OPERATION_NAME;
+        try {
+            await withMicroWorktree({
+                operation: OPERATION_NAME,
+                id: args.id,
+                logPrefix: LOG_PREFIX,
+                execute: async ({ worktreePath }) => {
+                    // Create WU YAML in micro-worktree
+                    const wuPath = createWUYamlInWorktree(worktreePath, args.id, args.lane, args.title, priority, type, {
+                        // Initiative system fields (WU-1247)
+                        initiative: args.initiative,
+                        phase: args.phase,
+                        blockedBy: args.blockedBy,
+                        blocks: args.blocks,
+                        labels: args.labels,
+                        // WU-1368: Assigned to
+                        assignedTo,
+                        // WU-1364: Full spec inline options
+                        description: args.description,
+                        acceptance: args.acceptance,
+                        codePaths: args.codePaths,
+                        testPathsManual: args.testPathsManual,
+                        testPathsUnit: args.testPathsUnit,
+                        testPathsE2e: args.testPathsE2e,
+                        // WU-1998: Exposure field options
+                        exposure: args.exposure,
+                        userJourney: args.userJourney,
+                        uiPairingWus: args.uiPairingWus,
+                        // WU-2320: Spec references
+                        specRefs: args.specRefs,
+                    });
+                    // Update backlog.md in micro-worktree
+                    const backlogPath = updateBacklogInWorktree(worktreePath, args.id, args.lane, args.title);
+                    // Build commit message
+                    const shortTitle = truncateTitle(args.title);
+                    const commitMessage = COMMIT_FORMATS.CREATE(args.id, shortTitle);
+                    // Return commit message and files to commit
+                    return {
+                        commitMessage,
+                        files: [wuPath, backlogPath],
+                    };
+                },
+            });
+        }
+        finally {
+            if (previousWuTool === undefined) {
+                delete process.env.LUMENFLOW_WU_TOOL;
+            }
+            else {
+                process.env.LUMENFLOW_WU_TOOL = previousWuTool;
+            }
+        }
         console.log(`\n${LOG_PREFIX} ✅ Transaction complete!`);
         console.log(`\nWU ${args.id} created successfully:`);
         console.log(`  File: ${WU_PATHS.WU(args.id)}`);
@@ -515,6 +589,7 @@ async function main() {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }