@lumenflow/cli 2.4.0 → 2.5.0

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 };

package/dist/plan-promote.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/* eslint-disable security/detect-non-literal-fs-filename */
+/**
+ * Plan Promote Command (WU-1313)
+ *
+ * Promotes a plan from draft to approved status.
+ * Validates that required sections are complete before approving.
+ *
+ * Usage:
+ *   pnpm plan:promote --id WU-1313
+ *   pnpm plan:promote --id INIT-001 --force  # Skip validation
+ *
+ * Features:
+ * - Validates plan completeness (non-empty required sections)
+ * - Adds approved status and timestamp
+ * - Uses micro-worktree isolation for atomic commits
+ * - Idempotent: no error if already approved
+ *
+ * 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 { 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_PROMOTE ?? '[plan:promote]';
+/** Micro-worktree operation name */
+const OPERATION_NAME = 'plan-promote';
+/** WU ID pattern */
+const WU_ID_PATTERN = /^WU-\d+$/;
+/** Initiative ID pattern */
+const INIT_ID_PATTERN = /^INIT-[A-Z0-9]+$/i;
+/** Required sections that must have content */
+const REQUIRED_SECTIONS = ['Goal', 'Scope', 'Approach'];
+/** Status marker patterns */
+const STATUS_APPROVED_PATTERN = /^Status:\s*approved/im;
+/**
+ * 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;
+}
+/**
+ * Validate that a plan has all required sections with content
+ *
+ * @param planPath - Path to plan file
+ * @returns Validation result with valid flag and errors array
+ */
+export function validatePlanComplete(planPath) {
+    if (!existsSync(planPath)) {
+        return { valid: false, errors: ['Plan file not found'] };
+    }
+    const text = readFileSync(planPath, { encoding: 'utf-8' });
+    const errors = [];
+    for (const section of REQUIRED_SECTIONS) {
+        const sectionHeading = `## ${section}`;
+        const headingIndex = text.indexOf(sectionHeading);
+        if (headingIndex === -1) {
+            errors.push(`Missing required section: ${section}`);
+            continue;
+        }
+        // Find the content between this heading and the next
+        const afterHeading = text.substring(headingIndex + sectionHeading.length);
+        const nextHeadingIndex = afterHeading.indexOf('\n## ');
+        const sectionContent = nextHeadingIndex >= 0 ? afterHeading.substring(0, nextHeadingIndex) : afterHeading;
+        // Check if content is just whitespace, empty, or only comments
+        const trimmedContent = sectionContent
+            .split('\n')
+            .filter((line) => !line.trim().startsWith('<!--') && line.trim() !== '-->')
+            .join('\n')
+            .trim();
+        if (trimmedContent === '' || trimmedContent.length < 10) {
+            errors.push(`${section} section is empty or too short`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Promote a plan to approved status
+ *
+ * Adds Status: approved and Approved: date after the Created line.
+ *
+ * @param planPath - Path to plan file
+ * @returns True if changes were made, false if already approved
+ */
+export function promotePlan(planPath) {
+    if (!existsSync(planPath)) {
+        die(`Plan file not found: ${planPath}`);
+    }
+    const text = readFileSync(planPath, { encoding: 'utf-8' });
+    // Check if already approved
+    if (STATUS_APPROVED_PATTERN.test(text)) {
+        console.log(`${LOG_PREFIX} Plan already approved (idempotent)`);
+        return false;
+    }
+    // Find the Created: line and insert status after it
+    // Use specific pattern to avoid backtracking (sonarjs/slow-regex)
+    const createdPattern = /^Created:\s*\S.*$/m;
+    const createdMatch = createdPattern.exec(text);
+    const today = todayISO();
+    const statusLines = `Status: approved\nApproved: ${today}`;
+    let newText;
+    if (createdMatch && createdMatch.index !== undefined) {
+        // Insert after Created: line
+        const insertPos = createdMatch.index + createdMatch[0].length;
+        newText = text.substring(0, insertPos) + '\n' + statusLines + text.substring(insertPos);
+    }
+    else {
+        // No Created: line found, insert after first heading
+        const firstHeadingPattern = /^# .+$/m;
+        const firstHeadingMatch = firstHeadingPattern.exec(text);
+        if (firstHeadingMatch && firstHeadingMatch.index !== undefined) {
+            const insertPos = firstHeadingMatch.index + firstHeadingMatch[0].length;
+            newText =
+                text.substring(0, insertPos) + '\n\n' + statusLines + '\n' + text.substring(insertPos);
+        }
+        else {
+            // Fallback: prepend to file
+            newText = statusLines + '\n\n' + text;
+        }
+    }
+    writeFileSync(planPath, newText, { encoding: 'utf-8' });
+    console.log(`${LOG_PREFIX} Plan promoted to approved status`);
+    return true;
+}
+/**
+ * Generate commit message for plan promote operation
+ *
+ * @param id - WU or Initiative ID
+ * @returns Commit message
+ */
+export function getCommitMessage(id) {
+    const idLower = id.toLowerCase();
+    return `docs: promote ${idLower} plan to approved`;
+}
+async function main() {
+    const FORCE_OPTION = {
+        name: 'force',
+        flags: '-f, --force',
+        description: 'Skip validation and promote anyway',
+    };
+    const args = createWUParser({
+        name: 'plan-promote',
+        description: 'Promote a plan to approved status',
+        options: [WU_OPTIONS.id, FORCE_OPTION],
+        required: ['id'],
+        allowPositionalId: true,
+    });
+    const id = args.id;
+    const force = args.force;
+    // 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} Promoting 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"`);
+                }
+                // Validate plan completeness (unless force)
+                if (!force) {
+                    const validation = validatePlanComplete(planAbsPath);
+                    if (!validation.valid) {
+                        const errorList = validation.errors.map((e) => `  - ${e}`).join('\n');
+                        die(`Plan validation failed:\n\n${errorList}\n\n` +
+                            `Fix these issues or use --force to skip validation.`);
+                    }
+                    console.log(`${LOG_PREFIX} Plan validation passed`);
+                }
+                // Promote the plan
+                const changed = promotePlan(planAbsPath);
+                if (!changed) {
+                    console.log(`${LOG_PREFIX} No changes needed (already approved)`);
+                }
+                return {
+                    commitMessage: getCommitMessage(id),
+                    files: [planRelPath],
+                };
+            },
+        });
+        console.log(`\n${LOG_PREFIX} Plan promoted successfully!`);
+        console.log(`\nPromotion Details:`);
+        console.log(`  ID:     ${id}`);
+        console.log(`  Status: approved`);
+    }
+    catch (error) {
+        die(`Plan promotion 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 };