@lumenflow/core 1.0.0

package/dist/rollback-utils.d.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Rollback Utilities for WU Tooling
+ *
+ * WU-1255: Per-file error tracking for robust rollback operations.
+ * Ensures all files are attempted even if some fail, with clear error reporting.
+ *
+ * @see {@link tools/wu-done.mjs} - Consumer (rollbackTransaction function)
+ */
+/**
+ * Error entry for failed file restoration
+ */
+interface RollbackError {
+    name: string;
+    path: string;
+    error: string;
+}
+/**
+ * Result of a rollback operation.
+ * Tracks which files were restored and which failed.
+ *
+ * @class
+ */
+export declare class RollbackResult {
+    /** Names of successfully restored files */
+    restored: string[];
+    /** Failed file restorations */
+    errors: RollbackError[];
+    constructor();
+    /**
+     * Record a successful file restoration.
+     * @param {string} name - File identifier (e.g., 'backlog.md')
+     */
+    addSuccess(name: any): void;
+    /**
+     * Record a failed file restoration.
+     * @param {string} name - File identifier
+     * @param {string} path - Full file path
+     * @param {string} error - Error message
+     */
+    addError(name: any, path: any, error: any): void;
+    /**
+     * Check if all files were restored successfully.
+     * @returns {boolean} True if no errors occurred
+     */
+    get success(): boolean;
+}
+/**
+ * Restore multiple files with per-file error tracking.
+ *
+ * Each file is restored independently - if one fails, subsequent files
+ * are still attempted. This ensures maximum recovery even in partial
+ * failure scenarios.
+ *
+ * @param {Array<{name: string, path: string, content: string}>} filesToRestore - Files to restore
+ * @returns {RollbackResult} Result with restored files and any errors
+ *
+ * @example
+ * const result = rollbackFiles([
+ *   { name: 'backlog.md', path: '/path/to/backlog.md', content: 'original content' },
+ *   { name: 'status.md', path: '/path/to/status.md', content: 'original content' },
+ * ]);
+ *
+ * if (!result.success) {
+ *   console.error('Rollback had errors:', result.errors);
+ * }
+ */
+export declare function rollbackFiles(filesToRestore: any): RollbackResult;
+/**
+ * Delete multiple files with per-file error tracking.
+ *
+ * @param {Array<{name: string, path: string}>} filesToDelete - Files to delete
+ * @returns {RollbackResult} Result with deleted files and any errors
+ */
+export declare function deleteFiles(filesToDelete: any): RollbackResult;
+export {};

