avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/deployment-environment-guard.js

@@ -0,0 +1,1236 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const CONTRACT = "avorelo.deploymentEnvironmentGuard.v1";
+const REPORT_DIR_REL = ".claude/cco/reports/deployment-environment-guard";
+const REPORT_JSON_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const TEXT_FILE_RE = /\.(cjs|cts|env|ini|js|json|jsx|md|mjs|mts|prisma|sql|toml|ts|tsx|txt|yaml|yml)$/i;
+const ENV_FILE_RE = /(^|\/)(\.env(?:\.[^/]+)?|env\.example)$/i;
+const ENV_EXAMPLE_RE = /(^|\/)(\.env\.(?:example|sample|local\.example|production\.example|development\.example)|env\.example)$/i;
+const WORKFLOW_RE = /^\.github\/workflows\/.+\.(yml|yaml)$/i;
+const SKIP_DIRS = new Set([
+  ".claude",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".wasp",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+]);
+
+const PUBLIC_ENV_PREFIX_RE = /^(NEXT_PUBLIC_|VITE_|PUBLIC_|REACT_APP_|EXPO_PUBLIC_)/i;
+const SECRET_LIKE_ENV_RE = /(SERVICE_ROLE|SECRET|TOKEN|API_KEY|DATABASE_URL|DB_URL|ADMIN|PRIVATE|PASSWORD|CREDENTIAL|SESSION_SECRET|JWT_SECRET|STRIPE_SECRET|SUPABASE_SERVICE_ROLE)/i;
+const DEPLOY_COMMAND_RE = /\b(deploy|release|publish|vercel|netlify|railway|fly\s+deploy|docker\s+push|gh\s+release)\b/i;
+const DEPLOY_PROVIDER_RE = /\b(vercel|netlify|railway|render|fly|docker|cloudbuild|procfile)\b/i;
+const PRODUCTION_DEPLOY_RE = /(?:--prod\b|\bproduction\b|\bdeploy:prod\b|\bdeploy:production\b|\bvercel\s+--prod\b|\bnetlify\s+deploy\s+--prod\b|\bfly\s+deploy\b|\brailway\s+up\b)/i;
+const PREVIEW_SIGNAL_RE = /\b(preview|staging|deploy-preview|branch-deploy|nonprod|non-prod)\b/i;
+const MIGRATION_COMMAND_RE = /\b(prisma\s+migrate\s+deploy|prisma\s+db\s+push|drizzle-kit\s+(push|migrate)|supabase\s+(db\s+push|migration\s+up)|db:migrate|migrate(?::deploy)?|migration)\b/i;
+const SEED_COMMAND_RE = /\b(seed|db:seed|seed:prod|supabase\s+db\s+seed)\b/i;
+const DESTRUCTIVE_COMMAND_RE = /\b(db\s+reset|drop\s+database|drop\s+table|truncate\b|delete\s+from\s+[a-z0-9_]+\s*;?$|supabase\s+db\s+reset|prisma\s+db\s+push|force\s+migration|reset:db)\b/i;
+const TEST_COMMAND_RE = /\b((npm|pnpm|yarn)\s+test|node\s+--test|vitest|jest|playwright|cypress|pytest|go\s+test|cargo\s+test)\b/i;
+const PRODUCTION_URL_RE = /\bhttps?:\/\/[A-Za-z0-9.-]+\.[A-Za-z]{2,}(?::\d+)?(?:\/[^\s"'`)]*)?/g;
+const LOCALHOST_RE = /\bhttps?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?\b/i;
+const PUSH_MAIN_RE = /\bon\s*:\s*[\s\S]{0,600}\bpush\s*:\s*[\s\S]{0,600}\bbranches\s*:\s*[\s\S]{0,300}\bmain\b/i;
+const WORKFLOW_DISPATCH_RE = /\bworkflow_dispatch\b/i;
+const PRODUCTION_ENV_RE = /\benvironment\s*:\s*production\b/i;
+const SECRET_LITERAL_RE = /["']?(?:api[_-]?key|token|password|secret|authorization|database_url)["']?\s*[:=]\s*["']?(?!\$\{\{|\$[A-Z_]+|process\.env|import\.meta\.env|<redacted>|redacted|example|sample|placeholder|changeme|replace-me|your-|test-|xxxx|dummy\b)([^\s"',}]{12,})/i;
+const URL_WITH_CREDENTIAL_RE = /\b(?:postgres(?:ql)?|mysql|https?):\/\/[^/\s:@]+:[^@\s]+@/i;
+const ROLLBACK_SIGNAL_RE = /\b(rollback|roll back|recovery|restore|revert|backup|runbook|incident|migration down)\b/i;
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function sanitizeText(value, max = 220) {
+  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|database_url)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]")
+    .replace(/\bhttps?:\/\/[^/\s:@]+:[^@\s]+@/ig, "https://[redacted]@[redacted]")
+    .trim();
+  if (!text) return null;
+  return text.length > max ? `${text.slice(0, max - 3).trimEnd()}...` : text;
+}
+
+function sanitizeRef(ref) {
+  const text = String(ref || "").trim().replace(/\\/g, "/");
+  if (!text || text.startsWith("..")) return null;
+  return text;
+}
+
+function makeEvidenceRef(relPath, lineNumber, label) {
+  const base = sanitizeRef(relPath);
+  if (!base) return null;
+  const suffix = Number.isFinite(lineNumber) && lineNumber > 0 ? `:${lineNumber}` : "";
+  const note = label ? ` (${sanitizeText(label, 80)})` : "";
+  return `${base}${suffix}${note}`;
+}
+
+function severityRank(severity) {
+  if (severity === "block") return 4;
+  if (severity === "warn") return 3;
+  if (severity === "info") return 2;
+  return 1;
+}
+
+function riskRank(risk) {
+  return {
+    none: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    blocked: 4,
+    unknown: 1,
+  }[risk] ?? 0;
+}
+
+function severityToRisk(severity) {
+  if (severity === "block") return "blocked";
+  if (severity === "warn") return "medium";
+  if (severity === "info") return "low";
+  return "none";
+}
+
+function pickHigherRisk(current, next) {
+  return riskRank(next) > riskRank(current) ? next : current;
+}
+
+function walkWorkspace(cwd) {
+  const files = [];
+
+  function visit(current, depth) {
+    if (depth > 8 || files.length >= 2400) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (files.length >= 2400) return;
+      const absPath = path.join(current, entry.name);
+      const relPath = toPosix(path.relative(cwd, absPath));
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        visit(absPath, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      files.push({
+        absPath,
+        relPath,
+        text: undefined,
+      });
+    }
+  }
+
+  visit(cwd, 0);
+  return files;
+}
+
+function readText(file) {
+  if (file.text !== undefined) return file.text;
+  if (!(
+    TEXT_FILE_RE.test(file.relPath)
+    || ENV_FILE_RE.test(file.relPath)
+    || /(^|\/)(Dockerfile|Procfile|\.dockerignore)$/i.test(file.relPath)
+  )) {
+    file.text = null;
+    return file.text;
+  }
+  try {
+    const stat = fs.statSync(file.absPath);
+    if (stat.size > 256 * 1024) {
+      file.text = null;
+      return file.text;
+    }
+    file.text = fs.readFileSync(file.absPath, "utf8");
+    return file.text;
+  } catch {
+    file.text = null;
+    return file.text;
+  }
+}
+
+function findLineNumber(text, index) {
+  return text.slice(0, index).split(/\r?\n/).length;
+}
+
+function findLineRef(file, predicate, labelFactory) {
+  const text = readText(file);
+  if (!text) return null;
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!predicate(lines[i], i + 1)) continue;
+    return makeEvidenceRef(file.relPath, i + 1, labelFactory ? labelFactory(lines[i], i + 1) : null);
+  }
+  return makeEvidenceRef(file.relPath, null, null);
+}
+
+function packageScriptRef(file, scriptName) {
+  const text = readText(file);
+  if (!text) return sanitizeRef(file.relPath);
+  const index = text.indexOf(`"${scriptName}"`);
+  if (index < 0) return makeEvidenceRef(file.relPath, null, scriptName);
+  return makeEvidenceRef(file.relPath, findLineNumber(text, index), scriptName);
+}
+
+function addSurfaceRef(list, ref) {
+  if (ref) list.push(ref);
+}
+
+function makeBaseSurface() {
+  return { risk: "none" };
+}
+
+function buildEmptyReport() {
+  return {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status: "no_data",
+    redacted: true,
+    summary: {
+      surfacesInspected: 0,
+      risksFound: 0,
+      blockers: 0,
+      needsReview: 0,
+      safeNextAction: "No local deployment or environment surface was detected. Re-run after adding deploy, CI, or environment configuration.",
+    },
+    surfaces: {
+      packageScripts: {
+        detected: false,
+        scriptRefs: [],
+        deployScripts: [],
+        migrationScripts: [],
+        risk: "none",
+      },
+      envFiles: {
+        detected: false,
+        envNameRefs: [],
+        publicSecretNameSignals: [],
+        missingExampleSignals: [],
+        risk: "none",
+      },
+      deploymentProviders: {
+        detected: false,
+        vercel: [],
+        netlify: [],
+        render: [],
+        railway: [],
+        fly: [],
+        docker: [],
+        risk: "none",
+      },
+      ciWorkflows: {
+        detected: false,
+        workflowRefs: [],
+        testBeforeDeployEvidence: [],
+        deployWithoutTestSignals: [],
+        risk: "none",
+      },
+      databaseDeployPath: {
+        detected: false,
+        migrationRefs: [],
+        seedRefs: [],
+        resetOrDestructiveSignals: [],
+        risk: "none",
+      },
+      productionRouting: {
+        detected: false,
+        productionUrlRefs: [],
+        localhostInProductionSignals: [],
+        branchOrEnvSeparationEvidence: [],
+        risk: "none",
+      },
+      rollbackRecovery: {
+        detected: false,
+        rollbackRefs: [],
+        recoveryRefs: [],
+        missingRecoverySignals: [],
+        risk: "none",
+      },
+    },
+    findings: [],
+    rollup: {
+      readySignals: [],
+      needsReview: [],
+      blockedItems: [],
+      notEnoughEvidence: [],
+    },
+    integrationRefs: {
+      productionConfidence: [REPORT_JSON_REL],
+      productHome: [REPORT_JSON_REL],
+      radar: [REPORT_JSON_REL],
+      status: [REPORT_JSON_REL],
+      dashboard: [REPORT_JSON_REL],
+      support: [REPORT_JSON_REL],
+    },
+    privacy: {
+      localOnly: true,
+      remoteFetch: false,
+      providerConnection: false,
+      deployExecuted: false,
+      buildExecuted: false,
+      migrationExecuted: false,
+      rawSecretValuesStored: false,
+      rawPromptStored: false,
+      rawCodeStored: false,
+      fullLogsStored: false,
+      privatePathsStored: false,
+      redacted: true,
+    },
+    claimSafety: {
+      deploymentVerified: false,
+      launchReadyClaim: false,
+      productionCertified: false,
+      cloudProviderScanned: false,
+      envValuesVerified: false,
+      rollbackGuaranteed: false,
+      autoFixed: false,
+    },
+  };
+}
+
+function createState() {
+  return {
+    seenFindingIds: new Set(),
+    deploymentSurfaceDetected: false,
+    previewEvidence: [],
+    productionEvidence: [],
+    rollbackEvidence: [],
+    workflowManualDispatch: [],
+    envUsageRefs: [],
+  };
+}
+
+function updateSurfaceRisk(surface, severity, overrideRisk) {
+  surface.risk = pickHigherRisk(surface.risk, overrideRisk || severityToRisk(severity));
+}
+
+function addFinding(report, state, surface, finding, riskOverride) {
+  const evidenceRef = sanitizeRef(finding.evidenceRef);
+  const key = `${finding.id}:${evidenceRef || "none"}`;
+  if (state.seenFindingIds.has(key)) return;
+  state.seenFindingIds.add(key);
+
+  const normalized = {
+    id: finding.id,
+    severity: finding.severity,
+    category: finding.category,
+    title: sanitizeText(finding.title, 120),
+    evidenceRef,
+    reasonCodes: unique(finding.reasonCodes || []),
+    safeNextAction: sanitizeText(finding.safeNextAction, 220) || "Review the local deployment path before shipping.",
+  };
+  report.findings.push(normalized);
+  if (surface) updateSurfaceRisk(surface, normalized.severity, riskOverride);
+}
+
+function addReadySignal(report, text) {
+  if (!text) return;
+  report.rollup.readySignals.push(sanitizeText(text, 220));
+}
+
+function providerSlotFor(relPath) {
+  const name = toPosix(relPath).toLowerCase();
+  if (/vercel\.json$/.test(name)) return "vercel";
+  if (/netlify\.toml$/.test(name)) return "netlify";
+  if (/render\.ya?ml$/.test(name)) return "render";
+  if (/railway\.json$/.test(name)) return "railway";
+  if (/fly\.toml$/.test(name)) return "fly";
+  if (/(^|\/)(dockerfile|docker-compose\.ya?ml|\.dockerignore)$/.test(name)) return "docker";
+  return null;
+}
+
+function configFileCandidates(files) {
+  return files.filter((file) => {
+    const rel = file.relPath;
+    return providerSlotFor(rel)
+      || WORKFLOW_RE.test(rel)
+      || /(^|\/)(procfile|app\.json|cloudbuild\.ya?ml)$/i.test(rel)
+      || /(^|\/)(scripts|deploy|infra|ops)\/.+\.(cjs|js|mjs|ps1|sh|ts|yaml|yml)$/i.test(rel)
+      || /(^|\/)package\.json$/i.test(rel);
+  });
+}
+
+function isExampleEnvFile(relPath) {
+  return ENV_EXAMPLE_RE.test(relPath);
+}
+
+function isDeployScript(name, command) {
+  return /\bdeploy\b/i.test(name) || DEPLOY_COMMAND_RE.test(command);
+}
+
+function isPreviewScript(name, command) {
+  return /\bpreview\b/i.test(name) || PREVIEW_SIGNAL_RE.test(command);
+}
+
+function isBuildScript(name, command) {
+  return /\bbuild\b/i.test(name) || /\bbuild\b/i.test(command);
+}
+
+function hasProductionDeploy(command, name) {
+  return PRODUCTION_DEPLOY_RE.test(command) || /\bdeploy:(prod|production)\b/i.test(name);
+}
+
+function isMigrationCommand(command) {
+  return MIGRATION_COMMAND_RE.test(command);
+}
+
+function isSeedCommand(command) {
+  return SEED_COMMAND_RE.test(command);
+}
+
+function isDestructiveCommand(command) {
+  return DESTRUCTIVE_COMMAND_RE.test(command);
+}
+
+function hasPublishSignal(command) {
+  return /\bnpm\s+publish\b|\bgh\s+release\b/i.test(command);
+}
+
+function isWorkflowDeployActionLine(line) {
+  if (PRODUCTION_ENV_RE.test(line)) return true;
+  return /\b(run|command)\s*:\s*.*\b(deploy|release|publish|vercel|netlify|railway|fly\s+deploy|docker\s+push|gh\s+release)\b/i.test(line)
+    || /\buses\s*:\s*.*\b(vercel|netlify|railway|fly|docker)\b/i.test(line);
+}
+
+function extractEnvUsageRefs(files) {
+  const refs = [];
+  for (const file of files) {
+    const text = readText(file);
+    if (!text || /\.md$/i.test(file.relPath)) continue;
+    const matcher = /\b(?:process\.env|import\.meta\.env)\.([A-Z0-9_]+)\b/g;
+    let match;
+    while ((match = matcher.exec(text)) && refs.length < 24) {
+      refs.push({
+        name: match[1],
+        ref: makeEvidenceRef(file.relPath, findLineNumber(text, match.index), match[1]),
+      });
+      if (match.index === matcher.lastIndex) matcher.lastIndex += 1;
+    }
+  }
+  return refs;
+}
+
+function detectPackageScripts(report, state, files) {
+  const surface = report.surfaces.packageScripts;
+  const dbSurface = report.surfaces.databaseDeployPath;
+  const routingSurface = report.surfaces.productionRouting;
+
+  for (const file of files.filter((item) => /(^|\/)package\.json$/i.test(item.relPath))) {
+    const text = readText(file);
+    if (!text) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(text);
+    } catch {
+      continue;
+    }
+
+    const scripts = manifest && typeof manifest.scripts === "object" ? manifest.scripts : null;
+    if (!scripts || Object.keys(scripts).length === 0) continue;
+    surface.detected = true;
+
+    for (const [name, rawValue] of Object.entries(scripts)) {
+      if (typeof rawValue !== "string") continue;
+      const value = rawValue.trim();
+      const lowerName = String(name || "").toLowerCase();
+      const ref = packageScriptRef(file, name);
+      addSurfaceRef(surface.scriptRefs, ref);
+      if (isBuildScript(lowerName, value)) {
+        state.deploymentSurfaceDetected = true;
+      }
+
+      const deployScript = isDeployScript(lowerName, value);
+      const previewScript = isPreviewScript(lowerName, value);
+      const productionDeploy = hasProductionDeploy(value, lowerName);
+      const migrationScript = isMigrationCommand(value);
+      const seedScript = isSeedCommand(value);
+      const destructive = isDestructiveCommand(value);
+      const publishSignal = hasPublishSignal(value);
+
+      if (deployScript) {
+        state.deploymentSurfaceDetected = true;
+        surface.detected = true;
+        addSurfaceRef(surface.deployScripts, ref);
+      }
+      if (previewScript) {
+        state.previewEvidence.push(ref);
+        addReadySignal(report, "Preview or staging script evidence is present.");
+      }
+      if (productionDeploy) {
+        state.productionEvidence.push(ref);
+      }
+      if (migrationScript) {
+        dbSurface.detected = true;
+        addSurfaceRef(surface.migrationScripts, ref);
+        addSurfaceRef(dbSurface.migrationRefs, ref);
+      }
+      if (seedScript) {
+        dbSurface.detected = true;
+        addSurfaceRef(dbSurface.seedRefs, ref);
+      }
+      if (destructive) {
+        dbSurface.detected = true;
+        addSurfaceRef(dbSurface.resetOrDestructiveSignals, ref);
+      }
+      if (PRODUCTION_URL_RE.test(value)) {
+        routingSurface.detected = true;
+        addSurfaceRef(routingSurface.productionUrlRefs, ref);
+      }
+      PRODUCTION_URL_RE.lastIndex = 0;
+
+      if (deployScript && lowerName === "deploy" && productionDeploy) {
+        addFinding(report, state, surface, {
+          id: "default_production_deploy",
+          severity: "block",
+          category: "package_script",
+          title: "Default deploy script targets production",
+          evidenceRef: ref,
+          reasonCodes: [
+            "package_scripts_detected",
+            "deploy_script_detected",
+            "production_deploy_script_detected",
+            "blocked_deployment_risk",
+            "safe_next_action_available",
+          ],
+          safeNextAction: "Make preview or staging the default deploy path and keep production deploy explicit and reviewed.",
+        });
+      } else if (deployScript && productionDeploy) {
+        addFinding(report, state, surface, {
+          id: "explicit_production_deploy",
+          severity: "warn",
+          category: "package_script",
+          title: "Production deploy script is present locally",
+          evidenceRef: ref,
+          reasonCodes: [
+            "package_scripts_detected",
+            "deploy_script_detected",
+            "production_deploy_script_detected",
+            "safe_next_action_available",
+          ],
+          safeNextAction: "Keep production deploy explicit and add preview, test, and rollback evidence before shipping.",
+        });
+      } else if (deployScript) {
+        addFinding(report, state, surface, {
+          id: "deploy_target_unclear",
+          severity: "warn",
+          category: "package_script",
+          title: "Deploy script target is not clearly separated",
+          evidenceRef: ref,
+          reasonCodes: [
+            "package_scripts_detected",
+            "deploy_script_detected",
+            "preview_production_separation_unclear",
+            "not_enough_evidence",
+          ],
+          safeNextAction: "Make preview versus production targets explicit in local deploy scripts before shipping.",
+        });
+      }
+
+      if (deployScript && migrationScript) {
+        addFinding(report, state, dbSurface, {
+          id: productionDeploy ? "deploy_migration_coupling_prod" : "deploy_migration_coupling",
+          severity: destructive ? "block" : "warn",
+          category: "migration",
+          title: destructive
+            ? "Production deploy path includes risky database mutation commands"
+            : "Deploy path is coupled to database migration commands",
+          evidenceRef: ref,
+          reasonCodes: [
+            "migration_script_detected",
+            "deploy_migration_coupling_detected",
+            ...(destructive ? ["destructive_db_command_detected", "blocked_deployment_risk"] : []),
+          ],
+          safeNextAction: destructive
+            ? "Remove destructive database commands from deploy-time scripts and keep database review separate from deploy."
+            : "Split migration steps from deploy commands and review them separately before shipping.",
+        }, destructive ? "blocked" : productionDeploy ? "high" : "medium");
+      }
+
+      if (deployScript && seedScript) {
+        addFinding(report, state, dbSurface, {
+          id: productionDeploy ? "deploy_seed_coupling_prod" : "deploy_seed_coupling",
+          severity: productionDeploy ? "block" : "warn",
+          category: "seed",
+          title: productionDeploy
+            ? "Production deploy path includes seeding"
+            : "Deploy path is coupled to a seed command",
+          evidenceRef: ref,
+          reasonCodes: [
+            "seed_script_detected",
+            "deploy_seed_coupling_detected",
+            ...(productionDeploy ? ["blocked_deployment_risk"] : []),
+          ],
+          safeNextAction: "Keep seed commands out of production deploy paths and run them through a separately reviewed workflow.",
+        }, productionDeploy ? "blocked" : "medium");
+      }
+
+      if (deployScript && destructive) {
+        addFinding(report, state, dbSurface, {
+          id: "destructive_db_in_deploy_script",
+          severity: "block",
+          category: "migration",
+          title: "Deploy path includes destructive database commands",
+          evidenceRef: ref,
+          reasonCodes: [
+            "destructive_db_command_detected",
+            "blocked_deployment_risk",
+            "deploy_script_detected",
+          ],
+          safeNextAction: "Remove reset, drop, truncate, or unsafe db push commands from deploy-time scripts before shipping.",
+        }, "blocked");
+      }
+
+      if (deployScript && publishSignal) {
+        addFinding(report, state, surface, {
+          id: "publish_in_deploy_path",
+          severity: "block",
+          category: "package_script",
+          title: "Deploy path mixes app deployment with package publishing",
+          evidenceRef: ref,
+          reasonCodes: [
+            "deploy_script_detected",
+            "npm_publish_script_detected",
+            "blocked_deployment_risk",
+          ],
+          safeNextAction: "Separate package publishing or release commands from the app deploy path before shipping.",
+        }, "blocked");
+      }
+    }
+  }
+
+  surface.scriptRefs = unique(surface.scriptRefs);
+  surface.deployScripts = unique(surface.deployScripts);
+  surface.migrationScripts = unique(surface.migrationScripts);
+  dbSurface.migrationRefs = unique(dbSurface.migrationRefs);
+  dbSurface.seedRefs = unique(dbSurface.seedRefs);
+  dbSurface.resetOrDestructiveSignals = unique(dbSurface.resetOrDestructiveSignals);
+}
+
+function detectEnvFiles(report, state, files) {
+  const surface = report.surfaces.envFiles;
+  const envUsageRefs = extractEnvUsageRefs(files);
+  state.envUsageRefs = envUsageRefs;
+  const envFiles = files.filter((file) => ENV_FILE_RE.test(file.relPath));
+  const exampleFiles = envFiles.filter((file) => isExampleEnvFile(file.relPath));
+
+  if (envFiles.length === 0 && envUsageRefs.length === 0) {
+    return;
+  }
+
+  surface.detected = true;
+  const nameRefs = [];
+  const publicSecretRefs = [];
+
+  for (const file of envFiles) {
+    const text = readText(file);
+    if (!text) continue;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+      const match = lines[i].match(/^\s*([A-Z0-9_]+)\s*=/);
+      if (!match) continue;
+      const name = match[1];
+      const ref = makeEvidenceRef(file.relPath, i + 1, name);
+      nameRefs.push(ref);
+      if (PUBLIC_ENV_PREFIX_RE.test(name) && SECRET_LIKE_ENV_RE.test(name)) {
+        publicSecretRefs.push(ref);
+      }
+    }
+  }
+
+  for (const item of envUsageRefs) {
+    if (!item || !item.name || !item.ref) continue;
+    if (PUBLIC_ENV_PREFIX_RE.test(item.name) && SECRET_LIKE_ENV_RE.test(item.name)) {
+      publicSecretRefs.push(item.ref);
+    }
+  }
+
+  surface.envNameRefs = unique(nameRefs).slice(0, 12);
+  surface.publicSecretNameSignals = unique(publicSecretRefs).slice(0, 8);
+
+  if (surface.publicSecretNameSignals.length > 0) {
+    addFinding(report, state, surface, {
+      id: "public_secret_like_env_name",
+      severity: "block",
+      category: "env",
+      title: "Public or client env names expose secret-like variables",
+      evidenceRef: surface.publicSecretNameSignals[0],
+      reasonCodes: [
+        "env_file_detected",
+        "public_env_prefix_detected",
+        "public_secret_like_name_detected",
+        "blocked_deployment_risk",
+      ],
+      safeNextAction: "Move secret-like variables out of public or client env prefixes before shipping.",
+    }, "blocked");
+  }
+
+  if (envUsageRefs.length > 0 && exampleFiles.length === 0) {
+    surface.missingExampleSignals = unique(envUsageRefs.map((item) => item.ref)).slice(0, 6);
+    addFinding(report, state, surface, {
+      id: "env_example_missing",
+      severity: "warn",
+      category: "env",
+      title: "Environment variables are used without a clear example file",
+      evidenceRef: surface.missingExampleSignals[0],
+      reasonCodes: [
+        "env_example_missing_or_unclear",
+        "not_enough_evidence",
+      ],
+      safeNextAction: "Add a redacted example env file that documents safe variable names before shipping.",
+    }, "medium");
+  } else if (exampleFiles.length > 0) {
+    addReadySignal(report, "Example env files are present for local deployment setup.");
+  }
+
+  surface.missingExampleSignals = unique(surface.missingExampleSignals);
+}
+
+function detectProviderAndRoutingSignals(report, state, files) {
+  const providerSurface = report.surfaces.deploymentProviders;
+  const routingSurface = report.surfaces.productionRouting;
+
+  for (const file of configFileCandidates(files)) {
+    const slot = providerSlotFor(file.relPath);
+    if (slot) {
+      providerSurface.detected = true;
+      providerSurface[slot].push(sanitizeRef(file.relPath));
+      state.deploymentSurfaceDetected = true;
+    }
+
+    const text = readText(file);
+    if (!text) continue;
+    const lines = text.split(/\r?\n/);
+
+    let providerHadSeparation = false;
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+
+      if (PUBLIC_ENV_PREFIX_RE.test(line) && SECRET_LIKE_ENV_RE.test(line)) {
+        const ref = makeEvidenceRef(file.relPath, i + 1, "public-secret-like-env");
+        addFinding(report, state, providerSurface, {
+          id: "provider_public_secret_env_name",
+          severity: "block",
+          category: "provider_config",
+          title: "Deployment config references public secret-like env names",
+          evidenceRef: ref,
+          reasonCodes: [
+            "provider_config_detected",
+            "public_env_prefix_detected",
+            "public_secret_like_name_detected",
+            "blocked_deployment_risk",
+          ],
+          safeNextAction: "Remove secret-like public env names from deploy or provider config before shipping.",
+        }, "blocked");
+      }
+
+      if (SECRET_LITERAL_RE.test(line) || URL_WITH_CREDENTIAL_RE.test(line)) {
+        const ref = makeEvidenceRef(file.relPath, i + 1, "secret-literal");
+        addFinding(report, state, providerSurface, {
+          id: "provider_secret_literal",
+          severity: "block",
+          category: slot === "docker" ? "docker" : "provider_config",
+          title: "Provider or deploy config appears to contain a committed secret-like literal",
+          evidenceRef: ref,
+          reasonCodes: [
+            ...(slot ? [`${slot}_config_detected`] : ["provider_config_detected"]),
+            "secret_value_literal_detected",
+            "blocked_deployment_risk",
+          ],
+          safeNextAction: "Replace committed secret-like literals with environment references before shipping.",
+        }, "blocked");
+      }
+      SECRET_LITERAL_RE.lastIndex = 0;
+      URL_WITH_CREDENTIAL_RE.lastIndex = 0;
+
+      const urlMatches = [...line.matchAll(PRODUCTION_URL_RE)];
+      if (urlMatches.length > 0 && !LOCALHOST_RE.test(line)) {
+        const ref = makeEvidenceRef(file.relPath, i + 1, "production-url");
+        routingSurface.detected = true;
+        routingSurface.productionUrlRefs.push(ref);
+        addFinding(report, state, routingSurface, {
+          id: "production_url_detected_local",
+          severity: "warn",
+          category: "production_route",
+          title: "Production URL is hardcoded in local deploy or config files",
+          evidenceRef: ref,
+          reasonCodes: [
+            "production_url_detected",
+            "safe_next_action_available",
+          ],
+          safeNextAction: "Move production URLs behind explicit environment separation and review the default target before shipping.",
+        }, "medium");
+      }
+
+      if (LOCALHOST_RE.test(line) && /\bproduction\b/i.test(text)) {
+        const ref = makeEvidenceRef(file.relPath, i + 1, "localhost-in-production");
+        routingSurface.detected = true;
+        routingSurface.localhostInProductionSignals.push(ref);
+        addFinding(report, state, routingSurface, {
+          id: "localhost_in_production",
+          severity: "warn",
+          category: "production_route",
+          title: "Production config appears to reference localhost",
+          evidenceRef: ref,
+          reasonCodes: [
+            "localhost_in_production_config",
+            "safe_next_action_available",
+          ],
+          safeNextAction: "Remove localhost targets from production-oriented config and keep preview and production routing separate.",
+        }, "medium");
+      }
+
+      if (PREVIEW_SIGNAL_RE.test(line) && /\bproduction\b/i.test(text)) {
+        const ref = makeEvidenceRef(file.relPath, i + 1, "preview-production-separation");
+        providerHadSeparation = true;
+        routingSurface.detected = true;
+        routingSurface.branchOrEnvSeparationEvidence.push(ref);
+        state.previewEvidence.push(ref);
+      }
+    }
+
+    if (providerHadSeparation) {
+      addReadySignal(report, "Provider or deploy config shows preview versus production separation evidence.");
+    }
+  }
+
+  providerSurface.vercel = unique(providerSurface.vercel);
+  providerSurface.netlify = unique(providerSurface.netlify);
+  providerSurface.render = unique(providerSurface.render);
+  providerSurface.railway = unique(providerSurface.railway);
+  providerSurface.fly = unique(providerSurface.fly);
+  providerSurface.docker = unique(providerSurface.docker);
+  routingSurface.productionUrlRefs = unique(routingSurface.productionUrlRefs);
+  routingSurface.localhostInProductionSignals = unique(routingSurface.localhostInProductionSignals);
+  routingSurface.branchOrEnvSeparationEvidence = unique(routingSurface.branchOrEnvSeparationEvidence);
+
+  if (providerSurface.detected && routingSurface.branchOrEnvSeparationEvidence.length === 0) {
+    addFinding(report, state, providerSurface, {
+      id: "provider_separation_unclear",
+      severity: "warn",
+      category: "provider_config",
+      title: "Deployment provider config lacks clear preview or production separation evidence",
+      evidenceRef: providerSurface.vercel[0]
+        || providerSurface.netlify[0]
+        || providerSurface.render[0]
+        || providerSurface.railway[0]
+        || providerSurface.fly[0]
+        || providerSurface.docker[0]
+        || null,
+      reasonCodes: [
+        "provider_config_detected",
+        "preview_production_separation_unclear",
+        "not_enough_evidence",
+      ],
+      safeNextAction: "Document or encode preview versus production separation in local provider config before shipping.",
+    }, "medium");
+  }
+}
+
+function detectCiWorkflows(report, state, files) {
+  const surface = report.surfaces.ciWorkflows;
+
+  for (const file of files.filter((item) => WORKFLOW_RE.test(item.relPath))) {
+    surface.detected = true;
+    state.deploymentSurfaceDetected = true;
+    addSurfaceRef(surface.workflowRefs, sanitizeRef(file.relPath));
+
+    const text = readText(file);
+    if (!text) continue;
+    const lines = text.split(/\r?\n/);
+
+    let firstDeployLine = null;
+    let firstTestLine = null;
+    let hasDeploy = false;
+    let hasManualDispatch = WORKFLOW_DISPATCH_RE.test(text);
+
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (firstTestLine === null && TEST_COMMAND_RE.test(line)) {
+        firstTestLine = i + 1;
+      }
+      if (firstDeployLine === null && isWorkflowDeployActionLine(line)) {
+        firstDeployLine = i + 1;
+      }
+      if (isWorkflowDeployActionLine(line)) {
+        hasDeploy = true;
+      }
+    }
+
+    if (!hasDeploy) continue;
+
+    const deployRef = makeEvidenceRef(file.relPath, firstDeployLine, "deploy-workflow");
+    const testBeforeDeploy = firstTestLine !== null && firstDeployLine !== null && firstTestLine < firstDeployLine;
+
+    if (testBeforeDeploy) {
+      surface.testBeforeDeployEvidence.push(makeEvidenceRef(file.relPath, firstTestLine, "test-before-deploy"));
+      addReadySignal(report, "CI workflow shows test-before-deploy evidence.");
+    } else {
+      surface.deployWithoutTestSignals.push(deployRef);
+    }
+
+    if (hasManualDispatch) {
+      state.workflowManualDispatch.push(sanitizeRef(file.relPath));
+      addReadySignal(report, "CI workflow includes a manual dispatch path for bounded review.");
+    }
+
+    const pushMainProduction = PUSH_MAIN_RE.test(text) && (PRODUCTION_ENV_RE.test(text) || PRODUCTION_DEPLOY_RE.test(text));
+    if (pushMainProduction && !testBeforeDeploy) {
+      addFinding(report, state, surface, {
+        id: "push_main_production_without_tests",
+        severity: "block",
+        category: "ci",
+        title: "CI appears to deploy to production on push to main without test-before-deploy evidence",
+        evidenceRef: deployRef,
+        reasonCodes: [
+          "ci_workflow_detected",
+          "deploy_workflow_detected",
+          "push_main_production_deploy_detected",
+          "deploy_without_test_evidence",
+          "blocked_deployment_risk",
+        ],
+        safeNextAction: "Require tests before deploy and avoid direct push-to-main production deploys without bounded review evidence.",
+      }, "blocked");
+    } else if (!testBeforeDeploy) {
+      addFinding(report, state, surface, {
+        id: "deploy_without_tests",
+        severity: "warn",
+        category: "ci",
+        title: "Deploy workflow does not show test-before-deploy evidence",
+        evidenceRef: deployRef,
+        reasonCodes: [
+          "ci_workflow_detected",
+          "deploy_workflow_detected",
+          "deploy_without_test_evidence",
+          "not_enough_evidence",
+        ],
+        safeNextAction: "Add explicit test steps before deploy in CI before treating the deploy path as safer to ship.",
+      }, "medium");
+    }
+  }
+
+  surface.workflowRefs = unique(surface.workflowRefs);
+  surface.testBeforeDeployEvidence = unique(surface.testBeforeDeployEvidence);
+  surface.deployWithoutTestSignals = unique(surface.deployWithoutTestSignals);
+}
+
+function detectDatabaseAndRollback(report, state, files) {
+  const dbSurface = report.surfaces.databaseDeployPath;
+  const rollbackSurface = report.surfaces.rollbackRecovery;
+
+  for (const file of files) {
+    const rel = file.relPath;
+    const text = readText(file);
+    if (!text) continue;
+    const lowerRel = rel.toLowerCase();
+
+    if (/(\brollback\b|\brecovery\b|\brunbook\b|\brestore\b|\brevert\b)/i.test(rel) || ROLLBACK_SIGNAL_RE.test(text)) {
+      rollbackSurface.detected = true;
+      const ref = findLineRef(file, (line) => ROLLBACK_SIGNAL_RE.test(line), () => "rollback-recovery") || sanitizeRef(rel);
+      if (/\brollback|roll back|revert|restore\b/i.test(text) || /\brollback|revert\b/i.test(rel)) {
+        rollbackSurface.rollbackRefs.push(ref);
+      }
+      if (/\brecovery|runbook|incident|backup\b/i.test(text) || /\brecovery|runbook|incident\b/i.test(rel)) {
+        rollbackSurface.recoveryRefs.push(ref);
+      }
+      state.rollbackEvidence.push(ref);
+    }
+
+    if (/^(.+\/)?(scripts|deploy|infra|ops)\//i.test(lowerRel) || WORKFLOW_RE.test(rel) || /(^|\/)package\.json$/i.test(rel)) {
+      const lines = text.split(/\r?\n/);
+      for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (MIGRATION_COMMAND_RE.test(line)) {
+          dbSurface.detected = true;
+          dbSurface.migrationRefs.push(makeEvidenceRef(rel, i + 1, "migration-command"));
+        }
+        if (SEED_COMMAND_RE.test(line)) {
+          dbSurface.detected = true;
+          dbSurface.seedRefs.push(makeEvidenceRef(rel, i + 1, "seed-command"));
+        }
+        if (DESTRUCTIVE_COMMAND_RE.test(line)) {
+          dbSurface.detected = true;
+          dbSurface.resetOrDestructiveSignals.push(makeEvidenceRef(rel, i + 1, "destructive-db-command"));
+        }
+      }
+    }
+  }
+
+  rollbackSurface.rollbackRefs = unique(rollbackSurface.rollbackRefs);
+  rollbackSurface.recoveryRefs = unique(rollbackSurface.recoveryRefs);
+  dbSurface.migrationRefs = unique(dbSurface.migrationRefs);
+  dbSurface.seedRefs = unique(dbSurface.seedRefs);
+  dbSurface.resetOrDestructiveSignals = unique(dbSurface.resetOrDestructiveSignals);
+
+  if (dbSurface.resetOrDestructiveSignals.length > 0) {
+    addFinding(report, state, dbSurface, {
+      id: "destructive_db_signal_detected",
+      severity: "block",
+      category: "migration",
+      title: "Destructive database commands are present near the deploy path",
+      evidenceRef: dbSurface.resetOrDestructiveSignals[0],
+      reasonCodes: [
+        "destructive_db_command_detected",
+        "blocked_deployment_risk",
+      ],
+      safeNextAction: "Remove destructive database commands from deploy-adjacent scripts or workflows before shipping.",
+    }, "blocked");
+  } else if (dbSurface.detected && (dbSurface.migrationRefs.length > 0 || dbSurface.seedRefs.length > 0)) {
+    const evidenceRef = dbSurface.migrationRefs[0] || dbSurface.seedRefs[0] || null;
+    addFinding(report, state, dbSurface, {
+      id: "database_deploy_path_review",
+      severity: "warn",
+      category: dbSurface.seedRefs.length > 0 ? "seed" : "migration",
+      title: "Database mutation commands appear near the deploy path",
+      evidenceRef,
+      reasonCodes: [
+        ...(dbSurface.migrationRefs.length > 0 ? ["migration_script_detected"] : []),
+        ...(dbSurface.seedRefs.length > 0 ? ["seed_script_detected"] : []),
+        "not_enough_evidence",
+      ],
+      safeNextAction: "Review database migration and seed steps separately from deploy commands before shipping.",
+    }, "medium");
+  }
+
+  if (state.deploymentSurfaceDetected && state.rollbackEvidence.length === 0) {
+    rollbackSurface.detected = true;
+    rollbackSurface.missingRecoverySignals.push(
+      report.surfaces.packageScripts.deployScripts[0]
+      || report.surfaces.ciWorkflows.workflowRefs[0]
+      || report.surfaces.deploymentProviders.vercel[0]
+      || report.surfaces.deploymentProviders.netlify[0]
+      || report.surfaces.deploymentProviders.render[0]
+      || report.surfaces.deploymentProviders.railway[0]
+      || report.surfaces.deploymentProviders.fly[0]
+      || report.surfaces.deploymentProviders.docker[0]
+      || null
+    );
+    addFinding(report, state, rollbackSurface, {
+      id: "rollback_evidence_missing",
+      severity: "warn",
+      category: "rollback",
+      title: "Deployment surfaces exist without local rollback or recovery evidence",
+      evidenceRef: rollbackSurface.missingRecoverySignals[0],
+      reasonCodes: [
+        "rollback_evidence_missing",
+        "not_enough_evidence",
+      ],
+      safeNextAction: "Add a compact rollback or recovery note before treating the deploy path as safer to ship.",
+    }, "medium");
+  } else if (state.rollbackEvidence.length > 0) {
+    addReadySignal(report, "Rollback or recovery evidence is present locally.");
+  }
+
+  rollbackSurface.missingRecoverySignals = unique(rollbackSurface.missingRecoverySignals);
+}
+
+function finalizeReport(report, state) {
+  const findings = report.findings.sort((a, b) => severityRank(b.severity) - severityRank(a.severity));
+  report.findings = findings;
+
+  report.rollup.readySignals = unique(report.rollup.readySignals).filter(Boolean).slice(0, 8);
+  report.rollup.needsReview = unique(findings.filter((item) => item.severity === "warn").map((item) => item.title)).filter(Boolean).slice(0, 8);
+  report.rollup.blockedItems = unique(findings.filter((item) => item.severity === "block").map((item) => item.title)).filter(Boolean).slice(0, 8);
+  report.rollup.notEnoughEvidence = unique(findings
+    .filter((item) => item.reasonCodes.includes("not_enough_evidence") || item.reasonCodes.includes("preview_production_separation_unclear") || item.reasonCodes.includes("rollback_evidence_missing") || item.reasonCodes.includes("env_example_missing_or_unclear"))
+    .map((item) => item.title))
+    .filter(Boolean)
+    .slice(0, 8);
+
+  report.surfaces.packageScripts.scriptRefs = unique(report.surfaces.packageScripts.scriptRefs).slice(0, 12);
+  report.surfaces.packageScripts.deployScripts = unique(report.surfaces.packageScripts.deployScripts).slice(0, 8);
+  report.surfaces.packageScripts.migrationScripts = unique(report.surfaces.packageScripts.migrationScripts).slice(0, 8);
+  report.surfaces.envFiles.envNameRefs = unique(report.surfaces.envFiles.envNameRefs).slice(0, 12);
+  report.surfaces.envFiles.publicSecretNameSignals = unique(report.surfaces.envFiles.publicSecretNameSignals).slice(0, 8);
+  report.surfaces.envFiles.missingExampleSignals = unique(report.surfaces.envFiles.missingExampleSignals).slice(0, 8);
+
+  const detectedSurfaces = Object.values(report.surfaces).filter((surface) => surface.detected).length;
+  const blockers = findings.filter((item) => item.severity === "block").length;
+  const needsReview = findings.filter((item) => item.severity === "warn").length;
+
+  report.summary.surfacesInspected = detectedSurfaces;
+  report.summary.risksFound = findings.length;
+  report.summary.blockers = blockers;
+  report.summary.needsReview = needsReview;
+
+  if (detectedSurfaces === 0) {
+    report.status = "no_data";
+    report.summary.safeNextAction = "No local deployment or environment surface was detected. Re-run after adding deploy, CI, or environment configuration.";
+    return report;
+  }
+
+  if (blockers > 0) {
+    report.status = "blocked";
+  } else if (needsReview > 0) {
+    report.status = "warn";
+  } else {
+    report.status = "pass";
+  }
+
+  const nextFinding = findings.find((item) => item.severity === "block")
+    || findings.find((item) => item.severity === "warn");
+  report.summary.safeNextAction = nextFinding
+    ? nextFinding.safeNextAction
+    : "Keep preview or production separation, test-before-deploy evidence, and rollback guidance current before shipping.";
+  return report;
+}
+
+function buildDeploymentEnvironmentGuard(cwd = process.cwd(), options = {}) {
+  const files = walkWorkspace(cwd);
+  const report = buildEmptyReport();
+  const state = createState();
+
+  detectPackageScripts(report, state, files);
+  detectEnvFiles(report, state, files);
+  detectProviderAndRoutingSignals(report, state, files);
+  detectCiWorkflows(report, state, files);
+  detectDatabaseAndRollback(report, state, files);
+
+  if (report.surfaces.productionRouting.branchOrEnvSeparationEvidence.length > 0) {
+    report.surfaces.productionRouting.detected = true;
+    updateSurfaceRisk(report.surfaces.productionRouting, "info", "low");
+  }
+  if (report.surfaces.ciWorkflows.testBeforeDeployEvidence.length > 0 && report.surfaces.ciWorkflows.deployWithoutTestSignals.length === 0) {
+    updateSurfaceRisk(report.surfaces.ciWorkflows, "info", "low");
+  }
+  if (report.surfaces.rollbackRecovery.rollbackRefs.length > 0 || report.surfaces.rollbackRecovery.recoveryRefs.length > 0) {
+    updateSurfaceRisk(report.surfaces.rollbackRecovery, "info", "low");
+  }
+  if (report.surfaces.envFiles.detected && report.surfaces.envFiles.publicSecretNameSignals.length === 0 && report.surfaces.envFiles.missingExampleSignals.length === 0) {
+    updateSurfaceRisk(report.surfaces.envFiles, "info", "low");
+  }
+  if (report.surfaces.deploymentProviders.detected && report.surfaces.productionRouting.branchOrEnvSeparationEvidence.length > 0) {
+    updateSurfaceRisk(report.surfaces.deploymentProviders, "info", "low");
+  }
+
+  finalizeReport(report, state);
+
+  if (options.write !== false) {
+    safeWriteJson(cwd, REPORT_JSON_REL, report);
+  }
+  return report;
+}
+
+function generateDeploymentEnvironmentGuard(cwd = process.cwd(), options = {}) {
+  const report = buildDeploymentEnvironmentGuard(cwd, options);
+  return {
+    report,
+    reportPath: path.join(cwd, REPORT_JSON_REL),
+  };
+}
+
+function loadDeploymentEnvironmentGuard(cwd = process.cwd()) {
+  return safeReadJson(cwd, REPORT_JSON_REL, null);
+}
+
+function formatDeploymentEnvironmentGuardText(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return [
+      "Avorelo Deployment & Environment Guard",
+      "Status: NO DATA",
+      "No local deployment or environment surface was detected yet.",
+      "Safe next action: Re-run after adding deploy, CI, or environment configuration.",
+    ].join("\n");
+  }
+
+  const lines = [
+    "Avorelo Deployment & Environment Guard",
+    `Status: ${String(report.status || "no_data").replace(/_/g, " ").toUpperCase()} · redacted=${report.redacted === true ? "yes" : "no"}`,
+    `Surfaces: ${report.summary?.surfacesInspected || 0} · risks=${report.summary?.risksFound || 0} · blockers=${report.summary?.blockers || 0} · review=${report.summary?.needsReview || 0}`,
+    "Notes: local static scan only · no provider connection · no deploy/build/migration execution",
+  ];
+
+  const findings = Array.isArray(report.findings) ? report.findings.slice(0, 5) : [];
+  if (findings.length > 0) {
+    lines.push("");
+    lines.push("Findings:");
+    for (const finding of findings) {
+      lines.push(`- [${finding.severity}] ${finding.title}${finding.evidenceRef ? ` · ${finding.evidenceRef}` : ""}`);
+    }
+  }
+
+  if (Array.isArray(report.rollup?.readySignals) && report.rollup.readySignals.length > 0) {
+    lines.push("");
+    lines.push("Evidence:");
+    for (const item of report.rollup.readySignals.slice(0, 3)) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(`Safe next action: ${report.summary?.safeNextAction || "Review the local deployment path before shipping."}`);
+  return lines.join("\n");
+}
+
+function formatDeploymentEnvironmentGuardStatusLineFromReport(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return "Deployment guard: NOT RUN · run `avorelo deployment-guard --text`";
+  }
+  return `Deployment guard: ${String(report.status || "no_data").replace(/_/g, " ").toUpperCase()}`
+    + ` · blockers=${report.summary?.blockers || 0}`
+    + ` · review=${report.summary?.needsReview || 0}`
+    + ` · next: ${sanitizeText(report.summary?.safeNextAction, 140) || "Review the local deployment path before shipping."}`;
+}
+
+function buildDeploymentEnvironmentGuardSurface(cwd = process.cwd(), options = {}) {
+  const report = loadDeploymentEnvironmentGuard(cwd) || (options.buildIfMissing ? buildDeploymentEnvironmentGuard(cwd, { write: false }) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      blockerCount: 0,
+      needsReviewCount: 0,
+      surfacesInspected: 0,
+      nextBestAction: "Run `avorelo deployment-guard --text` before treating a local deploy path as safe to ship.",
+      statusLine: "Deployment guard: NOT RUN · run `avorelo deployment-guard --text`",
+      showInStatus: true,
+      showInDashboard: true,
+      evidenceRef: null,
+      limitations: [
+        "Local static scan only. No live deploy or provider connection.",
+      ],
+    };
+  }
+
+  return {
+    status: report.status,
+    blockerCount: report.summary?.blockers || 0,
+    needsReviewCount: report.summary?.needsReview || 0,
+    surfacesInspected: report.summary?.surfacesInspected || 0,
+    nextBestAction: report.summary?.safeNextAction,
+    statusLine: formatDeploymentEnvironmentGuardStatusLineFromReport(report),
+    showInStatus: true,
+    showInDashboard: true,
+    evidenceRef: REPORT_JSON_REL,
+    limitations: [
+      "Local static scan only. No live deploy or provider connection.",
+      "No deploy, build, migration, or provider API execution happens in this guard.",
+    ],
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  REPORT_JSON_REL,
+  buildDeploymentEnvironmentGuard,
+  generateDeploymentEnvironmentGuard,
+  loadDeploymentEnvironmentGuard,
+  formatDeploymentEnvironmentGuardText,
+  formatDeploymentEnvironmentGuardStatusLineFromReport,
+  buildDeploymentEnvironmentGuardSurface,
+};