infraweaver 0.1.0

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

@@ -0,0 +1,279 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import { PRODUCT_NAME } from "#app/brand";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { walkTfFiles } from "#app/mcp/modules";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { buildConcernResult } from "#app/mcp/terraform/concernResult";
+import { indexTfResources } from "#app/mcp/terraform/cspm";
+import { docUrlsForGroup, ruleDocUrl } from "#app/mcp/terraform/decisions";
+import { findActionTriggers } from "#app/mcp/terraform/governance";
+import {
+  buildDriftStatement,
+  classifyForgotten,
+  detectDrift,
+  driftToConcerns,
+  filterProviderNoise,
+  isSupportedPlanFormat,
+  PlanDocument,
+  summarizeActionInvocations,
+} from "#app/mcp/terraform/planDrift";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import {
+  SEVERITY_RANK,
+  type Severity,
+  skipResult,
+} from "#app/mcp/terraform/types";
+import { log } from "#app/utils/cli";
+
+export const DetectPlanDriftParams = type({
+  "path?": type.string.describe(
+    "path to a `terraform show -json` plan artifact. Defaults to $INFRAWEAVER_PLAN_JSON_PATH, then ./plan.json.",
+  ),
+  "severity_threshold?": type(
+    "'critical' | 'high' | 'medium' | 'low' | 'info'",
+  ).describe(
+    "minimum severity to report (default: the run's configured threshold, else low).",
+  ),
+  "noise_fields?": type("string[]").describe(
+    "extra attribute names to treat as provider-computed noise, in addition to the built-in " +
+      "per-provider defaults (aws tags_all, google effective_labels/terraform_labels). An update whose " +
+      "ENTIRE diff is noise fields is excluded from drift and listed under `noise_filtered` instead.",
+  ),
+  "noise_filter?": type("boolean").describe(
+    "set false to disable the provider-noise filter entirely and report every mutating change as drift " +
+      "(default true).",
+  ),
+});
+
+/** Read every `.tf` file under `cwd` into `{ file, hcl }` pairs for the resource index. */
+function readTfFiles(cwd: string): { file: string; hcl: string }[] {
+  const out: { file: string; hcl: string }[] = [];
+  for (const file of walkTfFiles(cwd)) {
+    try {
+      out.push({ file, hcl: readFileSync(join(cwd, file), "utf8") });
+    } catch {
+      // unreadable file — skip
+    }
+  }
+  return out;
+}
+
+export function DetectPlanDriftTool(ctx: LocalToolContext) {
+  return tool({
+    name: "detect_plan_drift",
+    description:
+      "Detect infrastructure DRIFT from a `terraform show -json` plan artifact WITHOUT holding cloud " +
+      "credentials — the customer's CI runs `terraform plan` (where the creds live) and writes the plan out " +
+      "as JSON; this reads that artifact. The sovereign, zero-credential companion to running terraform_plan " +
+      "against live state. On a run whose CODE is unchanged (a scheduled drift workflow), every mutating " +
+      "`resource_changes[]` entry is drift: a resource updated/deleted/replaced/recreated to reconcile live " +
+      "state with code. Each drifted resource becomes a `reviewer`-source concern at its file:line (returning " +
+      "the SAME { concerns, groups, summary } shape as terraform_scan); as drift it is not-code-verifiable by " +
+      `the ✗→✓ re-scan (reconciling needs live cloud access — a human decision; ${PRODUCT_NAME} never applies). ` +
+      "Drift whose address isn't in code is returned under `unlocated`. DETECTION ONLY — never edits, applies, " +
+      "or opens a PR. Returns `found: false` (never an error) when no plan artifact is present.",
+    parameters: DetectPlanDriftParams,
+    execute: execute(
+      async ({ path, severity_threshold, noise_fields, noise_filter }) => {
+        const cwd = ctx.payload.cwd ?? process.cwd();
+        // SECURITY: confine the agent-supplied `path` to the workspace; the env-var
+        // fallback is operator-controlled, so it stays unconfined.
+        const planPath = path
+          ? resolveWithinCwd(cwd, path)
+          : process.env.INFRAWEAVER_PLAN_JSON_PATH || join(cwd, "plan.json");
+        let raw: string;
+        try {
+          raw = readFileSync(planPath, "utf8");
+        } catch {
+          return skipResult(
+            "plan_artifact_not_found",
+            `no plan artifact at ${planPath} (write one with \`terraform show -json plan.out > plan.json\`, ` +
+              `or set the path arg / $INFRAWEAVER_PLAN_JSON_PATH)`,
+            {
+              key: "found",
+              reasonKey: "reason",
+              extra: { concerns: [], groups: [], unlocated: [] },
+            },
+          );
+        }
+
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(raw || "{}");
+        } catch {
+          return skipResult(
+            "plan_artifact_parse_error",
+            `could not parse JSON at ${planPath}`,
+            {
+              key: "found",
+              reasonKey: "reason",
+              extra: { concerns: [], groups: [], unlocated: [] },
+            },
+          );
+        }
+        const document = PlanDocument(parsed);
+        if (document instanceof type.errors) {
+          return skipResult(
+            "plan_artifact_invalid",
+            `plan artifact at ${planPath} is not a terraform show -json document: ${document.summary}`,
+            {
+              key: "found",
+              reasonKey: "reason",
+              extra: { concerns: [], groups: [], unlocated: [] },
+            },
+          );
+        }
+
+        // Forward-compat: an unknown MAJOR schema means we may be reading a
+        // document we do not understand, so say so rather than report a
+        // confident 'no drift' derived from keys that may have moved.
+        const formatSupported = isSupportedPlanFormat(document.format_version);
+        // Provider-noise filter: an update whose ENTIRE diff is provider-computed
+        // bookkeeping (aws tags_all, …) is not an operator touching infra. Kept
+        // auditable — filtered items are returned, never silently dropped.
+        const { kept: drift, filtered: noiseFiltered } =
+          noise_filter === false
+            ? { kept: detectDrift(document), filtered: [] }
+            : filterProviderNoise(detectDrift(document), noise_fields ?? []);
+        // State-only removals: the cloud object survives but leaves management, so
+        // every later drift scan is blind to it. Reported as a coverage gap — and
+        // a STATEFUL forget (a database leaving management) escalates to
+        // needs-human: after it, a data-bearing object exists with no destroy
+        // protection, no drift visibility, and nothing in code saying so.
+        const forgotten = classifyForgotten(document);
+        const statefulForgotten = forgotten.filter((f) => f.stateful);
+        const tfFiles = readTfFiles(cwd);
+        const index = indexTfResources(tfFiles);
+        const byAddress = new Map(index.map((e) => [e.address, e]));
+        const { concerns: driftConcerns, unlocated } = driftToConcerns(
+          drift,
+          (address) => {
+            const e = byAddress.get(address);
+            return e ? { file: e.file, line: e.line } : null;
+          },
+        );
+        // Runtime↔static correlation (TC-2.1 ∘ TC-3.2): `action_invocations` is
+        // the plan saying "THIS apply invokes provider actions" — the runtime
+        // counterpart of the static `imperative-action-trigger` finding. Each
+        // invocation is marked with whether a lifecycle trigger in the repo's HCL
+        // declares it, so an invocation NOT declared in code stands out.
+        const declaredActionRefs = new Set(
+          tfFiles.flatMap(({ hcl }) =>
+            findActionTriggers(hcl).flatMap((t) => t.actions),
+          ),
+        );
+        const actionInvocations = summarizeActionInvocations(document).map(
+          (inv) => ({
+            ...inv,
+            declared_in_code: declaredActionRefs.has(inv.address),
+          }),
+        );
+
+        const configured = ctx.payload.severityThreshold as
+          | Severity
+          | undefined;
+        const threshold: Severity = severity_threshold ?? configured ?? "low";
+        const minRank = SEVERITY_RANK[threshold];
+        const autonomyThreshold =
+          (ctx.payload.autonomyThreshold as Severity | undefined) ?? "high";
+
+        const {
+          active,
+          suppressed,
+          groups,
+          batchPlan,
+          bySeverity: by_severity,
+        } = buildConcernResult(ctx, driftConcerns, {
+          cwd,
+          minRank,
+          grouping: "file",
+          autonomyThreshold,
+          // drift is a narrow concern source — join any prior scan baseline so a
+          // later ✗→✓ verify doesn't read the whole workspace as regressions.
+          baselineMode: "merge",
+        });
+
+        log.info(
+          `» detect_plan_drift: ${active.length} drifted resource(s) ≥ ${threshold} from ${planPath}` +
+            (noiseFiltered.length
+              ? `, ${noiseFiltered.length} noise-filtered`
+              : "") +
+            (unlocated.length ? `, ${unlocated.length} unlocated` : "") +
+            (statefulForgotten.length
+              ? `, ${statefulForgotten.length} STATEFUL forget(s)`
+              : "") +
+            (suppressed.length ? ` (${suppressed.length} suppressed)` : ""),
+        );
+
+        const coverageGap = formatSupported
+          ? undefined
+          : `plan artifact declares format_version ${document.format_version} — this parser reads 1.x; ` +
+            "results may be incomplete";
+
+        // Record the drift statement for terraform_emit_evidence: drift (with the
+        // forgotten blind-spot list and any coverage gap) enters the SIGNED
+        // bundle instead of dying as a run verdict. The statement is built from
+        // the UNTHRESHOLDED drift set — evidence must not shrink with a
+        // reporting preference.
+        scanSessionOf(ctx.toolState).lastDrift = buildDriftStatement({
+          sourceFile: planPath,
+          kept: drift,
+          filtered: noiseFiltered,
+          forgotten,
+          unlocated: unlocated.length,
+          coverageGaps: coverageGap ? [coverageGap] : [],
+        });
+
+        const needsHumanReasons = statefulForgotten.map(
+          (f) =>
+            `plan forgets STATEFUL resource ${f.address} (${f.type}) — after this apply it keeps existing ` +
+            "with no destroy protection and no drift visibility; confirm the removal is intentional",
+        );
+
+        return toolOk({
+          found: true,
+          source_file: planPath,
+          drift: active.length > 0,
+          summary: {
+            drifted: active.length,
+            suppressed: suppressed.length,
+            noise_filtered: noiseFiltered.length,
+            unlocated: unlocated.length,
+            groups: groups.length,
+            by_severity,
+          },
+          groups: groups.map((g) => ({
+            ...g,
+            doc_urls: docUrlsForGroup(g, active),
+          })),
+          batch_plan: batchPlan,
+          concerns: active.map((c) => ({ ...c, doc_url: ruleDocUrl(c) })),
+          // A resource that drifted but isn't in code (e.g. deleted from the config but
+          // still in state) — surfaced honestly, not hidden.
+          unlocated,
+          // Drift excluded as provider-computed bookkeeping (aws tags_all, …) —
+          // listed field-by-field so the filtering is auditable, never silent.
+          noise_filtered: noiseFiltered,
+          // Resources the plan would drop from state while the real object keeps
+          // existing. NOT drift and NOT a destroy — but after this, drift detection
+          // can no longer see them, so the gap is stated rather than assumed away.
+          // Each entry carries `stateful`; a stateful forget escalates below.
+          forgotten,
+          // Provider actions THIS plan will invoke (TF 1.15 `action_invocations`) —
+          // the runtime counterpart of the static `imperative-action-trigger`
+          // finding; `declared_in_code: false` means the plan invokes an action no
+          // lifecycle trigger in the repo declares.
+          action_invocations: actionInvocations,
+          // Deterministic escalation (mirrors terraform_plan's needs_human): a
+          // stateful resource leaving management is a human decision, not a verdict.
+          needs_human: needsHumanReasons.length > 0,
+          needs_human_reasons: needsHumanReasons,
+          ...(coverageGap ? { coverage_gap: coverageGap } : {}),
+        });
+      },
+    ),
+  });
+}

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

