infraweaver 0.1.0

package/src/mcp/guardrails.ts

@@ -0,0 +1,771 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { COST_FILE, PRODUCT_NAME } from "#app/brand";
+import { groupIdFromBranch } from "#app/mcp/staleFix";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import type { ToolState } from "#app/toolState";
+import { log } from "#app/utils/cli";
+import type { OctokitWithPlugins } from "#app/utils/github";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { RunContextData } from "#app/utils/runContextData";
+import { resolveEnv } from "#app/utils/secrets";
+import { $ } from "#app/utils/shell";
+import { resolveToolSelection } from "#app/utils/toolSelection";
+
+/**
+ * The narrow context the push-time guardrails read: the payload (allow-lists,
+ * tool selection, protected paths, PR caps), the tool state (selected mode,
+ * run-start baseline, recorded plan verdicts), and tmpdir (a gitleaks report
+ * lands here). No GitHub/git tokens — these gates inspect local state + the local
+ * git tree, so both `GitToolContext` and the GitHub write context satisfy them.
+ */
+export interface GuardrailContext {
+  payload: ResolvedPayload;
+  toolState: ToolState;
+  tmpdir: string;
+}
+
+/**
+ * The cross-run open-PR flood guard additionally needs the GitHub client + repo
+ * coordinates to count PRs the run can't see in local state. Only
+ * {@link assertUnderOpenPrCaps} requires it; the pure push-time gates take the
+ * narrower {@link GuardrailContext}.
+ */
+export interface OpenPrCapContext extends GuardrailContext {
+  octokit: OctokitWithPlugins;
+  repo: RunContextData["repo"];
+}
+
+/**
+ * Terraform-write guardrails — hard, code-level limits that back the prompt
+ * rules of the modes that write Terraform and open PRs (**Remediate** and the
+ * **RefreshRemediation** sweep). They only engage for those modes, so every other
+ * mode (Build, Fix, Review, …) is completely unaffected.
+ */
+
+export const REMEDIATE_MODE = "Remediate";
+/** the stale-fix self-healing sweep re-derives + force-updates remediation
+ * PRs, so it writes Terraform and pushes exactly like Remediate and is bounded by
+ * the same guardrails. */
+export const REFRESH_REMEDIATION_MODE = "RefreshRemediation";
+/** the `refactor` verb relocates resources behind a module boundary and pushes
+ * Terraform like Remediate, so it is bounded by the same allow-list / secret /
+ * destroy guardrails — PLUS the equivalence hard-fail below (a refactor that
+ * can't prove behaviour-preservation must not reach a human). */
+export const REFACTOR_MODE = "Refactor";
+/** the dependency / deprecation / cost verbs each write Terraform and push
+ * exactly like Remediate, so they are bounded by the same allow-list / secret /
+ * destroy / PR-cap guardrails. UpdateDependencies also runs the equivalence
+ * check for config-preserving bumps and so inherits the equivalence hard-fail
+ * below; ModernizeDeprecated and CostOptimization are behaviour-altering and
+ * prove via plan, so they never record an equivalence verdict and that one gate
+ * no-ops for them. */
+export const UPDATE_DEPENDENCIES_MODE = "UpdateDependencies";
+export const MODERNIZE_DEPRECATED_MODE = "ModernizeDeprecated";
+export const COST_OPTIMIZATION_MODE = "CostOptimization";
+/** the combined verb: it both remediates (a ✗→✓ fix, like Remediate) and
+ * refactors (an equivalence-proven modularisation, like Refactor) on one branch,
+ * so it is bounded by EVERY guardrail of both — the allow-list / secret /
+ * destroy / PR caps AND the equivalence hard-fail (which gates the refactor half
+ * once terraform_equivalence_check runs; no-op until it does). */
+export const REMEDIATE_AND_REFACTOR_MODE = "RemediateAndRefactor";
+
+/** default paths these modes may modify/create: Terraform sources only. */
+export const DEFAULT_ALLOWED_PATHS = ["**/*.tf", "**/*.tfvars"] as const;
+
+/** extra paths the Terratest scaffold writes, allowed only when the
+ * `terratest` input is enabled (Go test files + native `*.tftest.hcl` tests fall
+ * outside the Terraform-only default). */
+export const TERRATEST_ALLOWED_PATHS = [
+  "**/*_test.go",
+  "**/*.tftest.hcl",
+  "test/**",
+  "tests/**",
+  "go.mod",
+  "go.sum",
+] as const;
+
+/** doc paths writable only when the `docs` input is enabled — the
+ * terraform_module_docs surface. Deliberately narrow: module READMEs and the
+ * infraweaver docs dir only; the repo root README and arbitrary `docs/**` stay
+ * blocked even with the input on (fail-closed, mirroring the Terratest
+ * carve-out above). */
+export const DOCS_ALLOWED_PATHS = [
+  "modules/**/README.md",
+  "docs/infraweaver/**/*.md",
+] as const;
+
+/** the cost artifact, writable only by the CostOptimization mode (§5.19). A
+ * single exact filename rather than a glob — the same fail-closed narrowness as
+ * the docs carve-out, so no other markdown becomes writable by accident. */
+export const COST_ALLOWED_PATHS = [COST_FILE] as const;
+
+/** modes whose pushes/PRs are bounded by these guardrails — exported (ordered)
+ * so the security-model doc generator renders the real list, not a copy. */
+export const GUARDED_MODE_NAMES = [
+  REMEDIATE_MODE,
+  REFRESH_REMEDIATION_MODE,
+  REFACTOR_MODE,
+  REMEDIATE_AND_REFACTOR_MODE,
+  UPDATE_DEPENDENCIES_MODE,
+  MODERNIZE_DEPRECATED_MODE,
+  COST_OPTIMIZATION_MODE,
+] as const;
+
+const GUARDED_MODES: ReadonlySet<string> = new Set(GUARDED_MODE_NAMES);
+
+/** Whether a mode NAME is one whose pushes/PRs are bounded by these guardrails.
+ *  Pure (no ctx) so read-only tools — e.g. terraform_plan, which can't see the
+ *  full push surface — can tell whether a destructive plan WOULD block a push. */
+export function isGuardedModeName(mode: string | undefined): boolean {
+  return mode !== undefined && GUARDED_MODES.has(mode);
+}
+
+function isGuardedMode(ctx: GuardrailContext): boolean {
+  return isGuardedModeName(ctx.toolState.selectedMode);
+}
+
+export function resolveAllowedPaths(ctx: GuardrailContext): string[] {
+  const configured = ctx.payload.allowedPaths;
+  const base =
+    configured && configured.length > 0
+      ? [...configured]
+      : [...DEFAULT_ALLOWED_PATHS];
+  // when Terratest scaffolding is opted in (the `terratest` input OR the
+  // unified tools_enabled list), also permit the Go test + example-fixture
+  // paths the scaffold writes (they're outside the .tf default).
+  if (resolveToolSelection(ctx.payload).enabled("terratest"))
+    base.push(...TERRATEST_ALLOWED_PATHS);
+  // when the `docs` input is opted in, also permit the evidence-backed module
+  // README paths terraform_module_docs writes. A plain payload flag (not a
+  // tools_enabled token): docs generation is built-in, not an external tool.
+  if (ctx.payload.docs) base.push(...DOCS_ALLOWED_PATHS);
+  // the cost artifact is only ever written by the cost verb, so the carve-out is
+  // scoped to that mode rather than opened for every guarded mode.
+  if (ctx.toolState.selectedMode === COST_OPTIMIZATION_MODE)
+    base.push(...COST_ALLOWED_PATHS);
+  return base;
+}
+
+/**
+ * Compile a glob to an anchored RegExp. Supports `**` (any path segments,
+ * including the `**\/` "zero or more leading dirs" idiom), `*` (within a
+ * segment), and `?`. Sufficient for the path allow-list patterns
+ * (`**\/*.tf`, `modules/**`, `*.tfvars`).
+ */
+export function globToRegex(glob: string): RegExp {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]!;
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        if (glob[i + 2] === "/") {
+          re += "(?:.*/)?";
+          i += 2;
+        } else {
+          re += ".*";
+          i += 1;
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: literal regex metacharacters, not a template interpolation
+    } else if (".+^${}()|[]\\".includes(c)) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+export function isPathAllowed(path: string, globs: string[]): boolean {
+  const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+  return globs.some((g) => globToRegex(g).test(normalized));
+}
+
+/** the run-entry commit sha, used as the baseline for "what this run changed". */
+function runStartSha(ctx: GuardrailContext): string | null {
+  const head = ctx.toolState.initialHead;
+  if (!head) return null;
+  try {
+    const ref = head.kind === "branch" ? head.name : head.sha;
+    return $("git", ["rev-parse", ref], { log: false });
+  } catch {
+    return null;
+  }
+}
+
+/** files changed on the current branch since the run started. */
+function changedFilesSinceRunStart(ctx: GuardrailContext): string[] {
+  const base = runStartSha(ctx);
+  if (!base) return [];
+  // `$` returns trimmed stdout on success and throws on a non-zero exit (no
+  // onError handler) — so a genuine git failure here propagates and the caller
+  // fails closed (the push is refused) rather than treating an errored diff as
+  // "nothing changed". `git diff --name-only` exits 0 on a clean diff.
+  const out = $("git", ["diff", "--name-only", base, "HEAD"], { log: false });
+  return out
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Enforce the path allow-list before a Remediate-mode push. Throws if the
+ * branch changed any file outside the allowed globs — the choke point is
+ * push_branch, the only way changes reach a PR. Fails closed: if the baseline
+ * can't be established it refuses rather than letting an unbounded change
+ * through.
+ */
+export function enforceRemediationPaths(ctx: GuardrailContext): void {
+  if (!isGuardedMode(ctx)) return;
+
+  const base = runStartSha(ctx);
+  if (!base) {
+    throw new Error(
+      "push blocked (Terraform-only guardrail): could not establish the run-start commit to verify the change is limited to Terraform files. " +
+        "Ensure the run started from a clean checkout.",
+    );
+  }
+
+  const allowed = resolveAllowedPaths(ctx);
+  const changed = changedFilesSinceRunStart(ctx);
+  const violations = changed.filter((f) => !isPathAllowed(f, allowed));
+  if (violations.length > 0) {
+    throw new Error(
+      `push blocked (Terraform-only guardrail): this run changed files outside the allowed paths [${allowed.join(", ")}]. ` +
+        `This mode must only touch Terraform files. Revert these and keep the change to Terraform only:\n` +
+        violations.map((v) => `  - ${v}`).join("\n"),
+    );
+  }
+  log.info(
+    `» Terraform-only path guardrail ok (${changed.length} file(s), all within [${allowed.join(", ")}])`,
+  );
+}
+
+// --- protected-resource allowlist -------------------------------------
+
+/** glob patterns marking files the fixer must NEVER auto-modify (prod state,
+ * data stores, anything sensitive). The inverse of `allowed_paths`. */
+export function resolveProtectedPaths(ctx: GuardrailContext): string[] {
+  return ctx.payload.protectedPaths ?? [];
+}
+
+/**
+ * Block a push that touched any file matching `protected_paths`. This is the
+ * inverse of the allow-list: a changed file matching a protected glob fails the
+ * push, even though it's a `.tf`/`.tfvars` the allow-list would otherwise permit.
+ * No-op when `protected_paths` is unset or outside a guarded mode. Fails closed:
+ * if the run-start baseline can't be established it refuses, same as
+ * `enforceRemediationPaths`.
+ */
+export function enforceProtectedPaths(ctx: GuardrailContext): void {
+  if (!isGuardedMode(ctx)) return;
+  const protectedGlobs = resolveProtectedPaths(ctx);
+  if (protectedGlobs.length === 0) return;
+
+  const base = runStartSha(ctx);
+  if (!base) {
+    throw new Error(
+      "push blocked (protected-paths guardrail): could not establish the run-start commit to verify no protected path was modified. " +
+        "Ensure the run started from a clean checkout.",
+    );
+  }
+
+  const changed = changedFilesSinceRunStart(ctx);
+  const violations = changed.filter((f) => isPathAllowed(f, protectedGlobs));
+  if (violations.length > 0) {
+    throw new Error(
+      `push blocked (protected-paths guardrail): this run modified files matching the protected_paths globs [${protectedGlobs.join(", ")}], ` +
+        `which are marked never-auto-modify. Revert these and leave them for a human:\n` +
+        violations.map((v) => `  - ${v}`).join("\n"),
+    );
+  }
+  log.info(
+    `» protected-paths guardrail ok (no change matched [${protectedGlobs.join(", ")}])`,
+  );
+}
+
+// --- read-only (vendored) module guard --------------------------------
+
+/** globs marking FETCHED (vendored) module code — a private cross-repo `git::`
+ * module (refactor b.1) or a third-party registry module (b.4) that `terraform
+ * init` resolved into the local module cache. The refactor contract is that such
+ * a module is READ-ONLY: a concern inside it is fixed at the CALL SITE via inputs,
+ * never by editing the vendored copy, and a separate-repo b.1 module must never
+ * receive a write change. This is the code-level backing for that rule. */
+export const VENDORED_MODULE_PATHS = [
+  "**/.terraform/modules/**",
+  "**/.external_modules/**",
+] as const;
+
+/**
+ * Block a push that committed an edit to FETCHED (vendored) module code. The
+ * Terraform-only allow-list (`**​/*.tf`) would otherwise PERMIT
+ * `.terraform/modules/<x>/main.tf`, so without this a refactor could silently
+ * vendor-and-edit a read-only module's source — exactly what the b.1/b.4 contract
+ * forbids ("never open a write PR against a read-only module repo; never edit
+ * vendored module code"). Engages only in a guarded mode; fails closed on a
+ * missing baseline, like {@link enforceRemediationPaths}. No-op when nothing under
+ * the module cache was committed (the normal case — it's usually gitignored).
+ */
+export function assertNoVendoredModuleEdits(ctx: GuardrailContext): void {
+  if (!isGuardedMode(ctx)) return;
+  const base = runStartSha(ctx);
+  if (!base) {
+    throw new Error(
+      "push blocked (read-only module guardrail): could not establish the run-start commit to verify no vendored module code was edited. Ensure the run started from a clean checkout.",
+    );
+  }
+  const changed = changedFilesSinceRunStart(ctx);
+  const violations = changed.filter((f) =>
+    isPathAllowed(f, [...VENDORED_MODULE_PATHS]),
+  );
+  if (violations.length > 0) {
+    throw new Error(
+      "push blocked (read-only module guardrail): this run modified FETCHED module code under the local " +
+        "module cache. A module in a separate repo (b.1) or a third-party registry module (b.4) is READ-ONLY — " +
+        "fix a module-internal concern at the CALL SITE via the module's inputs, never by editing the vendored " +
+        "copy. Revert these:\n" +
+        violations.map((v) => `  - ${v}`).join("\n"),
+    );
+  }
+  log.info(
+    "» read-only module guardrail ok (no vendored module code was edited)",
+  );
+}
+
+// --- secrets-safe diff scan -------------------------------------------
+
+export interface SecretHit {
+  file: string;
+  line: number;
+  rule: string;
+}
+
+/**
+ * High-signal secret detectors applied to lines a fix ADDED. Kept deliberately
+ * narrow (low false-positive) — the goal is to stop a "fix" that hardcodes a
+ * literal credential (e.g. resolving a "use a variable" finding by pasting the
+ * secret), not to be a general-purpose scanner. Each entry is [rule, regex].
+ */
+const SECRET_VALUE_PATTERNS: ReadonlyArray<readonly [string, RegExp]> = [
+  [
+    "aws-access-key-id",
+    /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA)[0-9A-Z]{16}\b/,
+  ],
+  [
+    "pem-private-key",
+    /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----/,
+  ],
+  ["gcp-api-key", /\bAIza[0-9A-Za-z_-]{35}\b/],
+  ["github-token", /\bgh[pousr]_[0-9A-Za-z]{36,}\b/],
+  ["slack-token", /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/],
+  ["private-key-pem-block", /-----BEGIN PRIVATE KEY-----/],
+];
+
+// an HCL/tfvars assignment of a STRING LITERAL to a secret-named attribute, e.g.
+// `password = "hunter2"` or `secret_access_key = "AKIA..."`. The captured value is
+// filtered in code (see scanDiffForSecrets) to exclude empty strings and any value
+// containing a Terraform interpolation `${...}` — references like `= var.x` /
+// `= local.y` already fail the quoted-value match. Only a real inlined literal trips it.
+const SENSITIVE_ASSIGNMENT =
+  /\b(?:password|passwd|secret|secret_key|secret_access_key|access_key|api_key|apikey|auth_token|access_token|private_key|client_secret|credential|connection_string)\b\s*[=:]\s*"([^"]*)"/i;
+
+/**
+ * Scan a unified `git diff` for inlined secrets on ADDED lines only. Tracks the
+ * current file from `+++ b/<path>` headers and the new-side line number from
+ * `@@` hunk headers, so each hit carries an accurate `file:line`. Pure — the
+ * guardrail feeds it `git diff` output. Removed/context lines are ignored (a
+ * secret already in the base isn't this run's doing).
+ */
+export function scanDiffForSecrets(diff: string): SecretHit[] {
+  const hits: SecretHit[] = [];
+  let file = "(unknown)";
+  let newLine = 0;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      const path = raw.slice(4).trim().replace(/^b\//, "");
+      file = path === "/dev/null" ? "(deleted)" : path;
+      continue;
+    }
+    if (
+      raw.startsWith("--- ") ||
+      raw.startsWith("diff --git") ||
+      raw.startsWith("index ")
+    )
+      continue;
+    const hunk = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunk) {
+      newLine = Number(hunk[1]);
+      continue;
+    }
+    if (raw.startsWith("+")) {
+      const content = raw.slice(1);
+      for (const [rule, re] of SECRET_VALUE_PATTERNS) {
+        if (re.test(content)) hits.push({ file, line: newLine, rule });
+      }
+      // only a real inlined literal trips it: skip empty strings and any value
+      // carrying a `${...}` interpolation — including one with literal text before
+      // the interpolation (e.g. `connection_string = "postgres://u:${var.pw}@h"`),
+      // which the prior first-char-only exclusion wrongly flagged and dead-ended.
+      const secretValue = content.match(SENSITIVE_ASSIGNMENT)?.[1];
+      if (secretValue && !secretValue.includes("${")) {
+        hits.push({ file, line: newLine, rule: "hardcoded-secret-assignment" });
+      }
+      newLine++;
+    } else if (raw.startsWith("-")) {
+      // removed line — does not advance the new-side counter
+    } else {
+      // context line (leading space) or blank — advances the new-side counter
+      newLine++;
+    }
+  }
+  return hits;
+}
+
+/**
+ * Parse a `gitleaks detect --report-format json` report (an array of finding
+ * objects) into the shared `SecretHit` shape. Pure, so it's unit-testable
+ * without the binary. `gitleaks:` prefixes the rule so a hit's engine is
+ * obvious next to the built-in detectors. Tolerates an empty / non-array report.
+ */
+export function parseGitleaksReport(json: string): SecretHit[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json || "[]");
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const hits: SecretHit[] = [];
+  for (const f of parsed as Array<Record<string, unknown>>) {
+    const file = typeof f.File === "string" && f.File ? f.File : "(unknown)";
+    const line = typeof f.StartLine === "number" ? f.StartLine : 0;
+    const rule = typeof f.RuleID === "string" && f.RuleID ? f.RuleID : "secret";
+    hits.push({ file, line, rule: `gitleaks:${rule}` });
+  }
+  return hits;
+}
+
+/**
+ * Optional deeper secret scan via the external `gitleaks` binary, opt-in through
+ * the `gitleaks` action input. Best-effort: returns `null` when gitleaks isn't
+ * installed or can't run (the built-in scanner already provides the fail-closed
+ * baseline, so an absent gitleaks degrades to "built-in only" rather than
+ * failing the push). Scans the commits this run added (`<base>..HEAD`) and uses
+ * `--exit-code 0` so a leak doesn't make the process exit non-zero — we read the
+ * JSON report instead. Restricted env, so no secret leaks into the subprocess.
+ */
+function scanWithGitleaks(
+  ctx: GuardrailContext,
+  base: string,
+): SecretHit[] | null {
+  const reportPath = join(ctx.tmpdir, `gitleaks-report-${process.pid}.json`);
+  const cwd = ctx.payload.cwd ?? process.cwd();
+  const result = spawnSync(
+    "gitleaks",
+    [
+      "detect",
+      "--source",
+      ".",
+      "--log-opts",
+      `${base}..HEAD`,
+      "--report-format",
+      "json",
+      "--report-path",
+      reportPath,
+      "--exit-code",
+      "0",
+      "--no-banner",
+      "--redact",
+    ],
+    {
+      cwd,
+      encoding: "utf-8",
+      env: resolveEnv("restricted") as NodeJS.ProcessEnv,
+      maxBuffer: 64 * 1024 * 1024,
+    },
+  );
+  if (result.error) {
+    const missing = (result.error as NodeJS.ErrnoException).code === "ENOENT";
+    log.warning(
+      missing
+        ? "» gitleaks requested but not installed — falling back to the built-in secret scanner only"
+        : `» gitleaks could not run (${result.error.message}) — built-in secret scanner still enforced`,
+    );
+    return null;
+  }
+  try {
+    const report = readFileSync(reportPath, "utf8");
+    return parseGitleaksReport(report);
+  } catch {
+    // no report file written usually means a clean scan; treat as no hits.
+    return [];
+  } finally {
+    try {
+      rmSync(reportPath, { force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+}
+
+/**
+ * Block a push whose diff (since run start) inlines a secret. Reuses the same
+ * run-start baseline as the path guardrail. No-op outside a guarded mode. Fails
+ * closed on a missing baseline. The diff is read with `$` (restricted env), so
+ * no secret leaks into the subprocess.
+ *
+ * The built-in detectors always run (the deterministic, fail-closed baseline).
+ * When the operator opts in via the `gitleaks` input, gitleaks ALSO runs for
+ * deeper coverage and its hits are merged — but its absence never weakens the
+ * baseline (see scanWithGitleaks).
+ */
+export function assertNoSecretsInDiff(ctx: GuardrailContext): void {
+  if (!isGuardedMode(ctx)) return;
+  const base = runStartSha(ctx);
+  if (!base) {
+    throw new Error(
+      "push blocked (secret-scan guardrail): could not establish the run-start commit to scan the diff for inlined secrets. " +
+        "Ensure the run started from a clean checkout.",
+    );
+  }
+  const diff = $("git", ["diff", base, "HEAD"], { log: false });
+  const hits = scanDiffForSecrets(diff);
+
+  // optional deeper engine — merged on top of the built-in baseline. Opted in
+  // via the `gitleaks` input OR by naming "gitleaks" in the unified tools_enabled
+  // list; an explicit `-gitleaks` there turns it back off.
+  const gitleaksEnabled = resolveToolSelection(ctx.payload).enabled("gitleaks");
+  if (gitleaksEnabled) {
+    const gitleaksHits = scanWithGitleaks(ctx, base);
+    if (gitleaksHits) hits.push(...gitleaksHits);
+  }
+
+  if (hits.length > 0) {
+    throw new Error(
+      `push blocked (secret-scan guardrail): the change appears to inline ${hits.length} secret(s) — a fix must reference a variable/secret store, never paste a literal. ` +
+        `Remove or parameterise these and re-push:\n` +
+        hits.map((h) => `  - ${h.file}:${h.line} (${h.rule})`).join("\n"),
+    );
+  }
+  log.info(
+    `» secret-scan guardrail ok (no inlined secrets in the diff${gitleaksEnabled ? ", built-in + gitleaks" : ""})`,
+  );
+}
+
+/** resource addresses the operator has explicitly allowed to be destroyed/replaced. */
+export function resolveAllowReplace(ctx: GuardrailContext): string[] {
+  return ctx.payload.allowReplace ?? [];
+}
+
+export function isReplaceAllowed(
+  address: string,
+  allowList: string[],
+): boolean {
+  return allowList.some(
+    (a) =>
+      a === "*" || a === "all" || a === address || globToRegex(a).test(address),
+  );
+}
+
+/** Split a plan's stateful destroy/replace set by whether the operator's
+ *  `allow_replace` list covers each address. `blocked` is what
+ *  {@link assertNoBlockedDestroy} throws on at push — surfacing it at plan time
+ *  lets a committing mode abandon BEFORE the wasted commit/push round-trip. */
+export function partitionStatefulDestroy<T extends { address: string }>(
+  stateful: T[],
+  allowList: string[],
+): { blocked: T[]; allowed: T[] } {
+  const blocked: T[] = [];
+  const allowed: T[] = [];
+  for (const r of stateful) {
+    (isReplaceAllowed(r.address, allowList) ? allowed : blocked).push(r);
+  }
+  return { blocked, allowed };
+}
+
+/**
+ * Block a push that `terraform_plan` showed would DELETE or REPLACE a stateful
+ * (data-bearing) resource — RDS, S3, EBS, a SQL database, etc. A best-practice
+ * remediation should never destroy data; if the replacement is genuinely
+ * intended the operator opts in per-resource via the `allow_replace` input
+ * (an address, a glob, or `*`/`all`). No-op outside guarded modes. When no plan
+ * ran (no cloud credentials — `terraform_plan` degraded green), there is no
+ * evidence to act on and nothing is blocked: this gate engages only on what the
+ * plan actually reported, so it strengthens the run when creds are wired and is
+ * silent otherwise.
+ */
+export function assertNoBlockedDestroy(ctx: GuardrailContext): void {
+  if (!isGuardedMode(ctx)) return;
+  const planned = scanSessionOf(ctx.toolState).plannedDestroy;
+  if (!planned || planned.stateful.length === 0) return;
+
+  const allow = resolveAllowReplace(ctx);
+  const { blocked } = partitionStatefulDestroy(planned.stateful, allow);
+  if (blocked.length === 0) {
+    log.info(
+      `» destroy-block guardrail ok (${planned.stateful.length} stateful destroy/replace allowed via allow_replace)`,
+    );
+    return;
+  }
+  throw new Error(
+    `push blocked (Terraform-only guardrail): terraform plan shows this change would DESTROY or REPLACE ` +
+      `${blocked.length} stateful resource(s), which would likely cause data loss — a best-practice ` +
+      `remediation should not. Abandon this change, or, ONLY if the replacement is genuinely intended, ` +
+      `set the \`allow_replace\` input to include the resource address(es):\n` +
+      blocked
+        .map((r) => `  - ${r.address} (${r.action}, ${r.type})`)
+        .join("\n"),
+  );
+}
+
+/**
+ * Block a push whose `refactor` did not PROVE behaviour-equivalence. Acts on the
+ * `terraform_equivalence_check` verdict recorded in tool state — most critically
+ * an UNCOVERED `moved {}` block, which would silently destroy and recreate live
+ * resources on apply (the single highest-risk refactor defect, a sin of
+ * commission far worse than a missed finding). Like the destroy-block gate, it
+ * engages only on evidence the proof tool actually produced: no equivalence check
+ * recorded → nothing to act on → no-op (so a remediation, which never runs the
+ * check, is unaffected). No-op outside a guarded mode. When the recorded verdict
+ * is `equivalent: false`, the push is refused with the proof's own reasons.
+ */
+export function assertRefactorEquivalence(ctx: GuardrailContext): void {
+  if (!isGuardedMode(ctx)) return;
+  const proof = scanSessionOf(ctx.toolState).refactorEquivalence;
+  if (!proof || proof.equivalent) {
+    if (proof?.equivalent)
+      log.info(
+        "» refactor equivalence guardrail ok (behaviour-preserving proven)",
+      );
+    return;
+  }
+  const uncovered =
+    proof.uncovered_moves.length > 0
+      ? `\nUNCOVERED moves (these would be DESTROYED and RECREATED on apply — add a \`moved {}\` block for each):\n` +
+        proof.uncovered_moves.map((m) => `  - ${m.from} → ${m.to}`).join("\n")
+      : "";
+  throw new Error(
+    `push blocked (refactor equivalence guardrail): terraform_equivalence_check could NOT prove this ` +
+      `refactor preserves behaviour, so it must not reach a human as an equivalence claim. Resolve these and ` +
+      `re-prove before pushing:\n` +
+      proof.reasons.map((r) => `  - ${r}`).join("\n") +
+      uncovered,
+  );
+}
+
+/** maximum remediation PRs a single run may open (default 1). */
+export function resolveMaxPrs(ctx: GuardrailContext): number {
+  return ctx.payload.maxPrs ?? 1;
+}
+
+/**
+ * Enforce the per-run PR cap before opening a remediation PR. Throws when the
+ * cap is already reached so the agent stops at the configured number of scoped
+ * PRs instead of fanning out.
+ */
+export function assertUnderPrCap(ctx: GuardrailContext): void {
+  if (!isGuardedMode(ctx)) return;
+  const cap = resolveMaxPrs(ctx);
+  const opened = ctx.toolState.remediationPrsOpened ?? 0;
+  if (opened >= cap) {
+    throw new Error(
+      `PR limit reached (Terraform-only guardrail): this run is configured to open at most ${cap} PR(s) and has already opened ${opened}. ` +
+        `Stop here and report the remaining work for a future run.`,
+    );
+  }
+}
+
+/** record that a guarded-mode PR was opened (after create_pull_request succeeds). */
+export function recordRemediationPrOpened(ctx: GuardrailContext): void {
+  if (!isGuardedMode(ctx)) return;
+  ctx.toolState.remediationPrsOpened =
+    (ctx.toolState.remediationPrsOpened ?? 0) + 1;
+}
+
+/** max simultaneously-open remediation PRs before new ones are held back
+ * (default 10; 0 disables the cap). Action-input only (see payload.ts). */
+export function resolvePrConcurrentLimit(ctx: GuardrailContext): number {
+  return ctx.payload.prConcurrentLimit ?? 10;
+}
+
+/** max remediation PRs opened per rolling hour (default 0 = no hourly cap). */
+export function resolvePrHourlyLimit(ctx: GuardrailContext): number {
+  return ctx.payload.prHourlyLimit ?? 0;
+}
+
+/**
+ * Cross-run flood guard: cap how many remediation PRs may be simultaneously OPEN
+ * (`prConcurrentLimit`) and how many may be CREATED per rolling hour
+ * (`prHourlyLimit`). Unlike {@link assertUnderPrCap} — which counts only this
+ * run's PRs from in-memory tool state — this queries GitHub for PRs across runs,
+ * so a first scan on a messy repo (or a burst of push-triggered runs) can't bury
+ * the maintainer under remediation PRs. Engages only in a guarded mode; a 0 limit
+ * disables that check. Throws with an agent-actionable message, before creation.
+ */
+export async function assertUnderOpenPrCaps(
+  ctx: OpenPrCapContext,
+): Promise<void> {
+  if (!isGuardedMode(ctx)) return;
+  const concurrentLimit = resolvePrConcurrentLimit(ctx);
+  const hourlyLimit = resolvePrHourlyLimit(ctx);
+  if (concurrentLimit <= 0 && hourlyLimit <= 0) return;
+
+  const owner = ctx.repo.owner;
+  const repo = ctx.repo.name;
+
+  // Concurrency: count currently-open remediation PRs (`remediate/<id>`, incl.
+  // `remediate/batch-*`). groupIdFromBranch is non-null exactly for those.
+  if (concurrentLimit > 0) {
+    const open = await ctx.octokit.paginate(ctx.octokit.rest.pulls.list, {
+      owner,
+      repo,
+      state: "open",
+      per_page: 100,
+    });
+    const openRemediation = open.filter(
+      (pr) => groupIdFromBranch(pr.head.ref) !== null,
+    );
+    if (openRemediation.length >= concurrentLimit) {
+      throw new Error(
+        `Open remediation PR cap reached (Terraform-only guardrail): ${openRemediation.length} ${PRODUCT_NAME} ` +
+          `remediation PR(s) are already open and the cap is ${concurrentLimit}. Don't open another — stop here ` +
+          `and report the remaining work so it lands once existing PRs are merged or closed (or raise ` +
+          `\`pr_concurrent_limit\`).`,
+      );
+    }
+  }
+
+  // Hourly: count remediation PRs CREATED in the last rolling hour (any state — a
+  // PR merged or closed within the hour still counts toward creation velocity).
+  // The 100 most-recently-created PRs cover an hour in any realistic repo.
+  if (hourlyLimit > 0) {
+    const cutoffMs = Date.now() - 60 * 60 * 1000;
+    const recent = await ctx.octokit.rest.pulls.list({
+      owner,
+      repo,
+      state: "all",
+      sort: "created",
+      direction: "desc",
+      per_page: 100,
+    });
+    const recentRemediation = recent.data.filter(
+      (pr) =>
+        groupIdFromBranch(pr.head.ref) !== null &&
+        new Date(pr.created_at).getTime() >= cutoffMs,
+    );
+    if (recentRemediation.length >= hourlyLimit) {
+      throw new Error(
+        `Hourly remediation PR cap reached (Terraform-only guardrail): ${recentRemediation.length} remediation ` +
+          `PR(s) were opened in the last hour and the cap is ${hourlyLimit}. Stop here and report the remaining ` +
+          `work for a later run (or raise \`pr_hourly_limit\`).`,
+      );
+    }
+  }
+}