@lumenflow/core 1.0.0

package/dist/backlog-parser.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Parse YAML frontmatter from backlog.md
+ * @param {string} backlogPath - Path to backlog.md file
+ * @returns {{frontmatter: object|null, markdown: string}} Parsed frontmatter and markdown body
+ * @throws {Error} If file not found or YAML parsing fails
+ */
+export declare function parseBacklogFrontmatter(backlogPath: any): {
+    frontmatter: {
+        [key: string]: any;
+    };
+    markdown: string;
+};
+/**
+ * Section configuration from frontmatter
+ */
+interface SectionConfig {
+    heading?: string;
+}
+/**
+ * Backlog frontmatter structure
+ */
+interface BacklogFrontmatter {
+    sections?: Record<string, SectionConfig>;
+}
+/**
+ * Section boundary definition
+ */
+interface SectionBoundary {
+    start: number;
+    end: number | null;
+}
+/**
+ * Extract section headings from frontmatter
+ * @param {object|null} frontmatter - Parsed frontmatter object
+ * @returns {object} Map of section names to heading strings (e.g., {ready: "## 🚀 Ready"})
+ */
+export declare function getSectionHeadings(frontmatter: BacklogFrontmatter | null): Record<string, string>;
+/**
+ * Find section boundaries in backlog content
+ * @param {string[]} lines - Lines of backlog content
+ * @param {object|null} frontmatter - Parsed frontmatter object
+ * @returns {object} Map of section names to {start, end} boundary indices
+ */
+export declare function findSectionBoundaries(lines: string[], frontmatter: BacklogFrontmatter | null): Record<string, SectionBoundary | null>;
+export {};

package/dist/backlog-parser.js

