infraweaver 0.1.0

package/src/modes/remediate.ts

@@ -0,0 +1,78 @@
+import { COMMENT_COMMAND, PRODUCT_NAME, SARIF_FILE } from "#app/brand";
+import { REMEDIATION_ADDENDUM_HEADING } from "#app/reviewQuality";
+import { REMEDIATION_PR_FORMAT } from "./prFormats.ts";
+import type { Mode, ToolRef } from "./types.ts";
+
+export function remediateMode(t: ToolRef): Mode {
+  return {
+    name: "Remediate",
+    description:
+      "Bring a repository's Terraform up to best practice: scan with the deterministic check tools, then open one scoped, reviewable PR per concern that fixes it and proves each fix by re-scanning (✅).",
+    prompt: `### Checklist
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **scan**: call \`${t("terraform_scan")}\` to get the best-practice \`concerns\` plus \`groups\` — one group per file, each with a stable \`id\`, its \`file\`, the group \`severity\` (highest in the file), the distinct \`rule_ids\`, and the \`concern_ids\` it covers. If it reports zero concerns, call \`${t("report_progress")}\` with "Terraform already follows best practice — nothing to remediate." and **stop**.
+
+   *Alternative concern source:* if the Assessor (terraform-reviewer) has already produced a \`findings.json\` **or a SARIF report** (Trivy/Checkov/tflint \`-o sarif\`) for this repo (one exists in the workspace, or \`$INFRAWEAVER_FINDINGS_PATH\` is set), call \`${t("read_findings")}\` instead — it auto-detects the format and returns the **same** \`{concerns, groups}\` shape, so the rest of this checklist is unchanged. Default to \`${t("terraform_scan")}\`; only use \`${t("read_findings")}\` when such a file is present (it returns \`found: false\` otherwise). Note that reviewer-exclusive findings (source \`reviewer\`) can't be re-verified by ${PRODUCT_NAME}'s scanners — see the prove-it step.
+
+   *External / CSPM feed:* if the customer's cloud-security tool (Wiz / Orca / Prisma, or any CSPM) has produced an external-findings feed (a JSON file in the workspace, or \`$INFRAWEAVER_EXTERNAL_FINDINGS_PATH\` is set), call \`${t("ingest_external_findings")}\` — it maps each cloud alert back to the offending Terraform resource (by address, then type+name, then by correlating a cloud id / ARN against the resource block) and returns the **same** \`{concerns, groups}\` shape, so this checklist proceeds unchanged. ${PRODUCT_NAME} never touches the cloud here — the CSPM already holds the creds and emitted the JSON; we only read it. Mapped alerts are \`reviewer\`-source (so, like other reviewer findings, not re-verifiable by our scanners — see the prove-it step); any alert with no matching resource in code comes back under \`unmapped\` (report it, don't invent a fix). Returns \`found: false\` when no feed is present.
+
+   *Multi-root repos:* \`${t("terraform_validate")}\` and \`${t("terraform_plan")}\` are now **multi-root aware** — they automatically validate/plan **every** Terraform root in the repo (e.g. hepcare's \`terraform/\` + \`terraform/core/\`) and aggregate the result (see \`roots_validated\` / \`roots_planned\`), so you do **not** need to loop per-root yourself. Call \`${t("terraform_roots")}\` only when you want to see the root layout (or fix a concern that lives in one specific root).
+
+3. **pick scope**: act on **one group per PR** (a group is all of one file's concerns — different scanners flag the same defect under different rules, so fixing per-file avoids a flood of near-duplicate PRs). Take the **highest-severity group first**. **Targeted findings override this:** if YOUR TASK carries a \`TARGETED FINDINGS\` directive (a Cloud dashboard "Remediate" dispatch naming specific concern ids), act ONLY on the group(s) containing those ids — never the highest-severity group instead, and never widen to other groups. Unless the task explicitly asks for more, open **at most one PR this run**. Skip groups whose severity is only \`info\` unless asked. Use the \`terraform-best-practices\` skill for how to read each concern and apply the *minimal* fix.
+
+   **Autonomy**: each group carries an \`autonomy\` field — \`auto\` (fix and open a normal PR) or \`needs-human\` (a security finding at/above the \`autonomy_threshold\`, or — once plan runs — a high blast radius). You still fix and open a PR for a \`needs-human\` group, but you MUST add the \`needs-human\` label (\`${t("add_labels")}\`), open the PR with \`approved: false\` framing, and put a prominent **⚠️ Needs human review** callout at the top of the body listing the group's \`autonomy_reasons\`. Never batch a \`needs-human\` group with others.
+
+   **Dependency order & environment twins**: when a repo has local modules, \`${t("terraform_module_graph")}\` returns \`dependency_order\` — fix a shared/depended-on module BEFORE its dependents so sequenced PRs don't conflict. \`${t("terraform_roots")}\` returns \`environment_twins\` — parallel \`dev\`/\`staging\`/\`prod\` (or per-region) stacks that differ only by an environment segment; when the fixed file is one twin, note in the PR that the same fix should be offered for its twins (a separate PR per twin, honouring \`max_prs\`).
+
+   **Grouping & batching**: groups default to one-per-file. When a single rule dominates across many files (e.g. "add \`tags\` everywhere"), re-scan with \`group_by: "rule"\` so it becomes ONE coherent group/PR instead of many. The scan's \`batch_plan\` tells you which low-risk groups are \`batchable\` (combine them into the single \`batch_plan.batch_branch\` PR when \`max_prs\` would otherwise be exceeded) and which are \`isolated\` (each gets its own PR for independent review/revert). Still honour \`max_prs\` and never batch a \`needs-human\` group.
+
+   **Comment command**: when this run was triggered by a \`${COMMENT_COMMAND} fix …\` comment, the triggering body is in your prompt — honour the requested scope INSTEAD of "highest-severity group": \`fix #<concern-id>\` → act only on the group containing that concern id; \`fix all <severity>-severity\` → set the scan \`severity_threshold\` to that level and act on those groups (up to \`max_prs\`); \`fix <file>.tf\` → act on that file's group; \`fix all\` → act on the highest-severity groups up to \`max_prs\`. If the comment isn't a recognised fix command, fall back to the default scope. A **strategy suffix** — \`fix #<concern-id> with strategy B\` (or a bare \`strategy B\` reply on a proposal thread) — additionally tells you **which** fix to apply: see the propose-then-steer guidance in step 4.
+
+   **Bulk remediation (\`fix rule <rule-id>\` / \`fix all rule <rule-id>\`)**: a request to fix ONE scanner rule everywhere it fires (e.g. \`${COMMENT_COMMAND} fix rule CKV_AWS_23\` — "add a description to every security group", or \`fix rule terraform_required_version\`). Re-scan with \`group_by: "rule"\` so that rule becomes ONE group spanning every file, then act on the single group whose \`rule_ids\` include \`<rule-id>\` — apply the SAME minimal fix at every site in its \`files\` and open ONE coherent PR (not one per file). This is the sweep path; still honour \`max_prs\` and never batch a \`needs-human\` group. Cite each fixed site in the PR body.
+
+4. **for the chosen group**:
+   - **base branch**: this run's base branch is resolved deterministically — \`${t("create_pull_request")}\` targets the \`base_branch\` input if set, else the repository's default branch (\`main\`, or \`master\`). You do not choose it; just **omit** the \`base\` argument when opening the PR (below) and it is filled in.
+   - **idempotency**: the remediation branch is \`remediate/<group-id>\`. Before doing anything, check whether that branch or an open PR for it already exists (\`${t("git")}\` / \`${t("get_pull_request")}\`). If one exists, update it rather than opening a duplicate.
+   - **branch**: create \`remediate/<group-id>\` from the **current HEAD** (the checkout that was just scanned) via \`${t("git")}\` (\`git checkout -b remediate/<group-id>\`). Do NOT switch to a different base first — branching from the scanned checkout keeps the PR diff to exactly your fix.
+   - **honest refusal (decide BEFORE fixing)**: if the group's concerns appear in the scan's \`refusal_candidates\` (the fix needs a human decision — narrowing an IAM wildcard, a KMS key policy, a real ingress CIDR), do **not** guess a fix that could break the stack. Instead open a structured issue (\`${t("create_issue")}\`) describing the concern, why it isn't auto-fixed, and what a human should do, and skip the PR for that group. A proven fix or an honest refusal — never a guessed, unverifiable PR.
+   - **propose, then let me steer (when there's no single right fix)**: distinct from honest refusal (which refuses a fix a human must *decide*), this is for a finding with **2–3 genuinely distinct, defensible fixes** that differ in trade-offs, not correctness (e.g. encrypt with an AWS-managed key **vs** a customer-managed KMS key; a narrow security-group rule **vs** a prefix list **vs** a VPC endpoint). When such a fork exists **and the triggering comment did not already select a strategy**, do **not** silently pick for the reviewer: via \`${t("create_issue_comment")}\` post one short comment listing the options as **A / B / C** — each a single line (what it does + its trade-off) — and ask the reviewer to reply \`${COMMENT_COMMAND} fix #<concern-id> with strategy <A|B|C>\`. Then **skip the PR for this group** this run and note it in your final report (it resumes when the reviewer replies). When the comment **did** select one (\`fix #<id> with strategy B\`, or a bare \`strategy B\` reply on the proposal thread), apply **exactly** that strategy — don't second-guess it. Reserve this for real forks in the road; a fix with one obvious correct answer just gets made.
+   - **reuse a proven fix (optional, do this BEFORE editing)**: call \`${t("terraform_fix_memory")}\`. When proven-fix memory is enabled it returns any patterns whose \`finding_type\` matches this group's concerns — each a transformation that already passed a \`✗→✓\` proof on this repo or elsewhere in the fleet, with its \`remediation_hint\` + a \`before_example\`. Use a matching pattern as your STARTING POINT (it saves you rediscovering the approach), but ADAPT it to this repo's own resources — it is a prior, never a patch to paste. You MUST still run \`${t("terraform_verify_remediation")}\` to prove \`✗→✓\` here; a pattern is never blind-applied and never substitutes for the per-target proof. Returns an empty list (never an error) when memory is off or nothing matches — then fix from first principles as usual.
+   - **fix**: edit the group's file(s), using your native file tools. For a by-file group that's the single \`file\`; for a **by-rule group** it's every entry in \`files\` (fix the one rule everywhere it fires). Resolve **every** concern in the group — when the scan's \`co_located\` shows several scanners flagged the same \`file:line\`, they're one underlying defect: write ONE canonical fix and one explanation, not separate edits. **Only touch \`*.tf\` / \`*.tfvars\` files.** Make the smallest changes that clear the concerns — do NOT reformat or refactor unrelated code (see *SYSTEM* surgical-change rules). **Match the file's existing formatting in your edit, and never run \`terraform fmt\` on a file that already has pre-existing formatting drift** — \`terraform fmt\` rewrites the WHOLE file (every interpolation + alignment), burying your one-line fix under dozens of cosmetic lines and making the PR unreviewable. \`${t("terraform_validate")}\` reports that pre-existing drift as advisory \`preexisting_fmt_drift\` and does NOT gate on it, so leave it alone; repo-wide reformatting is a separate \`${COMMENT_COMMAND} fix rule terraform-fmt\` PR, never a rider on a security fix. **Module-source awareness:** call \`${t("terraform_module_graph")}\` first — if the concern's file is inside a \`local_module_dir\`, fix it ONCE at the module source (it propagates to all callers; note them in the PR); if the fix would require editing a registry/git/remote module, you can't fix it here — report it (open an issue naming the upstream module + version) instead. **Approved modules:** call \`${t("list_modules")}\` and prefer a catalogue module (registry or house, pinned) when the fix is genuinely a module swap — but for a one-line fix on an existing raw resource, fix it in place. **Provider-major awareness:** before introducing an argument or block, check \`terraform_validate\`'s \`providers\` list for the pinned \`major\` — argument names and valid blocks differ across majors. After the dir is init-ed (validate/plan ran), you can **verify an argument exists** for the installed provider with \`${t("terraform_provider_schema")}\` (pass the resource type + the arg names you added; it returns any \`unknown_args\` that would break \`plan\`). If your fix means RAISING a provider major (rare in Remediate — that is \`UpdateDependencies\`' job), call \`${t("terraform_provider_upgrade")}\` first: it names the codified breaking changes for that boundary and, critically, which of them MOVE STATE and therefore must never be applied autonomously. **Reusing a module?** call \`${t("terraform_module_interface")}\` on its dir to get its real \`variable\` names + which are required, so the \`module\` block you write is correct.
+   - **fix QUALITY — a real fix, not a scanner-silencer (enterprise bar)**: the goal is infrastructure that is *actually* safer, not Terraform that merely stops tripping the scanner. Three rules:
+     - **Secure defaults, never a hidden-insecure one.** When you parameterise a hardcoded value, the new \`variable\`'s \`default\` must be the SECURE choice, or have **no \`default\`** (forcing the operator to set it). NEVER preserve the insecure value as the default — e.g. replacing \`cidr_blocks = ["0.0.0.0/0"]\` with \`var.allowed_cidr_blocks\` *defaulting to \`["0.0.0.0/0"]\`* is not a fix: the deployed behaviour is identical and you've just moved the problem somewhere a scanner may not see it. If the secure value genuinely needs a human decision, this is an honest-refusal / propose-then-steer case, not a default-to-insecure.
+     - **Optional-input resources must be conditional.** If a fix adds a resource or block that only works when an OPTIONAL input is set (e.g. an HTTPS listener that needs \`var.ssl_certificate_arn\`, which defaults to \`null\`), gate it with \`count\`/\`for_each\` or a \`dynamic\` block so it is NOT emitted — and cannot break \`plan\`/\`apply\` — when the input is unset. Do not write an always-present resource that references a null/empty value, and never claim in the PR that something is "only active when set" unless the HCL actually makes it conditional. Remember \`${t("terraform_validate")}\` can pass on HCL that still fails at \`plan\`/\`apply\` — your claim of conditionality must be in the code, not just the prose.
+     - **Modernise, don't perpetuate.** Call \`${t("terraform_version_currency")}\` and, when you must add a \`required_providers\`/\`required_version\` block, pin a CURRENT supported major, not an ancient one chosen only to match legacy code. Flag (in the PR body, as a follow-up — not necessarily fixed in this scoped PR) deprecated patterns the scanners don't encode: the archived \`hashicorp/template\` provider + \`data "template_file"\` (modern: the built-in \`templatefile()\` function), \`aws_launch_configuration\` (→ \`aws_launch_template\`), and any provider/module pin that is several majors behind. A best-practice fix should not entrench an EOL provider. **State locking:** when a fix touches (or would add) an S3 backend, prefer native locking — \`use_lockfile = true\` — over the deprecated \`dynamodb_table\` argument, and never introduce DynamoDB locking into a backend that doesn't already have it. ⚠️ Changing an EXISTING backend block is not a code-only edit: it requires \`terraform init -migrate-state\` against real state, so report it for a human instead of pushing it in a remediation PR.
+   - **keep the module's tests/examples consistent (only when you fixed a reusable module)**: if the file(s) you changed live inside a \`local_module_dir\` (from \`${t("terraform_module_graph")}\`) AND your fix changed the module's public interface (added/removed/renamed a \`variable\`, tightened a type), call \`${t("terraform_module_tests")}\` with that module dir. It returns the module's existing \`examples/\` fixtures + \`terraform test\` (\`*.tftest.hcl\`) / Go Terratest files and the \`drift\` per asset — \`missing_required\` (a variable the asset must now set) and \`unknown_set\` (a variable the asset references that no longer exists). Update **exactly** the drifting assets so they match the new interface; **never weaken, delete, or comment out an assertion just to make a test pass** — a fix that breaks a module's contract is the test doing its job, so correct the fix or the fixture, not the assertion. \`examples/\` are \`*.tf\` (always within the push allow-list); native \`*.tftest.hcl\` / Go \`*_test.go\` files are only pushable when the \`terratest\` input is enabled — when it isn't and only those drift, note the needed test update in the PR body for a human rather than leaving the module's own tests broken. Skip this entirely for a one-off raw-resource fix that doesn't touch a module interface.
+   - **validate**: call \`${t("terraform_validate")}\`. If it does not pass, fix what it reports or abandon this group — **never open a PR whose validate did not pass**. \`passed\` excludes pre-existing \`terraform-fmt\` drift (surfaced separately as advisory \`preexisting_fmt_drift\`); only formatting drift YOUR edit introduced counts — so a failing \`passed\` is a real validate/lint error to fix, never a cue to reformat untouched code. Its \`providers\` field carries the pinned provider majors (use them as above). It also returns \`unknown_arguments\`: arguments you wrote that are NOT in the installed provider's schema and would break \`plan\` — treat any entry as a must-fix (correct the argument for the pinned major) even though \`passed\` doesn't gate on it. \`schema_checked: false\` means the schema wasn't available (rely on \`${t("terraform_plan")}\` then).
+   - **policy gate (optional)**: if the repo ships policy-as-code (a \`policy/\`, \`policies/\`, or \`.conftest\` dir of Rego), call \`${t("policy_check")}\` — it runs \`conftest\` against the plan JSON. It degrades green (\`ok: false\`) when conftest or a policy dir is absent. When it returns \`passed: false\`, treat it exactly like a failed validate: fix the violation (listed in \`failures\`) or label the PR \`needs-human\` and surface it — never push past a policy denial.
+   - **plan (safety gate — do this BEFORE pushing)**: call \`${t("terraform_plan")}\`. It auto-skips (returns \`ran: false\`) when no cloud credentials / the terraform CLI are present, or init/plan can't complete — then carry on. When it returns \`ran: true\`, add a one-line **Plan** note to the PR body (e.g. \`Plan: +0 ~1 -0\`) and act on three signals:
+     - **destroy/replace — blast-radius pre-flight (\`push_will_block\` / \`blocked_destructive\`)**: treat any destroy/replace as a stop sign — a best-practice remediation should rarely destroy or replace a resource. The plan does the \`allow_replace\` cross-check FOR you: \`blocked_destructive\` lists the stateful resources (RDS, S3, EBS, a SQL database, …) NOT covered by the operator's \`allow_replace\`, and **\`push_will_block: true\` means \`${t("push_branch")}\` WILL be hard-blocked** by the destroy guardrail. When \`push_will_block\` is true, **abandon this group now — before you commit or push** — and report it (don't waste a commit/push round-trip discovering the block at push). Only proceed past a stateful destroy/replace when \`allow_replace\` genuinely covers it (then \`push_will_block\` is false) AND the replacement is clearly intended. List the \`destructive\` resources in your report either way.
+     - **blast radius (\`blast_radius.tier\`)**: add it to the PR body (e.g. \`Blast radius: low (1 resource)\`). When the tier is \`high\` (more than 10 resources, or the change spans more than one module), add a prominent **⚠️ Large blast radius — review carefully** callout to the PR body so a reviewer knows this is not a one-line change.
+     - **idempotency (\`idempotent\`)**: when it is \`false\`, the second plan disagreed with the first — a perpetual-diff smell (a non-deterministic value such as \`timestamp()\`/\`uuid()\`/an unkeyed \`random_*\`). **Prefer to fix the non-determinism or abandon the group**; if you still open the PR, surface \`idempotency_warning\` prominently as a **⚠️ Non-deterministic plan** caveat. (Note: this catches in-config non-determinism only — ${PRODUCT_NAME} never applies, so a provider-normalisation perpetual diff can't be detected here.)
+     - **needs-human (\`needs_human\`)**: when \`true\`, the plan crossed a deterministic escalation line (high blast radius, a stateful destroy/replace, or a non-deterministic plan — see \`needs_human_reasons\`). Add the \`needs-human\` label (\`${t("add_labels")}\`) and a louder callout.
+     - **full plan (\`plan_text\`)**: when present, attach it to the PR body as a collapsed \`<details><summary>Plan</summary>\\n\\n\\\`\\\`\\\`\\n…\\n\\\`\\\`\\\`\\n</details>\` block so a reviewer can see the exact planned change without re-running it.
+   - **commit + push**: \`git add\` only the file you changed, commit with a message naming the file and the key rules (e.g. \`fix(tf): harden main.tf — S3 encryption + block public access\`), then \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*).
+   - **open PR — with a COMPLETE body (MANDATORY)**: \`${t("create_pull_request")}\` (omit \`base\` — it resolves to the run's base branch above). The PR body is the primary deliverable a human reviews. At an absolute minimum the body MUST explain, in plain English: (a) **what was wrong** — each concern by \`rule_id\` + its \`evidence\`; and (b) **what you changed** to fix each one, and why it's safe. Build it with the **Remediation PR format** at the end of this checklist (status banner → title + badges → \`## What changed\` with the *Was / Changed / Safe because* note per concern). Two parts of the format depend on the verification tool that runs in the NEXT step, so at open time they are provisional: open with a \`> [!NOTE]\` **verification pending** status banner (not a clean/caution verdict you haven't earned yet) and omit the \`## Validation\` section — the next step's \`${t("update_pull_request_body")}\` fills both from the tool result. Never write a verified/clean/regression status before the tool returned it. ⚠️ \`${t("report_progress")}\` writes the GitHub Actions **job summary**, which is NOT the PR body — a good job summary does **not** substitute for a complete PR body. If you only have time/budget for one, the PR body wins.
+   - **prove it (re-scan)**: call \`${t("terraform_verify_remediation")}\` with the group's \`concern_ids\`. It re-runs the scanners and returns the authoritative \`resolved\` / \`remaining\` sets and a \`verified\` flag — this is the proof, do NOT eyeball a scan or self-report. Then \`${t("update_pull_request_body")}\` to add a "Validation" section built **from that result**: one \`✅ <rule_id> resolved\` line per id in \`resolved\`, and list every id in \`remaining\` honestly as still-open. Never put a ✅ on a concern unless the tool returned it in \`resolved\`. Act on two more fields it returns:
+     - **regressions**: when \`has_regressions\` is true, the fix INTRODUCED new concerns (listed in \`regressions\`) that weren't there before — it traded one defect for another. Add a prominent **⚠️ Regression** callout listing them, add the \`needs-human\` label (\`${t("add_labels")}\`), and prefer reworking the fix to remove the regression before relying on the PR.
+     - **confidence**: render the returned \`confidence\` (high/medium/low) as a one-line badge in the PR body (e.g. \`Confidence: high\`) with its \`confidence_reasons\`. It is computed deterministically from the verification evidence (verified + no regressions + plan idempotency + blast radius + cost) — report it verbatim, do NOT inflate it.
+   - **per-finding explanation**: in the PR body, give each resolved concern a short three-line note — **Was** (what the scanner flagged, from its \`evidence\`), **Changed** (what your fix did), **Safe because** (why it's correct/non-breaking) — and hyperlink the \`rule_id\` to its documentation. The scan output carries a \`doc_url\` per concern (and \`doc_urls\` per group); use it, falling back to the concern's \`remediation_hint\` when no \`doc_url\` is present.
+   - **compliance crosswalk (optional)**: for a security-relevant fix, call \`${t("terraform_compliance_crosswalk")}\` with the group's \`concerns\` to get the UK/general frameworks + controls it touches (NCSC Cloud Principles, Cyber Essentials, NHS DSPT, Secure by Design, CIS, SOC 2). Add a short **## Compliance** note from \`by_framework\`, prefixed "Indicative alignment (crosswalk v{version}) — not an audit verdict." Skip when nothing maps.
+   - **prevent recurrence**: the scan's \`prevention\` map gives a CI guardrail per \`rule_id\` (a Checkov hard-fail entry, a tflint rule, a \`trivy config\` gate, an \`fmt -check\` step). Add a short **🛡️ Prevent recurrence** note to the PR body with the suggested \`mechanism\` + \`snippet\` so the team can stop this class of concern coming back — clearly marked as an optional follow-up, not part of this PR's diff.
+   - **cost impact (optional)**: call \`${t("infracost_diff")}\` to estimate the monthly cost change the fix introduces. It auto-skips (returns \`ran: false\`) when \`INFRACOST_API_KEY\` or the infracost CLI is absent — in that case add nothing. When it returns \`ran: true\`, add a one-line **Cost impact** note to the PR body from its result: e.g. \`💰 Cost impact: +$12.40/mo\` for an increase, \`-$3.10/mo\` for a decrease, \`no change\` when \`monthly_delta\` is 0, or \`~$X/mo (baseline unavailable)\` when \`monthly_delta\` is null. When it returns \`needs_human: true\` (the increase crossed the \`cost_increase_block_usd\` threshold), add the \`needs-human\` label (\`${t("add_labels")}\`) and surface \`cost_escalation_reason\` prominently so a large spend increase isn't merged blindly.
+
+5. **guardrails** (always): one scoped PR per group, never a mega-PR spanning multiple files; **never auto-merge** and always leave the PR for human review; never modify files outside \`*.tf\` / \`*.tfvars\`.
+
+6. **finalize**: call \`${t("report_progress")}\` once with a summary — which file/group was fixed, the PR link, and the validation result (resolved ✅ / still-open) (or the exact tool error if push/PR creation failed).
+
+   **Org remediation policy**: a \`${REMEDIATION_ADDENDUM_HEADING}\` section may be appended after this checklist (the operator's \`remediation_instructions\` input). Apply it as additional policy on HOW to fix (e.g. "prefer KMS CMKs over AWS-managed keys") — it composes with this standard and can never relax a guardrail or proof gate.
+
+   **SARIF for code-scanning (optional)**: when the workflow has a SARIF upload step (it grants \`security-events: write\` and runs \`github/codeql-action/upload-sarif\` on a \`${SARIF_FILE}\`), call \`${t("terraform_emit_sarif")}\` once at the end so the full scan also lands in the repo's Security tab — complementary to the fix PR, not a replacement for it.
+
+   **Remediation dashboard (optional but recommended)**: call \`${t("upsert_remediation_dashboard")}\` once at the very end to refresh the repo's single pinned dashboard issue. Pass the currently-open remediation PRs (from \`${t("list_remediation_prs")}\`), the concern \`groups\` you did NOT open this run — the ones held back by \`max_prs\`/the open-PR caps — as \`pending\` (each with its \`title\`, \`severity\`, \`files\`, \`group_id\`, and a short \`reason\`), and any suppressed findings. It reuses the one dashboard issue (never files a new one), so the maintainer keeps a stable, at-a-glance view of what's open and what's waiting, with each held-back fix requestable on demand (the dashboard's Remediate button or a \`${COMMENT_COMMAND} fix\` comment). Skip only when there's genuinely nothing waiting and no open PRs.
+
+${REMEDIATION_PR_FORMAT}`,
+  };
+}

