avorelo 0.1.0

package/scripts/lib/safe-path-engine.js

@@ -0,0 +1,705 @@
+"use strict";
+
+const crypto = require("crypto");
+const path = require("path");
+const { canExportReports } = require("./entitlements");
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+const { readLatestSkillRouteReceipt } = require("./skills-operating-layer");
+const { LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH } = require("./install-intake-risk");
+
+const SAFE_PATH_CONTRACT = "avorelo.safePath.v1";
+const SAFE_PATH_SCHEMA_VERSION = 1;
+const SAFE_PATH_DECISIONS = Object.freeze([
+  "allow_as_is",
+  "warn_with_boundary",
+  "approval_required",
+  "block",
+  "recommend_reduced_scope",
+  "ask_once",
+]);
+const LATEST_SAFE_PATH_RECEIPT_REL_PATH = ".claude/cco/security/safe-path/latest-receipt.json";
+const SAFE_PATH_HISTORY_DIR_REL_PATH = ".claude/cco/security/safe-path/history";
+const SAFE_PATH_EVENT_LOG_REL_PATH = ".claude/cco/events/safe-path.jsonl";
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function normalizePathList(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return list.map((item) => String(item || "").replace(/\\/g, "/").trim()).filter(Boolean);
+}
+
+function sanitizeText(value) {
+  return String(value || "")
+    .replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted-openai-key]")
+    .replace(/ghp_[A-Za-z0-9]{20,}/g, "[redacted-github-token]")
+    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted-aws-key]")
+    .replace(/(bearer\s+)[A-Za-z0-9._-]{8,}/ig, "$1[redacted]");
+}
+
+function summarizeScope(boundary) {
+  const parts = [];
+  if (boundary.accessMode) parts.push(boundary.accessMode);
+  if (boundary.pathScope?.length) parts.push(`paths=${boundary.pathScope.join(",")}`);
+  if (boundary.domainScope?.length) parts.push(`domains=${boundary.domainScope.join(",")}`);
+  if (boundary.toolScope?.length) parts.push(`tools=${boundary.toolScope.join(",")}`);
+  if (boundary.mcpScope?.length) parts.push(`mcp=${boundary.mcpScope.join(",")}`);
+  if (boundary.dryRun) parts.push("dry-run");
+  if (boundary.testOnly) parts.push("test-only");
+  if (boundary.allowNetwork === false) parts.push("no-network");
+  if (boundary.allowSecrets === false) parts.push("no-secrets");
+  return parts.join(" | ") || "narrow local scope";
+}
+
+function commandSuggestsDeploy(command) {
+  return /\b(deploy|publish|release|ship|vercel|netlify|railway|render|docker\s+push|npm\s+publish|gh\s+release)\b/i.test(String(command || ""));
+}
+
+function commandLooksBroad(command) {
+  return /\b(rg|grep|find|Get-ChildItem)\b.*(\*| -Recurse|\s+\.)/i.test(String(command || ""))
+    || /\bgit\s+add\s+\.\b/i.test(String(command || ""))
+    || /\bcp\b.*\s+\.\b/i.test(String(command || ""));
+}
+
+function pathIsBroad(candidate) {
+  const value = String(candidate || "").replace(/\\/g, "/").trim().toLowerCase();
+  if (!value) return true;
+  return [
+    ".",
+    "./",
+    "/",
+    "*",
+    "./*",
+    "src",
+    "app",
+    "packages",
+    "docs",
+    "tests",
+  ].includes(value) || value.endsWith("/*") || value.endsWith("/**");
+}
+
+function inferPrimaryPathScope(input = {}, governanceReceipt = null) {
+  const existing = normalizePathList(governanceReceipt?.scopeSummary?.pathScope || []);
+  if (existing.length) return existing;
+  return normalizePathList(input.targetPaths || input.target || []);
+}
+
+function inferDomainScope(input = {}, governanceReceipt = null) {
+  const existing = Array.isArray(governanceReceipt?.scopeSummary?.domainScope)
+    ? governanceReceipt.scopeSummary.domainScope.filter(Boolean)
+    : [];
+  if (existing.length) return existing;
+  if (!["browser_action", "network_request", "visual_qa_run"].includes(String(input.actionType || "").trim().toLowerCase())) {
+    return [];
+  }
+  if (!input.domain && !input.url && !input.target) return [];
+  try {
+    const target = input.url || input.target;
+    const url = /^https?:\/\//i.test(String(target || "")) ? String(target) : `https://${String(input.domain || target)}`;
+    return [new URL(url).hostname.toLowerCase()];
+  } catch {
+    return input.domain ? [String(input.domain).toLowerCase()] : [];
+  }
+}
+
+function defaultBoundary(input = {}, governanceReceipt = null) {
+  const scope = governanceReceipt?.scopeSummary || {};
+  const ttl = Number.isFinite(Number(governanceReceipt?.ttlSummary?.ttlSeconds))
+    ? Number(governanceReceipt.ttlSummary.ttlSeconds)
+    : null;
+  return {
+    accessMode: scope.accessMode || "unknown",
+    pathScope: inferPrimaryPathScope(input, governanceReceipt),
+    domainScope: inferDomainScope(input, governanceReceipt),
+    toolScope: Array.isArray(scope.toolScope) ? scope.toolScope.filter(Boolean) : [],
+    mcpScope: Array.isArray(scope.mcpScope) ? scope.mcpScope.filter(Boolean) : [],
+    allowNetwork: scope.allowNetwork === true,
+    allowSecrets: scope.allowSecrets === true,
+    dryRun: scope.dryRun === true,
+    testOnly: scope.testOnly === true,
+    ttlSeconds: ttl,
+  };
+}
+
+function buildSkillContextSafety(routeReceipt = null) {
+  if (!routeReceipt) {
+    return {
+      selectedSkillId: null,
+      sourceReviewStatus: "none",
+      contextWeight: null,
+      warnings: [],
+      deferredSourceUsed: false,
+    };
+  }
+  return {
+    selectedSkillId: routeReceipt.primarySkillId || null,
+    sourceReviewStatus: routeReceipt.deferredSources?.length ? "deferred_present" : (routeReceipt.primarySkillId ? "reviewed" : "none"),
+    contextWeight: routeReceipt.contextWeight || null,
+    warnings: Array.isArray(routeReceipt.skillContextWarnings) ? routeReceipt.skillContextWarnings : [],
+    deferredSourceUsed: false,
+  };
+}
+
+function buildIntakeContextSafety(intakeContext = null) {
+  if (!intakeContext) {
+    return {
+      latestReceiptPath: null,
+      matchedItemCount: 0,
+      reasonCodes: [],
+      nextAction: null,
+    };
+  }
+  return {
+    latestReceiptPath: intakeContext.receiptPath || LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH,
+    matchedItemCount: (intakeContext.matchedItems || []).length,
+    reasonCodes: (intakeContext.reasonCodes || []).slice(0, 8),
+    nextAction: intakeContext.safeNextAction || null,
+  };
+}
+
+function reductionSummary(fromValue, toValue, reasonCodes) {
+  return {
+    from: sanitizeText(fromValue || "broad requested scope"),
+    to: sanitizeText(toValue || "narrow reviewed scope"),
+    reasonCodes: unique(reasonCodes),
+  };
+}
+
+function saferAlternative(title, explanation, exampleCommand = null, exampleWorkflow = null) {
+  return {
+    title,
+    explanation: sanitizeText(explanation),
+    exampleCommand: exampleCommand ? sanitizeText(exampleCommand) : null,
+    exampleWorkflow: exampleWorkflow ? sanitizeText(exampleWorkflow) : null,
+  };
+}
+
+function buildApprovalBoundary(decision, governanceReceipt, boundary, reason) {
+  const required = decision.decision === "approval_required" || decision.decision === "block";
+  const askOnceAllowed = required && Number.isFinite(Number(boundary.ttlSeconds)) && Number(boundary.ttlSeconds) > 0 && decision.decision !== "block";
+  return {
+    required,
+    reason: sanitizeText(reason || governanceReceipt?.approvalBoundary?.summary || "Scoped review is required before the action proceeds."),
+    askOnceAllowed,
+    approvalText: required
+      ? `Approve only this narrowed scope: ${summarizeScope(boundary)}.`
+      : "No explicit approval boundary is required for the narrowed scope.",
+  };
+}
+
+function buildJitTemporaryScope(boundary, approvalBoundary) {
+  const ttlSeconds = Number.isFinite(Number(boundary.ttlSeconds)) ? Number(boundary.ttlSeconds) : null;
+  return {
+    supported: approvalBoundary.askOnceAllowed === true,
+    ttlSeconds,
+    scopeSummary: summarizeScope(boundary),
+  };
+}
+
+function buildCommonResult({
+  input,
+  decision,
+  governanceReceipt,
+  routeReceipt,
+  intakeContext,
+  safePathDecision,
+  boundary,
+  reduction,
+  alternative,
+  nextAction,
+}) {
+  const approvalBoundary = buildApprovalBoundary(decision, governanceReceipt, boundary, reduction?.reasonCodes?.[0] || governanceReceipt?.approvalBoundary?.summary);
+  const skillContextSafety = buildSkillContextSafety(routeReceipt);
+  const intakeContextSafety = buildIntakeContextSafety(intakeContext);
+  const evidenceRequirements = unique([
+    ...(routeReceipt?.evidenceRequirements || []),
+    ...(routeReceipt?.verificationRequirements || []),
+    ...(governanceReceipt?.reasonCodes || []).length ? [`Keep local evidence for: ${(governanceReceipt.reasonCodes || []).join(", ")}`] : [],
+    ...(intakeContextSafety.reasonCodes.length ? [`Review intake receipt before runtime trust: ${intakeContextSafety.reasonCodes.join(", ")}`] : []),
+  ]).map((entry) => sanitizeText(entry));
+  const safePathId = `safe-path-${sha256(JSON.stringify({
+    actionType: input.actionType,
+    target: input.target || input.command || input.url || "",
+    decision: decision.decision,
+    safePathDecision,
+    reasonCodes: decision.reasonCodes || [],
+  })).slice(0, 12)}`;
+
+  return {
+    schemaVersion: SAFE_PATH_SCHEMA_VERSION,
+    contract: SAFE_PATH_CONTRACT,
+    safePathId,
+    originalDecision: sanitizeText(decision.decision),
+    safePathDecision,
+    recommendedBoundary: boundary,
+    reductionSummary: reduction,
+    saferAlternative: alternative,
+    approvalBoundary,
+    jitTemporaryScope: buildJitTemporaryScope(boundary, approvalBoundary),
+    skillContextSafety,
+    intakeContextSafety,
+    evidenceRequirements,
+    nextAction: sanitizeText(nextAction),
+    redacted: true,
+    createdAt: decision.createdAt || nowIso(),
+  };
+}
+
+function ruleForSensitiveWrite(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  boundary.accessMode = "write";
+  boundary.allowSecrets = false;
+  boundary.pathScope = inferPrimaryPathScope(input, governanceReceipt).slice(0, 1);
+  boundary.dryRun = false;
+  boundary.testOnly = false;
+  const safePathDecision = decision.decision === "block" ? "block" : "approval_required";
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision,
+    boundary,
+    reduction: reductionSummary("write secret-bearing target directly", `write only ${boundary.pathScope[0] || "the reviewed target"} without secrets in evidence`, reasonCodes),
+    alternative: saferAlternative(
+      "Reduce the write and keep secrets out of the path",
+      "Edit a reviewed example, template, or minimal target path first. Keep secret values out of the change and out of receipts.",
+      null,
+      "Narrow the write to the exact file, keep no-secrets mode on, review the diff, then request approval once for that reduced scope."
+    ),
+    nextAction: "Narrow the write to the exact path, keep secrets out of evidence, review the diff, then request approval for the reduced scope.",
+  });
+}
+
+function ruleForDestructiveCommand(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  boundary.accessMode = "read_only";
+  boundary.allowNetwork = false;
+  boundary.allowSecrets = false;
+  boundary.dryRun = true;
+  boundary.testOnly = true;
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision: "block",
+    boundary,
+    reduction: reductionSummary(String(input.command || input.target || "destructive command"), "non-destructive inspection or dry-run", reasonCodes),
+    alternative: saferAlternative(
+      "Preserve the block and use a non-destructive check first",
+      "Destructive commands stay blocked. Use git status, diff, dry-run, or backup-oriented commands first.",
+      "git status --short",
+      "Inspect current state, confirm exact files, and choose a reversible workflow before any destructive step."
+    ),
+    nextAction: "Use a non-destructive inspection or dry-run command first. Keep the destructive action blocked.",
+  });
+}
+
+function ruleForBroadScope(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  boundary.pathScope = inferPrimaryPathScope(input, governanceReceipt).filter((entry) => !pathIsBroad(entry)).slice(0, 3);
+  if (!boundary.pathScope.length && normalizePathList(input.targetPaths || input.target || []).length) {
+    boundary.pathScope = normalizePathList(input.targetPaths || input.target || []).slice(0, 1);
+  }
+  boundary.accessMode = boundary.accessMode === "unknown" ? "read_only" : boundary.accessMode;
+  if (commandSuggestsDeploy(input.command || input.target || "")) {
+    boundary.dryRun = true;
+    boundary.testOnly = true;
+  }
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision: decision.decision === "approval_required" ? "approval_required" : "recommend_reduced_scope",
+    boundary,
+    reduction: reductionSummary("broad repo-wide scope", summarizeScope(boundary), reasonCodes),
+    alternative: saferAlternative(
+      "Narrow the action before running it broadly",
+      "Reduce the task to the smallest relevant path or file set, start read-only where possible, and keep test-only or dry-run mode on before wider changes.",
+      null,
+      "Start with a narrow path or test-only pass, then expand only if the evidence says it is needed."
+    ),
+    nextAction: boundary.dryRun || boundary.testOnly
+      ? "Narrow the scope first, then run a dry-run or test-only pass before wider changes."
+      : "Narrow the scope to the exact path or file set before proceeding.",
+  });
+}
+
+function ruleForExternalBoundary(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  boundary.domainScope = inferDomainScope(input, governanceReceipt).slice(0, 1);
+  boundary.allowNetwork = true;
+  boundary.allowSecrets = false;
+  boundary.testOnly = true;
+  const safePathDecision = decision.decision === "block"
+    ? "block"
+    : (decision.decision === "approval_required" ? "approval_required" : "warn_with_boundary");
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision,
+    boundary,
+    reduction: reductionSummary("broad external browser/network action", summarizeScope(boundary), reasonCodes),
+    alternative: saferAlternative(
+      "Use a domain-limited, no-session boundary",
+      "Prefer a localhost preview when possible. If the external domain is required, keep it domain-limited, no-cookies, no-session, and approval-gated.",
+      null,
+      "Use a local preview first. If that is not possible, request approval for one reviewed domain with no cookies or secrets."
+    ),
+    nextAction: "Prefer a local preview. Otherwise request approval for one reviewed domain with no cookies, sessions, or secrets.",
+  });
+}
+
+function ruleForToolOrMcp(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  boundary.toolScope = unique([input.toolName, ...(boundary.toolScope || [])]).filter(Boolean).slice(0, 1);
+  boundary.mcpScope = unique([input.mcpServer, ...(boundary.mcpScope || [])]).filter(Boolean).slice(0, 1);
+  boundary.allowNetwork = false;
+  boundary.allowSecrets = false;
+  const safePathDecision = decision.decision === "block"
+    ? "block"
+    : (decision.decision === "approval_required" ? "approval_required" : "warn_with_boundary");
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision,
+    boundary,
+    reduction: reductionSummary("unknown or unreviewed tool scope", summarizeScope(boundary), reasonCodes),
+    alternative: saferAlternative(
+      "Reduce access to one reviewed tool scope",
+      "Use one reviewed tool or MCP target only, prefer read-only behavior first, and require approval before wider or write-capable access.",
+      null,
+      "Confirm the reviewed tool or MCP target, keep the scope narrow, and request approval once only for that scope."
+    ),
+    nextAction: "Confirm one reviewed tool or MCP target, prefer read-only behavior first, then request approval for that reduced scope.",
+  });
+}
+
+function ruleForDeploy(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  boundary.accessMode = "execute";
+  boundary.allowNetwork = false;
+  boundary.allowSecrets = false;
+  boundary.dryRun = true;
+  boundary.testOnly = true;
+  const safePathDecision = decision.decision === "block"
+    ? "block"
+    : "approval_required";
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision,
+    boundary,
+    reduction: reductionSummary("real deploy or publish", "dry-run, preview, or test-only execution", reasonCodes),
+    alternative: saferAlternative(
+      "Start with dry-run, preview, or test-only",
+      "Deployment-like actions should begin with a dry-run, preview, or test-only step and require approval before any real publish or production-facing change.",
+      String(input.command || "").trim() ? `${String(input.command).trim()} --dry-run` : null,
+      "Run the narrowest preview or test-only workflow first, capture evidence, then request approval for any real publish step."
+    ),
+    nextAction: "Run a dry-run, preview, or test-only path first, collect evidence, then request approval before any real publish step.",
+  });
+}
+
+function ruleForSkillContext(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  if (routeReceipt?.contextWeight?.estimatedTokens >= 1200) {
+    boundary.testOnly = boundary.testOnly || /test|review|verify/i.test(String(input.userIntent || ""));
+  }
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision: decision.decision === "approval_required" ? "approval_required" : "warn_with_boundary",
+    boundary,
+    reduction: reductionSummary("broad skill context load", "compact summary plus required evidence only", reasonCodes),
+    alternative: saferAlternative(
+      "Load only the compact skill summary and required checks",
+      "When a selected skill is context-heavy or carries warnings, keep only compact excerpts, evidence requirements, and verification steps in the working context.",
+      null,
+      "Use the selected skill summary, then bring in only the required checks and evidence steps rather than the full skill body."
+    ),
+    nextAction: "Keep the selected skill to compact excerpts plus evidence and verification requirements only.",
+  });
+}
+
+function ruleForDefault(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  const safePathDecision = decision.decision === "allow"
+    ? "allow_as_is"
+    : decision.decision === "warn"
+      ? "warn_with_boundary"
+      : decision.decision === "approval_required"
+        ? "approval_required"
+        : "block";
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision,
+    boundary,
+    reduction: reductionSummary("requested action", summarizeScope(boundary), reasonCodes),
+    alternative: saferAlternative(
+      "Keep the action inside the smallest local scope",
+      "Use the smallest path, tool, domain, and evidence boundary that still completes the task.",
+      null,
+      "Start with the smallest local scope, keep evidence, and expand only if the task still cannot be completed."
+    ),
+    nextAction: routeReceipt?.nextAction || "Keep the action inside the smallest local scope and preserve evidence.",
+  });
+}
+
+function ruleForInstallIntake(input, decision, governanceReceipt, routeReceipt, reasonCodes) {
+  const boundary = defaultBoundary(input, governanceReceipt);
+  boundary.accessMode = "execute";
+  boundary.allowNetwork = false;
+  boundary.allowSecrets = false;
+  boundary.dryRun = true;
+  boundary.testOnly = true;
+  const safePathDecision = decision.decision === "block"
+    ? "block"
+    : decision.decision === "approval_required"
+      ? "approval_required"
+      : "recommend_reduced_scope";
+  return buildCommonResult({
+    input,
+    decision,
+    governanceReceipt,
+    routeReceipt,
+    intakeContext: input.intakeContext || null,
+    safePathDecision,
+    boundary,
+    reduction: reductionSummary("unreviewed install or intake path", "review source first, then use the smallest reviewed install/runtime scope", reasonCodes),
+    alternative: saferAlternative(
+      "Review intake before runtime trust",
+      "Do not trust the install or intake surface as normal runtime access yet. Review the source, pin the version, inspect scripts, and prefer read-only, no-secrets, or no-network alternatives first.",
+      null,
+      "Capture the intake receipt first, review the source and risk signals, then request approval only for the smallest reviewed scope."
+    ),
+    nextAction: input.intakeContext?.safeNextAction || "Review the intake source first, then use the smallest reviewed scope with no-secrets or no-network alternatives where possible.",
+  });
+}
+
+function chooseRule(input = {}, decision = {}, governanceReceipt = null, routeReceipt = null) {
+  const reasonCodes = unique([...(decision.reasonCodes || []), ...(governanceReceipt?.reasonCodes || [])]);
+  const reasonSet = new Set(reasonCodes);
+  const actionType = String(input.actionType || "").trim().toLowerCase();
+  const targetPaths = normalizePathList(input.targetPaths || input.target || []);
+  const hasBroadPath = targetPaths.some((candidate) => pathIsBroad(candidate)) || commandLooksBroad(input.command || input.target || "");
+  const hasSkillWarnings = Array.isArray(routeReceipt?.skillContextWarnings) && routeReceipt.skillContextWarnings.length > 0;
+  const contextHeavy = Number(routeReceipt?.contextWeight?.estimatedTokens || 0) >= 1200;
+  const hasInstallIntakeSignals = [
+    "UNKNOWN_PACKAGE_INSTALL",
+    "PACKAGE_NON_REGISTRY_SOURCE",
+    "PACKAGE_LOCAL_FILE_SOURCE",
+    "INSTALL_SCRIPT_PRESENT",
+    "NETWORK_SCRIPT_PRESENT",
+    "DESTRUCTIVE_SCRIPT_PRESENT",
+    "UNKNOWN_MCP_SOURCE",
+    "UNKNOWN_EXTENSION_SOURCE",
+    "DEFERRED_SKILL_SOURCE",
+  ].some((code) => reasonSet.has(code));
+
+  if (reasonSet.has("DESTRUCTIVE_COMMAND") || reasonSet.has("FORCE_PUSH_OR_HISTORY_REWRITE")) {
+    return { handler: ruleForDestructiveCommand, reasonCodes };
+  }
+  if (reasonSet.has("SENSITIVE_ENV_FILE") || reasonSet.has("SECRET_LIKE_TARGET") || reasonSet.has("AUTH_OR_BILLING_SCOPE") || reasonSet.has("DEPLOYMENT_CONFIG") || reasonSet.has("CI_CONFIG")) {
+    if (actionType === "file_write" || actionType === "config_change" || actionType === "secret_access") {
+      return { handler: ruleForSensitiveWrite, reasonCodes };
+    }
+  }
+  if (commandSuggestsDeploy(input.command || input.target || "")) {
+    return { handler: ruleForDeploy, reasonCodes: unique([...reasonCodes, "DEPLOYMENT_CONFIG"]) };
+  }
+  if (hasInstallIntakeSignals) {
+    return { handler: ruleForInstallIntake, reasonCodes };
+  }
+  if (reasonSet.has("BROWSER_EXTERNAL_DOMAIN") || reasonSet.has("EXTERNAL_NETWORK_REQUEST") || actionType === "browser_action" || actionType === "network_request") {
+    return { handler: ruleForExternalBoundary, reasonCodes };
+  }
+  if (reasonSet.has("UNKNOWN_MCP_TOOL") || reasonSet.has("WRITE_CAPABLE_TOOL") || actionType === "tool_call" || actionType === "mcp_tool_call") {
+    return { handler: ruleForToolOrMcp, reasonCodes };
+  }
+  if (hasBroadPath || (actionType === "file_write" && targetPaths.length > 1)) {
+    return { handler: ruleForBroadScope, reasonCodes: unique([...reasonCodes, "BROAD_SCOPE"]) };
+  }
+  if (hasSkillWarnings || contextHeavy) {
+    return { handler: ruleForSkillContext, reasonCodes: unique([...reasonCodes, ...(routeReceipt?.skillContextWarnings || []).map((warning) => warning.code)]) };
+  }
+  return { handler: ruleForDefault, reasonCodes };
+}
+
+function buildSafePathReceipt(input = {}, decision = {}, governanceReceipt = null, options = {}) {
+  const routeReceipt = options.skillRouteContext || readLatestSkillRouteReceipt(options.cwd || process.cwd());
+  const { handler, reasonCodes } = chooseRule(input, decision, governanceReceipt, routeReceipt);
+  return handler(input, decision, governanceReceipt, routeReceipt, reasonCodes);
+}
+
+function appendJsonl(cwd, relPath, payload) {
+  const fs = require("fs");
+  const absPath = path.join(cwd, relPath);
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.appendFileSync(absPath, `${JSON.stringify(payload)}\n`, "utf8");
+}
+
+function writeSafePathReceipt(cwd, receipt, options = {}) {
+  ensureCcoDirs(cwd);
+  safeWriteJson(cwd, LATEST_SAFE_PATH_RECEIPT_REL_PATH, receipt);
+  appendJsonl(cwd, SAFE_PATH_EVENT_LOG_REL_PATH, receipt);
+  if (canExportReports(options.plan || "free")) {
+    safeWriteJson(cwd, `${SAFE_PATH_HISTORY_DIR_REL_PATH}/${receipt.safePathId}.json`, receipt);
+  }
+  return LATEST_SAFE_PATH_RECEIPT_REL_PATH;
+}
+
+function recordSafePathLearningSignals(cwd, receipt) {
+  const events = [
+    {
+      eventName: "safe_path_evaluated",
+      category: "safe_path",
+      status: receipt.safePathDecision,
+      payload: {
+        safePathDecision: receipt.safePathDecision,
+        originalDecision: receipt.originalDecision,
+        reasonCodes: receipt.reductionSummary?.reasonCodes || [],
+      },
+    },
+  ];
+
+  if (receipt.safePathDecision === "recommend_reduced_scope" || receipt.safePathDecision === "warn_with_boundary") {
+    events.push({
+      eventName: "safe_path_recommended",
+      category: "safe_path",
+      status: receipt.safePathDecision,
+      payload: {
+        accessMode: receipt.recommendedBoundary?.accessMode || "unknown",
+        reasonCodes: receipt.reductionSummary?.reasonCodes || [],
+      },
+    });
+  }
+  if (receipt.approvalBoundary?.required) {
+    events.push({
+      eventName: "approval_boundary_used",
+      category: "safe_path",
+      status: "approval_required",
+      payload: {
+        askOnceAllowed: receipt.approvalBoundary.askOnceAllowed === true,
+      },
+    });
+  }
+  if (receipt.safePathDecision === "block") {
+    events.push({
+      eventName: "block_preserved",
+      category: "safe_path",
+      status: "blocked",
+      payload: {
+        reasonCodes: receipt.reductionSummary?.reasonCodes || [],
+      },
+    });
+  }
+  if (receipt.safePathDecision === "recommend_reduced_scope" || receipt.safePathDecision === "approval_required" || receipt.safePathDecision === "warn_with_boundary") {
+    events.push({
+      eventName: "access_reduced",
+      category: "safe_path",
+      status: "recommended",
+      payload: {
+        from: receipt.reductionSummary?.from || null,
+        to: receipt.reductionSummary?.to || null,
+      },
+    });
+  }
+  if (receipt.jitTemporaryScope?.supported) {
+    events.push({
+      eventName: "jit_temporary_scope_recommended",
+      category: "safe_path",
+      status: "recommended",
+      payload: {
+        ttlSeconds: receipt.jitTemporaryScope.ttlSeconds,
+      },
+    });
+  }
+  if (receipt.skillContextSafety?.warnings?.length) {
+    events.push({
+      eventName: "skill_context_safety_warning",
+      category: "safe_path",
+      status: "warn",
+      payload: {
+        warningCodes: receipt.skillContextSafety.warnings.map((warning) => warning.code).slice(0, 5),
+        contextWeight: receipt.skillContextSafety.contextWeight?.label || "low",
+      },
+    });
+  }
+
+  events.forEach((event) => {
+    try {
+      appendProductLearningEvent(cwd, event);
+    } catch {}
+  });
+}
+
+function readLatestSafePathReceipt(cwd) {
+  return safeReadJson(cwd, LATEST_SAFE_PATH_RECEIPT_REL_PATH, null);
+}
+
+function buildSafePathSurface(cwd) {
+  const latestReceipt = readLatestSafePathReceipt(cwd);
+  const status = latestReceipt ? "foundation" : "partial";
+  const topReasonCodes = unique(latestReceipt?.reductionSummary?.reasonCodes || []).slice(0, 5);
+  const lastDecision = latestReceipt?.safePathDecision || null;
+  const approvalsRequired = latestReceipt?.approvalBoundary?.required ? 1 : 0;
+  const blocksPreserved = latestReceipt?.safePathDecision === "block" ? 1 : 0;
+  const reductionsRecommended = ["recommend_reduced_scope", "warn_with_boundary", "approval_required"].includes(lastDecision) ? 1 : 0;
+  const skillContextWarnings = Number(latestReceipt?.skillContextSafety?.warnings?.length || 0);
+  return {
+    status,
+    showInStatus: true,
+    showInDashboard: true,
+    latestReceiptPath: latestReceipt ? LATEST_SAFE_PATH_RECEIPT_REL_PATH : null,
+    lastDecision,
+    topReasonCodes,
+    reductionsRecommended,
+    approvalsRequired,
+    blocksPreserved,
+    skillContextWarnings,
+    nextAction: latestReceipt?.nextAction || "Run `avorelo guard` on a risky action to generate the first Safe Path receipt.",
+    latestReceipt,
+    statusLine: `Safe Path: ${status.toUpperCase()} · last=${lastDecision || "none"} · reductions=${reductionsRecommended} · approvals=${approvalsRequired} · blocks-preserved=${blocksPreserved}`,
+  };
+}
+
+module.exports = {
+  SAFE_PATH_CONTRACT,
+  SAFE_PATH_SCHEMA_VERSION,
+  SAFE_PATH_DECISIONS,
+  LATEST_SAFE_PATH_RECEIPT_REL_PATH,
+  SAFE_PATH_EVENT_LOG_REL_PATH,
+  buildSafePathReceipt,
+  writeSafePathReceipt,
+  readLatestSafePathReceipt,
+  buildSafePathSurface,
+  recordSafePathLearningSignals,
+};