avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/smallest-safe-plan.js

@@ -0,0 +1,214 @@
+"use strict";
+
+const CONTRACT = "avorelo.smallestSafePlan.v1";
+
+const DEFAULT_ANTI_GOALS = Object.freeze([
+  "dashboard_rewrite",
+  "new_orchestrator",
+  "broad_refactor",
+  "autonomous_executor",
+  "generic_platform",
+  "new_abstraction_without_reuse_evidence",
+]);
+
+const SCOPE_TIERS = Object.freeze(["tiny", "small", "medium", "large", "unsafe"]);
+
+const DIFF_SIZES = Object.freeze(["tiny", "small", "medium", "large"]);
+
+function generatePlan(taskClassification, riskClassification, routeDecision, options = {}) {
+  const taskType = taskClassification.taskType;
+  const riskLevel = riskClassification.level;
+  const contextPacket = options.contextPacket || null;
+
+  const antiGoals = [...DEFAULT_ANTI_GOALS];
+  const approvalRequiredIf = [];
+  const escalationTriggers = [];
+  const allowedAreas = [];
+  const blockedAreas = [];
+  let allowedFilesMax = 5;
+  let expectedDiffSize = "small";
+  let scopeTier = "small";
+  let refactorAllowed = false;
+  let newAbstractionAllowed = false;
+
+  // Scope from task type
+  switch (taskType) {
+    case "docs-only":
+    case "release-doc-update":
+      scopeTier = "tiny";
+      allowedFilesMax = 3;
+      expectedDiffSize = "tiny";
+      allowedAreas.push("docs", "artifacts");
+      blockedAreas.push("scripts/lib", "src", "package.json");
+      break;
+
+    case "public-copy":
+    case "article-writing":
+      scopeTier = "small";
+      allowedFilesMax = 5;
+      expectedDiffSize = "small";
+      allowedAreas.push("docs", "artifacts", "apps/public-web");
+      blockedAreas.push("scripts/lib", "package.json");
+      break;
+
+    case "capability-development":
+      scopeTier = "medium";
+      allowedFilesMax = 15;
+      expectedDiffSize = "medium";
+      allowedAreas.push("scripts/lib", "tests", "docs", "artifacts");
+      break;
+
+    case "bugfix":
+      scopeTier = "small";
+      allowedFilesMax = 8;
+      expectedDiffSize = "small";
+      allowedAreas.push("scripts/lib", "tests", "src");
+      break;
+
+    case "ui-compact-surface":
+    case "dashboard-change":
+      scopeTier = "small";
+      allowedFilesMax = 8;
+      expectedDiffSize = "small";
+      allowedAreas.push("scripts/lib", "tests");
+      antiGoals.push("dashboard_rewrite_without_approval");
+      break;
+
+    case "guard-policy-change":
+    case "production-readiness-review":
+      scopeTier = "medium";
+      allowedFilesMax = 12;
+      expectedDiffSize = "medium";
+      allowedAreas.push("scripts/lib", "tests", "docs");
+      approvalRequiredIf.push("touches_production_guard", "modifies_policy_gate");
+      break;
+
+    case "browser-proof-qa":
+      scopeTier = "tiny";
+      allowedFilesMax = 2;
+      expectedDiffSize = "tiny";
+      allowedAreas.push("artifacts", "docs/dogfood");
+      break;
+
+    case "claim-safety-review":
+      scopeTier = "small";
+      allowedFilesMax = 5;
+      expectedDiffSize = "small";
+      allowedAreas.push("docs", "artifacts");
+      break;
+
+    case "broad-refactor-request":
+      scopeTier = "unsafe";
+      allowedFilesMax = 50;
+      expectedDiffSize = "large";
+      refactorAllowed = true;
+      newAbstractionAllowed = true;
+      approvalRequiredIf.push("broad_scope", "touches_many_files");
+      escalationTriggers.push("scope_exceeds_plan");
+      break;
+
+    case "deploy-request":
+    case "publish-request":
+    case "billing-entitlement-change":
+      scopeTier = "unsafe";
+      allowedFilesMax = 0;
+      expectedDiffSize = "tiny";
+      blockedAreas.push("*");
+      break;
+
+    default:
+      scopeTier = "small";
+      allowedFilesMax = 8;
+      expectedDiffSize = "small";
+  }
+
+  // Risk escalation
+  if (riskLevel === "high" && scopeTier !== "unsafe") {
+    approvalRequiredIf.push("risk_level_high");
+    escalationTriggers.push("unexpected_side_effect");
+  }
+
+  if (riskLevel === "blocked") {
+    scopeTier = "unsafe";
+    allowedFilesMax = 0;
+    blockedAreas.push("*");
+  }
+
+  // Standard approval triggers
+  approvalRequiredIf.push("touches_billing", "adds_dependency", "deploys", "publishes");
+
+  // Context packet awareness
+  if (contextPacket && contextPacket.selectedRefs) {
+    const contextAreas = contextPacket.selectedRefs
+      .map((r) => r.ref)
+      .filter(Boolean)
+      .map((r) => r.split("/")[0])
+      .filter(Boolean);
+    if (contextAreas.length > 0 && allowedAreas.length === 0) {
+      allowedAreas.push(...[...new Set(contextAreas)].slice(0, 5));
+    }
+  }
+
+  // Lean code flags
+  const leanFlags = [];
+  if (taskType !== "broad-refactor-request" && !refactorAllowed) {
+    leanFlags.push("prefer_existing_patterns");
+    leanFlags.push("prefer_local_change");
+    leanFlags.push("prefer_one_clear_fix");
+    leanFlags.push("prefer_deterministic_validation");
+  }
+
+  // Proof commands
+  const proofCommands = buildProofCommands(taskClassification);
+
+  return {
+    schemaVersion: CONTRACT,
+    scopeTier,
+    allowedFilesMax,
+    expectedDiffSize,
+    allowedAreas: [...new Set(allowedAreas)],
+    blockedAreas: [...new Set(blockedAreas)],
+    antiGoals: [...new Set(antiGoals)],
+    refactorAllowed,
+    newAbstractionAllowed,
+    approvalRequiredIf: [...new Set(approvalRequiredIf)],
+    escalationTriggers: [...new Set(escalationTriggers)],
+    leanFlags,
+    proofCommands,
+    rollbackPlan: buildRollbackPlan(taskType),
+  };
+}
+
+function buildProofCommands(taskClassification) {
+  const commands = [];
+  const taskType = taskClassification.taskType;
+
+  if (["capability-development", "bugfix", "guard-policy-change", "ui-compact-surface", "dashboard-change"].includes(taskType)) {
+    commands.push("node --test tests/*.test.js");
+  }
+
+  if (["capability-development", "guard-policy-change", "production-readiness-review"].includes(taskType)) {
+    commands.push("node scripts/validate-capability-contracts.js");
+  }
+
+  if (["public-copy", "article-writing", "claim-safety-review"].includes(taskType)) {
+    commands.push("node scripts/validate-context-compiler.js");
+  }
+
+  return commands;
+}
+
+function buildRollbackPlan(taskType) {
+  if (["deploy-request", "publish-request", "billing-entitlement-change"].includes(taskType)) {
+    return "Blocked — no action taken.";
+  }
+  return "Revert the PR. Existing subsystems continue working independently.";
+}
+
+module.exports = {
+  generatePlan,
+  DEFAULT_ANTI_GOALS,
+  SCOPE_TIERS,
+  DIFF_SIZES,
+  CONTRACT,
+};

