@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/orchestration/decision-tree.js

@@ -0,0 +1,192 @@
+/**
+ * Decision Tree -- Project State Router
+ *
+ * Detects project state and routes to the appropriate workflow.
+ * Uses codified decision logic (no LLM reasoning for routing).
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ * Routes project state to the appropriate workflow.
+ *
+ * @module core/orchestration/decision-tree
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Project state enum -- detected by the decision tree
+ * @enum {string}
+ */
+const ProjectState = {
+  /** No .merlin-core config found -- needs initialization */
+  NO_CONFIG: "NO_CONFIG",
+  /** Config exists but no docs/ directory */
+  EXISTING_NO_DOCS: "EXISTING_NO_DOCS",
+  /** Config and docs both exist -- ready for development */
+  EXISTING_WITH_DOCS: "EXISTING_WITH_DOCS",
+  /** Brand new project -- no package.json, .git, or docs */
+  GREENFIELD: "GREENFIELD",
+};
+
+/**
+ * Route definition returned by the decision tree
+ * @typedef {Object} RouteResult
+ * @property {string} workflow - Workflow ID to execute
+ * @property {string} [startPhase] - Phase to start from (if not beginning)
+ * @property {string} reason - Human-readable routing reason
+ */
+
+/**
+ * Evaluation result combining state detection and routing
+ * @typedef {Object} EvaluationResult
+ * @property {string} state - Detected ProjectState
+ * @property {string} workflow - Workflow ID
+ * @property {string} [startPhase] - Starting phase override
+ * @property {string} reason - Routing reason
+ * @property {number} evaluatedAt - Timestamp of evaluation
+ * @property {Object} indicators - Detection indicators used
+ */
+
+/**
+ * DecisionTree -- Detects project state and routes to workflows.
+ *
+ * All routing decisions are codified (if/else, lookup tables).
+ * No LLM reasoning is involved in the routing path.
+ */
+class DecisionTree {
+  /**
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} [options] - Configuration options
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(projectRoot, options = {}) {
+    if (!projectRoot || typeof projectRoot !== "string") {
+      throw new Error("projectRoot is required and must be a string");
+    }
+
+    this.projectRoot = projectRoot;
+    this.options = { debug: false, ...options };
+  }
+
+  /**
+   * Detect the current project state by checking filesystem indicators.
+   *
+   * Detection order:
+   * 1. GREENFIELD -- no package.json, no .git, no docs/
+   * 2. NO_CONFIG  -- no .merlin-core directory
+   * 3. EXISTING_NO_DOCS -- .merlin-core exists but no docs/
+   * 4. EXISTING_WITH_DOCS -- both exist
+   *
+   * @returns {string} ProjectState enum value
+   */
+  detectState() {
+    const hasPackageJson = fs.existsSync(
+      path.join(this.projectRoot, "package.json"),
+    );
+    const hasGit = fs.existsSync(path.join(this.projectRoot, ".git"));
+    const hasMerlinConfig = fs.existsSync(
+      path.join(this.projectRoot, ".merlin-core"),
+    );
+    const hasDocs = fs.existsSync(path.join(this.projectRoot, "docs"));
+
+    this._log(
+      `Indicators: package.json=${hasPackageJson}, .git=${hasGit}, .merlin-core=${hasMerlinConfig}, docs=${hasDocs}`,
+    );
+
+    // Check 1: Greenfield -- nothing exists
+    if (!hasPackageJson && !hasGit && !hasDocs) {
+      return ProjectState.GREENFIELD;
+    }
+
+    // Check 2: No Merlin config
+    if (!hasMerlinConfig) {
+      return ProjectState.NO_CONFIG;
+    }
+
+    // Check 3: Config exists but no docs
+    if (!hasDocs) {
+      return ProjectState.EXISTING_NO_DOCS;
+    }
+
+    // Check 4: Everything present
+    return ProjectState.EXISTING_WITH_DOCS;
+  }
+
+  /**
+   * Route to the appropriate workflow based on project state.
+   *
+   * @param {string} state - ProjectState value
+   * @returns {RouteResult} Workflow route definition
+   */
+  route(state) {
+    const routes = {
+      [ProjectState.GREENFIELD]: {
+        workflow: "folloni-funnel",
+        reason: "New project -- full Folloni pipeline from scratch",
+      },
+      [ProjectState.NO_CONFIG]: {
+        workflow: "merlin-init",
+        reason: "Project needs Merlin initialization before development",
+      },
+      [ProjectState.EXISTING_NO_DOCS]: {
+        workflow: "folloni-funnel",
+        startPhase: "research",
+        reason: "Existing code but no documentation -- start with research",
+      },
+      [ProjectState.EXISTING_WITH_DOCS]: {
+        workflow: "development-cycle",
+        reason: "Full project ready for development cycle",
+      },
+    };
+
+    return routes[state] || routes[ProjectState.GREENFIELD];
+  }
+
+  /**
+   * Run the full decision tree: detect state, route, and return action.
+   *
+   * @returns {EvaluationResult} Complete evaluation result
+   */
+  evaluate() {
+    const state = this.detectState();
+    const route = this.route(state);
+
+    const result = {
+      state,
+      ...route,
+      evaluatedAt: Date.now(),
+      indicators: {
+        hasPackageJson: fs.existsSync(
+          path.join(this.projectRoot, "package.json"),
+        ),
+        hasGit: fs.existsSync(path.join(this.projectRoot, ".git")),
+        hasMerlinConfig: fs.existsSync(
+          path.join(this.projectRoot, ".merlin-core"),
+        ),
+        hasDocs: fs.existsSync(path.join(this.projectRoot, "docs")),
+      },
+    };
+
+    this._log(
+      `Evaluation: state=${state}, workflow=${route.workflow}, reason=${route.reason}`,
+    );
+
+    return result;
+  }
+
+  /**
+   * Debug logger.
+   * @param {string} message - Log message
+   * @private
+   */
+  _log(message) {
+    if (this.options.debug) {
+      console.log(`[DecisionTree] ${message}`);
+    }
+  }
+}
+
+module.exports = { DecisionTree, ProjectState };

