terramend 0.2.0 → 0.2.1

package/src/mcp/assess.ts

@@ -0,0 +1,341 @@
+import { type } from "arktype";
+import { buildCrosswalkReport, type CrosswalkReport } from "#app/mcp/crosswalk";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { runScanners } from "#app/mcp/terraform/scanners";
+import {
+  type Concern,
+  dedupe,
+  isTerraformConcern,
+  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 { resolveModuleFetchEnv } from "#app/utils/moduleFetch";
+import { type ResolvedToolSelection, resolveToolSelection } from "#app/utils/toolSelection";
+
+/**
+ * Assess pillar — the read-only product (roadmap pillar 3). Terramend'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 (§23), 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;
+}
+
+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>;
+  /** 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;
+  };
+  /** 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` should be the severity-sorted, deduped,
+ * Terraform-only set; `crosswalk` is `buildCrosswalkReport(concerns)`.
+ */
+export function buildAssessment(
+  concerns: Concern[],
+  crosswalk: CrosswalkReport,
+  verification: VerificationSummary,
+): 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]++;
+
+  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,
+  );
+
+  return {
+    posture: assessPosture(by_severity),
+    total: concerns.length,
+    by_severity,
+    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,
+    },
+    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.",
+};
+
+/**
+ * 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): string {
+  const lines: string[] = [];
+  lines.push(POSTURE_BANNER[s.posture]);
+  lines.push("");
+  lines.push("## 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"
+    }`,
+  );
+  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}_`);
+
+  lines.push("");
+  lines.push(
+    "_Read-only assessment — no Terraform was modified and no PR was opened. " +
+      "Run Terramend in `remediate` mode to fix and prove these concerns._",
+  );
+  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 §1.5 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;
+  outcomes: ScannerOutcome[];
+  concerns: Concern[];
+  crosswalk: CrosswalkReport;
+  verification: VerificationSummary;
+  scorecard: AssessmentScorecard;
+} {
+  const cwd = ctx.payload.cwd ?? process.cwd();
+  const minRank = SEVERITY_RANK[threshold];
+  // §1.5 — same licence gate + module-fetch credential as terraform_scan, so a
+  // gated tool (e.g. tflint) shows up as INCONCLUSIVE coverage, not a silent pass.
+  // 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: resolveModuleFetchEnv(ctx.payload),
+  });
+  const concerns = sortConcerns(dedupe(outcomes.flatMap((o) => o.concerns)))
+    .filter(isTerraformConcern)
+    .filter((c) => SEVERITY_RANK[c.severity] >= minRank);
+  const crosswalk = buildCrosswalkReport(
+    concerns.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(concerns, outcomes);
+  const scorecard = buildAssessment(concerns, crosswalk, verification);
+  return { cwd, selection, outcomes, concerns, crosswalk, verification, scorecard };
+}
+
+export function TerraformAssessTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_assess",
+    description:
+      "Read-only Terraform best-practice ASSESSMENT (the Assess pillar — the scanner engine surfaced as a " +
+      "product). Runs the deterministic scanners, then returns a deterministic `scorecard` (overall " +
+      "`posture` — clean / advisory / action-required, `by_severity` counts, `top_risks`, an indicative " +
+      "compliance-crosswalk summary, and a five-status `verification` coverage block) plus a ready-to-post " +
+      "`markdown` report. It NEVER modifies Terraform or opens a PR — use it to report posture (e.g. in a job " +
+      "summary or a CI gate on `posture`). Pairs with `terraform_emit_sarif` (Security tab), " +
+      "`terraform_emit_evidence` (auditor bundle), and `infracost_diff` / `terraform_version_currency` for the " +
+      "cost and currency lenses. For the fix loop, use `terraform_scan` + the Remediate mode instead.",
+    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, outcomes, scorecard } = runAssessmentPipeline(ctx, threshold);
+      const markdown = renderAssessmentMarkdown(scorecard);
+
+      const ran = outcomes.filter((o) => o.ran).map((o) => o.source);
+      // §1.5 — 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)) ` +
+          `from [${ran.join(", ")}]`,
+      );
+      return toolOk({
+        scanned_dir: cwd,
+        scanners_ran: ran,
+        // 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,
+      });
+    }),
+  });
+}

package/src/mcp/changeSummary.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { parseBlockAddress, summarizeTerraformResourceDiff } from "#app/mcp/changeSummary";
+
+describe("parseBlockAddress", () => {
+  it("parses two-label resource/data blocks into addresses", () => {
+    expect(parseBlockAddress('resource "aws_s3_bucket" "logs" {')).toBe("aws_s3_bucket.logs");
+    expect(parseBlockAddress('  data "aws_ami" "ubuntu" {')).toBe("data.aws_ami.ubuntu");
+  });
+
+  it("parses single-label module/variable/output/provider blocks", () => {
+    expect(parseBlockAddress('module "vpc" {')).toBe("module.vpc");
+    expect(parseBlockAddress('variable "region" {')).toBe("var.region");
+    expect(parseBlockAddress('output "url" {')).toBe("output.url");
+    expect(parseBlockAddress('provider "aws" {')).toBe("provider.aws");
+  });
+
+  it("returns null for non-block lines", () => {
+    expect(parseBlockAddress('  cidr_blocks = ["10.0.0.0/16"]')).toBeNull();
+    expect(parseBlockAddress("}")).toBeNull();
+    expect(parseBlockAddress('resource "aws_s3_bucket" {')).toBeNull(); // missing name label
+  });
+});
+
+describe("summarizeTerraformResourceDiff", () => {
+  it("collects added/removed block addresses and touched files, ignoring non-tf files", () => {
+    const diff = `diff --git a/main.tf b/main.tf
+--- a/main.tf
++++ b/main.tf
+@@ -1,3 +1,8 @@
++resource "aws_s3_bucket" "logs" {
++  bucket = "x"
++}
+-resource "aws_launch_configuration" "web" {
+-  image_id = "ami-1"
+-}
+   cidr_blocks = ["10.0.0.0/16"]
+diff --git a/README.md b/README.md
+--- a/README.md
++++ b/README.md
+@@ -1 +1 @@
++resource "aws_s3_bucket" "not_terraform" {
+`;
+    const s = summarizeTerraformResourceDiff(diff);
+    expect(s.added).toEqual(["aws_s3_bucket.logs"]);
+    expect(s.removed).toEqual(["aws_launch_configuration.web"]);
+    // the README "resource" line must NOT be counted (not a .tf file)
+    expect(s.added).not.toContain("aws_s3_bucket.not_terraform");
+    expect(s.files).toEqual(["main.tf"]);
+    expect(s.counts).toEqual({ added: 1, removed: 1, files: 1 });
+  });
+
+  it("surfaces an in-place block edit as a touched file (not an added/removed address)", () => {
+    const diff = `diff --git a/vpc.tf b/vpc.tf
+--- a/vpc.tf
++++ b/vpc.tf
+@@ -2,3 +2,3 @@ resource "aws_security_group" "db" {
+-  description = "old"
++  description = "new"
+`;
+    const s = summarizeTerraformResourceDiff(diff);
+    expect(s.added).toEqual([]);
+    expect(s.removed).toEqual([]);
+    expect(s.files).toEqual(["vpc.tf"]);
+  });
+
+  it("counts a new module addition across a new .tf file", () => {
+    const diff = `diff --git a/modules.tf b/modules.tf
+--- /dev/null
++++ b/modules.tf
+@@ -0,0 +1,4 @@
++module "vpc" {
++  source = "./modules/vpc"
++}
+`;
+    const s = summarizeTerraformResourceDiff(diff);
+    expect(s.added).toEqual(["module.vpc"]);
+    expect(s.files).toEqual(["modules.tf"]);
+  });
+
+  it("is empty for a diff that touches no Terraform files", () => {
+    const diff = `diff --git a/app.py b/app.py
+--- a/app.py
++++ b/app.py
+@@ -1 +1 @@
++print("hi")
+`;
+    expect(summarizeTerraformResourceDiff(diff)).toEqual({
+      added: [],
+      removed: [],
+      files: [],
+      counts: { added: 0, removed: 0, files: 0 },
+    });
+  });
+});

package/src/mcp/changeSummary.ts

@@ -0,0 +1,145 @@
+import { type } from "arktype";
+import { resolveBaseBranch } from "#app/mcp/pr";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { skipResult } from "#app/mcp/terraform/types";
+import { log } from "#app/utils/cli";
+import { $ } from "#app/utils/shell";
+
+/**
+ * §36 AI PR summaries — the deterministic Terraform-change anchor. A PR summary
+ * written purely by the model drifts (miscounts resources, invents changes). This
+ * parses the PR's unified diff for Terraform BLOCK changes (which resource /
+ * module / data / variable / output addresses were added or removed, which files
+ * were touched) so the human-readable summary is anchored to facts, not prose.
+ *
+ * Pure parser (`summarizeTerraformResourceDiff`) + a tool that runs the
+ * merge-base diff and feeds it in. Block ADDED/REMOVED is precise (a block header
+ * on a +/- line); in-place edits to an existing block surface as a touched FILE
+ * (attributing a sub-block edit to a specific address needs full-file parsing —
+ * we stay honest and report the file rather than guess).
+ */
+
+export interface TerraformChangeSummary {
+  /** addresses of blocks added in this diff (e.g. `aws_s3_bucket.logs`, `module.vpc`). */
+  added: string[];
+  /** addresses of blocks removed in this diff. */
+  removed: string[];
+  /** Terraform files touched (a superset signal — includes in-place edits). */
+  files: string[];
+  counts: { added: number; removed: number; files: number };
+}
+
+const isTfFile = (file: string): boolean => /\.tf$|\.tfvars$/.test(file);
+
+/**
+ * Parse a Terraform block header into its address, or null when the line is not a
+ * top-level block header. Handles two-label blocks (`resource`/`data`) and
+ * single-label blocks (`module`/`variable`/`output`/`provider`). The line is the
+ * raw HCL (diff +/- prefix already stripped). Pure.
+ */
+export function parseBlockAddress(line: string): string | null {
+  const s = line.trim();
+  const two = s.match(/^(resource|data)\s+"([^"]+)"\s+"([^"]+)"\s*\{/);
+  if (two) {
+    const [, kind, t, name] = two;
+    return kind === "data" ? `data.${t}.${name}` : `${t}.${name}`;
+  }
+  const one = s.match(/^(module|variable|output|provider)\s+"([^"]+)"\s*\{/);
+  if (one) {
+    const [, kind, name] = one;
+    const prefix = kind === "variable" ? "var" : kind;
+    return `${prefix}.${name}`;
+  }
+  return null;
+}
+
+/**
+ * Summarise a unified `git diff` into added/removed Terraform block addresses +
+ * the touched Terraform files. Tracks the current file from `+++ b/<path>`
+ * headers and only considers `.tf`/`.tfvars` files. Pure; deterministic ordering
+ * (sorted, de-duplicated). A block counted as both added and removed (moved) is
+ * left in both lists — the prose can describe the move.
+ */
+export function summarizeTerraformResourceDiff(diff: string): TerraformChangeSummary {
+  const added = new Set<string>();
+  const removed = new Set<string>();
+  const files = new Set<string>();
+  let file = "";
+  let inTf = false;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      const path = raw.slice(4).trim().replace(/^b\//, "");
+      file = path === "/dev/null" ? "" : path;
+      inTf = !!file && isTfFile(file);
+      continue;
+    }
+    if (raw.startsWith("--- ") || raw.startsWith("diff --git") || raw.startsWith("@@")) continue;
+    if (!inTf) continue;
+    if (raw.startsWith("+") || raw.startsWith("-")) {
+      files.add(file);
+      const addr = parseBlockAddress(raw.slice(1));
+      if (addr) (raw.startsWith("+") ? added : removed).add(addr);
+    }
+  }
+  const sort = (s: Set<string>): string[] => [...s].sort();
+  return {
+    added: sort(added),
+    removed: sort(removed),
+    files: sort(files),
+    counts: { added: added.size, removed: removed.size, files: files.size },
+  };
+}
+
+export const TerraformChangeSummaryParams = type({
+  "base?": type.string.describe(
+    "base branch to diff against (default: the run's resolved base branch — main/master or the base_branch input).",
+  ),
+});
+
+export function TerraformChangeSummaryTool(ctx: ToolContext) {
+  return tool({
+    name: "terraform_change_summary",
+    description:
+      "§36 — a DETERMINISTIC anchor for a PR summary: the Terraform `resource`/`module`/`data`/`variable`/" +
+      "`output` addresses ADDED and REMOVED on this branch vs its base, plus the Terraform files touched. " +
+      "Runs a merge-base `git diff` of `*.tf`/`*.tfvars` and parses the block headers, so the human-readable " +
+      "summary you write is grounded in real counts instead of guessed ones. Degrades green (returns " +
+      "`ok: false`) when git can't resolve the base (fetch it first) or nothing Terraform changed — then " +
+      "summarise from the diff yourself. In-place edits to an existing block surface as a touched `file` " +
+      "(not an added/removed address). Use it in SummarizePr (or any PR summary) before writing the prose.",
+    parameters: TerraformChangeSummaryParams,
+    execute: execute(async ({ base }) => {
+      const baseBranch = base ?? resolveBaseBranch(ctx);
+      const pathspec = ["--", "*.tf", "*.tfvars"];
+      let diff: string | null = null;
+      // prefer the remote-tracking base (origin/<base>), fall back to a local ref.
+      for (const ref of [`origin/${baseBranch}`, baseBranch]) {
+        try {
+          diff = $("git", ["diff", "--merge-base", ref, ...pathspec], { log: false });
+          break;
+        } catch {
+          diff = null;
+        }
+      }
+      if (diff === null) {
+        return skipResult(
+          "base_unresolved",
+          `could not diff against '${baseBranch}' (fetch the base first, e.g. git_fetch({ ref: "${baseBranch}" })) — summarise from the diff yourself`,
+        );
+      }
+      const summary = summarizeTerraformResourceDiff(diff);
+      if (summary.counts.files === 0) {
+        return skipResult(
+          "no_terraform_changes",
+          "no Terraform files changed vs the base — this PR's summary is not Terraform-specific; summarise from the diff yourself",
+        );
+      }
+      log.info(
+        `» terraform_change_summary: +${summary.counts.added} -${summary.counts.removed} block(s) ` +
+          `across ${summary.counts.files} file(s) vs ${baseBranch}`,
+      );
+      return toolOk({ base: baseBranch, ...summary });
+    }),
+  });
+}

