@lumenflow/cli 2.2.1 → 2.3.1

package/dist/initiative-add-wu.js

@@ -227,9 +227,10 @@ async function main() {
             `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
     }
 }
-// Guard main() for testability
-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/initiative-bulk-assign-wus.js

@@ -21,14 +21,16 @@ import { parse as parseYaml } from 'yaml';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { createWuPaths } from '@lumenflow/core/dist/wu-paths.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[initiative:bulk-assign]';
 /** Default lane bucket configuration path */
 const DEFAULT_CONFIG_PATH = 'tools/config/initiative-lane-buckets.yaml';
+const wuPaths = createWuPaths();
 /** WU directory relative to repo root */
-const WU_DIR = 'docs/04-operations/tasks/wu';
+const WU_DIR = wuPaths.WU_DIR();
 /** Initiative directory relative to repo root */
-const INIT_DIR = 'docs/04-operations/tasks/initiatives';
+const INIT_DIR = wuPaths.INITIATIVES_DIR();
 /** Environment variable required for apply mode */
 const ADMIN_ENV_VAR = 'LUMENFLOW_ADMIN';
 /** Micro-worktree operation name */
@@ -306,9 +308,10 @@ async function main() {
     });
     console.log(`${LOG_PREFIX} ✅ Successfully applied ${changes.length} changes`);
 }
-// Guard main() for testability (WU-1366)
-import { fileURLToPath } from 'node:url';
-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) => {
         die(`Bulk assign failed: ${err.message}`);
     });

package/dist/initiative-create.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 /* eslint-disable security/detect-non-literal-fs-filename */
+/* eslint-disable no-console -- CLI tool requires console output */
+/* eslint-disable @typescript-eslint/explicit-function-return-type -- CLI tool uses dynamic YAML types */
 /**
  * Initiative Create Helper (WU-1247, WU-1439)
  *
@@ -34,6 +36,8 @@ import { stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { INIT_PATHS } from '@lumenflow/initiatives/dist/initiative-paths.js';
 import { INIT_PATTERNS, INIT_COMMIT_FORMATS, INIT_DEFAULTS, } from '@lumenflow/initiatives/dist/initiative-constants.js';
+// WU-1211: Import initiative validation for completeness warnings
+import { validateInitiativeCompleteness } from '@lumenflow/initiatives/dist/initiative-validation.js';
 import { FILE_SYSTEM } from '@lumenflow/core/dist/wu-constants.js';
 import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
 import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
@@ -124,46 +128,78 @@ async function main() {
     checkInitiativeExists(args.id);
     await ensureOnMain(getGitForCwd());
     // Transaction: micro-worktree isolation (WU-1439)
+    // WU-1255: Set LUMENFLOW_WU_TOOL to allow pre-push hook bypass for micro-worktree pushes
+    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 Initiative YAML in micro-worktree
-                const initPath = createInitiativeYamlInWorktree(worktreePath, args.id, args.slug, args.title, {
-                    priority: args.priority,
-                    owner: args.owner,
-                    targetDate: args.targetDate,
-                });
-                // Return commit message and files to commit
-                return {
-                    commitMessage: INIT_COMMIT_FORMATS.CREATE(args.id, args.title),
-                    files: [initPath],
-                };
-            },
-        });
-        console.log(`\n${LOG_PREFIX} ✅ Transaction complete!`);
-        console.log(`\nInitiative Created:`);
-        console.log(`  ID:     ${args.id}`);
-        console.log(`  Slug:   ${args.slug}`);
-        console.log(`  Title:  ${args.title}`);
-        console.log(`  Status: ${INIT_DEFAULTS.STATUS}`);
-        console.log(`  File:   ${INIT_PATHS.INITIATIVE(args.id)}`);
-        console.log(`\nNext steps:`);
-        console.log(`  1. Edit ${args.id}.yaml to add description, phases, and success_metrics`);
-        console.log(`  2. Link WUs to this initiative: pnpm wu:create --initiative ${args.id} ...`);
-        console.log(`  3. View status: pnpm initiative:status ${args.id}`);
+        try {
+            await withMicroWorktree({
+                operation: OPERATION_NAME,
+                id: args.id,
+                logPrefix: LOG_PREFIX,
+                execute: async ({ worktreePath }) => {
+                    // Create Initiative YAML in micro-worktree
+                    const initPath = createInitiativeYamlInWorktree(worktreePath, args.id, args.slug, args.title, {
+                        priority: args.priority,
+                        owner: args.owner,
+                        targetDate: args.targetDate,
+                    });
+                    // Return commit message and files to commit
+                    return {
+                        commitMessage: INIT_COMMIT_FORMATS.CREATE(args.id, args.title),
+                        files: [initPath],
+                    };
+                },
+            });
+            console.log(`\n${LOG_PREFIX} ✅ Transaction complete!`);
+            console.log(`\nInitiative Created:`);
+            console.log(`  ID:     ${args.id}`);
+            console.log(`  Slug:   ${args.slug}`);
+            console.log(`  Title:  ${args.title}`);
+            console.log(`  Status: ${INIT_DEFAULTS.STATUS}`);
+            console.log(`  File:   ${INIT_PATHS.INITIATIVE(args.id)}`);
+            // WU-1211: Check completeness and emit warnings
+            const initContent = {
+                id: args.id,
+                slug: args.slug,
+                title: args.title,
+                description: '',
+                status: INIT_DEFAULTS.STATUS,
+                phases: [],
+                success_metrics: [],
+            };
+            const completenessResult = validateInitiativeCompleteness(initContent);
+            if (completenessResult.warnings.length > 0) {
+                console.log(`\n${LOG_PREFIX} ⚠️  Incomplete initiative - missing recommended fields:`);
+                for (const warning of completenessResult.warnings) {
+                    console.log(`  - ${warning}`);
+                }
+            }
+            console.log(`\nNext steps:`);
+            console.log(`  1. Edit ${args.id}.yaml to add description, phases, and success_metrics`);
+            console.log(`  2. Link WUs to this initiative: pnpm wu:create --initiative ${args.id} ...`);
+            console.log(`  3. View status: pnpm initiative:status ${args.id}`);
+        }
+        catch (error) {
+            die(`Transaction failed: ${error.message}\n\n` +
+                `Micro-worktree cleanup was attempted automatically.\n` +
+                `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
+        }
     }
