infraweaver 0.1.0

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

@@ -0,0 +1,384 @@
+import { type } from "arktype";
+import {
+  isGuardedModeName,
+  partitionStatefulDestroy,
+} from "#app/mcp/guardrails";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { resolveRoots } from "#app/mcp/terraform/paths";
+import {
+  aggregatePlans,
+  classifyDestructive,
+  comparePlanStability,
+  computeBlastRadius,
+  isPureMovePlan,
+  type PlanSummary,
+  parseTerraformPlanJson,
+  type RootPlan,
+} from "#app/mcp/terraform/plan";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import { runTf } from "#app/mcp/terraform/subprocess";
+import { skipResult } from "#app/mcp/terraform/types";
+import { log } from "#app/utils/cli";
+import { resolveModuleCredentialEnv } from "#app/utils/registryAuth";
+
+const PLAN_JSON_ARGS = [
+  "plan",
+  "-input=false",
+  "-no-color",
+  "-lock=false",
+  "-json",
+];
+
+interface RootPlanOutcome {
+  ran: boolean;
+  skipReason?: string | undefined;
+  summary?: PlanSummary | undefined;
+  stable?: boolean | undefined;
+  stabilityReason?: string | undefined;
+  planText?: string | undefined;
+}
+
+/** init + plan (+ a stability re-plan + a human-readable plan) in a SINGLE root.
+ * Used by terraform_plan once per discovered root. */
+function planOneRoot(
+  absDir: string,
+  creds: Record<string, string>,
+): RootPlanOutcome {
+  // `terraform` when installed, else `tofu` (identical plan CLI, resolved by
+  // runTf) — an OpenTofu-only runner keeps the plan gate instead of skipping it.
+  const init = runTf(["init", "-input=false", "-no-color"], absDir, creds);
+  if (init.missing)
+    return { ran: false, skipReason: "terraform (or tofu) not installed" };
+  if (init.status !== 0) {
+    return {
+      ran: false,
+      skipReason: `terraform init failed: ${init.stderr.trim().slice(0, 200) || "unknown error"}`,
+    };
+  }
+  const plan = runTf(PLAN_JSON_ARGS, absDir, creds);
+  if (plan.status !== 0) {
+    return {
+      ran: false,
+      skipReason: `terraform plan failed: ${plan.stderr.trim().slice(0, 200) || "unknown error"}`,
+    };
+  }
+  const summary = parseTerraformPlanJson(plan.stdout);
+  const hasChanges =
+    summary.add + summary.change + summary.destroy > 0 ||
+    summary.changed.length > 0;
+
+  // stability: re-plan once and compare (only when there's a change).
+  let stable = true;
+  let stabilityReason: string | undefined;
+  if (hasChanges) {
+    const plan2 = runTf(PLAN_JSON_ARGS, absDir, creds);
+    if (plan2.status === 0) {
+      const s = comparePlanStability(
+        summary,
+        parseTerraformPlanJson(plan2.stdout),
+      );
+      stable = s.stable;
+      stabilityReason = s.reason;
+    }
+  }
+  // human-readable plan for the PR <details> block (separate non-json run).
+  let planText: string | undefined;
+  if (hasChanges) {
+    const readable = runTf(
+      ["plan", "-input=false", "-no-color", "-lock=false"],
+      absDir,
+      creds,
+    );
+    if (readable.status === 0 && readable.stdout.trim())
+      planText = readable.stdout.trim().slice(0, 12_000);
+  }
+  return { ran: true, summary, stable, stabilityReason, planText };
+}
+
+// env vars that signal a cloud provider credential is present — terraform plan
+// needs live provider/backend access, so we only attempt it when one is set.
+const CLOUD_CRED_SIGNALS = [
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_PROFILE",
+  "AWS_ROLE_ARN",
+  "AWS_WEB_IDENTITY_TOKEN_FILE",
+  "ARM_CLIENT_ID",
+  "ARM_USE_OIDC",
+  "AZURE_CLIENT_ID",
+  "GOOGLE_CREDENTIALS",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+  "GOOGLE_OAUTH_ACCESS_TOKEN",
+] as const;
+
+function hasCloudCredentials(): boolean {
+  return CLOUD_CRED_SIGNALS.some((k) => !!process.env[k]);
+}
+
+// env vars terraform/providers legitimately consume, re-admitted past the
+// secret-stripping `run()` env for the plan invocation. Infraweaver is BYOK
+// across providers (Anthropic / OpenAI / Google Gemini / …), so NONE of those
+// LLM keys may leak into the terraform subprocess. PREFIXES are only ones that
+// can't collide with a provider key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+// `GEMINI_API_KEY` carry no cloud prefix; the bare `GOOGLE_` prefix is
+// deliberately NOT used — it would re-admit `GOOGLE_GENERATIVE_AI_API_KEY`).
+// GCP creds are matched by exact NAME / the safe `GOOGLE_CLOUD_` prefix instead.
+const CLOUD_CRED_PREFIXES = [
+  "AWS_",
+  "ARM_",
+  "AZURE_",
+  "GCLOUD_",
+  "GOOGLE_CLOUD_",
+  "TF_VAR_",
+  "TF_TOKEN_",
+  "TF_CLI_",
+];
+const CLOUD_CRED_NAMES = new Set([
+  "GOOGLE_CREDENTIALS",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+  "GOOGLE_CLOUD_KEYFILE_JSON",
+  "GOOGLE_OAUTH_ACCESS_TOKEN",
+  "GOOGLE_PROJECT",
+  "GOOGLE_REGION",
+  "GOOGLE_ZONE",
+  "GOOGLE_IMPERSONATE_SERVICE_ACCOUNT",
+]);
+
+// LLM/model-provider credentials that collide with a cloud PREFIX above and so
+// must be explicitly denied — otherwise a BYOK key would leak into the terraform
+// subprocess. `AWS_BEARER_TOKEN_BEDROCK` (Amazon Bedrock) matches `AWS_`;
+// `AZURE_OPENAI_*` matches `AZURE_`. NB `AWS_REGION` (also a Bedrock env var) is
+// a legitimate cloud/terraform setting and is intentionally NOT denied. Keep in
+// sync with the provider `envVars` in src/models.ts.
+const LLM_CRED_DENY = new Set([
+  "AWS_BEARER_TOKEN_BEDROCK",
+  "AZURE_OPENAI_API_KEY",
+  "AZURE_OPENAI_ENDPOINT",
+]);
+
+export function collectCloudCredentials(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v === undefined) continue;
+    if (LLM_CRED_DENY.has(k)) continue; // never leak a model-provider key, even if it matches a cloud prefix
+    if (
+      CLOUD_CRED_PREFIXES.some((p) => k.startsWith(p)) ||
+      CLOUD_CRED_NAMES.has(k)
+    )
+      env[k] = v;
+  }
+  return env;
+}
+
+export const TerraformPlanParams = type({});
+
+export interface PlanRunners {
+  planOneRoot: (
+    absDir: string,
+    creds: Record<string, string>,
+  ) => RootPlanOutcome;
+  hasCloudCredentials: () => boolean;
+}
+
+const realRunners: PlanRunners = { planOneRoot, hasCloudCredentials };
+
+export async function runPlan(
+  ctx: LocalToolContext,
+  runners: PlanRunners = realRunners,
+) {
+  const cwd = ctx.payload.cwd ?? process.cwd();
+  if (!runners.hasCloudCredentials()) {
+    return skipResult(
+      "no_cloud_credentials",
+      "no cloud credentials detected — terraform plan needs provider/backend access; skipped (add AWS/Azure/GCP creds or an OIDC role to enable it)",
+    );
+  }
+  // fold the optional module credentials into the plan env so `terraform init`
+  // can resolve a private cross-repo `git::` module (GIT_CONFIG_*) or a private
+  // registry module (TF_TOKEN_<host>). Neither key namespace collides with the
+  // cloud creds; the operator-supplied registry token is added here because
+  // collectCloudCredentials() only sees a TF_TOKEN_* that's already in the env.
+  const creds = {
+    ...collectCloudCredentials(),
+    ...(resolveModuleCredentialEnv(ctx.payload, {
+      sshKeyDir: ctx.tmpdir,
+    }) ?? {}),
+  };
+
+  // multi-root: plan EACH root (hepcare: terraform/ + terraform/core/) and
+  // aggregate. resolveRoots falls back to [cwd] for a single-root repo, so
+  // behaviour there is identical to before.
+  const roots = resolveRoots(cwd);
+  const perRoot = roots.map((r) => ({
+    dir: r.relDir || ".",
+    outcome: runners.planOneRoot(r.absDir, creds),
+  }));
+  const ran = perRoot.filter((p) => p.outcome.ran);
+  if (ran.length === 0) {
+    // every root skipped — surface the first reason (e.g. not installed / init failed).
+    const reason =
+      perRoot[0]?.outcome.skipReason ?? "no terraform root could be planned";
+    const code = reason.includes("not installed")
+      ? "terraform_not_installed"
+      : reason.includes("init failed")
+        ? "terraform_init_failed"
+        : "terraform_plan_failed";
+    return skipResult(code, `terraform plan skipped — ${reason}`);
+  }
+
+  const rootPlans: RootPlan[] = ran.map((p) => ({
+    dir: p.dir,
+    summary: p.outcome.summary!,
+    stable: p.outcome.stable!,
+  }));
+  const agg = aggregatePlans(rootPlans);
+  const classified = classifyDestructive(agg.destructive);
+  const blastRadius = computeBlastRadius(agg.changed);
+  // record the UNION across roots so the push-time destroy-block guardrail
+  // blocks if ANY root would destroy/replace a stateful resource.
+  const session = scanSessionOf(ctx.toolState);
+  session.plannedDestroy = {
+    stateful: classified.stateful,
+    ephemeral: classified.ephemeral,
+  };
+  // Blast-radius pre-flight: surface, at PLAN time, which stateful
+  // destroy/replaces are NOT covered by the operator's `allow_replace` —
+  // i.e. what the push-time destroy guardrail (assertNoBlockedDestroy) would
+  // block. A committing mode can then abandon BEFORE the wasted commit/push
+  // round-trip rather than discovering the block at push. `push_will_block`
+  // is the same predicate the guardrail uses (guarded mode + uncovered
+  // stateful destroy); read-only modes never push, so it is false there.
+  const allowReplace = ctx.payload.allowReplace ?? [];
+  const { blocked: blockedDestructive } = partitionStatefulDestroy(
+    classified.stateful,
+    allowReplace,
+  );
+  const pushWillBlock =
+    isGuardedModeName(ctx.toolState.selectedMode) &&
+    blockedDestructive.length > 0;
+  // record the blast tier + idempotency for the confidence label.
+  session.lastBlastTier = blastRadius.tier;
+  session.lastIdempotent = agg.idempotent;
+  // raw totals, for the TC-2.2 upgrade evidence statement — the signed bundle
+  // has to say what the plan SHOWED, not merely that one ran.
+  session.lastPlanTotals = {
+    to_add: agg.add,
+    to_change: agg.change,
+    to_destroy: agg.destroy,
+    destructive: agg.destructive.length,
+  };
+  // Ordering is what makes this plan proof OF the upgrade rather than merely
+  // contemporaneous with it: a plan produced before terraform_provider_upgrade
+  // ran describes the pre-migration configuration and proves nothing about it.
+  session.planFollowedUpgradeDetection = session.upgradeIntent !== undefined;
+
+  // per-root human-readable plans, headed by root, for the PR <details>.
+  const planTextParts = ran
+    .filter((p) => p.outcome.planText)
+    .map((p) =>
+      ran.length > 1
+        ? `### Root: ${p.dir}\n${p.outcome.planText}`
+        : p.outcome.planText,
+    );
+  const planText = planTextParts.length
+    ? planTextParts.join("\n\n").slice(0, 20_000)
+    : undefined;
+  const idempotencyWarning = ran.find((p) => !p.outcome.stable)?.outcome
+    .stabilityReason;
+
+  // deterministic escalation to human review.
+  const escalationReasons: string[] = [];
+  if (blastRadius.tier === "high") {
+    escalationReasons.push(
+      `high blast radius (${blastRadius.resourceCount} resources / ${blastRadius.modules.length} modules)`,
+    );
+  }
+  if (classified.stateful.length > 0) {
+    escalationReasons.push(
+      `${classified.stateful.length} stateful resource(s) would be destroyed/replaced`,
+    );
+  }
+  if (!agg.idempotent)
+    escalationReasons.push("non-deterministic plan (perpetual-diff smell)");
+
+  log.info(
+    `» terraform_plan: +${agg.add} ~${agg.change} -${agg.destroy} across ${ran.length} root(s) ` +
+      `[blast: ${blastRadius.tier}, ${blastRadius.resourceCount} res / ${blastRadius.modules.length} mod]` +
+      (agg.hasDestroyOrReplace
+        ? ` (DESTRUCTIVE: ${agg.destructive.length}, stateful: ${classified.stateful.length})`
+        : "") +
+      (agg.idempotent ? "" : " ⚠ UNSTABLE (non-deterministic plan)") +
+      (escalationReasons.length ? " ⚠ needs-human" : ""),
+  );
+  return toolOk({
+    ran: true,
+    roots_planned: ran.map((p) => p.dir),
+    to_add: agg.add,
+    to_change: agg.change,
+    to_destroy: agg.destroy,
+    has_destroy_or_replace: agg.hasDestroyOrReplace,
+    destructive: agg.destructive,
+    // data-bearing resources that would be lost — these block the push
+    // unless allowed via `allow_replace`.
+    stateful_destructive: classified.stateful,
+    // blast-radius pre-flight: the stateful destroy/replaces NOT covered by
+    // `allow_replace` (what the push-time guardrail would block), and whether
+    // a push in this mode would actually be blocked — so a committing mode can
+    // abandon before the wasted commit/push instead of failing at push.
+    ...(blockedDestructive.length
+      ? { blocked_destructive: blockedDestructive }
+      : {}),
+    push_will_block: pushWillBlock,
+    // how much this fix touches; `high` should force human review.
+    blast_radius: blastRadius,
+    // false when any root's second plan disagreed (perpetual-diff smell).
+    idempotent: agg.idempotent,
+    idempotency_warning: idempotencyWarning,
+    // state-only moves and the modularization no-op gate.
+    moved_count: agg.moved.length,
+    ...(agg.moved.length ? { moved: agg.moved.slice(0, 50) } : {}),
+    refactor_safe: isPureMovePlan(agg),
+    // deterministic escalation to human review.
+    needs_human: escalationReasons.length > 0,
+    ...(escalationReasons.length
+      ? { needs_human_reasons: escalationReasons }
+      : {}),
+    // full human-readable plan(s) for a collapsed <details> block.
+    ...(planText ? { plan_text: planText } : {}),
+    // roots where plan couldn't run (no backend creds for that root, etc.).
+    ...(perRoot.some((p) => !p.outcome.ran)
+      ? {
+          roots_skipped: perRoot
+            .filter((p) => !p.outcome.ran)
+            .map((p) => ({ dir: p.dir, reason: p.outcome.skipReason })),
+        }
+      : {}),
+  });
+}
+
+export function TerraformPlanTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_plan",
+    description:
+      "Run `terraform plan` and report the planned change summary (resources to add / change / destroy), " +
+      "any resource that would be DESTROYED or REPLACED, a blast-radius score (how much the fix touches), " +
+      "and a plan-stability check (a second plan must match the first — a perpetual-diff smell otherwise). " +
+      "Opt-in and degrades green — it auto-skips (returns `ran: false`, never fails the run) when no cloud " +
+      "credentials are detected, terraform is not installed, or init/plan can't complete (plan needs live " +
+      "provider/backend access). Call it after a fix to attach the real-world effect to the PR and surface " +
+      "destructive changes for human review. **Multi-root aware:** it plans EVERY Terraform root in the repo " +
+      "(`roots_planned`) and aggregates — counts summed, destructive/blast unioned — so you don't loop " +
+      "yourself. Returns `plan_text` (the full human-readable plan(s), for a collapsed <details> block) and " +
+      "`needs_human` (true when a high blast radius, a stateful destroy/replace, or a non-deterministic plan " +
+      "means a human must review). Blast-radius pre-flight: `blocked_destructive` lists the stateful " +
+      "destroy/replaces NOT covered by `allow_replace`, and `push_will_block: true` means a push in this " +
+      "committing mode WOULD be blocked by the destroy guardrail — abandon now, before committing/pushing, " +
+      "rather than wasting the round-trip. For an M2 modularization refactor, `refactor_safe: true` is the gate: " +
+      "the plan is purely `moved` state operations (every resource address preserved via `moved {}` blocks, " +
+      "zero add/change/destroy) — if a modularization PR's plan is NOT refactor_safe, fix the moved blocks " +
+      "rather than accepting resource churn.",
+    parameters: TerraformPlanParams,
+    execute: execute(async () => runPlan(ctx)),
+  });
+}

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