package/.merlin-core/core/orchestration/executor-assignment.js

@@ -0,0 +1,372 @@
+/**
+ * Executor Assignment -- Assigns agents to tasks based on complexity and type
+ *
+ * DETERMINISTIC: Assignment uses heuristics and keyword matching.
+ * No AI involvement in agent selection.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ * and task-centric (rather than story-centric) model.
+ *
+ * @module core/orchestration/executor-assignment
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const { classifyTop } = require("./intent-classifier");
+
+/**
+ * Task complexity levels
+ * @enum {string}
+ */
+const Complexity = {
+  TRIVIAL: "trivial",
+  SIMPLE: "simple",
+  MODERATE: "moderate",
+  COMPLEX: "complex",
+  CRITICAL: "critical",
+};
+
+/**
+ * Task type to recommended agent mapping
+ * @constant {Object.<string, Object>}
+ */
+const TASK_TYPE_AGENTS = {
+  implementation: {
+    primary: "dev",
+    fallback: "architect",
+    qualityGate: "qa",
+  },
+  testing: {
+    primary: "qa",
+    fallback: "dev",
+    qualityGate: "architect",
+  },
+  architecture: {
+    primary: "architect",
+    fallback: "analyst",
+    qualityGate: "pm",
+  },
+  research: {
+    primary: "researcher",
+    fallback: "web-researcher",
+    qualityGate: "analyst",
+  },
+  deployment: {
+    primary: "devops",
+    fallback: "dev",
+    qualityGate: "architect",
+  },
+  database: {
+    primary: "data-engineer",
+    fallback: "dev",
+    qualityGate: "architect",
+  },
+  design: {
+    primary: "ux",
+    fallback: "analyst",
+    qualityGate: "dev",
+  },
+  analysis: {
+    primary: "analyst",
+    fallback: "researcher",
+    qualityGate: "pm",
+  },
+  planning: {
+    primary: "pm",
+    fallback: "po",
+    qualityGate: "architect",
+  },
+  exploration: {
+    primary: "scout",
+    fallback: "researcher",
+    qualityGate: "analyst",
+  },
+};
+
+/**
+ * Keywords used to auto-detect task type from description
+ * @constant {Object.<string, string[]>}
+ */
+const TYPE_KEYWORDS = {
+  implementation: [
+    "implement",
+    "code",
+    "build",
+    "create",
+    "develop",
+    "feature",
+    "function",
+    "class",
+    "module",
+    "api",
+    "endpoint",
+  ],
+  testing: [
+    "test",
+    "qa",
+    "validate",
+    "assert",
+    "coverage",
+    "e2e",
+    "unit",
+    "integration",
+    "regression",
+  ],
+  architecture: [
+    "architecture",
+    "design",
+    "pattern",
+    "adr",
+    "rfc",
+    "scalability",
+    "refactor",
+    "system-design",
+  ],
+  research: [
+    "research",
+    "investigate",
+    "analyze",
+    "study",
+    "benchmark",
+    "evaluate",
+    "poc",
+    "proof-of-concept",
+  ],
+  deployment: [
+    "deploy",
+    "ci/cd",
+    "pipeline",
+    "docker",
+    "kubernetes",
+    "infrastructure",
+    "devops",
+    "release",
+  ],
+  database: [
+    "schema",
+    "migration",
+    "query",
+    "table",
+    "index",
+    "database",
+    "sql",
+    "rls",
+    "data-model",
+  ],
+  design: [
+    "wireframe",
+    "mockup",
+    "ux",
+    "ui",
+    "accessibility",
+    "usability",
+    "figma",
+    "prototype",
+  ],
+  analysis: [
+    "requirements",
+    "user-story",
+    "acceptance",
+    "specification",
+    "business-rule",
+    "stakeholder",
+  ],
+  planning: [
+    "plan",
+    "roadmap",
+    "sprint",
+    "backlog",
+    "prioritize",
+    "milestone",
+    "estimate",
+  ],
+  exploration: [
+    "explore",
+    "discover",
+    "scan",
+    "map",
+    "scout",
+    "reconnaissance",
+    "audit",
+  ],
+};
+
+/**
+ * ExecutorAssignment -- Assigns executor agents to tasks.
+ */
+class ExecutorAssignment {
+  constructor() {
+    // intentionally stateless -- all methods are pure
+  }
+
+  /**
+   * Assign the best agent for a task.
+   *
+   * @param {Object} task - Task definition
+   * @param {string} [task.type] - Explicit task type (overrides auto-detection)
+   * @param {string} [task.description] - Task description (used for auto-detection)
+   * @param {number} [task.fileCount] - Number of files involved
+   * @param {number} [task.locEstimate] - Estimated lines of code
+   * @param {number} [task.dependencyCount] - Number of dependencies
+   * @returns {Object} Assignment with agentId, complexity, qualityGate, reason
+   */
+  assign(task) {
+    const taskType = task.type || this._detectType(task.description || "");
+    const complexity = this._classifyComplexity(task, taskType);
+    const agentId = this._selectAgent(taskType, complexity);
+    const mapping =
+      TASK_TYPE_AGENTS[taskType] || TASK_TYPE_AGENTS.implementation;
+
+    return {
+      agentId,
+      taskType,
+      complexity,
+      qualityGate: mapping.qualityGate,
+      reason: `Type "${taskType}" (${complexity}) assigned to @${agentId}`,
+    };
+  }
+
+  /**
+   * Classify task complexity using heuristics.
+   *
+   * @param {Object} task - Task with optional fileCount, locEstimate, dependencyCount
+   * @returns {string} Complexity enum value
+   * @private
+   */
+  _classifyComplexity(task, taskType) {
+    // Delegate to standalone function to avoid duplication (review fix #10)
+    return classifyComplexity(task, taskType);
+  }
+
+  /**
+   * Select the best agent for a task type and complexity.
+   *
+   * For CRITICAL complexity, prefers the architect for oversight.
+   * Otherwise uses the primary agent from the type mapping.
+   *
+   * @param {string} taskType - Task type key
+   * @param {string} complexity - Complexity level
+   * @returns {string} Agent ID
+   * @private
+   */
+  _selectAgent(taskType, complexity) {
+    const mapping = TASK_TYPE_AGENTS[taskType];
+    if (!mapping) return "dev";
+
+    // Critical tasks get architect oversight unless already architecture type
+    if (complexity === Complexity.CRITICAL && taskType !== "architecture") {
+      return "architect";
+    }
+
+    return mapping.primary;
+  }
+
+  /**
+   * Auto-detect task type from description using IntentClassifier.
+   *
+   * Maps the top-scoring agent back to a task type via TASK_TYPE_AGENTS.
+   * Falls back to TYPE_KEYWORDS matching if classifier returns no result.
+   *
+   * @param {string} description - Task description text
+   * @returns {string} Detected task type
+   * @private
+   */
+  _detectType(description) {
+    if (!description) return "implementation";
+
+    // Use intent classifier to find best agent, then map back to task type
+    const result = classifyTop(description);
+    if (result && result.confidence >= 0.1) {
+      const agentToType = this._buildAgentToTypeMap();
+      const taskType = agentToType[result.agentId];
+      if (taskType) return taskType;
+    }
+
+    // Fallback: legacy keyword matching for edge cases
+    const normalized = description.toLowerCase();
+    const scores = {};
+
+    for (const [type, keywords] of Object.entries(TYPE_KEYWORDS)) {
+      let score = 0;
+      for (const keyword of keywords) {
+        if (normalized.includes(keyword)) {
+          score++;
+        }
+      }
+      if (score > 0) {
+        scores[type] = score;
+      }
+    }
+
+    let bestType = "implementation";
+    let bestScore = 0;
+    for (const [type, score] of Object.entries(scores)) {
+      if (score > bestScore) {
+        bestScore = score;
+        bestType = type;
+      }
+    }
+
+    return bestType;
+  }
+
+  /**
+   * Build reverse mapping from agent ID to task type.
+   * @returns {Object.<string, string>}
+   * @private
+   */
+  _buildAgentToTypeMap() {
+    const map = {};
+    for (const [type, config] of Object.entries(TASK_TYPE_AGENTS)) {
+      map[config.primary] = type;
+      if (config.fallback) map[config.fallback] = map[config.fallback] || type;
+    }
+    return map;
+  }
+}
+
+/**
+ * Classify task complexity as a standalone function.
+ * Reusable by MasterOrchestrator for response mode escalation.
+ *
+ * @param {Object} task - Task with optional fileCount, locEstimate, dependencyCount
+ * @returns {string} Complexity enum value
+ */
+function classifyComplexity(task, taskType) {
+  const files = task.fileCount || 0;
+  const loc = task.locEstimate || 0;
+  const deps = task.dependencyCount || 0;
+
+  let score = 0;
+  if (files > 10) score += 3;
+  else if (files > 5) score += 2;
+  else if (files > 1) score += 1;
+
+  if (loc > 1000) score += 3;
+  else if (loc > 300) score += 2;
+  else if (loc > 50) score += 1;
+
+  if (deps > 5) score += 2;
+  else if (deps > 2) score += 1;
+
+  if (score >= 7) return Complexity.CRITICAL;
+  if (score >= 5) return Complexity.COMPLEX;
+  if (score >= 3) return Complexity.MODERATE;
+  if (score >= 1) return Complexity.SIMPLE;
+
+  // v3.0.0 — Implementation tasks can never be TRIVIAL.
+  // TRIVIAL routes to DIRECT mode (no Folloni, no gates, no plan check).
+  // Implementation MUST go through at minimum ROUTE mode.
+  if (taskType === "implementation") return Complexity.SIMPLE;
+
+  return Complexity.TRIVIAL;
+}
+
+module.exports = {
+  ExecutorAssignment,
+  Complexity,
+  TASK_TYPE_AGENTS,
+  TYPE_KEYWORDS,
+  classifyComplexity,
+};