@lumenflow/core 1.0.0

package/dist/orchestration-advisory-loader.js

@@ -0,0 +1,87 @@
+/**
+ * Orchestration Advisory Loader
+ *
+ * Pure JavaScript implementation of mandatory agent advisory.
+ * Uses minimatch for glob pattern matching (same as TypeScript version).
+ *
+ * @module orchestration-advisory-loader
+ * @see {@link ./orchestration-advisory.mjs} - TypeScript version for tests
+ * @see {@link ./domain/orchestration.constants.mjs} - Pattern definitions
+ */
+import { minimatch } from 'minimatch';
+import picocolors from 'picocolors';
+/**
+ * Mandatory agent trigger patterns.
+ * Mirrors MANDATORY_TRIGGERS from orchestration.constants.mjs.
+ */
+const MANDATORY_TRIGGERS = {
+    'security-auditor': ['supabase/migrations/**', '**/auth/**', '**/rls/**', '**/permissions/**'],
+    'beacon-guardian': ['**/prompts/**', '**/classification/**', '**/detector/**', '**/llm/**'],
+};
+/**
+ * Detect mandatory agents based on code paths.
+ *
+ * @param {string[]} codePaths - Array of file paths
+ * @returns {string[]} Array of mandatory agent names
+ */
+function detectMandatoryAgents(codePaths) {
+    if (!codePaths || codePaths.length === 0) {
+        return [];
+    }
+    const triggeredAgents = new Set();
+    for (const [agentName, patterns] of Object.entries(MANDATORY_TRIGGERS)) {
+        const isTriggered = codePaths.some((filePath) => patterns.some((pattern) => minimatch(filePath, pattern)));
+        if (isTriggered) {
+            triggeredAgents.add(agentName);
+        }
+    }
+    return Array.from(triggeredAgents);
+}
+/**
+ * Emit mandatory agent advisory based on code paths.
+ *
+ * @param {string[]} codePaths - Array of file paths
+ * @param {string} wuId - Work Unit ID
+ */
+export function emitMandatoryAgentAdvisory(codePaths, wuId) {
+    if (!codePaths || codePaths.length === 0) {
+        return;
+    }
+    const mandatoryAgents = detectMandatoryAgents(codePaths);
+    if (mandatoryAgents.length === 0) {
+        return;
+    }
+    const horizontalLine = '═'.repeat(60);
+    console.log('');
+    console.log(picocolors.yellow(horizontalLine));
+    console.log(picocolors.yellow(picocolors.bold(' MANDATORY AGENT ADVISORY ')));
+    console.log(picocolors.yellow(horizontalLine));
+    console.log('');
+    console.log(`[orchestrate] Based on code_paths in ${wuId}, the following`);
+    console.log(`[orchestrate] mandatory agents MUST be invoked BEFORE wu:done:`);
+    console.log('');
+    for (const agent of mandatoryAgents) {
+        console.log(picocolors.cyan(`  • ${agent}`));
+    }
+    console.log('');
+    console.log(picocolors.gray(`Run: pnpm orchestrate:suggest --wu ${wuId}`));
+    console.log(picocolors.yellow(horizontalLine));
+    console.log('');
+}
+/**
+ * Check mandatory agent compliance.
+ *
+ * @param {string[]} codePaths - Array of file paths
+ * @param {string} _wuId - Work Unit ID (reserved for future telemetry lookup)
+ * @returns {{compliant: boolean, missing: string[]}}
+ */
+export function checkMandatoryAgentsCompliance(codePaths, _wuId) {
+    if (!codePaths || codePaths.length === 0) {
+        return { compliant: true, missing: [] };
+    }
+    const mandatoryAgents = detectMandatoryAgents(codePaths);
+    return {
+        compliant: mandatoryAgents.length === 0,
+        missing: mandatoryAgents,
+    };
+}