@@ -0,0 +1,130 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import { COST_FILE, PRODUCT_NAME } from "#app/brand";
+import { COST_OPTIMIZATION_MODE } from "#app/mcp/guardrails";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { walkTfFiles } from "#app/mcp/modules";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { indexTfResources } from "#app/mcp/terraform/cspm";
+import {
+  detectIdleFloor,
+  IDLE_FLOOR_DOES_NOT_ASSERT,
+  renderCostMarkdown,
+} from "#app/mcp/terraform/idleFloor";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import { skipResult } from "#app/mcp/terraform/types";
+import { log } from "#app/utils/cli";
+import packageJson from "#package.json" with { type: "json" };
+
+/** No `output_path`: the artifact name is FIXED. The guardrail carve-out that
+ *  lets this file be pushed is the single literal `cost.md` (see
+ *  `COST_ALLOWED_PATHS`), so an agent-chosen path could either be rejected at
+ *  push time or — worse, for a path like `main.tf` that IS allow-listed —
+ *  overwrite Terraform source with markdown. Fixing the name makes the tool's
+ *  write surface exactly the surface the guardrail permits. */
+export const TerraformEmitCostParams = type({});
+
+/** Read every `.tf` file under `cwd` into `{ file, hcl }` pairs for the resource index. */
+function readTfFiles(cwd: string): { file: string; hcl: string }[] {
+  const out: { file: string; hcl: string }[] = [];
+  for (const file of walkTfFiles(cwd)) {
+    try {
+      out.push({ file, hcl: readFileSync(join(cwd, file), "utf8") });
+    } catch {
+      // unreadable file — skip
+    }
+  }
+  return out;
+}
+
+export function TerraformEmitCostTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_emit_cost",
+    description:
+      "Compute the credential-free IDLE FLOOR — what this configuration bills at ZERO traffic — and write " +
+      `it as a \`${COST_FILE}\` artifact for the PR. Needs NO cloud credentials, NO pricing API key and makes ` +
+      "NO network call: prices come from a bundled snapshot of public Azure list prices, so it works offline " +
+      "in the free tier. Reports only the DETERMINISTIC portion of cost (reserved compute, provisioned " +
+      "gateways, provisioned cache) — never a monthly total, because usage-dependent lines (data processed, " +
+      "requests, egress) are not derivable from Terraform and quoting them would be a guess; a resource whose " +
+      "tier it cannot identify is listed as unpriced rather than estimated. Use it to justify a " +
+      "CostOptimization fix: the floor is the part a right-sizing PR actually removes. CostOptimization mode " +
+      "only (that is the one mode whose push allows the artifact). Azure resource types today; returns " +
+      "`found: false` (never an error) when nothing is priced.",
+    parameters: TerraformEmitCostParams,
+    // writes a file that lands in the PR diff — mutating for subagent purposes.
+    mutates: true,
+    execute: execute(async () => {
+      // Mode gate, mirroring terraform_module_docs: the push guardrail only
+      // allow-lists `cost.md` for CostOptimization, so writing it under any other
+      // guarded mode would hard-block that run's push. Skip, never throw.
+      const mode = ctx.toolState.selectedMode;
+      if (mode !== COST_OPTIMIZATION_MODE) {
+        return skipResult(
+          "cost_mode_only",
+          `the cost artifact is written by the ${COST_OPTIMIZATION_MODE} mode only (this run is ${mode ?? "unset"}) — its push allow-list is the one that permits ${COST_FILE}`,
+          { key: "found", reasonKey: "reason", extra: { items: [], monthly_floor: 0 } },
+        );
+      }
+
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      const target = resolveWithinCwd(cwd, COST_FILE);
+      const session = scanSessionOf(ctx.toolState);
+
+      const report = detectIdleFloor(indexTfResources(readTfFiles(cwd)));
+      if (report.items.length === 0) {
+        // Clear any earlier report: a re-run after a fix that removed the last
+        // priced resource must not leave the evidence bundle asserting the OLD
+        // floor while cost.md was never rewritten.
+        session.lastIdleFloor = undefined;
+        return skipResult(
+          "no_priced_resources",
+          "no resources from the idle-floor catalog were priced in this configuration",
+          {
+            key: "found",
+            reasonKey: "reason",
+            extra: { items: [], monthly_floor: 0, unpriced: report.unpriced },
+          },
+        );
+      }
+
+      const markdown = renderCostMarkdown(report, packageJson.version);
+      try {
+        writeFileSync(target, markdown, "utf8");
+      } catch (e) {
+        return skipResult(
+          "cost_write_failed",
+          `could not write the cost artifact to ${target}: ${e instanceof Error ? e.message : String(e)}`,
+          { key: "found", reasonKey: "reason", extra: { items: [], monthly_floor: 0 } },
+        );
+      }
+
+      // Hand the report to the session so the evidence bundle can carry the same
+      // numbers without recomputing them (one source, one set of bytes signed).
+      session.lastIdleFloor = report;
+
+      log.info(
+        `» terraform_emit_cost: ${report.currency} ${report.monthly_floor.toFixed(2)}/mo idle floor ` +
+          `across ${report.items.length} resource(s) → ${target}` +
+          (report.unpriced.length ? ` (${report.unpriced.length} unpriced)` : ""),
+      );
+      return toolOk({
+        found: true,
+        output_path: target,
+        currency: report.currency,
+        monthly_floor: report.monthly_floor,
+        priced_at: report.priced_at,
+        region: report.region,
+        items: report.items,
+        // Catalogued resources whose tier wasn't identifiable — the floor is a
+        // lower bound by exactly these, and saying so is the point.
+        unpriced: report.unpriced,
+        note:
+          `Idle floor only — ${IDLE_FLOOR_DOES_NOT_ASSERT} ` +
+          `${PRODUCT_NAME} holds no cloud credentials and made no pricing call.`,
+      });
+    }),
+  });
+}

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