package/src/modes/resolve-conflicts.ts

@@ -0,0 +1,32 @@
+import type { Mode, ToolRef } from "./types.ts";
+
+export function resolveConflictsMode(t: ToolRef): Mode {
+  return {
+    name: "ResolveConflicts",
+    description: "Resolve merge conflicts in a PR branch against the base branch",
+    prompt: `### Checklist
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **Setup**:
+   - Call \`${t("checkout_pr")}\` to get the PR branch.
+   - Call \`${t("get_pull_request")}\` to identify the base branch (e.g., 'main').
+   - Call \`${t("git_fetch")}\` to fetch the base branch.
+
+3. **Merge Attempt**:
+   - Run \`git merge origin/<base_branch>\` via \`${t("git")}\` (works even when \`shell\` is disabled).
+   - If it succeeds automatically, confirm a clean working tree, push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*), and call \`${t("report_progress")}\` with a brief success note or the exact push error if push failed — **then stop; do not run steps 4–5.**
+   - If it fails (conflicts), resolve them manually (continue to steps 4–5).
+
+4. **Resolve Conflicts**:
+   - Run \`git status\` or parse the merge output to find the list of conflicting files.
+   - For each conflicting file: read it, find the conflict markers (\`<<<<<<<\`, \`=======\`, \`>>>>>>>\`), understand the code context, and rewrite the file with the correct resolution. Remove all markers.
+   - Verify the file syntax is correct after resolution.
+
+5. **Finalize**:
+   - Run a final verification (build/test) to ensure the resolution works.
+   - via \`${t("git")}\`: \`git add\` the resolved files, then \`git commit -m "resolve merge conflicts"\` (works even when \`shell\` is disabled)
+   - confirm a clean working tree, then push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*)
+   - Call \`${t("report_progress")}\` with a summary of what was resolved (or the exact push error if push failed)`,
+  };
+}