@@ -0,0 +1,102 @@
+/**
+ * Backlog Parser (WU-1065, WU-1211)
+ * Shared module for parsing YAML frontmatter in backlog.md
+ * Uses gray-matter library for robust frontmatter parsing
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import matter from 'gray-matter';
+import yaml from 'yaml';
+import { createError, ErrorCodes } from './error-handler.js';
+/**
+ * Parse YAML frontmatter from backlog.md
+ * @param {string} backlogPath - Path to backlog.md file
+ * @returns {{frontmatter: object|null, markdown: string}} Parsed frontmatter and markdown body
+ * @throws {Error} If file not found or YAML parsing fails
+ */
+export function parseBacklogFrontmatter(backlogPath) {
+    if (!existsSync(backlogPath)) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Backlog not found: ${backlogPath}`, {
+            path: backlogPath,
+        });
+    }
+    const content = readFileSync(backlogPath, { encoding: 'utf-8' });
+    try {
+        // Configure gray-matter to use modern yaml library instead of deprecated js-yaml
+        const { data, content: markdown } = matter(content, {
+            engines: {
+                yaml: {
+                    parse: yaml.parse.bind(yaml),
+                    stringify: yaml.stringify.bind(yaml),
+                },
+            },
+        });
+        // gray-matter returns {} for no frontmatter; normalize to null for consistency
+        const frontmatter = Object.keys(data).length > 0 ? data : null;
+        return { frontmatter, markdown };
+    }
+    catch (err) {
+        throw createError(ErrorCodes.YAML_PARSE_ERROR, `Failed to parse frontmatter in ${backlogPath}:\n\n${err.message}\n\n` +
+            `Ensure frontmatter is valid YAML between --- delimiters.`, { path: backlogPath, originalError: err.message });
+    }
+}
+/**
+ * Extract section headings from frontmatter
+ * @param {object|null} frontmatter - Parsed frontmatter object
+ * @returns {object} Map of section names to heading strings (e.g., {ready: "## 🚀 Ready"})
+ */
+export function getSectionHeadings(frontmatter) {
+    if (!frontmatter || !frontmatter.sections) {
+        return {};
+    }
+    const headings = {};
+    for (const [sectionName, sectionConfig] of Object.entries(frontmatter.sections)) {
+        if (sectionConfig.heading) {
+            headings[sectionName] = sectionConfig.heading;
+        }
+    }
+    return headings;
+}
+/**
+ * Find section boundaries in backlog content
+ * @param {string[]} lines - Lines of backlog content
+ * @param {object|null} frontmatter - Parsed frontmatter object
+ * @returns {object} Map of section names to {start, end} boundary indices
+ */
+export function findSectionBoundaries(lines, frontmatter) {
+    if (!frontmatter || !frontmatter.sections) {
+        return {};
+    }
+    const headings = getSectionHeadings(frontmatter);
+    const boundaries = {};
+    // Initialize all sections as null (not found)
+    for (const sectionName of Object.keys(headings)) {
+        boundaries[sectionName] = null;
+    }
+    // Find start indices for each section (exact match)
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const [sectionName, heading] of Object.entries(headings)) {
+            if (line === heading) {
+                boundaries[sectionName] = { start: i, end: null };
+            }
+        }
+    }
+    // Calculate end indices (last line before next section or EOF)
+    const sectionStarts = Object.values(boundaries)
+        .filter((b) => b !== null)
+        .map((b) => b.start)
+        .sort((a, b) => a - b);
+    for (const boundary of Object.values(boundaries)) {
+        if (boundary === null)
+            continue;
+        const currentStart = boundary.start;
+        const nextStart = sectionStarts.find((s) => s > currentStart);
+        if (nextStart !== undefined) {
+            boundary.end = nextStart - 1;
+        }
+        else {
+            boundary.end = lines.length - 1;
+        }
+    }
+    return boundaries;
+}

package/dist/backlog-sync-validator.d.ts

@@ -0,0 +1,78 @@
+export declare function validateBacklogSync(backlogPath: any): {
+    valid: boolean;
+    errors: any[];
+    stats?: undefined;
+} | {
+    valid: boolean;
+    errors: any[];
+    stats: {
+        ready: number;
+        inProgress: number;
+        blocked: number;
+        done: number;
+        duplicates: number;
+        parentOnlyInReady: number;
+    };
+};
+/**
+ * Options for fixing backlog duplicates
+ */
+export interface FixBacklogDuplicatesOptions {
+    /** If true, report changes without writing */
+    dryRun?: boolean;
+    /** If true, return fixed content without writing (WU-1506) */
+    returnContent?: boolean;
+}
+/**
+ * Fix backlog duplicates by removing WUs from non-authoritative sections
+ * - If WU in Done AND Ready: remove from Ready (Done is authoritative)
+ * - If WU in Done AND InProgress: remove from InProgress (Done is authoritative)
+ *
+ * Part of WU-1303: Backlog duplicate entries after rebase conflicts
+ * WU-1506: Added returnContent option for atomic in-memory validation
+ *
+ * @param {string} backlogPath - Path to backlog.md file
+ * @param {FixBacklogDuplicatesOptions} options - Fix options
+ * @returns {{fixed: boolean, removed: Array<{wu: string, section: string}>, backupPath?: string, content?: string}}
+ */
+export declare function fixBacklogDuplicates(backlogPath: any, options?: FixBacklogDuplicatesOptions): {
+    fixed: boolean;
+    removed: any[];
+    error: any;
+    message?: undefined;
+    content?: undefined;
+    dryRun?: undefined;
+    backupPath?: undefined;
+} | {
+    fixed: boolean;
+    removed: any[];
+    message: string;
+    error?: undefined;
+    content?: undefined;
+    dryRun?: undefined;
+    backupPath?: undefined;
+} | {
+    fixed: boolean;
+    removed: any[];
+    content: string;
+    message: string;
+    error?: undefined;
+    dryRun?: undefined;
+    backupPath?: undefined;
+} | {
+    fixed: boolean;
+    removed: any[];
+    dryRun: boolean;
+    message: string;
+    error?: undefined;
+    content?: undefined;
+    backupPath?: undefined;
+} | {
+    fixed: boolean;
+    removed: any[];
+    backupPath: string;
+    message: string;
+    error?: undefined;
+    content?: undefined;
+    dryRun?: undefined;
+};

package/dist/backlog-sync-validator.js

@@ -0,0 +1,294 @@
+/**
+ * Backlog Sync Validator (WU-672, WU-1065, WU-1137, WU-1303)
+ * Detects WUs present in multiple sections (Done+Ready, Done+InProgress, etc.)
+ * Uses frontmatter-driven section detection (WU-1065) instead of brittle string matching
+ * Flags parent-only WUs in Ready section (WU-1137) - sub-lane format is preferred
+ * Supports --fix mode to automatically remove duplicates (WU-1303)
+ */
+import { readFileSync, writeFileSync, existsSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { parseBacklogFrontmatter, getSectionHeadings } from './backlog-parser.js';
+import { extractParent } from './lane-checker.js';
+import { CONFIG_FILES, STRING_LITERALS, getProjectRoot, } from './wu-constants.js';
+/**
+ * Check if parent lane has sub-lane taxonomy in .lumenflow.lane-inference.yaml
+ * @param {string} parent - Parent lane name
+ * @param {string} projectRoot - Path to project root
+ * @returns {boolean} True if parent has sub-lanes defined
+ */
+function hasSubLaneTaxonomy(parent, projectRoot) {
+    const taxonomyPath = path.join(projectRoot, CONFIG_FILES.LANE_INFERENCE);
+    if (!existsSync(taxonomyPath)) {
+        return false;
+    }
+    try {
+        const taxonomyContent = readFileSync(taxonomyPath, { encoding: 'utf-8' });
+        const taxonomy = yaml.load(taxonomyContent);
+        const normalizedParent = parent.trim().toLowerCase();
+        return Object.keys(taxonomy).some((key) => key.toLowerCase().trim() === normalizedParent);
+    }
+    catch {
+        // If taxonomy file is malformed, assume no taxonomy (fail safe)
+        return false;
+    }
+}
+export function validateBacklogSync(backlogPath) {
+    // Parse frontmatter to get configured section headings
+    let frontmatter, markdown;
+    try {
+        ({ frontmatter, markdown } = parseBacklogFrontmatter(backlogPath));
+    }
+    catch (err) {
+        return { valid: false, errors: [err.message] };
+    }
+    // If no frontmatter, fall back to empty sections (backlog without frontmatter is valid)
+    const headings = frontmatter ? getSectionHeadings(frontmatter) : {};
+    const lines = markdown.split(/\r?\n/);
+    // Parse sections using frontmatter headings
+    const sections = {
+        ready: new Set(),
+        in_progress: new Set(),
+        blocked: new Set(),
+        done: new Set(),
+    };
+    let currentSection = null;
+    // Build heading-to-section map for efficient lookup
+    const headingMap = new Map();
+    for (const [sectionName, heading] of Object.entries(headings)) {
+        headingMap.set(heading, sectionName);
+    }
+    // WU-1334: Pattern to match WU IDs only in backlog list items
+    // Matches lines starting with:
+    // - `- WU-123` (bullet list)
+    // - `* WU-123` (asterisk list)
+    // - `- [ ] WU-123` (unchecked checkbox)
+    // - `- [x] WU-123` (checked checkbox)
+    // - `- [WU-123 - title](...)` (markdown link)
+    // Does NOT match prose like "See WU-123 for details" or "WU-123 → WU-124"
+    const BACKLOG_ITEM_PATTERN = /^\s*[-*]\s*(?:\[[ x]\]\s*)?\[?(WU-\d+)/i;
+    for (const line of lines) {
+        // Check if line matches any configured section heading (exact match)
+        if (headingMap.has(line)) {
+            currentSection = headingMap.get(line);
+            continue;
+        }
+        // Reset section when encountering other ## headings (not subsections ###)
+        if (line.trim().startsWith('## ') && !line.trim().startsWith('### ')) {
+            currentSection = null;
+            continue;
+        }
+        if (currentSection) {
+            const match = line.match(BACKLOG_ITEM_PATTERN);
+            if (match) {
+                sections[currentSection].add(match[1].toUpperCase());
+            }
+        }
+    }
+    // Detect duplicates
+    const errors = [];
+    // Done + Ready
+    const doneAndReady = [...sections.done].filter((wu) => sections.ready.has(wu));
+    if (doneAndReady.length > 0) {
+        errors.push(`❌ ${doneAndReady.length} WU(s) are in BOTH Done and Ready sections:${STRING_LITERALS.NEWLINE}${doneAndReady
+            .map((wu) => `   - ${wu}`)
+            .join(STRING_LITERALS.NEWLINE)}${STRING_LITERALS.DOUBLE_NEWLINE}` +
+            `   Fix: Remove from Ready section (they are already complete)${STRING_LITERALS.NEWLINE}` +
+            `   Command: Edit docs/04-operations/tasks/backlog.md and remove duplicate entries`);
+    }
+    // Done + In Progress (should never happen, but check anyway)
+    const doneAndInProgress = [...sections.done].filter((wu) => sections.in_progress.has(wu));
+    if (doneAndInProgress.length > 0) {
+        errors.push(`❌ ${doneAndInProgress.length} WU(s) are in BOTH Done and In Progress sections:${STRING_LITERALS.NEWLINE}${doneAndInProgress
+            .map((wu) => `   - ${wu}`)
+            .join(STRING_LITERALS.NEWLINE)}${STRING_LITERALS.DOUBLE_NEWLINE}` +
+            `   Fix: Remove from In Progress section (they are already complete)${STRING_LITERALS.NEWLINE}` +
+            `   Or: If reopened, remove from Done and update WU YAML status to in_progress`);
+    }
+    // Ready + In Progress (legitimate during claim, but flag for awareness)
+    const readyAndInProgress = [...sections.ready].filter((wu) => sections.in_progress.has(wu));
+    if (readyAndInProgress.length > 0) {
+        errors.push(`⚠️  ${readyAndInProgress.length} WU(s) are in BOTH Ready and In Progress sections:${STRING_LITERALS.NEWLINE}${readyAndInProgress
+            .map((wu) => `   - ${wu}`)
+            .join(STRING_LITERALS.NEWLINE)}${STRING_LITERALS.DOUBLE_NEWLINE}` +
+            `   This is normal during wu:claim before commit.${STRING_LITERALS.NEWLINE}` +
+            `   If you see this error after commit, wu:claim did not remove from Ready.${STRING_LITERALS.NEWLINE}` +
+            `   Fix: Remove from Ready section`);
+    }
+    // WU-1137: Check for parent-only WUs in Ready section (sub-lane format preferred)
+    const projectRoot = getProjectRoot(import.meta.url);
+    const wuDir = path.join(path.dirname(backlogPath), 'wu');
+    const parentOnlyWUs = [];
+    for (const wuId of sections.ready) {
+        const wuPath = path.join(wuDir, `${wuId}.yaml`);
+        if (!existsSync(wuPath)) {
+            continue; // Skip missing WU files (handled by other validators)
+        }
+        try {
+            const wuContent = readFileSync(wuPath, { encoding: 'utf-8' });
+            const wuDoc = yaml.load(wuContent);
+            if (wuDoc && wuDoc.lane) {
+                const lane = wuDoc.lane.toString().trim();
+                const hasColon = lane.includes(':');
+                // If parent-only format (no colon) and parent has sub-lane taxonomy, flag it
+                if (!hasColon) {
+                    const parent = extractParent(lane);
+                    if (hasSubLaneTaxonomy(parent, projectRoot)) {
+                        parentOnlyWUs.push({ wuId, lane, parent });
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip WU files that can't be parsed (handled by other validators)
+            continue;
+        }
+    }
+    if (parentOnlyWUs.length > 0) {
+        errors.push(`⚠️  ${parentOnlyWUs.length} WU(s) in Ready section use parent-only lane format (sub-lane format preferred):${STRING_LITERALS.NEWLINE}${parentOnlyWUs
+            .map((wu) => `   - ${wu.wuId}: "${wu.lane}" (parent has sub-lanes)`)
+            .join(STRING_LITERALS.NEWLINE)}${STRING_LITERALS.DOUBLE_NEWLINE}` +
+            `   Fix: Migrate to sub-lane format using:${STRING_LITERALS.NEWLINE}` +
+            `        pnpm wu:infer-lane --id WU-123     # Suggest a sub-lane${STRING_LITERALS.NEWLINE}` +
+            `        pnpm wu:edit --id WU-123 --lane "Parent: Sub"${STRING_LITERALS.NEWLINE}` +
+            `   See: docs/04-operations/_frameworks/lumenflow/sub-lanes.md`);
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        stats: {
+            ready: sections.ready.size,
+            inProgress: sections.in_progress.size,
+            blocked: sections.blocked.size,
+            done: sections.done.size,
+            duplicates: doneAndReady.length + doneAndInProgress.length + readyAndInProgress.length,
+            parentOnlyInReady: parentOnlyWUs.length,
+        },
+    };
+}
+/**
+ * Fix backlog duplicates by removing WUs from non-authoritative sections
+ * - If WU in Done AND Ready: remove from Ready (Done is authoritative)
+ * - If WU in Done AND InProgress: remove from InProgress (Done is authoritative)
+ *
+ * Part of WU-1303: Backlog duplicate entries after rebase conflicts
+ * WU-1506: Added returnContent option for atomic in-memory validation
+ *
+ * @param {string} backlogPath - Path to backlog.md file
+ * @param {FixBacklogDuplicatesOptions} options - Fix options
+ * @returns {{fixed: boolean, removed: Array<{wu: string, section: string}>, backupPath?: string, content?: string}}
+ */
+export function fixBacklogDuplicates(backlogPath, options = {}) {
+    const { dryRun = false, returnContent = false } = options;
+    // Parse frontmatter to get configured section headings
+    let frontmatter, markdown;
+    try {
+        ({ frontmatter, markdown } = parseBacklogFrontmatter(backlogPath));
+    }
+    catch (err) {
+        return { fixed: false, removed: [], error: err.message };
+    }
+    const headings = frontmatter ? getSectionHeadings(frontmatter) : {};
+    const lines = markdown.split(/\r?\n/);
+    // Track section boundaries and WU locations
+    const sections = {
+        ready: { wus: new Set(), lineNumbers: new Map() },
+        in_progress: { wus: new Set(), lineNumbers: new Map() },
+        blocked: { wus: new Set(), lineNumbers: new Map() },
+        done: { wus: new Set(), lineNumbers: new Map() },
+    };
+    let currentSection = null;
+    // Build heading-to-section map
+    const headingMap = new Map();
+    for (const [sectionName, heading] of Object.entries(headings)) {
+        headingMap.set(heading, sectionName);
+    }
+    // WU-1334: Same pattern as validateBacklogSync - only match list items
+    const BACKLOG_ITEM_PATTERN = /^\s*[-*]\s*(?:\[[ x]\]\s*)?\[?(WU-\d+)/i;
+    // Parse sections and track line numbers for each WU
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (headingMap.has(line)) {
+            currentSection = headingMap.get(line);
+            continue;
+        }
+        // Reset section on other ## headings
+        if (line.trim().startsWith('## ') && !line.trim().startsWith('### ')) {
+            currentSection = null;
+            continue;
+        }
+        if (currentSection && sections[currentSection]) {
+            const match = line.match(BACKLOG_ITEM_PATTERN);
+            if (match) {
+                const wuId = match[1].toUpperCase();
+                sections[currentSection].wus.add(wuId);
+                // Store line number (can have multiple lines per WU, but we just need one to identify the entry)
+                if (!sections[currentSection].lineNumbers.has(wuId)) {
+                    sections[currentSection].lineNumbers.set(wuId, i);
+                }
+            }
+        }
+    }
+    // Find duplicates that need removal
+    const linesToRemove = new Set();
+    const removed = [];
+    // Done + Ready: remove from Ready
+    for (const wu of sections.done.wus) {
+        if (sections.ready.wus.has(wu)) {
+            const lineNum = sections.ready.lineNumbers.get(wu);
+            if (lineNum !== undefined) {
+                linesToRemove.add(lineNum);
+                removed.push({ wu, section: 'ready' });
+            }
+        }
+    }
+    // Done + InProgress: remove from InProgress
+    for (const wu of sections.done.wus) {
+        if (sections.in_progress.wus.has(wu)) {
+            const lineNum = sections.in_progress.lineNumbers.get(wu);
+            if (lineNum !== undefined) {
+                linesToRemove.add(lineNum);
+                removed.push({ wu, section: 'in_progress' });
+            }
+        }
+    }
+    // No duplicates to fix
+    if (removed.length === 0) {
+        return { fixed: false, removed: [], message: 'No duplicates found' };
+    }
+    // Remove duplicate lines (filter out the lines to remove)
+    const newLines = lines.filter((_, index) => !linesToRemove.has(index));
+    // Reconstruct file with frontmatter
+    const originalContent = readFileSync(backlogPath, { encoding: 'utf-8' });
+    const frontmatterMatch = originalContent.match(/^---\n[\s\S]*?\n---\n/);
+    const frontmatterContent = frontmatterMatch ? frontmatterMatch[0] : STRING_LITERALS.EMPTY;
+    const newContent = frontmatterContent + newLines.join(STRING_LITERALS.NEWLINE);
+    // WU-1506: Return content without writing when returnContent is true
+    if (returnContent) {
+        return {
+            fixed: true,
+            removed,
+            content: newContent,
+            message: `Would remove ${removed.length} duplicate(s)`,
+        };
+    }
+    // Dry run - report what would change
+    if (dryRun) {
+        return {
+            fixed: false,
+            removed,
+            dryRun: true,
+            message: `Would remove ${removed.length} duplicate(s)`,
+        };
+    }
+    // Create backup before modifying
+    const backupPath = `${backlogPath}.bak`;
+    copyFileSync(backlogPath, backupPath);
+    writeFileSync(backlogPath, newContent, { encoding: 'utf-8' });
+    return {
+        fixed: true,
+        removed,
+        backupPath,
+        message: `Removed ${removed.length} duplicate(s). Backup at ${backupPath}`,
+    };
+}

