@lumenflow/core 2.2.2 → 2.3.2

package/dist/wu-done-preflight.js

@@ -64,6 +64,7 @@ export async function executePreflightCodePathValidation(id, paths, options = {}
         errors: result.errors,
         missingCodePaths: result.missingCodePaths || [],
         missingTestPaths: result.missingTestPaths || [],
+        suggestedTestPaths: result.suggestedTestPaths || {},
         abortedBeforeGates: true,
     };
 }
@@ -71,7 +72,7 @@ export async function executePreflightCodePathValidation(id, paths, options = {}
  * WU-1805: Build preflight code_paths error message with actionable guidance
  */
 export function buildPreflightCodePathErrorMessage(id, result) {
-    const { errors, missingCodePaths = [], missingTestPaths = [] } = result;
+    const { errors, missingCodePaths = [], missingTestPaths = [], suggestedTestPaths = {}, } = result;
     let message = `
 ❌ PREFLIGHT CODE_PATHS VALIDATION FAILED
 
@@ -100,12 +101,27 @@ Fix options for missing test_paths:
 
 `;
     }
+    // Add suggested paths if available
+    const suggestionsMap = suggestedTestPaths;
+    const hasSuggestions = Object.keys(suggestionsMap).some((missingPath) => suggestionsMap[missingPath]?.length > 0);
+    if (hasSuggestions) {
+        message += `Suggested alternatives found:
+`;
+        for (const [missingPath, suggestions] of Object.entries(suggestionsMap)) {
+            if (suggestions.length > 0) {
+                message += `For "${missingPath}":
+${suggestions.map((s) => `  - ${s}`).join('\n')}
+
+`;
+            }
+        }
+    }
     message += `
 After fixing, retry:
   pnpm wu:done --id ${id}
 
 This preflight check runs BEFORE gates to catch YAML mismatches early.
-See: docs/04-operations/_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md for more recovery options.
+See: https://lumenflow.dev/reference/troubleshooting-wu-done/ for more recovery options.
 `;
     return message;
 }

package/dist/wu-done-ui.d.ts

@@ -4,13 +4,13 @@
  * WU-1281: Extracted display helpers to consolidate DRY violations
  * and use library-first duration formatting.
  *
- * @see {@link tools/wu-done.mjs} - Primary consumer
- * @see {@link tools/lib/wu-constants.mjs} - UI constants
+ * @see {@link packages/@lumenflow/cli/src/wu-done.ts} - Primary consumer
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-constants.ts} - UI constants
  */
 /**
  * Print prominent gate failure box
  *
- * Consolidated from two duplicate implementations in wu-done.mjs
+ * Consolidated from two duplicate implementations in wu-done.ts
  * (worktree mode and branch-only mode). Uses pretty-ms for
  * human-readable duration formatting.
  *

package/dist/wu-done-ui.js

@@ -4,15 +4,15 @@
  * WU-1281: Extracted display helpers to consolidate DRY violations
  * and use library-first duration formatting.
  *
- * @see {@link tools/wu-done.mjs} - Primary consumer
- * @see {@link tools/lib/wu-constants.mjs} - UI constants
+ * @see {@link packages/@lumenflow/cli/src/wu-done.ts} - Primary consumer
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-constants.ts} - UI constants
  */
 import prettyMs from 'pretty-ms';
 import { UI, LOG_PREFIX, STRING_LITERALS } from './wu-constants.js';
 /**
  * Print prominent gate failure box
  *
- * Consolidated from two duplicate implementations in wu-done.mjs
+ * Consolidated from two duplicate implementations in wu-done.ts
  * (worktree mode and branch-only mode). Uses pretty-ms for
  * human-readable duration formatting.
  *

package/dist/wu-done-validation.d.ts

@@ -79,4 +79,34 @@ export declare function validateTypeVsCodePathsPreflight(wu: any): {
  * WU-2310: Build error message for type vs code_paths preflight failure.
  */
 export declare function buildTypeVsCodePathsErrorMessage(id: any, blockedPaths: any): string;