package/src/modes/review.ts

@@ -0,0 +1,135 @@
+import { REVIEWER_AGENT_NAME } from "#app/agents/reviewer";
+import {
+  FINDING_VERIFICATION_PASS,
+  REVIEW_FINDING_PRECEDENTS,
+} from "#app/reviewQuality";
+import { PR_SUMMARY_FORMAT } from "./prFormats.ts";
+import type { Mode, ToolRef } from "./types.ts";
+
+export function reviewMode(t: ToolRef): Mode {
+  return {
+    name: "Review",
+    nonCommitting: true,
+    description:
+      "Review code, PRs, or implementations; provide feedback or suggestions; identify issues; or check code quality, style, and correctness",
+    prompt: `### Checklist
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **checkout**: call \`${t("checkout_pr")}\` — this returns PR metadata, a \`diffPath\`, and (when TF declarations changed) a supplemental \`impactPath\`. read the diff TOC end-to-end and treat its file line ranges as your coverage checklist. only AFTER the raw-diff read, use \`impactPath\` as an explicitly-incomplete list of reference leads (where the PR's changed var/resource/module/output blocks are used elsewhere) — it never replaces raw-diff reading or establishes coverage.
+
+3. **triage**: orient yourself on the PR — identify *what kind of thing this is* (domain it touches, seams it crosses, external contracts it depends on, user-facing surfaces it changes). pull as much context as you need to render a confident, well-grounded review: read related files, grep for callers of changed symbols, check tests that exercise the touched paths, fetch related GitHub state. **you are the synthesizer** — never delegate understanding to subagents.
+
+   if the PR is **genuinely trivial**, skip the fan-out entirely and submit a \`No new issues found.\` review per step 7.
+
+   "Genuinely trivial" (skip):
+   - single-word doc typo, whitespace/format-only, comment-only across any number of files
+   - lockfile or generated-code regeneration (size of diff is irrelevant — read the *shape*)
+   - mechanical rename whose only effect is import-path updates
+   - low-risk dep patch bump
+
+   "Looks trivial but isn't" (do **NOT** skip — small diff, big blast radius):
+   - any 1-line change to SQL / regex / auth / billing / permission / signature-verification code
+   - flipping a feature-flag default, default config value, or retry/timeout constant
+   - changing a money/tax/currency/fee constant by any amount
+   - changing an HTTP method, redirect URL, response code, or status enum
+   - tightening or loosening a comparison operator (\`<\` ↔ \`<=\`, \`==\` ↔ \`!=\`)
+   - renaming a public API surface (still trivial in shape, but needs an impact lens)
+   - adding a new direct dependency (supply-chain surface)
+   - any "typo fix" in user-facing copy that changes meaning ("approved" → "denied")
+   - mixed diffs where a semantic 1-liner is buried in whitespace/formatting changes
+
+4. **lens dispatch — one lens per unresolved, load-bearing hypothesis (0, 1, or 2+)**.
+
+   You review the PR yourself first — read the whole diff, pull context, trace the changes. A lens is not a second opinion for its own sake; it is an independent pass at a *specific, falsifiable question you could not confidently resolve on your own*. After your own pass, keep only the open questions that meet ALL THREE bars:
+   - **falsifiable** — you can state in one line what evidence confirms it and what refutes it. "is the auth correct?" fails this; "does the new middleware run *before* the tenant-scoping guard on \`/export\`?" passes.
+   - **load-bearing** — if it resolves the wrong way, the review's verdict or a specific finding changes. A question whose answer doesn't move the review is not worth a dispatch.
+   - **beyond your own reach** — you tried and the code alone doesn't settle it: it needs an external-contract check, a cross-file trace too wide to hold confidently, or an independent adversarial read of genuinely subtle logic. "I'd like a second look to be thorough" does NOT qualify — that is doing your own job on a weaker model.
+
+   Dispatch **one \`${REVIEWER_AGENT_NAME}\` lens per surviving hypothesis**: **0** for most PRs (you resolved everything yourself — still the common outcome), **1** when a single real question remains, **2+** when several do. The count follows the questions — do NOT manufacture a hypothesis to reach two, and do NOT drop a real one to avoid dispatching alone. When you dispatch 2+, they go out together in parallel (step 5); a lone lens is the same mechanism at n=1, and is legitimate precisely because it answers a question you genuinely could not resolve — not because a second model looked.
+
+   Where load-bearing hypotheses cluster: high-stakes subsystems (auth, billing, payments, schema migration, webhooks, secrets, RBAC, multi-tenant isolation, cron/scheduling) and substantive diffs (>5 files, >200 net lines) are where an unresolved question is most likely genuinely load-bearing — but a 1-line change to a security boundary can raise exactly one hypothesis worth a lens, and a 500-line mechanical rename can raise none. Size is a hint about where to look, never the gate.
+
+   Lens framings come in two flavors:
+   - **themed lenses** — a perspective applied across the whole diff (correctness, security, user-journey, performance, etc.).
+   - **subsystem lenses** — a domain-scoped frame for high-stakes subsystems the PR touches (e.g. "the auth lens", "the billing lens", "the schema-migration lens"). **for high-stakes domains, lead with the subsystem lens rather than the generic themed equivalent** — "billing-subsystem" outperforms "correctness on billing code" because the framing primes the subagent to remember domain-specific failure modes (double-charges, refund races, currency rounding, dispute flows) the generic lens misses.
+
+   starter menu (each entry is a *source* of hypotheses, not a checklist to run — pick one only when it names a falsifiable question you actually could not resolve yourself):
+   - **correctness & invariants** — bugs, races, error handling, edge cases, state-machine boundaries
+   - **impact** — stale references in code/tests/docs/configs/UI after rename/remove
+   - **research-validated assumptions** — third-party API contracts, SDK semantics, framework directives, version-gated behavior. **only pick when the PR's correctness depends on the contract behaving a specific way** — not when the API is merely used. The bar is "if the third-party contract differs from what the diff assumes, the PR is incorrect." When dispatched, the subagent must verify load-bearing claims via web search and quote source URLs.
+   - **security** — new endpoints, authZ, input validation, secrets handling, replay/CSRF/injection, cross-tenant isolation
+   - **user-journey** — UX-touching flows: walk through happy path and failure modes as a user
+   - **operational readiness** — observability, alerting, migrations (forward + rollback), feature flags, on-call burden
+   - **integration & cross-cutting** — API contracts between modules, backward-compat of public surfaces, multi-service ordering
+   - **test integrity** — meaningful coverage for the changed behavior; deterministic; no shared-state pollution
+   - **performance** — N+1 queries, hot-path allocation, latency budgets, index coverage
+   - **holistic** — does the PR make sense as a whole? symmetric flows (delete for every create, rollback for every migration)?
+   - **subsystem lenses** (invent as the PR demands) — auth, billing, payments, schema migration, webhooks, secrets, RBAC, multi-tenant isolation, cron/scheduling, etc.
+
+   The only subagent type is \`${REVIEWER_AGENT_NAME}\` — used for lens judgment work ("is this safe / correct / well-tested?"), runs on a mid-tier model.
+
+5. **fan out (only if step 4 raised ≥1 hypothesis)**: dispatch every \`${REVIEWER_AGENT_NAME}\` lens for this run **IN A SINGLE ASSISTANT TURN.** One hypothesis is a single Task block; **2+ hypotheses are MULTIPLE PARALLEL TASK TOOL_USE BLOCKS IN ONE MESSAGE.**
+
+   ⚠️  CRITICAL — WHEN YOU DISPATCH 2+ LENSES, PARALLELISM IS MANDATORY. ⚠️
+   The default tool-call behavior of Claude Code (and most agent runtimes) is **serial dispatch**: emit one Task call, await result, emit next, await, etc. With multiple lenses this collapses your fan-out into a sequential review where each lens adds N × (orchestrator-think-time + lens-execution-time) to wall time. **YOU MUST OVERRIDE THIS DEFAULT.** Emit ALL of your Task tool_use blocks in the SAME assistant message, BEFORE you read ANY result from ANY of them. If you find yourself emitting one Task call, then thinking about the result, then emitting another — STOP and re-issue them all together. (A lone lens is trivially "parallel" — it is one block in one turn.)
+
+   ✅ Right pattern: one assistant turn with N Task tool_use blocks → wait → N results arrive together → aggregate.
+   ❌ Wrong pattern: turn 1 = Task(lens A) → turn 2 (after A's result) = Task(lens B) → turn 3 (after B's result) = Task(lens C). This is the failure mode. Do not do this.
+
+   You can also include your own \`read\` / \`grep\` / \`webfetch\` calls in the SAME turn as the parallel \`${REVIEWER_AGENT_NAME}\` dispatches — concurrent context-pulling on the orchestrator side runs in parallel with the lens fan-out and costs zero extra wall time.
+
+   if a subagent errors out, times out, or returns nothing usable, retry once with the same lens; if it still fails, proceed with partial coverage and note the missing lens in the review body — do not skip the fan-out entirely on a single subagent failure. each subagent gets:
+   - **the absolute \`diffPath\` (and \`incrementalDiffPath\` if available) from step 2's \`${t("checkout_pr")}\` return, named verbatim in the dispatch prompt** (e.g. \`diffPath: /tmp/infraweaver-XXXX/pr-NNN-SHA.diff\`). the reviewer's baked-in system prompt selects its FIRST action on this token — paraphrasing ("review the diff", "look at this PR") sends it down the \`git diff origin/<base>\` fallback, which fails on shallow GHA checkouts. the subagent \`read\`s those files for scope; it must NOT re-derive the diff via \`git diff\` (bare \`git diff origin/<base>\` is symmetric and pulls in the inverse of any commits that landed on \`<base>\` since the branch forked — pure noise, and the git tool rejects it). reading and codebase exploration are still its job.
+   - **only one lens = one hypothesis** — state it as the falsifiable question, name its scope boundary (which files/paths/contract it covers), and say what evidence would confirm vs refute it; never a multi-section "review for X, Y, and Z" prompt, and never a vague "review for security" with no question the answer would change
+   - **a Task \`description\` set to the lens name** (e.g. \`"security"\`, \`"correctness"\`, \`"billing-subsystem"\`) — the harness reads this field to label the subagent's log lines so parallel runs can be told apart in CI output. without it, every subagent shows up as \`subagent#N\`.
+   - if the lens touches external contracts, instruct the subagent to verify load-bearing claims via web search rather than trust training data, and to quote source URLs in its reasoning. action runs are non-interactive — there's no human in the loop to catch "I'm pretty sure Stripe does X."
+   - ask the subagent to report findings with file paths and NEW line numbers from the diff so you can anchor inline comments without re-reading the entire diff.
+
+   delegation discipline:
+   - do NOT summarize the PR for them (biases toward a validation frame)
+   - do NOT hand them a curated reading list (let them discover scope)
+   - do NOT pre-shape their output with a finding schema
+   - do NOT mention the other lenses (independence is the point — overlapping findings are a strong signal)
+
+6. **aggregate & draft**: when the fan-out lands, merge findings; de-dup overlaps (two lenses catching the same issue = higher-confidence signal); trace each finding yourself before accepting it. drop praise, style preferences, speculative/unverified claims, findings about pre-existing code unrelated to the PR (heuristic: if the finding's root cause lives in lines this PR added or modified, it's in scope; otherwise drop unless the PR plausibly introduced or amplified the regression), and anything not actionable. also drop **bloat-shaped findings** — proposed fixes that would add defensive checks for cases that can't happen, abstractions used once, comments restating obvious code, tests asserting tautologies, or "just-in-case" guards. subagents are fallible and bias toward recommending changes; the bar for an actionable inline comment is sound + correct + elegant. recommending a change that improves only one of the three (or worse, degrades elegance to nominally improve correctness) makes the codebase worse, not better.
+
+   Apply the **Finding precedents** (defined after this checklist, before the body format) to every candidate — a precedent match means drop, unless you have specific evidence the precedent does not apply here.
+
+   **Hunt for non-anchored concerns before drafting.** After collecting your anchored findings, deliberately scan for concerns that have no specific line to point at — typically: deletion / cleanup plans for code the diff replaces or shadows; rollout sequencing (what happens to in-flight state during deploy / revert?); coverage gaps the diff implies but doesn't add; scope questions that only the human can answer (e.g. is the legacy path going away or is this a long-term dual track?); architectural risks the diff opens up that aren't a single-line bug. On substantial PRs (migrations, refactors, multi-file rewrites, version bumps that change runtime semantics), at least one such concern almost always exists; if you can't think of any, your bar is probably too high.
+
+   ${FINDING_VERIFICATION_PASS}
+
+   for surviving findings, draft inline comments with NEW line numbers from the diff — attach a \`<details>Technical details</details>\` block to any inline comment whose fix is non-trivial or has cross-file implications (see Inline technical details in the format below). every comment must be actionable, 2-3 sentences max in the visible part. use GitHub permalink format for code references. for impact-analysis findings (stale references after rename/remove), report them in the review body ordered by severity (runtime breakage > incorrect docs > stale comments) rather than as inline comments unless they're anchored to a specific line.
+
+7. **submit**: ALWAYS submit exactly one review via \`${t("create_pull_request_review")}\`. Do NOT call \`report_progress\` — the review is the final record and the progress comment will be cleaned up automatically.
+
+   note: the first create_pull_request_review submission may error with a one-time diff-coverage nudge listing unread TOC regions. retry the same call to proceed — optionally after reading the listed ranges. the pre-flight will not block again this session.
+
+   The review body is structured as: \`[optional alert blockquote]\` → \`[PR summary using the default format below]\`. Inline comments are passed via the \`comments\` parameter, not in the body.
+
+   The opening callout is what the author sees first — pick the one that matches what you want them to do. Four tiers, from loudest to friendliest:
+
+   - \`[!CAUTION]\` — large red banner. Reads as "this will break something."
+   - \`[!IMPORTANT]\` — large purple banner. Reads as "you need to look at this before merging."
+   - \`> ℹ️ ...\` — informational blockquote. Reads as "minor suggestions, nothing blocking."
+   - \`> ✅ ...\` — green friendly blockquote. Reads as "no concerns, mergeable."
+
+   Two reinforcing levers: callout intensity (above) and \`approved\` (which gates the footer Fix-button affordance — Fix renders on every non-approving review, so \`approved: true\` suppresses it). Wrapping mergeable feedback in \`[!IMPORTANT]\` trains users to click Fix on reviews that don't need fixing. Pick the tier the author's actual next action justifies.
+
+   - **critical issues** (blocks merge — bugs, security, data loss, broken core flows):
+     \`approved: false\`. Body opens with \`> [!CAUTION]\\n> This PR introduces ...\`, followed by the PR summary. Include all inline comments via \`comments\`.
+   - **must-address non-critical findings** (real consequences if shipped — incorrect behavior in non-critical paths, missing validation on user input, regressions the author should fix before merge):
+     \`approved: false\`. Body opens with \`> [!IMPORTANT]\\n> ...\`, followed by the PR summary. Reserve this tier for findings with concrete fallout — do NOT use \`[!IMPORTANT]\` for nits, style preferences, or "consider also" suggestions. Include all inline comments via \`comments\`.
+   - **minor suggestions only** (single-line nits, doc/comment polish, defer-able observations, "rough edges"):
+     \`approved: false\`. Body opens with \`> ℹ️ No critical issues — minor suggestions inline.\\n\\n\` followed by the PR summary. Include all inline comments via \`comments\`. Vary the wording after the emoji to fit the review (e.g. "Minor suggestions only.", "Two rough edges worth a look."), but always keep the ℹ️ prefix and keep it short.
+   - **informational observations** (mergeable as-is, nothing actionable — e.g. prior feedback addressed cleanly, surfacing a minor stale doc reference, calling out something noteworthy without recommending a change):
+     \`approved: true\`. Body opens with \`> ✅ No new issues found.\\n\\n\` followed by the PR summary. Do NOT include inline \`comments\` — the ✅ signals "no action needed", which contradicts an actionable anchor; if a point is concrete enough to anchor to a line, downgrade the whole review to "minor suggestions only" (\`approved: false\`) instead.
+   - **no actionable issues**:
+     \`approved: true\`. Body opens with \`> ✅ No new issues found.\\n\\n\` followed by the PR summary.
+
+${REVIEW_FINDING_PRECEDENTS}
+
+${PR_SUMMARY_FORMAT}`,
+  };
+}

