@lumenflow/cli 4.23.0 → 5.0.0

package/packs/software-delivery/src/domain/orchestration.constants.ts

@@ -0,0 +1,168 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * 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.ts} - Uses these constants
+ * @see {@link ../ports/metrics-collector.port.ts} - Uses these constants
+ */
+
+import { DIRECTORIES, LUMENFLOW_PATHS } from '../constants/wu-paths-constants.js';
+
+/**
+ * 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.
+ *
+ * Note: This should match the lanes defined in workspace.yaml.
+ * These are LumenFlow framework lanes, not application-specific lanes.
+ */
+export const LANES = [
+  'Framework: Core',
+  'Framework: CLI',
+  'Framework: Memory',
+  'Framework: Agent',
+  'Framework: Metrics',
+  'Framework: Initiatives',
+  'Framework: Shims',
+  'Operations: Infrastructure',
+  'Operations: CI/CD',
+  'Content: Documentation',
+] as const;
+
+/** 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.
+ *
+ * Note: These are LumenFlow framework agents defined in .claude/agents/.
+ * Application-specific agents should be configured separately.
+ */
+export const AGENT_NAMES = [
+  'general-purpose',
+  'lumenflow-pm',
+  'test-engineer',
+  'code-reviewer',
+  'bug-triage',
+  'lumenflow-enforcer',
+  'lumenflow-doc-sync',
+] as const;
+
+/** 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 const SEVERITY_LEVELS = ['high', 'medium', 'low'] as const;
+
+/** Type for severity levels */
+export type SeverityLevel = (typeof SEVERITY_LEVELS)[number];
+
+/**
+ * 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'] as const;
+
+/** Type for agent result statuses */
+export type AgentResultStatus = (typeof AGENT_RESULT_STATUSES)[number];
+
+/**
+ * Timeline event types for orchestration history.
+ */
+export const TIMELINE_EVENT_TYPES = ['claim', 'done', 'block', 'agent', 'gates'] as const;
+
+/** Type for timeline event types */
+export type TimelineEventType = (typeof TIMELINE_EVENT_TYPES)[number];
+
+/**
+ * Event severity levels for timeline display.
+ */
+export const EVENT_SEVERITY_LEVELS = ['info', 'warning', 'error'] as const;
+
+/** Type for event severity levels */
+export type EventSeverityLevel = (typeof EVENT_SEVERITY_LEVELS)[number];
+
+/**
+ * User choice options for execution plan confirmation.
+ */
+export const USER_CHOICE_OPTIONS = ['approve', 'reject', 'edit'] as const;
+
+/** Type for user choice options */
+export type UserChoiceOption = (typeof USER_CHOICE_OPTIONS)[number];
+
+/**
+ * Mandatory agent names (subset of AGENT_NAMES)
+ *
+ * Note: For LumenFlow framework development, mandatory agents are not currently
+ * enforced since this is a workflow framework, not an application with domain-specific concerns.
+ * Projects using LumenFlow can define their own mandatory agents in their config.
+ *
+ * The test-engineer and code-reviewer agents are suggested but not mandatory.
+ */
+export const MANDATORY_AGENT_NAMES = [] as const;
+
+/** 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.
+ *
+ * Note: For LumenFlow framework development, this is empty since we don't have
+ * application-specific concerns. Projects using LumenFlow
+ * should configure their own triggers based on their domain requirements.
+ *
+ * Example application-specific triggers (configure in your project):
+ * - security-auditor: supabase/migrations/**, auth/**, rls/**
+ * - llm-reviewer: prompts/**, llm/**
+ *
+ * Usage:
+ * ```typescript
+ * import { minimatch } from 'minimatch';
+ * const triggers = MANDATORY_TRIGGERS['my-agent'];
+ * const shouldTrigger = triggers?.some(pattern => minimatch(filePath, pattern));
+ * ```
+ */
+export const MANDATORY_TRIGGERS: Record<string, readonly string[]> = {
+  // No mandatory triggers for LumenFlow framework development.
+  // Projects should configure their own triggers based on their domain.
+};
+
+/**
+ * File system paths for metrics collection.
+ * Used by FileSystemMetricsCollector to avoid hardcoded strings.
+ */
+export const FILESYSTEM_PATHS = {
+  WU_DIR: DIRECTORIES.WU_DIR,
+  STATUS_FILE: DIRECTORIES.STATUS_PATH,
+  BACKLOG_FILE: DIRECTORIES.BACKLOG_PATH,
+  TELEMETRY_DIR: LUMENFLOW_PATHS.TELEMETRY,
+  STAMPS_DIR: LUMENFLOW_PATHS.STAMPS_DIR,
+  SESSION_FILE: LUMENFLOW_PATHS.SESSION_CURRENT,
+};

