@lumenflow/cli 2.4.0 → 2.5.1

package/dist/plan-create.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/* eslint-disable security/detect-non-literal-fs-filename */
+/**
+ * Plan Create Command (WU-1313)
+ *
+ * Creates plan files in the repo-native plansDir (not LUMENFLOW_HOME).
+ * Plans can be linked to WUs (via spec_refs) or initiatives (via related_plan).
+ *
+ * Usage:
+ *   pnpm plan:create --id WU-1313 --title "Feature plan"
+ *   pnpm plan:create --id INIT-001 --title "Initiative plan"
+ *
+ * Features:
+ * - Creates plan in repo directories.plansDir
+ * - Supports both WU-XXX and INIT-XXX IDs
+ * - Uses micro-worktree isolation for atomic commits
+ * - Idempotent: fails if plan already exists (no overwrite)
+ *
+ * Context: WU-1313 (INIT-013 Plan Tooling)
+ */
+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';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { todayISO } from '@lumenflow/core/dist/date-utils.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.PLAN_CREATE ?? '[plan:create]';
+/** Micro-worktree operation name */
+const OPERATION_NAME = 'plan-create';
+/** LumenFlow URI scheme for plan references */
+const PLAN_URI_SCHEME = 'lumenflow://plans/';
+/** WU ID pattern */
+const WU_ID_PATTERN = /^WU-\d+$/;
+/** Initiative ID pattern */
+const INIT_ID_PATTERN = /^INIT-[A-Z0-9]+$/i;
+/**
+ * Validate that the ID is a valid WU or Initiative ID
+ *
+ * @param id - ID to validate (WU-XXX or INIT-XXX)
+ * @throws Error if ID format is invalid
+ */
+export function validatePlanId(id) {
+    if (!id) {
+        die(`ID is required\n\nExpected format: WU-XXX or INIT-XXX`);
+    }
+    const isWU = WU_ID_PATTERN.test(id);
+    const isInit = INIT_ID_PATTERN.test(id);
+    if (!isWU && !isInit) {
+        die(`Invalid ID format: "${id}"\n\n` +
+            `Expected format:\n` +
+            `  - WU ID: WU-<number> (e.g., WU-1313)\n` +
+            `  - Initiative ID: INIT-<alphanumeric> (e.g., INIT-001, INIT-TOOLING)`);
+    }
+}
+/**
+ * Get the lumenflow:// URI for a plan
+ *
+ * @param id - WU or Initiative ID
+ * @returns lumenflow://plans/{id}-plan.md URI
+ */
+export function getPlanUri(id) {
+    return `${PLAN_URI_SCHEME}${id}-plan.md`;
+}
+/**
+ * Create a plan file in the repo plansDir
+ *
+ * @param worktreePath - Path to repo root or worktree
+ * @param id - WU or Initiative ID
+ * @param title - Plan title
+ * @returns Path to created file
+ * @throws Error if file already exists
+ */
+export function createPlan(worktreePath, id, title) {
+    const plansDir = join(worktreePath, WU_PATHS.PLANS_DIR());
+    const planPath = join(plansDir, `${id}-plan.md`);
+    if (existsSync(planPath)) {
+        die(`Plan file already exists: ${planPath}\n\n` +
+            `Options:\n` +
+            `  1. Edit the existing plan: pnpm plan:edit --id ${id}\n` +
+            `  2. Delete and recreate (not recommended)\n` +
+            `  3. Use plan:link to link existing plan to a WU/initiative`);
+    }
+    // Ensure plans directory exists
+    if (!existsSync(plansDir)) {
+        mkdirSync(plansDir, { recursive: true });
+    }
+    const today = todayISO();
+    const template = `# ${id} Plan - ${title}
+
+Created: ${today}
+
+## Goal
+
+<!-- What is the primary objective? -->
+
+## 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? -->
+
+## Open Questions
+
+<!-- Unresolved questions or decisions needed -->
+
+## References
+
+- ID: ${id}
+- Created: ${today}
+`;
+    writeFileSync(planPath, template, { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Created plan: ${planPath}`);
+    return planPath;
+}
+/**
+ * Generate commit message for plan creation
+ *
+ * @param id - WU or Initiative ID
+ * @param title - Plan title
+ * @returns Commit message
+ */
+export function getCommitMessage(id, title) {
+    const idLower = id.toLowerCase();
+    return `docs: create plan for ${idLower} - ${title}`;
+}
+async function main() {
+    const args = createWUParser({
+        name: 'plan-create',
+        description: 'Create a new plan file in repo plansDir',
+        options: [WU_OPTIONS.id, WU_OPTIONS.title],
+        required: ['id', 'title'],
+        allowPositionalId: true,
+    });
+    const id = args.id;
+    const title = args.title;
+    // Validate inputs
+    validatePlanId(id);
+    console.log(`${LOG_PREFIX} Creating plan for ${id}...`);
+    // Ensure on main for micro-worktree operations
+    await ensureOnMain(getGitForCwd());
+    try {
+        let createdPlanPath = '';
+        await withMicroWorktree({
+            operation: OPERATION_NAME,
+            id,
+            logPrefix: LOG_PREFIX,
+            pushOnly: true,
+            execute: async ({ worktreePath }) => {
+                // Create plan file
+                createdPlanPath = createPlan(worktreePath, id, title);
+                // Get relative path for commit
+                const planRelPath = createdPlanPath.replace(worktreePath + '/', '');
+                return {
+                    commitMessage: getCommitMessage(id, title),
+                    files: [planRelPath],
+                };
+            },
+        });
+        const planUri = getPlanUri(id);
+        console.log(`\n${LOG_PREFIX} Plan created successfully!`);
+        console.log(`\nPlan Details:`);
+        console.log(`  ID:      ${id}`);
+        console.log(`  Title:   ${title}`);
+        console.log(`  URI:     ${planUri}`);
+        console.log(`  File:    ${createdPlanPath}`);
+        console.log(`\nNext steps:`);
+        console.log(`  1. Edit the plan file with your goals and approach`);
+        console.log(`  2. Link to WU/initiative: pnpm plan:link --id ${id} --plan ${planUri}`);
+        console.log(`  3. When ready, promote: pnpm plan:promote --id ${id}`);
+    }
+    catch (error) {
+        die(`Plan creation 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}`);
+    }
+}
+// Guard main() for testability
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    void runCLI(main);
+}
+// Export for testing
+export { main };

package/dist/plan-edit.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/* eslint-disable security/detect-non-literal-fs-filename */
+/**
+ * Plan Edit Command (WU-1313)
+ *
+ * Edits existing plan files in the repo-native plansDir.
+ * Supports updating or appending to specific sections.
+ *
+ * Usage:
+ *   pnpm plan:edit --id WU-1313 --section Goal --content "New goal content"
+ *   pnpm plan:edit --id WU-1313 --section Risks --append "- New risk"
+ *
+ * Features:
+ * - Updates specific sections by name
+ * - Supports append mode for list sections (Risks, etc.)
+ * - Uses micro-worktree isolation for atomic commits
+ * - Validates section exists before editing
+ *
+ * Context: WU-1313 (INIT-013 Plan Tooling)
+ */
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.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.PLAN_EDIT ?? '[plan:edit]';
+/** Micro-worktree operation name */
+const OPERATION_NAME = 'plan-edit';
+/** WU ID pattern */
+const WU_ID_PATTERN = /^WU-\d+$/;
+/** Initiative ID pattern */
+const INIT_ID_PATTERN = /^INIT-[A-Z0-9]+$/i;
+/**
+ * Get the path to a plan file from its ID
+ *
+ * @param id - WU or Initiative ID
+ * @returns Path to plan file
+ * @throws Error if plan not found
+ */
+export function getPlanPath(id) {
+    const plansDir = WU_PATHS.PLANS_DIR();
+    const planPath = join(plansDir, `${id}-plan.md`);
+    if (!existsSync(planPath)) {
+        die(`Plan not found for ${id}\n\n` +
+            `Expected path: ${planPath}\n\n` +
+            `Create it first with: pnpm plan:create --id ${id} --title "Title"`);
+    }
+    return planPath;
+}
+/**
+ * Update a section in a plan file
+ *
+ * Replaces all content between the section heading and the next heading.
+ *
+ * @param planPath - Path to plan file
+ * @param section - Section name (without ##)
+ * @param content - New content for the section
+ * @returns True if changes were made, false if section not found
+ */
+export function updatePlanSection(planPath, section, content) {
+    if (!existsSync(planPath)) {
+        die(`Plan file not found: ${planPath}`);
+    }
+    const text = readFileSync(planPath, { encoding: 'utf-8' });
+    const lines = text.split('\n');
+    // Find the section heading
+    const sectionHeading = `## ${section}`;
+    const headingIndex = lines.findIndex((line) => line.trim() === sectionHeading);
+    if (headingIndex === -1) {
+        console.log(`${LOG_PREFIX} Section "${section}" not found in plan`);
+        return false;
+    }
+    // Find the next heading (end of this section)
+    let nextHeadingIndex = lines.findIndex((line, i) => i > headingIndex && line.trim().startsWith('## '));
+    if (nextHeadingIndex === -1) {
+        nextHeadingIndex = lines.length;
+    }
+    // Replace the section content (keep the heading, replace content until next heading)
+    const beforeSection = lines.slice(0, headingIndex + 1);
+    const afterSection = lines.slice(nextHeadingIndex);
+    const newLines = [...beforeSection, '', content, '', ...afterSection];
+    writeFileSync(planPath, newLines.join('\n'), { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Updated "${section}" section in plan`);
+    return true;
+}
+/**
+ * Append content to a section in a plan file
+ *
+ * Adds content at the end of the section, before the next heading.
+ *
+ * @param planPath - Path to plan file
+ * @param section - Section name (without ##)
+ * @param content - Content to append
+ * @returns True if changes were made, false if section not found
+ */
+export function appendToSection(planPath, section, content) {
+    if (!existsSync(planPath)) {
+        die(`Plan file not found: ${planPath}`);
+    }
+    const text = readFileSync(planPath, { encoding: 'utf-8' });
+    const lines = text.split('\n');
+    // Find the section heading
+    const sectionHeading = `## ${section}`;
+    const headingIndex = lines.findIndex((line) => line.trim() === sectionHeading);
+    if (headingIndex === -1) {
+        console.log(`${LOG_PREFIX} Section "${section}" not found in plan`);
+        return false;
+    }
+    // Find the next heading (end of this section)
+    let nextHeadingIndex = lines.findIndex((line, i) => i > headingIndex && line.trim().startsWith('## '));
+    if (nextHeadingIndex === -1) {
+        nextHeadingIndex = lines.length;
+    }
+    // Find the last non-empty line before the next heading
+    let insertIndex = nextHeadingIndex;
+    for (let i = nextHeadingIndex - 1; i > headingIndex; i--) {
+        if (lines[i].trim() !== '') {
+            insertIndex = i + 1;
+            break;
+        }
+    }
+    // Insert the new content
+    lines.splice(insertIndex, 0, content);
+    writeFileSync(planPath, lines.join('\n'), { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Appended to "${section}" section in plan`);
+    return true;
+}
+/**
+ * Generate commit message for plan edit operation
+ *
+ * @param id - WU or Initiative ID
+ * @param section - Section that was edited
+ * @returns Commit message
+ */
+export function getCommitMessage(id, section) {
+    const idLower = id.toLowerCase();
+    return `docs: update ${section} section in ${idLower} plan`;
+}
+async function main() {
+    const SECTION_OPTION = {
+        name: 'section',
+        flags: '--section <name>',
+        description: 'Section name to edit (Goal, Scope, Approach, etc.)',
+    };
+    const CONTENT_OPTION = {
+        name: 'content',
+        flags: '--content <text>',
+        description: 'New content for the section',
+    };
+    const APPEND_OPTION = {
+        name: 'append',
+        flags: '--append <text>',
+        description: 'Content to append to the section (instead of replace)',
+    };
+    const args = createWUParser({
+        name: 'plan-edit',
+        description: 'Edit a section in a plan file',
+        options: [WU_OPTIONS.id, SECTION_OPTION, CONTENT_OPTION, APPEND_OPTION],
+        required: ['id', 'section'],
+        allowPositionalId: true,
+    });
+    const id = args.id;
+    const section = args.section;
+    const content = args.content;
+    const appendContent = args.append;
+    // Validate we have either content or append
+    if (!content && !appendContent) {
+        die('Either --content or --append is required');
+    }
+    // Validate ID format
+    if (!WU_ID_PATTERN.test(id) && !INIT_ID_PATTERN.test(id)) {
+        die(`Invalid ID format: "${id}"\n\n` + `Expected format: WU-XXX or INIT-XXX`);
+    }
+    console.log(`${LOG_PREFIX} Editing plan for ${id}...`);
+    // Ensure on main for micro-worktree operations
+    await ensureOnMain(getGitForCwd());
+    try {
+        await withMicroWorktree({
+            operation: OPERATION_NAME,
+            id,
+            logPrefix: LOG_PREFIX,
+            pushOnly: true,
+            execute: async ({ worktreePath }) => {
+                const planRelPath = join(WU_PATHS.PLANS_DIR(), `${id}-plan.md`);
+                const planAbsPath = join(worktreePath, planRelPath);
+                if (!existsSync(planAbsPath)) {
+                    die(`Plan not found for ${id}\n\n` +
+                        `Expected path: ${planRelPath}\n\n` +
+                        `Create it first with: pnpm plan:create --id ${id} --title "Title"`);
+                }
+                let changed;
+                if (appendContent) {
+                    changed = appendToSection(planAbsPath, section, appendContent);
+                }
+                else if (content) {
+                    changed = updatePlanSection(planAbsPath, section, content);
+                }
+                else {
+                    // This shouldn't happen due to earlier validation, but satisfy TS
+                    changed = false;
+                }
+                if (!changed) {
+                    console.warn(`${LOG_PREFIX} Section "${section}" not found - no changes made`);
+                }
+                return {
+                    commitMessage: getCommitMessage(id, section),
+                    files: [planRelPath],
+                };
+            },
+        });
+        console.log(`\n${LOG_PREFIX} Plan edited successfully!`);
+        console.log(`\nEdit Details:`);
+        console.log(`  ID:      ${id}`);
+        console.log(`  Section: ${section}`);
+        console.log(`  Mode:    ${appendContent ? 'append' : 'replace'}`);
+    }
+    catch (error) {
+        die(`Plan edit 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}`);
+    }
+}
+// Guard main() for testability
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    void runCLI(main);
+}
+// Export for testing
+export { main };

package/dist/plan-link.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/* eslint-disable security/detect-non-literal-fs-filename */
+/**
+ * Plan Link Command (WU-1313)
+ *
+ * Links plan files to WUs (via spec_refs) or initiatives (via related_plan).
+ * This replaces the initiative:plan command for linking to initiatives.
+ *
+ * Usage:
+ *   pnpm plan:link --id WU-1313 --plan lumenflow://plans/WU-1313-plan.md
+ *   pnpm plan:link --id INIT-001 --plan lumenflow://plans/INIT-001-plan.md
+ *
+ * Features:
+ * - Auto-detects target type (WU or Initiative) from ID format
+ * - Updates spec_refs for WUs, related_plan for initiatives
+ * - Validates plan file exists before linking
+ * - Uses micro-worktree isolation for atomic commits
+ * - Idempotent: no error if already linked
+ *
+ * Context: WU-1313 (INIT-013 Plan Tooling)
+ */
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { INIT_PATHS } from '@lumenflow/initiatives/dist/initiative-paths.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.PLAN_LINK ?? '[plan:link]';
+/** Micro-worktree operation name */
+const OPERATION_NAME = 'plan-link';
+/** LumenFlow URI scheme for plan references */
+const PLAN_URI_SCHEME = 'lumenflow://plans/';
+/** WU ID pattern */
+const WU_ID_PATTERN = /^WU-\d+$/;
+/** Initiative ID pattern */
+const INIT_ID_PATTERN = /^INIT-[A-Z0-9]+$/i;
+/**
+ * Resolve the target type from an ID
+ *
+ * @param id - ID to check (WU-XXX or INIT-XXX)
+ * @returns 'wu' or 'initiative'
+ * @throws Error if ID format is invalid
+ */
+export function resolveTargetType(id) {
+    if (!id) {
+        die(`ID is required\n\nExpected format: WU-XXX or INIT-XXX`);
+    }
+    if (WU_ID_PATTERN.test(id)) {
+        return 'wu';
+    }
+    if (INIT_ID_PATTERN.test(id)) {
+        return 'initiative';
+    }
+    die(`Invalid ID format: "${id}"\n\n` +
+        `Expected format:\n` +
+        `  - WU ID: WU-<number> (e.g., WU-1313)\n` +
+        `  - Initiative ID: INIT-<alphanumeric> (e.g., INIT-001, INIT-TOOLING)`);
+    // TypeScript requires a return here even though die() never returns
+    return 'wu';
+}
+/**
+ * Validate that the plan file exists
+ *
+ * @param worktreePath - Path to repo root or worktree
+ * @param planUri - Plan URI (lumenflow://plans/...)
+ * @throws Error if plan file doesn't exist
+ */
+export function validatePlanExists(worktreePath, planUri) {
+    // Extract filename from URI
+    const filename = planUri.replace(PLAN_URI_SCHEME, '');
+    const plansDir = join(worktreePath, WU_PATHS.PLANS_DIR());
+    const planPath = join(plansDir, filename);
+    if (!existsSync(planPath)) {
+        die(`Plan file not found: ${planPath}\n\n` +
+            `Create it first with: pnpm plan:create --id <ID> --title "Title"`);
+    }
+}
+/**
+ * Link a plan to a WU by updating spec_refs
+ *
+ * @param worktreePath - Path to repo root or worktree
+ * @param wuId - WU ID
+ * @param planUri - Plan URI
+ * @returns True if changes were made, false if already linked
+ */
+export function linkPlanToWU(worktreePath, wuId, planUri) {
+    const wuRelPath = WU_PATHS.WU(wuId);
+    const wuAbsPath = join(worktreePath, wuRelPath);
+    if (!existsSync(wuAbsPath)) {
+        die(`WU not found: ${wuId}\n\nFile does not exist: ${wuAbsPath}`);
+    }
+    // Read raw YAML to preserve all fields
+    const rawText = readFileSync(wuAbsPath, { encoding: 'utf-8' });
+    const doc = parseYAML(rawText);
+    // Check for existing spec_refs
+    let specRefs = doc.spec_refs;
+    if (!specRefs) {
+        specRefs = [];
+    }
+    // Check if already linked
+    if (specRefs.includes(planUri)) {
+        console.log(`${LOG_PREFIX} Plan already linked to ${wuId} (idempotent)`);
+        return false;
+    }
+    // Add new plan URI
+    specRefs.push(planUri);
+    doc.spec_refs = specRefs;
+    // Write back
+    const out = stringifyYAML(doc, { lineWidth: -1 });
+    writeFileSync(wuAbsPath, out, { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Linked plan to ${wuId}: ${planUri}`);
+    return true;
+}
+/**
+ * Link a plan to an initiative by updating related_plan
+ *
+ * @param worktreePath - Path to repo root or worktree
+ * @param initId - Initiative ID
+ * @param planUri - Plan URI
+ * @returns True if changes were made, false if already linked
+ */
+export function linkPlanToInitiative(worktreePath, initId, planUri) {
+    const initRelPath = INIT_PATHS.INITIATIVE(initId);
+    const initAbsPath = join(worktreePath, initRelPath);
+    if (!existsSync(initAbsPath)) {
+        die(`Initiative not found: ${initId}\n\nFile does not exist: ${initAbsPath}`);
+    }
+    // Read raw YAML to preserve all fields
+    const rawText = readFileSync(initAbsPath, { encoding: 'utf-8' });
+    const doc = parseYAML(rawText);
+    // Check for existing related_plan
+    const existingPlan = doc.related_plan;
+    if (existingPlan === planUri) {
+        console.log(`${LOG_PREFIX} Plan already linked to ${initId} (idempotent)`);
+        return false;
+    }
+    if (existingPlan && existingPlan !== planUri) {
+        console.warn(`${LOG_PREFIX} Replacing existing related_plan: ${existingPlan} -> ${planUri}`);
+    }
+    // Update related_plan
+    doc.related_plan = planUri;
+    // Write back
+    const out = stringifyYAML(doc, { lineWidth: -1 });
+    writeFileSync(initAbsPath, out, { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Linked plan to ${initId}: ${planUri}`);
+    return true;
+}
+/**
+ * Generate commit message for plan link operation
+ *
+ * @param id - WU or Initiative ID
+ * @param planUri - Plan URI
+ * @returns Commit message
+ */
+export function getCommitMessage(id, planUri) {
+    const idLower = id.toLowerCase();
+    const filename = planUri.replace(PLAN_URI_SCHEME, '');
+    return `docs: link plan ${filename} to ${idLower}`;
+}
+async function main() {
+    const PLAN_OPTION = {
+        name: 'plan',
+        flags: '--plan <uri>',
+        description: 'Plan URI (lumenflow://plans/...)',
+    };
+    const args = createWUParser({
+        name: 'plan-link',
+        description: 'Link a plan file to a WU or initiative',
+        options: [WU_OPTIONS.id, PLAN_OPTION],
+        required: ['id', 'plan'],
+        allowPositionalId: true,
+    });
+    const id = args.id;
+    const planUri = args.plan;
+    // Resolve target type
+    const targetType = resolveTargetType(id);
+    console.log(`${LOG_PREFIX} Linking plan to ${targetType === 'wu' ? 'WU' : 'initiative'} ${id}...`);
+    // Ensure on main for micro-worktree operations
+    await ensureOnMain(getGitForCwd());
+    try {
+        await withMicroWorktree({
+            operation: OPERATION_NAME,
+            id,
+            logPrefix: LOG_PREFIX,
+            pushOnly: true,
+            execute: async ({ worktreePath }) => {
+                // Validate plan exists
+                validatePlanExists(worktreePath, planUri);
+                // Link plan based on target type
+                let changed;
+                let filePath;
+                if (targetType === 'wu') {
+                    changed = linkPlanToWU(worktreePath, id, planUri);
+                    filePath = WU_PATHS.WU(id);
+                }
+                else {
+                    changed = linkPlanToInitiative(worktreePath, id, planUri);
+                    filePath = INIT_PATHS.INITIATIVE(id);
+                }
+                if (!changed) {
+                    console.log(`${LOG_PREFIX} No changes needed (already linked)`);
+                }
+                return {
+                    commitMessage: getCommitMessage(id, planUri),
+                    files: [filePath],
+                };
+            },
+        });
+        console.log(`\n${LOG_PREFIX} Plan linked successfully!`);
+        console.log(`\nLink Details:`);
+        console.log(`  Target:  ${id} (${targetType})`);
+        console.log(`  Plan:    ${planUri}`);
+    }
+    catch (error) {
+        die(`Plan linking 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}`);
+    }
+}
+// Guard main() for testability
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    void runCLI(main);
+}
+// Export for testing
+export { main };