@lumenflow/core 2.2.2 → 2.3.2

package/dist/test-baseline.js

@@ -0,0 +1,282 @@
+/**
+ * Test Baseline - Test Ratchet Pattern (WU-1253)
+ *
+ * Implements a "ratchet" pattern for test failures:
+ * - Track known failures in a baseline file (.lumenflow/test-baseline.json)
+ * - Block NEW failures (not in baseline)
+ * - Allow pre-existing failures with warning
+ * - Auto-update baseline when tests are fixed (ratchet forward)
+ *
+ * This enables agents to work on WUs without being blocked by unrelated
+ * test failures, while still preventing introduction of NEW failures.
+ *
+ * @see https://lumenflow.dev/reference/test-ratchet/
+ */
+import { z } from 'zod';
+import { parseISO, isValid } from 'date-fns';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default path for the test baseline file */
+export const DEFAULT_BASELINE_PATH = '.lumenflow/test-baseline.json';
+/** Environment variable to override baseline path */
+export const BASELINE_PATH_ENV = 'LUMENFLOW_TEST_BASELINE';
+/** Current schema version */
+export const BASELINE_VERSION = 1;
+/**
+ * Zod schema for ISO8601 datetime strings.
+ * Uses date-fns (well-maintained library) for validation instead of regex.
+ */
+const isoDateTimeString = z.string().refine((val) => {
+    const parsed = parseISO(val);
+    return isValid(parsed);
+}, { message: 'Invalid ISO8601 datetime string' });
+// ============================================================================
+// Schema Definitions
+// ============================================================================
+/**
+ * Schema for a known test failure entry
+ */
+export const KnownFailureSchema = z.object({
+    /** Name of the failing test (describe > it format) */
+    test_name: z.string().min(1),
+    /** Path to the test file */
+    file_path: z.string().min(1),
+    /** Why this failure is in the baseline */
+    failure_reason: z.string().min(1),
+    /** When this failure was added to baseline */
+    added_at: isoDateTimeString,
+    /** Which WU added this to baseline */
+    added_by_wu: z.string().regex(/^WU-\d+$/),
+    /** WU expected to fix this failure (optional) */
+    expected_fix_wu: z
+        .string()
+        .regex(/^WU-\d+$/)
+        .optional(),
+    /** Optional reason for skipping this test */
+    skip_reason: z.string().optional(),
+});
+/**
+ * Schema for baseline statistics
+ */
+export const BaselineStatsSchema = z.object({
+    /** Total number of known failures */
+    total_known_failures: z.number().int().min(0),
+    /** Last time the baseline ratcheted forward (tests fixed) */
+    last_ratchet_forward: isoDateTimeString.optional(),
+});
+/**
+ * Schema for the complete test baseline file
+ */
+export const TestBaselineSchema = z.object({
+    /** Schema version for future migrations */
+    version: z.literal(BASELINE_VERSION),
+    /** When the baseline was last updated */
+    updated_at: isoDateTimeString,
+    /** Which WU last updated the baseline */
+    updated_by: z.string().regex(/^WU-\d+$/),
+    /** List of known test failures */
+    known_failures: z.array(KnownFailureSchema),
+    /** Baseline statistics */
+    stats: BaselineStatsSchema,
+});
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * Parse a test baseline JSON string
+ *
+ * @param json - JSON string content of baseline file
+ * @returns Parse result with baseline data or error
+ */
+export function parseTestBaseline(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: `Invalid JSON: ${e instanceof Error ? e.message : 'Unknown error'}`,
+        };
+    }
+    const result = TestBaselineSchema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            success: false,
+            error: `Schema validation failed: ${result.error.message}`,
+        };
+    }
+    return { success: true, data: result.data };
+}
+/**
+ * Create a new test baseline
+ *
+ * @param wuId - WU creating the baseline
+ * @param initialFailures - Optional initial failures to add
+ * @returns New test baseline
+ */
+export function createTestBaseline(wuId, initialFailures) {
+    const now = new Date().toISOString();
+    const knownFailures = (initialFailures ?? []).map((f) => ({
+        test_name: f.test_name,
+        file_path: f.file_path,
+        failure_reason: f.failure_reason,
+        added_at: now,
+        added_by_wu: wuId,
+        expected_fix_wu: f.expected_fix_wu,
+    }));
+    return {
+        version: BASELINE_VERSION,
+        updated_at: now,
+        updated_by: wuId,
+        known_failures: knownFailures,
+        stats: {
+            total_known_failures: knownFailures.length,
+        },
+    };
+}
+/**
+ * Compare current test results against the baseline
+ *
+ * This is the core ratchet logic:
+ * - NEW failures (not in baseline) block the gate
+ * - Pre-existing failures (in baseline) show warning
+ * - Fixed tests (in baseline but now passing) trigger ratchet forward
+ *
+ * @param baseline - The test baseline
+ * @param currentFailures - Current test failures from test run
+ * @returns Comparison result
+ */
+export function compareTestResults(baseline, currentFailures) {
+    const failingTests = currentFailures.filter((t) => !t.passed);
+    // Build lookup sets for efficient comparison
+    const baselineTestNames = new Set(baseline.known_failures.map((f) => f.test_name));
+    const currentFailingNames = new Set(failingTests.map((f) => f.test_name));
+    // Find NEW failures (in current failures, NOT in baseline)
+    const newFailures = failingTests.filter((f) => !baselineTestNames.has(f.test_name));
+    // Find pre-existing failures (in current failures AND in baseline)
+    const preExistingFailures = baseline.known_failures.filter((f) => currentFailingNames.has(f.test_name));
+    // Find fixed tests (in baseline but NOT in current failures)
+    const fixedTests = baseline.known_failures.filter((f) => !currentFailingNames.has(f.test_name));
+    return {
+        newFailures,
+        preExistingFailures,
+        fixedTests,
+        shouldBlock: newFailures.length > 0,
+        hasWarnings: preExistingFailures.length > 0,
+        shouldRatchetForward: fixedTests.length > 0,
+    };
+}
+/**
+ * Update the baseline (ratchet forward or add new known failures)
+ *
+ * @param baseline - Current baseline
+ * @param wuId - WU making the update
+ * @param options - Update options
+ * @returns Updated baseline (immutable)
+ */
+export function updateBaseline(baseline, wuId, options) {
+    const now = new Date().toISOString();
+    const { fixedTests = [], newKnownFailures = [] } = options;
+    // Remove fixed tests (ratchet forward)
+    const fixedTestSet = new Set(fixedTests);
+    let knownFailures = baseline.known_failures.filter((f) => !fixedTestSet.has(f.test_name));
+    // Add new known failures
+    const newEntries = newKnownFailures.map((f) => ({
+        test_name: f.test_name,
+        file_path: f.file_path,
+        failure_reason: f.failure_reason,
+        added_at: now,
+        added_by_wu: wuId,
+        expected_fix_wu: f.expected_fix_wu,
+    }));
+    knownFailures = [...knownFailures, ...newEntries];
+    const stats = {
+        total_known_failures: knownFailures.length,
+    };
+    // Record ratchet forward if we removed tests
+    if (fixedTests.length > 0) {
+        stats.last_ratchet_forward = now;
+    }
+    return {
+        version: BASELINE_VERSION,
+        updated_at: now,
+        updated_by: wuId,
+        known_failures: knownFailures,
+        stats,
+    };
+}
+// ============================================================================
+// Formatting Functions
+// ============================================================================
+/**
+ * Format a warning message for pre-existing failures
+ *
+ * @param preExisting - Pre-existing failures from baseline
+ * @returns Formatted warning string
+ */
+export function formatBaselineWarning(preExisting) {
+    const lines = [
+        '',
+        '='.repeat(70),
+        '  Pre-existing test failures (from baseline)',
+        '='.repeat(70),
+        '',
+        `  These failures are tracked in .lumenflow/test-baseline.json`,
+        '  They do not block your WU, but should be fixed eventually.',
+        '',
+    ];
+    for (const failure of preExisting) {
+        lines.push(`  - ${failure.test_name}`);
+        lines.push(`    File: ${failure.file_path}`);
+        lines.push(`    Reason: ${failure.failure_reason}`);
+        if (failure.expected_fix_wu) {
+            lines.push(`    Expected fix: ${failure.expected_fix_wu}`);
+        }
+        lines.push('');
+    }
+    lines.push('='.repeat(70));
+    return lines.join('\n');
+}
+/**
+ * Format an error message for new failures
+ *
+ * @param newFailures - New test failures
+ * @returns Formatted error string
+ */
+export function formatNewFailureError(newFailures) {
+    const lines = [
+        '',
+        '='.repeat(70),
+        '  NEW test failure(s) detected!',
+        '='.repeat(70),
+        '',
+        '  The following tests failed and are NOT in the baseline.',
+        '  This blocks your WU from completion.',
+        '',
+        '  Options:',
+        '    1. Fix the test or add to baseline with:',
+        '       pnpm baseline:add --test "<test_name>" --reason "<why>" --fix-wu WU-XXXX',
+        '    2. If this is a pre-existing failure on main, it should be in the baseline.',
+        '',
+    ];
+    for (const failure of newFailures) {
+        lines.push(`  - ${failure.test_name}`);
+        lines.push(`    File: ${failure.file_path}`);
+        if (failure.error_message) {
+            lines.push(`    Error: ${failure.error_message.substring(0, 100)}...`);
+        }
+        lines.push('');
+    }
+    lines.push('='.repeat(70));
+    return lines.join('\n');
+}
+/**
+ * Get the path to the test baseline file
+ *
+ * @returns Baseline file path
+ */
+export function getBaselineFilePath() {
+    return process.env[BASELINE_PATH_ENV] ?? DEFAULT_BASELINE_PATH;
+}