package/src/modes/summarize-pr.ts

@@ -0,0 +1,42 @@
+import type { Mode, ToolRef } from "./types.ts";
+
+export function summarizePrMode(t: ToolRef): Mode {
+  return {
+    name: "SummarizePr",
+    nonCommitting: true,
+    description:
+      "Summarize a pull request's changes in a single structured comment — what it does, the key changes, and any areas worth a closer look. Does NOT review, approve, or change code (use Review for a verdict).",
+    prompt: `### Checklist
+
+This mode posts ONE plain-English summary of what a PR does — an orientation aid, not a verdict. Do NOT approve, request changes, leave inline review comments, or modify any code. If a real review is wanted, that's the Review mode.
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **checkout**: call \`${t("checkout_pr")}\` — this returns PR metadata and a \`diffPath\`. Read the diff TOC so you understand the scope.
+
+3. **Terraform anchor (when relevant)**: call \`${t("terraform_change_summary")}\` — it returns the DETERMINISTIC Terraform block changes (resource/module/data/variable/output addresses ADDED and REMOVED, plus the Terraform files touched) vs the base. It degrades green (\`ok: false\`) when git can't resolve the base — run \`${t("git_fetch")}\` on the base ref first and retry — or when the PR has no Terraform changes (then it's a general summary). Use its counts as the factual backbone of the Terraform part of your summary instead of counting by eye.
+
+4. **read for intent**: read the \`diffPath\` (and related files as needed) to understand WHAT the PR does and WHY — not just the mechanics. Pull as much context as you need; you are the synthesizer.
+
+5. **post the summary**: call \`${t("create_issue_comment")}\` ONCE on the PR with a structured summary in this shape (omit a section when it has nothing):
+
+   \`\`\`
+   ## Summary
+   {1–2 sentences: what this PR does and why, in plain English.}
+
+   ### Key changes
+   - **{short title}** — {one sentence}; backtick-wrap files/identifiers you name.
+   - ...
+
+   ### Terraform changes
+   {only when terraform_change_summary returned data — e.g. "Adds \\\`module.vpc\\\` and \\\`aws_s3_bucket.logs\\\`; removes \\\`aws_launch_configuration.web\\\`; edits 3 files." Use its real addresses/counts.}
+
+   ### Worth a closer look (optional)
+   - {non-blocking observations a reviewer might want to focus on — risk areas, sequencing, things the diff implies but doesn't address. Phrase as orientation, not findings — this is not a review.}
+   \`\`\`
+
+   Keep it scannable: lead with intent, alternate prose with structure, backtick-wrap identifiers, no raw diff dumps, no \`+N/-M\` stats. NEVER fabricate a change — every claim must be in the diff (the Terraform counts come from the tool).
+
+6. **finalize**: call \`${t("report_progress")}\` with a one-line note that the summary was posted (or the exact error if the comment failed). Do NOT call \`${t("create_pull_request_review")}\` — this mode summarizes, it does not review.`,
+  };
+}