package/dist/orchestration-advisory.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Orchestration Advisory Emitter
+ *
+ * Utility functions for emitting mandatory agent advisories and checking compliance.
+ * Used by wu-claim.mjs (emit advisory) and wu-done.mjs (check compliance).
+ *
+ * @module orchestration-advisory
+ * @see {@link ./orchestration-rules.mjs} - detectMandatoryAgents function
+ * @see {@link ./domain/orchestration.constants.mjs} - MANDATORY_TRIGGERS patterns
+ */
+import type { MandatoryAgentName } from './domain/orchestration.types.js';
+/**
+ * Emit a mandatory agent advisory to the terminal.
+ *
+ * Called after wu:claim to inform the agent which mandatory agents
+ * must be invoked before wu:done.
+ *
+ * @param codePaths - Array of file paths being touched by the WU
+ * @param wuId - Work Unit ID (e.g., 'WU-1234')
+ *
+ * @example
+ * emitMandatoryAgentAdvisory(['supabase/migrations/001.sql'], 'WU-1234');
+ * // Outputs coloured advisory box with security-auditor requirement
+ */
+export declare function emitMandatoryAgentAdvisory(codePaths: readonly string[], wuId: string): void;
+/**
+ * Result of mandatory agent compliance check.
+ */
+export interface ComplianceResult {
+    /**
+     * True if no mandatory agents are required or all have been invoked.
+     */
+    compliant: boolean;
+    /**
+     * List of mandatory agent names that have not been invoked.
+     */
+    missing: MandatoryAgentName[];
+}
+/**
+ * Check if mandatory agents have been invoked for a WU.
+ *
+ * Called by wu:done to warn (non-blocking) if mandatory agents
+ * were not confirmed as invoked.
+ *
+ * Note: Current implementation returns missing based on code_paths only.
+ * Future versions will check telemetry for actual agent invocations.
+ *
+ * @param codePaths - Array of file paths touched by the WU
+ * @param _wuId - Work Unit ID (reserved for future telemetry lookup)
+ * @returns Compliance result with compliant flag and missing agents
+ *
+ * @example
+ * const result = checkMandatoryAgentsCompliance(['src/auth/login.js'], 'WU-1234');
+ * if (!result.compliant) {
+ *   console.warn(`Missing agents: ${result.missing.join(', ')}`);
+ * }
+ */
+export declare function checkMandatoryAgentsCompliance(codePaths: readonly string[], _wuId: string): ComplianceResult;

package/dist/orchestration-advisory.js

@@ -0,0 +1,94 @@
+/**
+ * Orchestration Advisory Emitter
+ *
+ * Utility functions for emitting mandatory agent advisories and checking compliance.
+ * Used by wu-claim.mjs (emit advisory) and wu-done.mjs (check compliance).
+ *
+ * @module orchestration-advisory
+ * @see {@link ./orchestration-rules.mjs} - detectMandatoryAgents function
+ * @see {@link ./domain/orchestration.constants.mjs} - MANDATORY_TRIGGERS patterns
+ */
+import picocolors from 'picocolors';
+import { detectMandatoryAgents } from './orchestration-rules.js';
+/**
+ * Log prefix for orchestration advisory messages.
+ */
+const ADVISORY_PREFIX = '[orchestrate]';
+/**
+ * Box drawing characters for advisory display.
+ */
+const BOX_CHARS = {
+    HORIZONTAL: '═',
+    BULLET: '•',
+};
+/**
+ * Advisory box width in characters.
+ */
+const ADVISORY_BOX_WIDTH = 60;
+/**
+ * Emit a mandatory agent advisory to the terminal.
+ *
+ * Called after wu:claim to inform the agent which mandatory agents
+ * must be invoked before wu:done.
+ *
+ * @param codePaths - Array of file paths being touched by the WU
+ * @param wuId - Work Unit ID (e.g., 'WU-1234')
+ *
+ * @example
+ * emitMandatoryAgentAdvisory(['supabase/migrations/001.sql'], 'WU-1234');
+ * // Outputs coloured advisory box with security-auditor requirement
+ */
+export function emitMandatoryAgentAdvisory(codePaths, wuId) {
+    if (codePaths.length === 0) {
+        return;
+    }
+    const mandatoryAgents = detectMandatoryAgents(codePaths);
+    if (mandatoryAgents.length === 0) {
+        return;
+    }
+    const horizontalLine = BOX_CHARS.HORIZONTAL.repeat(ADVISORY_BOX_WIDTH);
+    console.log('');
+    console.log(picocolors.yellow(horizontalLine));
+    console.log(picocolors.yellow(picocolors.bold(' MANDATORY AGENT ADVISORY ')));
+    console.log(picocolors.yellow(horizontalLine));
+    console.log('');
+    console.log(`${ADVISORY_PREFIX} Based on code_paths in ${wuId}, the following`);
+    console.log(`${ADVISORY_PREFIX} mandatory agents MUST be invoked BEFORE wu:done:`);
+    console.log('');
+    for (const agent of mandatoryAgents) {
+        console.log(picocolors.cyan(`  ${BOX_CHARS.BULLET} ${agent}`));
+    }
+    console.log('');
+    console.log(picocolors.gray(`Run: pnpm orchestrate:suggest --wu ${wuId}`));
+    console.log(picocolors.yellow(horizontalLine));
+    console.log('');
+}
+/**
+ * Check if mandatory agents have been invoked for a WU.
+ *
+ * Called by wu:done to warn (non-blocking) if mandatory agents
+ * were not confirmed as invoked.
+ *
+ * Note: Current implementation returns missing based on code_paths only.
+ * Future versions will check telemetry for actual agent invocations.
+ *
+ * @param codePaths - Array of file paths touched by the WU
+ * @param _wuId - Work Unit ID (reserved for future telemetry lookup)
+ * @returns Compliance result with compliant flag and missing agents
+ *
+ * @example
+ * const result = checkMandatoryAgentsCompliance(['src/auth/login.js'], 'WU-1234');
+ * if (!result.compliant) {
+ *   console.warn(`Missing agents: ${result.missing.join(', ')}`);
+ * }
+ */
+export function checkMandatoryAgentsCompliance(codePaths, _wuId) {
+    if (codePaths.length === 0) {
+        return { compliant: true, missing: [] };
+    }
+    const mandatoryAgents = detectMandatoryAgents(codePaths);
+    return {
+        compliant: mandatoryAgents.length === 0,
+        missing: mandatoryAgents,
+    };
+}

