avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/ai-work-efficiency-routing.js

@@ -0,0 +1,623 @@
+"use strict";
+
+const { nowIso, safeWriteJson, safeReadJson } = require("./fsx");
+const { inferTaskType } = require("./ai-task-inference");
+const { computeContextBudget } = require("./context-budget");
+const { computeTokenEfficiency } = require("./token-efficiency-map");
+const { planGovernedExposure } = require("./governed-exposure-planner");
+const { buildPromptCompilerPlan } = require("./prompt-compiler-plan");
+const { computeRoutingPlan } = require("./smart-routing-plan");
+const { classifyWorkClass } = require("./model-work-class-routing");
+const { buildValueLedger, writeValueLedger, LEDGER_REL } = require("./ai-value-ledger");
+const { buildValueProofTable } = require("./ai-value-proof-table");
+const { computeMeasuredLocalValue } = require("./ai-efficiency-measured-value");
+const { buildGuardIntegrationContract } = require("./ai-efficiency-guard-contract");
+
+const CONTRACT = "avorelo.aiWorkEfficiencyRouting.v1";
+const REPORT_DIR_REL = ".claude/cco/reports/ai-work-efficiency-routing";
+const REPORT_JSON_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const COMPLEXITY_LIMITS = {
+  maxChangedFiles: 100,
+  maxStateArtifacts: 300,
+  maxWasteSignals: 20,
+};
+
+function buildAiWorkEfficiencyRouting(cwd, options = {}) {
+  const totalStartMs = Date.now();
+
+  const changedFiles = options.changedFiles || undefined;
+  const taskTypeOverride = options.taskType || undefined;
+  const guardOverride = options.guardOverride || undefined;
+
+  const task = inferTaskType(cwd, { changedFiles, taskType: taskTypeOverride });
+
+  const contextBudget = computeContextBudget(cwd, {
+    changedFiles: task.changedFiles,
+    ...(options.stateArtifactOverride ? { stateArtifactOverride: options.stateArtifactOverride } : {}),
+  });
+
+  let governedExposure;
+  if (guardOverride) {
+    const baseExposure = planGovernedExposure(cwd, task);
+    governedExposure = {
+      ...baseExposure,
+      guardEvidenceRefs: guardOverride,
+      status: guardOverride.some((g) => g.blocked) ? "blocked" : baseExposure.status,
+    };
+  } else {
+    governedExposure = planGovernedExposure(cwd, task);
+  }
+
+  const promptCompilerPlan = buildPromptCompilerPlan(task, governedExposure, contextBudget);
+  const tokenEfficiency = computeTokenEfficiency(contextBudget, governedExposure);
+  const routingPlan = computeRoutingPlan(task, governedExposure, contextBudget);
+  const modelTaskRouting = classifyWorkClass(task, routingPlan);
+  const valueLedger = buildValueLedger(task, routingPlan, contextBudget, tokenEfficiency, governedExposure, promptCompilerPlan);
+
+  const measuredLocalValue = computeMeasuredLocalValue(contextBudget, governedExposure, tokenEfficiency, promptCompilerPlan);
+  const guardIntegrationContract = buildGuardIntegrationContract(cwd);
+
+  const totalDurationMs = Date.now() - totalStartMs;
+
+  const filesInspected = task.changedFiles ? task.changedFiles.length : 0;
+  const artifactsInspected = contextBudget.estimatedContextItems || 0;
+  const bytesInspected = contextBudget.estimatedInputBytes || 0;
+
+  const performanceGuard = {
+    status: "pass",
+    durationMs: totalDurationMs,
+    filesInspected,
+    artifactsInspected,
+    bytesInspected,
+    limitsApplied: [],
+    reasonCodes: ["PERFORMANCE_GUARD_PASS"],
+  };
+
+  if (task.changedFiles && task.changedFiles.length > COMPLEXITY_LIMITS.maxChangedFiles) {
+    performanceGuard.limitsApplied.push("SCAN_LIMIT_APPLIED");
+    performanceGuard.reasonCodes.push("SCAN_LIMIT_APPLIED");
+  }
+  if (artifactsInspected > COMPLEXITY_LIMITS.maxStateArtifacts) {
+    performanceGuard.limitsApplied.push("SCAN_SKIPPED_TOO_LARGE");
+    performanceGuard.reasonCodes.push("SCAN_SKIPPED_TOO_LARGE");
+  }
+  if (totalDurationMs > 1500) {
+    performanceGuard.status = "warn";
+    performanceGuard.reasonCodes.push("PERFORMANCE_GUARD_WARN");
+  }
+  if (totalDurationMs > 5000) {
+    performanceGuard.status = "blocked";
+    performanceGuard.reasonCodes.push("PERFORMANCE_GUARD_TRIGGERED");
+  }
+
+  const overhead = {
+    measured: true,
+    durationMs: totalDurationMs,
+    filesInspected,
+    stateArtifactsInspected: artifactsInspected,
+    limitsApplied: performanceGuard.limitsApplied,
+    reasonCodes: ["OVERHEAD_MEASURED"],
+  };
+
+  if (totalDurationMs > 5000) {
+    overhead.reasonCodes.push("STATUS_OVERHEAD_WARN");
+  } else {
+    overhead.reasonCodes.push("STATUS_OVERHEAD_WITHIN_LIMIT");
+  }
+
+  const isComplexityFallback = checkComplexityKillSwitch(task, contextBudget, tokenEfficiency, routingPlan);
+
+  const fullResult = {
+    task,
+    contextBudget,
+    governedExposure,
+    promptCompilerPlan,
+    tokenEfficiency,
+    routingPlan,
+    modelTaskRouting,
+    valueLedger,
+    overhead,
+  };
+
+  const valueProofTable = buildValueProofTable(fullResult);
+
+  const overallStatus = computeOverallStatus(task, routingPlan, governedExposure, contextBudget, valueLedger, isComplexityFallback);
+  const findings = collectFindings(fullResult, isComplexityFallback);
+
+  const integrations = buildIntegrations(overallStatus, valueLedger, routingPlan, contextBudget, measuredLocalValue);
+
+  const compactOutputQuality = buildCompactOutputQuality(findings, valueLedger, integrations);
+
+  const gatePolicy = {
+    mode: "mixed_warn_block",
+    blockRules: [
+      "GATE_BLOCK_RAW_PROMPT_DUMP", "GATE_BLOCK_RAW_CODE_DUMP", "GATE_BLOCK_RAW_LOG_DUMP",
+      "GATE_BLOCK_SECRET_EXPOSURE", "GATE_BLOCK_FAKE_SAVINGS", "GATE_BLOCK_FAKE_GREEN",
+      "GATE_BLOCK_MISSING_VALUE_PROOF", "GATE_BLOCK_ROUTE_WITHOUT_EVAL",
+      "GATE_BLOCK_MODEL_NETWORK_PROVIDER_CALL",
+    ],
+    warnRules: [
+      "GATE_WARN_HEURISTIC_SAVINGS", "GATE_WARN_PARTIAL_DOGFOOD", "GATE_WARN_CONTRACT_ONLY_GUARD",
+    ],
+    reasonCodes: ["GATE_POLICY_MIXED_WARN_BLOCK"],
+  };
+
+  const report = {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status: overallStatus,
+    summary: buildSummary(overallStatus, findings, routingPlan, valueLedger),
+    task: {
+      type: task.type,
+      confidence: task.confidence,
+      source: task.source,
+      reasonCodes: task.reasonCodes,
+    },
+    governedExposure: {
+      status: governedExposure.status,
+      includeContextRefs: governedExposure.includeContextRefs,
+      excludeContextRefs: governedExposure.excludeContextRefs,
+      exposedCapabilityRefs: governedExposure.exposedCapabilityRefs,
+      suppressedCapabilityRefs: governedExposure.suppressedCapabilityRefs,
+      exposedToolRefs: governedExposure.exposedToolRefs,
+      suppressedToolRefs: governedExposure.suppressedToolRefs,
+      guardEvidenceRefs: governedExposure.guardEvidenceRefs,
+      memoryRefs: governedExposure.memoryRefs,
+      policyRefs: governedExposure.policyRefs,
+      proofExpectations: governedExposure.proofExpectations,
+      reasonCodes: governedExposure.reasonCodes,
+    },
+    promptCompilerPlan: {
+      status: promptCompilerPlan.status,
+      includeContextRefs: promptCompilerPlan.includeContextRefs,
+      excludeContextRefs: promptCompilerPlan.excludeContextRefs,
+      evidenceRefs: promptCompilerPlan.evidenceRefs,
+      proofExpectations: promptCompilerPlan.proofExpectations,
+      suppressedNoise: promptCompilerPlan.suppressedNoise,
+      safeNextRunDefaults: promptCompilerPlan.safeNextRunDefaults,
+      routeInstructions: promptCompilerPlan.routeInstructions,
+      forbiddenOutputRules: promptCompilerPlan.forbiddenOutputRules,
+      reasonCodes: promptCompilerPlan.reasonCodes,
+    },
+    contextBudget: {
+      status: contextBudget.status,
+      budgetClass: contextBudget.budgetClass,
+      estimatedInputBytes: contextBudget.estimatedInputBytes,
+      estimatedContextItems: contextBudget.estimatedContextItems,
+      heuristicTokenEstimate: contextBudget.heuristicTokenEstimate,
+      duplicateContextCount: contextBudget.duplicateContextCount,
+      staleContextCount: contextBudget.staleContextCount,
+      suppressedContextCount: contextBudget.suppressedContextCount,
+      reasonCodes: contextBudget.reasonCodes,
+    },
+    tokenEfficiency: {
+      status: tokenEfficiency.status,
+      avoidableWasteSignals: tokenEfficiency.avoidableWasteSignals,
+      estimatedSavings: tokenEfficiency.estimatedSavings,
+      reasonCodes: tokenEfficiency.reasonCodes,
+    },
+    routingPlan: {
+      status: routingPlan.status,
+      recommendedRoute: routingPlan.recommendedRoute,
+      routeConfidence: routingPlan.routeConfidence,
+      why: routingPlan.why,
+      requiredGuards: routingPlan.requiredGuards,
+      requiredProof: routingPlan.requiredProof,
+      approvalNeeded: routingPlan.approvalNeeded,
+      reasonCodes: routingPlan.reasonCodes,
+    },
+    modelTaskRouting: {
+      status: modelTaskRouting.status,
+      routeClass: modelTaskRouting.routeClass,
+      providerSpecific: false,
+      modelCallsMade: false,
+      reasonCodes: modelTaskRouting.reasonCodes,
+    },
+    valueLedger: {
+      status: valueLedger.status,
+      found: valueLedger.found,
+      prepared: valueLedger.prepared,
+      avoided: valueLedger.avoided,
+      proved: valueLedger.proved,
+      forReview: valueLedger.forReview,
+      safeNextAction: valueLedger.safeNextAction,
+      measurementTypes: valueLedger.measurementTypes,
+      reasonCodes: valueLedger.reasonCodes,
+    },
+    valueProofTable: valueProofTable.table,
+    measuredLocalValue,
+    guardIntegrationContract,
+    gatePolicy,
+    compactOutputQuality,
+    performanceGuard,
+    overhead,
+    findings,
+    integrations,
+    limits: {
+      localFirst: true,
+      deterministicFirst: true,
+      modelCalls: false,
+      networkCalls: false,
+      providerCalls: false,
+      rawPromptDump: false,
+      rawCodeDump: false,
+      rawLogDump: false,
+      secretDump: false,
+      autoModelSwitch: false,
+      autoProviderSwitch: false,
+      autoCapabilityExposure: false,
+      heavyDashboard: false,
+    },
+  };
+
+  return { report };
+}
+
+function computeOverallStatus(task, routingPlan, governedExposure, contextBudget, valueLedger, isComplexityFallback) {
+  if (task.type === "unknown" && task.confidence === "none") return "no_data";
+  if (routingPlan.status === "blocked") return "blocked";
+  if (governedExposure.status === "blocked") return "blocked";
+  if (isComplexityFallback) return "warn";
+  if (contextBudget.status === "warn") return "warn";
+  if (routingPlan.approvalNeeded) return "warn";
+  if (valueLedger.status === "no_data") return "warn";
+  return "pass";
+}
+
+function checkComplexityKillSwitch(task, contextBudget, tokenEfficiency, routingPlan) {
+  const wasteCount = (tokenEfficiency.avoidableWasteSignals || []).length;
+  const changedCount = (task.changedFiles || []).length;
+  if (changedCount > COMPLEXITY_LIMITS.maxChangedFiles) return true;
+  if (contextBudget.estimatedContextItems > COMPLEXITY_LIMITS.maxStateArtifacts) return true;
+  if (wasteCount > COMPLEXITY_LIMITS.maxWasteSignals) return true;
+  return false;
+}
+
+function buildSummary(status, findings, routingPlan, valueLedger) {
+  const blockCount = findings.filter((f) => f.severity === "block").length;
+  const warnCount = findings.filter((f) => f.severity === "warn").length;
+  const infoCount = findings.filter((f) => f.severity === "info").length;
+
+  const text = status === "pass"
+    ? `Route ${routingPlan.recommendedRoute} ready. ${valueLedger.publicSafeSummary}`
+    : status === "blocked"
+      ? `Blocked: ${valueLedger.forReview.length > 0 ? valueLedger.forReview[0] : "existing guard blocked."}`
+      : `Warning: ${warnCount} issue(s) to review. ${valueLedger.publicSafeSummary}`;
+
+  return {
+    title: "AI work efficiency and routing",
+    text,
+    findingCounts: { info: infoCount, warn: warnCount, block: blockCount },
+    safeNextAction: valueLedger.safeNextAction,
+  };
+}
+
+function collectFindings(fullResult, isComplexityFallback) {
+  const findings = [];
+  const task = fullResult.task;
+  const ctx = fullResult.contextBudget;
+  const route = fullResult.routingPlan;
+  const exp = fullResult.governedExposure;
+
+  if (task.type !== "unknown") {
+    findings.push({
+      id: "task-inferred",
+      severity: "info",
+      reasonCode: "TASK_TYPE_INFERRED",
+      title: "Task type inferred",
+      message: `Task inferred as ${task.type} from ${task.source} evidence (${task.confidence} confidence).`,
+      evidenceRefs: [],
+      safeNextAction: "Verify task classification matches intent.",
+    });
+  }
+
+  if (ctx.status === "warn") {
+    findings.push({
+      id: "context-budget-warn",
+      severity: "warn",
+      reasonCode: ctx.budgetClass === "oversized" ? "CONTEXT_BUDGET_EXCEEDED" : "CONTEXT_BUDGET_WARN",
+      title: "Context budget warning",
+      message: `Context is ${ctx.budgetClass} (${ctx.estimatedContextItems} items, ~${ctx.heuristicTokenEstimate} tokens heuristic).`,
+      evidenceRefs: [],
+      safeNextAction: "Review and reduce context before proceeding.",
+    });
+  }
+
+  if (ctx.duplicateContextCount > 0) {
+    findings.push({
+      id: "duplicate-context",
+      severity: "info",
+      reasonCode: "DUPLICATE_CONTEXT_SIGNAL",
+      title: "Duplicate context detected",
+      message: `${ctx.duplicateContextCount} duplicate context ref(s) found.`,
+      evidenceRefs: [],
+      safeNextAction: "Deduplicate context refs.",
+    });
+  }
+
+  if (route.approvalNeeded) {
+    findings.push({
+      id: "approval-needed",
+      severity: "warn",
+      reasonCode: "ROUTE_REVIEW_REQUIRED",
+      title: "Human review required",
+      message: `Route ${route.recommendedRoute} requires approval before proceeding.`,
+      evidenceRefs: [],
+      safeNextAction: "Get human review before continuing.",
+    });
+  }
+
+  const blockedGuards = (exp.guardEvidenceRefs || []).filter((g) => g.blocked);
+  for (const g of blockedGuards) {
+    findings.push({
+      id: `guard-blocked-${g.source}`,
+      severity: "block",
+      reasonCode: "EXISTING_GUARD_BLOCKED",
+      title: `Guard blocked: ${g.source}`,
+      message: `Existing ${g.source} guard is blocked. Route cannot bypass this.`,
+      evidenceRefs: [{ path: g.path, kind: "guard_output", selector: g.source, redacted: true }],
+      safeNextAction: `Resolve ${g.source} guard before proceeding.`,
+    });
+  }
+
+  if (isComplexityFallback) {
+    findings.push({
+      id: "complexity-fallback",
+      severity: "warn",
+      reasonCode: "COMPLEXITY_LIMIT_REACHED",
+      title: "Complexity limit reached",
+      message: "Too many signals or files. Falling back to conservative recommendation.",
+      evidenceRefs: [],
+      safeNextAction: "Review scope and run a smaller proof-first task.",
+    });
+  }
+
+  return findings;
+}
+
+function buildIntegrations(status, valueLedger, routingPlan, contextBudget, measuredLocalValue) {
+  const mlvCompact = measuredLocalValue && measuredLocalValue.suppressedContextRefs > 0
+    ? ` ${measuredLocalValue.suppressedContextRefs} ref(s) suppressed.`
+    : "";
+  const statusLine = `AI route: ${routingPlan.recommendedRoute}; context ${contextBudget.budgetClass}; ${valueLedger.found.length} signal(s).${mlvCompact} Safe next action ready.`;
+
+  return {
+    productHome: {
+      cardSource: "aiWorkEfficiencyRouting",
+      status,
+      found: valueLedger.found.slice(0, 3),
+      fixedOrPrepared: valueLedger.prepared.slice(0, 3),
+      savedOrProved: valueLedger.avoided.slice(0, 3),
+      forReview: valueLedger.forReview.slice(0, 3),
+      safeNextAction: valueLedger.safeNextAction,
+    },
+    radar: {
+      included: true,
+      surface: "ai_work_efficiency_routing",
+    },
+    status: {
+      included: true,
+      compactLine: statusLine,
+    },
+    dashboard: {
+      included: true,
+      compactCardOnly: true,
+    },
+    valueSignals: {
+      included: true,
+      source: "aiWorkEfficiencyRouting",
+    },
+    receipts: {
+      included: true,
+      source: "aiWorkEfficiencyRouting",
+    },
+    nextRun: {
+      included: true,
+      safeDefaultsPrepared: true,
+    },
+    releaseGate: {
+      included: true,
+      mode: "warn",
+    },
+  };
+}
+
+function buildCompactOutputQuality(findings, valueLedger, integrations) {
+  const maxBulletsPerSection = 5;
+  const reasonCodes = ["COMPACT_OUTPUT_QUALITY_PASS"];
+
+  const seenMessages = new Set();
+  let duplicatesSuppressed = 0;
+  for (const f of findings) {
+    if (seenMessages.has(f.message)) duplicatesSuppressed++;
+    else seenMessages.add(f.message);
+  }
+  if (duplicatesSuppressed > 0) reasonCodes.push("COMPACT_OUTPUT_DUPLICATES_SUPPRESSED");
+
+  const homeBullets = (integrations.productHome.found || []).length +
+    (integrations.productHome.fixedOrPrepared || []).length +
+    (integrations.productHome.savedOrProved || []).length +
+    (integrations.productHome.forReview || []).length;
+  if (homeBullets > maxBulletsPerSection * 4) reasonCodes.push("COMPACT_OUTPUT_LIMIT_APPLIED");
+
+  const rawDumpDetected = false;
+  const hasSafeNextAction = !!(valueLedger.safeNextAction && valueLedger.safeNextAction.length > 0);
+  if (hasSafeNextAction) reasonCodes.push("SAFE_NEXT_ACTION_PRESENT");
+
+  const usedPrepared = valueLedger.prepared.length > 0;
+  if (usedPrepared) reasonCodes.push("PREPARED_NOT_FIXED");
+
+  let status = "pass";
+  if (rawDumpDetected) status = "blocked";
+  else if (duplicatesSuppressed > 3) status = "warn";
+
+  return {
+    status,
+    maxBulletsPerSection,
+    duplicatesSuppressed,
+    rawDumpDetected,
+    reasonCodes,
+  };
+}
+
+function generateAiWorkEfficiencyRouting(cwd, options = {}) {
+  const { report } = buildAiWorkEfficiencyRouting(cwd, options);
+  safeWriteJson(cwd, REPORT_JSON_REL, report);
+  return { report };
+}
+
+function readLatestAiWorkEfficiencyRoutingReport(cwd) {
+  return safeReadJson(cwd, REPORT_JSON_REL);
+}
+
+function buildAiWorkEfficiencyRoutingSurface(cwd, options = {}) {
+  let report = readLatestAiWorkEfficiencyRoutingReport(cwd);
+  if (!report && options.buildIfMissing) {
+    const result = generateAiWorkEfficiencyRouting(cwd);
+    report = result.report;
+  }
+  if (!report) {
+    return {
+      showInStatus: false,
+      statusLine: "AI efficiency: no data",
+      status: "no_data",
+    };
+  }
+  return {
+    showInStatus: true,
+    statusLine: report.integrations?.status?.compactLine || "AI efficiency: available",
+    status: report.status,
+    route: report.routingPlan?.recommendedRoute,
+    budgetClass: report.contextBudget?.budgetClass,
+    findingCounts: report.summary?.findingCounts,
+  };
+}
+
+function formatAiWorkEfficiencyRoutingText(report) {
+  const lines = [];
+  lines.push(`AI work efficiency and routing: ${report.status}`);
+  lines.push("");
+
+  if (report.valueLedger.found.length > 0) {
+    lines.push("Found:");
+    for (const f of report.valueLedger.found.slice(0, 5)) lines.push(`  - ${f}`);
+    lines.push("");
+  }
+
+  if (report.valueLedger.prepared.length > 0) {
+    lines.push("Prepared:");
+    for (const p of report.valueLedger.prepared.slice(0, 5)) lines.push(`  - ${p}`);
+    lines.push("");
+  }
+
+  if (report.valueLedger.avoided.length > 0) {
+    lines.push("Saved-or-Proved:");
+    for (const a of report.valueLedger.avoided.slice(0, 5)) lines.push(`  - ${a}`);
+    lines.push("");
+  }
+
+  if (report.valueLedger.forReview.length > 0) {
+    lines.push("For review:");
+    for (const r of report.valueLedger.forReview.slice(0, 5)) lines.push(`  - ${r}`);
+    lines.push("");
+  }
+
+  const mlv = report.measuredLocalValue;
+  if (mlv && mlv.status !== "unavailable") {
+    lines.push("Measured local value:");
+    if (mlv.suppressedContextRefs > 0) lines.push(`  - ${mlv.suppressedContextRefs} context ref(s) suppressed`);
+    if (mlv.capabilityRefsSuppressed > 0) lines.push(`  - ${mlv.capabilityRefsSuppressed} capability(ies) suppressed`);
+    if (mlv.toolRefsSuppressed > 0) lines.push(`  - ${mlv.toolRefsSuppressed} tool(s) suppressed`);
+    if (mlv.staleRefsSuppressed > 0) lines.push(`  - ${mlv.staleRefsSuppressed} stale ref(s) suppressed`);
+    if (mlv.duplicateRefsSuppressed > 0) lines.push(`  - ${mlv.duplicateRefsSuppressed} duplicate(s) suppressed`);
+    if (mlv.caveat) lines.push(`  Caveat: ${mlv.caveat}`);
+    lines.push("");
+  }
+
+  lines.push("Safe next action:");
+  lines.push(`  ${report.valueLedger.safeNextAction}`);
+
+  return lines.join("\n");
+}
+
+function runAiEfficiencyGate(cwd, options = {}) {
+  const { report } = buildAiWorkEfficiencyRouting(cwd, options);
+  const blockFindings = [];
+  const warnFindings = [];
+
+  if (report.limits.rawPromptDump) blockFindings.push({ severity: "block", reason: "GATE_BLOCK_RAW_PROMPT_DUMP" });
+  if (report.limits.rawCodeDump) blockFindings.push({ severity: "block", reason: "GATE_BLOCK_RAW_CODE_DUMP" });
+  if (report.limits.rawLogDump) blockFindings.push({ severity: "block", reason: "GATE_BLOCK_RAW_LOG_DUMP" });
+  if (report.limits.secretDump) blockFindings.push({ severity: "block", reason: "GATE_BLOCK_SECRET_EXPOSURE" });
+  if (report.limits.modelCalls) blockFindings.push({ severity: "block", reason: "GATE_BLOCK_MODEL_NETWORK_PROVIDER_CALL" });
+  if (report.limits.networkCalls) blockFindings.push({ severity: "block", reason: "GATE_BLOCK_MODEL_NETWORK_PROVIDER_CALL" });
+  if (report.limits.providerCalls) blockFindings.push({ severity: "block", reason: "GATE_BLOCK_MODEL_NETWORK_PROVIDER_CALL" });
+
+  const mlv = report.measuredLocalValue || {};
+  if (mlv.publicClaimAllowed && mlv.measurementType === "heuristic") {
+    blockFindings.push({ severity: "block", reason: "GATE_BLOCK_FAKE_SAVINGS" });
+  }
+
+  const guardContract = report.guardIntegrationContract || {};
+  const blockedGuards = (guardContract.guards || []).filter((g) => g.present && g.blocked);
+  if (blockedGuards.length > 0 && report.status === "pass") {
+    blockFindings.push({ severity: "block", reason: "GATE_BLOCK_FAKE_GREEN" });
+  }
+
+  for (const f of report.findings) {
+    if (f.severity === "block") {
+      blockFindings.push({ severity: "block", reason: f.reasonCode });
+    }
+  }
+
+  if (report.tokenEfficiency && report.tokenEfficiency.estimatedSavings &&
+      report.tokenEfficiency.estimatedSavings.type === "heuristic") {
+    warnFindings.push({ severity: "warn", reason: "GATE_WARN_HEURISTIC_SAVINGS" });
+  }
+
+  const contractOnlyGuards = (guardContract.guards || []).filter((g) => !g.present && g.contractReady);
+  if (contractOnlyGuards.length > 0) {
+    warnFindings.push({ severity: "warn", reason: "GATE_WARN_CONTRACT_ONLY_GUARD" });
+  }
+
+  if (report.routingPlan && report.routingPlan.routeConfidence === "low") {
+    warnFindings.push({ severity: "warn", reason: "GATE_WARN_LOW_ROUTE_CONFIDENCE" });
+  }
+
+  const allFindings = [...blockFindings, ...warnFindings];
+  const gateStatus = blockFindings.length > 0 ? "blocked" : warnFindings.length > 0 ? "warn" : "pass";
+
+  const reasonCodes = ["GATE_POLICY_MIXED_WARN_BLOCK"];
+  if (gateStatus === "pass") reasonCodes.push("GATE_PASS");
+  if (gateStatus === "warn") reasonCodes.push("GATE_WARN");
+  if (gateStatus === "blocked") reasonCodes.push("GATE_BLOCKED");
+
+  const safeNextAction = gateStatus === "blocked"
+    ? "Resolve block findings before proceeding."
+    : gateStatus === "warn"
+      ? "Review warn findings; may proceed with caution."
+      : "Gate passed. Continue with recommended route.";
+
+  return {
+    status: gateStatus,
+    blockFindings,
+    warnFindings,
+    findings: allFindings,
+    reasonCodes,
+    evidenceRefs: report.findings.flatMap((f) => f.evidenceRefs || []),
+    safeNextAction,
+    reportStatus: report.status,
+  };
+}
+
+module.exports = {
+  buildAiWorkEfficiencyRouting,
+  generateAiWorkEfficiencyRouting,
+  readLatestAiWorkEfficiencyRoutingReport,
+  buildAiWorkEfficiencyRoutingSurface,
+  formatAiWorkEfficiencyRoutingText,
+  runAiEfficiencyGate,
+  CONTRACT,
+  REPORT_JSON_REL,
+};