avorelo 0.1.0

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

@@ -0,0 +1,768 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const CONTRACT = "avorelo.smartWorkRouting.v1";
+const SCHEMA_VERSION = 1;
+
+const ROUTE_DIR_REL = ".claude/cco/orchestration/smart-work-routing";
+const LATEST_ROUTE_REL = `${ROUTE_DIR_REL}/latest-route.json`;
+const HANDOFF_DIR_REL = ".claude/cco/orchestration/worker-handoff";
+const LATEST_HANDOFF_REL = `${HANDOFF_DIR_REL}/latest-handoff.json`;
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const PATH_TYPES = Object.freeze([
+  "local_deterministic",
+  "local_or_cheap",
+  "strong_worker",
+  "handoff",
+  "a2a_delegate",
+  "acp_session",
+  "human_approval",
+]);
+
+const DECISION_TYPES = Object.freeze([
+  "auto_execute",
+  "auto_prepare",
+  "delegate",
+  "approval_required",
+  "blocked",
+  "debug_only",
+]);
+
+const MODES = Object.freeze(["automatic", "assisted", "manual_debug"]);
+
+const REASON_CODES = Object.freeze({
+  SAFE_LOCAL_PATH_AVAILABLE: "SAFE_LOCAL_PATH_AVAILABLE",
+  CHEAP_WORKER_CAPABLE: "CHEAP_WORKER_CAPABLE",
+  STRONG_WORKER_REQUIRED_FOR_CRITICAL_STAGE: "STRONG_WORKER_REQUIRED_FOR_CRITICAL_STAGE",
+  PROOF_REQUIRED_FOR_CODE_CHANGE: "PROOF_REQUIRED_FOR_CODE_CHANGE",
+  SAME_SURFACE_PREFERRED: "SAME_SURFACE_PREFERRED",
+  CROSS_VENDOR_ROUTING_BLOCKED_BY_DEFAULT: "CROSS_VENDOR_ROUTING_BLOCKED_BY_DEFAULT",
+  ACP_NOT_NEEDED_CLI_PATH_SUFFICIENT: "ACP_NOT_NEEDED_CLI_PATH_SUFFICIENT",
+  ACP_COMPATIBLE_EDITOR_DETECTED: "ACP_COMPATIBLE_EDITOR_DETECTED",
+  A2A_NOT_NEEDED_LOCAL_OR_HANDOFF_SUFFICIENT: "A2A_NOT_NEEDED_LOCAL_OR_HANDOFF_SUFFICIENT",
+  A2A_REMOTE_AGENT_DETECTED: "A2A_REMOTE_AGENT_DETECTED",
+  A2A_OPAQUE_AGENT_DELEGATION_REQUIRED: "A2A_OPAQUE_AGENT_DELEGATION_REQUIRED",
+  EXTERNAL_AGENT_REQUIRES_APPROVAL: "EXTERNAL_AGENT_REQUIRES_APPROVAL",
+  REMOTE_AGENT_NO_IDENTITY_PROOF: "REMOTE_AGENT_NO_IDENTITY_PROOF",
+  REMOTE_AGENT_NO_CAPABILITY_CARD: "REMOTE_AGENT_NO_CAPABILITY_CARD",
+  REMOTE_AGENT_NO_COMPLETION_RECEIPT: "REMOTE_AGENT_NO_COMPLETION_RECEIPT",
+  SECRETS_EXCLUDED_FROM_CONTEXT: "SECRETS_EXCLUDED_FROM_CONTEXT",
+  DEPLOY_REQUIRES_APPROVAL: "DEPLOY_REQUIRES_APPROVAL",
+  DESTRUCTIVE_ACTION_BLOCKED: "DESTRUCTIVE_ACTION_BLOCKED",
+});
+
+// ── Keyword matchers ──────────────────────────────────────────────────────────
+
+function includesAny(text, patterns) {
+  const t = String(text || "").toLowerCase();
+  return patterns.some((p) => t.includes(p.toLowerCase()));
+}
+
+const REMOTE_AGENT_KEYWORDS = [
+  "remote agent", "external agent", "opaque agent", "delegate to", "delegate implementation",
+  "third-party agent", "openai agent", "openrouter", "a2a", "agent-to-agent",
+];
+const ACP_KEYWORDS = [
+  "acp", "acp-compatible", "editor agent", "editor integration", "session bridge",
+  "cursor", "vscode agent", "jetbrains agent",
+];
+const DESTRUCTIVE_KEYWORDS = [
+  "delete .git", "rm -rf", "drop table", "truncate", "destroy", "wipe repo",
+  "clean repo", "reset hard", "force push", "obliterate",
+];
+const DEPLOY_KEYWORDS = [
+  "deploy to production", "deploy to prod", "release to production", "ship to prod",
+  "push to production", "production deploy", "release build", "publish release",
+];
+const SECURITY_KEYWORDS = [
+  "auth", "token", "secret", "password", "credential", "oauth", "jwt",
+  "api key", "encryption", "tls", "ssl", "certificate",
+];
+const DOCS_KEYWORDS = [
+  "update docs", "update documentation", "write docs", "fix readme", "doc change",
+  "add comment", "summarize", "explain", "describe", "changelog",
+];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function createRoutingId() {
+  return `route-${crypto.randomBytes(6).toString("hex")}`;
+}
+
+function createHandoffId() {
+  return `handoff-${crypto.randomBytes(6).toString("hex")}`;
+}
+
+function safeReadJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function getMode(cwd) {
+  try {
+    const { getSeamlessMode } = require("./seamless-outcome");
+    return getSeamlessMode({}) || "automatic";
+  } catch {
+    return "automatic";
+  }
+}
+
+// ── Task classification ───────────────────────────────────────────────────────
+
+function classifyTaskForRouting(taskText, orchestrationPlan) {
+  // Reuse orchestration classification if available
+  if (orchestrationPlan && orchestrationPlan.task) {
+    return orchestrationPlan.task;
+  }
+  try {
+    const { classifyWorkTask } = require("./work-aware-orchestration");
+    return classifyWorkTask(taskText);
+  } catch {
+    return {
+      summary: String(taskText || "").slice(0, 120),
+      taskType: "unknown",
+      riskLevel: "medium",
+      complexity: "medium",
+      contextPressure: "medium",
+      redacted: true,
+    };
+  }
+}
+
+// ── Decision logic (Phase 4) ──────────────────────────────────────────────────
+
+function decideExecutionPath(cwd, orchestrationPlan, executionPacket, options = {}) {
+  // Always classify from current taskText — stored plan task may be for a different task
+  const task = classifyTaskForRouting(options.taskText || "", null);
+
+  const { taskType, riskLevel } = task;
+  const taskText = options.taskText || task.summary || "";
+
+  const reasonCodes = [];
+  let decision = "auto_prepare";
+  let pathType = "local_or_cheap";
+  let selectedWorker = "local_or_cheap";
+  let selectedModelProfile = "local_summary";
+  let selectedTool = "avorelo_cli";
+  let sameSurfacePreferred = true;
+  let crossVendorAllowed = false;
+  let proofRequired = false;
+  let interrupt = false;
+  let interruptReason = null;
+  let safeNextAction = null;
+
+  // Remote/opaque agent delegation
+  if (includesAny(taskText, REMOTE_AGENT_KEYWORDS)) {
+    decision = "approval_required";
+    pathType = "a2a_delegate";
+    selectedWorker = "human_approval";
+    reasonCodes.push(REASON_CODES.A2A_REMOTE_AGENT_DETECTED);
+    reasonCodes.push(REASON_CODES.EXTERNAL_AGENT_REQUIRES_APPROVAL);
+    reasonCodes.push(REASON_CODES.REMOTE_AGENT_NO_IDENTITY_PROOF);
+    reasonCodes.push(REASON_CODES.REMOTE_AGENT_NO_CAPABILITY_CARD);
+    reasonCodes.push(REASON_CODES.REMOTE_AGENT_NO_COMPLETION_RECEIPT);
+    interrupt = true;
+    interruptReason = "Remote/opaque agent delegation requires explicit approval. No secrets or broad context will be sent.";
+    safeNextAction = "Review proposed delegation scope, confirm no secrets included, then approve explicitly.";
+    proofRequired = true;
+    return {
+      decision, pathType, selectedWorker, selectedModelProfile, selectedTool,
+      sameSurfacePreferred, crossVendorAllowed, reasonCodes,
+      interrupt, interruptReason, safeNextAction, proofRequired,
+    };
+  }
+
+  // Destructive command
+  if (includesAny(taskText, DESTRUCTIVE_KEYWORDS) || riskLevel === "high" && includesAny(taskText, ["delete", "rm -rf", "wipe", "destroy", "clean"])) {
+    decision = "blocked";
+    pathType = "human_approval";
+    selectedWorker = "human_approval";
+    reasonCodes.push(REASON_CODES.DESTRUCTIVE_ACTION_BLOCKED);
+    interrupt = true;
+    interruptReason = "Destructive command detected. Action blocked by default.";
+    safeNextAction = "Review the command carefully. Run a dry-run or preview first before proceeding.";
+    proofRequired = true;
+    return {
+      decision, pathType, selectedWorker, selectedModelProfile, selectedTool,
+      sameSurfacePreferred, crossVendorAllowed, reasonCodes,
+      interrupt, interruptReason, safeNextAction, proofRequired,
+    };
+  }
+
+  // Deploy/prod
+  if (includesAny(taskText, DEPLOY_KEYWORDS) || taskType === "deployment_release") {
+    decision = "approval_required";
+    pathType = "human_approval";
+    selectedWorker = "human_approval";
+    reasonCodes.push(REASON_CODES.DEPLOY_REQUIRES_APPROVAL);
+    interrupt = true;
+    interruptReason = "Deploy/production action requires explicit approval.";
+    safeNextAction = "Run tests, build, and preview first: avorelo execution-packet \"run build and tests\"";
+    proofRequired = true;
+    return {
+      decision, pathType, selectedWorker, selectedModelProfile, selectedTool,
+      sameSurfacePreferred, crossVendorAllowed, reasonCodes,
+      interrupt, interruptReason, safeNextAction, proofRequired,
+    };
+  }
+
+  // Security/auth/secrets
+  if (taskType === "security_sensitive" || riskLevel === "critical" || includesAny(taskText, SECURITY_KEYWORDS)) {
+    decision = "approval_required";
+    pathType = "strong_worker";
+    selectedWorker = "strong_model";
+    selectedModelProfile = "security_review";
+    reasonCodes.push(REASON_CODES.STRONG_WORKER_REQUIRED_FOR_CRITICAL_STAGE);
+    reasonCodes.push(REASON_CODES.SECRETS_EXCLUDED_FROM_CONTEXT);
+    reasonCodes.push(REASON_CODES.PROOF_REQUIRED_FOR_CODE_CHANGE);
+    interrupt = true;
+    interruptReason = "Security/auth/secrets task requires strong worker and approval. Secrets excluded from context.";
+    safeNextAction = "Review the security scope carefully. Use avorelo guard before any auth change.";
+    proofRequired = true;
+    crossVendorAllowed = false;
+    return {
+      decision, pathType, selectedWorker, selectedModelProfile, selectedTool,
+      sameSurfacePreferred, crossVendorAllowed, reasonCodes,
+      interrupt, interruptReason, safeNextAction, proofRequired,
+    };
+  }
+
+  // ACP-compatible editor request (metadata only)
+  if (includesAny(taskText, ACP_KEYWORDS)) {
+    decision = "auto_prepare";
+    pathType = "acp_session";
+    selectedWorker = "local_or_cheap";
+    reasonCodes.push(REASON_CODES.ACP_COMPATIBLE_EDITOR_DETECTED);
+    reasonCodes.push(REASON_CODES.ACP_NOT_NEEDED_CLI_PATH_SUFFICIENT);
+    safeNextAction = "ACP readiness metadata generated. Local CLI path is sufficient for v1.";
+    proofRequired = false;
+    return {
+      decision, pathType, selectedWorker, selectedModelProfile, selectedTool,
+      sameSurfacePreferred, crossVendorAllowed, reasonCodes,
+      interrupt, interruptReason, safeNextAction, proofRequired,
+    };
+  }
+
+  // Docs/summarization: auto_prepare or auto_execute, local/cheap
+  if (taskType === "documentation" || taskType === "summarization" ||
+      taskType === "repo_inspection" || taskType === "handoff" ||
+      includesAny(taskText, DOCS_KEYWORDS)) {
+    decision = riskLevel === "low" ? "auto_execute" : "auto_prepare";
+    pathType = "local_or_cheap";
+    selectedWorker = "local_or_cheap";
+    selectedModelProfile = "local_summary";
+    reasonCodes.push(REASON_CODES.SAFE_LOCAL_PATH_AVAILABLE);
+    reasonCodes.push(REASON_CODES.CHEAP_WORKER_CAPABLE);
+    reasonCodes.push(REASON_CODES.SAME_SURFACE_PREFERRED);
+    proofRequired = false;
+    return {
+      decision, pathType, selectedWorker, selectedModelProfile, selectedTool,
+      sameSurfacePreferred, crossVendorAllowed, reasonCodes,
+      interrupt, interruptReason, safeNextAction, proofRequired,
+    };
+  }
+
+  // Bug fix / implementation: auto_prepare, handoff/strong_worker for implementation
+  if (taskType === "bug_fix" || taskType === "implementation" || taskType === "refactor" || taskType === "test_or_verification") {
+    decision = "auto_prepare";
+    const hasStrongStage = orchestrationPlan &&
+      Array.isArray(orchestrationPlan.stages) &&
+      orchestrationPlan.stages.some((s) => s.workerSelection?.role === "strong_model");
+
+    if (hasStrongStage || riskLevel === "high") {
+      pathType = "strong_worker";
+      selectedWorker = "strong_model";
+      selectedModelProfile = "default_coding";
+      reasonCodes.push(REASON_CODES.STRONG_WORKER_REQUIRED_FOR_CRITICAL_STAGE);
+    } else {
+      pathType = "handoff";
+      selectedWorker = "local_or_cheap";
+      selectedModelProfile = "local_summary";
+      reasonCodes.push(REASON_CODES.CHEAP_WORKER_CAPABLE);
+    }
+    reasonCodes.push(REASON_CODES.SAME_SURFACE_PREFERRED);
+    reasonCodes.push(REASON_CODES.PROOF_REQUIRED_FOR_CODE_CHANGE);
+    reasonCodes.push(REASON_CODES.CROSS_VENDOR_ROUTING_BLOCKED_BY_DEFAULT);
+    proofRequired = true;
+    safeNextAction = "Worker handoff prepared. Review scope, then execute with target worker.";
+    return {
+      decision, pathType, selectedWorker, selectedModelProfile, selectedTool,
+      sameSurfacePreferred, crossVendorAllowed, reasonCodes,
+      interrupt, interruptReason, safeNextAction, proofRequired,
+    };
+  }
+
+  // Default: auto_prepare, local/cheap
+  reasonCodes.push(REASON_CODES.SAFE_LOCAL_PATH_AVAILABLE);
+  reasonCodes.push(REASON_CODES.SAME_SURFACE_PREFERRED);
+  reasonCodes.push(REASON_CODES.CROSS_VENDOR_ROUTING_BLOCKED_BY_DEFAULT);
+  return {
+    decision, pathType, selectedWorker, selectedModelProfile, selectedTool,
+    sameSurfacePreferred, crossVendorAllowed, reasonCodes,
+    interrupt, interruptReason, safeNextAction, proofRequired,
+  };
+}
+
+// ── Protocol readiness (Phase 6) ──────────────────────────────────────────────
+
+function buildProtocolReadiness(cwd, route, options = {}) {
+  const taskText = (route && route.task && route.task.summary) || "";
+  const pathType = route && route.executionPath && route.executionPath.pathType;
+
+  const acpNeeded = pathType === "acp_session" || includesAny(taskText, ACP_KEYWORDS);
+  const a2aNeeded = pathType === "a2a_delegate" || includesAny(taskText, REMOTE_AGENT_KEYWORDS);
+
+  return {
+    acp: {
+      neededNow: acpNeeded,
+      adapterReady: false,
+      useWhen: "An ACP-compatible editor or session bridge is explicitly detected or requested.",
+      reason: acpNeeded
+        ? "ACP-compatible editor or session bridge detected in task. Readiness metadata generated; no ACP implementation in v1."
+        : "Local CLI/handoff path sufficient for v1. ACP not needed.",
+      reasonCodes: acpNeeded
+        ? [REASON_CODES.ACP_COMPATIBLE_EDITOR_DETECTED]
+        : [REASON_CODES.ACP_NOT_NEEDED_CLI_PATH_SUFFICIENT],
+    },
+    a2a: {
+      neededNow: a2aNeeded,
+      adapterReady: false,
+      useWhen: "Task explicitly requires remote/opaque independent agent delegation with identity proof, capability card, and completion receipt.",
+      reason: a2aNeeded
+        ? "Remote agent delegation detected. Requires approval. No secrets or broad context will be sent. Identity proof, capability card, and completion receipt required."
+        : "Local or same-surface handoff path sufficient. A2A not needed.",
+      reasonCodes: a2aNeeded
+        ? [
+            REASON_CODES.A2A_REMOTE_AGENT_DETECTED,
+            REASON_CODES.EXTERNAL_AGENT_REQUIRES_APPROVAL,
+            REASON_CODES.REMOTE_AGENT_NO_IDENTITY_PROOF,
+            REASON_CODES.REMOTE_AGENT_NO_CAPABILITY_CARD,
+            REASON_CODES.REMOTE_AGENT_NO_COMPLETION_RECEIPT,
+          ]
+        : [REASON_CODES.A2A_NOT_NEEDED_LOCAL_OR_HANDOFF_SUFFICIENT],
+    },
+  };
+}
+
+// ── Worker handoff bundle (Phase 5) ──────────────────────────────────────────
+
+function buildWorkerHandoff(cwd, route, options = {}) {
+  const handoffId = createHandoffId();
+  const pathType = route.executionPath && route.executionPath.pathType;
+  const selectedWorker = (route.executionPath && route.executionPath.selectedWorker) || "local_or_cheap";
+  const targetSurface = selectedWorker === "strong_model" ? "claude_code" : "local_or_cheap";
+  const sameSurfacePreferred = (route.executionPath && route.executionPath.sameSurfacePreferred) !== false;
+
+  // Cross-vendor only with explicit approval
+  const crossVendorEnabled = options.crossVendorEnabled === true;
+  const needsApproval = ["a2a_delegate", "human_approval"].includes(pathType) ||
+    (route.executionPath && !route.executionPath.sameSurfacePreferred && !crossVendorEnabled);
+
+  const allowedScopeSummary = [
+    "file_read", "file_write_with_diff", "run_tests", "run_lint",
+    "run_build", "run_type_check", "git_status", "git_diff", "git_log",
+  ].join(", ");
+
+  const blockedScopeSummary = [
+    "secrets (.env, .key, credentials)", "auth/billing dirs", "deploy actions",
+    "remote agent execution", "broad context dumps", "raw code export",
+  ].join("; ");
+
+  return {
+    contract: "avorelo.workerHandoff.v1",
+    handoffId,
+    targetWorker: selectedWorker,
+    targetSurface,
+    sameSurfacePreferred,
+    crossVendorAllowed: crossVendorEnabled,
+    taskGoal: (route.task && route.task.summary) || "not_set",
+    executionPacketRef: ".claude/cco/orchestration/execution-packet/latest-packet.json",
+    contextPackRef: ".claude/cco/orchestration/context-optimizer/latest-pack.json",
+    allowedScopeSummary,
+    blockedScopeSummary,
+    proofRequired: (route.executionPath && route.executionPath.proofRequired) || false,
+    requiredBeforeWrite: ["read relevant files", "run avorelo guard", "confirm scope"],
+    requiredAfterWrite: route.executionPath && route.executionPath.proofRequired
+      ? ["run tests", "run build", "write proof artifact"]
+      : ["git diff review"],
+    safeNextAction: (route.executionPath && route.executionPath.safeNextAction) ||
+      "Review handoff scope, then execute with target worker.",
+    continuation: {
+      type: needsApproval ? "require_user_approval" : "continue_with_handoff",
+      approvalRequired: needsApproval,
+      approvalReason: needsApproval ? "Remote/cross-vendor delegation requires explicit approval." : null,
+    },
+    outputExpectations: {
+      diffRequired: (route.executionPath && route.executionPath.proofRequired) || false,
+      receiptRequired: true,
+      testPassRequired: (route.executionPath && route.executionPath.proofRequired) || false,
+    },
+    redacted: true,
+  };
+}
+
+// ── Value evidence ────────────────────────────────────────────────────────────
+
+function buildValueEvidence(route, orchestrationPlan) {
+  const evidence = [];
+  const stages = (orchestrationPlan && orchestrationPlan.stages) || [];
+  const localStages = stages.filter((s) =>
+    s.workerSelection && (s.workerSelection.costTier === "free_local" || s.workerSelection.role === "local_or_cheap")
+  ).length;
+
+  if (localStages > 0) {
+    evidence.push(`${localStages} local/cheap stage(s) from orchestration plan (evidence-backed)`);
+  }
+
+  const pathType = route.executionPath && route.executionPath.pathType;
+  if (pathType === "local_or_cheap" || pathType === "local_deterministic") {
+    evidence.push("Same-surface local path selected — no premium escalation needed");
+  }
+
+  const blockedCodes = (route.executionPath && route.executionPath.reasonCodes || []);
+  if (blockedCodes.includes(REASON_CODES.DESTRUCTIVE_ACTION_BLOCKED) ||
+      blockedCodes.includes(REASON_CODES.DEPLOY_REQUIRES_APPROVAL)) {
+    evidence.push("Unsafe action blocked — approval gate applied");
+  }
+  if (blockedCodes.includes(REASON_CODES.SECRETS_EXCLUDED_FROM_CONTEXT)) {
+    evidence.push("Secrets excluded from context — exposure prevented");
+  }
+
+  return {
+    evidenceItems: evidence,
+    localStagesUsed: localStages,
+    caveats: [
+      "Savings are estimates based on receipt data, not exact billing amounts.",
+      "No guaranteed savings claimed.",
+    ],
+    redacted: true,
+  };
+}
+
+// ── Main builder: buildSmartWorkRoute ─────────────────────────────────────────
+
+function buildSmartWorkRoute(cwd, taskText, options = {}) {
+  const routingId = createRoutingId();
+  const mode = getMode(cwd);
+
+  // Load orchestration plan if available
+  let orchestrationPlan = null;
+  try {
+    const planPath = path.join(cwd, ".claude/cco/orchestration/work-aware-orchestration/latest-plan.json");
+    const data = safeReadJson(planPath);
+    // Only use if it matches the current task (task summary overlap)
+    if (data && data.task) {
+      orchestrationPlan = data;
+    }
+  } catch { /* non-fatal */ }
+
+  // Load execution packet if available
+  let executionPacket = null;
+  try {
+    const packetPath = path.join(cwd, ".claude/cco/orchestration/execution-packet/latest-packet.json");
+    executionPacket = safeReadJson(packetPath);
+  } catch { /* non-fatal */ }
+
+  // Always classify from the current task text — do not reuse stored plan's task
+  const task = classifyTaskForRouting(taskText, null);
+
+  // Decide execution path
+  const pathDecision = decideExecutionPath(cwd, orchestrationPlan, executionPacket, {
+    taskText,
+    ...options,
+  });
+
+  const executionPath = {
+    pathType: pathDecision.pathType,
+    selectedWorker: pathDecision.selectedWorker,
+    selectedModelProfile: pathDecision.selectedModelProfile,
+    selectedTool: pathDecision.selectedTool,
+    sameSurfacePreferred: pathDecision.sameSurfacePreferred,
+    crossVendorAllowed: pathDecision.crossVendorAllowed,
+    reasonCodes: pathDecision.reasonCodes,
+    proofRequired: pathDecision.proofRequired,
+    interrupt: pathDecision.interrupt || false,
+    interruptReason: pathDecision.interruptReason || null,
+    safeNextAction: pathDecision.safeNextAction || null,
+  };
+
+  // Only reuse orchestration plan stages if the plan's task type matches current task
+  const planTaskType = orchestrationPlan && orchestrationPlan.task && orchestrationPlan.task.taskType;
+  const stagesFromPlan = planTaskType === task.taskType && Array.isArray(orchestrationPlan.stages)
+    ? orchestrationPlan.stages.map((s) => ({
+        stageId: s.stageId,
+        lifecycleStage: s.lifecycleStage,
+        riskLevel: s.riskLevel,
+        recommendedWorker: s.recommendedWorker,
+        proofExpected: s.proofExpected,
+        redacted: true,
+      }))
+    : null;
+
+  // Derive minimal stage list from routing decision when plan stages are unavailable/mismatched
+  const derivedStages = (() => {
+    const d = pathDecision.decision;
+    const pt = pathDecision.pathType;
+    if (d === "blocked" || d === "approval_required") return [];
+    if (pt === "local_or_cheap" || pt === "local_deterministic") return [
+      { stageId: "inspect", lifecycleStage: "inspect", riskLevel: "low", recommendedWorker: "local_or_cheap", proofExpected: false, redacted: true },
+      { stageId: "handoff", lifecycleStage: "handoff", riskLevel: "low", recommendedWorker: "local_or_cheap", proofExpected: false, redacted: true },
+    ];
+    return [
+      { stageId: "inspect", lifecycleStage: "inspect", riskLevel: "low", recommendedWorker: "local_or_cheap", proofExpected: false, redacted: true },
+      { stageId: "handoff", lifecycleStage: "handoff", riskLevel: "low", recommendedWorker: "local_or_cheap", proofExpected: false, redacted: true },
+    ];
+  })();
+
+  const stages = stagesFromPlan || derivedStages;
+
+  // Gather context info
+  const context = {
+    contextPackRef: executionPacket && executionPacket.contextPackRef || null,
+    secretsExcluded: true,
+    broadContextExcluded: true,
+    estimatedTokens: 0,
+    localOnly: true,
+    redacted: true,
+  };
+
+  // Safety summary
+  const safety = {
+    secretsExcluded: true,
+    broadRepoContextBlocked: true,
+    deployBlocked: pathDecision.decision === "approval_required" &&
+      pathDecision.reasonCodes.includes(REASON_CODES.DEPLOY_REQUIRES_APPROVAL),
+    destructiveBlocked: pathDecision.decision === "blocked",
+    remoteAgentApprovalRequired: pathDecision.reasonCodes.includes(REASON_CODES.EXTERNAL_AGENT_REQUIRES_APPROVAL),
+    crossVendorBlockedByDefault: !pathDecision.crossVendorAllowed,
+    interruptRequired: pathDecision.interrupt || false,
+    redacted: true,
+  };
+
+  const route = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    routingId,
+    task,
+    mode,
+    decision: pathDecision.decision,
+    executionPath,
+    stages,
+    context,
+    safety,
+    protocolReadiness: null, // populated below
+    workerHandoff: null,     // populated below
+    proof: {
+      receiptPath: LATEST_ROUTE_REL,
+      proofRequired: pathDecision.proofRequired,
+      redacted: true,
+    },
+    valueEvidence: null,     // populated below
+    receipts: {
+      routeReceiptPath: LATEST_ROUTE_REL,
+      handoffReceiptPath: LATEST_HANDOFF_REL,
+      orchestrationPlanRef: orchestrationPlan
+        ? ".claude/cco/orchestration/work-aware-orchestration/latest-plan.json"
+        : null,
+      executionPacketRef: executionPacket
+        ? ".claude/cco/orchestration/execution-packet/latest-packet.json"
+        : null,
+    },
+    redacted: true,
+  };
+
+  // Build protocol readiness
+  route.protocolReadiness = buildProtocolReadiness(cwd, route, options);
+
+  // Build value evidence
+  route.valueEvidence = buildValueEvidence(route, orchestrationPlan);
+
+  // Build worker handoff (all paths except debug_only)
+  if (pathDecision.decision !== "debug_only") {
+    route.workerHandoff = buildWorkerHandoff(cwd, route, options);
+  }
+
+  return route;
+}
+
+// ── Smart route surface ───────────────────────────────────────────────────────
+
+function buildSmartRouteSurface(cwd, options = {}) {
+  const routePath = path.join(cwd, LATEST_ROUTE_REL);
+  const handoffPath = path.join(cwd, LATEST_HANDOFF_REL);
+
+  return {
+    contract: CONTRACT,
+    status: fs.existsSync(routePath) ? "available" : "not_run",
+    latestRoutePath: LATEST_ROUTE_REL,
+    latestHandoffPath: fs.existsSync(handoffPath) ? LATEST_HANDOFF_REL : null,
+    nextAction: fs.existsSync(routePath)
+      ? "Smart route receipt available. Run avorelo smart-route \"<task>\" to route a new task."
+      : "Run avorelo smart-route \"<task>\" to build a smart work route.",
+    redacted: true,
+  };
+}
+
+// ── Receipt writer ────────────────────────────────────────────────────────────
+
+function writeSmartWorkRouteReceipt(cwd, route) {
+  const dir = path.join(cwd, ROUTE_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(cwd, LATEST_ROUTE_REL);
+  fs.writeFileSync(filePath, JSON.stringify(route, null, 2), "utf8");
+  return LATEST_ROUTE_REL;
+}
+
+function writeWorkerHandoffReceipt(cwd, handoff) {
+  const dir = path.join(cwd, HANDOFF_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(cwd, LATEST_HANDOFF_REL);
+  fs.writeFileSync(filePath, JSON.stringify(handoff, null, 2), "utf8");
+  return LATEST_HANDOFF_REL;
+}
+
+// ── Text formatter ────────────────────────────────────────────────────────────
+
+function formatSmartRouteText(route, options = {}) {
+  const debug = options.debug === true;
+  const lines = [];
+
+  const { decision, executionPath, task, safety, protocolReadiness } = route;
+
+  if (decision === "blocked") {
+    lines.push("ACTION BLOCKED");
+    lines.push(`Reason: ${executionPath.interruptReason || "Destructive or unsafe action detected."}`);
+    lines.push(`Safe next action: ${executionPath.safeNextAction || "Review and reduce scope."}`);
+    lines.push(`Proof needed: Run avorelo guard for verification steps.`);
+  } else if (decision === "approval_required") {
+    lines.push("ACTION REQUIRED");
+    lines.push(`Reason: ${executionPath.interruptReason || "High-risk action requires approval."}`);
+    lines.push(`Safe next action: ${executionPath.safeNextAction || "Review scope before proceeding."}`);
+    lines.push(`Proof needed: Run avorelo execution-packet for proof requirements.`);
+  } else {
+    lines.push("Avorelo routed this safely.");
+    const stageSummary = (route.stages || []).map((s) => s.stageId).filter(Boolean).join(" → ") || "prepare → handoff";
+    lines.push(`Path: ${stageSummary}`);
+    lines.push(`Context: compact pack, secrets excluded`);
+    lines.push(`Proof: ${executionPath.proofRequired ? "required" : "optional"}`);
+    if (route.workerHandoff) {
+      lines.push(`Next: worker handoff prepared`);
+    }
+  }
+
+  if (debug) {
+    lines.push("");
+    lines.push("--- Debug: Routing Detail ---");
+    lines.push(`Routing ID: ${route.routingId}`);
+    lines.push(`Mode: ${route.mode}`);
+    lines.push(`Decision: ${decision}`);
+    lines.push(`Path type: ${executionPath.pathType}`);
+    lines.push(`Worker: ${executionPath.selectedWorker}`);
+    lines.push(`Model profile: ${executionPath.selectedModelProfile}`);
+    lines.push(`Same surface preferred: ${executionPath.sameSurfacePreferred}`);
+    lines.push(`Cross-vendor: ${executionPath.crossVendorAllowed ? "allowed" : "blocked by default"}`);
+    lines.push(`Reason codes: ${(executionPath.reasonCodes || []).join(", ")}`);
+    lines.push("");
+    lines.push("--- Debug: Task Classification ---");
+    lines.push(`Task type: ${task.taskType}`);
+    lines.push(`Risk: ${task.riskLevel}`);
+    lines.push(`Complexity: ${task.complexity}`);
+    lines.push("");
+    lines.push("--- Debug: Safety ---");
+    lines.push(`Secrets excluded: ${safety.secretsExcluded}`);
+    lines.push(`Broad context blocked: ${safety.broadRepoContextBlocked}`);
+    lines.push(`Deploy blocked: ${safety.deployBlocked}`);
+    lines.push(`Destructive blocked: ${safety.destructiveBlocked}`);
+    lines.push(`Cross-vendor blocked by default: ${safety.crossVendorBlockedByDefault}`);
+    lines.push(`Interrupt required: ${safety.interruptRequired}`);
+    lines.push("");
+    lines.push("--- Debug: Protocol Readiness ---");
+    lines.push(`ACP needed now: ${protocolReadiness.acp.neededNow} (${protocolReadiness.acp.reason})`);
+    lines.push(`A2A needed now: ${protocolReadiness.a2a.neededNow} (${protocolReadiness.a2a.reason})`);
+    if (route.valueEvidence) {
+      lines.push("");
+      lines.push("--- Debug: Value Evidence ---");
+      for (const item of route.valueEvidence.evidenceItems || []) {
+        lines.push(`  - ${item}`);
+      }
+      for (const caveat of route.valueEvidence.caveats || []) {
+        lines.push(`  Caveat: ${caveat}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ── Ledger entry reader ───────────────────────────────────────────────────────
+
+function readSmartRouteLedgerEntry(cwd) {
+  const routePath = path.join(cwd, LATEST_ROUTE_REL);
+  if (!fs.existsSync(routePath)) return null;
+
+  const data = safeReadJson(routePath);
+  if (!data) return null;
+
+  const decision = data.decision || "unknown";
+  const pathType = (data.executionPath && data.executionPath.pathType) || "unknown";
+  const reasonCodes = (data.executionPath && data.executionPath.reasonCodes) || [];
+
+  const valueSignals = [];
+  const riskSignals = [];
+
+  if (pathType === "local_or_cheap" || pathType === "local_deterministic") {
+    valueSignals.push("local_or_cheap_path_selected");
+  }
+  if (reasonCodes.includes(REASON_CODES.DESTRUCTIVE_ACTION_BLOCKED)) {
+    riskSignals.push("destructive_action_blocked");
+  }
+  if (reasonCodes.includes(REASON_CODES.SECRETS_EXCLUDED_FROM_CONTEXT)) {
+    riskSignals.push("secrets_excluded");
+  }
+  if (reasonCodes.includes(REASON_CODES.DEPLOY_REQUIRES_APPROVAL)) {
+    riskSignals.push("deploy_approval_required");
+  }
+
+  const { normalizeLedgerEntry } = require("./work-ledger");
+  return normalizeLedgerEntry("smart_route", "smart_work_routing", data, {
+    status: decision === "blocked" ? "warn" : "pass",
+    summary: `Smart route: decision=${decision}, path=${pathType}.`,
+    evidencePath: LATEST_ROUTE_REL,
+    evidenceKind: "receipt",
+    valueSignals,
+    riskSignals,
+    reasonCodes: reasonCodes.slice(0, 5),
+  });
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  PATH_TYPES,
+  DECISION_TYPES,
+  MODES,
+  REASON_CODES,
+  LATEST_ROUTE_REL,
+  LATEST_HANDOFF_REL,
+  ROUTE_DIR_REL,
+  HANDOFF_DIR_REL,
+  buildSmartWorkRoute,
+  decideExecutionPath,
+  buildProtocolReadiness,
+  buildWorkerHandoff,
+  writeSmartWorkRouteReceipt,
+  writeWorkerHandoffReceipt,
+  buildSmartRouteSurface,
+  formatSmartRouteText,
+  readSmartRouteLedgerEntry,
+  classifyTaskForRouting,
+};