package/dist/orchestration-di.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Orchestration Dependency Injection Composition Root
+ *
+ * Factory functions that wire infrastructure adapters to application use cases.
+ * Follows hexagonal architecture - this is the only place where concrete
+ * implementations are coupled.
+ *
+ * @module orchestration-di
+ * @see {@link ./ports/metrics-collector.port.mjs} - Input port
+ * @see {@link ./ports/dashboard-renderer.port.mjs} - Output port
+ * @see {@link ./adapters/filesystem-metrics.adapter.mjs} - Input adapter
+ * @see {@link ./adapters/terminal-renderer.adapter.mjs} - Output adapter
+ */
+import { GetDashboardDataUseCase } from './usecases/get-dashboard-data.usecase.js';
+import { GetSuggestionsUseCase } from './usecases/get-suggestions.usecase.js';
+import type { IDashboardRenderer } from './ports/dashboard-renderer.port.js';
+/**
+ * Create a GetDashboardDataUseCase with FileSystemMetricsCollector.
+ *
+ * @param baseDir - Base directory for filesystem operations (default: process.cwd())
+ * @returns Configured use case instance
+ *
+ * @example
+ * const useCase = createDashboardUseCase();
+ * const data = await useCase.execute();
+ */
+export declare function createDashboardUseCase(baseDir?: string): GetDashboardDataUseCase;
+/**
+ * Create a GetSuggestionsUseCase with FileSystemMetricsCollector.
+ *
+ * @param baseDir - Base directory for filesystem operations (default: process.cwd())
+ * @returns Configured use case instance
+ *
+ * @example
+ * const useCase = createSuggestionsUseCase();
+ * const suggestions = await useCase.execute({ codePaths: ['src/auth/login.js'] });
+ */
+export declare function createSuggestionsUseCase(baseDir?: string): GetSuggestionsUseCase;
+/**
+ * Create a TerminalDashboardRenderer for CLI output.
+ *
+ * @returns Configured renderer instance
+ *
+ * @example
+ * const renderer = createRenderer();
+ * renderer.render(dashboardData);
+ */
+export declare function createRenderer(): IDashboardRenderer;

package/dist/orchestration-di.js