package/dist/branch-drift.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Branch drift detection and graduated warning system
+ *
+ * WU-1370: Graduated warnings for branch drift
+ * - < 10 commits behind: OK (no message)
+ * - 10-14 commits behind: INFO ("Consider rebasing")
+ * - 15-19 commits behind: WARNING ("Rebase recommended")
+ * - >= 20 commits behind: ERROR (hard block, "Must rebase")
+ *
+ * @see {@link THRESHOLDS} for configurable threshold values
+ */
+/**
+ * Drift level constants
+ * Used as return values from getDriftLevel()
+ */
+export declare const DRIFT_LEVELS: {
+    OK: string;
+    INFO: string;
+    WARNING: string;
+    ERROR: string;
+};
+/**
+ * Calculate drift level based on number of commits behind main
+ *
+ * @param {number} commitsBehind - Number of commits behind main (from git rev-list --count)
+ * @returns {'ok' | 'info' | 'warning' | 'error'} Drift severity level
+ *
+ * @example
+ * getDriftLevel(5)   // 'ok' - no warning needed
+ * getDriftLevel(10)  // 'info' - suggest rebasing
+ * getDriftLevel(15)  // 'warning' - recommend rebasing
+ * getDriftLevel(20)  // 'error' - hard block, must rebase
+ */
+export declare function getDriftLevel(commitsBehind: any): string;