@@ -0,0 +1,108 @@
+import { writeFileSync } from "node:fs";
+import { type } from "arktype";
+import { SARIF_FILE } from "#app/brand";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { buildSarifReport } from "#app/mcp/terraform/findings";
+import {
+  checkovFrameworksFor,
+  detectIacLanguages,
+  inLanguageScope,
+  resolveLanguageScope,
+} from "#app/mcp/terraform/iacLanguages";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import { runScanners } from "#app/mcp/terraform/scanners";
+import { suppressConcerns } from "#app/mcp/terraform/suppressions";
+import {
+  dedupe,
+  SEVERITY_RANK,
+  type Severity,
+  skipResult,
+  sortConcerns,
+} from "#app/mcp/terraform/types";
+import { log } from "#app/utils/cli";
+import { resolveModuleCredentialEnv } from "#app/utils/registryAuth";
+import { resolveToolSelection } from "#app/utils/toolSelection";
+
+export const TerraformEmitSarifParams = type({
+  "output_path?": type.string.describe(
+    `where to write the SARIF file (default: ./${SARIF_FILE} in the workspace). Upload it with github/codeql-action/upload-sarif to populate the repo's Security tab.`,
+  ),
+  "severity_threshold?": type(
+    "'critical' | 'high' | 'medium' | 'low' | 'info'",
+  ).describe(
+    "minimum severity to include (default: the run's configured threshold, else low).",
+  ),
+});
+
+export function TerraformEmitSarifTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_emit_sarif",
+    description:
+      "Emit the current best-practice scan as a SARIF 2.1.0 file for GitHub code-scanning. Re-runs " +
+      `the scanners and writes a SARIF report (default \`${SARIF_FILE}\`) that a later workflow step uploads ` +
+      "with `github/codeql-action/upload-sarif`, surfacing every concern in the repo's Security tab with the " +
+      "right severity + doc link. This is the EMIT side (the inverse of `read_findings`' SARIF INGEST) — use " +
+      "it when the goal is to REPORT findings to code-scanning rather than open a remediation PR. Degrades " +
+      "green: writes an empty-result report when the tree is clean.",
+    parameters: TerraformEmitSarifParams,
+    execute: execute(async ({ output_path, severity_threshold }) => {
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      const configured = ctx.payload.severityThreshold as Severity | undefined;
+      const threshold: Severity = severity_threshold ?? configured ?? "low";
+      const minRank = SEVERITY_RANK[threshold];
+      // Mirror the Assess pillar's multi-language scope so the Security tab reflects
+      // exactly what the assessment reports — Terraform plus every other IaC language
+      // the scanners parse (scoped by `iac_languages`), not Terraform alone.
+      const languageScope = resolveLanguageScope(ctx.payload.iacLanguages, detectIacLanguages(cwd));
+      // same selection + module-fetch credential as terraform_scan, so the
+      // SARIF report mirrors exactly what a scan reports (no extra gated tools).
+      const outcomes = runScanners(cwd, {
+        selection: resolveToolSelection(ctx.payload),
+        terraformEnv: resolveModuleCredentialEnv(ctx.payload, {
+          sshKeyDir: ctx.tmpdir,
+        }),
+        checkovFrameworks: checkovFrameworksFor(languageScope.scanned),
+        toolsNetwork: ctx.payload.toolsNetwork,
+      });
+      const inScope = inLanguageScope(languageScope);
+      const concerns = suppressConcerns(
+        sortConcerns(dedupe(outcomes.flatMap((o) => o.concerns)))
+          .filter(inScope)
+          .filter((c) => SEVERITY_RANK[c.severity] >= minRank),
+        cwd,
+      );
+      const suppressedCount = concerns.filter((c) => c.suppression).length;
+      const report = buildSarifReport(concerns);
+      // SECURITY: confine the agent-supplied output_path to the workspace so it
+      // can't be used to clobber arbitrary files on the runner (the action
+      // process runs outside the shell sandbox). Computed BEFORE the try so an
+      // escape attempt surfaces as a clear error, not a "write failed" skip.
+      const target = resolveWithinCwd(cwd, output_path ?? SARIF_FILE);
+      try {
+        writeFileSync(target, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+      } catch (e) {
+        return skipResult(
+          "sarif_write_failed",
+          `could not write SARIF to ${target}: ${e instanceof Error ? e.message : String(e)}`,
+        );
+      }
+      // record the agent-emitted path so the end-of-run findings-output safety
+      // net (finalizeSuccessRun) defers to this file instead of rewriting it.
+      scanSessionOf(ctx.toolState).emittedSarifPath = target;
+      log.info(
+        `» terraform_emit_sarif: ${concerns.length} result(s)` +
+          (suppressedCount ? ` (${suppressedCount} suppressed)` : "") +
+          ` → ${target}`,
+      );
+      return toolOk({
+        sarif_path: target,
+        result_count: concerns.length,
+        suppressed_count: suppressedCount,
+        rule_count: report.runs?.[0]?.tool?.driver?.rules?.length ?? 0,
+        note: "Upload with github/codeql-action/upload-sarif to populate the repo's Security tab.",
+      });
+    }),
+  });
+}

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

