@lumenflow/core 1.0.0

package/dist/dependency-guard.js

@@ -0,0 +1,142 @@
+/**
+ * Dependency Guard (WU-1783)
+ *
+ * Detects dependency-mutating pnpm commands and provides blocking/guidance
+ * for worktree discipline enforcement.
+ *
+ * Used by:
+ * - pre-tool-use-hook.sh to block dependency mutations on main
+ * - deps:add and deps:remove wrapper commands
+ *
+ * @see {@link .claude/hooks/pre-tool-use-hook.sh} - PreToolUse hook
+ * @see {@link tools/deps-add.mjs} - Safe wrapper for pnpm add
+ * @see {@link tools/deps-remove.mjs} - Safe wrapper for pnpm remove
+ */
+import { EMOJI } from './wu-constants.js';
+/**
+ * pnpm subcommands that mutate dependencies.
+ *
+ * These commands modify package.json, pnpm-lock.yaml, and/or node_modules.
+ * Running them on main checkout violates worktree isolation.
+ *
+ * Includes both full names and shorthand aliases:
+ * - add: Add packages to dependencies
+ * - install/i: Install packages from lockfile
+ * - remove/rm/uninstall: Remove packages from dependencies
+ * - update/up: Update packages to latest
+ */
+export const DEPENDENCY_MUTATING_COMMANDS = [
+    'add',
+    'install',
+    'i', // shorthand for install
+    'remove',
+    'rm', // shorthand for remove
+    'uninstall', // alias for remove
+    'update',
+    'up', // shorthand for update
+];
+/**
+ * Check if a command is a dependency-mutating pnpm command.
+ *
+ * @param {string|null|undefined} command - Command string to check
+ * @returns {boolean} True if the command mutates dependencies
+ *
+ * @example
+ * isDependencyMutatingCommand('pnpm add react'); // true
+ * isDependencyMutatingCommand('pnpm run test'); // false
+ * isDependencyMutatingCommand('npm install'); // false (not pnpm)
+ */
+export function isDependencyMutatingCommand(command) {
+    // Handle null/undefined/empty
+    if (!command) {
+        return false;
+    }
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return false;
+    }
+    // Only check pnpm commands
+    if (!trimmed.startsWith('pnpm ') && trimmed !== 'pnpm') {
+        return false;
+    }
+    // Extract the subcommand (first argument after 'pnpm')
+    // Handle: pnpm add, pnpm --filter web add, etc.
+    const parts = trimmed.split(/\s+/);
+    // Find the first non-flag argument after 'pnpm'
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        // Skip flags (start with -)
+        if (part.startsWith('-')) {
+            // Handle --filter=value format
+            if (part.includes('=')) {
+                continue;
+            }
+            // Handle --filter value format (skip next part too)
+            if (part === '--filter' || part === '-F') {
+                i++; // Skip the filter value
+                continue;
+            }
+            continue;
+        }
+        // This is the subcommand
+        return DEPENDENCY_MUTATING_COMMANDS.includes(part);
+    }
+    return false;
+}
+/**
+ * Build a blocking message for dependency-mutating commands on main.
+ *
+ * @param {string} command - The blocked command
+ * @returns {string} Formatted error message with guidance
+ *
+ * @example
+ * const message = buildDependencyBlockMessage('pnpm add react');
+ * // Returns multi-line message with guidance
+ */
+export function buildDependencyBlockMessage(command) {
+    // Extract the pnpm subcommand for targeted guidance
+    const parts = command.trim().split(/\s+/);
+    let subcommand = '';
+    for (let i = 1; i < parts.length; i++) {
+        if (!parts[i].startsWith('-')) {
+            subcommand = parts[i];
+            break;
+        }
+    }
+    const wrapperCommand = subcommand === 'add' || subcommand === 'i' || subcommand === 'install'
+        ? 'pnpm deps:add'
+        : subcommand === 'remove' || subcommand === 'rm' || subcommand === 'uninstall'
+            ? 'pnpm deps:remove'
+            : 'the corresponding deps:* wrapper';
+    return `
+${EMOJI.BLOCKED} BLOCKED: Dependency mutation on main checkout
+
+Command: ${command}
+
+REASON: Running ${subcommand || 'dependency'} commands on main bypasses worktree isolation.
+This can cause:
+  - Dirty lockfile diffs that block other agents
+  - pnpm virtual-store mismatches
+  - Wedged wu:done workflows
+
+TO FIX:
+  1. Claim a WU first (if not already claimed):
+     pnpm wu:claim --id WU-XXXX --lane "Your Lane"
+
+  2. Navigate to the worktree:
+     cd worktrees/<lane>-wu-<id>/
+
+  3. Run your command there, or use the safe wrapper:
+     ${wrapperCommand}
+
+The safe wrapper (${wrapperCommand}) enforces worktree context
+and runs the underlying pnpm command with proper isolation.
+
+See: CLAUDE.md section 2 'Daily Operating Loop'
+See: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+`;
+}
+/**
+ * Log prefix for dependency guard output
+ */
+export const DEPS_LOG_PREFIX = '[deps-guard]';

