@lumenflow/core 1.0.0

package/dist/spawn-tree.js

@@ -0,0 +1,285 @@
+/**
+ * Spawn Tree Builder (WU-1950)
+ *
+ * Builds and formats spawn trees for visualization.
+ * Used by spawn:list command to display parent-child relationships.
+ *
+ * Note: Domain-specific tree visualization for spawn registry.
+ * Integrates with spawn-registry-store and spawn-registry-schema.
+ * No external tree library needed - logic is tightly coupled to spawn data model.
+ *
+ * @see {@link tools/__tests__/spawn-list.test.mjs} - Tests
+ * @see {@link tools/spawn-list.mjs} - CLI command
+ * @see {@link tools/lib/spawn-registry-store.mjs} - Data source
+ */
+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 { parse as parseYAML } from 'yaml';
+/**
+ * Status indicators for terminal output.
+ * Using unicode symbols for clear visual distinction.
+ */
+export const STATUS_INDICATORS = Object.freeze({
+    [SpawnStatus.PENDING]: '\u25CB', // ○ (white circle)
+    [SpawnStatus.COMPLETED]: '\u2713', // ✓ (check mark)
+    [SpawnStatus.TIMEOUT]: '\u23F1', // ⏱ (stopwatch)
+    [SpawnStatus.CRASHED]: '\u2717', // ✗ (x mark)
+});
+/**
+ * Tree node structure
+ * @typedef {object} SpawnTreeNode
+ * @property {string} wuId - WU ID for this node
+ * @property {string|null} spawnId - Spawn ID (null for root)
+ * @property {string|null} status - Spawn status (null for root)
+ * @property {string|null} lane - Lane (null for root)
+ * @property {string|null} spawnedAt - Spawn timestamp (null for root)
+ * @property {SpawnTreeNode[]} children - Child nodes
+ */
+/**
+ * Builds a spawn tree from flat spawn events.
+ *
+ * @param {import('./spawn-registry-schema.js').SpawnEvent[]} spawns - Array of spawn events
+ * @param {string} rootWuId - Root WU ID to build tree from
+ * @returns {SpawnTreeNode} Tree rooted at rootWuId
+ *
+ * @example
+ * const tree = buildSpawnTree(spawns, 'WU-1000');
+ * // { wuId: 'WU-1000', children: [{ wuId: 'WU-1001', ... }] }
+ */
+export function buildSpawnTree(spawns, rootWuId) {
+    // Create root node
+    /** @type {SpawnTreeNode} */
+    const root = {
+        wuId: rootWuId,
+        spawnId: null,
+        status: null,
+        lane: null,
+        spawnedAt: null,
+        children: [],
+    };
+    if (spawns.length === 0) {
+        return root;
+    }
+    // Build index of spawns by parent WU ID for efficient lookup
+    /** @type {Map<string, import('./spawn-registry-schema.js').SpawnEvent[]>} */
+    const spawnsByParent = new Map();
+    for (const spawn of spawns) {
+        const existing = spawnsByParent.get(spawn.parentWuId) ?? [];
+        existing.push(spawn);
+        spawnsByParent.set(spawn.parentWuId, existing);
+    }
+    // Recursive function to build tree
+    /**
+     * @param {string} parentWuId
+     * @returns {SpawnTreeNode[]}
+     */
+    function buildChildren(parentWuId) {
+        const childSpawns = spawnsByParent.get(parentWuId) ?? [];
+        return childSpawns.map((spawn) => ({
+            wuId: spawn.targetWuId,
+            spawnId: spawn.id,
+            status: spawn.status,
+            lane: spawn.lane,
+            spawnedAt: spawn.spawnedAt,
+            children: buildChildren(spawn.targetWuId),
+        }));
+    }
+    root.children = buildChildren(rootWuId);
+    return root;
+}
+/**
+ * Tree branch characters for formatting
+ */
+const TREE_CHARS = Object.freeze({
+    VERTICAL: '\u2502', // │
+    BRANCH: '\u251C', // ├
+    LAST_BRANCH: '\u2514', // └
+    HORIZONTAL: '\u2500', // ─
+    SPACE: ' ',
+});
+/**
+ * Formats a spawn tree for terminal display with indentation and tree characters.
+ *
+ * @param {SpawnTreeNode} tree - Tree to format
+ * @returns {string} Formatted tree string
+ *
+ * @example
+ * const formatted = formatSpawnTree(tree);
+ * // WU-1000 (root)
+ * // ├── ○ WU-1001 [spawn-1111] (Operations: Tooling)
+ * // │   └── ✓ WU-1002 [spawn-2222] (Core: Backend)
+ * // └── ○ WU-1003 [spawn-3333] (Experience: Web)
+ */
+export function formatSpawnTree(tree) {
+    const lines = [];
+    // Root line
+    lines.push(`${tree.wuId} (root)`);
+    if (tree.children.length === 0) {
+        lines.push(`  (no spawns)`);
+        return lines.join('\n');
+    }
+    // Recursive formatting
+    /**
+     * @param {SpawnTreeNode[]} children
+     * @param {string} prefix - Indentation prefix for this level
+     */
+    function formatChildren(children, prefix) {
+        children.forEach((child, index) => {
+            const isLast = index === children.length - 1;
+            const branch = isLast
+                ? `${TREE_CHARS.LAST_BRANCH}${TREE_CHARS.HORIZONTAL}${TREE_CHARS.HORIZONTAL}`
+                : `${TREE_CHARS.BRANCH}${TREE_CHARS.HORIZONTAL}${TREE_CHARS.HORIZONTAL}`;
+            const indicator = STATUS_INDICATORS[child.status] ?? '?';
+            const spawnInfo = child.spawnId ? ` [${child.spawnId}]` : '';
+            const laneInfo = child.lane ? ` (${child.lane})` : '';
+            lines.push(`${prefix}${branch} ${indicator} ${child.wuId}${spawnInfo}${laneInfo}`);
+            // Child prefix: use vertical bar if not last, space if last
+            const childPrefix = prefix + (isLast ? '    ' : `${TREE_CHARS.VERTICAL}   `);
+            formatChildren(child.children, childPrefix);
+        });
+    }
+    formatChildren(tree.children, '');
+    return lines.join('\n');
+}
+/**
+ * Gets all spawns for a WU (both where WU is parent and descendants).
+ *
+ * Returns all spawns needed to build the full tree from this WU.
+ *
+ * @param {string} wuId - WU ID to get spawns for
+ * @param {string} baseDir - Directory containing spawn-registry.jsonl
+ * @returns {Promise<import('./spawn-registry-schema.js').SpawnEvent[]>} Array of spawn events
+ *
+ * @example
+ * const spawns = await getSpawnsByWU('WU-1000', '.beacon/state');
+ */
+export async function getSpawnsByWU(wuId, baseDir) {
+    const store = new SpawnRegistryStore(baseDir);
+    try {
+        await store.load();
+    }
+    catch (error) {
+        // Registry doesn't exist or is invalid
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    // Get all spawns
+    const allSpawns = store.getAllSpawns();
+    if (allSpawns.length === 0) {
+        return [];
+    }
+    // Find all spawns in the tree rooted at wuId
+    // Start with direct children of wuId
+    const result = [];
+    const visited = new Set();
+    const queue = [wuId];
+    while (queue.length > 0) {
+        const currentWuId = queue.shift();
+        if (visited.has(currentWuId))
+            continue;
+        visited.add(currentWuId);
+        // Find spawns where current WU is the parent
+        const childSpawns = store.getByParent(currentWuId);
+        for (const spawn of childSpawns) {
+            if (!result.some((s) => s.id === spawn.id)) {
+                result.push(spawn);
+                queue.push(spawn.targetWuId);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Gets all spawns for an initiative.
+ *
+ * Reads WU YAML files to find which WUs belong to the initiative,
+ * then returns all spawns where parent or target WU belongs to initiative.
+ *
+ * @param {string} initiativeId - Initiative ID (e.g., 'INIT-001')
+ * @param {string} registryDir - Directory containing spawn-registry.jsonl
+ * @param {string} wuDir - Directory containing WU YAML files
+ * @returns {Promise<import('./spawn-registry-schema.js').SpawnEvent[]>} Array of spawn events
+ *
+ * @example
+ * const spawns = await getSpawnsByInitiative('INIT-001', '.beacon/state', 'docs/04-operations/tasks/wu');
+ */
+export async function getSpawnsByInitiative(initiativeId, registryDir, wuDir) {
+    // Get all WUs belonging to initiative
+    const initiativeWuIds = await getWUsForInitiative(initiativeId, wuDir);
+    if (initiativeWuIds.size === 0) {
+        return [];
+    }
+    // Load spawn registry
+    const store = new SpawnRegistryStore(registryDir);
+    try {
+        await store.load();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    // Filter spawns where parent belongs to initiative
+    const allSpawns = store.getAllSpawns();
+    return allSpawns.filter((spawn) => initiativeWuIds.has(spawn.parentWuId));
+}
+/**
+ * Reads WU YAML files to find WUs belonging to an initiative.
+ *
+ * @param {string} initiativeId - Initiative ID
+ * @param {string} wuDir - Directory containing WU YAML files
+ * @returns {Promise<Set<string>>} Set of WU IDs belonging to initiative
+ */
+async function getWUsForInitiative(initiativeId, wuDir) {
+    const wuIds = new Set();
+    let files;
+    try {
+        files = await fs.readdir(wuDir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return wuIds;
+        }
+        throw error;
+    }
+    const wuFiles = files.filter((f) => f.startsWith('WU-') && f.endsWith('.yaml'));
+    for (const file of wuFiles) {
+        try {
+            const content = await fs.readFile(path.join(wuDir, file), 'utf-8');
+            const doc = parseYAML(content);
+            if (doc.initiative === initiativeId) {
+                wuIds.add(doc.id);
+            }
+        }
+        catch {
+            // Skip files that can't be parsed
+            continue;
+        }
+    }
+    return wuIds;
+}
+/**
+ * Converts a spawn tree to JSON format.
+ *
+ * @param {SpawnTreeNode} tree - Tree to convert
+ * @returns {object} JSON-serializable tree
+ *
+ * @example
+ * const json = treeToJSON(tree);
+ * console.log(JSON.stringify(json, null, 2));
+ */
+export function treeToJSON(tree) {
+    return {
+        wuId: tree.wuId,
+        spawnId: tree.spawnId,
+        status: tree.status,
+        lane: tree.lane,
+        spawnedAt: tree.spawnedAt,
+        children: tree.children.map((child) => treeToJSON(child)),
+    };
+}

package/dist/stamp-status-validator.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Stamp-status validation utilities
+ *
+ * WU-1781: Provides utilities to detect and handle legacy WUs with stamp-status mismatches.
+ *
+ * The problem: WUs with .done stamps but non-done status (e.g., cancelled, ready) cause
+ * tasks:validate to fail, which blocks husky pre-push and prevents wu:done from completing.
+ *
+ * The solution: Detect these legacy artifacts and exempt them from validation to prevent
+ * deadlocks, while still enforcing validation on new/active WUs.
+ */
+/**
+ * List of parent-only lanes that are deprecated (legacy).
+ * WUs with these lanes are considered legacy artifacts and may have stamp-status mismatches.
+ * Modern WUs should use sub-lanes like "Operations: Tooling".
+ *
+ * @type {readonly string[]}
+ */
+export declare const LEGACY_PARENT_ONLY_LANES: readonly string[];
+/**
+ * Check if a lane is a deprecated parent-only lane (no sub-lane specified).
+ *
+ * @param {string|null|undefined} lane - The lane to check
+ * @returns {boolean} True if the lane is a parent-only legacy lane
+ *
+ * @example
+ * isLegacyParentOnlyLane('Intelligence') // true
+ * isLegacyParentOnlyLane('Operations: Tooling') // false
+ */
+export declare function isLegacyParentOnlyLane(lane: any): boolean;
+/**
+ * Check if a WU is a legacy artifact with stamp-status mismatch.
+ *
+ * A legacy stamped WU is one that:
+ * - Has a .done stamp file
+ * - Has a status that is NOT 'done'
+ *
+ * These WUs are historical artifacts from before validation was strict,
+ * and should be exempted from the stamp-status consistency check.
+ *
+ * @param {object} wu - The parsed WU YAML object
+ * @param {string} wu.id - WU ID (e.g., 'WU-100')
+ * @param {string} wu.status - WU status (e.g., 'done', 'cancelled', 'ready')
+ * @param {Set<string>} stampedIds - Set of WU IDs that have .done stamp files
+ * @returns {boolean} True if this is a legacy stamped WU with mismatch
+ *
+ * @example
+ * const stampedIds = new Set(['WU-100', 'WU-101']);
+ * isLegacyStampedWU({ id: 'WU-100', status: 'cancelled' }, stampedIds) // true
+ * isLegacyStampedWU({ id: 'WU-100', status: 'done' }, stampedIds) // false (no mismatch)
+ * isLegacyStampedWU({ id: 'WU-999', status: 'cancelled' }, stampedIds) // false (no stamp)
+ */
+export declare function isLegacyStampedWU(wu: any, stampedIds: any): boolean;
+/**
+ * Check if a WU ID is exempted from stamp-status validation via config.
+ *
+ * The .lumenflow.config.yaml can specify exemptions for known historical
+ * artifacts that cannot be fixed (e.g., WU-307, WU-311, WU-1152).
+ *
+ * @param {string} id - WU ID to check
+ * @param {string[]|null|undefined} exemptions - List of exempted WU IDs from config
+ * @returns {boolean} True if the WU is exempted
+ *
+ * @example
+ * isExemptedFromStampStatusCheck('WU-307', ['WU-307', 'WU-311']) // true
+ * isExemptedFromStampStatusCheck('WU-999', ['WU-307', 'WU-311']) // false
+ */
+export declare function isExemptedFromStampStatusCheck(id: any, exemptions: any): boolean;
+/**
+ * Determine if a WU should be exempted from stamp-status validation.
+ *
+ * A WU is exempted if:
+ * 1. It's explicitly listed in the config exemptions, OR
+ * 2. It's a legacy stamped WU (has stamp but status != done) AND has a legacy parent-only lane
+ *
+ * @param {object} wu - The parsed WU YAML object
+ * @param {Set<string>} stampedIds - Set of WU IDs that have .done stamp files
+ * @param {string[]} exemptions - List of exempted WU IDs from config
+ * @returns {{ exempted: boolean, reason: string|null }} Whether exempted and why
+ */
+export declare function shouldExemptFromStampStatusCheck(wu: any, stampedIds: any, exemptions?: any[]): {
+    exempted: boolean;
+    reason: string;
+};

package/dist/stamp-status-validator.js

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Stamp-status validation utilities
+ *
+ * WU-1781: Provides utilities to detect and handle legacy WUs with stamp-status mismatches.
+ *
+ * The problem: WUs with .done stamps but non-done status (e.g., cancelled, ready) cause
+ * tasks:validate to fail, which blocks husky pre-push and prevents wu:done from completing.
+ *
+ * The solution: Detect these legacy artifacts and exempt them from validation to prevent
+ * deadlocks, while still enforcing validation on new/active WUs.
+ */
+/**
+ * List of parent-only lanes that are deprecated (legacy).
+ * WUs with these lanes are considered legacy artifacts and may have stamp-status mismatches.
+ * Modern WUs should use sub-lanes like "Operations: Tooling".
+ *
+ * @type {readonly string[]}
+ */
+export const LEGACY_PARENT_ONLY_LANES = Object.freeze([
+    'Intelligence',
+    'Core Systems',
+    'Operations',
+    'Experience',
+    'Discovery',
+]);
+/**
+ * Check if a lane is a deprecated parent-only lane (no sub-lane specified).
+ *
+ * @param {string|null|undefined} lane - The lane to check
+ * @returns {boolean} True if the lane is a parent-only legacy lane
+ *
+ * @example
+ * isLegacyParentOnlyLane('Intelligence') // true
+ * isLegacyParentOnlyLane('Operations: Tooling') // false
+ */
+export function isLegacyParentOnlyLane(lane) {
+    if (!lane || typeof lane !== 'string') {
+        return false;
+    }
+    const normalizedLane = lane.trim();
+    // Check if it's an exact match to a parent-only lane (case-insensitive)
+    const lowerLane = normalizedLane.toLowerCase();
+    return LEGACY_PARENT_ONLY_LANES.some((parentLane) => parentLane.toLowerCase() === lowerLane);
+}
+/**
+ * Check if a WU is a legacy artifact with stamp-status mismatch.
+ *
+ * A legacy stamped WU is one that:
+ * - Has a .done stamp file
+ * - Has a status that is NOT 'done'
+ *
+ * These WUs are historical artifacts from before validation was strict,
+ * and should be exempted from the stamp-status consistency check.
+ *
+ * @param {object} wu - The parsed WU YAML object
+ * @param {string} wu.id - WU ID (e.g., 'WU-100')
+ * @param {string} wu.status - WU status (e.g., 'done', 'cancelled', 'ready')
+ * @param {Set<string>} stampedIds - Set of WU IDs that have .done stamp files
+ * @returns {boolean} True if this is a legacy stamped WU with mismatch
+ *
+ * @example
+ * const stampedIds = new Set(['WU-100', 'WU-101']);
+ * isLegacyStampedWU({ id: 'WU-100', status: 'cancelled' }, stampedIds) // true
+ * isLegacyStampedWU({ id: 'WU-100', status: 'done' }, stampedIds) // false (no mismatch)
+ * isLegacyStampedWU({ id: 'WU-999', status: 'cancelled' }, stampedIds) // false (no stamp)
+ */
+export function isLegacyStampedWU(wu, stampedIds) {
+    if (!wu || !wu.id || !stampedIds) {
+        return false;
+    }
+    // Must have a stamp
+    const hasStamp = stampedIds.has(wu.id);
+    if (!hasStamp) {
+        return false;
+    }
+    // Must have a status that is NOT done
+    const status = wu.status;
+    if (!status || typeof status !== 'string') {
+        return false;
+    }
+    // If status is 'done', this is a normal WU (no mismatch)
+    if (status.toLowerCase() === 'done') {
+        return false;
+    }
+    // Has stamp + status != done = legacy mismatch
+    return true;
+}
+/**
+ * Check if a WU ID is exempted from stamp-status validation via config.
+ *
+ * The .lumenflow.config.yaml can specify exemptions for known historical
+ * artifacts that cannot be fixed (e.g., WU-307, WU-311, WU-1152).
+ *
+ * @param {string} id - WU ID to check
+ * @param {string[]|null|undefined} exemptions - List of exempted WU IDs from config
+ * @returns {boolean} True if the WU is exempted
+ *
+ * @example
+ * isExemptedFromStampStatusCheck('WU-307', ['WU-307', 'WU-311']) // true
+ * isExemptedFromStampStatusCheck('WU-999', ['WU-307', 'WU-311']) // false
+ */
+export function isExemptedFromStampStatusCheck(id, exemptions) {
+    if (!id || !exemptions || !Array.isArray(exemptions)) {
+        return false;
+    }
+    return exemptions.includes(id);
+}
+/**
+ * Determine if a WU should be exempted from stamp-status validation.
+ *
+ * A WU is exempted if:
+ * 1. It's explicitly listed in the config exemptions, OR
+ * 2. It's a legacy stamped WU (has stamp but status != done) AND has a legacy parent-only lane
+ *
+ * @param {object} wu - The parsed WU YAML object
+ * @param {Set<string>} stampedIds - Set of WU IDs that have .done stamp files
+ * @param {string[]} exemptions - List of exempted WU IDs from config
+ * @returns {{ exempted: boolean, reason: string|null }} Whether exempted and why
+ */
+export function shouldExemptFromStampStatusCheck(wu, stampedIds, exemptions = []) {
+    const id = wu?.id;
+    // Check config exemption first
+    if (isExemptedFromStampStatusCheck(id, exemptions)) {
+        return { exempted: true, reason: 'config exemption' };
+    }
+    // Check if it's a legacy stamped WU with a legacy lane
+    if (isLegacyStampedWU(wu, stampedIds)) {
+        const lane = wu.lane;
+        if (isLegacyParentOnlyLane(lane)) {
+            return { exempted: true, reason: 'legacy parent-only lane with stamp' };
+        }
+    }
+    return { exempted: false, reason: null };
+}

package/dist/stamp-utils.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Stamp File Utilities
+ *
+ * Centralized stamp file operations (create, validate)
+ * Eliminates magic string for stamp body template
+ *
+ * WU-2242: Added format validation for corrupted stamp detection
+ *
+ * Stamp files (.beacon/stamps/WU-{id}.done) serve as completion markers
+ * Used by wu:done, wu:recovery, and validation tools
+ */
+/**
+ * Stamp format error types (WU-2242)
+ * @readonly
+ * @enum {string}
+ */
+export declare const STAMP_FORMAT_ERRORS: Readonly<{
+    /** Stamp file is empty or contains only whitespace */
+    EMPTY_FILE: "EMPTY_FILE";
+    /** Missing WU identifier line (format: WU WU-123 (em dash) Title) */
+    MISSING_WU_LINE: "MISSING_WU_LINE";
+    /** Missing Completed: YYYY-MM-DD line */
+    MISSING_COMPLETED_LINE: "MISSING_COMPLETED_LINE";
+    /** Date is not in valid YYYY-MM-DD format or is invalid */
+    INVALID_DATE_FORMAT: "INVALID_DATE_FORMAT";
+    /** WU ID in stamp does not match expected ID */
+    WU_ID_MISMATCH: "WU_ID_MISMATCH";
+}>;
+/**
+ * Create stamp file (idempotent - safe to call multiple times)
+ *
+ * @param {object} params - Parameters
+ * @param {string} params.id - WU ID (e.g., 'WU-123')
+ * @param {string} params.title - WU title
+ * @returns {object} Result { created: boolean, path: string, reason?: string }
+ */
+export declare function createStamp({ id, title }: {
+    id: any;
+    title: any;
+}): {
+    created: boolean;
+    path: string;
+    reason: string;
+} | {
+    created: boolean;
+    path: string;
+    reason?: undefined;
+};
+/**
+ * Validate stamp exists
+ *
+ * @param {string} stampPath - Path to stamp file
+ * @returns {boolean} True if stamp exists
+ */
+export declare function validateStamp(stampPath: any): boolean;
+/**
+ * Get stamp path using WU_PATHS (consistent with codebase)
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Absolute path to stamp file
+ */
+export declare function getStampPath(id: any): string;
+/**
+ * Validate stamp file format (WU-2242)
+ *
+ * Expected format:
+ * ```
+ * WU WU-123 (em dash) Title here
+ * Completed: 2025-12-31
+ * ```
+ *
+ * @param {string} wuId - WU ID (e.g., 'WU-123')
+ * @param {string} [projectRoot=process.cwd()] - Project root directory
+ * @returns {Promise<{valid: boolean, errors: string[], missing?: boolean}>}
+ */
+export declare function validateStampFormat(wuId: any, projectRoot?: string): Promise<{
+    valid: boolean;
+    errors: any[];
+    missing: boolean;
+} | {
+    valid: boolean;
+    errors: any[];
+    missing?: undefined;
+}>;
+/**
+ * Parsed stamp metadata
+ */
+interface StampMetadata {
+    wuId?: string;
+    title?: string;
+    completedDate?: string;
+}
+/**
+ * Parse stamp content to extract metadata
+ *
+ * @param {string} content - Stamp file content
+ * @returns {StampMetadata}
+ */
+export declare function parseStampContent(content: string): StampMetadata;
+export {};