package/src/modes/task.ts

@@ -0,0 +1,26 @@
+import { infraweaverMcpName } from "#app/external";
+import type { Mode, ToolRef } from "./types.ts";
+
+export function taskMode(t: ToolRef): Mode {
+  return {
+    name: "Task",
+    description:
+      "General-purpose tasks that don't fit other modes: answering questions, adding comments, labeling, running ad-hoc commands, or any direct request",
+    prompt: `### Checklist
+
+1. **task list**: create your task list for this run as your first action.
+
+2. Analyze the task. For simple operations (labeling, commenting, answering questions, running a single command), handle directly — but your answer only reaches the user through \`${t("report_progress")}\` (step 4); raw assistant text is discarded.
+
+3. For substantial work — code changes across multiple files, multi-step investigations:
+   - plan your approach before starting
+   - use native file and shell tools for local operations
+   - use ${infraweaverMcpName} MCP tools for GitHub/git operations
+   - if code changes are needed: review your own diff before committing — verify only intended changes are present, no debug artifacts remain, and the changes are clean enough that a senior engineer would approve without hesitation
+
+4. Finalize:
+   - if code changes were made, push to a pull request (new or existing) using \`${t("push_branch")}\` and \`${t("create_pull_request")}\` as needed. \`git status\` must be clean before you finish (see *SYSTEM* Git rules if push fails).
+   - call \`${t("report_progress")}\` once with results — include exact tool errors if push or PR creation failed
+   - if the task involved labeling, commenting, or other GitHub operations, perform those directly`,
+  };
+}

