infraweaver 0.3.7 → 0.3.8

package/src/mcp/terraform/treeLayout.ts

@@ -0,0 +1,378 @@
+/**
+ * Which root module each directory and variable file belongs to.
+ *
+ * Two jobs need it. trivy and checkov evaluate variables, so a value set in a
+ * `.tfvars` file — an open CIDR, a public flag — is a finding only when the
+ * scan loads that file, and loads it for the root that uses it rather than for
+ * every root in the tree. And a pull-request review only needs to scan the
+ * roots a change can reach: a root none of whose files, local modules or
+ * variable files changed has the same findings on both sides of the PR.
+ *
+ * Terraform loads `terraform.tfvars` and `*.auto.tfvars` from the root module's
+ * own directory by itself. Any other variable file — `prod.tfvars` next to the
+ * root, `envs/prod/vars/prod.tfvars`, `config/staging.tfvars` — is passed with
+ * `-var-file`, so its root is not written anywhere a scan can read. It is
+ * matched by the variables it sets, then by where it lives; a file that could
+ * belong to several roots is left out and reported rather than guessed, and
+ * `var_files` names its root explicitly.
+ */
+import { readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { parseModuleBlocks, walkFilesBySuffix } from "#app/mcp/modules";
+import { skipNonCode } from "#app/mcp/terraform/hcl";
+import { resolveRoots } from "#app/mcp/terraform/paths";
+
+/** The variable files Terraform loads by itself in a root module, in its order. */
+const AUTO_TFVARS = /^(?:terraform\.tfvars|.+\.auto\.tfvars)(?:\.json)?$/;
+
+/** A variable file assigned to a root by the `var_files` setting. */
+export interface VarFileMapping {
+  /** the root module's directory, relative to the scan directory ("" = itself) */
+  root: string;
+  /** the variable file, relative to the scan directory */
+  file: string;
+}
+
+export interface RootLayout {
+  /** the root module's directory, relative to the scan directory ("" = itself) */
+  dir: string;
+  /** the root's directory and every local module directory it calls, transitively */
+  closure: string[];
+  /** the variable files Terraform loads by itself, in its load order */
+  autoVarFiles: string[];
+  /** variable files passed with `-var-file`: from `var_files`, or matched to this root */
+  varFiles: string[];
+  /** the root's configuration and its modules', for finding files it reads by name */
+  source: string;
+}
+
+export interface TreeLayout {
+  roots: RootLayout[];
+  /** every directory that holds Terraform configuration */
+  tfDirs: string[];
+  /** variable files no root could be matched to, and why */
+  unmatched: { file: string; reason: string }[];
+}
+
+const CONFIG_SUFFIXES = [".tf", ".tf.json", ".tofu"] as const;
+
+function dirOf(file: string): string {
+  const d = posix.dirname(file);
+  return d === "." ? "" : d;
+}
+
+/** `dir/rel` resolved; null when it climbs out of the scan directory. */
+function joinRel(dir: string, rel: string): string | null {
+  const joined = posix.normalize(dir ? `${dir}/${rel}` : rel);
+  if (joined === "." || joined === "./") return "";
+  if (joined === ".." || joined.startsWith("../")) return null;
+  return joined.replace(/^\.\//, "").replace(/\/$/, "");
+}
+
+function read(cwd: string, rel: string): string {
+  try {
+    return readFileSync(join(cwd, rel), "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/** True when `dir` is `ancestor` or lies beneath it. */
+export function isWithin(dir: string, ancestor: string): boolean {
+  return ancestor === "" || dir === ancestor || dir.startsWith(`${ancestor}/`);
+}
+
+/** Local module sources and declared variable names of one directory's configuration. */
+function dirFacts(cwd: string, files: string[]): { modules: string[]; variables: Set<string> } {
+  const modules: string[] = [];
+  const variables = new Set<string>();
+  for (const file of files) {
+    const text = read(cwd, file);
+    if (file.endsWith(".json")) {
+      try {
+        const doc = JSON.parse(text) as Record<string, unknown>;
+        for (const name of Object.keys((doc.variable as object | undefined) ?? {})) {
+          variables.add(name);
+        }
+        for (const block of Object.values((doc.module as object | undefined) ?? {})) {
+          const source = (block as { source?: unknown }).source;
+          if (typeof source === "string" && /^\.\.?\//.test(source)) modules.push(source);
+        }
+      } catch {
+        // configuration that does not parse declares nothing we can use
+      }
+      continue;
+    }
+    for (const block of parseModuleBlocks(text)) {
+      if (block.kind === "local") modules.push(block.source);
+    }
+    for (const m of text.matchAll(/(?:^|\n)\s*variable\s+"?([A-Za-z0-9_-]+)"?/g)) {
+      if (m[1]) variables.add(m[1]);
+    }
+  }
+  return { modules, variables };
+}
+
+/** The names a variable file assigns at its top level. */
+export function varFileKeys(text: string, json: boolean): string[] {
+  if (json) {
+    try {
+      const doc = JSON.parse(text) as unknown;
+      return doc && typeof doc === "object" && !Array.isArray(doc) ? Object.keys(doc) : [];
+    } catch {
+      return [];
+    }
+  }
+  const keys: string[] = [];
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    const skip = skipNonCode(text, i);
+    if (skip) {
+      i = skip.end;
+      continue;
+    }
+    const ch = text[i] as string;
+    if ("{[(".includes(ch)) depth++;
+    else if ("}])".includes(ch)) depth = Math.max(0, depth - 1);
+    else if (depth === 0 && /[A-Za-z_]/.test(ch) && !/[\w-]/.test(text[i - 1] ?? "")) {
+      const m = /^([A-Za-z_][\w-]*)[ \t]*=(?!=)/.exec(text.slice(i, i + 200));
+      if (m?.[1]) {
+        keys.push(m[1]);
+        i += m[0].length - 1;
+      }
+    }
+  }
+  return keys;
+}
+
+const tokens = (path: string): string[] =>
+  path
+    .replace(/\.auto\.tfvars(?:\.json)?$|\.tfvars(?:\.json)?$/, "")
+    .toLowerCase()
+    .split(/[-_./]+/)
+    .filter(Boolean);
+
+/**
+ * The root a `-var-file` file belongs to, or why none could be chosen. A
+ * candidate declares at least half of the variables the file sets. Among
+ * several, the deepest one the file lives inside wins, then the one whose path
+ * shares the most words with the file's (`config/staging.tfvars` and
+ * `envs/staging`), then a root at the top of the tree.
+ */
+function matchRoot(
+  file: string,
+  keys: string[],
+  roots: { dir: string; variables: Set<string> }[],
+): { root: string } | { reason: string } {
+  if (keys.length === 0) return { reason: "it sets no variables" };
+  const candidates = roots.filter((r) => {
+    const declared = keys.filter((k) => r.variables.has(k)).length;
+    return declared > 0 && declared * 2 >= keys.length;
+  });
+  if (candidates.length === 0) return { reason: "no root module declares its variables" };
+  if (candidates.length === 1) return { root: (candidates[0] as { dir: string }).dir };
+  const dir = dirOf(file);
+  const inside = candidates
+    .filter((r) => r.dir !== "" && isWithin(dir, r.dir))
+    .sort((a, b) => b.dir.length - a.dir.length);
+  if (inside[0]) return { root: inside[0].dir };
+  const words = new Set(tokens(file));
+  const scored = candidates
+    .map((r) => ({ dir: r.dir, score: tokens(r.dir).filter((t) => words.has(t)).length }))
+    .sort((a, b) => b.score - a.score);
+  if (scored[0] && scored[0].score > 0 && scored[0].score !== scored[1]?.score) {
+    return { root: scored[0].dir };
+  }
+  const top = candidates.find((r) => r.dir === "");
+  if (top) return { root: "" };
+  return {
+    reason: `it fits several root modules (${candidates.map((r) => r.dir).join(", ")}) — name its root in var_files`,
+  };
+}
+
+/** Terraform's load order: terraform.tfvars, terraform.tfvars.json, then *.auto.tfvars by name. */
+function autoOrder(files: string[]): string[] {
+  const first = files.filter((f) => posix.basename(f).startsWith("terraform.tfvars")).sort();
+  const rest = files.filter((f) => !posix.basename(f).startsWith("terraform.tfvars"));
+  return [
+    ...first,
+    ...rest.sort((a, b) => posix.basename(a).localeCompare(posix.basename(b), "en")),
+  ];
+}
+
+/** The tree's root modules, what each reaches, and the variable files each loads. */
+export function treeLayout(cwd: string, explicit: readonly VarFileMapping[] = []): TreeLayout {
+  const filesByDir = new Map<string, string[]>();
+  for (const suffix of CONFIG_SUFFIXES) {
+    for (const file of walkFilesBySuffix(cwd, suffix)) {
+      const dir = dirOf(file);
+      filesByDir.set(dir, [...(filesByDir.get(dir) ?? []), file]);
+    }
+  }
+  const tfDirs = [...filesByDir.keys()].sort();
+  const facts = new Map(tfDirs.map((d) => [d, dirFacts(cwd, filesByDir.get(d) ?? [])]));
+  const modulesOf = (dir: string): string[] =>
+    (facts.get(dir)?.modules ?? [])
+      .map((source) => joinRel(dir, source))
+      .filter((d): d is string => d !== null && facts.has(d));
+
+  const rootDirs = resolveRoots(cwd).map((r) => r.relDir);
+  const closures = new Map<string, string[]>();
+  for (const root of rootDirs) {
+    const seen = new Set<string>([root]);
+    const queue = [root];
+    for (let dir = queue.shift(); dir !== undefined; dir = queue.shift()) {
+      for (const next of modulesOf(dir)) {
+        if (!seen.has(next)) {
+          seen.add(next);
+          queue.push(next);
+        }
+      }
+    }
+    closures.set(root, [...seen].sort());
+  }
+  const rootSet = new Set(rootDirs);
+  const moduleDirs = new Set([...closures.values()].flat().filter((d) => !rootSet.has(d)));
+
+  const varFiles = [
+    ...walkFilesBySuffix(cwd, ".tfvars"),
+    ...walkFilesBySuffix(cwd, ".tfvars.json"),
+  ].sort();
+  const auto = new Map<string, string[]>();
+  const passed = new Map<string, string[]>();
+  const unmatched: TreeLayout["unmatched"] = [];
+  const add = (m: Map<string, string[]>, root: string, file: string) => {
+    const list = m.get(root) ?? [];
+    if (!list.includes(file)) m.set(root, [...list, file]);
+  };
+
+  const named = new Set<string>();
+  for (const { root, file } of explicit) {
+    const r = joinRel("", root);
+    const f = joinRel("", file);
+    if (r === null || f === null || !rootSet.has(r)) {
+      unmatched.push({
+        file,
+        reason: `var_files names ${root || "."}, which is not a root module`,
+      });
+      continue;
+    }
+    named.add(f);
+    add(passed, r, f);
+  }
+
+  const variablesOf = rootDirs.map((dir) => ({
+    dir,
+    variables: facts.get(dir)?.variables ?? new Set<string>(),
+  }));
+  for (const file of varFiles) {
+    if (named.has(file)) continue;
+    const dir = dirOf(file);
+    if (rootSet.has(dir) && AUTO_TFVARS.test(posix.basename(file))) {
+      add(auto, dir, file);
+      continue;
+    }
+    // a module's own example values are not any root's
+    if (moduleDirs.has(dir)) continue;
+    const match = matchRoot(
+      file,
+      varFileKeys(read(cwd, file), file.endsWith(".json")),
+      variablesOf,
+    );
+    if ("root" in match) add(passed, match.root, file);
+    else unmatched.push({ file, reason: match.reason });
+  }
+
+  const roots = rootDirs.map((dir) => {
+    const closure = closures.get(dir) ?? [dir];
+    return {
+      dir,
+      closure,
+      autoVarFiles: autoOrder(auto.get(dir) ?? []),
+      varFiles: passed.get(dir) ?? [],
+      source: closure
+        .flatMap((d) => filesByDir.get(d) ?? [])
+        .map((f) => read(cwd, f))
+        .join("\n"),
+    };
+  });
+  return { roots, tfDirs, unmatched };
+}
+
+/** `root=file` lines (the `var_files` setting) as mappings; malformed lines are reported. */
+export function parseVarFileMappings(raw: string | undefined): {
+  mappings: VarFileMapping[];
+  invalid: string[];
+} {
+  const mappings: VarFileMapping[] = [];
+  const invalid: string[] = [];
+  for (const entry of (raw ?? "").split(/[\n,]/)) {
+    const line = entry.trim();
+    if (!line) continue;
+    const eq = line.indexOf("=");
+    const root = line.slice(0, eq).trim();
+    const file = line.slice(eq + 1).trim();
+    if (eq === -1 || !file) invalid.push(line);
+    else mappings.push({ root: root === "." ? "" : root, file });
+  }
+  return { mappings, invalid };
+}
+
+/** Settings files that can change any finding in the tree. */
+const SCANNER_SETTINGS =
+  /^(?:\.checkov\.ya?ml|\.trivyignore(?:\.yaml)?|trivy\.ya?ml|\.tflint\.hcl|\.infraweaver(?:\.baseline)?\.(?:ya?ml|json)|\.terraformrc|terraform\.rc)$/;
+
+/**
+ * The directories a pull request's scan must cover, from the layouts of both
+ * sides and the files it changed (relative to the scan directory). A root is
+ * reached when a changed file lies in a directory of its closure, is one of
+ * its variable files, or is named in its configuration (a policy read with
+ * `file()`, wherever it lives); every directory of a reached root's closure is kept.
+ * A changed configuration file no root reaches keeps its own directory, as a
+ * whole-tree scan would have scanned it. Null — scan everything — when a
+ * scanner or Infraweaver settings file changed.
+ */
+export function scopeFor(
+  layouts: readonly TreeLayout[],
+  changed: Iterable<string>,
+): string[] | null {
+  const keep = new Set<string>();
+  const tfDirs = new Set(layouts.flatMap((l) => l.tfDirs));
+  for (const raw of changed) {
+    const file = raw.replace(/\\/g, "/");
+    const dir = dirOf(file);
+    const name = posix.basename(file);
+    const isConfig = CONFIG_SUFFIXES.some((s) => name.endsWith(s));
+    let reached = false;
+    for (const layout of layouts) {
+      for (const root of layout.roots) {
+        // a closure directory itself, not what lies beneath it: a module at the
+        // top of the tree would otherwise reach every root for any file at all
+        const hit =
+          root.closure.includes(dir) ||
+          root.autoVarFiles.includes(file) ||
+          root.varFiles.includes(file) ||
+          (!isConfig && root.source.includes(name));
+        if (hit) {
+          for (const d of root.closure) keep.add(d);
+          reached = true;
+        }
+      }
+    }
+    if (reached) continue;
+    if (isConfig && tfDirs.has(dir)) keep.add(dir);
+    else if (SCANNER_SETTINGS.test(name)) return null;
+  }
+  return [...keep].sort();
+}
+
+/**
+ * The directories to leave out of a scan that should cover only `keep`: every
+ * configuration directory that is neither kept nor above a kept one, and only
+ * the topmost of those, since skipping a directory skips what is beneath it.
+ */
+export function skipDirsFor(tfDirs: readonly string[], keep: readonly string[]): string[] {
+  const kept = new Set(keep);
+  const skip = tfDirs.filter((d) => d !== "" && !kept.has(d) && !keep.some((k) => isWithin(k, d)));
+  return skip.filter((d) => !skip.some((o) => o !== d && isWithin(d, o))).sort();
+}

package/src/mcp/terraform/types.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { posix } from "node:path";
 import { toolSkip } from "#app/mcp/shared";
 import type { IacLanguage } from "#app/mcp/terraform/iacLanguages";
 import type { EgressIsolation } from "#app/mcp/terraform/scannerNetns";
@@ -57,6 +58,7 @@ export interface Concern {
     | "trivy"
     | "checkov"
     | "infraweaver"
+    | "betterleaks"
     | "reviewer";
   /** original namespaced rule, e.g. "trivy:AVD-AWS-0088" */
   rule_id: string;
@@ -295,7 +297,8 @@ export function canonicalTrivyRule(bare: string): string {
  */
 export function rebaseConcern(c: Concern, relDir: string): Concern {
   if (!relDir) return c;
-  const file = `${relDir}/${c.location.file}`.replace(/\/+/g, "/");
+  // normalized: checkov run over one root reports its modules as `../../modules/x`
+  const file = posix.normalize(`${relDir}/${c.location.file}`);
   const prefix = `${c.source}:`;
   const bareRule = c.rule_id.startsWith(prefix) ? c.rule_id.slice(prefix.length) : c.rule_id;
   return {

package/src/mcp/terraform/versionRequirements.ts

@@ -198,6 +198,15 @@ const ROOT_BECAUSE: Record<RootRequirements["via"], string> = {
     "configures a provider or a backend",
 };
 
+/** the pessimistic pin for the lowest major a constraint admits — `>= 6.42`
+ *  becomes `~> 6.42`, staying on the major the repo already uses rather than
+ *  steering it back to one it has left. */
+function pessimisticFor(constraint: string | null): string {
+  const floor = constraint === null ? null : /(\d+)(?:\.(\d+))?/.exec(constraint);
+  if (!floor) return "`~> <major>.0`, on the major you have tested";
+  return `\`~> ${floor[1]}.${floor[2] ?? "0"}\``;
+}
+
 /** Turn the per-root findings into native concerns. */
 function versionRequirementsToConcerns(roots: RootRequirements[]): Concern[] {
   const concerns: Concern[] = [];
@@ -284,8 +293,8 @@ function versionRequirementsToConcerns(roots: RootRequirements[]): Concern[] {
               : `provider \`${p.name}\` is constrained to \`${p.version}\`, which admits more than one ` +
                 "major — a future `init` can install a new major with no commit in this repo",
           remediation_hint:
-            "Constrain the provider to a single major with the pessimistic operator — `~> 5.0` — or to " +
-            "an exact version. A major renames arguments and removes blocks, which is why the push " +
+            `Constrain the provider to a single major with the pessimistic operator — ${pessimisticFor(p.version)} — ` +
+            "or to an exact version. A major renames arguments and removes blocks, which is why the push " +
             "guardrail refuses a constraint that crosses or floats across one.",
         }),
       );

package/src/modes/__snapshots__/assemblePrompt.test.ts.snap

@@ -410,6 +410,7 @@ exports[`assemblePrompt — outline snapshot per built-in mode > every built-in
       "infraweaver_reply_to_review_comment",
       "infraweaver_resolve_review_thread",
       "infraweaver_review_scan_delta",
+      "infraweaver_stage_review",
     ],
   },
   "UpdateDependencies": {
@@ -656,6 +657,7 @@ exports[`assemblePrompt — outline snapshot per built-in mode > tool references
     "mcp__infraweaver__reply_to_review_comment",
     "mcp__infraweaver__resolve_review_thread",
     "mcp__infraweaver__review_scan_delta",
+    "mcp__infraweaver__stage_review",
   ],
   "UpdateDependencies": [
     "mcp__infraweaver__add_labels",

package/src/modes/modernize-deprecated.ts

@@ -5,7 +5,7 @@ export function modernizeDeprecatedMode(t: ToolRef): Mode {
   return {
     name: "ModernizeDeprecated",
     description:
-      "Migrate deprecated Terraform patterns to their modern equivalents (aws_launch_configuration → aws_launch_template, the template_file data source → the templatefile() function, EOL provider pins), one PR per pattern class. These ALTER the resource set, so they are proven by a reviewed plan delta (or shipped `proposed — unproven`) with a `moved {}` block wherever an address can be preserved; equivalence is never claimed.",
+      "Migrate deprecated Terraform patterns to their modern equivalents (aws_launch_configuration → aws_launch_template, the template_file data source → the templatefile() function, EOL provider pins), one PR per pattern class. These ALTER the resource set, so they are proven by a reviewed plan delta (or shipped proposed — unproven) with a `moved {}` block wherever an address can be preserved; equivalence is never claimed.",
     prompt: `### Checklist
 
 This mode migrates DEPRECATED Terraform patterns to modern ones. Unlike Refactor, these migrations swap a resource TYPE / data source / function and therefore ALTER the resource set — so equivalence is FALSE and must NEVER be claimed (the equivalence guard would block such a claim anyway). The proof is a reviewed plan delta when cloud credentials exist, otherwise the change ships labelled \`proposed — unproven\`. Author a \`moved {}\` block wherever an address genuinely carries over, and use \`create_before_destroy\` where a replace is unavoidable.
@@ -22,7 +22,7 @@ This mode migrates DEPRECATED Terraform patterns to modern ones. Unlike Refactor
 
 6. **prove via plan, never equivalence**: do NOT call \`${t("terraform_equivalence_check")}\` — this change is behaviour-altering and an equivalence claim would be false (and is hard-blocked at push). Instead:
    - **cloud credentials present**: call \`${t("terraform_plan")}\` and attach the **reviewed plan delta**. Treat \`has_destroy_or_replace\`/\`stateful_destructive\` exactly as Remediate — a stateful destroy/replace is hard-blocked at push unless \`allow_replace\` covers it; a high \`blast_radius.tier\` or \`needs_human\` adds the \`needs-human\` label (\`${t("add_labels")}\`) + a prominent callout.
-   - **no credentials**: ship \`proposed — unproven\` — add the label, put the proposed-unproven banner unmissably at the top of the body, and state plainly that this migration ALTERS resources and the plan must be reviewed before merge.
+   - **no credentials**: ship it proposed — unproven — add the \`proposed-unproven\` label (exactly that name), put the proposed-unproven banner unmissably at the top of the body, and state plainly that this migration ALTERS resources and the plan must be reviewed before merge.
    - record the outcome with \`${t("terraform_emit_evidence")}\`.
 
 7. **keep module tests consistent** (if a local module changed): \`${t("terraform_module_tests")}\` — update drifting \`examples/\`/tests, never weaken an assertion.

package/src/modes/refactor.ts

@@ -16,21 +16,21 @@ This mode standardises STRUCTURE while preserving BEHAVIOUR — the equivalence
 2. **detect (two kinds of behaviour-preserving refactor — call BOTH)**:
    - \`${t("module_extraction_candidates")}\` → resource \`clusters\` (raw root resources that should likely be a module call), each with matched \`candidates\` (house modules by resource-type signature; catalogue modules by real signature when terraform init already fetched their content, else by keyword; plus 1–2-resource groups that EXACTLY duplicate an existing module) and per-candidate \`expected_moves\` (every cluster resource → its new module address).
    - \`${t("terraform_normalization_candidates")}\` → in-place idiomatic cleanups that change SYNTAX, not behaviour (redundant whole-string \`"\${expr}"\` interpolation; legacy HCL0.11 map-argument block syntax like \`vars {\` on a \`template_file\`). These relocate NOTHING — zero \`moved {}\` blocks — and are proven by the same equivalence check.
-   - \`${t("terraform_consolidation_candidates")}\` → the SAME resource shape declared in several root directories (\`env/dev\` + \`env/staging\` + \`env/prod\`), with the single parameterised module they could all call already derived: which attributes are identical (module content) and which differ (per-environment inputs). A member root of a group will ALSO show up as a zero-candidate cluster in \`${t("module_extraction_candidates")}\` — prefer the consolidation, which does that work once for every environment instead of once per environment.
+   - \`${t("terraform_consolidation_candidates")}\` → the SAME resource shape declared in several root directories (\`env/dev\` + \`env/staging\` + \`env/prod\`), with the single parameterised module they could all call already derived: which attributes are identical (module content) and which differ (per-environment inputs). A member root of a group will ALSO show up as a zero-candidate cluster in \`${t("module_extraction_candidates")}\` — prefer the consolidation, which does that work once for every environment instead of once per environment. Its \`near_groups\` are the opposite case: roots recognisably the same stack that DIFFER (one carries a resource the other does not), where folding them together is a design decision this mode has no basis for. Do NOT extract a near-group root's shared resources into a module on its own either — a module one twin calls and the other does not widens exactly the drift the near-group reports. Leave those roots alone and name the near-group and its \`differences\` in your report.
 
    **Before picking, check the interface.** \`${t("module_extraction_candidates")}\` reports \`unmapped_attributes\` per candidate and a top-level \`partial_interfaces\` list: arguments the raw resources SET that the target module does not. Adopting such a module DROPS them silently — and the equivalence check cannot catch it, because once the argument is gone it is absent from both sides. Two of these are unrecoverable rather than merely wrong (\`object_lock_enabled\` cannot be set after creation; \`force_destroy\` changes deletion semantics). So: **decline the candidate, or extend the module to expose the argument and say so in the PR body.** Deleting the argument to make the shapes match is never the fix. A candidate whose \`unmapped_attributes\` is \`null\` was NOT checked — the module is external and its code is not in this repo — which is not the same as clean.
 
-   Pick the highest-value refactor across ALL THREE detectors. Only when they ALL come back empty is there genuinely nothing to do: call \`${t("report_progress")}\` with an ACCURATE message — e.g. "No behaviour-preserving refactor found: no extraction clusters and no idiomatic-normalisation candidates." — and **stop**. Two anti-patterns to avoid in that message: (i) never call a repo "already idiomatic" while normalisation candidates remain; (ii) when what's left is behaviour-CHANGING modernisation — a deprecated-resource swap (\`aws_launch_configuration\`→\`aws_launch_template\`, \`aws_elb\`→\`aws_lb\`, \`template_file\`→\`templatefile()\`) — do NOT report "nothing to refactor": that is real work, but it ALTERS the resource set, so it belongs to Remediate. Say so explicitly rather than implying the code is clean.
+   Pick the highest-value refactor across ALL THREE detectors. Only when they ALL come back empty — or all that remains is a cluster in a near-group root — is there genuinely nothing to do: call \`${t("report_progress")}\` with an ACCURATE message — e.g. "No behaviour-preserving refactor found: no extraction clusters and no idiomatic-normalisation candidates." — and **stop**. Two anti-patterns to avoid in that message: (i) never call a repo "already idiomatic" while normalisation candidates remain; (ii) when what's left is behaviour-CHANGING modernisation — a deprecated-resource swap (\`aws_launch_configuration\`→\`aws_launch_template\`, \`aws_elb\`→\`aws_lb\`, \`template_file\`→\`templatefile()\`) — do NOT report "nothing to refactor": that is real work, but it ALTERS the resource set, so it belongs to Remediate. Say so explicitly rather than implying the code is clean.
 
 3. **pick scope — ONE refactor per PR**: take the largest / highest-cohesion extraction cluster, the file(s) with the most normalisation sites, or ONE consolidation group (which is one refactor spanning its member roots — see b.5), first. **Targeted directive override:** if YOUR TASK names specific files/resources, act only on those. Unless the task explicitly asks for more, open **at most one PR this run**.
 
    **If you chose an in-place NORMALISATION** (not a module extraction), nothing relocates: SKIP steps 4–6 (no module source, no wiring, no \`moved {}\` blocks). Apply the \`${t("terraform_normalization_candidates")}\` edits directly (rewrite \`"\${expr}"\` → \`expr\`, \`vars {\` → \`vars = {\`, etc.) — only the literal cleanups, never a resource-type swap — then jump to step 7. The equivalence check (step 8) proves the no-op: same resource set, identical argument names, zero moves.
 
 4. **resolve the module source (risk order — PRESERVING variants only)**: choose where the module code comes from. This mode ships only behaviour-preserving refactors; pick the lowest-risk viable source:
-   - **b.2 — module exists, same repo** (candidate \`kind: local\`): call it by its \`./modules/x\` path. No credential. *Prefer this.*
+   - **b.2 — module exists, same repo** (candidate \`kind: local\`): write the candidate's \`call_source\` as the module block's \`source\` — the path from the calling root, e.g. \`../../modules/x\` from \`env/dev\`. The candidate's \`source\` is repo-relative and resolves only from the repo root. No credential. *Prefer this.*
    - **b.1 — module exists, separate org repo** (candidate \`kind: git\`): use a \`git::…?ref=<pinned-sha>\` source (pin an exact commit, never a branch). The equivalence proof (step 8) attributes the module's resources from what \`terraform init\` fetched at that ref — the init runs inside \`${t("terraform_validate")}\` and the equivalence check itself — so a true relocation into an org module proves \`equivalent: true\` exactly like a local one. If the fetch fails (no access, offline), the module stays invisible to the proof and it DECLINES: fix access or abandon, never relabel. Access is via the GitHub App token (or the operator's read-only deploy key) and is **READ-ONLY** — ⚠️ **NEVER open a write PR against the module repo.** If a concern lives inside the shared module, fix it at the CALL SITE via inputs, or note "fix needed in module repo \`<repo>\`" — do not edit vendored module code. A candidate's \`expected_moves\` for a git module is a TEMPLATE built from the root's own leaf names — correct each \`to\` against the module's REAL resource addresses (read the fetched module, or the equivalence check's \`uncovered_moves\`/\`resource_set_diff\` will name them).
-   - **b.3 — no module exists, author it** (no candidate): MECHANICAL extraction. Take the cluster's existing resource blocks, move them verbatim into \`./modules/<name>/\`, parameterise each hardcoded value into a \`variable\` (with a SECURE \`default\`, or **no default** so the caller must set it — NEVER preserve an insecure value as a default), expose the needed \`output\`s, and replace the root resources with a \`module\` block passing the ORIGINAL values. You do the naming + structure; the equivalence check (step 8) is the guardrail that proves you changed nothing.
-   - **b.5 — consolidation: one module, N environment roots** (a \`${t("terraform_consolidation_candidates")}\` group): the b.3 extraction done once for a shape several roots duplicate. Author \`./modules/<name>/\` from the group's resources, then convert EVERY member root in this same PR. Rules that are not optional: (i) move each resource block **verbatim, keeping its resource name** — the group's \`expected_moves_by_member\` assumes the leaf name survives, and renaming it to \`this\` invalidates every move; (ii) put each \`module_body_values\` entry in the module exactly as written — \`kind: "attribute"\` is a right-hand side (\`bucket = <value>\`), \`kind: "block"\` is a nested block's BODY and goes back inside its own braces (\`versioning_configuration { <value> }\`), never as \`versioning_configuration = { … }\`; (iii) replace ONLY the \`variables\` attributes with \`var.<name>\`, and copy each member's \`per_member.value\` into THAT member's call **verbatim — never retyped, never reformatted, never swapped between environments**. A \`classification: reference\` variable (identical text like \`var.bucket_name\` in every root) is still per-environment: the text matches, the value does not. Never fold differing values into one interpolated template (\`"acme-\${var.env}-logs"\`) — the job is to preserve N values, not to invent a rule that reproduces them. Paste each root's \`moved {}\` blocks, then prove ALL the roots with a single \`${t("terraform_equivalence_check")}\`.
+   - **b.3 — no module exists, author it** (no candidate): MECHANICAL extraction. Take the cluster's existing resource blocks, move them verbatim into \`./modules/<name>/\`, parameterise each hardcoded value into a \`variable\` (with a SECURE \`default\`, or **no default** so the caller must set it — NEVER preserve an insecure value as a default), expose the needed \`output\`s, and replace the root resources with a \`module\` block passing the ORIGINAL values. Its \`source\` is relative to the root's directory: \`../../modules/<name>\` from \`env/dev\`, \`./modules/<name>\` only from the repo root. You do the naming + structure; the equivalence check (step 8) is the guardrail that proves you changed nothing.
+   - **b.5 — consolidation: one module, N environment roots** (a \`${t("terraform_consolidation_candidates")}\` group): the b.3 extraction done once for a shape several roots duplicate. Author \`./modules/<name>/\` from the group's resources, then convert EVERY member root in this same PR; each member's call writes that member's \`call_source\` as its \`source\`. Rules that are not optional: (i) move each resource block **verbatim, keeping its resource name** — the group's \`expected_moves_by_member\` assumes the leaf name survives, and renaming it to \`this\` invalidates every move; a \`module\` entry in the group's \`resources\` is a module CALL the shape includes — move that call block too, keeping its name, and write its \`wrapped_calls[].source\` (relative to the NEW module, e.g. \`../s3\`) as its \`source\`, since the root's \`../../modules/s3\` no longer resolves from there; (ii) put each \`module_body_values\` entry in the module exactly as written — \`kind: "attribute"\` is a right-hand side (\`bucket = <value>\`), \`kind: "block"\` is a nested block's BODY and goes back inside its own braces (\`versioning_configuration { <value> }\`), never as \`versioning_configuration = { … }\`; (iii) replace ONLY the \`variables\` attributes with \`var.<name>\`, and copy each member's \`per_member.value\` into THAT member's call **verbatim — never retyped, never reformatted, never swapped between environments**. A \`classification: reference\` variable (identical text like \`var.bucket_name\` in every root) is still per-environment: the text matches, the value does not. Never fold differing values into one interpolated template (\`"acme-\${var.env}-logs"\`) — the job is to preserve N values, not to invent a rule that reproduces them. Paste each root's \`moved {}\` blocks, then prove ALL the roots with a single \`${t("terraform_equivalence_check")}\`.
    - **b.4 — third-party module (behaviour-ALTERING)**: adopting a community/registry module changes defaults and often adds resources, so equivalence is FALSE and must **never** be claimed. This is a DIFFERENT proof (a reviewed plan delta, opt-in; \`proposed — unproven\` by default) — follow the **b.4 path** at the end of this checklist INSTEAD of steps 5–12's equivalence gate. Reserve it for a genuine module adoption; a plain relocation of your own resources is b.1/b.2/b.3.
 
 5. **wire the module call**: get the chosen module's REAL interface so the \`module\` block passes its actual \`variable\` names (a missing required variable is a PR question for the reviewer, never a guessed value). For a LOCAL module dir (b.2/b.3) call \`${t("terraform_module_interface")}\`; for a REGISTRY-sourced module — a \`module_catalogue\` entry like \`terraform-aws-modules/vpc/aws\`, or the b.4 adoption — call \`${t("terraform_module_lookup")}\` to read its published \`required_inputs\`/\`outputs\` + resolved \`version\` from the registry. \`${t("terraform_module_graph")}\` shows existing local module dirs + callers. Apply the same secure-default discipline as Remediate: a parameterised value's default must be the secure choice or absent — never a hidden-insecure default.
@@ -42,7 +42,7 @@ This mode standardises STRUCTURE while preserving BEHAVIOUR — the equivalence
 8. **PROVE equivalence (the gate)**: call \`${t("terraform_equivalence_check")}\`. It compares the working tree against the run-start commit and must return \`equivalent: true\` — meaning: same resource multiset (\`resource_set_diff\` empty), identical per-resource argument names, **zero \`uncovered_moves\`**, and validate + fmt clean. If \`equivalent\` is false:
    - any \`uncovered_moves\` → add the missing \`moved {}\` block(s) for those addresses and re-run;
    - a non-empty \`resource_set_diff.added\`/\`removed\` or \`arg_diffs\` → the refactor changed behaviour; fix it back to a true no-op, or ABANDON the cluster (it may be a behaviour-altering adoption — see step 4).
-   - a non-empty \`value_mismatches\` (\`values_preserved: false\`) → a relocated argument's VALUE changed: the check resolved \`var.<x>\` back through the call site and it no longer yields what that root had. This is the b.5 failure nothing else can see — the resource set, the argument names, the moves, validate and even a plan are all clean, and the apply applies another environment's configuration. Each row names the root, the argument, the \`before\` value and what it now resolves to: put that root's OWN value back at its OWN call site, copied verbatim from the before tree.
+   - a non-empty \`value_mismatches\` (\`values_preserved: false\`) → a VALUE changed: the check follows each value — \`var.<x>\` back through the call site, locals, module outputs, data sources, nested and \`dynamic\` blocks — and it no longer yields what the before tree had. This is the b.5 failure nothing else can see — the resource set, the argument names, the moves, validate and even a plan are all clean, and the apply applies another environment's configuration. Each row names the root, the resource, the argument path, the \`before\` value and what it now resolves to: put that root's OWN value back at its OWN call site, copied verbatim from the before tree. A row on a resource you did not move means a shared module's body or an untouched call site changed under it — undo that edit.
    - a \`verdict: "unverifiable"\` naming a repetition that moved between levels → the per-key \`moved {}\` blocks are the right shape and the proof will not evaluate the \`for_each\` expression to confirm the key set is complete. This is the ONE case a plan settles: run \`${t("terraform_plan")}\` and reach \`refactor_safe: true\` on the tree you are pushing, and the push is allowed with the verdict left at \`unverifiable\` (never restated as proven). Without cloud credentials, escalate the cluster rather than pushing.
    Do not proceed to push until \`equivalent: true\`, or until that one \`unverifiable\` is plan-corroborated. **Optional stronger proof:** when cloud credentials are present, call \`${t("terraform_plan")}\` — a \`refactor_safe: true\` (pure-move) plan corroborates the keys-free proof; attach the plan to the PR. Then **re-run \`${t("terraform_equivalence_check")}\`** so the plan's own reading of what moved folds into the recorded proof (\`plan_corroborated: true\`). Make no edits between the two calls — the pairing is tied to the exact tree the plan saw and is discarded if the tree changed.
 
@@ -52,7 +52,7 @@ This mode standardises STRUCTURE while preserving BEHAVIOUR — the equivalence
 
 11. **branch + commit + push**: create \`infraweaver/refactor-<slug>\` from the **current HEAD** (the scanned checkout) via \`${t("git")}\` — do NOT switch base first. \`git add\` only the files you changed, commit with a message naming the module + cluster (e.g. \`refactor(tf): extract S3 logging resources into module.logging\`), then \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*). The push guardrails enforce Terraform-only paths, no inlined secrets, AND the equivalence hard-fail — which refuses an unproven refactor AND one that recorded no proof at all, so skipping step 8 blocks the push rather than slipping past it.
 
-12. **open the PR (MANDATORY body)**: \`${t("create_pull_request")}\` (omit \`base\` — it resolves to the run's base branch). Build the body with the **Refactor PR format** at the end of this checklist — status banner → title → \`## What changed\` (include the adopted candidate's \`selection_reason\` VERBATIM; if you omit it, \`${t("create_pull_request")}\` appends it under \`### Module selection\`) → \`## Equivalence proof\` (built ONLY from \`${t("terraform_equivalence_check")}\`, the proof not a self-report) → composition note. Optionally call \`${t("terraform_emit_evidence")}\` — it records the equivalence statement with the proof behind it; when its result says \`signed: true\`, add a one-line evidence note to the PR body naming the artefact and the signing key fingerprint (\`key_fingerprint_sha256\`) so a reviewer can verify with \`infraweaver verify-evidence\`. Never auto-merge.
+12. **open the PR (MANDATORY body)**: \`${t("create_pull_request")}\` (omit \`base\` — it resolves to the run's base branch). Build the body with the **Refactor PR format** at the end of this checklist — status banner → title → \`## What changed\` (include the adopted candidate's \`selection_reason\` VERBATIM; if you omit it, \`${t("create_pull_request")}\` appends it under \`### Module selection\`) → \`## Equivalence proof\` (built ONLY from \`${t("terraform_equivalence_check")}\`, the proof not a self-report) → composition note. Optionally call \`${t("terraform_emit_evidence")}\` — it records the equivalence statement with the proof behind it; when its result says \`signed: true\`, add a one-line evidence note to the PR body naming the artefact and the signing key fingerprint (\`key_fingerprint_sha256\`) so a reviewer can verify with \`infraweaver verify-evidence\`. Never auto-merge. If \`${t("create_pull_request")}\` refuses because an open PR already changes the same files, that PR is this refactor waiting for review: delete the branch you pushed and report it — never re-open under another branch name.
 
 13. **finalize**: call \`${t("report_progress")}\` once with a summary — which cluster was modularised, into which module, the PR link, and the equivalence verdict (or the exact tool error if a step failed).
 
@@ -61,11 +61,11 @@ This mode standardises STRUCTURE while preserving BEHAVIOUR — the equivalence
 Use this ONLY when the chosen source is a community/registry module that changes behaviour — equivalence is false here and must NEVER be claimed. The proof is a reviewed plan delta, gated behind opt-in read creds; by default the change ships labelled \`proposed — unproven\` and asserts nothing about runtime.
 
 - **Find + read the module**: when the operator's \`module_catalogue\` / \`refactor_source\` doesn't already name the module, call \`${t("terraform_module_search")}\` to find a published one — pass your org's \`namespace\` to prefer your OWN vetted modules over a stranger's. Search covers the PUBLIC registry only: a private-registry module must be named in \`module_catalogue\` / \`refactor_source\`, or looked up directly by its \`host/namespace/name/provider\` address. Then call \`${t("terraform_module_lookup")}\` on the chosen \`namespace/name/provider\` to read its \`required_inputs\` / \`outputs\` + latest \`version\`, so the \`module\` block wires the real interface and pins an exact version.
-- **Scan with external-module resolution ON**: call \`${t("terraform_scan")}\` with \`download_external_modules: true\` (and verify with \`${t("terraform_verify_remediation")}\`'s \`download_external_modules: true\`) so the adopted module's INTERNALS stay in scope. Skipping it would let the module's findings vanish unfixed — a false ✗→✓ ("finding-laundering"). Non-negotiable.
+- **Scan with external-module resolution ON**: call \`${t("terraform_scan")}\` with \`download_external_modules: true\` (and verify with \`${t("terraform_verify_remediation")}\`'s \`download_external_modules: true\`) so the adopted module's INTERNALS stay in scope. Skipping it would let the module's findings vanish unfixed — a false ✗→✓ ("finding-laundering"). Non-negotiable. A finding inside the module is reported on the line of the \`module\` block that calls it, with the module resource it is about named in the evidence ("— inside the module: module.data.aws_s3_bucket.this (main.tf:25)").
 - **Remediate module-sourced findings via INPUTS**: set the hardening variable at the call site — never edit vendored module code. Where the module exposes no knob for a control, label it \`needs-fork\` and surface it; never a silent pass.
 - **Pin the exact version**: a registry \`version\` or a git \`?ref=<sha>\` (provenance discipline — the analog to a SHA-pinned action); it is recorded in the evidence bundle.
 - **Proof**:
-   - **Default (no read creds)**: do NOT run a plan. Call \`${t("terraform_emit_evidence")}\` with \`proposed_unproven: true\` **before you push** — the bundle records that the change asserts nothing about runtime, and \`${t("push_branch")}\` refuses a refactor that reaches a reviewer with neither a proof nor that marker. Then add the \`proposed-unproven\` label (\`${t("add_labels")}\`) and put the proposed-unproven banner unmissably at the top of the body. It must NEVER read as a proven / equivalence change.
+   - **Default (no read creds)**: do NOT run a plan. Call \`${t("terraform_emit_evidence")}\` with \`proposed_unproven: true\` **before you push** — the bundle records that the change asserts nothing about runtime (commit the file it writes with the change, unedited: the push admits exactly those bytes), and \`${t("push_branch")}\` refuses a refactor that reaches a reviewer with neither a proof nor that marker. Then add the \`proposed-unproven\` label (\`${t("add_labels")}\`) and put the proposed-unproven banner unmissably at the top of the body. It must NEVER read as a proven / equivalence change.
    - **Opt-in (read-only backend/state supplied)**: call \`${t("terraform_plan")}\` **before you push**, then record the outcome with \`${t("terraform_emit_evidence")}\` passing \`reviewed_plan: true\` (refused if no plan ran) — that marker is what the push gate accepts for a behaviour-altering adoption; a plan alone no longer discharges it. Emit the **reviewed plan delta** in the PR body as the proof (replacing the proposed-unproven section). No supplied credential is stored, and no plan attribute VALUES are kept — only the aggregate totals and affected addresses the push gates read.
 - Same guardrails: one cluster per PR, never auto-merge, Terraform-only, never write-PR a read-only module repo.
 

package/src/modes/remediate.ts

@@ -33,7 +33,7 @@ export function remediateMode(t: ToolRef): Mode {
    **Bulk remediation (\`fix rule <rule-id>\` / \`fix all rule <rule-id>\`)**: a request to fix ONE scanner rule everywhere it fires (e.g. \`${COMMENT_COMMAND} fix rule CKV_AWS_23\` — "add a description to every security group", or \`fix rule terraform_required_version\`). Re-scan with \`group_by: "rule"\` so that rule becomes ONE group spanning every file, then act on the single group whose \`rule_ids\` include \`<rule-id>\` — apply the SAME minimal fix at every site in its \`files\` and open ONE coherent PR (not one per file). This is the sweep path; still honour \`max_prs\` and never batch a \`needs-human\` group. Cite each fixed site in the PR body.
 
 4. **for the chosen group**:
-   - **base branch**: this run's base branch is resolved deterministically — \`${t("create_pull_request")}\` targets the \`base_branch\` input if set, else the repository's default branch (\`main\`, or \`master\`). You do not choose it; just **omit** the \`base\` argument when opening the PR (below) and it is filled in.
+   - **base branch**: this run's base branch is resolved deterministically — \`${t("create_pull_request")}\` targets the \`base_branch\` input if set, else the branch the run started on, else the repository's default branch (\`main\`, or \`master\`). You do not choose it; just **omit** the \`base\` argument when opening the PR (below) and it is filled in.
    - **idempotency**: the remediation branch is \`remediate/<group-id>\`. Before doing anything, check whether that branch or an open PR for it already exists (\`${t("git")}\` / \`${t("get_pull_request")}\`). If one exists, update it rather than opening a duplicate.
    - **branch**: create \`remediate/<group-id>\` from the **current HEAD** (the checkout that was just scanned) via \`${t("git")}\` (\`git checkout -b remediate/<group-id>\`). Do NOT switch to a different base first — branching from the scanned checkout keeps the PR diff to exactly your fix.
    - **honest refusal (decide BEFORE fixing)**: if the group's concerns appear in the scan's \`refusal_candidates\` (the fix needs a human decision — narrowing an IAM wildcard, a KMS key policy, a real ingress CIDR), do **not** guess a fix that could break the stack. Instead open a structured issue (\`${t("create_issue")}\`) describing the concern, why it isn't auto-fixed, and what a human should do, and skip the PR for that group. A proven fix or an honest refusal — never a guessed, unverifiable PR.

package/src/modes/terraform-code-review.ts

@@ -29,9 +29,10 @@ This mode reviews the **Terraform** in a human PR and submits ONE review. It is
 
 4. **introduced findings — comment or dismiss each one**: for EVERY introduced finding the delta lists (the most severe first; past its limit it only counts the rest, which need nothing from you), read the cited code and decide:
    - **comment**: an inline comment on the changed line, with \`finding_id\` set to that finding's id and an \`audit\` filled from your verification pass. Explain the concrete consequence in this configuration, not the rule's generic text. The tool adds the scanner, rule and mapped controls itself — do not restate them.
-   - **dismiss**: list it in \`dismissed\` with the specific reason it needs no comment here — a named sibling resource or module default already satisfies the control, the resource is not instantiated (\`count = 0\`), or the rule does not fit this configuration for a stated reason. "Not important" is not a reason. A finding marked \`possibly_preexisting\` is usually a rename, or a move into another module, without a \`moved\` block: say that (and whether a \`moved\` block is needed) rather than treating the misconfiguration as new.
+   - **dismiss**: list it in \`dismissed\` with the specific reason it needs no comment here — a named sibling resource or module default already satisfies the control, the resource is not instantiated (\`count = 0\`), or the rule does not fit this configuration for a stated reason. "Not important" is not a reason. A finding marked \`possibly_preexisting\` is usually a rename, or a move into another module, without a \`moved\` block (\`renamed_from\` names the resource it pairs with): the review's verdict already names each such resource once, so make ONE comment per renamed resource giving the \`moved\` block it needs, and dismiss its other findings as part of that rename rather than treating each misconfiguration as new.
    **One comment per root cause.** When several introduced findings are the same problem on the same lines (two scanners flagging one open ingress rule), comment once with the most specific \`finding_id\` and dismiss the others as duplicates of that comment.
    The review tool refuses once if any introduced finding is neither commented nor dismissed; on the retry it names the rest to the author as unaddressed.
+   **A comment limit is not yours to apply.** The repo may set \`review_comment_limit\`; the tool enforces it after you submit, keeping the most severe comments inline and listing the rest in the review body. Comment on or dismiss every introduced finding exactly as you would without one — never leave a finding unaddressed, or fold it into prose, because of a limit.
 
 5. **suggestions**: offer a \`suggestion\` only on a scanner-backed comment whose fix fits inside that comment's own line range [start_line, line], preserving exact indentation. The tool applies it to a scratch copy, re-runs fmt, validate and every scanner, and makes it committable only if the finding is gone and nothing new appeared ("Proven by re-scan"); otherwise it is shown as plain code marked "Unproven". A fix that needs another resource, a new variable or lines outside the range is described in prose instead — it cannot be proven from a line range. A judgement's suggestion is always shown as unproven code.
 
@@ -54,9 +55,11 @@ This mode reviews the **Terraform** in a human PR and submits ONE review. It is
 
    When the finding under test is a **cloud-misconfig** (public exposure, missing encryption, over-broad IAM, open ingress), the verification dispatch MUST include the Terraform-security refute lens above in addition to the generic charge — these IaC false-positive patterns (a separate hardening resource, a disabled resource, a call-site override) are exactly what a generic code lens misses. A scanner-backed finding the refute lens knocks down is DISMISSED with that reason, not silently dropped.
 
-   Every 🚨/⚠️ comment — and every scanner-backed comment — carries an \`audit\`; one without is withheld. Then ALWAYS submit exactly one review via \`${t("create_pull_request_review")}\` (never \`report_progress\` for review output), with \`comments\` (anchored to NEW line numbers) and \`dismissed\`. Non-anchorable concerns go in the body \`### \` sections. The tool opens the body with the verdict (merge-blocking or not, and the author's next steps) and closes it with the scan delta — counts, gate, controls, dismissals and suggestion proofs — so do not restate those yourself.
+   A \`betterleaks:\` finding is a secret the PR's commits add, in any file, Terraform or not: answer it like any scanner finding, and never quote, decode or guess its value — say which file and line holds it and that it must be removed from the history and rotated.
 
-   Same opening-callout ladder + \`approved\` lever as Review — \`[!CAUTION]\` (a state-destroying or security-breaking change) → \`[!IMPORTANT]\` (a real misconfig to fix before merge; at least this tier whenever an introduced high/critical finding stands after verification) → \`> ℹ️ ...\` (minor HCL/style nits) → \`> ✅ No new issues found.\` (mergeable, \`approved: true\`, no inline comments). Pick the tier the author's actual next action justifies. note: the first \`create_pull_request_review\` submission may error with a one-time diff-coverage, audit or scan-delta nudge — fix what it names and retry.
+   Every 🚨/⚠️ comment — and every scanner-backed comment — carries an \`audit\`; one without is withheld. Then ALWAYS submit exactly one review via \`${t("create_pull_request_review")}\` (never \`report_progress\` for review output), with \`comments\` (anchored to NEW line numbers) and \`dismissed\`. Non-anchorable concerns go in the body \`### \` sections. With more than about 10 comments and dismissals in all, stage them first with \`${t("stage_review")}\` in calls of up to 10 — one dismissal entry can carry several \`finding_ids\` that share a reason — and then submit \`${t("create_pull_request_review")}\` with the body alone: one oversized call can be cut off mid-way and cost the whole review. The tool opens the body with the verdict (merge-blocking or not, and the author's next steps) and closes it with the scan delta — counts, gate, controls, dismissals and suggestion proofs — so do not restate those yourself.
+
+   Same opening-callout ladder + \`approved\` lever as Review — \`[!CAUTION]\` (a state-destroying or security-breaking change) → \`[!IMPORTANT]\` (a real misconfig to fix before merge; at least this tier whenever an introduced high/critical finding stands after verification) → \`> ℹ️ ...\` (minor HCL/style nits) → \`> ✅ No new issues found.\` (mergeable, \`approved: true\`, no inline comments). Pick the tier the author's actual next action justifies. note: the first \`create_pull_request_review\` submission may error with a one-time diff-coverage, audit or scan-delta nudge — fix what it names (stage what it asks for) and retry.
 
 9. **guardrails**: never modify \`*.tf\`/\`*.tfvars\`, never commit/push, never open a PR or issue. Only Terraform files are in scope. The review is the only deliverable.