package/dist/rollback-utils.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Rollback Utilities for WU Tooling
+ *
+ * WU-1255: Per-file error tracking for robust rollback operations.
+ * Ensures all files are attempted even if some fail, with clear error reporting.
+ *
+ * @see {@link tools/wu-done.mjs} - Consumer (rollbackTransaction function)
+ */
+/* eslint-disable security/detect-non-literal-fs-filename */
+import { writeFileSync, unlinkSync } from 'node:fs';
+/**
+ * Result of a rollback operation.
+ * Tracks which files were restored and which failed.
+ *
+ * @class
+ */
+export class RollbackResult {
+    /** Names of successfully restored files */
+    restored;
+    /** Failed file restorations */
+    errors;
+    constructor() {
+        this.restored = [];
+        this.errors = [];
+    }
+    /**
+     * Record a successful file restoration.
+     * @param {string} name - File identifier (e.g., 'backlog.md')
+     */
+    addSuccess(name) {
+        this.restored.push(name);
+    }
+    /**
+     * Record a failed file restoration.
+     * @param {string} name - File identifier
+     * @param {string} path - Full file path
+     * @param {string} error - Error message
+     */
+    addError(name, path, error) {
+        this.errors.push({ name, path, error });
+    }
+    /**
+     * Check if all files were restored successfully.
+     * @returns {boolean} True if no errors occurred
+     */
+    get success() {
+        return this.errors.length === 0;
+    }
+}
+/**
+ * Restore multiple files with per-file error tracking.
+ *
+ * Each file is restored independently - if one fails, subsequent files
+ * are still attempted. This ensures maximum recovery even in partial
+ * failure scenarios.
+ *
+ * @param {Array<{name: string, path: string, content: string}>} filesToRestore - Files to restore
+ * @returns {RollbackResult} Result with restored files and any errors
+ *
+ * @example
+ * const result = rollbackFiles([
+ *   { name: 'backlog.md', path: '/path/to/backlog.md', content: 'original content' },
+ *   { name: 'status.md', path: '/path/to/status.md', content: 'original content' },
+ * ]);
+ *
+ * if (!result.success) {
+ *   console.error('Rollback had errors:', result.errors);
+ * }
+ */
+export function rollbackFiles(filesToRestore) {
+    const result = new RollbackResult();
+    for (const file of filesToRestore) {
+        try {
+            writeFileSync(file.path, file.content, { encoding: 'utf-8' });
+            result.addSuccess(file.name);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.addError(file.name, file.path, message);
+        }
+    }
+    return result;
+}
+/**
+ * Delete multiple files with per-file error tracking.
+ *
+ * @param {Array<{name: string, path: string}>} filesToDelete - Files to delete
+ * @returns {RollbackResult} Result with deleted files and any errors
+ */
+export function deleteFiles(filesToDelete) {
+    const result = new RollbackResult();
+    for (const file of filesToDelete) {
+        try {
+            unlinkSync(file.path);
+            result.addSuccess(file.name);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.addError(file.name, file.path, message);
+        }
+    }
+    return result;
+}

package/dist/section-headings.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Section Headings Constants
+ *
+ * Centralized section heading defaults for backlog.md and status.md
+ * Eliminates magic strings scattered throughout wu-* tools
+ *
+ * Usage: Use getSectionHeadingsWithDefaults() to get frontmatter-configured
+ * headings with sensible fallbacks if frontmatter is missing/malformed
+ */
+/**
+ * Default section headings (fallbacks when frontmatter is missing)
+ * Re-exports from wu-constants.mjs for backwards compatibility
+ */
+export declare const DEFAULT_SECTION_HEADINGS: {
+    backlog: {
+        ready: string;
+        in_progress: string;
+        blocked: string;
+        done: string;
+    };
+    status: {
+        in_progress: string;
+        completed: string;
+        blocked: string;
+    };
+};
+/**
+ * Get section headings with frontmatter override + defaults
+ *
+ * Replaces scattered pattern: headings.done || '## ✅ Done'
+ * Centralizes fallback logic for consistent heading resolution
+ *
+ * @param {object|null} frontmatter - Parsed frontmatter from backlog.md/status.md
+ * @param {'backlog'|'status'} docType - Document type
+ * @returns {object} Section headings (configured or default)
+ */
+export declare function getSectionHeadingsWithDefaults(frontmatter: any, docType?: string): {
+    ready: any;
+    in_progress: any;
+    blocked: any;
+    done: any;
+    completed: any;
+};

package/dist/section-headings.js

