avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/execution-route-governor.js

@@ -0,0 +1,179 @@
+"use strict";
+
+// Execution Route Governor — run-level route binding for the Governed Run Contract.
+// Selects execution route based on task classification, risk level, and context signals.
+// This is the run contract's route decision layer. It does NOT replace:
+//   - ai-work-efficiency-routing.js (owner of efficiency/economics routing signals)
+// The efficiency layer provides signal-level routing; this layer binds those signals
+// to a specific run execution route (deterministic_only, targeted_code_edit, blocked, etc.).
+// See docs/internal/capability-ownership-registry.md
+
+const CONTRACT = "avorelo.executionRouteGovernor.v1";
+
+const ROUTE_DECISIONS = Object.freeze([
+  "deterministic_only",
+  "deterministic_first",
+  "targeted_code_edit",
+  "cheap_llm_ok",
+  "deep_reasoning_required",
+  "long_context_required",
+  "browser_proof_required",
+  "github_action_required",
+  "external_api_blocked",
+  "needs_decision",
+  "blocked",
+]);
+
+const MODEL_CLASSES = Object.freeze(["none", "cheap_llm", "deep_reasoning", "long_context"]);
+
+function selectRoute(taskClassification, riskClassification, options = {}) {
+  const taskType = taskClassification.taskType;
+  const riskLevel = riskClassification.level;
+  const sideEffectLevel = riskClassification.sideEffectLevel;
+  const contextPacket = options.contextPacket || null;
+  const capabilityContract = options.capabilityContract || null;
+
+  const reasonCodes = [];
+  let decision = taskClassification.routeDefault || "deterministic_first";
+  let modelClass = "none";
+  let requiresHumanApproval = false;
+  const allowedTools = [];
+  const blockedTools = [];
+
+  // Blocked routes override everything
+  if (riskLevel === "blocked") {
+    decision = "blocked";
+    modelClass = "none";
+    requiresHumanApproval = true;
+    reasonCodes.push("risk_blocked");
+    return buildRoute(decision, modelClass, requiresHumanApproval, reasonCodes, allowedTools, blockedTools);
+  }
+
+  // Needs-decision routes — check before side-effect gates
+  if (taskType === "broad-refactor-request" || decision === "needs_decision") {
+    decision = "needs_decision";
+    requiresHumanApproval = true;
+    reasonCodes.push("scope_requires_decision");
+    return buildRoute(decision, modelClass, requiresHumanApproval, reasonCodes, allowedTools, blockedTools);
+  }
+
+  // Side-effect based gates
+  if (sideEffectLevel === "destructive" || sideEffectLevel === "external_write") {
+    decision = "blocked";
+    requiresHumanApproval = true;
+    reasonCodes.push("destructive_or_external_write_blocked");
+    return buildRoute(decision, modelClass, requiresHumanApproval, reasonCodes, allowedTools, blockedTools);
+  }
+
+  // Route selection based on task type
+  switch (taskType) {
+    case "docs-only":
+      decision = "deterministic_only";
+      modelClass = "none";
+      allowedTools.push("file_read", "file_write", "validators");
+      reasonCodes.push("docs_only_deterministic");
+      break;
+
+    case "release-doc-update":
+      decision = "deterministic_first";
+      modelClass = "none";
+      allowedTools.push("file_read", "file_write", "validators");
+      reasonCodes.push("release_doc_deterministic_first");
+      break;
+
+    case "public-copy":
+    case "article-writing":
+      decision = "deterministic_first";
+      modelClass = "cheap_llm";
+      allowedTools.push("file_read", "file_write", "validators", "claim_safety");
+      reasonCodes.push("public_content_claim_safety_required");
+      break;
+
+    case "capability-development":
+    case "bugfix":
+    case "ui-compact-surface":
+      decision = "targeted_code_edit";
+      modelClass = "cheap_llm";
+      allowedTools.push("file_read", "file_write", "tests", "validators");
+      reasonCodes.push("code_edit_targeted");
+      break;
+
+    case "dashboard-change":
+      decision = "targeted_code_edit";
+      modelClass = "cheap_llm";
+      allowedTools.push("file_read", "file_write", "tests", "validators");
+      blockedTools.push("dashboard_rewrite");
+      reasonCodes.push("dashboard_no_rewrite");
+      break;
+
+    case "production-readiness-review":
+    case "guard-policy-change":
+      decision = riskLevel === "high" ? "deep_reasoning_required" : "targeted_code_edit";
+      modelClass = riskLevel === "high" ? "deep_reasoning" : "cheap_llm";
+      allowedTools.push("file_read", "file_write", "tests", "validators", "guard_tests");
+      reasonCodes.push("high_proof_required");
+      break;
+
+    case "browser-proof-qa":
+      decision = "browser_proof_required";
+      modelClass = "none";
+      allowedTools.push("browser", "screenshot", "validators");
+      reasonCodes.push("browser_proof_route");
+      break;
+
+    case "claim-safety-review":
+      decision = "deterministic_first";
+      modelClass = "none";
+      allowedTools.push("file_read", "validators", "claim_safety");
+      reasonCodes.push("claim_review_deterministic");
+      break;
+
+    default:
+      decision = "deterministic_first";
+      modelClass = "cheap_llm";
+      reasonCodes.push("default_route");
+  }
+
+  // Context packet awareness — prefer bounded context
+  if (contextPacket && contextPacket.metrics) {
+    if (contextPacket.metrics.totalEstimatedTokens > 5000) {
+      if (decision !== "deep_reasoning_required" && decision !== "blocked") {
+        reasonCodes.push("large_context_detected");
+      }
+    }
+  }
+
+  // Capability contract awareness
+  if (capabilityContract) {
+    if (capabilityContract.compliance === "needs_attention") {
+      reasonCodes.push("capability_needs_attention");
+    }
+  }
+
+  // Blocked overrides cheap
+  if (riskLevel === "high" && modelClass === "none") {
+    modelClass = "cheap_llm";
+    reasonCodes.push("risk_elevated_model_class");
+  }
+
+  return buildRoute(decision, modelClass, requiresHumanApproval, reasonCodes, allowedTools, blockedTools);
+}
+
+function buildRoute(decision, modelClass, requiresHumanApproval, reasonCodes, allowedTools, blockedTools) {
+  return {
+    schemaVersion: CONTRACT,
+    decision,
+    reasonCodes: [...new Set(reasonCodes)],
+    allowedTools,
+    blockedTools,
+    modelClass,
+    requiresHumanApproval,
+  };
+}
+
+module.exports = {
+  selectRoute,
+  ROUTE_DECISIONS,
+  MODEL_CLASSES,
+  CONTRACT,
+};