package/dist/branch-drift.js

@@ -0,0 +1,51 @@
+/**
+ * Branch drift detection and graduated warning system
+ *
+ * WU-1370: Graduated warnings for branch drift
+ * - < 10 commits behind: OK (no message)
+ * - 10-14 commits behind: INFO ("Consider rebasing")
+ * - 15-19 commits behind: WARNING ("Rebase recommended")
+ * - >= 20 commits behind: ERROR (hard block, "Must rebase")
+ *
+ * @see {@link THRESHOLDS} for configurable threshold values
+ */
+import { THRESHOLDS } from './wu-constants.js';
+/**
+ * Drift level constants
+ * Used as return values from getDriftLevel()
+ */
+export const DRIFT_LEVELS = {
+    OK: 'ok',
+    INFO: 'info',
+    WARNING: 'warning',
+    ERROR: 'error',
+};
+/**
+ * Calculate drift level based on number of commits behind main
+ *
+ * @param {number} commitsBehind - Number of commits behind main (from git rev-list --count)
+ * @returns {'ok' | 'info' | 'warning' | 'error'} Drift severity level
+ *
+ * @example
+ * getDriftLevel(5)   // 'ok' - no warning needed
+ * getDriftLevel(10)  // 'info' - suggest rebasing
+ * getDriftLevel(15)  // 'warning' - recommend rebasing
+ * getDriftLevel(20)  // 'error' - hard block, must rebase
+ */
+export function getDriftLevel(commitsBehind) {
+    // Handle edge cases: negative or non-integer values
+    const commits = Math.floor(commitsBehind);
+    if (commits < 0) {
+        return DRIFT_LEVELS.OK;
+    }
+    if (commits >= THRESHOLDS.BRANCH_DRIFT_MAX) {
+        return DRIFT_LEVELS.ERROR;
+    }
+    if (commits >= THRESHOLDS.BRANCH_DRIFT_WARNING) {
+        return DRIFT_LEVELS.WARNING;
+    }
+    if (commits >= THRESHOLDS.BRANCH_DRIFT_INFO) {
+        return DRIFT_LEVELS.INFO;
+    }
+    return DRIFT_LEVELS.OK;
+}