package/dist/dependency-validator.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Dependency Validator (WU-2202)
+ *
+ * Validates that required dependencies are available before tool execution.
+ * Prevents silent failures when node_modules is corrupted or incomplete.
+ *
+ * Background: During INIT-038 orchestration, wu:spawn incorrectly reported
+ * lanes as occupied when the yaml package was missing from node_modules.
+ * The tool read lock files but failed silently and reported wrong data.
+ *
+ * This module provides:
+ * - validateDependencies(): Check if packages can be imported
+ * - formatDependencyError(): Generate clear error messages
+ * - TOOL_DEPENDENCIES: Map of tools to their required packages
+ *
+ * @see WU-2202 - Fix false lane occupancy when deps broken
+ */
+/**
+ * Map of tools to their required npm packages.
+ *
+ * Each tool lists the packages it needs to function correctly.
+ * These are checked before tool execution to prevent silent failures.
+ *
+ * @type {Record<string, string[]>}
+ */
+export declare const TOOL_DEPENDENCIES: Readonly<{
+    'wu:spawn': string[];
+    'wu:claim': string[];
+    'wu:done': string[];
+    'wu:block': string[];
+    'wu:unblock': string[];
+    'mem:inbox': string[];
+    'mem:signal': string[];
+    'mem:ready': string[];
+    'mem:checkpoint': string[];
+}>;
+/**
+ * Validate that required dependencies are available.
+ *
+ * @param {string[]} packages - List of package names to check
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ *
+ * @example
+ * const result = await validateDependencies(['yaml', 'ms']);
+ * if (!result.valid) {
+ *   console.error(`Missing: ${result.missing.join(', ')}`);
+ * }
+ */
+export declare function validateDependencies(packages: any): Promise<{
+    valid: boolean;
+    missing: any[];
+}>;
+/**
+ * Format an error message for missing dependencies.
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'wu:spawn')
+ * @param {string[]} missing - List of missing package names
+ * @returns {string} Formatted error message with fix instructions
+ *
+ * @example
+ * const msg = formatDependencyError('wu:spawn', ['yaml']);
+ * console.error(msg);
+ */
+export declare function formatDependencyError(toolName: any, missing: any): string;
+/**
+ * Validate dependencies for wu:spawn.
+ *
+ * Convenience function that validates wu:spawn's required packages.
+ * Called before lane lock check to prevent false positives.
+ *
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ */
+export declare function validateSpawnDependencies(): Promise<{
+    valid: boolean;
+    missing: any[];
+}>;
+/**
+ * Validate dependencies for mem:inbox.
+ *
+ * Convenience function that validates mem:inbox's required packages.
+ *
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ */
+export declare function validateInboxDependencies(): Promise<{
+    valid: boolean;
+    missing: any[];
+}>;
+/**
+ * Validate dependencies for a specific tool.
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'wu:spawn', 'mem:inbox')
+ * @returns {Promise<{valid: boolean, missing: string[], toolName: string}>} Validation result
+ *
+ * @example
+ * const result = await validateToolDependencies('wu:spawn');
+ * if (!result.valid) {
+ *   console.error(formatDependencyError(result.toolName, result.missing));
+ *   process.exit(1);
+ * }
+ */
+export declare function validateToolDependencies(toolName: any): Promise<{
+    toolName: any;
+    valid: boolean;
+    missing: any[];
+}>;

package/dist/dependency-validator.js