@@ -0,0 +1,57 @@
+/**
+ * Orchestration Dependency Injection Composition Root
+ *
+ * Factory functions that wire infrastructure adapters to application use cases.
+ * Follows hexagonal architecture - this is the only place where concrete
+ * implementations are coupled.
+ *
+ * @module orchestration-di
+ * @see {@link ./ports/metrics-collector.port.mjs} - Input port
+ * @see {@link ./ports/dashboard-renderer.port.mjs} - Output port
+ * @see {@link ./adapters/filesystem-metrics.adapter.mjs} - Input adapter
+ * @see {@link ./adapters/terminal-renderer.adapter.mjs} - Output adapter
+ */
+import { FileSystemMetricsCollector } from './adapters/filesystem-metrics.adapter.js';
+import { TerminalDashboardRenderer } from './adapters/terminal-renderer.adapter.js';
+import { GetDashboardDataUseCase } from './usecases/get-dashboard-data.usecase.js';
+import { GetSuggestionsUseCase } from './usecases/get-suggestions.usecase.js';
+/**
+ * Create a GetDashboardDataUseCase with FileSystemMetricsCollector.
+ *
+ * @param baseDir - Base directory for filesystem operations (default: process.cwd())
+ * @returns Configured use case instance
+ *
+ * @example
+ * const useCase = createDashboardUseCase();
+ * const data = await useCase.execute();
+ */
+export function createDashboardUseCase(baseDir) {
+    const collector = new FileSystemMetricsCollector(baseDir);
+    return new GetDashboardDataUseCase(collector);
+}
+/**
+ * Create a GetSuggestionsUseCase with FileSystemMetricsCollector.
+ *
+ * @param baseDir - Base directory for filesystem operations (default: process.cwd())
+ * @returns Configured use case instance
+ *
+ * @example
+ * const useCase = createSuggestionsUseCase();
+ * const suggestions = await useCase.execute({ codePaths: ['src/auth/login.js'] });
+ */
+export function createSuggestionsUseCase(baseDir) {
+    const collector = new FileSystemMetricsCollector(baseDir);
+    return new GetSuggestionsUseCase(collector);
+}
+/**
+ * Create a TerminalDashboardRenderer for CLI output.
+ *
+ * @returns Configured renderer instance
+ *
+ * @example
+ * const renderer = createRenderer();
+ * renderer.render(dashboardData);
+ */
+export function createRenderer() {
+    return new TerminalDashboardRenderer();
+}

package/dist/orchestration-rules.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Orchestration Rules
+ *
+ * Pure functions for agent detection and suggestion generation.
+ * Uses minimatch for glob pattern matching (NOT regex).
+ *
+ * @module orchestration-rules
+ * @see {@link ./domain/orchestration.constants.mjs} - MANDATORY_TRIGGERS patterns
+ * @see {@link ../../../ai/onboarding/agent-selection-guide.md} - Agent selection rules
+ */
+import { type MandatoryAgentName } from './domain/orchestration.constants.js';
+/**
+ * Detect mandatory agents that should be invoked based on code paths.
+ *
+ * Uses minimatch glob patterns from MANDATORY_TRIGGERS to determine
+ * which agents are required for the given file paths.
+ *
+ * @param {readonly string[]} codePaths - Array of file paths being touched by the WU
+ * @returns {MandatoryAgentName[]} Array of unique mandatory agent names that should be invoked
+ */
+export declare function detectMandatoryAgents(codePaths: readonly string[]): MandatoryAgentName[];
+/**
+ * Generate suggestions for next actions based on WU progress and agent history.
+ *
+ * @param {readonly object[]} wuProgress - Array of WU progress records
+ * @param {object} _agentHistory - Record of agent metrics (reserved for future use)
+ * @returns {object[]} Array of prioritised suggestions
+ */
+export declare function generateSuggestions(wuProgress: any, _agentHistory: any): any[];
+/**
+ * WU-1542: Build a formatted error message for mandatory agent enforcement failures.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {readonly string[]} missingAgents - Array of mandatory agent names that were not invoked
+ * @param {readonly string[]} codePaths - Array of file paths that triggered the agents
+ * @returns {string} Formatted error message string
+ */
+export declare function buildMandatoryAgentsErrorMessage(wuId: any, missingAgents: any, codePaths: any): string;
+/**
+ * WU-1542: Check mandatory agent compliance with optional blocking mode.
+ *
+ * @param {readonly string[]} codePaths - Array of file paths being touched by the WU
+ * @param {string} wuId - Work Unit ID for error message context
+ * @param {{ blocking: boolean }} options - Options including blocking mode flag
+ * @returns {{ compliant: boolean, blocking: boolean, missing: string[], errorMessage?: string }}
+ */
+export declare function checkMandatoryAgentsComplianceBlocking(codePaths: any, wuId: any, options: any): {
+    compliant: boolean;
+    blocking: boolean;
+    missing: ("security-auditor" | "beacon-guardian")[];
+    errorMessage?: undefined;
+} | {
+    compliant: boolean;
+    blocking: boolean;
+    missing: ("security-auditor" | "beacon-guardian")[];
+    errorMessage: string;
+};

