avorelo 0.1.0 → 0.3.0

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

@@ -1,768 +0,0 @@
-"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,
-};