avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/scope-repair-before-approval.js

@@ -0,0 +1,865 @@
+"use strict";
+
+const path = require("path");
+
+const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const CONTRACT = "avorelo.scopeRepair.v1";
+const REPORT_DIR_REL = ".claude/cco/orchestration/scope-repair";
+const LATEST_REPORT_REL = `${REPORT_DIR_REL}/latest-report.json`;
+const BOUNDARY_REPORT_REL = ".claude/cco/security/governed-action-exposure/latest-report.json";
+
+const DEFAULT_BOUNDARY_IDS = new Set([
+  "boundary-action-file-read",
+  "boundary-action-file-write-source",
+  "boundary-action-command-run",
+  "boundary-action-public-content",
+  "boundary-exposure-local",
+  "boundary-exposure-repo",
+  "boundary-exposure-docs",
+  "boundary-exposure-package",
+  "boundary-tool-local-read",
+  "boundary-tool-local-write",
+  "boundary-tool-package-manager",
+  "boundary-tool-browser",
+]);
+
+const DECISION_TYPES = Object.freeze([
+  "no_data",
+  "no_mismatch",
+  "mismatch_detected",
+  "repaired_to_requested_scope",
+  "downgraded_to_read_only",
+  "limited_to_local_target",
+  "package_install_removed_for_metadata_review",
+  "external_target_removed",
+  "split_safe_scope_from_review_scope",
+  "approval_avoided_after_repair",
+  "approval_still_required_after_repair",
+  "blocked_unrepairable_scope",
+]);
+
+const TEXT_STATUS_LABELS = Object.freeze({
+  pass: "PASS",
+  warn: "WARN",
+  blocked: "BLOCKED",
+  no_data: "No Data",
+});
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function sanitizeText(value, maxChars = 180) {
+  const text = String(value || "")
+    .replace(/\s+/g, " ")
+    .replace(/(?:sk-[A-Za-z0-9_-]{16,}|gh[ps]_[A-Za-z0-9]{12,}|npm_[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{16})/g, "[redacted-token]")
+    .replace(/(bearer\s+)[A-Za-z0-9._-]{8,}/ig, "$1[redacted]")
+    .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]")
+    .trim();
+  if (!text) return null;
+  if (/^\s*(?:system|user|assistant)\s*:/i.test(text)) return null;
+  if (/\b(?:function\s+\w+\s*\(|const\s+\w+\s*=|module\.exports\s*=|class\s+\w+)/.test(text) && /[{};]/.test(text)) {
+    return null;
+  }
+  return text.length > maxChars ? `${text.slice(0, maxChars - 3).trimEnd()}...` : text;
+}
+
+function normalizeList(value) {
+  return (Array.isArray(value) ? value : value ? [value] : [])
+    .map((item) => String(item || "").trim())
+    .filter(Boolean);
+}
+
+function toRelativeRedactedPath(cwd, value) {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  if (/^https?:\/\//i.test(raw)) {
+    try {
+      return new URL(raw).hostname.toLowerCase();
+    } catch {
+      return null;
+    }
+  }
+  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 normalizeFiles(cwd, files) {
+  return unique(normalizeList(files).map((item) => toRelativeRedactedPath(cwd, item))).filter(Boolean);
+}
+
+function normalizeTargets(cwd, targets) {
+  return unique(normalizeList(targets).map((item) => {
+    if (/^[A-Za-z]:\\/.test(item) || item.includes("\\") || item.startsWith("/")) {
+      return toRelativeRedactedPath(cwd, item);
+    }
+    return sanitizeText(item, 120);
+  })).filter(Boolean);
+}
+
+function normalizeActions(actions) {
+  return unique(normalizeList(actions).map((item) => sanitizeText(item, 80)?.toLowerCase())).filter(Boolean);
+}
+
+function inferIntentType(scope = {}) {
+  if (scope.intentType) return scope.intentType;
+  const actions = normalizeActions(scope.actions);
+  const files = normalizeList(scope.files).map((item) => item.replace(/\\/g, "/"));
+  const targets = normalizeList(scope.targets).map((item) => item.toLowerCase());
+
+  if (actions.length > 0) {
+    if (actions.every((item) => item === "file_read" || item === "read_only" || item === "inspect")) return "read_only";
+    if (actions.includes("package_review") || actions.includes("metadata_review")) return "package_review";
+    if (actions.includes("browser_local")) return "browser_local";
+    if (actions.some((item) => item.includes("write") || item.includes("change") || item.includes("edit"))) return "code_change";
+  }
+
+  if (targets.some((item) => /localhost|127\.0\.0\.1|0\.0\.0\.0/.test(item))) return "browser_local";
+  if (files.length > 0 && files.every((item) => item.startsWith("docs/") || item.endsWith(".md"))) return "docs_only";
+  if (files.length > 0) return "code_change";
+  return "unknown";
+}
+
+function computeRiskTier(scope = {}) {
+  const actions = normalizeActions(scope.actions);
+  const files = normalizeList(scope.files).map((item) => item.replace(/\\/g, "/").toLowerCase());
+  const targets = normalizeList(scope.targets).map((item) => item.toLowerCase());
+
+  const sensitiveFile = files.some((item) =>
+    /(^|\/)(?:\.env(?:\..*)?|secrets?|credentials?|auth|billing|payment|deploy|deployment|infra|terraform|k8s|docker|vercel|netlify|production|prod-config)/i.test(item)
+  );
+  const broadWrite = files.some((item) => /\*\*|\*$/.test(item)) || scope.repoWide === true;
+  const sensitiveAction = actions.some((item) =>
+    ["package_install", "package_publish", "deploy_action", "secret_access", "config_change"].includes(item)
+  );
+  const externalTarget = targets.some((item) => !/^(localhost|127\.0\.0\.1|0\.0\.0\.0|repo_internal|local_only|\.)/.test(item));
+
+  if (sensitiveFile || sensitiveAction) return "high";
+  if (broadWrite || externalTarget) return "high";
+  if (actions.some((item) => item.includes("write") || item.includes("change") || item.includes("browser"))) return "medium";
+  if (files.length > 0 || actions.length > 0 || targets.length > 0) return "low";
+  return "unknown";
+}
+
+function normalizeScope(cwd, scope = {}, kind) {
+  if (!scope || typeof scope !== "object") {
+    return {
+      source: "none",
+      intentType: "unknown",
+      files: [],
+      actions: [],
+      targets: [],
+      riskTier: "unknown",
+    };
+  }
+
+  const normalized = {
+    source: sanitizeText(scope.source, 40) || (kind === "requested" ? "provided" : "fixture"),
+    intentType: inferIntentType(scope),
+    files: normalizeFiles(cwd, scope.files || scope.paths),
+    actions: normalizeActions(scope.actions),
+    targets: normalizeTargets(cwd, scope.targets || scope.domains),
+    riskTier: scope.riskTier || computeRiskTier(scope),
+  };
+
+  if (normalized.actions.length === 0 && normalized.intentType === "read_only") {
+    normalized.actions = ["file_read"];
+  }
+  if (normalized.actions.length === 0 && normalized.intentType === "browser_local") {
+    normalized.actions = ["browser_local"];
+  }
+  if (normalized.actions.length === 0 && normalized.intentType === "package_review") {
+    normalized.actions = ["package_review"];
+  }
+  if (normalized.actions.length === 0 && normalized.files.length > 0) {
+    normalized.actions = normalized.intentType === "docs_only" ? ["docs_write"] : ["file_write"];
+  }
+  return normalized;
+}
+
+function mapBoundaryDecisionToScope(cwd, decision) {
+  const requested = normalizeScope(cwd, {
+    source: "inferred",
+    intentType: mapIntentTypeFromBoundary(decision, decision.requestedScope),
+    files: decision?.requestedScope?.paths,
+    actions: mapActionsFromBoundary(decision, decision.requestedScope),
+    targets: decision?.requestedScope?.domains,
+    riskTier: decision?.requestedScope?.riskTier,
+  }, "requested");
+  const planned = normalizeScope(cwd, {
+    source: "boundary",
+    intentType: mapIntentTypeFromBoundary(decision, decision.normalizedScope),
+    files: decision?.normalizedScope?.paths,
+    actions: mapActionsFromBoundary(decision, decision.normalizedScope),
+    targets: decision?.normalizedScope?.domains,
+    riskTier: decision?.normalizedScope?.riskTier,
+  }, "planned");
+
+  const repaired = decision?.minimalSafeScope
+    ? normalizeScope(cwd, {
+        source: "boundary",
+        intentType: mapIntentTypeFromBoundary(decision, decision.minimalSafeScope),
+        files: decision.minimalSafeScope.paths,
+        actions: mapActionsFromBoundary(decision, decision.minimalSafeScope),
+        targets: decision.minimalSafeScope.domains,
+        riskTier: decision.minimalSafeScope.riskTier,
+      }, "planned")
+    : null;
+
+  return { requested, planned, repaired };
+}
+
+function mapIntentTypeFromBoundary(decision, scope) {
+  const visibility = String(scope?.visibility || "").toLowerCase();
+  if (decision?.actionType === "file_read") return "read_only";
+  if (decision?.actionType === "package_install") return "package_review";
+  if (decision?.actionType === "browser_action") {
+    return visibility === "local_only" || (scope?.domains || []).some((item) => /localhost|127\.0\.0\.1/.test(String(item))) ? "browser_local" : "unknown";
+  }
+  if ((scope?.paths || []).every((item) => String(item).startsWith("docs/") || String(item).endsWith(".md"))) {
+    return "docs_only";
+  }
+  return visibility === "repo_internal" || (scope?.paths || []).length > 0 ? "code_change" : "unknown";
+}
+
+function mapActionsFromBoundary(decision, scope) {
+  if (decision?.actionType === "file_read") return ["file_read"];
+  if (decision?.actionType === "file_write") {
+    return (scope?.paths || []).every((item) => String(item).startsWith("docs/") || String(item).endsWith(".md"))
+      ? ["docs_write"]
+      : ["file_write"];
+  }
+  if (decision?.actionType === "package_install") return ["package_install"];
+  if (decision?.actionType === "browser_action") {
+    return (scope?.domains || []).some((item) => /localhost|127\.0\.0\.1/.test(String(item))) ? ["browser_local"] : ["browser_external"];
+  }
+  if (decision?.actionType) return [decision.actionType];
+  if (decision?.toolType === "local_read") return ["file_read"];
+  if (decision?.toolType === "local_write") return ["file_write"];
+  if (decision?.toolType === "browser") return ["browser_external"];
+  if (decision?.toolType === "package_manager") return ["package_install"];
+  if (decision?.exposureType === "local_only") return ["file_read"];
+  return [];
+}
+
+function derivePairFromBoundary(cwd, boundaryReport) {
+  const decisions = Array.isArray(boundaryReport?.decisions) ? boundaryReport.decisions : [];
+  if (!decisions.length) return null;
+  const nonDefault = decisions.filter((decision) => !DEFAULT_BOUNDARY_IDS.has(String(decision.id || "")));
+  const eligible = nonDefault.find((decision) =>
+    decision
+    && decision.requestedScope
+    && decision.normalizedScope
+    && (
+      decision.minimalSafeScope
+      || decision.decision === "auto_limit"
+      || decision.reasonCodes?.includes("safe_scope_available")
+    )
+  );
+  if (!eligible) return null;
+  return {
+    source: "boundary",
+    decision: eligible,
+    ...mapBoundaryDecisionToScope(cwd, eligible),
+  };
+}
+
+function loadDerivedPair(cwd, options = {}) {
+  if (options.requestedScope || options.plannedAction) {
+    return {
+      source: "provided",
+      requested: normalizeScope(cwd, { ...options.requestedScope, source: options.requestedScope?.source || "provided" }, "requested"),
+      planned: normalizeScope(cwd, { ...options.plannedAction, source: options.plannedAction?.source || "fixture" }, "planned"),
+      repairedSeed: options.repairedScope ? normalizeScope(cwd, options.repairedScope, "planned") : null,
+    };
+  }
+
+  const boundaryReport = options.boundaryReport || safeReadJson(cwd, BOUNDARY_REPORT_REL, null);
+  if (boundaryReport) {
+    const derived = derivePairFromBoundary(cwd, boundaryReport);
+    if (derived) {
+      return {
+        source: "boundary",
+        requested: derived.requested,
+        planned: derived.planned,
+        repairedSeed: derived.repaired,
+      };
+    }
+  }
+
+  return null;
+}
+
+function diffCount(left, right) {
+  const leftSet = new Set(left || []);
+  const rightSet = new Set(right || []);
+  let count = 0;
+  for (const item of leftSet) {
+    if (!rightSet.has(item)) count += 1;
+  }
+  return count;
+}
+
+function isSensitiveScope(scope = {}) {
+  return computeRiskTier(scope) === "high";
+}
+
+function computeApprovalState(scope = {}, options = {}) {
+  const riskTier = scope.riskTier || computeRiskTier(scope);
+  const actions = normalizeActions(scope.actions);
+  if (options.missingRequested && riskTier === "high") return "blocked";
+  if (actions.some((item) => ["package_install", "package_publish", "deploy_action", "secret_access"].includes(item))) {
+    return "approval_required";
+  }
+  if (riskTier === "high") return options.missingRequested ? "blocked" : "approval_required";
+  if (riskTier === "unknown") return "unknown";
+  return "not_required";
+}
+
+function buildNoDataReport() {
+  const safeNextAction = "Continue with bounded work and create proof.";
+  return {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status: "no_data",
+    redacted: true,
+    summary: {
+      mismatchesDetected: 0,
+      scopeRepairsApplied: 0,
+      approvalsAvoided: 0,
+      approvalsStillRequired: 0,
+      blockedAfterRepair: 0,
+      filesAvoided: 0,
+      actionsAvoided: 0,
+      safeNextAction,
+    },
+    requestedScope: {
+      source: "none",
+      intentType: "unknown",
+      files: [],
+      actions: [],
+      targets: [],
+      riskTier: "unknown",
+    },
+    plannedAction: {
+      source: "none",
+      files: [],
+      actions: [],
+      targets: [],
+      riskTier: "unknown",
+      approvalBeforeRepair: "unknown",
+    },
+    repairedScope: {
+      applied: false,
+      repairType: "none",
+      files: [],
+      actions: [],
+      targets: [],
+      riskTier: "unknown",
+      approvalAfterRepair: "unknown",
+      approvalAvoided: false,
+    },
+    decisions: ["no_data"],
+    reasonCodes: ["no_requested_scope_available", "no_planned_action_available", "safe_next_action_available"],
+    wasteSignals: {
+      scopeExpansionAvoided: false,
+      unnecessaryFilesAvoided: 0,
+      unnecessaryActionsAvoided: 0,
+      approvalAvoided: false,
+      confidence: "none",
+    },
+    carryForward: {
+      nextRunRefs: [],
+      boundaryRefs: [],
+      productHomeRefs: [],
+      evidenceRefs: [],
+    },
+    integrationRefs: {
+      boundary: [],
+      nextRun: [],
+      productHome: [],
+      status: [],
+      dashboard: [],
+      outcomeEvidence: [],
+    },
+    privacy: buildPrivacySection(),
+    claimSafety: buildClaimSafetySection(),
+    text: {
+      found: "no requested/planned scope pair available",
+      repaired: "none",
+      approval: "unknown",
+    },
+  };
+}
+
+function buildPrivacySection() {
+  return {
+    localOnly: true,
+    rawPromptStored: false,
+    rawCodeStored: false,
+    secretsStored: false,
+    screenshotsStored: false,
+    fullLogsStored: false,
+    privatePathsStored: false,
+    redacted: true,
+  };
+}
+
+function buildClaimSafetySection() {
+  return {
+    approvalAlwaysAvoided: false,
+    guaranteedSafe: false,
+    autonomousApproval: false,
+    fullPolicyEnforcement: false,
+    runtimeBoundaryRewrite: false,
+    savingsGuaranteed: false,
+  };
+}
+
+function compareScope(requested, planned) {
+  const reasonCodes = [];
+  const mismatches = [];
+
+  const requestedFiles = new Set(requested.files || []);
+  const plannedFiles = new Set(planned.files || []);
+  const requestedActions = new Set(requested.actions || []);
+  const plannedActions = new Set(planned.actions || []);
+  const requestedTargets = new Set(requested.targets || []);
+  const plannedTargets = new Set(planned.targets || []);
+
+  const extraFiles = [...plannedFiles].filter((item) => !requestedFiles.has(item));
+  const extraActions = [...plannedActions].filter((item) => !requestedActions.has(item));
+  const extraTargets = [...plannedTargets].filter((item) => !requestedTargets.has(item));
+
+  if (requested.files.length > 0 && extraFiles.length > 0) {
+    mismatches.push("file_scope");
+    reasonCodes.push("scope_expansion_detected", "file_scope_expanded");
+  }
+  if (requested.actions.length > 0 && extraActions.length > 0) {
+    mismatches.push("action_scope");
+    reasonCodes.push("scope_expansion_detected", "action_scope_expanded");
+  }
+  if (requested.targets.length > 0 && extraTargets.length > 0) {
+    mismatches.push("target_scope");
+    reasonCodes.push("scope_expansion_detected", "target_scope_expanded");
+  }
+
+  if (requested.intentType === "read_only" && planned.actions.some((item) => item !== "file_read" && item !== "read_only")) {
+    mismatches.push("read_only_violation");
+    reasonCodes.push("write_after_read_only_request");
+  }
+  if (requested.intentType === "docs_only" && planned.files.some((item) => !(item.startsWith("docs/") || item.endsWith(".md")))) {
+    mismatches.push("docs_violation");
+    reasonCodes.push("docs_request_expanded_to_source");
+  }
+  if (requested.intentType === "package_review" && planned.actions.includes("package_install")) {
+    mismatches.push("package_violation");
+    reasonCodes.push("package_install_after_review_request");
+  }
+  if (requested.intentType === "browser_local" && planned.targets.some((item) => !/^(localhost|127\.0\.0\.1|0\.0\.0\.0)/.test(item))) {
+    mismatches.push("external_target_violation");
+    reasonCodes.push("external_target_after_local_request");
+  }
+
+  return {
+    mismatches: unique(mismatches),
+    reasonCodes: unique(reasonCodes),
+    extraFiles,
+    extraActions,
+    extraTargets,
+  };
+}
+
+function repairScope(requested, planned, comparison, repairedSeed) {
+  if (!requested || !planned) {
+    return {
+      repaired: {
+        applied: false,
+        repairType: "none",
+        files: [],
+        actions: [],
+        targets: [],
+        riskTier: "unknown",
+        approvalAfterRepair: "unknown",
+        approvalAvoided: false,
+      },
+      decisions: [],
+      reasonCodes: [],
+      foundLine: "no requested/planned scope pair available",
+      repairedLine: "none",
+      approvalLine: "unknown",
+    };
+  }
+
+  if (requested.intentType === "unknown" && planned.riskTier === "high") {
+    return {
+      repaired: {
+        applied: false,
+        repairType: "blocked_unrepairable",
+        files: [],
+        actions: [],
+        targets: [],
+        riskTier: "high",
+        approvalAfterRepair: "blocked",
+        approvalAvoided: false,
+      },
+      decisions: ["mismatch_detected", "blocked_unrepairable_scope"],
+      reasonCodes: unique([...comparison.reasonCodes, "blocked_unrepairable_scope"]),
+      foundLine: "requested scope is missing and the planned action is too broad to repair safely",
+      repairedLine: "blocked as unrepairable without explicit scope",
+      approvalLine: "blocked",
+    };
+  }
+
+  let files = repairedSeed?.files?.length ? repairedSeed.files.slice() : planned.files.slice();
+  let actions = repairedSeed?.actions?.length ? repairedSeed.actions.slice() : planned.actions.slice();
+  let targets = repairedSeed?.targets?.length ? repairedSeed.targets.slice() : planned.targets.slice();
+  let repairType = "none";
+  const decisions = [];
+  const reasonCodes = [];
+
+  if (comparison.mismatches.length > 0) {
+    decisions.push("mismatch_detected");
+  } else {
+    decisions.push("no_mismatch");
+    return {
+      repaired: {
+        applied: false,
+        repairType,
+        files,
+        actions,
+        targets,
+        riskTier: computeRiskTier({ files, actions, targets }),
+        approvalAfterRepair: computeApprovalState({ files, actions, targets, riskTier: computeRiskTier({ files, actions, targets }) }),
+        approvalAvoided: false,
+      },
+      decisions,
+      reasonCodes: ["no_scope_mismatch_detected", "safe_next_action_available"],
+      foundLine: "planned action already matches the requested scope",
+      repairedLine: "none",
+      approvalLine: "not required",
+    };
+  }
+
+  if (requested.files.length > 0) {
+    files = requested.files.slice();
+    repairType = "reduce_files";
+    decisions.push("repaired_to_requested_scope");
+    reasonCodes.push("reduced_to_user_requested_scope");
+  }
+
+  if (requested.actions.length > 0) {
+    actions = requested.actions.slice();
+  }
+
+  if (requested.targets.length > 0) {
+    targets = requested.targets.slice();
+  }
+
+  if (requested.intentType === "read_only") {
+    actions = ["file_read"];
+    repairType = "downgrade_to_read_only";
+    decisions.push("downgraded_to_read_only");
+    reasonCodes.push("downgraded_to_read_only");
+  } else if (requested.intentType === "browser_local") {
+    actions = actions.includes("browser_local") ? ["browser_local"] : ["browser_local"];
+    targets = requested.targets.length > 0 ? requested.targets.slice() : targets.filter((item) => /^(localhost|127\.0\.0\.1|0\.0\.0\.0)/.test(item));
+    repairType = "limit_to_local";
+    decisions.push("limited_to_local_target");
+    if (comparison.extraTargets.length > 0) decisions.push("external_target_removed");
+    reasonCodes.push("limited_to_local_target", "external_target_removed");
+  } else if (requested.intentType === "package_review") {
+    actions = ["package_review"];
+    repairType = "remove_package_install";
+    decisions.push("package_install_removed_for_metadata_review");
+    reasonCodes.push("package_install_removed");
+  } else if (requested.intentType === "docs_only") {
+    files = requested.files.length > 0 ? requested.files.slice() : planned.files.filter((item) => item.startsWith("docs/") || item.endsWith(".md"));
+    actions = ["docs_write"];
+    repairType = repairType === "none" ? "reduce_files" : repairType;
+    decisions.push("repaired_to_requested_scope");
+    reasonCodes.push("reduced_to_user_requested_scope");
+  }
+
+  files = unique(files);
+  actions = unique(actions);
+  targets = unique(targets);
+
+  const riskTier = computeRiskTier({ files, actions, targets });
+  const approvalAfterRepair = computeApprovalState({ files, actions, targets, riskTier });
+  const approvalAvoided = approvalAfterRepair === "not_required";
+
+  return {
+    repaired: {
+      applied: true,
+      repairType,
+      files,
+      actions,
+      targets,
+      riskTier,
+      approvalAfterRepair,
+      approvalAvoided,
+    },
+    decisions,
+    reasonCodes: unique(reasonCodes),
+    foundLine: buildFoundLine(requested, planned, comparison),
+    repairedLine: buildRepairedLine(requested, planned, { files, actions, targets, repairType }),
+    approvalLine: approvalAfterRepair === "approval_required" && isSensitiveScope({ files, actions, targets, riskTier })
+      ? "still required because scoped work still touches a sensitive area"
+      : approvalAfterRepair === "blocked"
+        ? "blocked"
+        : approvalAvoided
+          ? "avoided"
+          : "not required",
+  };
+}
+
+function buildFoundLine(requested, planned, comparison) {
+  if (requested.intentType === "read_only" && comparison.mismatches.includes("read_only_violation")) {
+    return "planned write expanded beyond a read-only request";
+  }
+  if (requested.intentType === "docs_only" && comparison.mismatches.includes("docs_violation")) {
+    return "planned source changes expanded beyond the docs-only request";
+  }
+  if (requested.intentType === "package_review" && comparison.mismatches.includes("package_violation")) {
+    return "planned package install expanded beyond the metadata review request";
+  }
+  if (requested.intentType === "browser_local" && comparison.mismatches.includes("external_target_violation")) {
+    return "planned browser target expanded beyond local proof scope";
+  }
+  return "planned action expanded beyond requested scope";
+}
+
+function buildRepairedLine(requested, planned, repaired) {
+  if (repaired.repairType === "downgrade_to_read_only") {
+    return "downgraded planned write scope to read-only";
+  }
+  if (repaired.repairType === "limit_to_local") {
+    return "limited planned targets to local-only proof";
+  }
+  if (repaired.repairType === "remove_package_install") {
+    return "removed package install and kept metadata review only";
+  }
+  if (requested.files.length > 0 && planned.files.length > requested.files.length) {
+    return `reduced ${planned.files.length} planned files to ${requested.files.length} requested files`;
+  }
+  if (requested.actions.length > 0 && planned.actions.length > requested.actions.length) {
+    return `reduced ${planned.actions.length} planned actions to ${requested.actions.length} requested actions`;
+  }
+  if (requested.targets.length > 0 && planned.targets.length > requested.targets.length) {
+    return `reduced ${planned.targets.length} planned targets to ${requested.targets.length} requested targets`;
+  }
+  return "narrowed the planned action to the requested scope";
+}
+
+function buildSafeNextAction(requested, repaired, status) {
+  if (status === "no_data") return "Continue with bounded work and create proof.";
+  if (status === "blocked") return "Keep the action blocked and confirm the intended scope explicitly.";
+  if (repaired.approvalAfterRepair === "approval_required") {
+    if (requested.intentType === "read_only") return "Continue read-only or approve the scoped sensitive change.";
+    return "Approve only the scoped sensitive change or continue read-only.";
+  }
+  if (requested.intentType === "read_only") return "Continue with bounded read-only review.";
+  if (requested.intentType === "browser_local") return "Continue with localhost-only proof.";
+  return "Continue with bounded implementation.";
+}
+
+function buildReportFromPair(cwd, pair) {
+  if (!pair || !pair.requested || !pair.planned) {
+    return buildNoDataReport();
+  }
+
+  const requested = pair.requested;
+  const planned = pair.planned;
+  const comparison = compareScope(requested, planned);
+  const approvalBeforeRepair = computeApprovalState(planned, { missingRequested: requested.intentType === "unknown" });
+  const repairResult = repairScope(requested, planned, comparison, pair.repairedSeed);
+  const safeNextAction = buildSafeNextAction(requested, repairResult.repaired, repairResult.repaired.approvalAfterRepair === "blocked" ? "blocked" : null);
+  const filesAvoided = Math.max(0, diffCount(planned.files, repairResult.repaired.files));
+  const actionsAvoided = Math.max(0, diffCount(planned.actions, repairResult.repaired.actions));
+  const approvalAvoided = approvalBeforeRepair !== "not_required" && repairResult.repaired.approvalAfterRepair === "not_required";
+  const approvalsStillRequired = repairResult.repaired.approvalAfterRepair === "approval_required" ? 1 : 0;
+  const blockedAfterRepair = repairResult.repaired.approvalAfterRepair === "blocked" ? 1 : 0;
+
+  const status = blockedAfterRepair > 0
+    ? "blocked"
+    : comparison.mismatches.length > 0 || approvalsStillRequired > 0
+      ? "warn"
+      : "pass";
+
+  const decisions = unique([
+    ...repairResult.decisions,
+    ...(approvalAvoided ? ["approval_avoided_after_repair"] : []),
+    ...(approvalsStillRequired > 0 ? ["approval_still_required_after_repair"] : []),
+  ]);
+
+  const reasonCodes = unique([
+    ...comparison.reasonCodes,
+    ...repairResult.reasonCodes,
+    ...(approvalAvoided ? ["approval_avoided"] : []),
+    ...(approvalsStillRequired > 0 ? ["approval_still_required"] : []),
+    ...(filesAvoided > 0 ? ["unnecessary_files_avoided"] : []),
+    ...(actionsAvoided > 0 ? ["unnecessary_actions_avoided"] : []),
+    ...(comparison.mismatches.length > 0 ? ["safe_next_action_available"] : ["no_scope_mismatch_detected", "safe_next_action_available"]),
+    "raw_data_excluded",
+  ]);
+
+  const report = {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status,
+    redacted: true,
+    summary: {
+      mismatchesDetected: comparison.mismatches.length > 0 ? 1 : 0,
+      scopeRepairsApplied: repairResult.repaired.applied ? 1 : 0,
+      approvalsAvoided: approvalAvoided ? 1 : 0,
+      approvalsStillRequired,
+      blockedAfterRepair,
+      filesAvoided,
+      actionsAvoided,
+      safeNextAction,
+    },
+    requestedScope: requested,
+    plannedAction: {
+      ...planned,
+      approvalBeforeRepair,
+    },
+    repairedScope: {
+      ...repairResult.repaired,
+      approvalAfterRepair: repairResult.repaired.approvalAfterRepair,
+      approvalAvoided,
+    },
+    decisions,
+    reasonCodes,
+    wasteSignals: {
+      scopeExpansionAvoided: comparison.mismatches.length > 0 && repairResult.repaired.applied,
+      unnecessaryFilesAvoided: filesAvoided,
+      unnecessaryActionsAvoided: actionsAvoided,
+      approvalAvoided,
+      confidence: pair.source === "boundary" ? "estimated" : "measured",
+    },
+    carryForward: {
+      nextRunRefs: [LATEST_REPORT_REL],
+      boundaryRefs: pair.source === "boundary" ? [BOUNDARY_REPORT_REL] : [],
+      productHomeRefs: [LATEST_REPORT_REL],
+      evidenceRefs: [],
+    },
+    integrationRefs: {
+      boundary: pair.source === "boundary" ? [BOUNDARY_REPORT_REL] : [],
+      nextRun: [LATEST_REPORT_REL],
+      productHome: [LATEST_REPORT_REL],
+      status: [LATEST_REPORT_REL],
+      dashboard: [LATEST_REPORT_REL],
+      outcomeEvidence: [],
+    },
+    privacy: buildPrivacySection(),
+    claimSafety: buildClaimSafetySection(),
+  };
+
+  report.text = {
+    found: repairResult.foundLine,
+    repaired: repairResult.repairedLine,
+    approval: repairResult.approvalLine,
+  };
+
+  return report;
+}
+
+function buildScopeRepairReport(cwd = process.cwd(), options = {}) {
+  const pair = loadDerivedPair(cwd, options);
+  return buildReportFromPair(cwd, pair);
+}
+
+function writeScopeRepairReport(cwd, report) {
+  safeWriteJson(cwd, LATEST_REPORT_REL, report);
+  return LATEST_REPORT_REL;
+}
+
+function generateScopeRepairReport(cwd = process.cwd(), options = {}) {
+  const report = buildScopeRepairReport(cwd, options);
+  const written = options.write === false ? null : writeScopeRepairReport(cwd, report);
+  return {
+    report,
+    written: Boolean(written),
+    jsonPath: written,
+  };
+}
+
+function readLatestScopeRepairReport(cwd = process.cwd()) {
+  return safeReadJson(cwd, LATEST_REPORT_REL, null);
+}
+
+function formatScopeRepairText(report) {
+  const lines = [
+    "Avorelo Scope Repair",
+    `Status: ${TEXT_STATUS_LABELS[report.status] || String(report.status || "warn").toUpperCase()}`,
+    `Found: ${report.text?.found || "planned action already matches the requested scope"}`,
+    `Repaired: ${report.text?.repaired || "none"}`,
+    `Next: ${report.summary?.safeNextAction || "Continue with bounded work and create proof."}`,
+  ];
+  if (report.status !== "no_data") {
+    lines.splice(4, 0, `Approval: ${report.text?.approval || "not required"}`);
+  }
+  return lines.join("\n");
+}
+
+function buildDashboardCard(report) {
+  return {
+    title: "Scope Repair Before Approval",
+    statusLabel: TEXT_STATUS_LABELS[report.status] || String(report.status || "warn").toUpperCase(),
+    found: report.text?.found || "No scope mismatch detected.",
+    repaired: report.text?.repaired || "none",
+    approval: report.text?.approval || "not required",
+    safeNextAction: report.summary?.safeNextAction || "Continue with bounded work and create proof.",
+  };
+}
+
+function buildScopeRepairSurface(cwd = process.cwd(), options = {}) {
+  const report = readLatestScopeRepairReport(cwd)
+    || (options.buildIfMissing === true ? buildScopeRepairReport(cwd, { write: false }) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      showInStatus: false,
+      showInDashboard: false,
+      repairsApplied: 0,
+      approvalsAvoided: 0,
+      approvalsStillRequired: 0,
+      nextAction: "Run `avorelo scope-repair --text` when you have requested/planned scope evidence.",
+      latestReportPath: null,
+      statusLine: null,
+      dashboardCard: null,
+    };
+  }
+
+  return {
+    status: report.status,
+    showInStatus: true,
+    showInDashboard: true,
+    repairsApplied: Number(report.summary?.scopeRepairsApplied || 0),
+    approvalsAvoided: Number(report.summary?.approvalsAvoided || 0),
+    approvalsStillRequired: Number(report.summary?.approvalsStillRequired || 0),
+    nextAction: report.summary?.safeNextAction || "Continue with bounded work and create proof.",
+    latestReportPath: LATEST_REPORT_REL,
+    statusLine: `Scope repair: ${TEXT_STATUS_LABELS[report.status] || String(report.status || "warn").toUpperCase()} · repairs ${report.summary?.scopeRepairsApplied || 0} · avoided ${report.summary?.approvalsAvoided || 0} · review ${report.summary?.approvalsStillRequired || 0} · next: ${report.summary?.safeNextAction || "Continue with bounded work and create proof."}`,
+    dashboardCard: buildDashboardCard(report),
+    report,
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  REPORT_DIR_REL,
+  LATEST_REPORT_REL,
+  DECISION_TYPES,
+  buildScopeRepairReport,
+  writeScopeRepairReport,
+  generateScopeRepairReport,
+  readLatestScopeRepairReport,
+  formatScopeRepairText,
+  buildScopeRepairSurface,
+};