package/dist/orchestration-rules.js

@@ -0,0 +1,201 @@
+/**
+ * Orchestration Rules
+ *
+ * Pure functions for agent detection and suggestion generation.
+ * Uses minimatch for glob pattern matching (NOT regex).
+ *
+ * @module orchestration-rules
+ * @see {@link ./domain/orchestration.constants.mjs} - MANDATORY_TRIGGERS patterns
+ * @see {@link ../../../ai/onboarding/agent-selection-guide.md} - Agent selection rules
+ */
+import { minimatch } from 'minimatch';
+import { MANDATORY_TRIGGERS } from './domain/orchestration.constants.js';
+/**
+ * Threshold for considering a WU "near completion".
+ * WUs with DoD progress >= this value trigger code-reviewer suggestion.
+ */
+const NEAR_COMPLETION_THRESHOLD = 8;
+/**
+ * Detect mandatory agents that should be invoked based on code paths.
+ *
+ * Uses minimatch glob patterns from MANDATORY_TRIGGERS to determine
+ * which agents are required for the given file paths.
+ *
+ * @param {readonly string[]} codePaths - Array of file paths being touched by the WU
+ * @returns {MandatoryAgentName[]} Array of unique mandatory agent names that should be invoked
+ */
+export function detectMandatoryAgents(codePaths) {
+    if (codePaths.length === 0) {
+        return [];
+    }
+    const triggeredAgents = new Set();
+    for (const [agentName, patterns] of Object.entries(MANDATORY_TRIGGERS)) {
+        const isTriggered = codePaths.some((filePath) => patterns.some((pattern) => minimatch(filePath, pattern)));
+        if (isTriggered) {
+            triggeredAgents.add(agentName);
+        }
+    }
+    return Array.from(triggeredAgents);
+}
+/**
+ * Generate suggestions for next actions based on WU progress and agent history.
+ *
+ * @param {readonly object[]} wuProgress - Array of WU progress records
+ * @param {object} _agentHistory - Record of agent metrics (reserved for future use)
+ * @returns {object[]} Array of prioritised suggestions
+ */
+export function generateSuggestions(wuProgress, _agentHistory) {
+    if (wuProgress.length === 0) {
+        return [];
+    }
+    const suggestions = [];
+    let suggestionCounter = 0;
+    for (const wu of wuProgress) {
+        const wuSuggestions = generateWUSuggestions(wu, () => ++suggestionCounter);
+        suggestions.push(...wuSuggestions);
+    }
+    // Sort by priority: high > medium > low
+    return suggestions.sort((a, b) => {
+        const priorityOrder = {
+            high: 0,
+            medium: 1,
+            low: 2,
+        };
+        return priorityOrder[a.priority] - priorityOrder[b.priority];
+    });
+}
+/**
+ * Generate suggestions for a single WU.
+ *
+ * @param {object} wu - WU progress record
+ * @param {function} nextId - Function to generate unique suggestion IDs
+ * @returns {object[]} Array of suggestions for this WU
+ */
+function generateWUSuggestions(wu, nextId) {
+    const suggestions = [];
+    // Check for pending mandatory agents (HIGH priority)
+    const mandatoryAgents = ['security-auditor', 'beacon-guardian'];
+    for (const agentName of mandatoryAgents) {
+        if (wu.agents[agentName] === 'pending') {
+            suggestions.push({
+                id: `sug-${nextId().toString().padStart(3, '0')}`,
+                priority: 'high',
+                action: `Run ${agentName}`,
+                reason: `Mandatory agent pending for ${wu.wuId}`,
+                command: `pnpm orchestrate:run ${agentName} --wu ${wu.wuId}`,
+            });
+        }
+    }
+    // Check for code-reviewer near completion (MEDIUM priority)
+    const isNearCompletion = wu.dodProgress >= NEAR_COMPLETION_THRESHOLD;
+    const codeReviewerStatus = wu.agents['code-reviewer'];
+    const needsCodeReviewer = isNearCompletion && codeReviewerStatus !== 'pass' && codeReviewerStatus !== 'fail';
+    if (needsCodeReviewer) {
+        suggestions.push({
+            id: `sug-${nextId().toString().padStart(3, '0')}`,
+            priority: 'medium',
+            action: `Run code-reviewer`,
+            reason: `${wu.wuId} is near completion (${wu.dodProgress}/${wu.dodTotal})`,
+            command: `pnpm orchestrate:run code-reviewer --wu ${wu.wuId}`,
+        });
+    }
+    // Check for test-engineer when tests pending (LOW priority)
+    const testEngineerStatus = wu.agents['test-engineer'];
+    const needsTestEngineer = testEngineerStatus === 'pending';
+    if (needsTestEngineer) {
+        suggestions.push({
+            id: `sug-${nextId().toString().padStart(3, '0')}`,
+            priority: 'low',
+            action: `Run test-engineer`,
+            reason: `Tests pending for ${wu.wuId}`,
+            command: `pnpm orchestrate:run test-engineer --wu ${wu.wuId}`,
+        });
+    }
+    return suggestions;
+}
+/**
+ * WU-1542: Agent trigger descriptions for error messages.
+ * Maps agent names to human-readable descriptions of their trigger patterns.
+ */
+const AGENT_TRIGGER_DESCRIPTIONS = {
+    'security-auditor': 'supabase/migrations/**, **/auth/**, **/rls/**, **/permissions/**',
+    'beacon-guardian': '**/prompts/**, **/classification/**, **/detector/**, **/llm/**',
+};
+/**
+ * WU-1542: Build a formatted error message for mandatory agent enforcement failures.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {readonly string[]} missingAgents - Array of mandatory agent names that were not invoked
+ * @param {readonly string[]} codePaths - Array of file paths that triggered the agents
+ * @returns {string} Formatted error message string
+ */
+export function buildMandatoryAgentsErrorMessage(wuId, missingAgents, codePaths) {
+    const lines = [
+        '',
+        '='.repeat(70),
+        ' MANDATORY AGENT ENFORCEMENT FAILED (--require-agents)',
+        '='.repeat(70),
+        '',
+        `WU ${wuId} cannot be completed because the following mandatory agents`,
+        'were not confirmed as invoked before wu:done:',
+        '',
+    ];
+    for (const agent of missingAgents) {
+        const description = AGENT_TRIGGER_DESCRIPTIONS[agent] || 'unknown patterns';
+        lines.push(`  - ${agent}`);
+        lines.push(`    Triggered by: ${description}`);
+    }
+    lines.push('');
+    lines.push('Code paths that triggered mandatory agents:');
+    for (const path of codePaths.slice(0, 5)) {
+        lines.push(`  - ${path}`);
+    }
+    if (codePaths.length > 5) {
+        lines.push(`  ... and ${codePaths.length - 5} more`);
+    }
+    lines.push('');
+    lines.push('Required action:');
+    lines.push('  1. Invoke the required agents BEFORE calling wu:done');
+    lines.push('  2. For security-auditor: Review PHI/auth/RLS implications');
+    lines.push('  3. For beacon-guardian: Validate LLM/prompt compliance');
+    lines.push('');
+    lines.push('To bypass (NOT RECOMMENDED for PHI/auth work):');
+    lines.push('  Remove --require-agents flag from wu:done command');
+    lines.push('');
+    lines.push('See: ai/onboarding/agent-selection-guide.md for agent invocation guidance');
+    lines.push('='.repeat(70));
+    return lines.join('\n');
+}
+/**
+ * WU-1542: Check mandatory agent compliance with optional blocking mode.
+ *
+ * @param {readonly string[]} codePaths - Array of file paths being touched by the WU
+ * @param {string} wuId - Work Unit ID for error message context
+ * @param {{ blocking: boolean }} options - Options including blocking mode flag
+ * @returns {{ compliant: boolean, blocking: boolean, missing: string[], errorMessage?: string }}
+ */
+export function checkMandatoryAgentsComplianceBlocking(codePaths, wuId, options) {
+    const missingAgents = detectMandatoryAgents(codePaths);
+    if (missingAgents.length === 0) {
+        return {
+            compliant: true,
+            blocking: false,
+            missing: [],
+        };
+    }
+    // Non-blocking mode: return compliance info without error message
+    if (!options.blocking) {
+        return {
+            compliant: false,
+            blocking: false,
+            missing: missingAgents,
+        };
+    }
+    // Blocking mode: generate error message
+    return {
+        compliant: false,
+        blocking: true,
+        missing: missingAgents,
+        errorMessage: buildMandatoryAgentsErrorMessage(wuId, missingAgents, codePaths),
+    };
+}