@lumenflow/cli 2.3.2 → 2.5.0

package/dist/initiative-add-wu.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 /* eslint-disable security/detect-non-literal-fs-filename */
+/* eslint-disable no-console -- CLI tool requires console output */
 /**
  * Initiative Add WU Command (WU-1389)
  *
@@ -30,13 +31,118 @@ import { INIT_PATTERNS, INIT_COMMIT_FORMATS, INIT_LOG_PREFIX, } from '@lumenflow
 import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { PATTERNS } 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';
+import { withMicroWorktree, isRetryExhaustionError as coreIsRetryExhaustionError, formatRetryExhaustionError as coreFormatRetryExhaustionError, } from '@lumenflow/core/dist/micro-worktree.js';
 import { readWU, writeWU } from '@lumenflow/core/dist/wu-yaml.js';
 import { readInitiative, writeInitiative } from '@lumenflow/initiatives/dist/initiative-yaml.js';
+import { validateSingleWU } from '@lumenflow/core/dist/validators/wu-tasks.js';
 /** Log prefix for console output */
 const LOG_PREFIX = INIT_LOG_PREFIX.ADD_WU;
 /** Micro-worktree operation name */
 const OPERATION_NAME = 'initiative-add-wu';
+/**
+ * Validate WU spec for linking to an initiative (WU-1330)
+ *
+ * Performs validation including:
+ * - Schema validation (required fields, formats) - BLOCKING
+ * - Placeholder detection ([PLACEHOLDER] markers) - BLOCKING
+ * - Minimum description length (50 chars) - BLOCKING
+ * - Acceptance criteria present - BLOCKING
+ * - Completeness warnings (notes, spec_refs) - NON-BLOCKING
+ *
+ * Uses non-strict mode: schema errors block, completeness warnings don't.
+ *
+ * @param {string} wuId - WU ID to validate
+ * @returns {WULinkValidationResult} Validation result with errors and warnings
+ */
+export function validateWUForLinking(wuId) {
+    const wuPath = WU_PATHS.WU(wuId);
+    // Check if file exists first
+    if (!existsSync(wuPath)) {
+        return {
+            valid: false,
+            errors: [`WU file not found: ${wuPath}`],
+            warnings: [],
+        };
+    }
+    // Use the core validator with non-strict mode
+    // Schema errors (required fields, format, placeholders) -> block
+    // Completeness warnings (notes, spec_refs) -> don't block
+    const result = validateSingleWU(wuPath, { strict: false });
+    return {
+        valid: result.valid,
+        errors: result.errors,
+        warnings: result.warnings,
+    };
+}
+/**
+ * WU-1333/WU-1336: Check if an error is a retry exhaustion error
+ *
+ * Detects when micro-worktree push retries have been exhausted.
+ * Delegates to the shared helper from @lumenflow/core.
+ *
+ * @param {Error} error - Error to check
+ * @returns {boolean} True if this is a retry exhaustion error
+ */
+export function isRetryExhaustionError(error) {
+    return coreIsRetryExhaustionError(error);
+}
+/**
+ * WU-1333/WU-1336: Format retry exhaustion error with actionable next steps
+ *
+ * When push retries are exhausted, provides clear guidance on how to proceed.
+ * Delegates to the shared helper from @lumenflow/core with command-specific options.
+ *
+ * @param {Error} error - The retry exhaustion error
+ * @param {string} wuId - WU ID being linked
+ * @param {string} initId - Initiative ID being linked to
+ * @returns {string} Formatted error message with next steps
+ */
+export function formatRetryExhaustionError(error, wuId, initId) {
+    return coreFormatRetryExhaustionError(error, {
+        command: `pnpm initiative:add-wu --wu ${wuId} --initiative ${initId}`,
+    });
+}
+/**
+ * Format validation errors for display to user (WU-1330)
+ *
+ * Creates a human-readable error message with all validation issues.
+ *
+ * @param {string} wuId - WU ID that failed validation
+ * @param {string[]} errors - Array of error messages
+ * @returns {string} Formatted error message
+ */
+export function formatValidationErrors(wuId, errors) {
+    const errorList = errors.map((e) => `  - ${e}`).join('\n');
+    return (`WU ${wuId} failed validation:\n\n${errorList}\n\n` +
+        `Fix the WU spec before linking to an initiative:\n` +
+        `  pnpm wu:edit --id ${wuId} ...\n\n` +
+        `Or validate the WU:\n` +
+        `  pnpm wu:validate --id ${wuId}`);
+}
+/**
+ * Check if WU exists and is valid for linking (WU-1330)
+ *
+ * Combines existence check with strict validation.
+ * Throws with aggregated errors if validation fails.
+ *
+ * @param {string} wuId - WU ID to check and validate
+ * @returns {object} WU document if validation passes
+ * @throws {Error} If WU doesn't exist or validation fails
+ */
+export function checkWUExistsAndValidate(wuId) {
+    const wuPath = WU_PATHS.WU(wuId);
+    // Check existence
+    if (!existsSync(wuPath)) {
+        die(`WU not found: ${wuId}\n\nFile does not exist: ${wuPath}`);
+    }
+    // Validate WU
+    const validation = validateWUForLinking(wuId);
+    if (!validation.valid) {
+        die(formatValidationErrors(wuId, validation.errors));
+    }
+    // Return the document if validation passes
+    return readWU(wuPath, wuId);
+}
 /**
  * Validate Initiative ID format
  * @param {string} id - Initiative ID to validate
@@ -56,18 +162,6 @@ function validateWuIdFormat(id) {
         die(`Invalid WU ID format: "${id}"\n\nExpected format: WU-<number> (e.g., WU-123)`);
     }
 }
-/**
- * Check if WU exists
- * @param {string} wuId - WU ID to check
- * @returns {object} WU document
- */
-function checkWUExists(wuId) {
-    const wuPath = WU_PATHS.WU(wuId);
-    if (!existsSync(wuPath)) {
-        die(`WU not found: ${wuId}\n\nFile does not exist: ${wuPath}`);
-    }
-    return readWU(wuPath, wuId);
-}
 /**
  * Check if Initiative exists
  * @param {string} initId - Initiative ID to check
@@ -164,10 +258,12 @@ async function main() {
     const wuId = args.wu;
     const initId = args.initiative;
     console.log(`${LOG_PREFIX} Linking ${wuId} to ${initId}...`);
-    // Pre-flight validation
+    // Pre-flight validation: ID formats
     validateInitIdFormat(initId);
     validateWuIdFormat(wuId);
-    const wuDoc = checkWUExists(wuId);
+    // WU-1330: Validate WU spec before linking
+    // This ensures only valid, complete WUs can be linked to initiatives
+    const wuDoc = checkWUExistsAndValidate(wuId);
     const initDoc = checkInitiativeExists(initId);
     // Check for conflicting links
     checkConflictingLink(wuDoc, initId);
@@ -232,5 +328,5 @@ async function main() {
 // path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
 if (import.meta.main) {
-    runCLI(main);
+    void runCLI(main);
 }

package/dist/initiative-plan.js

@@ -31,12 +31,13 @@ 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';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.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';
+/** Standard plans directory relative to repo root (WU-1301: uses config-based paths) */
+const PLANS_DIR = WU_PATHS.PLANS_DIR();
 /** LumenFlow URI scheme for plan references */
 const PLAN_URI_SCHEME = 'lumenflow://plans/';
 /**

package/dist/initiative-remove-wu.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/* eslint-disable security/detect-non-literal-fs-filename */
+/* eslint-disable no-console -- CLI tool requires console output */
+/**
+ * Initiative Remove WU Command (WU-1328)
+ *
+ * Unlinks a WU from an initiative bidirectionally:
+ * 1. Removes `initiative: INIT-NNN` field from WU YAML
+ * 2. Removes WU ID from initiative `wus: []` array
+ *
+ * Uses micro-worktree isolation for atomic operations.
+ *
+ * Usage:
+ *   pnpm initiative:remove-wu --initiative INIT-001 --wu WU-123
+ *
+ * Features:
+ * - Validates both WU and initiative exist before modifying
+ * - Idempotent: no error if link does not exist
+ * - Handles partial state gracefully (WU has initiative but not in initiative's wus list)
+ * - Atomic: both files updated in single commit
+ *
+ * Context: WU-1328 (initial implementation)
+ */
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { existsSync } from 'node:fs';
+import { join } 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, INIT_COMMIT_FORMATS, INIT_LOG_PREFIX, } from '@lumenflow/initiatives/dist/initiative-constants.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { PATTERNS } from '@lumenflow/core/dist/wu-constants.js';
+import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree, isRetryExhaustionError as coreIsRetryExhaustionError, formatRetryExhaustionError as coreFormatRetryExhaustionError, } from '@lumenflow/core/dist/micro-worktree.js';
+import { readWU, writeWU } from '@lumenflow/core/dist/wu-yaml.js';
+import { readInitiative, writeInitiative } from '@lumenflow/initiatives/dist/initiative-yaml.js';
+/** Log prefix for console output */
+export const LOG_PREFIX = INIT_LOG_PREFIX.REMOVE_WU;
+/** Micro-worktree operation name */
+export const OPERATION_NAME = 'initiative-remove-wu';
+/**
+ * WU-1333/WU-1336: Check if an error is a retry exhaustion error
+ *
+ * Detects when micro-worktree push retries have been exhausted.
+ * Delegates to the shared helper from @lumenflow/core.
+ *
+ * @param {Error} error - Error to check
+ * @returns {boolean} True if this is a retry exhaustion error
+ */
+export function isRetryExhaustionError(error) {
+    return coreIsRetryExhaustionError(error);
+}
+/**
+ * WU-1333/WU-1336: Format retry exhaustion error with actionable next steps
+ *
+ * When push retries are exhausted, provides clear guidance on how to proceed.
+ * Delegates to the shared helper from @lumenflow/core with command-specific options.
+ *
+ * @param {Error} error - The retry exhaustion error
+ * @param {string} wuId - WU ID being unlinked
+ * @param {string} initId - Initiative ID being unlinked from
+ * @returns {string} Formatted error message with next steps
+ */
+export function formatRetryExhaustionError(error, wuId, initId) {
+    return coreFormatRetryExhaustionError(error, {
+        command: `pnpm initiative:remove-wu --wu ${wuId} --initiative ${initId}`,
+    });
+}
+/**
+ * Validate Initiative ID format
+ * @param {string} id - Initiative ID to validate
+ */
+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 WU ID format
+ * @param {string} id - WU ID to validate
+ */
+export function validateWuIdFormat(id) {
+    if (!PATTERNS.WU_ID.test(id)) {
+        die(`Invalid WU ID format: "${id}"\n\nExpected format: WU-<number> (e.g., WU-123)`);
+    }
+}
+/**
+ * Check if WU exists
+ * @param {string} wuId - WU ID to check
+ * @returns {object} WU document
+ */
+export function checkWUExists(wuId) {
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        die(`WU not found: ${wuId}\n\nFile does not exist: ${wuPath}`);
+    }
+    return readWU(wuPath, wuId);
+}
+/**
+ * Check if Initiative exists
+ * @param {string} initId - Initiative ID to check
+ * @returns {object} Initiative document
+ */
+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);
+}
+/**
+ * Check if WU is currently linked to the initiative
+ * @param {object} wuDoc - WU document
+ * @param {object} initDoc - Initiative document
+ * @param {string} wuId - WU ID
+ * @param {string} initId - Initiative ID
+ * @returns {boolean} True if WU is linked to the initiative (both sides)
+ */
+export function checkWUIsLinked(wuDoc, initDoc, wuId, initId) {
+    const wuHasInit = wuDoc.initiative === initId;
+    const initHasWu = Array.isArray(initDoc.wus) && initDoc.wus.includes(wuId);
+    return wuHasInit && initHasWu;
+}
+/**
+ * Update WU YAML in micro-worktree (remove initiative field)
+ * @param {string} worktreePath - Path to micro-worktree
+ * @param {string} wuId - WU ID
+ * @param {string} initId - Initiative ID to remove
+ * @returns {boolean} True if changes were made
+ */
+export function updateWUInWorktree(worktreePath, wuId, initId) {
+    const wuRelPath = WU_PATHS.WU(wuId);
+    const wuAbsPath = join(worktreePath, wuRelPath);
+    const doc = readWU(wuAbsPath, wuId);
+    // Skip if no initiative field or different initiative (idempotent)
+    if (!doc.initiative || doc.initiative !== initId) {
+        return false;
+    }
+    // Remove initiative field
+    delete doc.initiative;
+    writeWU(wuAbsPath, doc);
+    console.log(`${LOG_PREFIX} Removed initiative: ${initId} from ${wuId}`);
+    return true;
+}
+/**
+ * Update Initiative YAML in micro-worktree (remove WU from wus list)
+ * @param {string} worktreePath - Path to micro-worktree
+ * @param {string} initId - Initiative ID
+ * @param {string} wuId - WU ID to remove
+ * @returns {boolean} True if changes were made
+ */
+export function updateInitiativeInWorktree(worktreePath, initId, wuId) {
+    const initRelPath = INIT_PATHS.INITIATIVE(initId);
+    const initAbsPath = join(worktreePath, initRelPath);
+    const doc = readInitiative(initAbsPath, initId);
+    // Skip if no wus array or WU not in list (idempotent)
+    if (!Array.isArray(doc.wus) || !doc.wus.includes(wuId)) {
+        return false;
+    }
+    // Remove WU from list
+    doc.wus = doc.wus.filter((id) => id !== wuId);
+    writeInitiative(initAbsPath, doc);
+    console.log(`${LOG_PREFIX} Removed ${wuId} from ${initId} wus list`);
+    return true;
+}
+export async function main() {
+    const args = createWUParser({
+        name: 'initiative-remove-wu',
+        description: 'Unlink a WU from an initiative bidirectionally',
+        options: [WU_OPTIONS.initiative, WU_OPTIONS.wu],
+        required: ['initiative', 'wu'],
+        allowPositionalId: false,
+    });
+    // Normalize args
+    const wuId = args.wu;
+    const initId = args.initiative;
+    console.log(`${LOG_PREFIX} Unlinking ${wuId} from ${initId}...`);
+    // Pre-flight validation
+    validateInitIdFormat(initId);
+    validateWuIdFormat(wuId);
+    const wuDoc = checkWUExists(wuId);
+    const initDoc = checkInitiativeExists(initId);
+    // Check if link exists - if not, report success (idempotent)
+    const wuHasInit = wuDoc.initiative === initId;
+    const initHasWu = Array.isArray(initDoc.wus) && initDoc.wus.includes(wuId);
+    if (!wuHasInit && !initHasWu) {
+        console.log(`${LOG_PREFIX} Link does not exist (idempotent - no changes needed)`);
+        console.log(`\n${LOG_PREFIX} ${wuId} is not linked to ${initId}`);
+        return;
+    }
+    // Ensure on main branch
+    await ensureOnMain(getGitForCwd());
+    // Transaction: micro-worktree isolation
+    try {
+        await withMicroWorktree({
+            operation: OPERATION_NAME,
+            id: `${wuId}-${initId}`.toLowerCase(),
+            logPrefix: LOG_PREFIX,
+            pushOnly: true,
+            execute: async ({ worktreePath }) => {
+                const files = [];
+                // Update WU YAML (remove initiative field)
+                const wuChanged = updateWUInWorktree(worktreePath, wuId, initId);
+                if (wuChanged) {
+                    files.push(WU_PATHS.WU(wuId));
+                }
+                // Update Initiative YAML (remove WU from wus list)
+                const initChanged = updateInitiativeInWorktree(worktreePath, initId, wuId);
+                if (initChanged) {
+                    files.push(INIT_PATHS.INITIATIVE(initId));
+                }
+                // If no changes, this is idempotent (race condition handling)
+                if (files.length === 0) {
+                    console.log(`${LOG_PREFIX} No changes detected (concurrent unlink operation)`);
+                    // Still need to return something for the commit
+                    return {
+                        commitMessage: INIT_COMMIT_FORMATS.UNLINK_WU(wuId, initId),
+                        files: [WU_PATHS.WU(wuId), INIT_PATHS.INITIATIVE(initId)],
+                    };
+                }
+                return {
+                    commitMessage: INIT_COMMIT_FORMATS.UNLINK_WU(wuId, initId),
+                    files,
+                };
+            },
+        });
+        console.log(`\n${LOG_PREFIX} Transaction complete!`);
+        console.log(`\nLink Removed:`);
+        console.log(`  WU:         ${wuId}`);
+        console.log(`  Initiative: ${initId}`);
+        console.log(`\nNext steps:`);
+        console.log(`  - View initiative status: pnpm initiative:status ${initId}`);
+        console.log(`  - View WU: cat ${WU_PATHS.WU(wuId)}`);
+    }
+    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}`);
+    }
+}
+// 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 (import.meta.main) {
+    void runCLI(main);
+}

package/dist/metrics-snapshot.js

@@ -24,12 +24,13 @@ import { Command } from 'commander';
 import { captureMetricsSnapshot, } from '@lumenflow/metrics';
 import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[metrics:snapshot]';
 /** Default snapshot output path */
 const DEFAULT_OUTPUT = '.lumenflow/snapshots/metrics-latest.json';
-/** WU directory relative to repo root */
-const WU_DIR = 'docs/04-operations/tasks/wu';
+/** WU directory relative to repo root (WU-1301: uses config-based paths) */
+const WU_DIR = WU_PATHS.WU_DIR();
 /** Skip-gates audit file path */
 const SKIP_GATES_PATH = '.lumenflow/skip-gates-audit.ndjson';
 /** Snapshot type options */