package/dist/usecases/get-suggestions.usecase.d.ts

@@ -29,7 +29,7 @@ export interface GetSuggestionsOptions {
      * When provided, suggestions for high-impact WUs are ranked higher
      * within the same priority level.
      *
-     * @see flow-bottlenecks.mjs for score calculation
+     * @see flow-bottlenecks.ts for score calculation
      */
     bottleneckScores?: BottleneckScores;
 }

package/dist/validation/command-registry.js

@@ -92,8 +92,44 @@ const wuClaim = {
         ];
     },
 };
+/**
+ * Predicate: Check if worktree has no uncommitted changes.
+ * For wu:prep running from worktree itself.
+ */
+const gitCleanPredicate = {
+    id: 'git-clean',
+    description: 'Worktree must not have uncommitted changes',
+    severity: SEVERITY.ERROR,
+    check: (context) => !context.git.isDirty,
+    getFixMessage: () => 'Commit or stash changes in worktree before running wu:prep',
+};
+/**
+ * Command definition for wu:prep (WU-1223).
+ *
+ * Runs gates and generates docs in the worktree, then prints copy-paste
+ * instruction to run wu:done from main checkout for merge/cleanup.
+ */
+const wuPrep = {
+    name: COMMANDS.WU_PREP,
+    description: 'Run gates + docs in worktree, prepare for wu:done',
+    requiredLocation: LOCATION_TYPES.WORKTREE,
+    requiredWuStatus: WU_STATUS.IN_PROGRESS,
+    predicates: [gitCleanPredicate, stateConsistentPredicate],
+    getNextSteps: (context) => {
+        const mainPath = context.location.mainCheckout || '/path/to/main';
+        const wuId = context.wu?.id || 'WU-XXX';
+        return [
+            `1. Gates and docs generated in worktree`,
+            `2. Return to main checkout and complete:`,
+            `   cd ${mainPath} && pnpm wu:done --id ${wuId}`,
+        ];
+    },
+};
 /**
  * Command definition for wu:done.
+ *
+ * WU-1223: Now requires main checkout (merge + cleanup only).
+ * Use wu:prep from worktree for gates and docs generation.
  */
 const wuDone = {
     name: COMMANDS.WU_DONE,
@@ -161,6 +197,7 @@ const wuRecover = {
 export const COMMAND_REGISTRY = new Map([
     [COMMANDS.WU_CREATE, wuCreate],
     [COMMANDS.WU_CLAIM, wuClaim],
+    [COMMANDS.WU_PREP, wuPrep],
     [COMMANDS.WU_DONE, wuDone],
     [COMMANDS.WU_BLOCK, wuBlock],
     [COMMANDS.WU_UNBLOCK, wuUnblock],

package/dist/validators/backlog-sync.js

@@ -5,6 +5,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { FILE_SYSTEM } from '../wu-constants.js';
+import { createWuPaths } from '../wu-paths.js';
 function extractWUIDsFromBacklog(content) {
     const wuIds = [];
     const pattern = /WU-\d+/gi;
@@ -29,8 +30,9 @@ export async function validateBacklogSync(options = {}) {
     const { cwd = process.cwd() } = options;
     const errors = [];
     const warnings = [];
-    const backlogPath = path.join(cwd, 'docs', '04-operations', 'tasks', 'backlog.md');
-    const wuDir = path.join(cwd, 'docs', '04-operations', 'tasks', 'wu');
+    const paths = createWuPaths({ projectRoot: cwd });
+    const backlogPath = path.join(cwd, paths.BACKLOG());
+    const wuDir = path.join(cwd, paths.WU_DIR());
     if (!existsSync(backlogPath)) {
         errors.push(`Backlog file not found: ${backlogPath}`);
         return { valid: false, errors, warnings, wuCount: 0, backlogCount: 0 };

package/dist/worktree-scanner.d.ts

@@ -10,7 +10,7 @@
  * - Reports last activity timestamp
  * - Identifies potentially abandoned WUs
  *
- * @see {@link tools/lib/__tests__/worktree-scanner.test.mjs} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/__tests__/worktree-scanner.test.ts} - Tests
  */
 /**
  * @typedef {object} WorktreeInfo

package/dist/worktree-scanner.js

@@ -10,7 +10,7 @@
  * - Reports last activity timestamp
  * - Identifies potentially abandoned WUs
  *
- * @see {@link tools/lib/__tests__/worktree-scanner.test.mjs} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/__tests__/worktree-scanner.test.ts} - Tests
  */
 import { exec } from 'node:child_process';
 import { promisify } from 'node:util';

package/dist/worktree-symlink.d.ts

@@ -10,7 +10,7 @@
  * auto-create the node_modules symlink pointing to the main repo's
  * node_modules directory, including nested package node_modules.
  *
- * @module tools/lib/worktree-symlink.mjs
+ * @module tools/lib/worktree-symlink.ts
  */
 /**
  * List of nested package/app paths that have their own node_modules
@@ -55,7 +55,7 @@ export declare function hasWorktreePathSymlinks(nodeModulesPath: any): {
  * @returns {{created: boolean, skipped: boolean, refused?: boolean, reason?: string, error?: Error}}
  *
  * @example
- * // In wu-claim.mjs after worktree creation:
+ * // In wu-claim.ts after worktree creation:
  * symlinkNodeModules('/path/to/worktrees/operations-tooling-wu-1443');
  */
 export declare function symlinkNodeModules(worktreePath: any, logger?: Console, mainRepoPath?: any): {
@@ -90,7 +90,7 @@ export declare function symlinkNodeModules(worktreePath: any, logger?: Console,
  * @returns {{created: number, skipped: number, errors: Error[]}}
  *
  * @example
- * // In wu-claim.mjs after worktree creation:
+ * // In wu-claim.ts after worktree creation:
  * symlinkNestedNodeModules(
  *   '/path/to/worktrees/operations-tooling-wu-1579',
  *   '/path/to/main-repo'

package/dist/worktree-symlink.js

@@ -10,7 +10,7 @@
  * auto-create the node_modules symlink pointing to the main repo's
  * node_modules directory, including nested package node_modules.
  *
- * @module tools/lib/worktree-symlink.mjs
+ * @module tools/lib/worktree-symlink.ts
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -202,7 +202,7 @@ function checkMainNodeModulesHealth(mainRepoPath, logger) {
  * @returns {{created: boolean, skipped: boolean, refused?: boolean, reason?: string, error?: Error}}
  *
  * @example
- * // In wu-claim.mjs after worktree creation:
+ * // In wu-claim.ts after worktree creation:
  * symlinkNodeModules('/path/to/worktrees/operations-tooling-wu-1443');
  */
 export function symlinkNodeModules(worktreePath, logger = console, mainRepoPath = null) {
@@ -310,7 +310,7 @@ function handleExistingNestedNodeModules(targetNodeModules, pkgPath, logger, err
  * @returns {{created: number, skipped: number, errors: Error[]}}
  *
  * @example
- * // In wu-claim.mjs after worktree creation:
+ * // In wu-claim.ts after worktree creation:
  * symlinkNestedNodeModules(
  *   '/path/to/worktrees/operations-tooling-wu-1579',
  *   '/path/to/main-repo'

package/dist/wu-backlog-updater.d.ts

@@ -1,7 +1,7 @@
 /**
  * Backlog.md Update Utilities
  *
- * Centralized backlog.md update functions (extracted from wu-done.mjs)
+ * Centralized backlog.md update functions (extracted from wu-done.ts)
  * Refactored to use BacklogManager (WU-1212) for AST-based manipulation
  *
  * Used by both main wu:done flow AND recovery mode (DRY principle)

package/dist/wu-backlog-updater.js

@@ -1,7 +1,7 @@
 /**
  * Backlog.md Update Utilities
  *
- * Centralized backlog.md update functions (extracted from wu-done.mjs)
+ * Centralized backlog.md update functions (extracted from wu-done.ts)
  * Refactored to use BacklogManager (WU-1212) for AST-based manipulation
  *
  * Used by both main wu:done flow AND recovery mode (DRY principle)

package/dist/wu-claim-helpers.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file wu-claim-helpers.mjs
+ * @file wu-claim-helpers.ts
  * Helper functions for wu:claim (WU-1423)
  *
  * Extracted email validation logic for testability and SOLID compliance.

package/dist/wu-claim-helpers.js

@@ -1,5 +1,5 @@
 /**
- * @file wu-claim-helpers.mjs
+ * @file wu-claim-helpers.ts
  * Helper functions for wu:claim (WU-1423)
  *
  * Extracted email validation logic for testability and SOLID compliance.

package/dist/wu-claim-resume.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file wu-claim-resume.mjs
+ * @file wu-claim-resume.ts
  * Helper functions for wu:claim --resume agent handoff (WU-2411)
  *
  * When an agent crashes or is killed, its worktree remains with uncommitted work.

package/dist/wu-claim-resume.js

@@ -1,5 +1,5 @@
 /**
- * @file wu-claim-resume.mjs
+ * @file wu-claim-resume.ts
  * Helper functions for wu:claim --resume agent handoff (WU-2411)
  *
  * When an agent crashes or is killed, its worktree remains with uncommitted work.

package/dist/wu-consistency-checker.d.ts

@@ -10,7 +10,7 @@
  * - ORPHAN_WORKTREE_DONE: Done WU still has worktree
  * - STAMP_EXISTS_YAML_NOT_DONE: Stamp exists but YAML status is not done (WU-2412)
  *
- * @see {@link ../wu-repair.mjs} CLI interface
+ * @see {@link ../wu-repair.ts} CLI interface
  */
 /**
  * Check a single WU for state inconsistencies

package/dist/wu-consistency-checker.js

@@ -10,13 +10,13 @@
  * - ORPHAN_WORKTREE_DONE: Done WU still has worktree
  * - STAMP_EXISTS_YAML_NOT_DONE: Stamp exists but YAML status is not done (WU-2412)
  *
- * @see {@link ../wu-repair.mjs} CLI interface
+ * @see {@link ../wu-repair.ts} CLI interface
  */
 import { readFile, writeFile, readdir, mkdir, access } from 'node:fs/promises';
 import { constants, existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parseYAML, stringifyYAML } from './wu-yaml.js';
-import { WU_PATHS } from './wu-paths.js';
+import { createWuPaths, WU_PATHS } from './wu-paths.js';
 import { CONSISTENCY_TYPES, CONSISTENCY_MESSAGES, LOG_PREFIX, REMOTES, STRING_LITERALS, toKebab, WU_STATUS, YAML_OPTIONS, } from './wu-constants.js';
 import { todayISO } from './date-utils.js';
 import { createGitForPath } from './git-adapter.js';
@@ -30,10 +30,11 @@ import { withMicroWorktree } from './micro-worktree.js';
  */
 export async function checkWUConsistency(id, projectRoot = process.cwd()) {
     const errors = [];
-    const wuPath = path.join(projectRoot, WU_PATHS.WU(id));
-    const stampPath = path.join(projectRoot, WU_PATHS.STAMP(id));
-    const backlogPath = path.join(projectRoot, WU_PATHS.BACKLOG());
-    const statusPath = path.join(projectRoot, WU_PATHS.STATUS());
+    const paths = createWuPaths({ projectRoot });
+    const wuPath = path.join(projectRoot, paths.WU(id));
+    const stampPath = path.join(projectRoot, paths.STAMP(id));
+    const backlogPath = path.join(projectRoot, paths.BACKLOG());
+    const statusPath = path.join(projectRoot, paths.STATUS());
     // Handle missing WU YAML gracefully
     try {
         await access(wuPath, constants.R_OK);
@@ -166,7 +167,8 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
  * @returns {Promise<object>} Aggregated report with valid, errors, and checked count
  */
 export async function checkAllWUConsistency(projectRoot = process.cwd()) {
-    const wuDir = path.join(projectRoot, 'docs/04-operations/tasks/wu');
+    const paths = createWuPaths({ projectRoot });
+    const wuDir = path.join(projectRoot, paths.WU_DIR());
     try {
         await access(wuDir, constants.R_OK);
     }
@@ -195,7 +197,8 @@ export async function checkAllWUConsistency(projectRoot = process.cwd()) {
  * @returns {Promise<object>} Result with valid, orphans list, and reports
  */
 export async function checkLaneForOrphanDoneWU(lane, excludeId, projectRoot = process.cwd()) {
-    const wuDir = path.join(projectRoot, 'docs/04-operations/tasks/wu');
+    const paths = createWuPaths({ projectRoot });
+    const wuDir = path.join(projectRoot, paths.WU_DIR());
     try {
         await access(wuDir, constants.R_OK);
     }
@@ -486,7 +489,8 @@ async function createStampInProject(id, title, projectRoot) {
  * @returns {Promise<string[]>} List of files modified (relative paths)
  */
 async function updateYamlToDoneInWorktree(id, worktreePath, projectRoot) {
-    const wuRelPath = WU_PATHS.WU(id);
+    const paths = createWuPaths({ projectRoot });
+    const wuRelPath = paths.WU(id);
     const wuSrcPath = path.join(projectRoot, wuRelPath);
     const wuDestPath = path.join(worktreePath, wuRelPath);
     // Read current YAML from project root
@@ -522,7 +526,8 @@ async function updateYamlToDoneInWorktree(id, worktreePath, projectRoot) {
  * @returns {Promise<void>}
  */
 async function updateYamlToDone(id, projectRoot) {
-    const wuPath = path.join(projectRoot, WU_PATHS.WU(id));
+    const paths = createWuPaths({ projectRoot });
+    const wuPath = path.join(projectRoot, paths.WU(id));
     // Read current YAML
     const content = await readFile(wuPath, { encoding: 'utf-8' });
     const wuDoc = parseYAML(content);
@@ -690,7 +695,8 @@ async function removeOrphanWorktree(id, lane, projectRoot) {
         // Worktree doesn't exist, that's fine
     }
     // 🚨 SAFETY GUARD 3: Check stamp exists (not rollback state)
-    const stampPath = path.join(projectRoot, WU_PATHS.STAMP(id));
+    const paths = createWuPaths({ projectRoot });
+    const stampPath = path.join(projectRoot, paths.STAMP(id));
     try {
         await access(stampPath, constants.R_OK);
     }