package/src/modes/terraform-code-review.ts

@@ -0,0 +1,68 @@
+import { REVIEWER_AGENT_NAME } from "#app/agents/reviewer";
+import {
+  FINDING_VERIFICATION_PASS,
+  REVIEW_FINDING_PRECEDENTS,
+  TERRAFORM_SECURITY_REFUTE_LENS,
+} from "#app/reviewQuality";
+import { PR_SUMMARY_FORMAT } from "./prFormats.ts";
+import type { Mode, ToolRef } from "./types.ts";
+
+export function terraformCodeReviewMode(t: ToolRef): Mode {
+  return {
+    name: "TerraformCodeReview",
+    nonCommitting: true,
+    description:
+      "Review the Terraform changes in a HUMAN pull request — security misconfig, state-destroying edits, version-pin drift, module hygiene, idiomatic HCL — and submit one PR review. A lighter, *.tf-only counterpart to Review: it skips the app-code, test-integrity, and user-journey lenses and never modifies files or opens a PR.",
+    prompt: `### Checklist
+
+This mode reviews the **Terraform** in a human PR and submits ONE review. It is read-only — never edits files, commits, pushes, or opens a PR. Scope is \`*.tf\` / \`*.tfvars\` / \`*.tf.json\` / \`*.tfvars.json\` ONLY; non-Terraform files in the diff are out of scope (do not review them — a one-line "N non-Terraform files not reviewed" note in the body is enough).
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **checkout**: call \`${t("checkout_pr")}\` — it returns PR metadata, a \`diffPath\`, and (when TF declarations changed) a supplemental \`impactPath\`. read the diff TOC end-to-end; treat the \`*.tf\`/\`*.tfvars\` file ranges as your coverage checklist and ignore the rest. only AFTER the raw-diff read, use \`impactPath\` as an explicitly-incomplete list of blast-radius leads (where the PR's changed var/resource/module/output blocks are referenced elsewhere) — it never establishes coverage.
+
+3. **triage**: orient on what the Terraform change does — which resources/modules/providers it touches, whether it changes a stateful resource, whether it crosses a security boundary (IAM, networking, encryption, public exposure). pull context as needed: read the surrounding \`.tf\`, the module being called, \`versions.tf\`/\`required_providers\`, and any \`.tfvars\` defaults. **you are the synthesizer** — never delegate understanding.
+
+   if the Terraform change is **genuinely trivial** (a comment/whitespace-only edit, a tag value, a description string), skip the fan-out and submit a \`✅ No new issues found.\` review per step 6.
+
+   "Looks trivial but isn't" (do **NOT** skip — small diff, big blast radius):
+   - any change to an IAM policy/role/statement, security-group/NACL rule, or \`*_public_access*\` flag
+   - any change to encryption settings (KMS key, \`encrypted\`, \`*_sse_*\`), or a secret/credential value
+   - flipping a \`force_destroy\`, \`deletion_protection\`, \`prevent_destroy\`, or \`skip_final_snapshot\`
+   - a resource \`type\` swap, a \`count\`/\`for_each\` change, or anything that renames/moves a stateful resource address (destroy-and-recreate risk)
+   - a provider/module version constraint change (supply-chain + behaviour surface)
+
+4. **lens dispatch — one lens per unresolved, load-bearing hypothesis (0, 1, or 2+)** (same discipline as Review). Review the Terraform yourself first. A lens is an independent pass at a *specific, falsifiable Terraform question you could not confidently resolve on your own* — not a second opinion for its own sake. The default is **0 lenses**: most Terraform PRs resolve fully yourself. After your own pass, keep only the open questions that are **falsifiable** (you can state what confirms/refutes), **load-bearing** (a wrong answer changes the review), and **beyond your own reach** (the HCL alone doesn't settle it — needs a provider-contract check, a cross-module trace too wide to hold, or an independent adversarial read).
+
+   Dispatch **one \`${REVIEWER_AGENT_NAME}\` lens per surviving hypothesis** — **0** for most PRs, **1** when a single real question remains, **2+** when several do. The count follows the questions: never manufacture a hypothesis to reach two, never drop a real one to avoid dispatching alone. When you dispatch 2+, they go out together in parallel (step 5). A substantive diff (multiple resources/modules AND >150 net lines of Terraform) or a high-stakes boundary (IAM, networking, encryption, stateful data stores, multi-account/workspace wiring) is where an unresolved question is most likely load-bearing — but a 1-line IAM or CIDR change can raise exactly one lens-worthy hypothesis while a large mechanical reformat raises none. Size is a hint, never the gate.
+
+   Terraform-scoped lens menu (each entry is a source of hypotheses, not a checklist — pick one only when it names a question you could not resolve yourself; invent as the diff demands):
+   - **security & exposure** — IAM least-privilege (no wildcard actions/resources), public exposure (S3/SG/RDS), encryption at rest/in transit, IMDSv2, plaintext secrets in \`.tf\`/\`.tfvars\`.
+   - **state safety & blast radius** — does the change force a destroy/replace of a stateful resource? is a \`moved {}\` block needed for a relocated address? \`create_before_destroy\` where a replace is unavoidable?
+   - **correctness** — would this pass \`terraform validate\`? deprecated syntax/arguments, wrong types, unresolved interpolations, \`count\`/\`for_each\` index churn.
+   - **version & supply-chain** — provider/module pins (exact vs floating), a bumped major's breaking changes, an unpinned remote module source.
+   - **module & interface hygiene** — variable validation/defaults (secure-by-default), unused/undocumented variables, sensitive outputs not marked \`sensitive\`.
+
+   The only subagent type is \`${REVIEWER_AGENT_NAME}\`. Do NOT use the app-code, test-integrity, performance, or user-journey lenses from Review — they don't apply to IaC.
+
+5. **fan out (only if step 4 raised ≥1 hypothesis)**: dispatch every \`${REVIEWER_AGENT_NAME}\` lens **IN A SINGLE ASSISTANT TURN** — one hypothesis is a single Task block; **2+ are MULTIPLE PARALLEL TASK TOOL_USE BLOCKS IN ONE MESSAGE** (when you dispatch 2+, serial dispatch defeats the only reason to fan out). Each subagent gets: the absolute \`diffPath\` from step 2 named verbatim; **only one lens = one hypothesis** (the falsifiable question with its scope boundary and what would confirm vs refute it, never a vague "review for security"); a Task \`description\` set to the lens name; and an instruction to verify any version/provider-contract claim via web search and quote source URLs (action runs are non-interactive). Do NOT summarise the diff for them, hand them a reading list, pre-shape their output, or mention the other lenses. On a subagent failure, retry once, then proceed with partial coverage and note the missing lens in the body.
+
+6. **aggregate, draft & submit**: merge findings; de-dup overlaps (two lenses catching the same issue = higher confidence); trace each finding yourself against the diff before accepting it. drop praise, style preferences, unverified claims, findings rooted in pre-existing \`.tf\` the PR didn't touch, and **bloat-shaped findings** (defensive guards for impossible cases, abstractions used once, comments restating code, "just-in-case" variables). Apply the **Finding precedents** below; a match means drop unless you have specific evidence it doesn't apply.
+
+   ${FINDING_VERIFICATION_PASS}
+
+   ${TERRAFORM_SECURITY_REFUTE_LENS}
+
+   When the finding under test is a **cloud-misconfig** (public exposure, missing encryption, over-broad IAM, open ingress), the verification dispatch MUST include the Terraform-security refute lens above in addition to the generic charge — these IaC false-positive patterns (a separate hardening resource, a disabled resource, a call-site override) are exactly what a generic code lens misses.
+
+   Hunt for non-anchored concerns too — an absent \`moved {}\` block, a missing \`prevent_destroy\` on a data store, a destroy/replace the human must sign off, a version bump whose changelog they should read. Then ALWAYS submit exactly one review via \`${t("create_pull_request_review")}\` (never \`report_progress\` for review output). Inline comments anchor to NEW line numbers via the \`comments\` parameter; non-anchorable concerns go in the body \`### \` sections.
+
+   Same opening-callout ladder + \`approved\` lever as Review — \`[!CAUTION]\` (a state-destroying or security-breaking change) → \`[!IMPORTANT]\` (a real misconfig to fix before merge) → \`> ℹ️ ...\` (minor HCL/style nits) → \`> ✅ No new issues found.\` (mergeable, \`approved: true\`, no inline comments). Pick the tier the author's actual next action justifies; do not wrap mergeable feedback in \`[!IMPORTANT]\`. note: the first \`create_pull_request_review\` submission may error with a one-time diff-coverage nudge — retry the same call to proceed.
+
+7. **guardrails**: never modify \`*.tf\`/\`*.tfvars\`, never commit/push, never open a PR or issue. Only Terraform files are in scope. The review is the only deliverable.
+
+${REVIEW_FINDING_PRECEDENTS}
+
+${PR_SUMMARY_FORMAT}`,
+  };
+}