@@ -0,0 +1,82 @@
+import { type } from "arktype";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import {
+  loadFixMemory,
+  matchPatternsForConcerns,
+  type ProvenFixPattern,
+} from "#app/mcp/terraform/fixMemory";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+
+export const TerraformFixMemoryParams = type({});
+
+/**
+ * The effective library for this run: the one loaded at run start
+ * (`session.fixMemoryLibrary` — the org's Cloud library ∪ any committed local
+ * file), or, on the local stdio MCP server where there is no run-start hook, a
+ * lazy read of the committed `.infraweaver.fix-memory.json`. Cached back onto the
+ * session so the file is read at most once.
+ */
+function effectiveLibrary(ctx: LocalToolContext): ProvenFixPattern[] {
+  const session = scanSessionOf(ctx.toolState);
+  if (session.fixMemoryLibrary === undefined) {
+    session.fixMemoryLibrary = loadFixMemory(ctx.payload.cwd);
+  }
+  return session.fixMemoryLibrary;
+}
+
+export function runFixMemory(ctx: LocalToolContext) {
+  if (!ctx.payload.fixMemory) {
+    return toolOk({
+      enabled: false,
+      patterns: [],
+      note: 'Proven-fix memory is off. Enable it with the `fix_memory: "true"` input.',
+    });
+  }
+
+  const session = scanSessionOf(ctx.toolState);
+  if (session.lastScanConcerns === undefined) {
+    return toolOk({
+      enabled: true,
+      patterns: [],
+      note: "No scan this run yet — run terraform_scan first, then call this to see proven priors for its findings.",
+    });
+  }
+
+  const matched = matchPatternsForConcerns(
+    effectiveLibrary(ctx),
+    session.lastScanConcerns,
+  );
+  return toolOk({
+    enabled: true,
+    patterns: matched.map((p) => ({
+      finding_type: p.finding_type,
+      title: p.title,
+      canonical_class: p.canonical_class ?? undefined,
+      remediation_hint: p.remediation_hint ?? undefined,
+      before_example: p.before_example ?? undefined,
+      times_proven: p.times_proven ?? undefined,
+      repos_count: p.repos_count ?? undefined,
+      last_proven: p.last_proven ?? undefined,
+    })),
+    note:
+      matched.length > 0
+        ? "Each pattern is a PROVEN starting point for that finding-type from a prior ✗→✓. Adapt it to THIS repo's resources — you MUST still run terraform_verify_remediation to prove ✗→✓ here. Never apply a pattern blind."
+        : "No proven-fix pattern matches this scan's finding-types yet.",
+  });
+}
+
+export function TerraformFixMemoryTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_fix_memory",
+    description:
+      "Reusable proven-fix memory: returns proven-fix patterns for the finding-types in the CURRENT " +
+      "scan — each a transformation that already passed a ✗→✓ proof on this repo or elsewhere in the " +
+      "fleet. Call it in the fix step to start from a known-good approach instead of rediscovering it. " +
+      "A pattern is a PRIOR, not a patch: adapt it to this repo's own resources and ALWAYS re-prove with " +
+      "terraform_verify_remediation — a pattern is never blind-applied, and the ✗→✓ proof is still required " +
+      "per target. Returns an empty list (never an error) when nothing matches or memory is off.",
+    parameters: TerraformFixMemoryParams,
+    execute: execute(() => Promise.resolve(runFixMemory(ctx))),
+  });
+}