@lumenflow/core 1.0.0

package/dist/domain/orchestration.constants.js

@@ -0,0 +1,97 @@
+/**
+ * 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 const DOD_TOTAL = 11;
+/**
+ * Valid lane names in the LumenFlow system.
+ * Used for type-safe lane validation.
+ */
+export const LANES = [
+    'Intelligence',
+    'Experience',
+    'Core Systems',
+    'Operations',
+    'Discovery',
+];
+/**
+ * Known agent names in the orchestration system.
+ * Includes both mandatory (Tier 1) and suggested (Tier 2) agents.
+ */
+export const AGENT_NAMES = [
+    'security-auditor',
+    'beacon-guardian',
+    'test-engineer',
+    'code-reviewer',
+];
+/**
+ * Alert severity levels for dashboard display.
+ * HIGH = action required immediately
+ * MEDIUM = action suggested
+ * LOW = informational
+ */
+export const SEVERITY_LEVELS = ['high', 'medium', 'low'];
+/**
+ * Default timeline window for dashboard display (hours).
+ */
+export const TIMELINE_WINDOW_HOURS = 24;
+/**
+ * Maximum alerts to display in dashboard.
+ */
+export const MAX_ALERTS_DISPLAY = 10;
+/**
+ * Agent result statuses for WU progress tracking.
+ */
+export const AGENT_RESULT_STATUSES = ['pending', 'pass', 'fail', 'skipped'];
+/**
+ * Timeline event types for orchestration history.
+ */
+export const TIMELINE_EVENT_TYPES = ['claim', 'done', 'block', 'agent', 'gates'];
+/**
+ * Event severity levels for timeline display.
+ */
+export const EVENT_SEVERITY_LEVELS = ['info', 'warning', 'error'];
+/**
+ * User choice options for execution plan confirmation.
+ */
+export const USER_CHOICE_OPTIONS = ['approve', 'reject', 'edit'];
+/**
+ * Mandatory agent names (subset of AGENT_NAMES)
+ */
+export const MANDATORY_AGENT_NAMES = ['security-auditor', 'beacon-guardian'];
+/**
+ * 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 const MANDATORY_TRIGGERS = {
+    'security-auditor': ['supabase/migrations/**', '**/auth/**', '**/rls/**', '**/permissions/**'],
+    'beacon-guardian': ['**/prompts/**', '**/classification/**', '**/detector/**', '**/llm/**'],
+};
+/**
+ * File system paths for metrics collection.
+ * Used by FileSystemMetricsCollector to avoid hardcoded strings.
+ */
+export const FILESYSTEM_PATHS = {
+    WU_DIR: 'docs/04-operations/tasks/wu',
+    STATUS_FILE: 'docs/04-operations/tasks/status.md',
+    BACKLOG_FILE: 'docs/04-operations/tasks/backlog.md',
+    TELEMETRY_DIR: '.beacon/telemetry',
+    STAMPS_DIR: '.beacon/stamps',
+    SESSION_FILE: '.beacon/sessions/current.json',
+};

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