@@ -0,0 +1,217 @@
+import { type } from "arktype";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { loadProvidersSchema } from "#app/mcp/providerSchema";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { collectProviderRequirements, collectResourceArguments } from "#app/mcp/terraform/scanners";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import {
+  BUILTIN_TRANSFORM_PACKS,
+  indexProvenTransforms,
+  matchTransforms,
+  packsForRequirements,
+  type SchemaLookup,
+  type TransformMatch,
+  type TransformPack,
+} from "#app/mcp/terraform/transformPacks";
+
+export const TerraformProviderUpgradeParams = type({});
+
+/**
+ * Provider-upgrade transform detection (TC-2.2).
+ *
+ * Reads the pinned provider majors, selects the built-in packs that apply, and
+ * reports every codified breaking change that this configuration actually
+ * contains — with the file it is in and, crucially, whether it can be applied
+ * unattended.
+ *
+ * Read-only. It edits nothing, plans nothing and pushes nothing.
+ */
+
+/** Bound the tool result: a repo pinning an old major can match hundreds of
+ *  sites, and a prompt is not a report. Truncation is always stated. */
+const MAX_REPORTED = 60;
+
+/**
+ * Bind the installed provider schema to the pure matcher's lookup seam.
+ *
+ * Degrades honestly: when the schema can't be loaded (terraform absent, or the
+ * directory was never init-ed) every entry lands as `unverified` rather than
+ * being presented as corroborated. A pack claim nobody could check must not read
+ * the same as one that was checked.
+ */
+function schemaLookupFor(cwd: string): SchemaLookup {
+  const schema = loadProvidersSchema(cwd);
+  if (!schema) return () => null;
+  return (resourceType: string) => {
+    const entry = schema.get(resourceType);
+    if (!entry) return null;
+    return new Set([...entry.attributes, ...entry.blocks]);
+  };
+}
+
+interface PackResult {
+  pack: TransformPack;
+  matches: TransformMatch[];
+}
+
+export function runProviderUpgrade(ctx: LocalToolContext) {
+  const cwd = ctx.payload.cwd ?? process.cwd();
+  const requirements = collectProviderRequirements(cwd);
+  const packs = packsForRequirements(BUILTIN_TRANSFORM_PACKS, requirements);
+
+  const pinned = requirements
+    .filter((r) => r.major !== null)
+    .map((r) => ({ provider: r.name, major: r.major, constraint: r.version }));
+
+  if (packs.length === 0) {
+    // Clear any earlier detection. The natural way to reach this branch is the
+    // agent bumping the pin and re-running to check its work: without this, the
+    // session still holds the PRE-edit intent and match set, and a later plan
+    // would sign a `plan-proven` verdict over the full original transform list
+    // — including ones the agent deliberately deferred.
+    const stale = scanSessionOf(ctx.toolState);
+    delete stale.upgradeIntent;
+    delete stale.transformMatches;
+    delete stale.planFollowedUpgradeDetection;
+    return toolOk({
+      applicable: false,
+      pinned_providers: pinned,
+      transforms: [],
+      note:
+        "No transform pack applies. A pack is selected only when a provider's pinned LOWER-BOUND major " +
+        "matches the major the pack migrates FROM; an unpinned provider matches nothing, because guessing " +
+        "which major it resolves to is how you get handed a migration you don't need. Packs available: " +
+        `${BUILTIN_TRANSFORM_PACKS.map((p) => `${p.provider} v${p.from_major}→v${p.to_major}`).join(", ")}.`,
+    });
+  }
+
+  const resources = collectResourceArguments(cwd);
+  const lookup = schemaLookupFor(cwd);
+  const results: PackResult[] = packs.map((pack) => ({
+    pack,
+    matches: matchTransforms(pack, resources, lookup),
+  }));
+
+  const session = scanSessionOf(ctx.toolState);
+  const fleet = indexProvenTransforms(session.provenTransformLibrary ?? []);
+  const allMatches = results.flatMap((r) => r.matches);
+  session.transformMatches = allMatches;
+
+  // The intent is recorded for the FIRST applicable pack. A repo mid-upgrade on
+  // two providers at once is possible but is not a thing to encourage, and an
+  // evidence statement that averaged two providers' verdicts would be unreadable.
+  const primary = results[0];
+  if (primary) {
+    const ids = [...new Set(primary.matches.map((m) => m.entry.id))].sort();
+    session.upgradeIntent = {
+      provider: primary.pack.provider,
+      from_major: primary.pack.from_major,
+      to_major: primary.pack.to_major,
+      pack_version: primary.pack.version,
+      pack_source: primary.pack.source,
+      pack_exhaustive: primary.pack.exhaustive,
+      transform_ids: ids,
+      needing_human: new Set(primary.matches.filter((m) => m.needs_human).map((m) => m.entry.id))
+        .size,
+    };
+  }
+
+  const needsHuman = allMatches.filter((m) => m.needs_human);
+  // Sort needs-human first, THEN truncate. Match order is pack-entry order, so
+  // a zone with 200 renamed DNS records would otherwise fill every slot and
+  // push the four state-moving transforms off the end — leaving the agent told
+  // "4 transforms move state, name them in the PR body" with no way to know
+  // which four. The dangerous ones are exactly the ones that must survive a cut.
+  const reported = [...allMatches]
+    .sort((a, b) => Number(b.needs_human) - Number(a.needs_human))
+    .slice(0, MAX_REPORTED);
+
+  return toolOk({
+    applicable: true,
+    pinned_providers: pinned,
+    packs: results.map((r) => ({
+      provider: r.pack.provider,
+      from_major: r.pack.from_major,
+      to_major: r.pack.to_major,
+      pack_version: r.pack.version,
+      source: r.pack.source,
+      exhaustive: r.pack.exhaustive,
+      ...(r.pack.official_tool ? { official_tool: r.pack.official_tool } : {}),
+      matched: r.matches.length,
+    })),
+    // Sites, not transforms: one entry firing on twelve resources is twelve
+    // matches. The signed bundle's `transforms_detected` counts DEDUPED entry
+    // ids, so the two are named differently rather than disagreeing under one
+    // name — for a big repo they differ by an order of magnitude.
+    matched_sites: allMatches.length,
+    transforms_detected: new Set(allMatches.map((m) => m.entry.id)).size,
+    transforms_needing_human: new Set(needsHuman.map((m) => m.entry.id)).size,
+    transforms: reported.map((m) => {
+      const proven = fleet.get(m.entry.id);
+      return {
+        id: m.entry.id,
+        kind: m.entry.kind,
+        ...(m.entry.resource_type ? { resource_type: m.entry.resource_type } : {}),
+        from: m.entry.from,
+        ...(m.entry.to ? { to: m.entry.to } : {}),
+        ...(m.file ? { file: m.file } : {}),
+        ...(m.resource_name ? { resource_name: m.resource_name } : {}),
+        confidence: m.confidence,
+        schema_agreement: m.schema_agreement,
+        state_move: m.entry.state_move,
+        needs_human: m.needs_human,
+        ...(m.needs_human_reason ? { needs_human_reason: m.needs_human_reason } : {}),
+        ...(m.entry.value_change ? { value_change: m.entry.value_change } : {}),
+        note: m.entry.note,
+        // fleet reuse (§5.12-shaped): counters only, never another repo's config.
+        ...(proven?.times_proven ? { fleet_times_proven: proven.times_proven } : {}),
+        ...(proven?.repos_count ? { fleet_repos_count: proven.repos_count } : {}),
+      };
+    }),
+    ...(allMatches.length > MAX_REPORTED
+      ? {
+          truncated: `showing ${MAX_REPORTED} of ${allMatches.length} matched sites, needs-human first — fix these, re-run, and the rest will surface.`,
+        }
+      : {}),
+    note: buildNote(results, new Set(needsHuman.map((m) => m.entry.id)).size),
+  });
+}
+
+function buildNote(results: PackResult[], needsHuman: number): string {
+  const parts: string[] = [];
+  const tool = results.find((r) => r.pack.official_tool)?.pack.official_tool;
+  if (tool) {
+    parts.push(
+      `The provider vendor ships its own migration tool for this upgrade — ${tool}. Run it FIRST and review its diff; these entries are for judging what it produced, not for redoing its work.`,
+    );
+  }
+  if (needsHuman > 0) {
+    parts.push(
+      `${needsHuman} transform(s) MOVE STATE or force replacement. Do not apply them autonomously: a config-only edit there destroys and recreates live resources. Split them into a separate PR, label it \`needs-human\`, and say in the body exactly which resources are affected.`,
+    );
+  }
+  parts.push(
+    "A pack entry is a LEAD, not a patch. Apply the edit yourself, then prove it: `terraform_validate` (its `unknown_arguments` reads the installed schema and is the authoritative check for anything this pack missed — the packs are explicitly not exhaustive), then `terraform_plan`. An entry marked `unverified` was NOT corroborated by the installed provider schema — treat it as a hint to check, never as fact.",
+  );
+  return parts.join(" ");
+}
+
+export function TerraformProviderUpgradeTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_provider_upgrade",
+    description:
+      "Codified provider-major migrations (transform packs). Reads the pinned provider majors from " +
+      "`required_providers`, selects the built-in pack for that major boundary (azurerm v3→v4, " +
+      "cloudflare v4→v5), and reports every documented breaking change this configuration actually " +
+      "contains: renamed and removed arguments, removed resource types, newly-required arguments, and " +
+      "provider-block changes — each with the file it is in. Call it BEFORE editing when raising a " +
+      "provider major. Two things it tells you that nothing else does: which changes MOVE STATE (those " +
+      "destroy and recreate live resources unless a human runs `state rm` + `import`, and must never be " +
+      "applied autonomously), and which changes are NOT pure renames (a value that must be inverted or " +
+      "retyped). Entries are cross-checked against the INSTALLED provider schema; one the schema does not " +
+      "corroborate is returned as `unverified`. Packs are not exhaustive — `terraform_validate`'s " +
+      "`unknown_arguments` remains the authoritative completeness check. Read-only.",
+    parameters: TerraformProviderUpgradeParams,
+    execute: execute(() => Promise.resolve(runProviderUpgrade(ctx))),
+  });
+}