@@ -0,0 +1,154 @@
+/**
+ * Dependency Validator (WU-2202)
+ *
+ * Validates that required dependencies are available before tool execution.
+ * Prevents silent failures when node_modules is corrupted or incomplete.
+ *
+ * Background: During INIT-038 orchestration, wu:spawn incorrectly reported
+ * lanes as occupied when the yaml package was missing from node_modules.
+ * The tool read lock files but failed silently and reported wrong data.
+ *
+ * This module provides:
+ * - validateDependencies(): Check if packages can be imported
+ * - formatDependencyError(): Generate clear error messages
+ * - TOOL_DEPENDENCIES: Map of tools to their required packages
+ *
+ * @see WU-2202 - Fix false lane occupancy when deps broken
+ */
+import { EMOJI, LOG_PREFIX } from './wu-constants.js';
+/**
+ * Map of tools to their required npm packages.
+ *
+ * Each tool lists the packages it needs to function correctly.
+ * These are checked before tool execution to prevent silent failures.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const TOOL_DEPENDENCIES = Object.freeze({
+    'wu:spawn': ['yaml', 'minimatch', 'commander'],
+    'wu:claim': ['yaml', 'commander'],
+    'wu:done': ['yaml', 'commander'],
+    'wu:block': ['yaml', 'commander'],
+    'wu:unblock': ['yaml', 'commander'],
+    'mem:inbox': ['ms', 'commander'],
+    'mem:signal': ['commander'],
+    'mem:ready': ['commander'],
+    'mem:checkpoint': ['commander'],
+});
+/**
+ * Check if a package can be imported.
+ *
+ * Uses dynamic import to test package availability.
+ * Returns false if the package cannot be loaded.
+ *
+ * @param {string} packageName - Name of the package to check
+ * @returns {Promise<boolean>} True if package is available
+ */
+async function canImport(packageName) {
+    try {
+        await import(packageName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate that required dependencies are available.
+ *
+ * @param {string[]} packages - List of package names to check
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ *
+ * @example
+ * const result = await validateDependencies(['yaml', 'ms']);
+ * if (!result.valid) {
+ *   console.error(`Missing: ${result.missing.join(', ')}`);
+ * }
+ */
+export async function validateDependencies(packages) {
+    if (!packages || packages.length === 0) {
+        return { valid: true, missing: [] };
+    }
+    const missing = [];
+    for (const pkg of packages) {
+        const available = await canImport(pkg);
+        if (!available) {
+            missing.push(pkg);
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+    };
+}
+/**
+ * Format an error message for missing dependencies.
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'wu:spawn')
+ * @param {string[]} missing - List of missing package names
+ * @returns {string} Formatted error message with fix instructions
+ *
+ * @example
+ * const msg = formatDependencyError('wu:spawn', ['yaml']);
+ * console.error(msg);
+ */
+export function formatDependencyError(toolName, missing) {
+    const packageList = missing.map((p) => `  - ${p}`).join('\n');
+    return `${EMOJI.FAILURE} ${toolName} cannot run: missing dependencies
+
+The following packages are required but not available:
+${packageList}
+
+This usually means node_modules is corrupted or incomplete.
+
+TO FIX:
+  1. Run: pnpm install
+  2. If that fails, try: rm -rf node_modules && pnpm install
+
+If the issue persists, check that the packages are listed in package.json
+and that there are no pnpm virtual-store errors.
+
+${LOG_PREFIX} Missing packages: ${missing.join(', ')}`;
+}
+/**
+ * Validate dependencies for wu:spawn.
+ *
+ * Convenience function that validates wu:spawn's required packages.
+ * Called before lane lock check to prevent false positives.
+ *
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ */
+export async function validateSpawnDependencies() {
+    return validateDependencies(TOOL_DEPENDENCIES['wu:spawn']);
+}
+/**
+ * Validate dependencies for mem:inbox.
+ *
+ * Convenience function that validates mem:inbox's required packages.
+ *
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ */
+export async function validateInboxDependencies() {
+    return validateDependencies(TOOL_DEPENDENCIES['mem:inbox']);
+}
+/**
+ * Validate dependencies for a specific tool.
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'wu:spawn', 'mem:inbox')
+ * @returns {Promise<{valid: boolean, missing: string[], toolName: string}>} Validation result
+ *
+ * @example
+ * const result = await validateToolDependencies('wu:spawn');
+ * if (!result.valid) {
+ *   console.error(formatDependencyError(result.toolName, result.missing));
+ *   process.exit(1);
+ * }
+ */
+export async function validateToolDependencies(toolName) {
+    const deps = TOOL_DEPENDENCIES[toolName] || [];
+    const result = await validateDependencies(deps);
+    return {
+        ...result,
+        toolName,
+    };
+}

package/dist/docs-path-validator.d.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Docs Path Validator
+ *
+ * Validates that files staged for commit in a docs-only WU
+ * are restricted to documentation paths only.
+ *
+ * Allowed paths:
+ * - memory-bank/**
+ * - docs/**
+ * - ai/**
+ * - .claude/**
+ * - *.md (markdown files anywhere)
+ * - .beacon/stamps/**
+ * - .beacon/state/wu-events.jsonl (tooling-managed metadata)
+ *
+ * Forbidden paths:
+ * - apps/**
+ * - packages/** (except test files)
+ * - supabase/**
+ * - tools/** (except test files)
+ */
+/**
+ * Validate a list of staged files for docs-only WU
+ * @param {string[]} stagedFiles - Array of file paths
+ * @returns {{valid: boolean, violations: string[]}} - Validation result
+ */
+export declare function validateDocsOnly(stagedFiles: any): {
+    valid: boolean;
+    violations: any[];
+};
+/**
+ * Get a human-readable description of allowed paths
+ * @returns {string} - Description of allowed paths
+ */
+export declare function getAllowedPathsDescription(): string;

package/dist/docs-path-validator.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Docs Path Validator
+ *
+ * Validates that files staged for commit in a docs-only WU
+ * are restricted to documentation paths only.
+ *
+ * Allowed paths:
+ * - memory-bank/**
+ * - docs/**
+ * - ai/**
+ * - .claude/**
+ * - *.md (markdown files anywhere)
+ * - .beacon/stamps/**
+ * - .beacon/state/wu-events.jsonl (tooling-managed metadata)
+ *
+ * Forbidden paths:
+ * - apps/**
+ * - packages/** (except test files)
+ * - supabase/**
+ * - tools/** (except test files)
+ */
+import path from 'node:path';
+import { WU_EVENTS_FILE_NAME } from './wu-state-store.js';
+import { BEACON_PATHS, DIRECTORIES, FILE_EXTENSIONS, STRING_LITERALS } from './wu-constants.js';
+const POSIX = path.posix;
+const DOCS_ONLY_PREFIXES = Object.freeze([
+    DIRECTORIES.DOCS,
+    DIRECTORIES.AI,
+    DIRECTORIES.CLAUDE,
+    DIRECTORIES.MEMORY_BANK,
+]);
+const TOOLS_TESTS_PREFIX = `${POSIX.join(DIRECTORIES.TOOLS, '__tests__')}${STRING_LITERALS.SLASH}`;
+const STAMPS_PREFIX = `${BEACON_PATHS.STAMPS_DIR}${STRING_LITERALS.SLASH}`;
+const WU_EVENTS_PATH = POSIX.join(BEACON_PATHS.STATE_DIR, WU_EVENTS_FILE_NAME);
+/**
+ * Check if a file path is allowed for docs-only WUs
+ * @param {string} filePath - The file path to validate
+ * @returns {boolean} - True if the path is allowed
+ */
+function isAllowedPath(filePath) {
+    if (!filePath)
+        return false;
+    if (filePath === WU_EVENTS_PATH)
+        return true;
+    if (filePath.startsWith(STAMPS_PREFIX))
+        return true;
+    if (filePath.startsWith(TOOLS_TESTS_PREFIX))
+        return true;
+    if (filePath.startsWith(DIRECTORIES.PACKAGES)) {
+        const testsSegment = `${STRING_LITERALS.SLASH}__tests__${STRING_LITERALS.SLASH}`;
+        return filePath.includes(testsSegment);
+    }
+    if (filePath.endsWith(FILE_EXTENSIONS.MARKDOWN))
+        return true;
+    for (const prefix of DOCS_ONLY_PREFIXES) {
+        if (filePath.startsWith(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Validate a list of staged files for docs-only WU
+ * @param {string[]} stagedFiles - Array of file paths
+ * @returns {{valid: boolean, violations: string[]}} - Validation result
+ */
+export function validateDocsOnly(stagedFiles) {
+    const violations = [];
+    for (const file of stagedFiles) {
+        if (!isAllowedPath(file)) {
+            violations.push(file);
+        }
+    }
+    return {
+        valid: violations.length === 0,
+        violations,
+    };
+}
+/**
+ * Get a human-readable description of allowed paths
+ * @returns {string} - Description of allowed paths
+ */
+export function getAllowedPathsDescription() {
+    return `Docs-only WUs can only modify:
+  - memory-bank/** (task definitions, workflow docs)
+  - ai/** (agent documentation, onboarding)
+  - .claude/** (agent configuration and skills)
+  - docs/** (technical documentation)
+  - *.md (markdown files)
+  - .beacon/stamps/** (completion stamps)
+  - .beacon/state/${WU_EVENTS_FILE_NAME} (WU lifecycle event log)
+  - tools/__tests__/** (test files only)
+  - packages/**/__tests__/** (test files only)`;
+}

package/dist/domain/orchestration.constants.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Orchestration Domain Constants
+ *
+ * Centralised constants for the agent orchestration dashboard.
+ * Avoids magic numbers and hardcoded strings throughout the orchestration layer.
+ *
+ * @module orchestration.constants
+ * @see {@link ../ports/dashboard-renderer.port.mjs} - Uses these constants
+ * @see {@link ../ports/metrics-collector.port.mjs} - Uses these constants
+ */
+/**
+ * Total number of Definition of Done checkpoints.
+ * Used by dashboard to show DoD progress (X/11).
+ */
+export declare const DOD_TOTAL = 11;
+/**
+ * Valid lane names in the LumenFlow system.
+ * Used for type-safe lane validation.
+ */
+export declare const LANES: readonly ["Intelligence", "Experience", "Core Systems", "Operations", "Discovery"];
+/** Type for valid lane names */
+export type Lane = (typeof LANES)[number];
+/**
+ * Known agent names in the orchestration system.
+ * Includes both mandatory (Tier 1) and suggested (Tier 2) agents.
+ */
+export declare const AGENT_NAMES: readonly ["security-auditor", "beacon-guardian", "test-engineer", "code-reviewer"];
+/** Type for agent names */
+export type AgentName = (typeof AGENT_NAMES)[number];
+/**
+ * Alert severity levels for dashboard display.
+ * HIGH = action required immediately
+ * MEDIUM = action suggested
+ * LOW = informational
+ */
+export declare const SEVERITY_LEVELS: readonly ["high", "medium", "low"];
+/** Type for severity levels */
+export type SeverityLevel = (typeof SEVERITY_LEVELS)[number];
+/**
+ * Default timeline window for dashboard display (hours).
+ */
+export declare const TIMELINE_WINDOW_HOURS = 24;
+/**
+ * Maximum alerts to display in dashboard.
+ */
+export declare const MAX_ALERTS_DISPLAY = 10;
+/**
+ * Agent result statuses for WU progress tracking.
+ */
+export declare const AGENT_RESULT_STATUSES: readonly ["pending", "pass", "fail", "skipped"];
+/** Type for agent result statuses */
+export type AgentResultStatus = (typeof AGENT_RESULT_STATUSES)[number];
+/**
+ * Timeline event types for orchestration history.
+ */
+export declare const TIMELINE_EVENT_TYPES: readonly ["claim", "done", "block", "agent", "gates"];
+/** Type for timeline event types */
+export type TimelineEventType = (typeof TIMELINE_EVENT_TYPES)[number];
+/**
+ * Event severity levels for timeline display.
+ */
+export declare const EVENT_SEVERITY_LEVELS: readonly ["info", "warning", "error"];
+/** Type for event severity levels */
+export type EventSeverityLevel = (typeof EVENT_SEVERITY_LEVELS)[number];
+/**
+ * User choice options for execution plan confirmation.
+ */
+export declare const USER_CHOICE_OPTIONS: readonly ["approve", "reject", "edit"];
+/** Type for user choice options */
+export type UserChoiceOption = (typeof USER_CHOICE_OPTIONS)[number];
+/**
+ * Mandatory agent names (subset of AGENT_NAMES)
+ */
+export declare const MANDATORY_AGENT_NAMES: readonly ["security-auditor", "beacon-guardian"];
+/** Type for mandatory agent names */
+export type MandatoryAgentName = (typeof MANDATORY_AGENT_NAMES)[number];
+/**
+ * Mandatory agent triggers - glob patterns that indicate when agents must be invoked.
+ * Uses minimatch patterns (NOT regex) for file path matching.
+ *
+ * @example
+ * // Check if a path triggers security-auditor:
+ * import { minimatch } from 'minimatch';
+ * const triggers = MANDATORY_TRIGGERS['security-auditor'];
+ * const shouldTrigger = triggers.some(pattern => minimatch(filePath, pattern));
+ */
+export declare const MANDATORY_TRIGGERS: Record<MandatoryAgentName, readonly string[]>;
+/**
+ * File system paths for metrics collection.
+ * Used by FileSystemMetricsCollector to avoid hardcoded strings.
+ */
+export declare const FILESYSTEM_PATHS: {
+    WU_DIR: string;
+    STATUS_FILE: string;
+    BACKLOG_FILE: string;
+    TELEMETRY_DIR: string;
+    STAMPS_DIR: string;
+    SESSION_FILE: string;
+};