package/packs/software-delivery/src/domain/orchestration.schemas.ts

@@ -0,0 +1,239 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * 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.ts} - Types inferred from these schemas
+ * @see {@link ./orchestration.constants.ts} - 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),
+});

package/packs/software-delivery/src/domain/orchestration.types.ts

@@ -0,0 +1,178 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Orchestration Domain Types
+ *
+ * TypeScript types inferred from Zod schemas.
+ * Single source of truth - schemas validate at runtime, types at compile time.
+ *
+ * @module orchestration.types
+ * @see {@link ./orchestration.schemas.ts} - Schemas these types are inferred from
+ * @see {@link ./orchestration.constants.ts} - Constants and derived types
+ */
+
+import type { z } from 'zod';
+import type {
+  GlobalStatusSchema,
+  AgentMetricSchema,
+  WUProgressSchema,
+  TimelineEventSchema,
+  AlertSchema,
+  SuggestionSchema,
+  ExecutionPlanSchema,
+  UserChoiceSchema,
+  DashboardDataSchema,
+} from './orchestration.schemas.js';
+
+// Re-export constant-derived types for convenience
+export type {
+  Lane,
+  AgentName,
+  SeverityLevel,
+  AgentResultStatus,
+  TimelineEventType,
+  EventSeverityLevel,
+  UserChoiceOption,
+  MandatoryAgentName,
+} from './orchestration.constants.js';
+
+// Re-export const values as well
+export {
+  LANES,
+  AGENT_NAMES,
+  SEVERITY_LEVELS,
+  AGENT_RESULT_STATUSES,
+  TIMELINE_EVENT_TYPES,
+  EVENT_SEVERITY_LEVELS,
+  USER_CHOICE_OPTIONS,
+  MANDATORY_AGENT_NAMES,
+} from './orchestration.constants.js';
+
+/**
+ * Global orchestration status.
+ * Shows high-level dashboard metrics at a glance.
+ *
+ * @example
+ * const status: GlobalStatus = {
+ *   activeWUs: 2,
+ *   completed24h: 5,
+ *   blocked: 1,
+ *   gatesFailing: 0,
+ *   longestRunning: { wuId: 'WU-1234', lane: 'Intelligence', durationMs: 2700000 },
+ *   pendingMandatory: [{ wuId: 'WU-1235', agent: 'security-auditor' }],
+ * };
+ */
+export type GlobalStatus = z.infer<typeof GlobalStatusSchema>;
+
+/**
+ * Per-agent metrics for dashboard display.
+ * Tracks invocation counts, pass rates, and timing.
+ *
+ * @example
+ * const metric: AgentMetric = {
+ *   invoked: 3,
+ *   passRate: 100,
+ *   avgDurationMs: 120000,
+ *   lastRun: { wuId: 'WU-1234', timestamp: '2025-01-15T10:00:00Z', result: 'pass' },
+ * };
+ */
+export type AgentMetric = z.infer<typeof AgentMetricSchema>;
+
+/**
+ * Work Unit progress for dashboard display.
+ * Shows DoD progress and agent status per WU.
+ *
+ * @example
+ * const progress: WUProgress = {
+ *   wuId: 'WU-1234',
+ *   lane: 'Intelligence',
+ *   title: 'LLM Classification Feature',
+ *   dodProgress: 8,
+ *   dodTotal: 11,
+ *   agents: { 'llm-reviewer': 'pass', 'code-reviewer': 'pending' },
+ *   headline: 'Blocked on code-reviewer - awaiting approval',
+ * };
+ */
+export type WUProgress = z.infer<typeof WUProgressSchema>;
+
+/**
+ * Timeline event for orchestration history.
+ * Records key events for dashboard display.
+ *
+ * @example
+ * const event: TimelineEvent = {
+ *   timestamp: '2025-01-15T09:00:00Z',
+ *   event: 'claim',
+ *   wuId: 'WU-1234',
+ *   detail: 'Claimed for Intelligence lane',
+ *   severity: 'info',
+ * };
+ */
+export type TimelineEvent = z.infer<typeof TimelineEventSchema>;
+
+/**
+ * Dashboard alert for items requiring attention.
+ *
+ * @example
+ * const alert: Alert = {
+ *   severity: 'high',
+ *   message: 'Mandatory agent not yet invoked',
+ *   wuId: 'WU-1235',
+ *   action: 'Run security-auditor before wu:done',
+ * };
+ */
+export type Alert = z.infer<typeof AlertSchema>;
+
+/**
+ * Orchestration suggestion for next actions.
+ *
+ * @example
+ * const suggestion: Suggestion = {
+ *   id: 'sug-001',
+ *   priority: 'high',
+ *   action: 'Run security-auditor',
+ *   reason: 'WU touches auth paths',
+ *   command: 'pnpm orchestrate:run security-auditor',
+ * };
+ */
+export type Suggestion = z.infer<typeof SuggestionSchema>;
+
+/**
+ * Execution plan for proposed orchestration actions.
+ *
+ * @example
+ * const plan: ExecutionPlan = {
+ *   wuId: 'WU-1234',
+ *   steps: [
+ *     { order: 1, agent: 'llm-reviewer', status: 'pending' },
+ *     { order: 2, action: 'gates', status: 'pending' },
+ *   ],
+ *   estimatedTokens: 5000,
+ * };
+ */
+export type ExecutionPlan = z.infer<typeof ExecutionPlanSchema>;
+
+/**
+ * User choice on execution plan confirmation.
+ *
+ * @example
+ * const choice: UserChoice = { choice: 'approve' };
+ * const editChoice: UserChoice = { choice: 'edit', modifications: ['Skip step 2'] };
+ */
+export type UserChoice = z.infer<typeof UserChoiceSchema>;
+
+/**
+ * Complete dashboard data aggregating all metrics.
+ * This is the main data structure passed to renderers.
+ *
+ * @example
+ * const data: DashboardData = {
+ *   globalStatus: { ... },
+ *   agentMetrics: { 'security-auditor': { ... } },
+ *   wuProgress: [{ ... }],
+ *   timeline: [{ ... }],
+ *   alerts: [{ ... }],
+ * };
+ */
+export type DashboardData = z.infer<typeof DashboardDataSchema>;