package/dist/cleanup-install-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WU-2278: Cleanup Install Configuration
+ *
+ * Provides configuration for pnpm install during wu:done cleanup.
+ * - 60 second timeout to prevent indefinite hangs
+ * - CI=true for non-interactive mode
+ * - frozen-lockfile to prevent lockfile mutations
+ *
+ * @module cleanup-install-config
+ */
+/**
+ * Timeout for cleanup install operation (ms)
+ * @constant {number}
+ */
+export declare const CLEANUP_INSTALL_TIMEOUT_MS = 60000;
+/**
+ * Get configuration for cleanup pnpm install
+ *
+ * Returns command and options suitable for execAsync:
+ * - CI=true environment variable for non-interactive mode
+ * - 60 second timeout to prevent hangs
+ * - frozen-lockfile flag to prevent mutations
+ *
+ * @returns {{ command: string, timeout: number, env: object }}
+ */
+export declare function getCleanupInstallConfig(): {
+    command: string;
+    timeout: number;
+    env: {
+        CI: string;
+        TZ?: string | undefined;
+    };
+};

package/dist/cleanup-install-config.js

@@ -0,0 +1,37 @@
+/**
+ * WU-2278: Cleanup Install Configuration
+ *
+ * Provides configuration for pnpm install during wu:done cleanup.
+ * - 60 second timeout to prevent indefinite hangs
+ * - CI=true for non-interactive mode
+ * - frozen-lockfile to prevent lockfile mutations
+ *
+ * @module cleanup-install-config
+ */
+import { PKG_MANAGER, PKG_COMMANDS, PKG_FLAGS } from './wu-constants.js';
+/**
+ * Timeout for cleanup install operation (ms)
+ * @constant {number}
+ */
+export const CLEANUP_INSTALL_TIMEOUT_MS = 60000; // 60 seconds
+/**
+ * Get configuration for cleanup pnpm install
+ *
+ * Returns command and options suitable for execAsync:
+ * - CI=true environment variable for non-interactive mode
+ * - 60 second timeout to prevent hangs
+ * - frozen-lockfile flag to prevent mutations
+ *
+ * @returns {{ command: string, timeout: number, env: object }}
+ */
+export function getCleanupInstallConfig() {
+    const command = `${PKG_MANAGER} ${PKG_COMMANDS.INSTALL} ${PKG_FLAGS.FROZEN_LOCKFILE}`;
+    return {
+        command,
+        timeout: CLEANUP_INSTALL_TIMEOUT_MS,
+        env: {
+            ...process.env,
+            CI: 'true', // Non-interactive mode
+        },
+    };
+}