@@ -0,0 +1,49 @@
+/**
+ * Section Headings Constants
+ *
+ * Centralized section heading defaults for backlog.md and status.md
+ * Eliminates magic strings scattered throughout wu-* tools
+ *
+ * Usage: Use getSectionHeadingsWithDefaults() to get frontmatter-configured
+ * headings with sensible fallbacks if frontmatter is missing/malformed
+ */
+import { getSectionHeadings } from './backlog-parser.js';
+import { BACKLOG_SECTIONS, STATUS_SECTIONS } from './wu-constants.js';
+/**
+ * Default section headings (fallbacks when frontmatter is missing)
+ * Re-exports from wu-constants.mjs for backwards compatibility
+ */
+export const DEFAULT_SECTION_HEADINGS = {
+    backlog: {
+        ready: BACKLOG_SECTIONS.READY,
+        in_progress: BACKLOG_SECTIONS.IN_PROGRESS,
+        blocked: BACKLOG_SECTIONS.BLOCKED,
+        done: BACKLOG_SECTIONS.DONE,
+    },
+    status: {
+        in_progress: STATUS_SECTIONS.IN_PROGRESS,
+        completed: STATUS_SECTIONS.COMPLETED,
+        blocked: STATUS_SECTIONS.BLOCKED,
+    },
+};
+/**
+ * Get section headings with frontmatter override + defaults
+ *
+ * Replaces scattered pattern: headings.done || '## ✅ Done'
+ * Centralizes fallback logic for consistent heading resolution
+ *
+ * @param {object|null} frontmatter - Parsed frontmatter from backlog.md/status.md
+ * @param {'backlog'|'status'} docType - Document type
+ * @returns {object} Section headings (configured or default)
+ */
+export function getSectionHeadingsWithDefaults(frontmatter, docType = 'backlog') {
+    const defaults = DEFAULT_SECTION_HEADINGS[docType];
+    const configured = frontmatter ? getSectionHeadings(frontmatter) : {};
+    return {
+        ready: configured.ready || defaults.ready,
+        in_progress: configured.in_progress || defaults.in_progress,
+        blocked: configured.blocked || defaults.blocked,
+        done: configured.done || defaults.done,
+        completed: configured.completed || defaults.completed,
+    };
+}

package/dist/spawn-escalation.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Spawn Escalation Module (WU-1952, WU-1967)
+ *
+ * WU-1967: Replaced Bug WU creation with memory bus signalling.
+ * Signals orchestrator inbox instead of creating human-in-loop Bug WUs.
+ *
+ * Escalation Flow:
+ * 1. recoverStuckSpawn() returns { recovered: false, action: ESCALATED_STUCK }
+ * 2. escalateStuckSpawn() signals orchestrator via memory bus
+ * 3. Spawn status updated to ESCALATED (prevents duplicate signals)
+ * 4. Orchestrator decides: retry (1st), block (2nd), human escalate (3rd+)
+ *
+ * Library-First Note: This is project-specific spawn escalation code for
+ * PatientPath's custom spawn-registry.jsonl and memory bus patterns.
+ * No external library exists for this domain-specific agent lifecycle management.
+ *
+ * @see {@link tools/lib/__tests__/spawn-escalation.test.mjs} - Tests
+ * @see {@link tools/lib/spawn-recovery.mjs} - Recovery logic
+ * @see {@link tools/lib/mem-signal-core.mjs} - Signal creation
+ */
+/**
+ * Signal type for spawn failures
+ */
+export declare const SPAWN_FAILURE_SIGNAL_TYPE = "spawn_failure";
+/**
+ * Severity levels for spawn failure signals
+ */
+export declare const SignalSeverity: Readonly<{
+    WARNING: "warning";
+    ERROR: "error";
+    CRITICAL: "critical";
+}>;
+/**
+ * Suggested actions for spawn failure signals
+ */
+export declare const SuggestedAction: Readonly<{
+    RETRY: "retry";
+    BLOCK: "block";
+    HUMAN_ESCALATE: "human_escalate";
+}>;
+/**
+ * Escalates a stuck spawn by signalling the orchestrator.
+ *
+ * WU-1967: Replaced Bug WU creation with memory bus signalling.
+ * Called when recoverStuckSpawn() returns ESCALATED_STUCK.
+ * Signals orchestrator inbox with spawn failure context.
+ *
+ * Escalation levels based on recovery attempts:
+ * - 1st attempt: severity=warning, suggested_action=retry
+ * - 2nd attempt: severity=error, suggested_action=block
+ * - 3rd+ attempt: severity=critical, suggested_action=human_escalate
+ *
+ * @param {string} spawnId - ID of the stuck spawn
+ * @param {Object} options - Options
+ * @param {string} options.baseDir - Base directory for .beacon/
+ * @param {boolean} [options.dryRun=false] - If true, returns signal without sending
+ * @returns {Promise<EscalationResult>} Escalation result with signal details
+ *
+ * @throws {Error} If spawn not found
+ * @throws {Error} If spawn already escalated (duplicate prevention)
+ * @throws {Error} If no escalation audit log exists
+ *
+ * @example
+ * // After recoverStuckSpawn returns ESCALATED_STUCK
+ * const result = await escalateStuckSpawn('spawn-1234', { baseDir: '/path/to/project' });
+ * console.log(`Signal sent: ${result.signalId}, action: ${result.signal.suggested_action}`);
+ */
+export interface EscalateStuckSpawnOptions {
+    /** Base directory for .beacon/ */
+    baseDir?: string;
+    /** If true, return spec only without sending signal */
+    dryRun?: boolean;
+}
+export declare function escalateStuckSpawn(spawnId: any, options?: EscalateStuckSpawnOptions): Promise<{
+    signalId: string;
+    signal: {
+        type: string;
+        severity: "error" | "warning" | "critical";
+        spawn_id: any;
+        target_wu_id: any;
+        parent_wu_id: any;
+        lane: any;
+        recovery_action: any;
+        recovery_attempts: any;
+        last_checkpoint: any;
+        suggested_action: "retry" | "block" | "human_escalate";
+        message: string;
+    };
+    spawnStatus: "escalated";
+}>;