+/**
+ * WU-1153: Validate that code_paths are committed before wu:done metadata updates
+ *
+ * Prevents lost work by ensuring all code_paths are committed before metadata
+ * transaction starts. If code_paths are uncommitted and metadata transaction
+ * fails, the rollback could lose the uncommitted code changes.
+ *
+ * @param {object} wu - WU YAML document
+ * @param {object} gitAdapter - Git adapter instance
+ * @param {object} options - Validation options
+ * @param {boolean} [options.abortOnFailure=true] - Whether to call die() on failure
+ * @returns {Promise<{valid: boolean, errors: string[], uncommittedPaths: string[]}>}
+ */
+export declare function validateCodePathsCommittedBeforeDone(wu: Record<string, unknown>, gitAdapter: {
+    getStatus: () => Promise<string>;
+}, options?: {
+    abortOnFailure?: boolean;
+}): Promise<{
+    valid: boolean;
+    errors: string[];
+    uncommittedPaths: string[];
+}>;
+/**
+ * WU-1153: Build error message for uncommitted code_paths validation failure
+ *
+ * @param {string} wuId - WU ID
+ * @param {string[]} uncommittedPaths - List of uncommitted code_paths
+ * @returns {string} Formatted error message
+ */
+export declare function buildCodePathsCommittedErrorMessage(wuId: string, uncommittedPaths: string[]): string;
 export {};

package/dist/wu-done-validation.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { getGitForCwd } from './git-adapter.js';
 import { parseYAML } from './wu-yaml.js';
+import { die } from './error-handler.js';
 import { BRANCHES, EMOJI, FILE_SYSTEM, GIT_COMMANDS, LOG_PREFIX, STRING_LITERALS, TEST_TYPES, VALIDATION, WU_TYPES, } from './wu-constants.js';
 import { PLACEHOLDER_SENTINEL } from './wu-schema.js';
 import { resolveExposureDefault } from './wu-validation.js';