@@ -0,0 +1,280 @@
+/**
+ * Orchestration Domain Schemas
+ *
+ * Zod schemas for runtime validation of orchestration domain types.
+ * Single source of truth - types are inferred from these schemas.
+ *
+ * @module orchestration.schemas
+ * @see {@link ./orchestration.types.mjs} - Types inferred from these schemas
+ * @see {@link ./orchestration.constants.mjs} - Constants used in validation
+ */
+import { z } from 'zod';
+/**
+ * Schema for global orchestration status.
+ * Shows high-level dashboard metrics at a glance.
+ */
+export declare const GlobalStatusSchema: z.ZodObject<{
+    activeWUs: z.ZodNumber;
+    completed24h: z.ZodNumber;
+    blocked: z.ZodNumber;
+    gatesFailing: z.ZodNumber;
+    longestRunning: z.ZodNullable<z.ZodObject<{
+        wuId: z.ZodString;
+        lane: z.ZodEnum<{
+            Operations: "Operations";
+            Intelligence: "Intelligence";
+            Experience: "Experience";
+            "Core Systems": "Core Systems";
+            Discovery: "Discovery";
+        }>;
+        durationMs: z.ZodNumber;
+    }, z.core.$strip>>;
+    pendingMandatory: z.ZodArray<z.ZodObject<{
+        wuId: z.ZodString;
+        agent: z.ZodEnum<{
+            "security-auditor": "security-auditor";
+            "beacon-guardian": "beacon-guardian";
+            "test-engineer": "test-engineer";
+            "code-reviewer": "code-reviewer";
+        }>;
+    }, z.core.$strip>>;
+    activeSession: z.ZodNullable<z.ZodObject<{
+        sessionId: z.ZodString;
+        wuId: z.ZodString;
+        started: z.ZodString;
+        contextTier: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+        incidentsLogged: z.ZodNumber;
+    }, z.core.$strip>>;
+    worktreesWithUncommittedChanges: z.ZodArray<z.ZodObject<{
+        wuId: z.ZodString;
+        worktreePath: z.ZodString;
+        uncommittedFileCount: z.ZodNumber;
+        lastActivityTimestamp: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Schema for per-agent metrics.
+ * Tracks invocation counts, pass rates, and timing.
+ */
+export declare const AgentMetricSchema: z.ZodObject<{
+    invoked: z.ZodNumber;
+    passRate: z.ZodNumber;
+    avgDurationMs: z.ZodNumber;
+    lastRun: z.ZodNullable<z.ZodObject<{
+        wuId: z.ZodString;
+        timestamp: z.ZodString;
+        result: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Schema for WU progress tracking.
+ * Shows DoD progress and agent status per WU.
+ */
+export declare const WUProgressSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    lane: z.ZodEnum<{
+        Operations: "Operations";
+        Intelligence: "Intelligence";
+        Experience: "Experience";
+        "Core Systems": "Core Systems";
+        Discovery: "Discovery";
+    }>;
+    title: z.ZodString;
+    dodProgress: z.ZodNumber;
+    dodTotal: z.ZodLiteral<11>;
+    agents: z.ZodRecord<z.ZodString, z.ZodEnum<{
+        pass: "pass";
+        pending: "pending";
+        fail: "fail";
+        skipped: "skipped";
+    }>>;
+    headline: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for timeline events.
+ * Records orchestration history for dashboard display.
+ */
+export declare const TimelineEventSchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    event: z.ZodEnum<{
+        done: "done";
+        gates: "gates";
+        agent: "agent";
+        block: "block";
+        claim: "claim";
+    }>;
+    wuId: z.ZodString;
+    detail: z.ZodString;
+    severity: z.ZodEnum<{
+        info: "info";
+        error: "error";
+        warning: "warning";
+    }>;
+}, z.core.$strip>;
+/**
+ * Schema for dashboard alerts.
+ * Highlights items requiring attention.
+ */
+export declare const AlertSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    message: z.ZodString;
+    wuId: z.ZodString;
+    action: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for orchestration suggestions.
+ * Recommendations for next actions.
+ */
+export declare const SuggestionSchema: z.ZodObject<{
+    id: z.ZodString;
+    priority: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    action: z.ZodString;
+    reason: z.ZodString;
+    command: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for execution plans.
+ * Proposed sequence of orchestration actions.
+ */
+export declare const ExecutionPlanSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        order: z.ZodNumber;
+        agent: z.ZodOptional<z.ZodString>;
+        action: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            pass: "pass";
+            pending: "pending";
+            fail: "fail";
+            skipped: "skipped";
+        }>;
+    }, z.core.$strip>>;
+    estimatedTokens: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Schema for user choices on execution plans.
+ */
+export declare const UserChoiceSchema: z.ZodObject<{
+    choice: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+        edit: "edit";
+    }>;
+    modifications: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Schema for complete dashboard data.
+ * Aggregates all data needed for dashboard rendering.
+ */
+export declare const DashboardDataSchema: z.ZodObject<{
+    globalStatus: z.ZodObject<{
+        activeWUs: z.ZodNumber;
+        completed24h: z.ZodNumber;
+        blocked: z.ZodNumber;
+        gatesFailing: z.ZodNumber;
+        longestRunning: z.ZodNullable<z.ZodObject<{
+            wuId: z.ZodString;
+            lane: z.ZodEnum<{
+                Operations: "Operations";
+                Intelligence: "Intelligence";
+                Experience: "Experience";
+                "Core Systems": "Core Systems";
+                Discovery: "Discovery";
+            }>;
+            durationMs: z.ZodNumber;
+        }, z.core.$strip>>;
+        pendingMandatory: z.ZodArray<z.ZodObject<{
+            wuId: z.ZodString;
+            agent: z.ZodEnum<{
+                "security-auditor": "security-auditor";
+                "beacon-guardian": "beacon-guardian";
+                "test-engineer": "test-engineer";
+                "code-reviewer": "code-reviewer";
+            }>;
+        }, z.core.$strip>>;
+        activeSession: z.ZodNullable<z.ZodObject<{
+            sessionId: z.ZodString;
+            wuId: z.ZodString;
+            started: z.ZodString;
+            contextTier: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+            incidentsLogged: z.ZodNumber;
+        }, z.core.$strip>>;
+        worktreesWithUncommittedChanges: z.ZodArray<z.ZodObject<{
+            wuId: z.ZodString;
+            worktreePath: z.ZodString;
+            uncommittedFileCount: z.ZodNumber;
+            lastActivityTimestamp: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    agentMetrics: z.ZodRecord<z.ZodString, z.ZodObject<{
+        invoked: z.ZodNumber;
+        passRate: z.ZodNumber;
+        avgDurationMs: z.ZodNumber;
+        lastRun: z.ZodNullable<z.ZodObject<{
+            wuId: z.ZodString;
+            timestamp: z.ZodString;
+            result: z.ZodEnum<{
+                pass: "pass";
+                fail: "fail";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    wuProgress: z.ZodArray<z.ZodObject<{
+        wuId: z.ZodString;
+        lane: z.ZodEnum<{
+            Operations: "Operations";
+            Intelligence: "Intelligence";
+            Experience: "Experience";
+            "Core Systems": "Core Systems";
+            Discovery: "Discovery";
+        }>;
+        title: z.ZodString;
+        dodProgress: z.ZodNumber;
+        dodTotal: z.ZodLiteral<11>;
+        agents: z.ZodRecord<z.ZodString, z.ZodEnum<{
+            pass: "pass";
+            pending: "pending";
+            fail: "fail";
+            skipped: "skipped";
+        }>>;
+        headline: z.ZodString;
+    }, z.core.$strip>>;
+    timeline: z.ZodArray<z.ZodObject<{
+        timestamp: z.ZodString;
+        event: z.ZodEnum<{
+            done: "done";
+            gates: "gates";
+            agent: "agent";
+            block: "block";
+            claim: "claim";
+        }>;
+        wuId: z.ZodString;
+        detail: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            error: "error";
+            warning: "warning";
+        }>;
+    }, z.core.$strip>>;
+    alerts: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+        message: z.ZodString;
+        wuId: z.ZodString;
+        action: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/domain/orchestration.schemas.js

@@ -0,0 +1,211 @@
+/**
+ * Orchestration Domain Schemas
+ *
+ * Zod schemas for runtime validation of orchestration domain types.
+ * Single source of truth - types are inferred from these schemas.
+ *
+ * @module orchestration.schemas
+ * @see {@link ./orchestration.types.mjs} - Types inferred from these schemas
+ * @see {@link ./orchestration.constants.mjs} - Constants used in validation
+ */
+import { z } from 'zod';
+import { LANES, AGENT_NAMES, SEVERITY_LEVELS, AGENT_RESULT_STATUSES, TIMELINE_EVENT_TYPES, EVENT_SEVERITY_LEVELS, USER_CHOICE_OPTIONS, DOD_TOTAL, } from './orchestration.constants.js';
+/**
+ * Schema for the longest running WU information.
+ */
+const LongestRunningSchema = z.object({
+    wuId: z.string().min(1),
+    lane: z.enum(LANES),
+    durationMs: z.number().nonnegative(),
+});
+/**
+ * Schema for pending mandatory agent information.
+ */
+const PendingMandatorySchema = z.object({
+    wuId: z.string().min(1),
+    agent: z.enum(AGENT_NAMES),
+});
+/**
+ * Schema for active agent session (WU-1438).
+ */
+const ActiveSessionSchema = z.object({
+    sessionId: z.string().uuid(),
+    wuId: z.string().min(1),
+    started: z.string().datetime(),
+    contextTier: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+    incidentsLogged: z.number().int().nonnegative(),
+});
+/**
+ * Schema for worktree with uncommitted changes (WU-1748).
+ * Used for cross-agent visibility of abandoned WU work.
+ */
+const WorktreeWithUncommittedChangesSchema = z.object({
+    /** WU ID extracted from worktree branch name */
+    wuId: z.string().min(1),
+    /** Worktree directory path */
+    worktreePath: z.string().min(1),
+    /** Number of uncommitted files */
+    uncommittedFileCount: z.number().int().nonnegative(),
+    /** Last git activity timestamp (ISO 8601) */
+    lastActivityTimestamp: z.string(),
+});
+/**
+ * Schema for global orchestration status.
+ * Shows high-level dashboard metrics at a glance.
+ */
+export const GlobalStatusSchema = z.object({
+    /** Number of WUs currently in progress */
+    activeWUs: z.number().int().nonnegative(),
+    /** Number of WUs completed in the last 24 hours */
+    completed24h: z.number().int().nonnegative(),
+    /** Number of currently blocked WUs */
+    blocked: z.number().int().nonnegative(),
+    /** Number of WUs with failing gates */
+    gatesFailing: z.number().int().nonnegative(),
+    /** Information about the longest running WU, or null if none active */
+    longestRunning: LongestRunningSchema.nullable(),
+    /** List of WUs with pending mandatory agents */
+    pendingMandatory: z.array(PendingMandatorySchema),
+    /** Current active agent session, or null if none (WU-1438) */
+    activeSession: ActiveSessionSchema.nullable(),
+    /** Worktrees with uncommitted changes for cross-agent visibility (WU-1748) */
+    worktreesWithUncommittedChanges: z.array(WorktreeWithUncommittedChangesSchema),
+});
+/**
+ * Schema for last run information within agent metrics.
+ */
+const LastRunSchema = z.object({
+    wuId: z.string().min(1),
+    timestamp: z.string().datetime(),
+    result: z.enum(['pass', 'fail']),
+});
+/**
+ * Schema for per-agent metrics.
+ * Tracks invocation counts, pass rates, and timing.
+ */
+export const AgentMetricSchema = z.object({
+    /** Total number of times this agent has been invoked */
+    invoked: z.number().int().nonnegative(),
+    /** Pass rate as percentage (0-100) */
+    passRate: z.number().min(0).max(100),
+    /** Average duration in milliseconds */
+    avgDurationMs: z.number().nonnegative(),
+    /** Information about the most recent run, or null if never run */
+    lastRun: LastRunSchema.nullable(),
+});
+/**
+ * Schema for WU progress tracking.
+ * Shows DoD progress and agent status per WU.
+ */
+export const WUProgressSchema = z.object({
+    /** Work Unit ID (e.g., "WU-1234") */
+    wuId: z.string().min(1),
+    /** Lane the WU is assigned to */
+    lane: z.enum(LANES),
+    /** Human-readable title of the WU */
+    title: z.string().min(1),
+    /** Current DoD checkpoint progress (0 to DOD_TOTAL) */
+    dodProgress: z.number().int().min(0).max(DOD_TOTAL),
+    /** Total DoD checkpoints (always DOD_TOTAL) */
+    dodTotal: z.literal(DOD_TOTAL),
+    /** Status of each agent that has been or should be run */
+    agents: z.record(z.string(), z.enum(AGENT_RESULT_STATUSES)),
+    /** Tufte-style headline sentence describing current state */
+    headline: z.string(),
+});
+/**
+ * Schema for timeline events.
+ * Records orchestration history for dashboard display.
+ */
+export const TimelineEventSchema = z.object({
+    /** ISO 8601 timestamp of the event */
+    timestamp: z.string().datetime(),
+    /** Type of orchestration event */
+    event: z.enum(TIMELINE_EVENT_TYPES),
+    /** Associated Work Unit ID */
+    wuId: z.string().min(1),
+    /** Human-readable event description */
+    detail: z.string(),
+    /** Visual severity for display */
+    severity: z.enum(EVENT_SEVERITY_LEVELS),
+});
+/**
+ * Schema for dashboard alerts.
+ * Highlights items requiring attention.
+ */
+export const AlertSchema = z.object({
+    /** Alert severity level */
+    severity: z.enum(SEVERITY_LEVELS),
+    /** Human-readable alert message */
+    message: z.string().min(1),
+    /** Associated Work Unit ID */
+    wuId: z.string().min(1),
+    /** Suggested action or command */
+    action: z.string().min(1),
+});
+/**
+ * Schema for orchestration suggestions.
+ * Recommendations for next actions.
+ */
+export const SuggestionSchema = z.object({
+    /** Unique suggestion identifier */
+    id: z.string().min(1),
+    /** Suggestion priority level */
+    priority: z.enum(SEVERITY_LEVELS),
+    /** Short action description */
+    action: z.string().min(1),
+    /** Reason for the suggestion */
+    reason: z.string().min(1),
+    /** CLI command to execute the suggestion */
+    command: z.string().min(1),
+});
+/**
+ * Schema for execution plan steps.
+ */
+const ExecutionStepSchema = z.object({
+    /** Execution order (1-based) */
+    order: z.number().int().positive(),
+    /** Agent to run (if applicable) */
+    agent: z.string().optional(),
+    /** Action to perform (if not an agent) */
+    action: z.string().optional(),
+    /** Step execution status */
+    status: z.enum(AGENT_RESULT_STATUSES),
+});
+/**
+ * Schema for execution plans.
+ * Proposed sequence of orchestration actions.
+ */
+export const ExecutionPlanSchema = z.object({
+    /** Work Unit ID this plan is for */
+    wuId: z.string().min(1),
+    /** Ordered list of steps to execute */
+    steps: z.array(ExecutionStepSchema),
+    /** Estimated token cost for the full plan */
+    estimatedTokens: z.number().int().nonnegative(),
+});
+/**
+ * Schema for user choices on execution plans.
+ */
+export const UserChoiceSchema = z.object({
+    /** User's choice */
+    choice: z.enum(USER_CHOICE_OPTIONS),
+    /** Modifications if choice is 'edit' */
+    modifications: z.array(z.string()).optional(),
+});
+/**
+ * Schema for complete dashboard data.
+ * Aggregates all data needed for dashboard rendering.
+ */
+export const DashboardDataSchema = z.object({
+    /** Global status metrics */
+    globalStatus: GlobalStatusSchema,
+    /** Per-agent metrics keyed by agent name */
+    agentMetrics: z.record(z.string(), AgentMetricSchema),
+    /** Progress for all active WUs */
+    wuProgress: z.array(WUProgressSchema),
+    /** Recent timeline events */
+    timeline: z.array(TimelineEventSchema),
+    /** Current alerts */
+    alerts: z.array(AlertSchema),
+});