infraweaver 0.3.9 → 0.3.11

package/src/mcp/terraform/hardcodedSecrets.ts

@@ -0,0 +1,202 @@
+/**
+ * A credential written into the configuration as a string literal, by the
+ * name of the argument that holds it.
+ *
+ * WHY BY NAME. The secret scanners look at the VALUE — a known key format, or a
+ * string with enough entropy — so a hand-made password (`"cg-flagshop-Pr0d!…"`)
+ * slips past all of them. Terraform says more than a text scanner can see: the
+ * value sits in an argument, a map key or a variable whose name says what it
+ * holds. A literal in `password`, `client_secret` or a Lambda environment
+ * variable called `auth` is in the repository whatever it looks like.
+ *
+ * WHAT IS READ. Every `name = "…"` line inside a `resource`, `data`,
+ * `provider`, `module` or `locals` block, at any depth, so
+ * `environment { variables = { auth = "…" } }` and `jsonencode({ … })` objects
+ * are reached; and the `default` of a `variable` whose name is a secret's. Not
+ * read: comments, heredoc bodies, a name/value pair split across two keys
+ * (`[{ name = "PASSWORD", value = "…" }]`), and a value that starts on a later
+ * line than its name.
+ *
+ * WHAT IS NOT A FINDING. A reference, a function call, an interpolation, an
+ * empty string, or a placeholder made only of `*` / `x` / `<…>`. Neither is an
+ * argument whose name only mentions a secret (`password_length`, `secret_name`,
+ * `token_validity_units`, `creation_token`): the last word of the name decides.
+ *
+ * Arguments the provider can take write-only (`aws_db_instance.password`) may
+ * also be reported by `secret-persisted-to-state`, which says something else:
+ * that the value reaches state. This one says it is in git.
+ */
+
+import { isStringLiteral, stripTrailingComment } from "#app/mcp/terraform/hcl";
+import { HARDCODED_SECRET_ARGUMENT, NATIVE_SOURCE } from "#app/mcp/terraform/nativeRules";
+import type { SourceFile } from "#app/mcp/terraform/tree";
+import { buildConcern, type Concern } from "#app/mcp/terraform/types";
+
+/** a name's last word, alone, says it holds a secret. */
+const SECRET_WORDS = new Set([
+  "password",
+  "passwd",
+  "pwd",
+  "passphrase",
+  "secret",
+  "token",
+  "auth",
+  "apikey",
+  "credential",
+  "credentials",
+]);
+/** `<word>_key` names that hold a secret (`api_key`, `secret_key`, …). */
+const SECRET_KEY_PREFIXES = new Set(["api", "secret", "private", "signing"]);
+/** `<word>_token` names that are identifiers, not credentials. */
+const NOT_SECRET_TOKENS = new Set(["creation", "idempotency", "client", "request", "continuation"]);
+
+function words(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase()
+    .split(/[_-]+/)
+    .filter(Boolean);
+}
+
+/** True when an argument, map key or variable called `name` holds a secret. */
+export function isSecretName(name: string): boolean {
+  const w = words(name);
+  const last = w.at(-1);
+  const prev = w.at(-2);
+  if (last === undefined) return false;
+  if (last === "key") return prev !== undefined && SECRET_KEY_PREFIXES.has(prev);
+  if (last === "token" && prev !== undefined && NOT_SECRET_TOKENS.has(prev)) return false;
+  return SECRET_WORDS.has(last);
+}
+
+/** A literal that says it is not a real value: empty, masked, or `<…>`. */
+function isPlaceholder(inner: string): boolean {
+  return (
+    inner.trim() === "" ||
+    /^[*xX.]+$/.test(inner) ||
+    /^<[^>]*>$/.test(inner) ||
+    // the dummy credentials offline plans and LocalStack are given (`secret_key = "test"`)
+    /^(?:test|mock|fake|dummy|fixture|example|placeholder|sample)(?:[_-].*)?$/i.test(inner) ||
+    // a token's lifetime unit: `token_validity_units { access_token = "hours" }`
+    /^(?:seconds|minutes|hours|days)$/.test(inner)
+  );
+}
+
+export interface HardcodedSecret {
+  /** the argument, map key or variable name. */
+  name: string;
+  /** what holds it: `resource "aws_lambda_function" "x"`, `variable "db_password"`, … */
+  holder: string;
+  line: number;
+}
+
+/** a top-level block header: `resource "aws_db_instance" "db" {`, `locals {` */
+const HEADER = /^(resource|data|provider|module|locals|variable|output|terraform)\b([^{]*)\{\s*$/;
+/** `name = value`, the name bare or quoted */
+const ASSIGNMENT = /^\s*(?:"([A-Za-z_][\w-]*)"|([A-Za-z_][\w-]*))\s*=(?!=)\s*(.*)$/;
+const HEREDOC = /<<-?([A-Za-z_]\w*)\s*$/;
+/** a `key = "string"` pair inside a one-line object */
+const INLINE_PAIR = /(?:"([A-Za-z_][\w-]*)"|\b([A-Za-z_][\w-]*))\s*=(?!=)\s*("(?:[^"\\]|\\.)*")/g;
+
+function literalValue(raw: string): boolean {
+  const value = stripTrailingComment(raw).replace(/,$/, "").trim();
+  return isStringLiteral(value) && !isPlaceholder(value.slice(1, -1));
+}
+
+/**
+ * Every secret-named literal in one file. Pure.
+ *
+ * One pass over the lines rather than a block parse: every assignment line is
+ * the same question whatever block it sits in, and the native pack's block
+ * parser is shared by every scanner and budgeted (see nativeScan.perf.test).
+ */
+export function findHardcodedSecrets(hcl: string): HardcodedSecret[] {
+  const out: HardcodedSecret[] = [];
+  let holder: string | null = null;
+  let heredoc: string | null = null;
+  let inComment = false;
+  const lines = hcl.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = (lines[i] as string).replace(/\r$/, "");
+    if (heredoc !== null) {
+      if (line.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    if (inComment) {
+      if (line.includes("*/")) inComment = false;
+      continue;
+    }
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("/*")) {
+      inComment = !trimmed.includes("*/");
+      continue;
+    }
+    if (trimmed.startsWith("#") || trimmed.startsWith("//")) continue;
+    const header = HEADER.exec(line);
+    if (header) {
+      holder = `${header[1]}${(header[2] as string).trimEnd() ? ` ${(header[2] as string).trim()}` : ""}`;
+      continue;
+    }
+    if (line.startsWith("}")) {
+      holder = null;
+      continue;
+    }
+    const opens = HEREDOC.exec(line);
+    if (opens) heredoc = opens[1] as string;
+    if (holder === null || opens) continue;
+    const m = ASSIGNMENT.exec(line);
+    if (!m) continue;
+    const name = (m[1] ?? m[2]) as string;
+    const value = m[3] as string;
+    if (holder.startsWith("variable ")) {
+      // a variable's literal is its default, and the variable's name says what it holds
+      const variable = /^variable\s+"?([\w-]+)"?/.exec(holder)?.[1] ?? "";
+      if (name === "default" && isSecretName(variable) && literalValue(value)) {
+        out.push({ name: variable, holder, line: i + 1 });
+      }
+      continue;
+    }
+    if (holder.startsWith("output ") || holder.startsWith("terraform")) continue;
+    if (isSecretName(name) && literalValue(value)) {
+      out.push({ name, holder, line: i + 1 });
+      continue;
+    }
+    // an object written on one line holds its own pairs: `{ "DB_PASSWORD" = "…" }`
+    for (const pair of value.matchAll(INLINE_PAIR)) {
+      const key = (pair[1] ?? pair[2]) as string;
+      if (isSecretName(key) && literalValue(pair[3] as string)) {
+        out.push({ name: key, holder, line: i + 1 });
+      }
+    }
+  }
+  return out;
+}
+
+/** Scan an already-read tree into native concerns. Pure; no I/O of its own. */
+export function scanHardcodedSecrets(files: readonly SourceFile[]): Concern[] {
+  const concerns: Concern[] = [];
+  for (const { path, hcl } of files) {
+    for (const hit of findHardcodedSecrets(hcl)) {
+      concerns.push(
+        buildConcern({
+          source: NATIVE_SOURCE,
+          rule: HARDCODED_SECRET_ARGUMENT,
+          file: path,
+          line: hit.line,
+          // a credential in the repository is readable by everyone who can read
+          // it, and stays in the history after it is edited out
+          severity: "high",
+          category: "security",
+          evidence:
+            `\`${hit.name}\` in \`${hit.holder}\` is a string literal, so the credential it holds is ` +
+            "committed to the repository (value not quoted here)",
+          remediation_hint:
+            "Rotate the credential first — it stays in the branch history after the line is changed. " +
+            "Then pass it in at run time: a `sensitive` variable with no default, or a read from a " +
+            "secret store (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager).",
+        }),
+      );
+    }
+  }
+  return concerns;
+}

package/src/mcp/terraform/nativeRuleScanners.ts

@@ -26,6 +26,7 @@
 
 import { scanDialect } from "#app/mcp/terraform/dialect";
 import { scanGovernanceFile } from "#app/mcp/terraform/governance";
+import { scanHardcodedSecrets } from "#app/mcp/terraform/hardcodedSecrets";
 import { scanInterfaceHygiene } from "#app/mcp/terraform/moduleInterfaceRules";
 import { scanUnpinnedModules } from "#app/mcp/terraform/moduleVersionConstraints";
 import {
@@ -34,6 +35,7 @@ import {
   DEPRECATED_S3_BUCKET_ARGUMENT,
   DEPRECATED_STATE_LOCKING,
   DYNAMIC_DESTROY_PROTECTION,
+  HARDCODED_SECRET_ARGUMENT,
   IMPERATIVE_ACTION_TRIGGER,
   LEGACY_BLOCK_ASSIGNMENT,
   LEGACY_INTERPOLATION,
@@ -125,6 +127,12 @@ export const NATIVE_RULE_SCANNERS: readonly NativeRuleScanner[] = [
     // one. See [[stateFiles]].
     scan: (ctx) => scanCommittedStateFiles(ctx.cwd),
   },
+  {
+    name: "hardcoded-secrets",
+    rules: [HARDCODED_SECRET_ARGUMENT],
+    // Per file: the argument's name and its literal are both on the line itself.
+    scan: (ctx) => ({ concerns: scanHardcodedSecrets(ctx.files) }),
+  },
   {
     name: "write-only",
     rules: [SECRET_PERSISTED_TO_STATE],

package/src/mcp/terraform/nativeRules.ts

@@ -59,6 +59,7 @@ export interface NativeRule {
 
 export const SECRET_PERSISTED_TO_STATE = "secret-persisted-to-state";
 export const COMMITTED_STATE_FILE = "committed-state-file";
+export const HARDCODED_SECRET_ARGUMENT = "hardcoded-secret-argument";
 export const IMPERATIVE_ACTION_TRIGGER = "imperative-action-trigger";
 export const DYNAMIC_DESTROY_PROTECTION = "dynamic-destroy-protection";
 export const DEPRECATED_STATE_LOCKING = "deprecated-state-locking";
@@ -103,6 +104,19 @@ export const NATIVE_RULES: readonly NativeRule[] = [
       "that the state contains a live credential, or that anyone has read it — the file is never opened; " +
       "the finding is that state is under version control, and what it recorded is for the owner to say",
   },
+  {
+    id: HARDCODED_SECRET_ARGUMENT,
+    title: "Credential written into the configuration as a literal",
+    band: "verified",
+    category: "security",
+    asserts:
+      "an argument, map key or variable whose name says it holds a credential (`password`, `token`, " +
+      "`client_secret`, `api_key`, …) is assigned a string literal, so the value is in the repository " +
+      "and in its history",
+    doesNotAssert:
+      "that the value is a live credential — it may be a test value; the finding is that a credential " +
+      "slot is filled from the code rather than at run time",
+  },
   {
     id: IMPERATIVE_ACTION_TRIGGER,
     title: "Imperative side-effect invoked from declarative IaC (action / action_trigger)",

package/src/mcp/terraform/refactorScope.ts

@@ -0,0 +1,86 @@
+/**
+ * What a Refactor run may propose, beyond what the detectors find.
+ *
+ * EXAMPLES ARE NOT REFACTORED BY DEFAULT. An `examples/` root is documentation
+ * that happens to plan: its resources exist to show a caller how to use the
+ * module, so they repeat on purpose, and a PR that consolidates or extracts them
+ * rewrites the docs to save nobody anything. The `refactor_examples` input opts
+ * back in.
+ *
+ * A REUSABLE MODULE IS REPORTED, NOT RESTRUCTURED. A repository whose root
+ * configures no provider and no backend, and ships `examples/`, is a module other
+ * people call (terraform-aws-vpc, say). Moving its resources into a submodule is
+ * provably equivalent, and still churn for every consumer: their plans gain a
+ * wall of `moved` addresses for no change in what they get. There, extraction
+ * and normalisation candidates come back marked `report_only` — named in the
+ * run's summary, never opened as a PR. Consolidating roots that duplicate each
+ * other is unaffected: that removes real duplication, not style.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** true for a path inside an `examples/` (or `example/`) directory, at any depth. */
+export function isExamplePath(path: string): boolean {
+  return /(?:^|\/)examples?\//.test(path.replace(/\\/g, "/"));
+}
+
+const PROVIDER_OR_BACKEND = /^\s*(?:provider\s+"|backend\s+")/m;
+
+/** whether some directory under `dir` (to a small depth) holds a `.tf` file. */
+function holdsTerraform(dir: string, depth: number): boolean {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return false;
+  }
+  for (const name of entries) {
+    const path = join(dir, name);
+    if (name.endsWith(".tf")) return true;
+    if (
+      depth > 0 &&
+      !name.startsWith(".") &&
+      statSync(path, { throwIfNoEntry: false })?.isDirectory()
+    ) {
+      if (holdsTerraform(path, depth - 1)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Why the repository at `cwd` reads as a reusable module rather than a
+ * deployment, or null when it does not.
+ */
+export function libraryRepoReason(cwd: string): string | null {
+  let rootFiles: string[];
+  try {
+    rootFiles = readdirSync(cwd).filter((f) => f.endsWith(".tf"));
+  } catch {
+    return null;
+  }
+  if (rootFiles.length === 0) return null;
+  for (const f of rootFiles) {
+    let text: string;
+    try {
+      text = readFileSync(join(cwd, f), "utf8");
+    } catch {
+      continue;
+    }
+    if (PROVIDER_OR_BACKEND.test(text)) return null;
+  }
+  const examples = ["examples", "example"].find((d) => existsSync(join(cwd, d)));
+  if (examples === undefined || !holdsTerraform(join(cwd, examples), 2)) return null;
+  return (
+    `the repository root configures no provider and no backend, and ships \`${examples}/\`: it is a ` +
+    "module other configurations call, so restructuring it is churn for every caller"
+  );
+}
+
+/** what a detector tool adds to its result when the repository is a library. */
+export function reportOnly(reason: string | null): {
+  report_only?: true;
+  report_only_reason?: string;
+} {
+  return reason === null ? {} : { report_only: true, report_only_reason: reason };
+}

package/src/mcp/terraform/standardsReport.ts

@@ -364,6 +364,8 @@ const SUBJECT: Record<string, RegExp> = {
   // rule's silence a real statement. Whether git could answer is handled one
   // level up by the blind set: a run that could not ask is never conforming.
   "committed-state-file": ANY_BLOCK,
+  // any block may hold a credential argument, a map of them, or a variable default
+  "hardcoded-secret-argument": ANY_BLOCK,
   "deprecated-s3-bucket-argument": /(?:^|\n)\s*resource\s+"?aws_s3_bucket(?:"|\s)/,
   "superseded-resource-type":
     /(?:^|\n)\s*(?:resource\s+"?(?:aws_launch_configuration|aws_elb)(?:"|\s)|data\s+"?template_file(?:"|\s))/,

package/src/mcp/terraform/tools/consolidationCandidates.ts

@@ -3,6 +3,7 @@ import type { LocalToolContext } from "#app/mcp/localContext";
 import { execute, tool, toolOk } from "#app/mcp/shared";
 import { findConsolidationGroups } from "#app/mcp/terraform/consolidation";
 import { readWorkingTree } from "#app/mcp/terraform/refactor/workspace";
+import { isExamplePath } from "#app/mcp/terraform/refactorScope";
 import { log } from "#app/utils/cli";
 
 const ConsolidationCandidatesParams = type({});
@@ -37,7 +38,10 @@ export function ConsolidationCandidatesTool(ctx: LocalToolContext) {
     parameters: ConsolidationCandidatesParams,
     execute: execute(async () => {
       const cwd = ctx.payload.cwd ?? process.cwd();
-      const result = findConsolidationGroups(readWorkingTree(cwd));
+      const tree = readWorkingTree(cwd);
+      const result = findConsolidationGroups(
+        ctx.payload.refactorExamples ? tree : tree.filter((f) => !isExamplePath(f.path)),
+      );
       log.info(
         `» terraform_consolidation_candidates: ${result.groups.length} group(s), ` +
           `${result.near_groups.length} near-group(s), ${result.declined_groups.length} declined`,

package/src/mcp/terraform/tools/normalizationCandidates.ts

@@ -2,6 +2,7 @@ import { type } from "arktype";
 import type { LocalToolContext } from "#app/mcp/localContext";
 import { execute, tool, toolOk } from "#app/mcp/shared";
 import { findNormalizationCandidates } from "#app/mcp/terraform/normalization";
+import { isExamplePath, libraryRepoReason, reportOnly } from "#app/mcp/terraform/refactorScope";
 import { log } from "#app/utils/cli";
 
 // --- the tool ----------------------------------------------------------------
@@ -28,12 +29,15 @@ export function NormalizationCandidatesTool(ctx: LocalToolContext) {
     parameters: NormalizationCandidatesParams,
     execute: execute(async () => {
       const cwd = ctx.payload.cwd ?? process.cwd();
-      const files = findNormalizationCandidates(cwd);
+      const files = findNormalizationCandidates(cwd).filter(
+        (f) => ctx.payload.refactorExamples || !isExamplePath(f.file),
+      );
       const total = files.reduce((n, f) => n + f.count, 0);
       log.info(
         `» terraform_normalization_candidates: ${total} site(s) across ${files.length} file(s)`,
       );
       return toolOk({
+        ...reportOnly(libraryRepoReason(cwd)),
         file_count: files.length,
         total,
         files,

package/src/mcp/terraform/types.ts

@@ -398,6 +398,9 @@ export interface ConcernGroup {
   /** stable id — the remediation branch/PR key (`remediate/<id>`). Derived from
    * the file (by-file grouping) or the rule (by-rule grouping). */
   id: string;
+  /** the branch its fix is pushed to: `remediate/<id>`, plus `--<base>` when the
+   * PR targets a branch other than the repository default. */
+  branch?: string;
   /** the group's primary file (by-file) or a human label like "3 files"
    * (by-rule); `files` carries the full list for by-rule groups. */
   file: string;

package/src/modes/refactor.ts

@@ -18,6 +18,8 @@ This mode standardises STRUCTURE while preserving BEHAVIOUR — the equivalence
    - \`${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. 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.
 
+   **A result marked \`report_only\` is an observation, not work.** The repository is a module other configurations call (\`report_only_reason\` says why), and restructuring it is churn for every caller: name those candidates in your \`${t("report_progress")}\` summary and open no PR for them. \`examples/\` roots are left out of every candidate list unless the operator set \`refactor_examples\`.
+
    **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 — 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.

package/src/modes/refresh-remediation.ts

@@ -26,7 +26,7 @@ This mode keeps already-open ${PRODUCT_NAME} remediation PRs healthy. A remediat
    - **resolved-on-base? → close it**: look for a group in step 3's scan whose \`id\` equals the PR's \`group_id\` (for a by-rule/batch PR, match on the concern ids it covered). If **no** current group/concern corresponds, the concern was already fixed on the base (a human fix, or a base change removed the file) — the PR is redundant. Call \`${t("close_pull_request")}\` with a one-line \`comment\` explaining it's resolved on the base. Do not push anything for this PR.
    - **still present → re-derive the fix on the current base**:
      - **read WHY the CI failed, before changing anything** (\`checks_failing\` PRs only): when step 2 gave the PR a \`failing_check_suite_id\`, call \`${t("get_check_suite_logs")}\` with that id FIRST. Re-deriving without reading the failure is exactly how attempt 2 and attempt 3 become identical repeats of attempt 1 — same fix, same red check, three times, until the retry cap escalates a PR nobody learned anything about. Use the returned \`failed_steps\` and log excerpt to decide what to do DIFFERENTLY this attempt. If the log shows the failure is not ours — a broken base, a missing credential, an unrelated flaky job — do not spend an attempt re-deriving: add \`needs-human\` (\`${t("add_labels")}\`), post ONE comment naming the failing step, and move on. Record the cause in the PR body/comment you write below, so the next attempt and any human start from what you found. When the id is absent, or the tool reports no failed runs, say so in the comment and continue with the plain re-derive rather than guessing.
-     - **branch**: recreate the remediation branch at the current base HEAD via \`${t("git")}\` (\`git checkout -B remediate/<id>\`) — \`-B\` force-resets it to the just-scanned base so the diff is only your fix.
+     - **branch**: recreate the remediation branch at the current base HEAD via \`${t("git")}\` (\`git({ command: "checkout", args: ["-B", <the PR's branch>] })\`, the \`branch\` step 2 returned) — \`-B\` force-resets it to the just-scanned base so the diff is only your fix.
      - **fix → validate → plan → keep tests consistent → prove it**: apply the minimal fix for that group exactly as in **Remediate** step 4 (same \`${t("terraform_validate")}\`, \`${t("terraform_plan")}\`, \`${t("terraform_module_tests")}\`, and \`${t("terraform_verify_remediation")}\` gates, and the same guardrails — never open/keep a PR whose validate didn't pass, abandon a group that would destroy a stateful resource, etc.).
      - **force-update the PR branch**: \`${t("push_branch")}\` with \`force: true\` (the PR already exists; force-updating its branch refreshes it in place — do NOT open a second PR). The Terraform-only / secret / destroy guardrails still run at push time.
      - **refresh the body**: \`${t("update_pull_request_body")}\` rebuilt from the fresh \`${t("terraform_verify_remediation")}\` result (the Remediation PR format below), and add a one-line note that it was rebased onto the current base (\`<short-sha>\`) on this run.

package/src/modes/remediate-and-refactor.ts

@@ -20,7 +20,7 @@ This mode composes the **Remediate** and **Refactor** verbs into a single run. I
    - **commit the fix** (\`git add\` only the changed \`*.tf\`/\`*.tfvars\`, a \`fix(tf): …\` message). Do NOT push yet. This committed state is the refactor's equivalence BASELINE.
 
 3. **REFACTOR (phase 2) — modularise on top of the committed fix**: follow the **Refactor** mode's flow:
-   - \`${t("module_extraction_candidates")}\` / \`${t("terraform_normalization_candidates")}\` → pick one behaviour-preserving refactor. Respect a pinned \`refactor_source\` if one was supplied (it constrains which module source you may use; the behaviour-altering b.4 path is only available when the operator pinned \`third-party\`).
+   - \`${t("module_extraction_candidates")}\` / \`${t("terraform_normalization_candidates")}\` → pick one behaviour-preserving refactor; a result marked \`report_only\` (the repository is a module others call) is named in the summary, never proposed. Respect a pinned \`refactor_source\` if one was supplied (it constrains which module source you may use; the behaviour-altering b.4 path is only available when the operator pinned \`third-party\`).
    - resolve the module source, wire the \`module\` call against its real interface (\`${t("terraform_module_interface")}\` for a local module dir, \`${t("terraform_module_lookup")}\` for a registry-sourced one), and emit a \`moved {}\` block for EVERY relocated address (\`${t("terraform_generate_moved")}\`).
    - \`terraform fmt\` + \`${t("terraform_validate")}\`, then — **with the refactor edits still UNCOMMITTED** — call \`${t("terraform_equivalence_check")}\`. In this mode it diffs the working tree against the COMMITTED fix (not the run-start commit), so it measures only the refactor. It must return \`equivalent: true\` (zero uncovered moves, resource set + arguments preserved, validate + fmt clean) before you proceed; \`${t("push_branch")}\` hard-blocks an unproven one — and, once this run has added a \`moved {}\` block, it also hard-blocks a push that never ran the check at all, so abandoning the refactor means REVERTING its edits rather than leaving them in with the fix. If it can't be proven equivalent, abandon the refactor and ship the fix alone.
    - **document the module (only when the \`docs\` input is enabled)**: after the equivalence check passes, call \`${t("terraform_module_docs")}\` for the module you created/adopted (pass the relocated addresses as \`moves\`). Do not hand-write docs — the tool builds from the interface, moved blocks, and equivalence verdict.

package/src/modes/remediate.ts

@@ -34,8 +34,8 @@ export function remediateMode(t: ToolRef): Mode {
 
 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 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.
+   - **idempotency**: the remediation branch is the group's \`branch\` (\`remediate/<group-id>\`, with a \`--<base>\` suffix when the PR targets a non-default branch) — use it exactly, never a name of your own. 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 the group's \`branch\` from the **current HEAD** (the checkout that was just scanned) via \`${t("git")}\` (\`git({ command: "checkout", args: ["-b", <branch>] })\`). 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.
    - **propose, then let me steer (when there's no single right fix)**: distinct from honest refusal (which refuses a fix a human must *decide*), this is for a finding with **2–3 genuinely distinct, defensible fixes** that differ in trade-offs, not correctness (e.g. encrypt with an AWS-managed key **vs** a customer-managed KMS key; a narrow security-group rule **vs** a prefix list **vs** a VPC endpoint). When such a fork exists **and the triggering comment did not already select a strategy**, do **not** silently pick for the reviewer: via \`${t("create_issue_comment")}\` post one short comment listing the options as **A / B / C** — each a single line (what it does + its trade-off) — and ask the reviewer to reply \`${COMMENT_COMMAND} fix #<concern-id> with strategy <A|B|C>\`. Then **skip the PR for this group** this run and note it in your final report (it resumes when the reviewer replies). When the comment **did** select one (\`fix #<id> with strategy B\`, or a bare \`strategy B\` reply on the proposal thread), apply **exactly** that strategy — don't second-guess it. Reserve this for real forks in the road; a fix with one obvious correct answer just gets made.
    - **reuse a proven fix (optional, do this BEFORE editing)**: call \`${t("terraform_fix_memory")}\`. When proven-fix memory is enabled it returns any patterns whose \`finding_type\` matches this group's concerns — each a transformation that already passed a \`✗→✓\` proof on this repo or elsewhere in the fleet, with its \`remediation_hint\` + a \`before_example\`. Use a matching pattern as your STARTING POINT (it saves you rediscovering the approach), but ADAPT it to this repo's own resources — it is a prior, never a patch to paste. You MUST still run \`${t("terraform_verify_remediation")}\` to prove \`✗→✓\` here; a pattern is never blind-applied and never substitutes for the per-target proof. Returns an empty list (never an error) when memory is off or nothing matches — then fix from first principles as usual.

package/src/utils/config/payload.ts

@@ -137,6 +137,7 @@ export const Inputs = type({
   // org-repo | author | third-party). Structured scope, not prompt text — see
   // parseRefactorSource / withRefactorSource. Gates the behaviour-altering b.4.
   "refactor_source?": type.string.or("undefined"),
+  "refactor_examples?": type.string.or("undefined"),
   "review_instructions?": type.string.or("undefined"),
   "fp_filtering_instructions?": type.string.or("undefined"),
   "remediation_instructions?": type.string.or("undefined"),
@@ -237,6 +238,7 @@ function resolveNonPromptInputs() {
     registry_token: core.getInput("registry_token") || undefined,
     registry_host: core.getInput("registry_host") || undefined,
     refactor_source: core.getInput("refactor_source") || undefined,
+    refactor_examples: core.getInput("refactor_examples") || undefined,
     review_instructions: core.getInput("review_instructions") || undefined,
     fp_filtering_instructions: core.getInput("fp_filtering_instructions") || undefined,
     remediation_instructions: core.getInput("remediation_instructions") || undefined,
@@ -690,6 +692,8 @@ export function resolvePayload(
     // Refactor mode for the b.4 consent gate. undefined → auto. Action-input/
     // trusted-dispatch only (not the untrusted repo file).
     refactorSource,
+    // opt in to refactoring `examples/` roots, which Refactor leaves alone by default
+    refactorExamples: parseBooleanInput(inputs.refactor_examples),
     // a `@infraweaver fix …` command parsed from the triggering comment
     // body (the raw prompt), scoping the run to a specific concern/severity/file.
     // null when the prompt isn't a recognised command.