@@ -251,7 +252,7 @@ export function validateTestPathsRequired(wu) {
 }
 /**
  * WU-2310: Allowed path patterns for documentation WUs.
- * Mirrors the patterns in gates-pre-commit.mjs gateDocsOnlyPathEnforcement()
+ * Mirrors the patterns in gates-pre-commit.ts gateDocsOnlyPathEnforcement()
  * to enable early validation at preflight (before transaction starts).
  *
  * @constant {RegExp[]}
@@ -338,3 +339,107 @@ Allowed paths for documentation WUs:
 After fixing, retry: pnpm wu:done --id ${id}
 `;
 }
+/**
+ * WU-1153: Validate that code_paths are committed before wu:done metadata updates
+ *
+ * Prevents lost work by ensuring all code_paths are committed before metadata
+ * transaction starts. If code_paths are uncommitted and metadata transaction
+ * fails, the rollback could lose the uncommitted code changes.
+ *
+ * @param {object} wu - WU YAML document
+ * @param {object} gitAdapter - Git adapter instance
+ * @param {object} options - Validation options
+ * @param {boolean} [options.abortOnFailure=true] - Whether to call die() on failure
+ * @returns {Promise<{valid: boolean, errors: string[], uncommittedPaths: string[]}>}
+ */
+export async function validateCodePathsCommittedBeforeDone(wu, gitAdapter, options = {}) {
+    const { abortOnFailure = true } = options;
+    const errors = [];
+    const uncommittedPaths = [];
+    // Skip validation if no code_paths
+    const codePaths = wu.code_paths;
+    if (!codePaths || codePaths.length === 0) {
+        return { valid: true, errors: [], uncommittedPaths: [] };
+    }
+    try {
+        // Get git status to check for uncommitted files
+        const gitStatus = await gitAdapter.getStatus();
+        // Parse git status output to find uncommitted files
+        const statusLines = gitStatus.split('\n').filter((line) => line.trim());
+        // Create a Set of uncommitted file paths for efficient lookup
+        const uncommittedFiles = new Set();
+        for (const line of statusLines) {
+            // Git status porcelain format:
+            // XY PATH
+            // where X = staged, Y = working tree
+            // We care about any file that's not in a clean state
+            const match = line.match(/^.{2}\s+(.+)$/);
+            if (match) {
+                const filePath = match[1];
+                uncommittedFiles.add(filePath);
+            }
+        }
+        // Check each code_path against uncommitted files
+        for (const codePath of codePaths) {
+            if (uncommittedFiles.has(codePath)) {
+                uncommittedPaths.push(codePath);
+            }
+        }
+        // If any code_paths are uncommitted, validation fails
+        if (uncommittedPaths.length > 0) {
+            const count = uncommittedPaths.length;
+            const pathList = uncommittedPaths.map((p) => `  - ${p}`).join('\n');
+            errors.push(`${count} code_path${count === 1 ? '' : 's'} are not committed:\n${pathList}`);
+            if (abortOnFailure) {
+                const errorMessage = buildCodePathsCommittedErrorMessage(wu.id, uncommittedPaths);
+                die(errorMessage);
+            }
+        }
+    }
+    catch (err) {
+        // If git status fails, warn but don't block (non-fatal)
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not validate code_paths commit status: ${err instanceof Error ? err.message : String(err)}`);
+        return { valid: true, errors: [], uncommittedPaths: [] };
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        uncommittedPaths,
+    };
+}
+/**
+ * WU-1153: Build error message for uncommitted code_paths validation failure
+ *
+ * @param {string} wuId - WU ID
+ * @param {string[]} uncommittedPaths - List of uncommitted code_paths
+ * @returns {string} Formatted error message
+ */
+export function buildCodePathsCommittedErrorMessage(wuId, uncommittedPaths) {
+    const count = uncommittedPaths.length;
+    const pathList = uncommittedPaths.map((p) => `  - ${p}`).join('\n');
+    return `
+❌ UNCOMMITTED CODE_PATHS DETECTED (WU-1153)
+
+${count} code_path${count === 1 ? '' : 's'} for ${wuId} are not committed:
+
+${pathList}
+
+wu:done cannot proceed because uncommitted code_paths would be lost 
+if the metadata transaction fails and needs to roll back.
+
+This prevents lost work from metadata rollbacks after code commits.
+
+Required actions:
+  1. Commit your code changes:
+     git add ${uncommittedPaths.join(' ')}
+     git commit -m "implement: ${wuId} changes"
+
+  2. Retry wu:done:
+     pnpm wu:done --id ${wuId}
+
+The guard ensures atomic completion: either both code and metadata succeed,
+or neither is modified. This prevents partial state corruption.
+
+Context: WU-1153 prevents lost work from metadata rollbacks
+`;
+}

package/dist/wu-done-worktree.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Worktree mode completion workflow for wu:done
- * Extracted from wu-done.mjs (WU-1215 refactoring)
+ * Extracted from wu-done.ts (WU-1215 refactoring)
  * Updated in WU-1369 to use atomic transaction pattern.
  *
  * Flow (WU-1369 Atomic Pattern):

package/dist/wu-done-worktree.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Worktree mode completion workflow for wu:done
- * Extracted from wu-done.mjs (WU-1215 refactoring)
+ * Extracted from wu-done.ts (WU-1215 refactoring)
  * Updated in WU-1369 to use atomic transaction pattern.
  *
  * Flow (WU-1369 Atomic Pattern):
@@ -30,6 +30,7 @@ import { getDriftLevel, DRIFT_LEVELS } from './branch-drift.js';
 import { createError, ErrorCodes } from './error-handler.js';
 import { createRecoveryError, createValidationError } from './wu-done-errors.js';
 import { validateDoneWU, validateAndNormalizeWUYAML } from './wu-schema.js';
+import { validateCodePathsCommittedBeforeDone } from './wu-done-validation.js';
 import { assertTransition } from './state-machine.js';
 import { detectZombieState, resetWorktreeYAMLForRecovery, getRecoveryAttemptCount, incrementRecoveryAttempt, clearRecoveryAttempts, shouldEscalateToManualIntervention, MAX_RECOVERY_ATTEMPTS, } from './wu-recovery.js';
 import { isPRModeEnabled, createPR, printPRCreatedMessage } from './wu-done-pr.js';
@@ -203,6 +204,15 @@ export async function executeWorktreeCompletion(context) {
         if (!completenessResult.valid) {
             throw createValidationError(`Cannot mark WU as done - spec incomplete:\n  ${completenessResult.errors.join('\n  ')}\n\nNext step: Update ${workingWUPath} to meet completion requirements and rerun wu:done`, { wuId: id });
         }
+        // WU-1153: Validate code_paths are committed before metadata transaction
+        // This prevents lost work from metadata rollbacks after code commits
+        console.log(`${LOG_PREFIX.DONE} Checking code_paths commit status (WU-1153)...`);
+        const gitAdapter = getGitForCwd();
+        const codePathsResult = await validateCodePathsCommittedBeforeDone(normalizeResult.normalized, gitAdapter, { abortOnFailure: false });
+        if (!codePathsResult.valid) {
+            const errorMessage = await import('./wu-done-validation.js').then((m) => m.buildCodePathsCommittedErrorMessage(id, codePathsResult.uncommittedPaths));
+            throw createValidationError(errorMessage, { wuId: id });
+        }
         console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All validations passed`);
         // ======================================================================
         // PHASE 2: COLLECT ALL CHANGES TO TRANSACTION (in memory, no writes)

package/dist/wu-events-cleanup.d.ts

@@ -0,0 +1,148 @@
+/**
+ * WU Events Cleanup (WU-1207)
+ *
+ * Archive old WU events to prevent unbounded growth of wu-events.jsonl.
+ * Moves completed WU events older than 90d to .lumenflow/archive/wu-events-YYYY-MM.jsonl.
+ * Keeps active WU events intact.
+ *
+ * Features:
+ * - Configurable archiveAfter threshold (default: 90 days)
+ * - Groups events by WU ID for atomic archival
+ * - Monthly archive file rollup
+ * - Active WU protection (in_progress/blocked/waiting never archived)
+ * - Dry-run mode for preview
+ *
+ * Reuses atomic write patterns from wu-state-store.ts.
+ *
+ * @see {@link packages/@lumenflow/core/src/__tests__/wu-events-cleanup.test.ts} - Tests
+ */
+import { type WUEvent } from './wu-state-schema.js';
+import type { EventArchivalConfig } from './lumenflow-config-schema.js';
+export type { EventArchivalConfig };
+/**
+ * Default event archival configuration
+ */
+export declare const DEFAULT_EVENT_ARCHIVAL_CONFIG: EventArchivalConfig;
+/**
+ * Context for archive decision making
+ */
+export interface ArchiveContext {
+    /** Current timestamp for age calculations */
+    now: number;
+    /** Set of WU IDs that are currently active (in_progress/blocked/waiting) */
+    activeWuIds: Set<string>;
+}
+/**
+ * Result of shouldArchiveEvent decision
+ */
+export interface ArchiveDecision {
+    archive: boolean;
+    reason: string;
+}
+/**
+ * Breakdown of archival by category
+ */
+export interface ArchivalBreakdown {
+    archivedOlderThanThreshold: number;
+    retainedActiveWu: number;
+    retainedWithinThreshold: number;
+}
+/**
+ * Options for archiveWuEvents operation
+ */
+export interface ArchiveWuEventsOptions {
+    /** If true, preview without modifications */
+    dryRun?: boolean;
+    /** Archive threshold duration string (e.g., '90d') */
+    archiveAfter?: string;
+    /** Archive threshold in milliseconds (alternative to archiveAfter string) */
+    archiveAfterMs?: number;
+    /** Current timestamp for testing (defaults to Date.now()) */
+    now?: number;
+    /** Function to get active WU IDs (override for testing) */
+    getActiveWuIds?: (baseDir: string) => Promise<Set<string>>;
+}
+/**
+ * Result of archiveWuEvents operation
+ */
+export interface ArchiveWuEventsResult {
+    /** Whether archival succeeded */
+    success: boolean;
+    /** WU IDs that were archived */
+    archivedWuIds: string[];
+    /** WU IDs that were retained */
+    retainedWuIds: string[];
+    /** Total number of events archived */
+    archivedEventCount: number;
+    /** Total number of events retained */
+    retainedEventCount: number;
+    /** Approximate bytes moved to archive */
+    bytesArchived: number;
+    /** True if in dry-run mode */
+    dryRun?: boolean;
+    /** Breakdown by category */
+    breakdown: ArchivalBreakdown;
+}
+/**
+ * Parse an archiveAfter duration string into milliseconds.
+ *
+ * Uses the `ms` package to parse human-readable duration strings.
+ *
+ * @param archiveAfterString - Duration string (e.g., '90d', '30d', '24h')
+ * @returns Duration in milliseconds
+ * @throws If format is invalid
+ *
+ * @example
+ * parseArchiveAfter('90d');  // 7776000000 (90 days in ms)
+ * parseArchiveAfter('30d');  // 2592000000 (30 days in ms)
+ */
+export declare function parseArchiveAfter(archiveAfterString: string): number;
+/**
+ * Get the archive file path for a given event timestamp.
+ *
+ * Groups events by month into files like:
+ * .lumenflow/archive/wu-events-2026-01.jsonl
+ *
+ * @param timestamp - ISO 8601 timestamp string
+ * @returns Relative path to archive file
+ *
+ * @example
+ * getArchiveFilePath('2026-01-15T10:30:00.000Z');
+ * // Returns: '.lumenflow/archive/wu-events-2026-01.jsonl'
+ */
+export declare function getArchiveFilePath(timestamp: string): string;
+/**
+ * Determine if an event should be archived based on WU status and age.
+ *
+ * Policy rules (checked in order):
+ * 1. Active WU events (in_progress/blocked/waiting) are never archived
+ * 2. Completed WU events older than threshold are archived
+ * 3. Otherwise, event is retained
+ *
+ * @param event - WU event to check
+ * @param config - Archival configuration
+ * @param context - Archive context (now timestamp, active WU IDs)
+ * @returns Archive decision with reason
+ */
+export declare function shouldArchiveEvent(event: WUEvent, config: EventArchivalConfig, context: ArchiveContext): ArchiveDecision;
+/**
+ * Archive old WU events to monthly archive files.
+ *
+ * Moves completed WU events older than threshold to archive files.
+ * Events are grouped by WU ID so all events for a WU are archived together.
+ * Active WU events (in_progress/blocked/waiting) are never archived.
+ *
+ * @param baseDir - Project base directory
+ * @param options - Archive options
+ * @returns Archive result with statistics
+ *
+ * @example
+ * // Preview archival
+ * const preview = await archiveWuEvents(baseDir, { dryRun: true });
+ * console.log(`Would archive ${preview.archivedWuIds.length} WUs`);
+ *
+ * @example
+ * // Archive with custom threshold
+ * const result = await archiveWuEvents(baseDir, { archiveAfter: '30d' });
+ */
+export declare function archiveWuEvents(baseDir: string, options?: ArchiveWuEventsOptions): Promise<ArchiveWuEventsResult>;