package/scripts/lib/smart-routing-plan.js

@@ -0,0 +1,115 @@
+"use strict";
+
+const ROUTES = [
+  "direct", "guarded", "proof_first", "test_first", "browser_proof",
+  "production_confidence", "security_review", "docs_only", "no_connect",
+  "human_review_required", "recovery_first", "capability_quarantine_review", "unknown",
+];
+
+const TASK_ROUTE_MAP = {
+  documentation: "docs_only",
+  test: "guarded",
+  refactor: "test_first",
+  implementation: "guarded",
+  public_web: "browser_proof",
+  browser_frontend: "browser_proof",
+  configuration: "guarded",
+  dependency_change: "production_confidence",
+  deployment_environment: "production_confidence",
+  security_sensitive: "security_review",
+  data_permissions: "security_review",
+  observability_recovery: "recovery_first",
+  cost_abuse: "production_confidence",
+  webhook_idempotency: "production_confidence",
+  skill_mcp_capability: "capability_quarantine_review",
+  prompt_context: "no_connect",
+  value_reporting: "no_connect",
+  unknown: "human_review_required",
+};
+
+const NO_CONNECT_TASKS = new Set([
+  "documentation", "prompt_context", "value_reporting",
+]);
+
+function computeRoutingPlan(taskResult, governedExposure, contextBudget) {
+  const startMs = Date.now();
+  const reasonCodes = [];
+  const why = [];
+  const requiredGuards = [];
+  const requiredProof = [];
+
+  const taskType = taskResult.type || "unknown";
+  const hasBlocked = (governedExposure.guardEvidenceRefs || []).some((g) => g.blocked);
+  const proofExpectations = governedExposure.proofExpectations || [];
+
+  let route = TASK_ROUTE_MAP[taskType] || "human_review_required";
+
+  if (hasBlocked) {
+    route = "human_review_required";
+    why.push("Existing guard is blocked — cannot route directly.");
+    reasonCodes.push("EXISTING_GUARD_BLOCKED", "ROUTE_HUMAN_REVIEW_REQUIRED");
+  }
+
+  if (taskResult.confidence === "none" || taskResult.confidence === "low") {
+    if (route === "direct") route = "guarded";
+    if (taskResult.confidence === "none") {
+      route = "human_review_required";
+      reasonCodes.push("ROUTE_HUMAN_REVIEW_REQUIRED");
+    }
+    why.push(`Task confidence is ${taskResult.confidence}.`);
+  }
+
+  if (contextBudget.budgetClass === "oversized") {
+    if (route === "direct") route = "guarded";
+    why.push("Context is oversized.");
+    reasonCodes.push("CONTEXT_BUDGET_EXCEEDED");
+  }
+
+  if (NO_CONNECT_TASKS.has(taskType) && !hasBlocked) {
+    route = taskType === "documentation" ? "docs_only" : "no_connect";
+    why.push(`Task type ${taskType} supports no-connect route.`);
+    reasonCodes.push("ROUTE_NO_CONNECT");
+  }
+
+  if (proofExpectations.includes("tests_required")) {
+    requiredProof.push("tests");
+    if (route === "direct") route = "test_first";
+  }
+  if (proofExpectations.includes("browser_proof_required")) {
+    requiredProof.push("browser_proof");
+    if (route === "direct" || route === "guarded") route = "browser_proof";
+  }
+  if (proofExpectations.includes("production_confidence_required")) {
+    requiredGuards.push("production_confidence");
+  }
+  if (proofExpectations.includes("security_review_required")) {
+    requiredGuards.push("security_review");
+    if (route !== "human_review_required") route = "security_review";
+  }
+
+  if (!why.length) {
+    why.push(`Task type ${taskType} maps to ${route} route.`);
+  }
+
+  const routeReasonCode = `ROUTE_${route.toUpperCase()}`;
+  if (!reasonCodes.includes(routeReasonCode)) reasonCodes.push(routeReasonCode);
+
+  let confidence = taskResult.confidence === "high" ? "high" : taskResult.confidence === "medium" ? "medium" : "low";
+  if (hasBlocked) confidence = "low";
+
+  const approvalNeeded = route === "human_review_required" || route === "security_review" || hasBlocked;
+
+  return {
+    status: hasBlocked ? "blocked" : "ready",
+    recommendedRoute: route,
+    routeConfidence: confidence,
+    why,
+    requiredGuards,
+    requiredProof,
+    approvalNeeded,
+    reasonCodes,
+    durationMs: Date.now() - startMs,
+  };
+}
+
+module.exports = { computeRoutingPlan, ROUTES, TASK_ROUTE_MAP };