package/packs/software-delivery/src/methodology/incremental-test.ts

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * @file incremental-test.ts
+ * @description Helpers for Vitest --changed execution
+ *
+ * WU-1920: Add incremental test execution to gates
+ * WU-2504: Use Vitest --changed instead of custom file diff logic
+ */
+
+import { GIT_REFS } from '../constants/wu-git-constants.js';
+
+// WU-2790 follow-up: the software-delivery pack cannot import from
+// @lumenflow/core (pack import-boundary enforcement restricts packs to
+// @lumenflow/kernel + Node built-ins). Vitest --changed's base branch
+// therefore stays on the pack's own GIT_REFS constant. If the host
+// workspace reconfigures software_delivery.git.mainBranch, incremental
+// test selection here falls back to origin/main — slightly over-selects
+// when running --changed, but preserves correctness. Proper fix requires
+// relocating the integration-target resolver into kernel; tracked
+// separately as a pack-boundary follow-up.
+
+/**
+ * Glob patterns to exclude slow integration/golden tests from changed runs.
+ * @type {string[]}
+ */
+export const VITEST_CHANGED_EXCLUDES = Object.freeze(['**/*.integration.*', '**/golden-*.test.*']);
+
+/**
+ * File extensions considered executable code for test runs.
+ * @type {string[]}
+ */
+export const CODE_FILE_EXTENSIONS = Object.freeze([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.js',
+  '.cjs',
+  '.mts',
+  '.cts',
+]);
+
+/**
+ * Check if a path points to a code file that should trigger full tests.
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if the path has a code extension
+ */
+export function isCodeFilePath(filePath: string) {
+  if (!filePath || typeof filePath !== 'string') {
+    return false;
+  }
+
+  const normalized = filePath.replace(/\\/g, '/').toLowerCase();
+  return CODE_FILE_EXTENSIONS.some((ext) => normalized.endsWith(ext));
+}
+
+/**
+ * Options for building Vitest changed args
+ */
+interface BuildVitestChangedArgsOptions {
+  /** Base branch for diff */
+  baseBranch?: string;
+}
+
+/**
+ * Build Vitest CLI args for --changed runs.
+ *
+ * @param {BuildVitestChangedArgsOptions} [options]
+ * @returns {string[]} Vitest args for changed test runs
+ */
+export function buildVitestChangedArgs(options: BuildVitestChangedArgsOptions = {}) {
+  const { baseBranch = GIT_REFS.ORIGIN_MAIN } = options;
+  const args = [
+    '--changed',
+    baseBranch,
+    '--run',
+    '--passWithNoTests',
+    '--maxWorkers=1',
+    '--teardownTimeout=30000',
+  ];
+
+  for (const pattern of VITEST_CHANGED_EXCLUDES) {
+    args.push(`--exclude='${pattern}'`);
+  }
+
+  return args;
+}

package/packs/software-delivery/src/methodology/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// WU-2683 (INIT-058 L4): Methodology cohort barrel — re-export relocated modules.
+export * from './manual-test-validator.js';
+export * from './incremental-test.js';