package/dist/spawn-escalation.js

@@ -0,0 +1,253 @@
+/**
+ * Spawn Escalation Module (WU-1952, WU-1967)
+ *
+ * WU-1967: Replaced Bug WU creation with memory bus signalling.
+ * Signals orchestrator inbox instead of creating human-in-loop Bug WUs.
+ *
+ * Escalation Flow:
+ * 1. recoverStuckSpawn() returns { recovered: false, action: ESCALATED_STUCK }
+ * 2. escalateStuckSpawn() signals orchestrator via memory bus
+ * 3. Spawn status updated to ESCALATED (prevents duplicate signals)
+ * 4. Orchestrator decides: retry (1st), block (2nd), human escalate (3rd+)
+ *
+ * Library-First Note: This is project-specific spawn escalation code for
+ * PatientPath's custom spawn-registry.jsonl and memory bus patterns.
+ * No external library exists for this domain-specific agent lifecycle management.
+ *
+ * @see {@link tools/lib/__tests__/spawn-escalation.test.mjs} - Tests
+ * @see {@link tools/lib/spawn-recovery.mjs} - Recovery logic
+ * @see {@link tools/lib/mem-signal-core.mjs} - Signal creation
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { SpawnRegistryStore } from './spawn-registry-store.js';
+import { SpawnStatus } from './spawn-registry-schema.js';
+import { RECOVERY_DIR_NAME } from './spawn-recovery.js';
+let createSignal = null;
+try {
+    const mod = await import('@lumenflow/memory/signal');
+    createSignal = mod.createSignal;
+}
+catch {
+    // @lumenflow/memory not available - signal features disabled
+}
+/**
+ * Log prefix for spawn-escalation messages
+ */
+const LOG_PREFIX = '[spawn-escalation]';
+/**
+ * Signal type for spawn failures
+ */
+export const SPAWN_FAILURE_SIGNAL_TYPE = 'spawn_failure';
+/**
+ * Severity levels for spawn failure signals
+ */
+export const SignalSeverity = Object.freeze({
+    WARNING: 'warning',
+    ERROR: 'error',
+    CRITICAL: 'critical',
+});
+/**
+ * Suggested actions for spawn failure signals
+ */
+export const SuggestedAction = Object.freeze({
+    RETRY: 'retry',
+    BLOCK: 'block',
+    HUMAN_ESCALATE: 'human_escalate',
+});
+/**
+ * @typedef {Object} SpawnFailureSignal
+ * @property {string} type - Always 'spawn_failure'
+ * @property {string} severity - 'warning' | 'error' | 'critical'
+ * @property {string} spawn_id - Spawn ID
+ * @property {string} target_wu_id - Target WU ID
+ * @property {string} parent_wu_id - Parent WU ID (orchestrator)
+ * @property {string} lane - Lane name
+ * @property {string} recovery_action - Recovery action that triggered escalation
+ * @property {number} recovery_attempts - Number of recovery attempts
+ * @property {string|null} last_checkpoint - Last checkpoint timestamp
+ * @property {string} suggested_action - 'retry' | 'block' | 'human_escalate'
+ * @property {string} message - Human-readable message
+ */
+/**
+ * @typedef {Object} EscalationResult
+ * @property {string} signalId - Signal ID (e.g., 'sig-abc12345')
+ * @property {SpawnFailureSignal} signal - The signal payload
+ * @property {string} spawnStatus - Updated spawn status (ESCALATED)
+ */
+/**
+ * @typedef {Object} AuditLogEntry
+ * @property {string} timestamp - ISO timestamp of recovery action
+ * @property {string} spawnId - ID of the spawn being recovered
+ * @property {string} action - Recovery action taken
+ * @property {string} reason - Explanation of why action was taken
+ * @property {Object} context - Additional context
+ */
+/**
+ * Counts existing escalation attempts for a spawn by reading audit logs.
+ *
+ * @param {string} baseDir - Base directory
+ * @param {string} spawnId - Spawn ID to count attempts for
+ * @returns {Promise<number>} Number of previous escalation attempts
+ */
+async function countEscalationAttempts(baseDir, spawnId) {
+    const recoveryDir = path.join(baseDir, '.beacon', RECOVERY_DIR_NAME);
+    try {
+        const files = await fs.readdir(recoveryDir);
+        const spawnFiles = files.filter((f) => f.startsWith(`${spawnId}-`) && f.endsWith('.json'));
+        return spawnFiles.length;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return 0;
+        }
+        throw error;
+    }
+}
+/**
+ * Determines severity and suggested action based on recovery attempts.
+ *
+ * @param {number} attempts - Number of recovery attempts
+ * @returns {{ severity: string, suggestedAction: string }}
+ */
+function determineEscalationLevel(attempts) {
+    if (attempts <= 1) {
+        return {
+            severity: SignalSeverity.WARNING,
+            suggestedAction: SuggestedAction.RETRY,
+        };
+    }
+    else if (attempts === 2) {
+        return {
+            severity: SignalSeverity.ERROR,
+            suggestedAction: SuggestedAction.BLOCK,
+        };
+    }
+    else {
+        return {
+            severity: SignalSeverity.CRITICAL,
+            suggestedAction: SuggestedAction.HUMAN_ESCALATE,
+        };
+    }
+}
+/**
+ * Find the most recent escalation audit log for a spawn.
+ *
+ * @param {string} baseDir - Base directory
+ * @param {string} spawnId - Spawn ID to find audit log for
+ * @returns {Promise<AuditLogEntry|null>} Audit log entry or null if not found
+ */
+async function findEscalationAuditLog(baseDir, spawnId) {
+    const recoveryDir = path.join(baseDir, '.beacon', RECOVERY_DIR_NAME);
+    try {
+        const files = await fs.readdir(recoveryDir);
+        // Filter files for this spawn ID, sorted by name (timestamp-based)
+        const spawnFiles = files
+            .filter((f) => f.startsWith(`${spawnId}-`) && f.endsWith('.json'))
+            .sort()
+            .reverse(); // Most recent first
+        if (spawnFiles.length === 0) {
+            return null;
+        }
+        // Read the most recent audit log
+        const auditPath = path.join(recoveryDir, spawnFiles[0]);
+        const content = await fs.readFile(auditPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Builds a spawn failure signal payload.
+ *
+ * @param {Object} spawn - Spawn event data
+ * @param {AuditLogEntry} auditLog - Escalation audit log
+ * @param {number} attempts - Number of recovery attempts
+ * @returns {SpawnFailureSignal} Signal payload
+ */
+function buildSpawnFailureSignal(spawn, auditLog, attempts) {
+    const { severity, suggestedAction } = determineEscalationLevel(attempts);
+    const lastCheckpoint = auditLog.context.lastCheckpoint || null;
+    return {
+        type: SPAWN_FAILURE_SIGNAL_TYPE,
+        severity,
+        spawn_id: spawn.id,
+        target_wu_id: spawn.targetWuId,
+        parent_wu_id: spawn.parentWuId,
+        lane: spawn.lane,
+        recovery_action: auditLog.action,
+        recovery_attempts: attempts,
+        last_checkpoint: lastCheckpoint,
+        suggested_action: suggestedAction,
+        message: `Spawn ${spawn.id} for ${spawn.targetWuId} stuck: ${auditLog.reason}`,
+    };
+}
+export async function escalateStuckSpawn(spawnId, options = {}) {
+    const { baseDir = process.cwd(), dryRun = false } = options;
+    const registryDir = path.join(baseDir, '.beacon', 'state');
+    // Load spawn registry
+    const store = new SpawnRegistryStore(registryDir);
+    try {
+        await store.load();
+    }
+    catch {
+        throw new Error(`Spawn ${spawnId} not found: registry unavailable`);
+    }
+    // Find the spawn
+    const spawn = store.getById(spawnId);
+    if (!spawn) {
+        throw new Error(`Spawn ${spawnId} not found in registry`);
+    }
+    // Check if signal module is available
+    if (!createSignal) {
+        throw new Error('Signal module (@lumenflow/memory) not available - cannot escalate');
+    }
+    // WU-1967: Check if already escalated (prevents duplicate signals)
+    if (spawn.status === SpawnStatus.ESCALATED) {
+        throw new Error(`Spawn ${spawnId} already escalated`);
+    }
+    // Find escalation audit log
+    const auditLog = await findEscalationAuditLog(baseDir, spawnId);
+    if (!auditLog) {
+        throw new Error(`No escalation audit log found for spawn ${spawnId}`);
+    }
+    // Count previous escalation attempts
+    const attempts = await countEscalationAttempts(baseDir, spawnId);
+    // Build signal payload
+    const signalPayload = buildSpawnFailureSignal(spawn, auditLog, attempts);
+    if (dryRun) {
+        console.log(`${LOG_PREFIX} [dry-run] Would signal orchestrator`);
+        console.log(`${LOG_PREFIX} [dry-run] Severity: ${signalPayload.severity}`);
+        console.log(`${LOG_PREFIX} [dry-run] Suggested action: ${signalPayload.suggested_action}`);
+        console.log(`${LOG_PREFIX} [dry-run] Message: ${signalPayload.message}`);
+        return {
+            signalId: 'sig-dry-run',
+            signal: signalPayload,
+            spawnStatus: SpawnStatus.ESCALATED,
+        };
+    }
+    // WU-1967: Send signal to orchestrator inbox
+    console.log(`${LOG_PREFIX} Signalling orchestrator for spawn ${spawnId}`);
+    console.log(`${LOG_PREFIX} Target WU: ${spawn.targetWuId}`);
+    console.log(`${LOG_PREFIX} Severity: ${signalPayload.severity}`);
+    console.log(`${LOG_PREFIX} Suggested action: ${signalPayload.suggested_action}`);
+    // Create signal with structured message (JSON payload in message field)
+    const signalResult = await createSignal(baseDir, {
+        message: JSON.stringify(signalPayload),
+        wuId: spawn.parentWuId, // Signal targets the orchestrator (parent WU)
+        lane: spawn.lane,
+    });
+    // Update spawn status to ESCALATED (prevents duplicate signals)
+    await store.updateStatus(spawnId, SpawnStatus.ESCALATED);
+    console.log(`${LOG_PREFIX} Signal sent: ${signalResult.signal.id}`);
+    console.log(`${LOG_PREFIX} Spawn ${spawnId} status updated to ESCALATED`);
+    return {
+        signalId: signalResult.signal.id,
+        signal: signalPayload,
+        spawnStatus: SpawnStatus.ESCALATED,
+    };
+}