infraweaver 0.1.0

package/src/mcp/assess.ts

@@ -0,0 +1,723 @@
+import { type } from "arktype";
+import { COMMENT_COMMAND, PRODUCT_NAME } from "#app/brand";
+import { buildCrosswalkReport, type CrosswalkReport } from "#app/mcp/crosswalk";
+import {
+  cyberEssentialsControlsAtRisk,
+  cyberEssentialsScore,
+} from "#app/mcp/cyberEssentials";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import {
+  type BaselineDelta,
+  baselineDelta,
+  loadBaselineWithMeta,
+} from "#app/mcp/terraform/baseline";
+import {
+  applyScannerAvailability,
+  checkovFrameworksFor,
+  detectIacLanguages,
+  type IacLanguage,
+  inLanguageScope,
+  LANGUAGE_LABEL,
+  type LanguageScope,
+  languageOfConcern,
+  resolveLanguageScope,
+} from "#app/mcp/terraform/iacLanguages";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import { attachSourceSnippets, runScanners } from "#app/mcp/terraform/scanners";
+import { suppressConcerns } from "#app/mcp/terraform/suppressions";
+import {
+  type Concern,
+  dedupe,
+  type ScannerOutcome,
+  SEVERITY_RANK,
+  type Severity,
+  sortConcerns,
+} from "#app/mcp/terraform/types";
+import {
+  buildVerificationSummary,
+  type VerificationSummary,
+} from "#app/mcp/terraform/verification";
+import { log } from "#app/utils/cli";
+import { resolveModuleCredentialEnv } from "#app/utils/registryAuth";
+import {
+  type ResolvedToolSelection,
+  resolveToolSelection,
+} from "#app/utils/toolSelection";
+
+/**
+ * Assess pillar — the read-only product. Infraweaver's scanner
+ * engine has two modes off ONE codebase: Remediate = engine + fix loop + verify;
+ * **Assess = engine, read-only**. This surfaces that read-only half as a
+ * first-class deliverable: run the deterministic scanners, normalise into the
+ * findings schema, map to the compliance crosswalk, and produce a
+ * **scorecard** + an auditor-facing markdown report — WITHOUT touching the
+ * Terraform or opening a PR. No cloud credentials, no writes.
+ *
+ * The scorecard is deterministic (computed from tool results, never the model's
+ * word) so a CI gate can branch on `posture` and an assessor gets a reproducible,
+ * framework-mapped report.
+ */
+
+export type AssessPosture = "clean" | "advisory" | "action-required";
+
+export interface AssessTopRisk {
+  rule_id: string;
+  severity: Severity;
+  file: string;
+  line: number | null;
+  evidence: string;
+}
+
+/** A finding a human explicitly accepted (a suppression with a mandatory reason).
+ *  Surfaced as the report's audit trail — who waived what, why, and until when. */
+export interface AssessWaiver {
+  rule_id: string;
+  severity: Severity;
+  file: string;
+  line: number | null;
+  reason: string;
+  source: "inline" | "policy";
+  expires: string | null;
+}
+
+/** Per-language breadth line for the multi-language Assess scorecard. Honest by
+ *  construction: a language is either `scanned` (a scanner covered it) or listed
+ *  in `unsupported` (detected, but no static scanner can assess it — e.g. Pulumi),
+ *  never silently dropped. `by_language` counts OPEN concerns per scanned language. */
+export interface AssessmentLanguages {
+  /** every IaC language detected in the tree (superset of scanned + unsupported). */
+  detected: IacLanguage[];
+  /** languages this run reported on (scope ∩ what a scanner can read). */
+  scanned: IacLanguage[];
+  /** file count per detected language — the breadth signal. */
+  file_counts: Partial<Record<IacLanguage, number>>;
+  /** open-concern count per scanned language (0 for a clean language). */
+  by_language: Partial<Record<IacLanguage, number>>;
+  /** detected languages NO installed scanner can statically assess — surfaced,
+   * never scanned-and-silent (each with the honest reason). */
+  unsupported: { language: IacLanguage; reason: string }[];
+}
+
+export interface AssessmentScorecard {
+  /** clean (0 concerns) · advisory (only medium/low/info) · action-required (≥1 critical/high). */
+  posture: AssessPosture;
+  total: number;
+  by_severity: Record<Severity, number>;
+  /** multi-language breadth: which IaC languages were detected/scanned/unsupported
+   * and the open-concern count per scanned language. Terraform-only trees still
+   * report here (just one scanned language). */
+  languages: AssessmentLanguages;
+  /** highest-severity concerns first, capped — the "what to look at first" list. */
+  top_risks: AssessTopRisk[];
+  compliance: {
+    /** frameworks this scan touched (from the crosswalk's by_framework index). */
+    frameworks: string[];
+    /** distinct controls touched across all frameworks. */
+    controls_touched: number;
+    /** concerns that mapped to ≥1 control vs none (honest coverage signal). */
+    mapped: number;
+    unmapped: number;
+    version: string;
+    reviewed: string;
+  };
+  /** Cyber Essentials posture (0–100, indicative) + the distinct CE controls the
+   * OPEN concerns leave at risk — the report headline a CISO reads first. */
+  cyber_essentials: {
+    score: number;
+    controls_at_risk: string[];
+  };
+  /** findings a human explicitly accepted — the report's de-emphasised audit
+   * trail (excluded from posture/counts above; an expired waiver auto-resurfaces). */
+  waivers: AssessWaiver[];
+  /** five-status verification taxonomy: per-concern fail / not-code-verifiable +
+   * the scanner coverage (verified vs inconclusive). Keeps a "clean" posture
+   * honest — e.g. "clean, but tflint inconclusive (not run)". */
+  verification: VerificationSummary;
+}
+
+/** posture from the severity distribution: any critical/high ⇒ action-required;
+ * any lower-severity concern ⇒ advisory; nothing ⇒ clean. */
+export function assessPosture(
+  bySeverity: Record<Severity, number>,
+): AssessPosture {
+  if (bySeverity.critical > 0 || bySeverity.high > 0) return "action-required";
+  if (bySeverity.medium > 0 || bySeverity.low > 0 || bySeverity.info > 0)
+    return "advisory";
+  return "clean";
+}
+
+const TOP_RISK_CAP = 10;
+
+/**
+ * Build the deterministic assessment scorecard from a scan's concerns + their
+ * crosswalk report. Pure. `concerns` is the OPEN (non-suppressed) severity-sorted,
+ * deduped, Terraform-only set — posture, counts and the CE score reflect only what
+ * is unresolved; `suppressed` carries the accepted findings for the audit trail.
+ * `crosswalk` is `buildCrosswalkReport(concerns)`.
+ */
+export function buildAssessment(
+  concerns: Concern[],
+  crosswalk: CrosswalkReport,
+  verification: VerificationSummary,
+  suppressed: Concern[] = [],
+  languageScope?: LanguageScope,
+): AssessmentScorecard {
+  const by_severity: Record<Severity, number> = {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    low: 0,
+    info: 0,
+  };
+  for (const c of concerns) by_severity[c.severity]++;
+
+  // Multi-language breadth. Default (no scope supplied) = the historical
+  // Terraform-only shape, so every existing caller/test keeps a single scanned
+  // language without change.
+  const by_language: Partial<Record<IacLanguage, number>> = {};
+  for (const c of concerns) {
+    const lang = languageOfConcern(c);
+    by_language[lang] = (by_language[lang] ?? 0) + 1;
+  }
+  const languages: AssessmentLanguages = languageScope
+    ? {
+        detected: languageScope.detected,
+        scanned: languageScope.scanned,
+        file_counts: languageScope.fileCounts,
+        by_language,
+        unsupported: languageScope.unsupported,
+      }
+    : {
+        detected: ["terraform"],
+        scanned: ["terraform"],
+        file_counts: {},
+        by_language,
+        unsupported: [],
+      };
+
+  const top_risks = [...concerns]
+    .sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity])
+    .slice(0, TOP_RISK_CAP)
+    .map((c) => ({
+      rule_id: c.rule_id,
+      severity: c.severity,
+      file: c.location.file,
+      line: c.location.line,
+      evidence: c.evidence,
+    }));
+
+  const controls_touched = Object.values(crosswalk.by_framework).reduce(
+    (n, controls) => n + controls.length,
+    0,
+  );
+
+  const waivers: AssessWaiver[] = suppressed
+    .filter((c) => c.suppression)
+    .map((c) => ({
+      rule_id: c.rule_id,
+      severity: c.severity,
+      file: c.location.file,
+      line: c.location.line,
+      reason: c.suppression?.reason ?? "",
+      source: c.suppression?.source ?? "policy",
+      expires: c.suppression?.expires ?? null,
+    }));
+
+  return {
+    posture: assessPosture(by_severity),
+    total: concerns.length,
+    by_severity,
+    languages,
+    top_risks,
+    compliance: {
+      frameworks: Object.keys(crosswalk.by_framework),
+      controls_touched,
+      mapped: crosswalk.entries.length,
+      unmapped: crosswalk.unmapped_concern_ids.length,
+      version: crosswalk.version,
+      reviewed: crosswalk.reviewed,
+    },
+    cyber_essentials: {
+      score: cyberEssentialsScore(concerns),
+      controls_at_risk: cyberEssentialsControlsAtRisk(concerns),
+    },
+    waivers,
+    verification,
+  };
+}
+
+const POSTURE_BANNER: Record<AssessPosture, string> = {
+  clean:
+    "> [!NOTE]\n> ✅ **Clean** — no best-practice concerns found at the configured threshold.",
+  advisory:
+    "> [!WARNING]\n> ⚠️ **Advisory** — concerns found, but none critical/high. Plan to address them.",
+  "action-required":
+    "> [!CAUTION]\n> 🚨 **Action required** — critical/high-severity concerns found. Review before relying on this Terraform.",
+};
+
+/** Optional render-time context the scorecard can't hold on its own. `delta` is
+ *  the run-to-run change vs the committed baseline checkpoint (null when no
+ *  baseline exists — there's nothing to compare against). */
+export interface AssessRenderContext {
+  delta?: { delta: BaselineDelta; since: string | null } | null;
+}
+
+/** The Cyber Essentials posture headline — the CISO-facing number the report
+ *  leads with (mirrors a "Failed (22%)"-style lead, but as a 0–100 score). */
+function renderCyberEssentialsHeadline(s: AssessmentScorecard): string {
+  const { score, controls_at_risk } = s.cyber_essentials;
+  const atRisk = controls_at_risk.length
+    ? `${controls_at_risk.length} control(s) at risk: ${controls_at_risk.join(", ")}`
+    : "no mapped controls at risk";
+  return `> **Cyber Essentials posture: ${score} / 100** (indicative) — ${atRisk}.`;
+}
+
+/** The run-to-run delta line — what changed since the baseline checkpoint.
+ *  Reads "no status changes" when nothing was added or fixed, mirroring the
+ *  push-to-push signal reviewers expect. */
+function renderDeltaLine(delta: BaselineDelta, since: string | null): string {
+  const ref = since ? `baseline (${since})` : "baseline";
+  if (delta.added === 0 && delta.fixed === 0) {
+    return `**Since ${ref}:** no status changes — ${delta.unchanged} carried.`;
+  }
+  return (
+    `**Since ${ref}:** 🔺 ${delta.added} new · ✅ ${delta.fixed} fixed · ` +
+    `${delta.unchanged} unchanged.`
+  );
+}
+
+/** The accepted/waived findings audit trail — de-emphasised (collapsed), kept out
+ *  of the posture above, and honest that an expired waiver resurfaces the finding. */
+function renderWaiverBlock(waivers: AssessWaiver[]): string[] {
+  const lines: string[] = [];
+  lines.push(
+    `<details><summary>🤝 Accepted / waived findings (${waivers.length})</summary>`,
+  );
+  lines.push("");
+  lines.push(
+    "Explicitly accepted by a human (a suppression with a mandatory reason). " +
+      "These do **not** affect the posture above; an expired waiver auto-resurfaces the finding.",
+  );
+  lines.push("");
+  for (const w of waivers) {
+    const loc = w.line !== null ? `\`${w.file}:${w.line}\`` : `\`${w.file}\``;
+    const expiry = w.expires ? `expires ${w.expires}` : "no expiry";
+    lines.push(
+      `- ${severityEmoji(w.severity)} \`${w.rule_id}\` — ${loc} — ${w.reason} ` +
+        `(source: ${w.source}, ${expiry})`,
+    );
+  }
+  lines.push("");
+  lines.push("</details>");
+  return lines;
+}
+
+/** The in-comment "fix it from here" call-to-action — names the exact
+ *  `@infraweaver fix …` comment commands a reviewer can post to dispatch a scoped,
+ *  `✗→✓`-verified remediation PR (the comment-trigger surface; it never merges).
+ *  Only rendered when there's something open to fix. */
+function renderRemediationCta(): string[] {
+  return [
+    "> [!TIP]",
+    `> **Fix it from here** — comment one of these and ${PRODUCT_NAME} opens a scoped PR that proves ` +
+      "each concern cleared (`✗→✓`) for your review (it never merges):",
+    ">",
+    `> - \`${COMMENT_COMMAND} fix all high-severity\` — every concern at/above a severity`,
+    `> - \`${COMMENT_COMMAND} fix #<id>\` — a single finding (the id from Top risks)`,
+    `> - \`${COMMENT_COMMAND} fix <file>\` — one file's group`,
+    `> - \`${COMMENT_COMMAND} fix all\` — everything (bounded by \`max_prs\`)`,
+  ];
+}
+
+/**
+ * The multi-language breadth section. Renders ONLY when there's something worth
+ * saying — Assess scanned a non-Terraform language, or a detected language could
+ * not be scanned (the honest coverage gap). A pure Terraform tree returns [] so
+ * the report is byte-for-byte unchanged. Deterministic; language order matches
+ * `scanned` (most files first). Pure.
+ */
+function renderLanguageBlock(langs: AssessmentLanguages): string[] {
+  const nonTf = langs.scanned.filter((l) => l !== "terraform");
+  if (nonTf.length === 0 && langs.unsupported.length === 0) return [];
+
+  const lines: string[] = ["### IaC languages scanned", ""];
+  const cells = langs.scanned.map((l) => {
+    const n = langs.by_language[l] ?? 0;
+    return `\`${LANGUAGE_LABEL[l]}: ${n}\``;
+  });
+  lines.push(
+    `Assess is Terraform-first but reads every IaC language your scanners parse. ` +
+      `Scanned **${langs.scanned.length}** language(s): ${cells.join(" · ")}.`,
+  );
+  // Remediate scope caveat — the moat line, stated plainly so a reader never
+  // mistakes multi-language Assess for multi-language auto-fix.
+  if (nonTf.length > 0) {
+    lines.push("");
+    lines.push(
+      `> Findings outside Terraform are **assessed, not auto-remediated** — the proven \`✗→✓\` fix loop ` +
+        `is Terraform-specific. Fix non-Terraform findings by hand using the guidance above.`,
+    );
+  }
+  if (langs.unsupported.length > 0) {
+    lines.push("");
+    lines.push("> [!WARNING]");
+    lines.push(
+      "> **Detected but not assessed** (no static scanner covers these — a coverage gap, not a pass):",
+    );
+    for (const u of langs.unsupported) {
+      lines.push(`> - \`${LANGUAGE_LABEL[u.language]}\` — ${u.reason}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Render the scorecard as a deterministic, auditor-facing markdown report (the
+ * Assess deliverable). Built entirely from the scorecard so it's reproducible and
+ * model-independent. Pure.
+ */
+export function renderAssessmentMarkdown(
+  s: AssessmentScorecard,
+  ctx: AssessRenderContext = {},
+): string {
+  const lines: string[] = [];
+  lines.push(POSTURE_BANNER[s.posture]);
+  lines.push("");
+  lines.push(renderCyberEssentialsHeadline(s));
+  lines.push("");
+  // Title reflects the breadth honestly: "Terraform" when that's all that was
+  // scanned (the common case), "IaC" when Assess widened to other languages.
+  const multiLang = s.languages.scanned.some((l) => l !== "terraform");
+  lines.push(`## ${multiLang ? "IaC" : "Terraform"} best-practice assessment`);
+  lines.push("");
+  const sevOrder: Severity[] = ["critical", "high", "medium", "low", "info"];
+  const sevCells = sevOrder
+    .filter((sev) => s.by_severity[sev] > 0)
+    .map((sev) => `\`${sev}: ${s.by_severity[sev]}\``);
+  lines.push(
+    `**${s.total} concern${s.total === 1 ? "" : "s"}** — ${
+      sevCells.length ? sevCells.join(" · ") : "none"
+    }`,
+  );
+  if (ctx.delta) {
+    lines.push("");
+    lines.push(renderDeltaLine(ctx.delta.delta, ctx.delta.since));
+  }
+  lines.push("");
+
+  // Multi-language breadth — only when Assess widened past Terraform, or when a
+  // detected language couldn't be scanned (the honest coverage gap). A pure
+  // Terraform tree keeps the report exactly as before.
+  const langBlock = renderLanguageBlock(s.languages);
+  if (langBlock.length > 0) {
+    lines.push(...langBlock);
+    lines.push("");
+  }
+
+  if (s.top_risks.length > 0) {
+    lines.push("### Top risks");
+    lines.push("");
+    for (const r of s.top_risks) {
+      const loc = r.line !== null ? `\`${r.file}:${r.line}\`` : `\`${r.file}\``;
+      lines.push(
+        `- ${severityEmoji(r.severity)} \`${r.rule_id}\` — ${loc} — ${r.evidence}`,
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push("### Compliance crosswalk");
+  lines.push("");
+  if (s.compliance.frameworks.length > 0) {
+    lines.push(
+      `Indicative alignment (crosswalk v${s.compliance.version}, reviewed ${s.compliance.reviewed}) — ` +
+        `**not an audit verdict**. Touches ${s.compliance.controls_touched} control(s) across ` +
+        `${s.compliance.frameworks.length} framework(s): ${s.compliance.frameworks.join(", ")}.`,
+    );
+    if (s.compliance.unmapped > 0) {
+      lines.push("");
+      lines.push(
+        `> ${s.compliance.unmapped} concern(s) did not map to a control in the starter rule-pack (honest coverage gap).`,
+      );
+    }
+  } else {
+    lines.push(
+      "No concerns mapped to a compliance control in the starter rule-pack.",
+    );
+  }
+  lines.push("");
+
+  // five-status verification taxonomy — keep the posture honest about coverage.
+  const v = s.verification;
+  lines.push("### Verification coverage");
+  lines.push("");
+  lines.push(
+    `Code-verified by: ${v.coverage.verified.length ? v.coverage.verified.join(", ") : "none"}.`,
+  );
+  if (v.coverage.inconclusive.length > 0) {
+    lines.push("");
+    lines.push(
+      `> [!WARNING]\n> **Inconclusive** (a coverage gap, not a pass) — these checks did not run:`,
+    );
+    for (const t of v.coverage.inconclusive)
+      lines.push(`> - \`${t.source}\` — ${t.reason}`);
+  }
+  if (v.counts.not_code_verifiable > 0) {
+    lines.push("");
+    lines.push(
+      `> ${v.counts.not_code_verifiable} concern(s) are **not code-verifiable** — they need a human/process decision (e.g. IAM least-privilege, a KMS key policy) the engine can flag but not prove.`,
+    );
+  }
+  lines.push("");
+  lines.push(`_${v.note}_`);
+
+  if (s.waivers.length > 0) {
+    lines.push("");
+    lines.push(...renderWaiverBlock(s.waivers));
+  }
+
+  // The "@infraweaver fix …" CTA is offered ONLY when there's a Terraform concern
+  // to fix — the fix loop is Terraform-only, so inviting a fix in a repo whose
+  // open findings are all CloudFormation/Kubernetes/etc. would advertise a no-op
+  // (and contradict the "assessed, not auto-remediated" caveat above). A pure
+  // Terraform tree is unchanged (every open concern counts under `terraform`).
+  if ((s.languages.by_language.terraform ?? 0) > 0) {
+    lines.push("");
+    lines.push(...renderRemediationCta());
+  }
+
+  lines.push("");
+  lines.push(
+    "_Read-only assessment — no Terraform was modified and no PR was opened._",
+  );
+  return lines.join("\n");
+}
+
+function severityEmoji(sev: Severity): string {
+  switch (sev) {
+    case "critical":
+      return "🚨";
+    case "high":
+      return "⚠️";
+    case "medium":
+      return "🔶";
+    case "low":
+      return "ℹ️";
+    default:
+      return "·";
+  }
+}
+
+export const TerraformAssessParams = type({
+  "severity_threshold?": type(
+    "'critical' | 'high' | 'medium' | 'low' | 'info'",
+  ).describe(
+    "minimum severity to include (default: the run's configured threshold, else low).",
+  ),
+});
+
+/** the full read-only assessment pipeline: scan (honouring the licence gate
+ * + module-fetch credential) → crosswalk → verification taxonomy → scorecard.
+ * Shared by `terraform_assess` and the evidence-bundle emitter so both report the
+ * identical posture from the identical toolchain. Pure-ish (only the scanners do
+ * I/O); no writes. */
+export function runAssessmentPipeline(
+  ctx: LocalToolContext,
+  threshold: Severity,
+): {
+  cwd: string;
+  selection: ResolvedToolSelection;
+  /** the resolved multi-language scope (detected / scanned / unsupported). */
+  languageScope: LanguageScope;
+  outcomes: ScannerOutcome[];
+  /** the full annotated set (suppression metadata attached) — what the Cloud report needs. */
+  concerns: Concern[];
+  /** the OPEN subset — what posture/score/crosswalk reflect. */
+  open: Concern[];
+  /** the accepted/waived subset — the audit trail. */
+  suppressed: Concern[];
+  crosswalk: CrosswalkReport;
+  verification: VerificationSummary;
+  scorecard: AssessmentScorecard;
+  /** run-to-run change vs the committed baseline; null when no baseline exists. */
+  delta: { delta: BaselineDelta; since: string | null } | null;
+} {
+  const cwd = ctx.payload.cwd ?? process.cwd();
+  const minRank = SEVERITY_RANK[threshold];
+
+  // Multi-language Assess: detect which IaC languages the tree contains and
+  // resolve the operator's `iac_languages` scope against it. This is a READ-ONLY
+  // surface, so it may widen past Terraform — trivy + checkov already parse
+  // CloudFormation / Kubernetes / Helm / Dockerfile / ARM / Bicep, and the fix
+  // loop stays Terraform-first regardless. Detected-but-unscannable languages
+  // (Pulumi) are surfaced as `unsupported`, never scanned-and-silent.
+  const languageScope = resolveLanguageScope(
+    ctx.payload.iacLanguages,
+    detectIacLanguages(cwd),
+  );
+
+  // same licence gate + module credentials (git-transport + private-registry
+  // token) as terraform_scan, so a gated tool (e.g. tflint) shows up as
+  // INCONCLUSIVE coverage, not a silent pass, and a private cross-repo/registry
+  // module still resolves during the read-only scan's init. The resolved selection
+  // is returned so the read-only/auditor surfaces can be as transparent about the
+  // toolchain (gated / disabled / mistyped tokens) as terraform_scan is — silence
+  // on the assess side would read as "fully covered".
+  const selection = resolveToolSelection(ctx.payload);
+  const outcomes = runScanners(cwd, {
+    selection,
+    terraformEnv: resolveModuleCredentialEnv(ctx.payload, {
+      sshKeyDir: ctx.tmpdir,
+    }),
+    // scope checkov to the detected/requested languages (trivy scans every format
+    // it finds; the language tag + scope filter below keep both honest).
+    checkovFrameworks: checkovFrameworksFor(languageScope.scanned),
+    toolsNetwork: ctx.payload.toolsNetwork,
+  });
+  // Re-check the scope against what ACTUALLY ran: a language whose only covering
+  // scanner was skipped/disabled this run must report as a coverage gap, never
+  // as scanned-clean-with-zero-findings.
+  const effectiveScope = applyScannerAvailability(languageScope, {
+    trivy: outcomes.some((o) => o.source === "trivy" && o.ran),
+    checkov: outcomes.some((o) => o.source === "checkov" && o.ran),
+  });
+  const inScope = inLanguageScope(effectiveScope);
+  const scanned = attachSourceSnippets(
+    sortConcerns(dedupe(outcomes.flatMap((o) => o.concerns)))
+      .filter(inScope)
+      .filter((c) => SEVERITY_RANK[c.severity] >= minRank),
+    cwd,
+  );
+  // Annotate suppressions once, then split. Posture, counts, score and crosswalk
+  // reflect only the OPEN findings (a suppression is an accepted finding — kept
+  // out of the posture and surfaced in the waiver audit trail instead); `concerns`
+  // stays the full annotated set the Cloud report carries.
+  const concerns = suppressConcerns(scanned, cwd);
+  const open = concerns.filter((c) => !c.suppression);
+  const suppressed = concerns.filter((c) => c.suppression);
+
+  const crosswalk = buildCrosswalkReport(
+    open.map((c) => ({
+      id: c.id,
+      rule_id: c.rule_id,
+      evidence: c.evidence,
+      category: c.category,
+      severity: c.severity,
+      location: c.location,
+    })),
+  );
+  const verification = buildVerificationSummary(open, outcomes);
+  const scorecard = buildAssessment(
+    open,
+    crosswalk,
+    verification,
+    suppressed,
+    effectiveScope,
+  );
+
+  // Run-to-run delta vs the committed baseline checkpoint (the engine's own
+  // reference point); null when no baseline exists — nothing to compare against.
+  const baseline = loadBaselineWithMeta(cwd);
+  const delta = baseline
+    ? { delta: baselineDelta(open, baseline.keys), since: baseline.created }
+    : null;
+
+  return {
+    cwd,
+    selection,
+    languageScope: effectiveScope,
+    outcomes,
+    concerns,
+    open,
+    suppressed,
+    crosswalk,
+    verification,
+    scorecard,
+    delta,
+  };
+}
+
+export function TerraformAssessTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_assess",
+    description:
+      "Read-only IaC best-practice ASSESSMENT (the Assess pillar — the scanner engine surfaced as a " +
+      "product). Terraform-first, but it also assesses every other IaC language the installed scanners parse " +
+      "(CloudFormation, Kubernetes, Helm, Dockerfile, Azure ARM/Bicep, Serverless, Ansible; OpenTofu `.tf`/" +
+      "`.tofu`) — scope it with the `iac_languages` input. Runs the deterministic scanners, then returns a " +
+      "deterministic `scorecard` (overall `posture` — clean / advisory / action-required, `by_severity` counts, " +
+      "a `languages` breadth block, `top_risks`, an indicative compliance-crosswalk summary, and a five-status " +
+      "`verification` coverage block) plus a ready-to-post `markdown` report. It NEVER modifies any file or opens " +
+      "a PR — use it to report posture (e.g. in a job summary or a CI gate on `posture`). A detected language no " +
+      "scanner can read (e.g. Pulumi) is reported under `languages.unsupported`, never silently dropped. Pairs " +
+      "with `terraform_emit_sarif` (Security tab), `terraform_emit_evidence` (auditor bundle), and `infracost_diff` " +
+      "/ `terraform_version_currency`. For the proven fix loop (Terraform only), use `terraform_scan` + Remediate.",
+    parameters: TerraformAssessParams,
+    execute: execute(async ({ severity_threshold }) => {
+      const configured = ctx.payload.severityThreshold as Severity | undefined;
+      const threshold: Severity = severity_threshold ?? configured ?? "low";
+
+      const {
+        cwd,
+        selection,
+        languageScope,
+        outcomes,
+        concerns,
+        scorecard,
+        delta,
+      } = runAssessmentPipeline(ctx, threshold);
+      // a mistyped iac_languages token is silently ignored otherwise — surface it
+      // like a mistyped tools_enabled token so the operator knows their scope
+      // narrowing didn't take.
+      if (languageScope.unknown_tokens.length > 0) {
+        log.warning(
+          `» iac_languages: ignoring unrecognised language(s) [${languageScope.unknown_tokens.join(", ")}]`,
+        );
+      }
+      // Publish the reported concern set (the pipeline already applied suppressions)
+      // so finalizeSuccessRun's emitFindingsOutputs + reportToCloud fire — assess IS
+      // the report path, but lastScanConcerns was only ever set by terraform_scan
+      // (Remediate), so Cloud reporting silently no-opped in Assess.
+      scanSessionOf(ctx.toolState).lastScanConcerns = concerns;
+      const markdown = renderAssessmentMarkdown(scorecard, { delta });
+
+      const ran = outcomes.filter((o) => o.ran).map((o) => o.source);
+      // a mistyped tools_enabled token is otherwise silently ignored; in a
+      // read-only assessment that's a footgun (the operator thinks they configured
+      // something they didn't). Surface it the same way terraform_scan does.
+      if (selection.unknownTokens.length > 0) {
+        log.warning(
+          `» tools_enabled: ignoring unrecognised tool(s) [${selection.unknownTokens.join(", ")}]`,
+        );
+      }
+      log.info(
+        `» terraform_assess: ${scorecard.posture} — ${scorecard.total} concern(s) ` +
+          `(${scorecard.compliance.controls_touched} control(s) across ${scorecard.compliance.frameworks.length} framework(s)) ` +
+          `across [${scorecard.languages.scanned.join(", ")}] from [${ran.join(", ")}]`,
+      );
+      return toolOk({
+        scanned_dir: cwd,
+        scanners_ran: ran,
+        // multi-language breadth: the languages detected/scanned + any detected
+        // language no scanner could assess (surfaced, never silently dropped).
+        languages: {
+          detected: languageScope.detected,
+          scanned: languageScope.scanned,
+          unsupported: languageScope.unsupported,
+          unknown_tokens: languageScope.unknown_tokens,
+        },
+        // parity with terraform_scan: which tools were licence-gated off, which
+        // the operator disabled, and which tokens were unrecognised — so the
+        // assessment is honest about its own coverage, not silently partial.
+        tool_selection: {
+          licence_gated: selection.gated,
+          disabled: selection.disabled,
+          unknown_tokens: selection.unknownTokens,
+        },
+        scorecard,
+        markdown,
+      });
+    }),
+  });
+}