avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/governed-action-exposure-primitives.js

@@ -0,0 +1,1514 @@
+"use strict";
+
+const crypto = require("crypto");
+const path = require("path");
+
+const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+const { readPackageJson } = require("./package-runtime");
+const { validateInstallClaims } = require("./public-install-claim-checker");
+const {
+  buildProductionConfidence,
+  loadProductionConfidence,
+  REPORT_JSON_REL: PRODUCTION_CONFIDENCE_REPORT_REL,
+} = require("./production-confidence");
+const {
+  buildGovernedWorkspaceHygieneReport,
+  readLatestGovernedWorkspaceHygieneReport,
+  LATEST_REPORT_REL: WORKSPACE_HYGIENE_REPORT_REL,
+} = require("./governed-workspace-hygiene");
+const {
+  buildLearningExperimentationReport,
+  LATEST_REPORT_REL: LEARNING_REPORT_REL,
+} = require("./learning-experimentation-foundation");
+const {
+  buildOutcomeEvidenceStack,
+  LEARNING_REPORT_REL: OUTCOME_LEARNING_REPORT_REL,
+} = require("./outcome-evidence-stack");
+const {
+  buildSkillsOperatingLayerReport,
+  readLatestSkillsOperatingLayerReport,
+  LATEST_V1_REPORT_REL: SKILLS_REPORT_REL,
+} = require("./skills-operating-layer");
+const {
+  LATEST_REPORT_REL: SCOPE_REPAIR_REPORT_REL,
+  readLatestScopeRepairReport,
+} = require("./scope-repair-before-approval");
+const {
+  classifyFilesystemWriteTarget,
+  isConfigFileTarget,
+  isDocsFileTarget,
+  isSensitiveWriteTarget,
+  isSourceFileTarget,
+  isTestFileTarget,
+} = require("./agent-security/file-write-rules");
+const { classifyPackageAction } = require("./agent-security/package-action-rules");
+const { classifyMcpAction } = require("./agent-security/mcp-action-rules");
+
+const CONTRACT = "avorelo.governedActionExposure.v1";
+const SCHEMA_VERSION = 1;
+const REPORT_DIR_REL = ".claude/cco/security/governed-action-exposure";
+const LATEST_REPORT_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const ACTION_TYPES = new Set([
+  "file_read",
+  "file_write",
+  "command_run",
+  "package_install",
+  "package_publish",
+  "mcp_tool_call",
+  "browser_action",
+  "network_request",
+  "secret_access",
+  "deploy_action",
+  "config_change",
+  "public_content_change",
+  "release_action",
+  "unknown",
+]);
+
+const EXPOSURE_TYPES = new Set([
+  "local_only",
+  "repo_internal",
+  "docs_public",
+  "website_public",
+  "npm_package_public",
+  "external_network",
+  "browser_external",
+  "production_deploy",
+  "credential_or_config",
+  "customer_data_adjacent",
+  "public_claim",
+  "unknown_exposure",
+]);
+
+const TOOL_TYPES = new Set([
+  "local_read",
+  "local_write",
+  "command",
+  "package_manager",
+  "mcp_read",
+  "mcp_write",
+  "browser",
+  "network",
+  "deploy",
+  "secret",
+  "unknown",
+]);
+
+const DECISIONS = new Set(["allow", "warn", "approval_required", "auto_limit", "block"]);
+const CONFIDENCE_LEVELS = new Set(["none", "low", "medium", "high"]);
+
+const DOGFOOD_COMMANDS = Object.freeze([
+  "node bin/avorelo support --json",
+  "node bin/avorelo support --text",
+  "node bin/avorelo outcome-evidence --json",
+  "node bin/avorelo outcome-evidence --text",
+  "node bin/avorelo workspace-hygiene --json",
+  "node bin/avorelo workspace-hygiene --text",
+  "node bin/avorelo learning --json",
+  "node bin/avorelo learning --text",
+  "node bin/avorelo production-confidence --json",
+  "node bin/avorelo production-confidence --text",
+  "node bin/avorelo skills --json",
+  "node bin/avorelo skills --text",
+  "node bin/avorelo boundary --json",
+  "node bin/avorelo boundary --text",
+  "node bin/avorelo status --text",
+  "node bin/avorelo open --json",
+  "node bin/avorelo package-audit --json",
+  "node bin/avorelo package-smoke --json",
+  "node bin/avorelo install-claims --json",
+  "node bin/avorelo public-distribution --json",
+]);
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort((left, right) => left.localeCompare(right))
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function hashId(prefix, payload) {
+  return `${prefix}-${sha256(stableStringify(payload)).slice(0, 12)}`;
+}
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function compactText(value, maxChars = 180) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (!text) return null;
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars - 3).trimEnd()}...`;
+}
+
+function sanitizeText(value, maxChars = 180) {
+  return compactText(
+    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]")
+      .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]"),
+    maxChars,
+  );
+}
+
+function normalizeEnum(value, allowed, fallback) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return allowed.has(normalized) ? normalized : fallback;
+}
+
+function toRelativeRedactedPath(cwd, value) {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  const normalized = raw.replace(/\\/g, "/");
+  if (/^https?:\/\//i.test(normalized)) {
+    try {
+      const url = new URL(normalized);
+      return url.hostname.toLowerCase();
+    } catch {
+      return "[redacted-url]";
+    }
+  }
+  const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+  const relative = path.relative(cwd, absolute).replace(/\\/g, "/");
+  if (!relative || relative === "") return ".";
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return "<outside-repo>";
+  return relative;
+}
+
+function normalizeList(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return list.map((item) => String(item || "").trim()).filter(Boolean);
+}
+
+function normalizeBrowserTargetType(value, normalizedScope = {}) {
+  const explicit = String(value || "").trim().toLowerCase();
+  if (["localhost", "local_file", "external_url", "production_url", "unknown"].includes(explicit)) {
+    return explicit;
+  }
+  const firstDomain = String((normalizedScope.domains || [])[0] || "").toLowerCase();
+  if (/^(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|::1)$/.test(firstDomain)) return "localhost";
+  if ((normalizedScope.paths || []).length > 0 && normalizedScope.visibility === "repo_internal") return "local_file";
+  if (normalizedScope.visibility === "production_deploy") return "production_url";
+  if ((normalizedScope.domains || []).length > 0) return "external_url";
+  return "unknown";
+}
+
+function normalizeBrowserActionCategory(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return normalized || "browser_action";
+}
+
+function buildRiskDimensions(flags = {}) {
+  return {
+    read: flags.read === true,
+    write: flags.write === true,
+    exec: flags.exec === true,
+    network: flags.network === true,
+    secret: flags.secret === true,
+    browser: flags.browser === true,
+    package: flags.package === true,
+    deploy: flags.deploy === true,
+    production: flags.production === true,
+    public_exposure: flags.public_exposure === true,
+    config: flags.config === true,
+    path: flags.path === true,
+    external_service: flags.external_service === true,
+    unknown_scope: flags.unknown_scope === true,
+  };
+}
+
+function countActiveRiskDimensions(dimensions) {
+  return Object.values(dimensions || {}).filter(Boolean).length;
+}
+
+function computeSideEffectLevel(dimensions) {
+  if (dimensions.secret || dimensions.deploy) return "critical";
+  if (dimensions.write || dimensions.exec || dimensions.network || dimensions.browser || dimensions.public_exposure || dimensions.production) {
+    return "high";
+  }
+  if (dimensions.package || dimensions.config || dimensions.path || dimensions.external_service || dimensions.unknown_scope) {
+    return "medium";
+  }
+  if (dimensions.read) return "low";
+  return "none";
+}
+
+function buildFallbackProductionReport() {
+  return {
+    status: "warn",
+    readiness: {
+      state: "not_enough_evidence",
+      confidence: "none",
+      safeNextAction: "Run `avorelo production-confidence --text` before using boundary output for ship decisions.",
+    },
+    summary: {
+      blocked: 0,
+      needsReview: 0,
+      notEnoughEvidence: 1,
+    },
+    categories: {
+      rollbackRecovery: {
+        id: "rollbackRecovery",
+        state: "warn",
+        safeNextAction: "Run `avorelo production-confidence --text` before deploy-adjacent decisions.",
+      },
+    },
+  };
+}
+
+function buildFallbackWorkspaceReport() {
+  return {
+    status: "warn",
+    summary: {
+      unknownSources: 1,
+      approvalRequired: 0,
+      blockedSources: 0,
+      receiptCount: 0,
+      safeNextAction: "Run `avorelo workspace-hygiene --json` before widening tool or source scope.",
+    },
+    inventory: {
+      capabilities: [],
+      tools: [],
+      skills: [],
+      mcpServers: [],
+      sources: [],
+    },
+    governance: {
+      receipts: [],
+    },
+  };
+}
+
+function buildFallbackOutcomeReport() {
+  return {
+    status: "warn",
+    summary: {
+      found: [],
+      fixed: [],
+      savedOrProved: [],
+      needsAttention: ["Capture outcome evidence before escalating risky public or deploy-adjacent decisions."],
+      safeNextAction: "Capture or import redacted outcome evidence first.",
+    },
+    tokenCost: {
+      measurementMode: "none",
+    },
+    evidenceContract: {
+      weakFindings: [],
+      rejectedFindings: [],
+      acceptedFindings: [],
+    },
+    proofLinks: [],
+  };
+}
+
+function buildFallbackLearningReport() {
+  return {
+    status: "warn",
+    summary: {
+      localEventsReviewed: 0,
+      experimentsReviewed: 0,
+      activeExperiments: 0,
+      weakSignalsFiltered: 0,
+      safeNextAction: "Collect local learning signals only after decisions are redacted and bounded.",
+    },
+    learning: {
+      findings: [],
+      capabilityImprovementCandidates: [],
+    },
+    outcomeReadiness: {
+      found: [],
+      fixed: [],
+      savedOrProved: [],
+      needsAttention: [],
+    },
+  };
+}
+
+function buildFallbackSkillsReport() {
+  return {
+    status: "warn",
+    summary: {
+      safeNextAction: "Run `avorelo skills --json` to review skill trust and verification gates.",
+    },
+    routing: {
+      selected: [],
+      deferred: [],
+      skipped: [],
+      deterministic: true,
+      llmDecisionMaker: false,
+    },
+    skills: [],
+    sources: [],
+  };
+}
+
+function buildFallbackPublicDistributionReport(cwd) {
+  const pkg = readPackageJson(cwd) || {};
+  return {
+    status: "warn",
+    distributionState: typeof pkg.avoreloDistributionState === "string" ? pkg.avoreloDistributionState : "private_local_only",
+    installClaims: {
+      blockedCount: 0,
+      status: "warn",
+    },
+    safeNextAction: "Run `avorelo public-distribution --json` for package/public boundary evidence.",
+  };
+}
+
+function buildLightweightPublicDistributionReport(cwd) {
+  const pkg = readPackageJson(cwd) || {};
+  let installClaims;
+  try {
+    installClaims = validateInstallClaims(cwd);
+  } catch {
+    installClaims = { status: "warn", blockedCount: 0 };
+  }
+  const distributionState = typeof pkg.avoreloDistributionState === "string"
+    ? pkg.avoreloDistributionState
+    : (pkg.private === false ? "ready_to_publish" : "private_local_only");
+
+  return {
+    status: distributionState === "published_verified" && (installClaims.blockedCount || 0) === 0 ? "pass" : "warn",
+    distributionState,
+    installClaims: {
+      status: installClaims.status || ((installClaims.blockedCount || 0) === 0 ? "pass" : "warn"),
+      blockedCount: installClaims.blockedCount || 0,
+    },
+    safeNextAction: distributionState === "published_verified"
+      ? "Public npm distribution is verified."
+      : "Review local package/public signals before widening public exposure.",
+  };
+}
+
+function buildIntegrationContext(cwd, options = {}) {
+  const overrides = options.integrationOverrides || {};
+  const allowBuildIfMissing = options.buildIfMissing === true;
+  let workspaceReport;
+  let outcomeReport;
+  let learningReport;
+  let productionReport;
+  let skillsReport;
+  let publicDistributionReport;
+
+  try {
+    workspaceReport = overrides.workspaceReport
+      || readLatestGovernedWorkspaceHygieneReport(cwd)
+      || (allowBuildIfMissing ? buildGovernedWorkspaceHygieneReport(cwd, { writeReport: false }).report : buildFallbackWorkspaceReport());
+  } catch {
+    workspaceReport = buildFallbackWorkspaceReport();
+  }
+
+  try {
+    outcomeReport = overrides.outcomeReport || (allowBuildIfMissing ? buildOutcomeEvidenceStack(cwd) : buildFallbackOutcomeReport());
+  } catch {
+    outcomeReport = buildFallbackOutcomeReport();
+  }
+
+  try {
+    learningReport = overrides.learningReport || (allowBuildIfMissing ? buildLearningExperimentationReport(cwd, { writeReport: false }) : buildFallbackLearningReport());
+  } catch {
+    learningReport = buildFallbackLearningReport();
+  }
+
+  try {
+    productionReport = overrides.productionReport || loadProductionConfidence(cwd) || (allowBuildIfMissing ? buildProductionConfidence(cwd) : buildFallbackProductionReport());
+  } catch {
+    productionReport = buildFallbackProductionReport();
+  }
+
+  try {
+    skillsReport = overrides.skillsReport
+      || readLatestSkillsOperatingLayerReport(cwd)
+      || (allowBuildIfMissing
+        ? buildSkillsOperatingLayerReport(cwd, {
+          task: "Governed action and exposure boundary review",
+          commandContext: "boundary",
+          writeReport: false,
+          emitEvents: false,
+        })
+        : buildFallbackSkillsReport());
+  } catch {
+    skillsReport = buildFallbackSkillsReport();
+  }
+
+  try {
+    publicDistributionReport = overrides.publicDistributionReport || buildLightweightPublicDistributionReport(cwd);
+  } catch {
+    publicDistributionReport = buildFallbackPublicDistributionReport(cwd);
+  }
+
+  return {
+    workspaceReport,
+    outcomeReport,
+    learningReport,
+    productionReport,
+    skillsReport,
+    publicDistributionReport,
+  };
+}
+
+function buildWorkspaceRisk(context) {
+  const summary = context.workspaceReport?.summary || {};
+  const riskyCapabilitySignals = (summary.blockedSources || 0) + (summary.approvalRequired || 0);
+  let level = "low";
+  if ((summary.blockedSources || 0) > 0 || riskyCapabilitySignals > 2) {
+    level = "high";
+  } else if ((summary.unknownSources || 0) > 0 || riskyCapabilitySignals > 0) {
+    level = "medium";
+  }
+  return {
+    level,
+    unknownSources: summary.unknownSources || 0,
+    approvalRequired: summary.approvalRequired || 0,
+    blockedSources: summary.blockedSources || 0,
+    riskyCapabilitySignals,
+  };
+}
+
+function hasWeakOutcomeEvidence(context) {
+  const report = context.outcomeReport || {};
+  const measurementMode = report.tokenCost?.measurementMode || "none";
+  return measurementMode === "none"
+    || measurementMode === "estimated"
+    || (report.evidenceContract?.weakFindings || []).length > 0
+    || (report.evidenceContract?.rejectedFindings || []).length > 0
+    || (report.summary?.needsAttention || []).length > 0;
+}
+
+function buildProductionConfidenceState(context) {
+  const report = context.productionReport || buildFallbackProductionReport();
+  return {
+    state: report.readiness?.state || "not_enough_evidence",
+    confidence: report.readiness?.confidence || "none",
+    nextAction: report.readiness?.safeNextAction || "Run `avorelo production-confidence --text` before shipping.",
+  };
+}
+
+function buildSkillBinding(context, candidate) {
+  const explicit = candidate.skillBinding;
+  if (explicit && typeof explicit === "object") {
+    return {
+      id: explicit.id || null,
+      sourceId: explicit.sourceId || null,
+      sourceTrust: explicit.sourceTrust || candidate.sourceTrust || "unknown",
+      verificationGates: Array.isArray(explicit.verificationGates) ? explicit.verificationGates.slice(0, 4) : [],
+      evidenceRequirements: Array.isArray(explicit.evidenceRequirements) ? explicit.evidenceRequirements.slice(0, 4) : [],
+      contextBudgetImpact: explicit.contextBudgetImpact || "unknown",
+      sideEffectLevel: explicit.sideEffectLevel || "unknown",
+    };
+  }
+
+  const selected = Array.isArray(context.skillsReport?.routing?.selected)
+    ? context.skillsReport.routing.selected[0]
+    : null;
+  if (!selected) return null;
+
+  const skillDetail = (context.skillsReport.skills || []).find((item) => item.id === selected.id) || null;
+  return {
+    id: selected.id || null,
+    sourceId: skillDetail?.sourceId || null,
+    sourceTrust: skillDetail?.trustLevel || "unknown",
+    verificationGates: Array.isArray(selected.verificationGates) ? selected.verificationGates.slice(0, 4) : [],
+    evidenceRequirements: Array.isArray(selected.evidenceRequirements) ? selected.evidenceRequirements.slice(0, 4) : [],
+    contextBudgetImpact: selected.contextBudgetImpact || skillDetail?.contextBudgetImpact || "unknown",
+    sideEffectLevel: selected.sideEffectLevel || skillDetail?.sideEffectLevel || "unknown",
+  };
+}
+
+function buildCapabilityBinding(context, candidate, skillBinding) {
+  const explicit = candidate.capabilityBinding;
+  if (explicit && typeof explicit === "object") {
+    return {
+      capabilityId: explicit.capabilityId || null,
+      capabilityLabel: explicit.capabilityLabel || explicit.capabilityId || null,
+      bindingDimension: explicit.bindingDimension || "unknown",
+      confidence: explicit.confidence || "medium",
+    };
+  }
+
+  if (!skillBinding?.id) return null;
+  const selected = Array.isArray(context.skillsReport?.routing?.selected)
+    ? context.skillsReport.routing.selected.find((item) => item.id === skillBinding.id)
+    : null;
+  const binding = Array.isArray(selected?.capabilityBindings) ? selected.capabilityBindings[0] : null;
+  if (!binding) return null;
+  return {
+    capabilityId: binding.capabilityId || null,
+    capabilityLabel: binding.capabilityLabel || binding.capabilityId || null,
+    bindingDimension: binding.bindingDimension || "unknown",
+    confidence: binding.confidence || "medium",
+  };
+}
+
+function buildEvidenceRefs(context, extra = []) {
+  return unique([
+    context.workspaceReport ? WORKSPACE_HYGIENE_REPORT_REL : null,
+    context.outcomeReport ? OUTCOME_LEARNING_REPORT_REL : null,
+    context.learningReport ? LEARNING_REPORT_REL : null,
+    context.productionReport ? PRODUCTION_CONFIDENCE_REPORT_REL : null,
+    context.skillsReport ? SKILLS_REPORT_REL : null,
+    "package.json",
+    ...(context.outcomeReport?.proofLinks || []).slice(0, 3),
+    ...(Array.isArray(extra) ? extra : []),
+  ]).slice(0, 8);
+}
+
+function normalizeScope(cwd, scope = {}) {
+  const normalized = {
+    paths: unique(normalizeList(scope.paths).map((item) => toRelativeRedactedPath(cwd, item))).filter(Boolean),
+    domains: unique(normalizeList(scope.domains).map((item) => sanitizeText(item, 120))).filter(Boolean),
+    toolNames: unique(normalizeList(scope.toolNames).map((item) => sanitizeText(item, 120))).filter(Boolean),
+    commandClass: sanitizeText(scope.commandClass, 80),
+    visibility: sanitizeText(scope.visibility, 80),
+    notes: sanitizeText(scope.notes, 140),
+    repoWide: scope.repoWide === true,
+    redacted: true,
+  };
+  return normalized;
+}
+
+function hasUnknownScope(normalizedScope) {
+  return normalizedScope.repoWide === true
+    || ((normalizedScope.paths || []).length === 0
+      && (normalizedScope.domains || []).length === 0
+      && (normalizedScope.toolNames || []).length === 0
+      && !normalizedScope.commandClass
+      && !normalizedScope.visibility);
+}
+
+function buildBaseDecisionRecord(cwd, candidate, context, type) {
+  const skillBinding = buildSkillBinding(context, candidate);
+  const capabilityBinding = buildCapabilityBinding(context, candidate, skillBinding);
+  const productionConfidenceState = buildProductionConfidenceState(context);
+  const workspaceRisk = buildWorkspaceRisk(context);
+  const requestedScope = normalizeScope(cwd, candidate.requestedScope || {});
+  const normalizedScope = normalizeScope(cwd, candidate.normalizedScope || candidate.requestedScope || {});
+  const sourceTrust = normalizeEnum(candidate.sourceTrust, new Set(["trusted", "known", "unknown", "untrusted"]), "unknown");
+  const id = candidate.id || hashId("boundary", {
+    type,
+    actionType: candidate.actionType,
+    exposureType: candidate.exposureType,
+    toolType: candidate.toolType,
+    intent: candidate.intent,
+    requestedScope,
+    sourceTrust,
+  });
+
+  return {
+    id,
+    type,
+    actionType: type === "action" ? normalizeEnum(candidate.actionType, ACTION_TYPES, "unknown") : null,
+    exposureType: type === "exposure" ? normalizeEnum(candidate.exposureType, EXPOSURE_TYPES, "unknown_exposure") : null,
+    toolType: type === "tool_scope" ? normalizeEnum(candidate.toolType, TOOL_TYPES, "unknown") : null,
+    browserTargetType: type === "action" && normalizeEnum(candidate.actionType, ACTION_TYPES, "unknown") === "browser_action"
+      ? normalizeBrowserTargetType(candidate.browserTargetType, normalizedScope)
+      : null,
+    browserActionCategory: type === "action" && normalizeEnum(candidate.actionType, ACTION_TYPES, "unknown") === "browser_action"
+      ? normalizeBrowserActionCategory(candidate.browserActionCategory)
+      : null,
+    intent: sanitizeText(candidate.intent || "", 180) || "No explicit intent provided.",
+    requestedScope,
+    normalizedScope,
+    minimalSafeScope: null,
+    sourceTrust,
+    capabilityBinding,
+    skillBinding,
+    productionConfidenceState,
+    workspaceRisk,
+    riskDimensions: buildRiskDimensions(),
+    sideEffectLevel: "none",
+    decision: "warn",
+    confidence: "low",
+    reasonCodes: [],
+    evidenceRefs: buildEvidenceRefs(context, candidate.evidenceRefs),
+    receiptRef: null,
+    safeNextAction: "Keep the action inside the smallest reviewed local scope.",
+    redacted: true,
+  };
+}
+
+function pushReason(reasons, condition, code) {
+  if (condition) reasons.add(code);
+}
+
+function updateDecisionIfStronger(record, nextDecision) {
+  const order = {
+    allow: 0,
+    warn: 1,
+    auto_limit: 2,
+    approval_required: 3,
+    block: 4,
+  };
+  if (order[nextDecision] > order[record.decision]) {
+    record.decision = nextDecision;
+  }
+}
+
+function applyCommonDecisionFloors(record, context) {
+  const reasons = new Set(record.reasonCodes || []);
+  const dimensions = record.riskDimensions || buildRiskDimensions();
+  const productionState = record.productionConfidenceState?.state || "not_enough_evidence";
+  const browserUnknownTarget = record.actionType === "browser_action" && record.browserTargetType === "unknown";
+
+  pushReason(reasons, record.sourceTrust === "unknown", "source_unknown");
+  pushReason(reasons, record.sourceTrust === "untrusted", "source_untrusted");
+  pushReason(reasons, hasUnknownScope(record.normalizedScope), "unknown_scope");
+  pushReason(reasons, record.ownerMissing === true, "missing_owner");
+  pushReason(reasons, record.minimalSafeScope, "safe_scope_available");
+  pushReason(reasons, !record.minimalSafeScope, "safe_scope_not_available");
+
+  if (dimensions.exec) reasons.add("requires_exec");
+  if (dimensions.network) reasons.add("requires_network");
+  if (dimensions.browser) reasons.add("requires_browser");
+  if (dimensions.secret) reasons.add("requires_secret_access");
+
+  if (record.type === "action" && record.actionType === "package_install") reasons.add("package_install_requested");
+  if (record.type === "action" && record.actionType === "package_publish") reasons.add("package_publish_requested");
+  if (record.type === "action" && record.actionType === "deploy_action") reasons.add("deploy_requested");
+  if (record.type === "exposure" && ["docs_public", "website_public", "npm_package_public", "public_claim"].includes(record.exposureType)) {
+    reasons.add("public_exposure_requested");
+  }
+
+  if (record.type === "action" && record.actionType === "file_write") {
+    if ((record.normalizedScope.paths || []).some((item) => item === "<outside-repo>")) reasons.add("writes_outside_repo");
+    if ((record.normalizedScope.paths || []).some((item) => isSourceFileTarget(item))) reasons.add("writes_source");
+    if ((record.normalizedScope.paths || []).some((item) => isConfigFileTarget(item))) reasons.add("writes_config");
+  }
+
+  if (record.type === "tool_scope" && record.toolType === "unknown" && context.workspaceReport?.summary?.unknownSources > 0) {
+    reasons.add("workspace_hygiene_unknown_tool");
+  }
+  if ((record.workspaceRisk?.riskyCapabilitySignals || 0) > 0 && (dimensions.write || dimensions.exec || dimensions.network || dimensions.browser)) {
+    reasons.add("workspace_hygiene_risky_capability");
+  }
+
+  if (record.skillBinding?.sourceTrust === "unknown" || record.skillBinding?.sourceTrust === "untrusted") {
+    reasons.add("skill_source_unknown");
+  }
+  if ((record.skillBinding?.verificationGates || []).length > 0 && countActiveRiskDimensions(dimensions) >= 2) {
+    reasons.add("skill_requires_verification_gate");
+  }
+
+  if (record.type !== "action" || record.actionType !== "file_read") {
+    if ((context.outcomeReport?.proofLinks || []).length === 0) {
+      reasons.add("outcome_evidence_missing");
+    } else if (hasWeakOutcomeEvidence(context)) {
+      reasons.add("outcome_evidence_weak");
+    }
+  }
+
+  if (productionState === "blocked" && (dimensions.production || dimensions.deploy || dimensions.public_exposure)) {
+    reasons.add("production_confidence_blocked");
+  } else if (productionState === "needs_review" && (dimensions.production || dimensions.deploy || dimensions.public_exposure)) {
+    reasons.add("production_confidence_needs_review");
+  }
+
+  const distributionState = context.publicDistributionReport?.distributionState || "private_local_only";
+  const blockedCount = context.publicDistributionReport?.installClaims?.blockedCount || 0;
+  if (record.type === "exposure" && record.exposureType === "npm_package_public" && distributionState !== "published_verified") {
+    reasons.add("public_distribution_not_verified");
+  }
+  if ((record.type === "exposure" && record.exposureType === "npm_package_public") || record.actionType === "package_publish") {
+    if (blockedCount > 0) reasons.add("install_claims_blocked");
+  }
+
+  if (record.sourceTrust === "untrusted" && (dimensions.write || dimensions.exec || dimensions.network || dimensions.browser || dimensions.public_exposure || dimensions.deploy)) {
+    updateDecisionIfStronger(record, "block");
+  } else if (
+    record.sourceTrust === "unknown"
+    && (dimensions.write || dimensions.exec || dimensions.network || dimensions.browser || dimensions.public_exposure || dimensions.deploy)
+    && !browserUnknownTarget
+  ) {
+    updateDecisionIfStronger(record, "approval_required");
+  }
+
+  if (hasUnknownScope(record.normalizedScope) && record.decision === "allow") {
+    updateDecisionIfStronger(record, countActiveRiskDimensions(dimensions) > 1 ? "approval_required" : "warn");
+  }
+  if (record.ownerMissing === true && record.decision === "allow") {
+    updateDecisionIfStronger(record, "warn");
+  }
+  if (productionState === "blocked" && (dimensions.production || dimensions.deploy || dimensions.public_exposure)) {
+    updateDecisionIfStronger(record, "block");
+  } else if (productionState === "needs_review" && (dimensions.production || dimensions.deploy || dimensions.public_exposure)) {
+    updateDecisionIfStronger(record, "approval_required");
+  }
+
+  record.reasonCodes = Array.from(reasons);
+  record.sideEffectLevel = computeSideEffectLevel(dimensions);
+  record.confidence = inferConfidence(record, context);
+  record.safeNextAction = buildSafeNextAction(record, context);
+  return record;
+}
+
+function inferConfidence(record, context) {
+  if (record.decision === "block" && record.reasonCodes.length > 0) return "high";
+  if (record.sourceTrust === "trusted" && record.decision === "allow" && !hasUnknownScope(record.normalizedScope)) return "high";
+  if ((record.sourceTrust === "unknown" && !(record.actionType === "browser_action" && record.browserTargetType === "unknown")) || hasUnknownScope(record.normalizedScope)) return "low";
+  if (hasWeakOutcomeEvidence(context) && (record.riskDimensions.public_exposure || record.riskDimensions.deploy || record.riskDimensions.production)) {
+    return "low";
+  }
+  if (record.decision === "allow" || record.decision === "warn") return "medium";
+  return "medium";
+}
+
+function buildSafeNextAction(record, context) {
+  if (record.decision === "block") {
+    if (record.minimalSafeScope) return `Do not proceed as requested. Use the reduced scope instead: ${record.minimalSafeScope.notes || "review the bounded alternative first."}`;
+    return "Do not proceed with the blocked request. Keep the work local, redacted, and non-executing.";
+  }
+  if (record.decision === "approval_required") {
+    if (record.minimalSafeScope) return `Approve only the reduced scope: ${record.minimalSafeScope.notes || "use the bounded alternative first."}`;
+    return "Request explicit approval before moving beyond the current bounded local review.";
+  }
+  if (record.decision === "auto_limit") {
+    return record.minimalSafeScope?.notes || "Use the deterministic reduced scope instead of the broader request.";
+  }
+  if (record.decision === "warn") {
+    return record.minimalSafeScope?.notes
+      || context.productionReport?.readiness?.safeNextAction
+      || context.workspaceReport?.summary?.safeNextAction
+      || "Keep the work reviewed, bounded, and redacted before expanding scope.";
+  }
+  return "Proceed inside the reviewed local scope and keep outputs redacted.";
+}
+
+function evaluateActionCandidate(cwd, candidate, context) {
+  const record = buildBaseDecisionRecord(cwd, candidate, context, "action");
+  const reasons = new Set(record.reasonCodes);
+  const scopePaths = record.normalizedScope.paths || [];
+  const firstPath = scopePaths[0] || "";
+  const writeProfile = scopePaths.length > 0 ? classifyFilesystemWriteTarget(cwd, firstPath === "<outside-repo>" ? "../outside" : firstPath) : null;
+  const packageProfile = candidate.actionType === "package_install" || candidate.actionType === "package_publish"
+    ? classifyPackageAction({
+      actionType: candidate.actionType === "package_install" ? "package.install" : "package.run",
+      command: candidate.command || (candidate.actionType === "package_install" ? "npm install example-package" : "npm publish --access public"),
+      target: scopePaths[0] || "",
+      packageManager: candidate.packageManager || "npm",
+      packageName: candidate.packageName || "example-package",
+    })
+    : null;
+  const mcpProfile = candidate.actionType === "mcp_tool_call"
+    ? classifyMcpAction({
+      actionType: candidate.mcpActionType || "mcp.write",
+      mcpServer: candidate.mcpServer || "unknown",
+      toolName: candidate.toolName || "unknown",
+      target: candidate.target || `${candidate.mcpServer || "unknown"}:${candidate.toolName || "unknown"}`,
+      resource: candidate.resource || {},
+      args: candidate.args || {},
+    })
+    : null;
+  const browserTargetType = record.actionType === "browser_action"
+    ? normalizeBrowserTargetType(candidate.browserTargetType, record.normalizedScope)
+    : "unknown";
+  const browserActionCategory = record.actionType === "browser_action"
+    ? normalizeBrowserActionCategory(candidate.browserActionCategory)
+    : null;
+  const localBrowserTarget = browserTargetType === "localhost" || browserTargetType === "local_file";
+
+  let dimensions = buildRiskDimensions({
+    read: record.actionType === "file_read",
+    write: ["file_write", "config_change", "public_content_change"].includes(record.actionType),
+    exec: ["command_run", "package_install", "package_publish", "mcp_tool_call", "release_action"].includes(record.actionType),
+    network: record.actionType === "network_request"
+      || packageProfile?.installFromUrlOrPath === true
+      || (record.actionType === "browser_action" && !localBrowserTarget && browserTargetType !== "unknown"),
+    secret: record.actionType === "secret_access" || isSensitiveWriteTarget(firstPath),
+    browser: record.actionType === "browser_action",
+    package: ["package_install", "package_publish"].includes(record.actionType),
+    deploy: ["deploy_action", "release_action"].includes(record.actionType) || /\bdeploy\b/i.test(String(candidate.command || "")),
+    production: ["deploy_action", "release_action"].includes(record.actionType) || browserTargetType === "production_url",
+    public_exposure: record.actionType === "public_content_change",
+    config: record.actionType === "config_change" || isConfigFileTarget(firstPath),
+    path: scopePaths.length > 0,
+    external_service: record.actionType === "network_request" || (record.actionType === "browser_action" && !localBrowserTarget),
+    unknown_scope: hasUnknownScope(record.normalizedScope),
+  });
+
+  if (record.actionType === "file_read" && record.sourceTrust === "trusted" && !hasUnknownScope(record.normalizedScope)) {
+    record.decision = "allow";
+    reasons.add("trusted_read_only");
+  } else if (record.actionType === "file_write") {
+    if (firstPath === "<outside-repo>") {
+      record.decision = "block";
+    } else if (isSensitiveWriteTarget(firstPath) || /\.npmrc$/i.test(firstPath) || /\.env(?:\..+)?$/i.test(firstPath)) {
+      record.decision = "block";
+    } else if (isSourceFileTarget(firstPath) || isConfigFileTarget(firstPath)) {
+      record.decision = "approval_required";
+    } else if (isDocsFileTarget(firstPath) || isTestFileTarget(firstPath)) {
+      record.decision = "warn";
+    } else {
+      record.decision = "approval_required";
+    }
+  } else if (record.actionType === "command_run") {
+    record.decision = /\b(rm\s+-rf|del\s+\/[qs]|remove-item\b|git\s+reset\b|git\s+push\b.*--force)\b/i.test(String(candidate.command || ""))
+      ? "block"
+      : "approval_required";
+  } else if (record.actionType === "package_install") {
+    record.decision = packageProfile?.recommendedDecision === "deny" ? "block" : "approval_required";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      paths: ["package.json", "package-lock.json"],
+      notes: "Review package metadata and lockfile impact locally before any install request is approved.",
+    });
+  } else if (record.actionType === "package_publish") {
+    record.decision = "block";
+  } else if (record.actionType === "mcp_tool_call") {
+    record.decision = mcpProfile?.readOnly === true && record.sourceTrust === "trusted"
+      ? "warn"
+      : (mcpProfile?.recommendedDecision === "deny" ? "block" : "approval_required");
+    if (mcpProfile?.readOnly !== true) {
+      record.minimalSafeScope = normalizeScope(cwd, {
+        toolNames: [candidate.toolName || "mcp-read-only-preview"],
+        notes: "Reduce the MCP request to read-only metadata inspection first.",
+      });
+    }
+  } else if (record.actionType === "browser_action") {
+    if (browserActionCategory === "production_browse" || browserTargetType === "production_url") {
+      record.decision = "block";
+      record.minimalSafeScope = normalizeScope(cwd, {
+        visibility: "local_plan_only",
+        notes: "Production browsing stays blocked. Keep proof scope local-only in v1.",
+      });
+    } else if (browserActionCategory === "form_submit") {
+      record.decision = "block";
+      record.minimalSafeScope = normalizeScope(cwd, {
+        visibility: "local_plan_only",
+        notes: "Do not submit forms. Capture bounded local proof without form actions.",
+      });
+    } else if (browserActionCategory === "credential_flow") {
+      record.decision = localBrowserTarget ? "approval_required" : "block";
+      record.minimalSafeScope = normalizeScope(cwd, {
+        visibility: "local_plan_only",
+        notes: "Do not use credentials by default. Keep browser proof to anonymous local evidence.",
+      });
+    } else if (browserActionCategory === "external_browse_request" || browserTargetType === "external_url") {
+      record.decision = "approval_required";
+      record.minimalSafeScope = normalizeScope(cwd, {
+        domains: record.normalizedScope.domains,
+        visibility: "local_plan_only",
+        notes: "Keep browser work at plan-only scope until a reviewed external target is explicitly approved.",
+      });
+    } else if (browserActionCategory === "screenshot_reference") {
+      if (localBrowserTarget) {
+        record.decision = "allow";
+        reasons.add("trusted_read_only");
+      } else if (browserTargetType === "unknown") {
+        record.decision = "warn";
+      } else {
+        record.decision = "approval_required";
+        record.minimalSafeScope = normalizeScope(cwd, {
+          visibility: "local_plan_only",
+          notes: "Keep screenshot and visual-hint scope local and redacted only.",
+        });
+      }
+    } else if (browserActionCategory === "visual_hint") {
+      if (localBrowserTarget || browserTargetType === "unknown") {
+        record.decision = "warn";
+      } else {
+        record.decision = "approval_required";
+        record.minimalSafeScope = normalizeScope(cwd, {
+          visibility: "local_plan_only",
+          notes: "Keep screenshot and visual-hint scope local and redacted only.",
+        });
+      }
+    } else if (["page_reachability_check", "dom_presence_check", "console_summary_check", "network_summary_check"].includes(browserActionCategory)) {
+      if (localBrowserTarget) {
+        record.decision = "allow";
+        reasons.add("trusted_read_only");
+      } else if (browserTargetType === "unknown") {
+        record.decision = "warn";
+      } else {
+        record.decision = "approval_required";
+        record.minimalSafeScope = normalizeScope(cwd, {
+          domains: record.normalizedScope.domains,
+          visibility: "local_plan_only",
+          notes: "Keep browser proof read-only and local-first until a reviewed external target is explicitly approved.",
+        });
+      }
+    } else {
+      record.decision = localBrowserTarget ? "warn" : "approval_required";
+      if (!localBrowserTarget) {
+        record.minimalSafeScope = normalizeScope(cwd, {
+          domains: record.normalizedScope.domains,
+          visibility: "local_plan_only",
+          notes: "Keep browser work at plan-only scope until the target is explicitly reviewed.",
+        });
+      }
+    }
+  } else if (record.actionType === "network_request") {
+    record.decision = "approval_required";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      visibility: "no_network_summary_only",
+      notes: "Prepare a no-network local summary first instead of making the request.",
+    });
+  } else if (record.actionType === "secret_access") {
+    record.decision = "block";
+  } else if (record.actionType === "deploy_action") {
+    record.decision = record.productionConfidenceState.state === "blocked" ? "block" : "approval_required";
+  } else if (record.actionType === "config_change") {
+    record.decision = isSensitiveWriteTarget(firstPath) || /\.npmrc$/i.test(firstPath) ? "block" : "approval_required";
+  } else if (record.actionType === "public_content_change") {
+    record.decision = "auto_limit";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      paths: ["docs/internal-draft.md"],
+      visibility: "repo_internal",
+      notes: "Keep public-facing copy changes as an internal draft until claims and proof are reviewed.",
+    });
+  } else if (record.actionType === "release_action") {
+    record.decision = "approval_required";
+  } else {
+    record.decision = hasUnknownScope(record.normalizedScope) ? "approval_required" : "warn";
+  }
+
+  if (writeProfile?.sourceFile) reasons.add("writes_source");
+  if (writeProfile?.configFile) reasons.add("writes_config");
+  if (!writeProfile?.insideProject && scopePaths.length > 0) reasons.add("writes_outside_repo");
+
+  record.riskDimensions = dimensions;
+  record.reasonCodes = Array.from(reasons);
+  return applyCommonDecisionFloors(record, context);
+}
+
+function evaluateExposureCandidate(cwd, candidate, context) {
+  const record = buildBaseDecisionRecord(cwd, candidate, context, "exposure");
+  const reasons = new Set(record.reasonCodes);
+  const claimRisk = normalizeEnum(candidate.claimRisk, new Set(["none", "bounded", "unsupported"]), "none");
+  const distributionState = context.publicDistributionReport?.distributionState || "private_local_only";
+  const installClaimsBlocked = context.publicDistributionReport?.installClaims?.blockedCount || 0;
+  const productionState = record.productionConfidenceState.state;
+
+  record.riskDimensions = buildRiskDimensions({
+    network: ["external_network", "browser_external"].includes(record.exposureType),
+    browser: record.exposureType === "browser_external",
+    deploy: record.exposureType === "production_deploy",
+    production: record.exposureType === "production_deploy",
+    public_exposure: ["docs_public", "website_public", "npm_package_public", "public_claim"].includes(record.exposureType),
+    config: record.exposureType === "credential_or_config",
+    secret: record.exposureType === "credential_or_config",
+    external_service: ["external_network", "browser_external", "production_deploy", "npm_package_public", "website_public"].includes(record.exposureType),
+    unknown_scope: hasUnknownScope(record.normalizedScope) || record.exposureType === "unknown_exposure",
+  });
+
+  if (record.exposureType === "local_only") {
+    record.decision = "allow";
+    reasons.add("trusted_read_only");
+  } else if (record.exposureType === "repo_internal") {
+    record.decision = "allow";
+  } else if (record.exposureType === "docs_public") {
+    record.decision = claimRisk === "unsupported" ? "approval_required" : "warn";
+  } else if (record.exposureType === "website_public") {
+    record.decision = claimRisk === "unsupported" ? "approval_required" : "warn";
+  } else if (record.exposureType === "npm_package_public") {
+    if (distributionState !== "published_verified" || installClaimsBlocked > 0) {
+      record.decision = "block";
+    } else {
+      record.decision = hasWeakOutcomeEvidence(context) ? "warn" : "allow";
+    }
+  } else if (record.exposureType === "external_network" || record.exposureType === "browser_external") {
+    record.decision = "approval_required";
+  } else if (record.exposureType === "production_deploy") {
+    record.decision = productionState === "blocked" ? "block" : "approval_required";
+  } else if (record.exposureType === "credential_or_config") {
+    record.decision = "block";
+  } else if (record.exposureType === "customer_data_adjacent") {
+    record.decision = "approval_required";
+  } else if (record.exposureType === "public_claim") {
+    record.decision = claimRisk === "unsupported" ? "block" : "warn";
+  } else {
+    record.decision = "approval_required";
+  }
+
+  if (claimRisk === "unsupported") reasons.add("public_claim_risk");
+  record.reasonCodes = Array.from(reasons);
+  return applyCommonDecisionFloors(record, context);
+}
+
+function evaluateToolCandidate(cwd, candidate, context) {
+  const record = buildBaseDecisionRecord(cwd, candidate, context, "tool_scope");
+  const reasons = new Set(record.reasonCodes);
+
+  record.riskDimensions = buildRiskDimensions({
+    read: record.toolType === "local_read" || record.toolType === "mcp_read",
+    write: record.toolType === "local_write" || record.toolType === "mcp_write",
+    exec: ["command", "package_manager", "mcp_write", "unknown"].includes(record.toolType),
+    network: ["network", "browser", "package_manager", "unknown"].includes(record.toolType),
+    browser: record.toolType === "browser",
+    package: record.toolType === "package_manager",
+    deploy: record.toolType === "deploy",
+    production: record.toolType === "deploy",
+    secret: record.toolType === "secret",
+    public_exposure: false,
+    config: record.toolType === "local_write" && (record.normalizedScope.paths || []).some((item) => isConfigFileTarget(item)),
+    path: (record.normalizedScope.paths || []).length > 0,
+    external_service: ["network", "browser", "deploy", "mcp_write", "unknown"].includes(record.toolType),
+    unknown_scope: hasUnknownScope(record.normalizedScope) || record.toolType === "unknown",
+  });
+
+  if (record.toolType === "local_read" && record.sourceTrust === "trusted" && !hasUnknownScope(record.normalizedScope)) {
+    record.decision = "allow";
+    reasons.add("trusted_read_only");
+  } else if (record.toolType === "local_write") {
+    record.decision = "auto_limit";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      paths: ["docs/**", "tests/**"],
+      visibility: "repo_internal",
+      notes: "Reduce write scope to docs/tests-only until a narrower reviewed source write is approved.",
+    });
+  } else if (record.toolType === "command") {
+    record.decision = "approval_required";
+  } else if (record.toolType === "package_manager") {
+    record.decision = "approval_required";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      paths: ["package.json", "package-lock.json"],
+      visibility: "repo_internal",
+      notes: "Review dependency metadata only before using a package manager with install capability.",
+    });
+  } else if (record.toolType === "mcp_read") {
+    record.decision = record.sourceTrust === "trusted" ? "allow" : "warn";
+  } else if (record.toolType === "mcp_write") {
+    record.decision = record.sourceTrust === "untrusted" ? "block" : "approval_required";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      toolNames: ["read_only_metadata"],
+      visibility: "repo_internal",
+      notes: "Start with read-only MCP inspection instead of write-capable access.",
+    });
+  } else if (record.toolType === "browser") {
+    record.decision = "approval_required";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      visibility: "local_plan_only",
+      notes: "Keep browser scope to local planning until the external target is explicitly reviewed.",
+    });
+  } else if (record.toolType === "network") {
+    record.decision = "approval_required";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      visibility: "no_network_summary_only",
+      notes: "Use a no-network local summary before requesting network scope.",
+    });
+  } else if (record.toolType === "deploy" || record.toolType === "secret") {
+    record.decision = "block";
+  } else {
+    record.decision = (record.riskDimensions.write || record.riskDimensions.network) ? "approval_required" : "warn";
+    record.minimalSafeScope = normalizeScope(cwd, {
+      toolNames: ["local_read_only"],
+      visibility: "repo_internal",
+      notes: "Reduce unknown tool scope to local read-only inspection first.",
+    });
+  }
+
+  record.reasonCodes = Array.from(reasons);
+  return applyCommonDecisionFloors(record, context);
+}
+
+function buildReceiptFromDecision(record) {
+  return {
+    receiptId: hashId("boundary-receipt", {
+      id: record.id,
+      decision: record.decision,
+      reasonCodes: record.reasonCodes,
+    }),
+    generatedAt: nowIso(),
+    type: record.type,
+    decision: record.decision,
+    actionType: record.actionType,
+    exposureType: record.exposureType,
+    toolType: record.toolType,
+    normalizedScope: record.normalizedScope,
+    minimalSafeScope: record.minimalSafeScope,
+    reasonCodes: record.reasonCodes,
+    evidenceRefs: record.evidenceRefs,
+    redacted: true,
+    safeNextAction: record.safeNextAction,
+  };
+}
+
+function buildDefaultCandidates(cwd) {
+  const hasDocs = toRelativeRedactedPath(cwd, "docs") !== "<outside-repo>";
+  return {
+    actions: [
+      {
+        id: "boundary-action-file-read",
+        actionType: "file_read",
+        intent: "Inspect local package metadata.",
+        sourceTrust: "trusted",
+        requestedScope: { paths: ["package.json"], visibility: "repo_internal" },
+      },
+      {
+        id: "boundary-action-file-write-source",
+        actionType: "file_write",
+        intent: "Change existing source code.",
+        sourceTrust: "trusted",
+        requestedScope: { paths: ["scripts/lib/public-cli.js"], visibility: "repo_internal" },
+      },
+      {
+        id: "boundary-action-command-run",
+        actionType: "command_run",
+        intent: "Run a local command that may change repo state.",
+        sourceTrust: "known",
+        command: "git push origin HEAD",
+        requestedScope: { commandClass: "local_command", visibility: "repo_internal" },
+      },
+      {
+        id: "boundary-action-public-content",
+        actionType: "public_content_change",
+        intent: "Draft public-facing copy updates without publishing them.",
+        sourceTrust: "trusted",
+        requestedScope: { paths: [hasDocs ? "docs/articles" : "docs"], visibility: "public_draft" },
+      },
+    ],
+    exposures: [
+      {
+        id: "boundary-exposure-local",
+        exposureType: "local_only",
+        intent: "Keep analysis local to the repo.",
+        sourceTrust: "trusted",
+        requestedScope: { visibility: "local_only" },
+      },
+      {
+        id: "boundary-exposure-repo",
+        exposureType: "repo_internal",
+        intent: "Share a redacted draft inside the repo only.",
+        sourceTrust: "trusted",
+        requestedScope: { visibility: "repo_internal" },
+      },
+      {
+        id: "boundary-exposure-docs",
+        exposureType: "docs_public",
+        intent: "Prepare customer-facing docs with bounded claims.",
+        sourceTrust: "known",
+        claimRisk: "bounded",
+        requestedScope: { visibility: "docs_public" },
+      },
+      {
+        id: "boundary-exposure-package",
+        exposureType: "npm_package_public",
+        intent: "Describe the public npm package without changing distribution state.",
+        sourceTrust: "known",
+        claimRisk: "bounded",
+        requestedScope: { visibility: "npm_package_public" },
+      },
+    ],
+    tools: [
+      {
+        id: "boundary-tool-local-read",
+        toolType: "local_read",
+        intent: "Read local files only.",
+        sourceTrust: "trusted",
+        requestedScope: { paths: ["package.json"], visibility: "repo_internal" },
+      },
+      {
+        id: "boundary-tool-local-write",
+        toolType: "local_write",
+        intent: "Request broad write access to the repo.",
+        sourceTrust: "known",
+        requestedScope: { paths: ["src/**", "docs/**"], repoWide: true, visibility: "repo_internal" },
+      },
+      {
+        id: "boundary-tool-package-manager",
+        toolType: "package_manager",
+        intent: "Use a package manager with install capability.",
+        sourceTrust: "known",
+        requestedScope: { paths: ["package.json", "package-lock.json"], visibility: "repo_internal" },
+      },
+      {
+        id: "boundary-tool-browser",
+        toolType: "browser",
+        intent: "Use an external browser-capable tool.",
+        sourceTrust: "unknown",
+        requestedScope: { domains: ["example.com"], visibility: "browser_external" },
+      },
+    ],
+  };
+}
+
+function buildOutcomeReadiness(report, context) {
+  const found = [];
+  const fixed = [];
+  const savedOrProved = [];
+  const needsAttention = [];
+
+  if (report.summary.blocked > 0) {
+    found.push(`${report.summary.blocked} boundary pattern(s) are blocked by deterministic policy.`);
+  }
+  if (report.summary.approvalRequired > 0) {
+    found.push(`${report.summary.approvalRequired} pattern(s) still require explicit approval.`);
+  }
+  if (report.summary.autoLimited > 0) {
+    fixed.push(`${report.summary.autoLimited} broad request(s) were reduced to a smaller safe scope.`);
+  }
+
+  savedOrProved.push(`${report.summary.receiptsCreated} redacted local boundary receipt(s) were prepared.`);
+  savedOrProved.push("LLM decisions remain disabled for boundary outcomes.");
+  if (context.skillsReport) savedOrProved.push("Skills routing stays thin, local, and verification-gated.");
+  if (context.publicDistributionReport?.distributionState === "published_verified") {
+    savedOrProved.push("Public distribution remains published_verified.");
+  }
+
+  if (hasWeakOutcomeEvidence(context)) {
+    needsAttention.push(context.outcomeReport?.summary?.safeNextAction || "Strengthen outcome evidence before widening public or deploy-adjacent scope.");
+  }
+  if ((context.workspaceReport?.summary?.unknownSources || 0) > 0) {
+    needsAttention.push(context.workspaceReport.summary.safeNextAction);
+  }
+  if ((context.productionReport?.readiness?.state || "") === "needs_review") {
+    needsAttention.push(context.productionReport.readiness.safeNextAction);
+  }
+  if (report.summary.safeNextAction) {
+    needsAttention.push(report.summary.safeNextAction);
+  }
+
+  return {
+    found: unique(found),
+    fixed: unique(fixed),
+    savedOrProved: unique(savedOrProved),
+    needsAttention: unique(needsAttention).slice(0, 4),
+  };
+}
+
+function summarizeDecisions(decisions) {
+  const summary = {
+    actionsReviewed: 0,
+    exposuresReviewed: 0,
+    toolsReviewed: 0,
+    allow: 0,
+    warn: 0,
+    approvalRequired: 0,
+    autoLimited: 0,
+    blocked: 0,
+    unknownScope: 0,
+    receiptsCreated: 0,
+    safeNextAction: "No decision data available.",
+  };
+
+  decisions.forEach((decision) => {
+    if (decision.type === "action") summary.actionsReviewed += 1;
+    if (decision.type === "exposure") summary.exposuresReviewed += 1;
+    if (decision.type === "tool_scope") summary.toolsReviewed += 1;
+    if (decision.decision === "allow") summary.allow += 1;
+    if (decision.decision === "warn") summary.warn += 1;
+    if (decision.decision === "approval_required") summary.approvalRequired += 1;
+    if (decision.decision === "auto_limit") summary.autoLimited += 1;
+    if (decision.decision === "block") summary.blocked += 1;
+    if (decision.reasonCodes.includes("unknown_scope")) summary.unknownScope += 1;
+  });
+
+  const next = decisions.find((item) => item.decision === "block")
+    || decisions.find((item) => item.decision === "approval_required")
+    || decisions.find((item) => item.decision === "auto_limit")
+    || decisions.find((item) => item.decision === "warn")
+    || decisions[0];
+  summary.safeNextAction = next?.safeNextAction || summary.safeNextAction;
+  return summary;
+}
+
+function buildClaimSafety() {
+  return {
+    autonomousExecution: false,
+    approvalBypassed: false,
+    enterpriseIamReplacement: false,
+    securityGuaranteed: false,
+    productionCertified: false,
+    liveEnforcementEverywhere: false,
+    externalScanPerformed: false,
+  };
+}
+
+function buildPolicy() {
+  return {
+    deterministic: true,
+    llmDecisionMaker: false,
+    localOnly: true,
+    upload: false,
+    providerApis: false,
+    toolExecution: false,
+    browserExecution: false,
+    deployExecution: false,
+  };
+}
+
+function buildDogfoodSection(cwd) {
+  const pkg = readPackageJson(cwd) || {};
+  const packageName = String(pkg.name || "").trim().toLowerCase();
+  return {
+    ranOnAvorelo: packageName === "avorelo" || /claudecode-optimizer/i.test(String(cwd || "")),
+    commands: DOGFOOD_COMMANDS,
+    summary: "Avorelo can classify risky action intent, public exposure, and tool scope on itself without executing the action.",
+  };
+}
+
+function buildGovernedActionExposureReport(cwd = process.cwd(), options = {}) {
+  const context = buildIntegrationContext(cwd, {
+    ...options,
+    buildIfMissing: options.buildIfMissing === true,
+  });
+  const defaults = buildDefaultCandidates(cwd);
+  const actionCandidates = Array.isArray(options.actions) ? options.actions : defaults.actions;
+  const exposureCandidates = Array.isArray(options.exposures) ? options.exposures : defaults.exposures;
+  const toolCandidates = Array.isArray(options.tools) ? options.tools : defaults.tools;
+
+  const decisions = [
+    ...actionCandidates.map((candidate) => evaluateActionCandidate(cwd, candidate, context)),
+    ...exposureCandidates.map((candidate) => evaluateExposureCandidate(cwd, candidate, context)),
+    ...toolCandidates.map((candidate) => evaluateToolCandidate(cwd, candidate, context)),
+  ];
+
+  const receipts = decisions.map((decision) => {
+    const receipt = buildReceiptFromDecision(decision);
+    decision.receiptRef = receipt.receiptId;
+    return receipt;
+  });
+
+  const summary = summarizeDecisions(decisions);
+  summary.receiptsCreated = receipts.length;
+  const outcomeReadiness = buildOutcomeReadiness({
+    summary,
+  }, context);
+
+  const report = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: nowIso(),
+    status: summary.blocked > 0 ? "fail" : (summary.warn > 0 || summary.approvalRequired > 0 || summary.autoLimited > 0 || summary.unknownScope > 0 ? "warn" : "pass"),
+    redacted: true,
+    summary,
+    decisions,
+    policy: buildPolicy(),
+    receipts,
+    outcomeReadiness,
+    scopeRepair: buildScopeRepairIntegration(cwd, options.integrationOverrides || {}),
+    claimSafety: buildClaimSafety(),
+    dogfood: buildDogfoodSection(cwd),
+  };
+
+  return report;
+}
+
+function writeGovernedActionExposureReport(cwd, report) {
+  safeWriteJson(cwd, LATEST_REPORT_REL, report);
+  return {
+    jsonPath: LATEST_REPORT_REL,
+  };
+}
+
+function generateGovernedActionExposureReport(cwd = process.cwd(), options = {}) {
+  const report = buildGovernedActionExposureReport(cwd, options);
+  const written = writeGovernedActionExposureReport(cwd, report);
+  return {
+    report,
+    written: true,
+    jsonPath: written.jsonPath,
+  };
+}
+
+function readLatestGovernedActionExposureReport(cwd) {
+  return safeReadJson(cwd, LATEST_REPORT_REL, null);
+}
+
+function buildScopeRepairIntegration(cwd, options = {}) {
+  const report = options.scopeRepairReport || readLatestScopeRepairReport(cwd);
+  if (!report) return null;
+  return {
+    status: report.status,
+    mismatchesDetected: Number(report.summary?.mismatchesDetected || 0),
+    repairsApplied: Number(report.summary?.scopeRepairsApplied || 0),
+    approvalsAvoided: Number(report.summary?.approvalsAvoided || 0),
+    approvalsStillRequired: Number(report.summary?.approvalsStillRequired || 0),
+    safeNextAction: sanitizeText(report.summary?.safeNextAction, 180),
+    evidenceRef: SCOPE_REPAIR_REPORT_REL,
+  };
+}
+
+function formatGovernedActionExposureText(report) {
+  const foundLine = report.outcomeReadiness.found.length > 0
+    ? report.outcomeReadiness.found.slice(0, 2).join(" ")
+    : "No high-risk boundary gaps detected.";
+  const autoLimitedLine = report.decisions
+    .filter((item) => item.decision === "auto_limit")
+    .slice(0, 2)
+    .map((item) => item.intent)
+    .join(" ");
+  const needsAttentionLine = report.outcomeReadiness.needsAttention.length > 0
+    ? report.outcomeReadiness.needsAttention.slice(0, 2).join(" ")
+    : "None.";
+
+  return [
+    "Avorelo Boundary",
+    `Status: ${String(report.status || "warn").toUpperCase()}`,
+    `Reviewed: ${report.summary.actionsReviewed} actions, ${report.summary.exposuresReviewed} exposures, ${report.summary.toolsReviewed} tools`,
+    `Decisions: ${report.summary.allow} allow, ${report.summary.warn} warn, ${report.summary.approvalRequired} approval required, ${report.summary.autoLimited} auto-limited, ${report.summary.blocked} blocked`,
+    `Found: ${foundLine}`,
+    `Auto-limited: ${autoLimitedLine || "None."}`,
+    ...(report.scopeRepair ? [`Scope repair: ${report.scopeRepair.repairsApplied || 0} applied, ${report.scopeRepair.approvalsAvoided || 0} approvals avoided, ${report.scopeRepair.approvalsStillRequired || 0} still require review`] : []),
+    `Needs attention: ${needsAttentionLine}`,
+    `Safe next action: ${report.summary.safeNextAction}`,
+  ].join("\n");
+}
+
+function formatGovernedActionExposureStatusLineFromReport(report) {
+  const reviewed = (report.summary.actionsReviewed || 0) + (report.summary.exposuresReviewed || 0) + (report.summary.toolsReviewed || 0);
+  const scopeRepair = report.scopeRepair
+    ? ` · scope repair ${report.scopeRepair.repairsApplied || 0}/${report.scopeRepair.approvalsAvoided || 0}`
+    : "";
+  return `Boundary: ${String(report.status || "warn").toUpperCase()} · ${reviewed} patterns reviewed · ${report.summary.approvalRequired || 0} approval required · ${report.summary.autoLimited || 0} auto-limited${scopeRepair} · next: ${report.summary.safeNextAction}`;
+}
+
+function buildGovernedActionExposureSurface(cwd = process.cwd(), options = {}) {
+  const report = readLatestGovernedActionExposureReport(cwd)
+    || (options.buildIfMissing === true ? buildGovernedActionExposureReport(cwd, options) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      showInStatus: true,
+      showInDashboard: true,
+      reviewedPatterns: 0,
+      approvalRequired: 0,
+      autoLimited: 0,
+      blocked: 0,
+      nextAction: "Run `avorelo boundary --text` to generate the first governed boundary report.",
+      latestReportPath: null,
+      statusLine: "Boundary: NOT RUN · run `avorelo boundary --text`",
+    };
+  }
+
+  const reviewedPatterns = (report.summary.actionsReviewed || 0) + (report.summary.exposuresReviewed || 0) + (report.summary.toolsReviewed || 0);
+  return {
+    status: report.status,
+    showInStatus: true,
+    showInDashboard: true,
+    reviewedPatterns,
+    approvalRequired: report.summary.approvalRequired || 0,
+    autoLimited: report.summary.autoLimited || 0,
+    blocked: report.summary.blocked || 0,
+    scopeRepair: report.scopeRepair || null,
+    nextAction: report.summary.safeNextAction,
+    latestReportPath: LATEST_REPORT_REL,
+    statusLine: formatGovernedActionExposureStatusLineFromReport(report),
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  LATEST_REPORT_REL,
+  DOGFOOD_COMMANDS,
+  buildGovernedActionExposureReport,
+  writeGovernedActionExposureReport,
+  generateGovernedActionExposureReport,
+  readLatestGovernedActionExposureReport,
+  buildGovernedActionExposureSurface,
+  formatGovernedActionExposureText,
+  formatGovernedActionExposureStatusLineFromReport,
+};