@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/orchestration/agent-invoker.js

@@ -0,0 +1,456 @@
+/**
+ * Agent Invoker -- Invokes agents for tasks during orchestration
+ *
+ * Provides the interface to invoke Merlin's 14 agents with structured
+ * context, timeout handling, retry logic, and audit logging.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/orchestration/agent-invoker
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const path = require("path");
+const EventEmitter = require("events");
+
+/**
+ * Merlin's 14 supported agents
+ * @constant {Object.<string, Object>}
+ */
+const SUPPORTED_AGENTS = {
+  "merlin-master": {
+    name: "merlin-master",
+    displayName: "Merlin Master",
+    file: "merlin-master.md",
+    capabilities: ["orchestration", "coordination", "routing", "founder-mode"],
+  },
+  analyst: {
+    name: "analyst",
+    displayName: "Business Analyst",
+    file: "analyst.md",
+    capabilities: ["requirements", "analysis", "documentation", "user-stories"],
+  },
+  architect: {
+    name: "architect",
+    displayName: "System Architect",
+    file: "architect.md",
+    capabilities: ["design", "architecture", "technical-decisions", "adr"],
+  },
+  dev: {
+    name: "dev",
+    displayName: "Developer",
+    file: "dev.md",
+    capabilities: ["implementation", "coding", "debugging", "refactoring"],
+  },
+  devops: {
+    name: "devops",
+    displayName: "DevOps Engineer",
+    file: "devops.md",
+    capabilities: ["deployment", "infrastructure", "ci-cd", "git"],
+  },
+  pm: {
+    name: "pm",
+    displayName: "Project Manager",
+    file: "pm.md",
+    capabilities: ["planning", "coordination", "story-management", "tracking"],
+  },
+  po: {
+    name: "po",
+    displayName: "Product Owner",
+    file: "po.md",
+    capabilities: ["backlog", "prioritization", "acceptance", "stakeholder"],
+  },
+  qa: {
+    name: "qa",
+    displayName: "QA Engineer",
+    file: "qa.md",
+    capabilities: ["testing", "quality", "validation", "test-automation"],
+  },
+  sm: {
+    name: "sm",
+    displayName: "Scrum Master",
+    file: "sm.md",
+    capabilities: ["ceremonies", "impediments", "process", "retrospective"],
+  },
+  ux: {
+    name: "ux",
+    displayName: "UX Designer",
+    file: "ux.md",
+    capabilities: ["design", "usability", "wireframes", "accessibility"],
+  },
+  "data-engineer": {
+    name: "data-engineer",
+    displayName: "Data Engineer",
+    file: "data-engineer.md",
+    capabilities: ["database", "schema", "migration", "data-pipeline"],
+  },
+  researcher: {
+    name: "researcher",
+    displayName: "Researcher",
+    file: "researcher.md",
+    capabilities: ["codebase-research", "analysis", "investigation", "audit"],
+  },
+  scout: {
+    name: "scout",
+    displayName: "Scout",
+    file: "scout.md",
+    capabilities: ["exploration", "discovery", "reconnaissance", "mapping"],
+  },
+  "web-researcher": {
+    name: "web-researcher",
+    displayName: "Web Researcher",
+    file: "web-researcher.md",
+    capabilities: [
+      "web-search",
+      "documentation",
+      "api-research",
+      "benchmarking",
+    ],
+  },
+};
+
+/**
+ * Invocation result status
+ * @enum {string}
+ */
+const InvocationStatus = {
+  SUCCESS: "success",
+  FAILED: "failed",
+  TIMEOUT: "timeout",
+  SKIPPED: "skipped",
+};
+
+/**
+ * AgentInvoker -- Interface to invoke agents for tasks
+ * @extends EventEmitter
+ */
+class AgentInvoker extends EventEmitter {
+  /**
+   * @param {Object} options - Configuration options
+   * @param {string} options.projectRoot - Project root path
+   * @param {number} [options.defaultTimeout=300000] - Default timeout in ms (5 min)
+   * @param {number} [options.maxRetries=3] - Max retries for transient failures
+   * @param {Function} [options.executor] - Custom executor function
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(options = {}) {
+    super();
+
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.defaultTimeout = options.defaultTimeout ?? 300000;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.executor = options.executor || null;
+    this.debug = options.debug ?? false;
+
+    // v3.0.0 — GuardrailEngine for pre/post execution checks
+    this.guardrailEngine = options.guardrailEngine || null;
+
+    // Agent files location
+    this.agentsDir = path.join(
+      this.projectRoot,
+      ".merlin-core",
+      "development",
+      "agents",
+    );
+
+    // Audit log
+    this._invocations = [];
+  }
+
+  /**
+   * Invoke an agent to execute a task.
+   *
+   * @param {string} agentName - Agent name (e.g., 'dev', 'qa', 'architect')
+   * @param {Object} task - Task definition with at least { name, description }
+   * @param {Object} [context={}] - Additional context for the invocation
+   * @returns {Promise<Object>} Invocation result
+   */
+  async invokeAgent(agentName, task, context = {}) {
+    const invocationId = this._generateId();
+    const startTime = Date.now();
+
+    // Normalize agent name
+    const normalizedName = agentName.replace(/^@/, "").toLowerCase();
+
+    // Validate agent
+    const agent = SUPPORTED_AGENTS[normalizedName];
+    if (!agent) {
+      const result = {
+        success: false,
+        invocationId,
+        agentName: normalizedName,
+        status: InvocationStatus.FAILED,
+        error: `Unknown agent: ${normalizedName}`,
+        duration: 0,
+      };
+      this._recordInvocation(result);
+      return result;
+    }
+
+    this._log(
+      `Invoking @${normalizedName} for task: ${task.name || "unnamed"}`,
+    );
+
+    // --- Guardrail: preCheck before invocation ---
+    if (this.guardrailEngine) {
+      const preResult = this.guardrailEngine.preCheck(normalizedName, {
+        id: task.name || "unnamed",
+        description: task.description || "",
+        files: task.files,
+        approach: task.description || task.name,
+      });
+      if (!preResult.passed) {
+        const result = {
+          success: false,
+          invocationId,
+          agentName: normalizedName,
+          status: InvocationStatus.FAILED,
+          error: `Blocked by guardrail preCheck: ${preResult.issues.map((i) => i.message).join("; ")}`,
+          duration: Date.now() - startTime,
+          issues: preResult.issues,
+        };
+        this._recordInvocation(result);
+        return result;
+      }
+
+      // Environment preflight if task has env dependencies
+      if (task.outputPaths || task.requiredTools || task.apiEndpoints) {
+        const envResult = await this.guardrailEngine.envPreflightCheck(task);
+        if (!envResult.passed) {
+          const result = {
+            success: false,
+            invocationId,
+            agentName: normalizedName,
+            status: InvocationStatus.FAILED,
+            error: `Blocked by envPreflight: ${envResult.issues.map((i) => i.message).join("; ")}`,
+            duration: Date.now() - startTime,
+            issues: envResult.issues,
+          };
+          this._recordInvocation(result);
+          return result;
+        }
+      }
+    }
+
+    // Build invocation context
+    const invocationContext = this._buildContext(agent, task, context);
+
+    // Emit start event
+    this.emit("invocationStart", {
+      invocationId,
+      agentName: normalizedName,
+      task,
+    });
+
+    try {
+      // Execute with timeout
+      const output = await this._executeWithTimeout(
+        () => this._execute(agent, task, invocationContext),
+        this.defaultTimeout,
+      );
+
+      const duration = Date.now() - startTime;
+
+      // --- Guardrail: postCheck after successful execution ---
+      let guardrailOverride = false;
+      if (this.guardrailEngine) {
+        const postResult = this.guardrailEngine.postCheck(
+          normalizedName,
+          { success: true, output },
+          { id: task.name, description: task.description, files: task.files },
+        );
+        if (!postResult.passed) {
+          guardrailOverride = true;
+          this._log(
+            `@${normalizedName} postCheck failed: ${postResult.issues.map((i) => i.message).join("; ")}`,
+          );
+        }
+      }
+
+      const result = {
+        success: !guardrailOverride,
+        invocationId,
+        agentName: normalizedName,
+        status: guardrailOverride
+          ? InvocationStatus.FAILED
+          : InvocationStatus.SUCCESS,
+        output,
+        duration,
+      };
+
+      this._recordInvocation(result);
+      this.emit(
+        guardrailOverride ? "invocationFailed" : "invocationComplete",
+        result,
+      );
+      this._log(`@${normalizedName} completed in ${duration}ms`);
+
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const isTimeout = error.message === "Agent invocation timed out";
+
+      // --- Guardrail: record failed attempt ---
+      if (this.guardrailEngine) {
+        this.guardrailEngine.postCheck(
+          normalizedName,
+          { success: false, error: error.message },
+          { id: task.name, description: task.description },
+        );
+      }
+
+      const result = {
+        success: false,
+        invocationId,
+        agentName: normalizedName,
+        status: isTimeout ? InvocationStatus.TIMEOUT : InvocationStatus.FAILED,
+        error: error.message,
+        duration,
+      };
+
+      this._recordInvocation(result);
+      this.emit("invocationFailed", result);
+      this._log(`@${normalizedName} failed: ${error.message}`);
+
+      return result;
+    }
+  }
+
+  /**
+   * Build structured context for an agent invocation.
+   *
+   * @param {Object} agent - Agent definition from SUPPORTED_AGENTS
+   * @param {Object} task - Task definition
+   * @param {Object} context - Additional context
+   * @returns {Object} Structured invocation context
+   * @private
+   */
+  _buildContext(agent, task, context) {
+    return {
+      agent: {
+        name: agent.name,
+        displayName: agent.displayName,
+        capabilities: agent.capabilities,
+        definitionPath: path.join(this.agentsDir, agent.file),
+      },
+      task: {
+        name: task.name || "unnamed",
+        description: task.description || "",
+        type: task.type || "general",
+        priority: task.priority || "normal",
+      },
+      environment: {
+        projectRoot: this.projectRoot,
+        timestamp: new Date().toISOString(),
+        timeout: this.defaultTimeout,
+      },
+      ...context,
+    };
+  }
+
+  /**
+   * Execute the agent task. Uses custom executor if provided.
+   *
+   * @param {Object} agent - Agent definition
+   * @param {Object} task - Task definition
+   * @param {Object} context - Invocation context
+   * @returns {Promise<Object>} Execution output
+   * @private
+   */
+  async _execute(agent, task, context) {
+    if (this.executor) {
+      return this.executor(agent, task, context);
+    }
+
+    // Default: return structured placeholder result.
+    // In production, this would interface with the LLM.
+    return {
+      status: "simulated",
+      message: `Task "${task.name}" executed by @${agent.name}`,
+      agent: agent.name,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Execute with timeout guard.
+   *
+   * @param {Function} fn - Async function to execute
+   * @param {number} timeout - Timeout in milliseconds
+   * @returns {Promise<*>} Function result
+   * @private
+   */
+  _executeWithTimeout(fn, timeout) {
+    return Promise.race([
+      fn(),
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error("Agent invocation timed out")),
+          timeout,
+        ),
+      ),
+    ]);
+  }
+
+  /**
+   * Record an invocation to the audit log.
+   * @param {Object} result - Invocation result
+   * @private
+   */
+  _recordInvocation(result) {
+    this._invocations.push({
+      ...result,
+      recordedAt: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * Get the full audit log of invocations.
+   * @returns {Object[]} All invocation records
+   */
+  getLog() {
+    return [...this._invocations];
+  }
+
+  /**
+   * Check if an agent is supported.
+   * @param {string} agentName - Agent name
+   * @returns {boolean}
+   */
+  isAgentSupported(agentName) {
+    const name = agentName.replace(/^@/, "").toLowerCase();
+    return SUPPORTED_AGENTS[name] !== undefined;
+  }
+
+  /**
+   * Get all supported agents.
+   * @returns {Object} Map of supported agents
+   */
+  getSupportedAgents() {
+    return { ...SUPPORTED_AGENTS };
+  }
+
+  /**
+   * Generate unique invocation ID.
+   * @returns {string}
+   * @private
+   */
+  _generateId() {
+    return `inv-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  /**
+   * Debug logger.
+   * @param {string} message
+   * @private
+   */
+  _log(message) {
+    if (this.debug) {
+      console.log(`[AgentInvoker] ${message}`);
+    }
+  }
+}
+
+module.exports = { AgentInvoker, SUPPORTED_AGENTS, InvocationStatus };

package/.merlin-core/core/orchestration/condition-evaluator.js

@@ -0,0 +1,250 @@
+/**
+ * Condition Evaluator -- Evaluates conditions for workflow branching
+ *
+ * DETERMINISTIC: All evaluations use filesystem checks, config values,
+ * and state data. No AI involvement in condition evaluation.
+ *
+ * Supports conditions: fileExists, configValue, envVar,
+ * phaseCompleted, gateApproved.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/orchestration/condition-evaluator
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Condition evaluation result
+ * @typedef {Object} ConditionResult
+ * @property {boolean} met - Whether the condition is met
+ * @property {string} reason - Human-readable explanation
+ */
+
+/**
+ * ConditionEvaluator -- Evaluates workflow branching conditions.
+ */
+class ConditionEvaluator {
+  /**
+   * @param {Object} [options] - Configuration options
+   * @param {string} [options.projectRoot] - Project root path
+   * @param {Object} [options.phaseOutputs={}] - Map of phase ID to output data
+   * @param {Object} [options.gateResults={}] - Map of gate key to evaluation result
+   */
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this._phaseOutputs = options.phaseOutputs || {};
+    this._gateResults = options.gateResults || {};
+  }
+
+  /**
+   * Evaluate a condition expression.
+   *
+   * Supported condition types:
+   * - fileExists:<path>         -- checks if file exists relative to projectRoot
+   * - configValue:<key>=<val>   -- checks if config key matches value
+   * - envVar:<name>             -- checks if environment variable is set
+   * - phaseCompleted:<phaseId>  -- checks if a phase completed successfully
+   * - gateApproved:<gateKey>    -- checks if a gate was approved
+   *
+   * @param {string} condition - Condition expression
+   * @param {Object} [context={}] - Additional evaluation context
+   * @returns {ConditionResult} Whether condition is met, with reason
+   */
+  evaluate(condition, context = {}) {
+    if (!condition || typeof condition !== "string") {
+      return { met: true, reason: "No condition specified (default: true)" };
+    }
+
+    const trimmed = condition.trim();
+
+    // Parse condition type and parameters
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex === -1) {
+      // Simple boolean condition name -- check context
+      return this._evaluateSimple(trimmed, context);
+    }
+
+    const type = trimmed.substring(0, colonIndex);
+    const params = trimmed.substring(colonIndex + 1);
+
+    switch (type) {
+      case "fileExists":
+        return this._evaluateFileExists(params, context);
+
+      case "configValue":
+        return this._evaluateConfigValue(params, context);
+
+      case "envVar":
+        return this._evaluateEnvVar(params);
+
+      case "phaseCompleted":
+        return this._evaluatePhaseCompleted(params);
+
+      case "gateApproved":
+        return this._evaluateGateApproved(params);
+
+      default:
+        return {
+          met: true,
+          reason: `Unknown condition type: ${type} (default: true)`,
+        };
+    }
+  }
+
+  /**
+   * Evaluate a simple named condition from context.
+   *
+   * @param {string} name - Condition name
+   * @param {Object} context - Context that may contain boolean flags
+   * @returns {ConditionResult}
+   * @private
+   */
+  _evaluateSimple(name, context) {
+    if (context[name] !== undefined) {
+      const met = Boolean(context[name]);
+      return { met, reason: `Context flag "${name}" is ${met}` };
+    }
+    return {
+      met: true,
+      reason: `Unknown simple condition "${name}" (default: true)`,
+    };
+  }
+
+  /**
+   * Check if a file exists relative to the project root.
+   *
+   * @param {string} relativePath - Path relative to projectRoot
+   * @returns {ConditionResult}
+   * @private
+   */
+  _evaluateFileExists(relativePath) {
+    const fullPath = path.join(this.projectRoot, relativePath.trim());
+    const exists = fs.existsSync(fullPath);
+    return {
+      met: exists,
+      reason: exists
+        ? `File exists: ${relativePath}`
+        : `File not found: ${relativePath}`,
+    };
+  }
+
+  /**
+   * Check if a config value matches an expected value.
+   *
+   * Format: key=value (checks context.config or environment)
+   *
+   * @param {string} params - "key=value" string
+   * @param {Object} context - Context with optional config object
+   * @returns {ConditionResult}
+   * @private
+   */
+  _evaluateConfigValue(params, context) {
+    const eqIndex = params.indexOf("=");
+    if (eqIndex === -1) {
+      // Just check if key exists and is truthy
+      const key = params.trim();
+      const value = context.config?.[key];
+      const met = Boolean(value);
+      return {
+        met,
+        reason: met ? `Config "${key}" is set` : `Config "${key}" is not set`,
+      };
+    }
+
+    const key = params.substring(0, eqIndex).trim();
+    const expected = params.substring(eqIndex + 1).trim();
+    const actual = String(context.config?.[key] ?? "");
+    const met = actual === expected;
+
+    return {
+      met,
+      reason: met
+        ? `Config "${key}" matches "${expected}"`
+        : `Config "${key}" is "${actual}", expected "${expected}"`,
+    };
+  }
+
+  /**
+   * Check if an environment variable is set.
+   *
+   * @param {string} varName - Environment variable name
+   * @returns {ConditionResult}
+   * @private
+   */
+  _evaluateEnvVar(varName) {
+    const name = varName.trim();
+    const value = process.env[name];
+    const met = value !== undefined && value !== "";
+
+    return {
+      met,
+      reason: met
+        ? `Environment variable "${name}" is set`
+        : `Environment variable "${name}" is not set`,
+    };
+  }
+
+  /**
+   * Check if a workflow phase completed successfully.
+   *
+   * @param {string} phaseId - Phase identifier
+   * @returns {ConditionResult}
+   * @private
+   */
+  _evaluatePhaseCompleted(phaseId) {
+    const id = phaseId.trim();
+    const output = this._phaseOutputs[id];
+    const met =
+      output && (output.status === "completed" || output.status === "success");
+
+    return {
+      met: Boolean(met),
+      reason: met
+        ? `Phase "${id}" completed successfully`
+        : `Phase "${id}" has not completed`,
+    };
+  }
+
+  /**
+   * Check if a quality gate was approved.
+   *
+   * @param {string} gateKey - Gate key (e.g., 'research_to_architecture')
+   * @returns {ConditionResult}
+   * @private
+   */
+  _evaluateGateApproved(gateKey) {
+    const key = gateKey.trim();
+    const result = this._gateResults[key];
+    const met = result && result.verdict === "approved";
+
+    return {
+      met: Boolean(met),
+      reason: met
+        ? `Gate "${key}" was approved`
+        : `Gate "${key}" was not approved (verdict: ${result?.verdict || "none"})`,
+    };
+  }
+
+  /**
+   * Update phase outputs for condition evaluation.
+   * @param {Object} outputs - Map of phase ID to output data
+   */
+  setPhaseOutputs(outputs) {
+    this._phaseOutputs = outputs || {};
+  }
+
+  /**
+   * Update gate results for condition evaluation.
+   * @param {Object} results - Map of gate key to evaluation result
+   */
+  setGateResults(results) {
+    this._gateResults = results || {};
+  }
+}
+
+module.exports = { ConditionEvaluator };