package/src/modes/types.ts

@@ -0,0 +1,17 @@
+export interface Mode {
+  name: string;
+  description: string;
+  // step-by-step guidance returned when the agent calls select_mode.
+  // custom user-defined modes supply this; built-in modes define it here.
+  prompt?: string | undefined;
+  // true for modes that legitimately never modify the working tree — they
+  // complete by submitting a review, posting a comment, or reporting a
+  // verdict. drives NON_COMMITTING_MODES (the post-run dirty-tree gate);
+  // declared here, next to the mode it describes, so a new read-only mode
+  // can't forget to update a hand-maintained list elsewhere.
+  nonCommitting?: boolean | undefined;
+}
+
+/** binds a bare MCP tool name to its agent-specific reference (per-run, via
+ * formatMcpToolRef) — the single closure each mode factory needs from computeModes. */
+export type ToolRef = (toolName: string) => string;

package/src/modes/update-dependencies.ts

@@ -0,0 +1,44 @@
+import { REFACTOR_PR_FORMAT } from "./prFormats.ts";
+import type { Mode, ToolRef } from "./types.ts";
+
+export function updateDependenciesMode(t: ToolRef): Mode {
+  return {
+    name: "UpdateDependencies",
+    description:
+      "Upgrade outdated or unpinned Terraform provider and module versions to current, supported pins, then PROVE the bump is safe — config-preserving bumps via the equivalence check (same resource set + arguments), behaviour-affecting major bumps via a reviewed plan delta (or shipped `proposed — unproven`). One scoped PR per provider/module.",
+    prompt: `### Checklist
+
+This mode turns the version-currency ADVISORY into action: it bumps stale/unpinned provider + module versions and PROVES the bump is safe before a human sees it, reusing the Refactor proof machinery. A pin bump that needs no code change is behaviour-preserving (proven by \`${t("terraform_equivalence_check")}\`); a major bump that changes resource shape ALTERS behaviour and is proven by a reviewed plan delta (or shipped \`proposed — unproven\`) — never a false equivalence claim.
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **detect**: call \`${t("terraform_version_currency")}\` — it returns provider/module pins that are outdated or unpinned, each with the current constraint, the latest version, and how many majors behind it is.
+
+3. **pick scope — ONE provider or module per PR**: take the most impactful safe upgrade first (a security-relevant provider bump, or pinning an unpinned pin to an exact constraint). **Targeted directive override:** if YOUR TASK names a specific provider/module, act only on it. Unless the task asks for more, open **at most one PR this run**; list deferred upgrades in the final report (never skip silently).
+
+4. **classify the bump (this decides the proof)**:
+   - **config-preserving** — a version-constraint change only (a patch/minor bump, or pinning a floating version) with NO change to any resource or argument. This is behaviour-preserving: prove it with \`${t("terraform_equivalence_check")}\` exactly as Refactor does — it must return \`equivalent: true\` (same resource set, identical arguments, validate + fmt clean). The push hard-fails an unproven one.
+   - **behaviour-affecting** — a major bump that requires resource/argument changes (renamed args, new required blocks, changed defaults). Equivalence is FALSE and must never be claimed. Make the minimal code changes the new major requires — use \`${t("terraform_validate")}\`'s \`providers\` majors and \`${t("terraform_provider_schema")}\` to get the new argument shape — then prove via the reviewed-plan path in step 6.
+
+4b. **for a provider MAJOR bump, call \`${t("terraform_provider_upgrade")}\` BEFORE editing.** It returns the codified breaking changes for that exact major boundary, each with the file it is in. Three things in its output decide what you do next, and none of them can be inferred from the diff:
+   - \`needs_human: true\` — the transform MOVES STATE (a removed resource type, or a rename the vendor marks manual). A config-only edit there DESTROYS AND RECREATES the live resource. Never apply one autonomously: put it in its own PR, label it \`needs-human\` (\`${t("add_labels")}\`), and name the affected resources in the body.
+   - \`value_change\` — the change is NOT a pure rename; the value must be inverted or retyped. Mechanically renaming these is how a live network silently gets its routing flipped while everything stays green.
+   - \`schema_agreement: "unverified"\` — the installed provider schema did not corroborate that entry. Treat it as a hint to check, never as fact.
+   The packs are explicitly NOT exhaustive; step 5's \`unknown_arguments\` is the authoritative completeness check. If the output names an official vendor migration tool, prefer it and review its diff rather than hand-migrating what it already handles.
+
+5. **validate**: \`${t("terraform_validate")}\` — never push a bump whose validate didn't pass. Use its \`unknown_arguments\` to catch arguments the new major dropped or renamed — including any the transform pack missed.
+
+6. **prove safety**:
+   - config-preserving → \`${t("terraform_equivalence_check")}\` is the proof (\`equivalent: true\`).
+   - behaviour-affecting → call \`${t("terraform_plan")}\` when cloud credentials are present and attach the **reviewed plan delta** as the proof; treat \`has_destroy_or_replace\`/\`stateful_destructive\` exactly as Remediate (a stateful destroy/replace is hard-blocked at push unless \`allow_replace\` covers that address — abandon otherwise). With NO creds, do not guess: ship the PR labelled \`proposed — unproven\` (\`${t("add_labels")}\`) with the proposed-unproven banner, stating the major bump ALTERS behaviour and the plan must be reviewed.
+   - record either proof with \`${t("terraform_emit_evidence")}\`.
+
+7. **keep module tests consistent** (only if the bump changed a local module's interface): \`${t("terraform_module_tests")}\` — update the drifting \`examples/\`/tests, never weaken an assertion.
+
+8. **open the PR (MANDATORY body)**: branch \`infraweaver/update-deps-<slug>\` from the scanned HEAD, \`git add\` only the changed files, commit naming the provider/module + old → new version, \`${t("push_branch")}\`, then \`${t("create_pull_request")}\` (omit \`base\`). Build the body with the **Refactor PR format** below — the equivalence proof for a config-preserving bump, or the reviewed-plan / proposed-unproven section for a major bump — stating old → new and linking the provider/module changelog. Never auto-merge.
+
+9. **finalize**: \`${t("report_progress")}\` once — which pin was bumped (old → new), the proof verdict, the PR link, and the deferred upgrades (or the exact tool error).
+
+${REFACTOR_PR_FORMAT}`,
+  };
+}