-    catch (error) {
-        die(`Transaction failed: ${error.message}\n\n` +
-            `Micro-worktree cleanup was attempted automatically.\n` +
-            `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
+    finally {
+        // WU-1255: Restore LUMENFLOW_WU_TOOL to previous value
+        if (previousWuTool === undefined) {
+            delete process.env.LUMENFLOW_WU_TOOL;
+        }
+        else {
+            process.env.LUMENFLOW_WU_TOOL = previousWuTool;
+        }
     }
 }
-// Guard main() for testability
-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)) {
-    runCLI(main);
+if (import.meta.main) {
+    void runCLI(main);
 }

package/dist/initiative-edit.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/* eslint-disable @typescript-eslint/explicit-function-return-type -- CLI tool uses dynamic YAML types */
 /**
  * Initiative Edit Helper
  *
@@ -29,7 +31,7 @@
  *   pnpm initiative:edit --id INIT-001 --notes "Phase 2 started"
  *
  * Part of WU-1451: Add initiative:edit command for updating initiative status and blockers
- * @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 { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
@@ -413,26 +415,40 @@ async function main() {
     await ensureCleanWorkingTree();
     await ensureMainUpToDate(getGitForCwd(), 'initiative:edit');
     console.log(`${PREFIX} Applying edits via micro-worktree...`);
-    await withMicroWorktree({
-        operation: MICRO_WORKTREE_OPERATIONS.INITIATIVE_EDIT,
-        id: id,
-        logPrefix: PREFIX,
-        pushOnly: true, // WU-1435: Push directly to origin/main without touching local main
-        execute: async ({ worktreePath }) => {
-            // Write updated Initiative to micro-worktree
-            const initPath = join(worktreePath, INIT_PATHS.INITIATIVE(id));
-            const yamlContent = stringifyYAML(updatedInit);
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes init files
-            writeFileSync(initPath, yamlContent, { encoding: FILE_SYSTEM.ENCODING });
-            console.log(`${PREFIX} Updated ${id}.yaml in micro-worktree`);
-            return {
-                commitMessage: INIT_COMMIT_FORMATS.EDIT(id),
-                files: [INIT_PATHS.INITIATIVE(id)],
-            };
-        },
-    });
-    console.log(`${PREFIX} Successfully edited ${id}`);
-    console.log(`${PREFIX} Changes pushed to origin/main`);
+    // WU-1255: Set LUMENFLOW_WU_TOOL to allow pre-push hook bypass for micro-worktree pushes
+    const previousWuTool = process.env.LUMENFLOW_WU_TOOL;
+    process.env.LUMENFLOW_WU_TOOL = MICRO_WORKTREE_OPERATIONS.INITIATIVE_EDIT;
+    try {
+        await withMicroWorktree({
+            operation: MICRO_WORKTREE_OPERATIONS.INITIATIVE_EDIT,
+            id: id,
+            logPrefix: PREFIX,
+            pushOnly: true, // WU-1435: Push directly to origin/main without touching local main
+            execute: async ({ worktreePath }) => {
+                // Write updated Initiative to micro-worktree
+                const initPath = join(worktreePath, INIT_PATHS.INITIATIVE(id));
+                const yamlContent = stringifyYAML(updatedInit);
+                // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes init files
+                writeFileSync(initPath, yamlContent, { encoding: FILE_SYSTEM.ENCODING });
+                console.log(`${PREFIX} Updated ${id}.yaml in micro-worktree`);
+                return {
+                    commitMessage: INIT_COMMIT_FORMATS.EDIT(id),
+                    files: [INIT_PATHS.INITIATIVE(id)],
+                };
+            },
+        });
+        console.log(`${PREFIX} Successfully edited ${id}`);
+        console.log(`${PREFIX} Changes pushed to origin/main`);
+    }
+    finally {
+        // WU-1255: Restore LUMENFLOW_WU_TOOL to previous value
+        if (previousWuTool === undefined) {
+            delete process.env.LUMENFLOW_WU_TOOL;
+        }
+        else {
+            process.env.LUMENFLOW_WU_TOOL = previousWuTool;
+        }
+    }
 }
 main().catch((err) => {
     console.error(`${PREFIX} ${err.message}`);

package/dist/initiative-list.js

@@ -94,9 +94,10 @@ async function main() {
             break;
     }
 }
-// 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/initiative-plan.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/* eslint-disable security/detect-non-literal-fs-filename */
+/**
+ * Initiative Plan Command (WU-1105, renamed in WU-1193)
+ *
+ * Links plan files to initiatives by setting the `related_plan` field
+ * in the initiative YAML.
+ *
+ * Usage:
+ *   pnpm initiative:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md
+ *   pnpm initiative:plan --initiative INIT-001 --create  # Create new plan template
+ *
+ * Features:
+ * - Validates initiative exists before modifying
+ * - Formats plan path as lumenflow:// URI
+ * - Idempotent: no error if same plan already linked
+ * - Warns if replacing existing plan link
+ * - Can create plan templates with --create
+ *
+ * Context: WU-1105 (INIT-003 Phase 3a), renamed from init:plan in WU-1193
+ */
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { existsSync, writeFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { INIT_PATHS } from '@lumenflow/initiatives/dist/initiative-paths.js';
+import { INIT_PATTERNS } from '@lumenflow/initiatives/dist/initiative-constants.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { readInitiative } from '@lumenflow/initiatives/dist/initiative-yaml.js';
+import { parseYAML, stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { LOG_PREFIX as CORE_LOG_PREFIX } from '@lumenflow/core/dist/wu-constants.js';
+/** Log prefix for console output */
+export const LOG_PREFIX = CORE_LOG_PREFIX.INITIATIVE_PLAN;
+/** Micro-worktree operation name */
+const OPERATION_NAME = 'initiative-plan';
+/** Standard plans directory relative to repo root */
+const PLANS_DIR = 'docs/04-operations/plans';
+/** LumenFlow URI scheme for plan references */
+const PLAN_URI_SCHEME = 'lumenflow://plans/';
+/**
+ * Custom option for plan file path
+ */
+const PLAN_OPTION = {
+    name: 'plan',
+    flags: '--plan <path>',
+    description: 'Path to plan file (markdown)',
+};
+/**
+ * Custom option for creating new plan template
+ */
+const CREATE_OPTION = {
+    name: 'create',
+    flags: '--create',
+    description: 'Create a new plan template instead of linking existing file',
+};
+/**
+ * Validate Initiative ID format
+ * @param id - Initiative ID to validate
+ * @throws Error if format is invalid
+ */
+export function validateInitIdFormat(id) {
+    if (!INIT_PATTERNS.INIT_ID.test(id)) {
+        die(`Invalid Initiative ID format: "${id}"\n\n` +
+            `Expected format: INIT-<number> or INIT-NAME (e.g., INIT-001, INIT-TOOLING)`);
+    }
+}
+/**
+ * Validate plan file path
+ * @param planPath - Path to plan file
+ * @throws Error if path is invalid or file doesn't exist
+ */
+export function validatePlanPath(planPath) {
+    if (!planPath.endsWith('.md')) {
+        die(`Invalid plan file format: "${planPath}"\n\nPlan files must be markdown (.md)`);
+    }
+    if (!existsSync(planPath)) {
+        die(`Plan file not found: "${planPath}"\n\nUse --create to create a new plan template`);
+    }
+}
+/**
+ * Format plan path as lumenflow:// URI
+ *
+ * Extracts the filename (and any subdirectory within plans/) and creates
+ * a standardized URI for the plan reference.
+ *
+ * @param planPath - Path to plan file (can be relative or absolute)
+ * @returns lumenflow://plans/<filename> URI
+ */
+export function formatPlanUri(planPath) {
+    // Try to extract path relative to plans directory
+    const plansMarker = '/plans/';
+    const plansIndex = planPath.indexOf(plansMarker);
+    if (plansIndex !== -1) {
+        // Extract everything after /plans/
+        const relativePath = planPath.substring(plansIndex + plansMarker.length);
+        return `${PLAN_URI_SCHEME}${relativePath}`;
+    }
+    // Fallback: just use the filename
+    const filename = basename(planPath);
+    return `${PLAN_URI_SCHEME}${filename}`;
+}
+/**
+ * Check if initiative exists and return the document
+ * @param initId - Initiative ID to check
+ * @returns Initiative document
+ * @throws Error if initiative not found
+ */
+export function checkInitiativeExists(initId) {
+    const initPath = INIT_PATHS.INITIATIVE(initId);
+    if (!existsSync(initPath)) {
+        die(`Initiative not found: ${initId}\n\nFile does not exist: ${initPath}`);
+    }
+    return readInitiative(initPath, initId);
+}
+/**
+ * Update initiative with plan reference in micro-worktree
+ *
+ * Uses raw YAML parsing to preserve unknown fields like related_plan
+ * that are not in the strict initiative schema.
+ *
+ * @param worktreePath - Path to micro-worktree
+ * @param initId - Initiative ID
+ * @param planUri - Plan URI to set
+ * @returns True if changes were made, false if already linked
+ */
+export function updateInitiativeWithPlan(worktreePath, initId, planUri) {
+    const initRelPath = INIT_PATHS.INITIATIVE(initId);
+    const initAbsPath = join(worktreePath, initRelPath);
+    // Read raw YAML to preserve unknown fields like related_plan
+    // (readInitiative strips them via zod schema validation)
+    const rawText = readFileSync(initAbsPath, { encoding: 'utf-8' });
+    const doc = parseYAML(rawText);
+    // Validate ID matches
+    if (doc.id !== initId) {
+        die(`Initiative YAML id mismatch. Expected ${initId}, found ${doc.id}`);
+    }
+    // Check for existing plan link
+    const existingPlan = doc.related_plan;
+    if (existingPlan === planUri) {
+        // Already linked to same plan - idempotent
+        return false;
+    }
+    if (existingPlan && existingPlan !== planUri) {
+        // Different plan already linked - warn but proceed
+        console.warn(`${LOG_PREFIX} Replacing existing related_plan: ${existingPlan} -> ${planUri}`);
+    }
+    // Update related_plan field
+    doc.related_plan = planUri;
+    const out = stringifyYAML(doc);
+    writeFileSync(initAbsPath, out, { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Updated ${initId} with related_plan: ${planUri}`);
+    return true;
+}
+/**
+ * Create a plan template file
+ *
+ * @param worktreePath - Path to repo root or worktree
+ * @param initId - Initiative ID
+ * @param title - Initiative title
+ * @returns Path to created file
+ * @throws Error if file already exists
+ */
+export function createPlanTemplate(worktreePath, initId, title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .substring(0, 30);
+    const filename = `${initId}-${slug}.md`;
+    const plansDir = join(worktreePath, PLANS_DIR);
+    const planPath = join(plansDir, filename);
+    if (existsSync(planPath)) {
+        die(`Plan file already exists: ${planPath}\n\nUse --plan to link an existing file`);
+    }
+    // Ensure plans directory exists
+    if (!existsSync(plansDir)) {
+        mkdirSync(plansDir, { recursive: true });
+    }
+    const template = `# ${initId} Plan - ${title}
+
+## Goal
+
+<!-- What is the primary objective of this initiative? -->
+
+## Scope
+
+<!-- What is in scope and out of scope? -->
+
+## Approach
+
+<!-- How will you achieve the goal? Key phases or milestones? -->
+
+## Success Criteria
+
+<!-- How will you know when this is complete? Measurable outcomes? -->
+
+## Risks
+
+<!-- What could go wrong? How will you mitigate? -->
+
+## References
+
+- Initiative: ${initId}
+- Created: ${new Date().toISOString().split('T')[0]}
+`;
+    writeFileSync(planPath, template, { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Created plan template: ${planPath}`);
+    return planPath;
+}
+/**
+ * Generate commit message for plan link operation
+ */
+export function getCommitMessage(initId, planUri) {
+    const filename = planUri.replace(PLAN_URI_SCHEME, '');
+    return `docs: link plan ${filename} to ${initId.toLowerCase()}`;
+}
+async function main() {
+    const args = createWUParser({
+        name: 'init-plan',
+        description: 'Link a plan file to an initiative',
+        options: [WU_OPTIONS.initiative, PLAN_OPTION, CREATE_OPTION],
+        required: ['initiative'],
+        allowPositionalId: false,
+    });
+    const initId = args.initiative;
+    const planPath = args.plan;
+    const shouldCreate = args.create;
+    // Validate inputs
+    validateInitIdFormat(initId);
+    // Check initiative exists first (before any mutations)
+    const initDoc = checkInitiativeExists(initId);
+    const initTitle = initDoc.title;
+    // Determine plan path and URI
+    let targetPlanPath;
+    let planUri;
+    if (shouldCreate) {
+        // Create mode - will create template and link it
+        console.log(`${LOG_PREFIX} Creating plan template for ${initId}...`);
+        // Ensure on main for micro-worktree operations
+        await ensureOnMain(getGitForCwd());
+        try {
+            await withMicroWorktree({
+                operation: OPERATION_NAME,
+                id: initId,
+                logPrefix: LOG_PREFIX,
+                pushOnly: true,
+                execute: async ({ worktreePath }) => {
+                    // Create plan template
+                    targetPlanPath = createPlanTemplate(worktreePath, initId, initTitle);
+                    planUri = formatPlanUri(targetPlanPath);
+                    // Update initiative with plan link
+                    updateInitiativeWithPlan(worktreePath, initId, planUri);
+                    // Return files to commit
+                    const planRelPath = targetPlanPath.replace(worktreePath + '/', '');
+                    return {
+                        commitMessage: getCommitMessage(initId, planUri),
+                        files: [planRelPath, INIT_PATHS.INITIATIVE(initId)],
+                    };
+                },
+            });
+            console.log(`\n${LOG_PREFIX} Transaction complete!`);
+            console.log(`\nPlan Linked:`);
+            console.log(`  Initiative: ${initId}`);
+            console.log(`  Plan URI:   ${planUri}`);
+            console.log(`  File:       ${targetPlanPath}`);
+            console.log(`\nNext steps:`);
+            console.log(`  1. Edit the plan file with your goals and approach`);
+            console.log(`  2. View initiative: pnpm initiative:status ${initId}`);
+        }
+        catch (error) {
+            die(`Transaction failed: ${error.message}\n\n` +
+                `Micro-worktree cleanup was attempted automatically.\n` +
+                `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
+        }
+    }
+    else if (planPath) {
+        // Link existing file mode
+        validatePlanPath(planPath);
+        planUri = formatPlanUri(planPath);
+        console.log(`${LOG_PREFIX} Linking plan to ${initId}...`);
+        // Check for idempotent case before micro-worktree
+        const existingPlan = initDoc.related_plan;
+        if (existingPlan === planUri) {
+            console.log(`${LOG_PREFIX} Plan already linked (idempotent - no changes needed)`);
+            console.log(`\n${LOG_PREFIX} ${initId} already has related_plan: ${planUri}`);
+            return;
+        }
+        // Ensure on main for micro-worktree operations
+        await ensureOnMain(getGitForCwd());
+        try {
+            await withMicroWorktree({
+                operation: OPERATION_NAME,
+                id: initId,
+                logPrefix: LOG_PREFIX,
+                pushOnly: true,
+                execute: async ({ worktreePath }) => {
+                    // Update initiative with plan link
+                    const changed = updateInitiativeWithPlan(worktreePath, initId, planUri);
+                    if (!changed) {
+                        console.log(`${LOG_PREFIX} No changes detected (concurrent link operation)`);
+                    }
+                    return {
+                        commitMessage: getCommitMessage(initId, planUri),
+                        files: [INIT_PATHS.INITIATIVE(initId)],
+                    };
+                },
+            });
+            console.log(`\n${LOG_PREFIX} Transaction complete!`);
+            console.log(`\nPlan Linked:`);
+            console.log(`  Initiative: ${initId}`);
+            console.log(`  Plan URI:   ${planUri}`);
+            console.log(`  File:       ${planPath}`);
+            console.log(`\nNext steps:`);
+            console.log(`  - View initiative: pnpm initiative:status ${initId}`);
+        }
+        catch (error) {
+            die(`Transaction failed: ${error.message}\n\n` +
+                `Micro-worktree cleanup was attempted automatically.\n` +
+                `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
+        }
+    }
+    else {
+        die('Either --plan or --create is required\n\n' +
+            'Usage:\n' +
+            '  pnpm init:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md\n' +
+            '  pnpm init:plan --initiative INIT-001 --create');
+    }
+}
+// Guard main() for testability - use import.meta.main (WU-1071)
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
+}
+// Export for testing
+export { main };

package/dist/initiative-status.js

@@ -214,9 +214,10 @@ async function main() {
             break;
     }
 }
-// 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);
 }