package/src/mcp/crosswalk.ts

@@ -1,6 +1,10 @@
 import { type } from "arktype";
 import type { ToolContext } from "#app/mcp/server";
 import { execute, tool, toolOk } from "#app/mcp/shared";
+import {
+  type ConcernVerificationStatus,
+  concernVerificationStatus,
+} from "#app/mcp/terraform/verification";
 import { log } from "#app/utils/cli";
 
 /**
@@ -248,6 +252,10 @@ export interface CrosswalkEntry {
   rule_id: string;
   themes: string[];
   controls: ControlRef[];
+  /** the five-status verdict for this control statement: `fail` (code-verified
+   * violation) or `not-code-verifiable` (a human-decision control the engine can
+   * flag but not prove). Lets an assessor read the crosswalk honestly. */
+  status: ConcernVerificationStatus;
 }
 
 export interface CrosswalkReport {
@@ -277,7 +285,13 @@ export function buildCrosswalkReport(concerns: ConcernForCrosswalk[]): Crosswalk
       unmapped.push(c.id);
       continue;
     }
-    entries.push({ concern_id: c.id, rule_id: c.rule_id, themes, controls });
+    entries.push({
+      concern_id: c.id,
+      rule_id: c.rule_id,
+      themes,
+      controls,
+      status: concernVerificationStatus(c).status,
+    });
     for (const ctl of controls) {
       const map = byFramework.get(ctl.framework) ?? new Map<string, string>();
       if (!map.has(ctl.control)) map.set(ctl.control, ctl.title);

package/src/mcp/guardrails.ts

@@ -5,6 +5,7 @@ import type { ToolContext } from "#app/mcp/server";
 import { log } from "#app/utils/cli";
 import { resolveEnv } from "#app/utils/secrets";
 import { $ } from "#app/utils/shell";
+import { resolveToolSelection } from "#app/utils/toolSelection";
 
 /**
  * Terraform-write guardrails — hard, code-level limits that back the prompt
@@ -49,9 +50,10 @@ function isGuardedMode(ctx: ToolContext): boolean {
 export function resolveAllowedPaths(ctx: ToolContext): string[] {
   const configured = ctx.payload.allowedPaths;
   const base = configured && configured.length > 0 ? [...configured] : [...DEFAULT_ALLOWED_PATHS];
-  // §28 — when Terratest scaffolding is opted in, also permit the Go test +
-  // example-fixture paths the scaffold writes (they're outside the .tf default).
-  if (ctx.payload.terratest) base.push(...TERRATEST_ALLOWED_PATHS);
+  // §28 — when Terratest scaffolding is opted in (the `terratest` input OR the
+  // unified tools_enabled list, §1.5), also permit the Go test + example-fixture
+  // paths the scaffold writes (they're outside the .tf default).
+  if (resolveToolSelection(ctx.payload).enabled("terratest")) base.push(...TERRATEST_ALLOWED_PATHS);
   return base;
 }
 
@@ -374,8 +376,11 @@ export function assertNoSecretsInDiff(ctx: ToolContext): void {
   const diff = $("git", ["diff", base, "HEAD"], { log: false });
   const hits = scanDiffForSecrets(diff);
 
-  // optional deeper engine — merged on top of the built-in baseline.
-  if (ctx.payload.gitleaks) {
+  // optional deeper engine — merged on top of the built-in baseline. Opted in
+  // via the `gitleaks` input OR by naming "gitleaks" in the unified tools_enabled
+  // list (§1.5); an explicit `-gitleaks` there turns it back off.
+  const gitleaksEnabled = resolveToolSelection(ctx.payload).enabled("gitleaks");
+  if (gitleaksEnabled) {
     const gitleaksHits = scanWithGitleaks(ctx, base);
     if (gitleaksHits) hits.push(...gitleaksHits);
   }
@@ -388,7 +393,7 @@ export function assertNoSecretsInDiff(ctx: ToolContext): void {
     );
   }
   log.info(
-    `» secret-scan guardrail ok (no inlined secrets in the diff${ctx.payload.gitleaks ? ", built-in + gitleaks" : ""})`,
+    `» secret-scan guardrail ok (no inlined secrets in the diff${gitleaksEnabled ? ", built-in + gitleaks" : ""})`,
   );
 }
 

package/src/mcp/localContext.ts

@@ -22,6 +22,13 @@ export interface LocalToolContext {
     | "autonomyThreshold"
     | "costIncreaseBlockUsd"
     | "moduleCatalogue"
+    // §1.5 — the unified tool selection + module-fetch credential are honoured on
+    // the local stdio MCP server too (read-only scans + private-module init).
+    | "toolsEnabled"
+    | "gitleaks"
+    | "terratest"
+    | "terraformMcp"
+    | "moduleFetchToken"
   >;
   toolState: ToolState;
   tmpdir: string;

package/src/mcp/localServer.test.ts

@@ -21,6 +21,8 @@ describe("buildLocalTools", () => {
       "list_modules",
       "module_extraction_candidates",
       "read_findings",
+      "terraform_assess",
+      "terraform_emit_evidence",
       "terraform_emit_sarif",
       "terraform_module_graph",
       "terraform_module_interface",