infraweaver 0.1.0

package/src/modes/prFormats.ts

@@ -0,0 +1,325 @@
+import { PRODUCT_NAME } from "#app/brand";
+
+// Default user-facing summary format embedded in BOTH Review and
+// IncrementalReview review bodies. The two modes share the preamble +
+// cross-cutting + nitpicks shape; the only difference is scope (full PR for
+// Review vs delta against the prior infraweaver review for IncrementalReview).
+// Distinct from the agent-internal snapshot (action/utils/prSummary.ts) which
+// has its own stable scaffold and is never shaped by user instructions — see
+// selectMode.ts for the firewall.
+export const PR_SUMMARY_FORMAT = `### Default format
+
+The body has at most four parts in this exact order:
+
+1. **Reviewed changes preamble** — one bolded inline lead-in describing what was reviewed in this run, a bullet list of the substantive changes, and an HTML comment carrying review metadata for downstream agents.
+2. **Cross-cutting issue sections** (zero or more) — one \`### \` heading per concern, with a human-readable problem write-up and a collapsed \`<details>Technical details</details>\` block underneath.
+3. **\`### ℹ️ Nitpicks\`** (only if there are nits worth surfacing in the body) — a flat bullet list, no technical-details block.
+4. **\`Suppressed findings\` collapsed block** at the very bottom (only when the adversarial verification pass suppressed at least one 🚨/⚠️ candidate) — the one-line-per-finding audit trail for the false-positive filter.
+
+Inline-vs-body split: concerns that anchor to a specific line go inline (use the \`comments\` parameter). Body \`### \` sections are reserved for concerns that **have no line to anchor to** — typically because the concern is about *absence* (something the diff should have done but didn't), *sequencing* (rollout / deletion / migration order), *design decisions only the human can make*, or *scope questions the diff implicitly raises but doesn't address*. A concern that anchors to a line but has broad implications still goes inline (use the technical-details block there to capture the implications — see Inline technical details below). If you found no non-anchorable concerns, the body has zero \`### \` issue sections — just the preamble + metadata.
+
+## 1. Reviewed changes preamble
+
+Open with a single bolded inline lead-in followed immediately by the bullet list (no \`### Key changes\` heading, no \`<b>TL;DR</b>\`):
+
+\`\`\`
+**Reviewed changes** — one sentence on what was reviewed in this run. For Review (initial), this is what the PR does and why. For IncrementalReview, this is what changed since the prior infraweaver review. Focus on intent, not mechanics.
+
+- **Short human-readable title** — 1 sentence per substantive change. Write a short prose phrase; when you name a file, type, or function, put that name in backticks (e.g. **Add \\\`TodoTracker\\\` for live checklists**). A reviewer should understand the full reviewed scope from this list alone — this IS the dispassionate "what was reviewed and what changed" overview, so cover the substantive changes, not just the loudest ones.
+
+<!--
+${PRODUCT_NAME} review metadata — for any agent (or human-with-agent) reading this
+review. Incorporate the fields below into your understanding of the context
+this review was made in. The findings below were written against
+{head_sha_short}; if new commits have landed on {head_ref} since this review
+was submitted, treat any specific bug, file, or line callout as POTENTIALLY
+STALE — re-diff against {head_sha_short} (or trigger a fresh review) and
+factor commits past {head_sha_short} into your understanding of the current
+state before acting on findings.
+
+- Mode: Review (initial)   or   IncrementalReview (delta against prior infraweaver review)
+- Files reviewed: {file_count}
+- Commits reviewed: {commit_count}
+- Base: {base_ref} ({base_sha_short})
+- Head: {head_ref} ({head_sha_short})
+- Reviewed commits:
+  - {sha_short} — {commit_subject}
+  - ...
+- Prior infraweaver review: none   or   {prior_sha_short} ({prior_review_html_url})
+- Submitted at: {iso_timestamp}
+-->
+\`\`\`
+
+Pull every metadata field from the \`checkout_pr\` tool's response — file count, commit count, base/head ref + SHA, the commit list. For \`IncrementalReview\` runs, populate \`Prior infraweaver review\` with the prior review's commit_id (short SHA) and \`html_url\` from \`list_pull_request_reviews\`.
+
+## 2. Cross-cutting issue sections (zero or more)
+
+For each cross-cutting concern, one \`### \` section. Use this exact shape:
+
+\`\`\`
+### {emoji} {short, descriptive title — what's wrong, not what to do}
+
+{Human-readable problem write-up. Describes the PROBLEM only — what's broken, what the symptom is, what the blast radius is. NO asks, NO suggested fixes, NO "the right thing to do is...". Asks and fixes live in the technical-details block below; the visible part is for the human to *understand* the problem, not to implement it.}
+
+<details><summary>Technical details</summary>
+
+\\\`\\\`\\\`\\\`markdown
+# {title repeated}
+
+## Affected sites
+- {file path:line} — {what's wrong there}
+- ...
+
+## Required outcome
+- {what the fix needs to achieve, not how to achieve it}
+- ...
+
+## Suggested approach (optional)
+{When the fix shape is non-obvious, sketch one or more reasonable directions. Skip when the outcome alone makes the fix obvious.}
+
+## Open questions for the human (optional)
+- {Any decision an implementing agent shouldn't make unilaterally — pricing thresholds, breaking-change policy, naming, scope of follow-up.}
+\\\`\\\`\\\`\\\`
+
+</details>
+\`\`\`
+
+Concrete example of the visible part of a non-anchored section (technical-details block unchanged from the template above):
+
+\`\`\`
+### ℹ️ Legacy \`opencode.ts\` has no documented deletion plan
+
+The v2 harness lands alongside the v1 file and imports one helper from it. Worth a follow-up issue or a TODO so the next maintainer doesn't have to re-derive the cleanup plan.
+\`\`\`
+
+The example's value is its *shape*: a finding about absence (no deletion plan), not a line-anchored bug. Body sections live or die on whether the concern genuinely doesn't fit on a line.
+
+**Heading severity emoji** — every \`### \` heading carries one:
+
+- 🚨 critical — blocks merge (data loss, security, broken core flow)
+- ⚠️ important — must address before merging (regression, missing validation, incorrect behavior)
+- ℹ️ informational — surfaced for awareness; mergeable as-is
+
+**Visible problem write-up rules:**
+
+- **No asks, no suggested fixes** in the visible part. The visible portion describes the problem; the technical-details block describes the fix shape and any open questions. The exception: a fix so self-evident that NOT stating it would be weird (e.g. "the typo is missing an 'r'") — in that case, fold it into the problem statement and skip the suggested-approach block in technical details too.
+- **Never two successive plain paragraphs.** Every transition between block-level elements must alternate prose with structure: paragraph → bullet list → paragraph; paragraph → code fence → bullet list; paragraph → table → paragraph. Two consecutive paragraphs in a row create a wall of text that's impossible to digest. If you catch yourself writing one, find a way to split it: pull a list out of it, drop a 2-3 line code fence between them, or merge them into a single tighter paragraph.
+- **Per-paragraph budget:** ~3 sentences max. Past that, you're explaining where you should be structuring.
+- **Identifier discipline still applies** in the visible part. Lead with behavior in plain English; name an identifier only when it's the subject of the concern or a public surface a reader would recognize. The technical-details block is where dense identifier references belong.
+
+**Technical-details block rules:**
+
+- Wrapped in a 4-backtick markdown fence (\`\\\`\\\`\\\`\\\`markdown ... \\\`\\\`\\\`\\\`\`) so it's visually distinct, one-click copyable, and can contain its own 3-backtick code fences without escape gymnastics. The contents are agent-readable — a fix-agent will pull the body down and use this block as the brief.
+- File paths and \`file:line\` refs are encouraged (and necessary) — the next agent uses these to navigate. Identifier density is fine here.
+- Slightly more verbose than the absolute minimum is OK when it materially helps the next agent: a small code snippet showing the symptom, a short table of mismatched key/column pairs, a one-paragraph "why CI doesn't catch it" note. Skip massive regression-test scaffolding or full route rewrites — the implementing agent writes those.
+- Use the four standard sections (\`Affected sites\`, \`Required outcome\`, optional \`Suggested approach\`, optional \`Open questions for the human\`). Skip the optional sections when they wouldn't add anything.
+
+## Inline technical details
+
+Inline comments are short (~2-3 sentences) by default. When an inline finding has broader implications worth recording for a fix-agent — e.g. a localized bug whose proper fix requires touching several files, or where the right fix depends on a design decision the human needs to make — append a collapsed \`<details><summary>Technical details</summary>\` block to the inline comment's body. Same shape as the body-section technical-details block (4-backtick fenced markdown, \`## Affected sites\` / \`## Required outcome\` / optional \`## Suggested approach\` / optional \`## Open questions for the human\`).
+
+GitHub renders the same markdown parser in inline comments as in the review body, so the collapsed-details affordance works the same way. The visible part of the inline comment stays scannable; the depth is one click away for any agent that needs it.
+
+## 3. \`### ℹ️ Nitpicks\` (optional, last content section)
+
+Only when there are nits that for some reason can't be inlined. Filepaths in nit text are fine — these are simple enough that a human or agent reads once and acts. No technical-details block.
+
+\`\`\`
+### ℹ️ Nitpicks
+
+- {nit, with file path inline if useful, ≤ ~200 chars}
+- ...
+\`\`\`
+
+## 4. \`Suppressed findings\` (optional, very last)
+
+Only when the adversarial verification pass (see the checklist) suppressed at least one 🚨/⚠️ candidate. One collapsed block, always the last element in the body, with the count in the summary line:
+
+\`\`\`
+<details><summary>🗑️ Suppressed findings (2)</summary>
+
+- ⚠️ \`networking/main.tf:42\` — claimed the subnet exposes the DB publicly — refuted: \`publicly_accessible = false\` at \`db.tf:18\`.
+- 🚨 \`api/auth.ts:77\` — claimed JWT signature bypass — refuted: the unverified decode is dev-only, gated by the \`NODE_ENV\` check two lines above.
+
+</details>
+\`\`\`
+
+One bullet per suppressed finding: severity emoji, \`file:line\`, the claim in a few words, the refutation in a few words. One line each — the block exists for auditability (a human catching the false-positive filter being wrong), not re-litigation. Omit the block entirely when nothing was suppressed.
+
+## Inline comment shape
+
+Inline comments use the same severity framing as body \`### \` sections, scaled down for line-anchored use:
+
+- **Lead with a 1-2 sentence problem statement.** The reader is looking at the line in question, so don't restate what the line says — describe what's wrong with it. Optionally prefix the visible line with a severity emoji (🚨 / ⚠️ / ℹ️) when severity isn't obvious from context.
+- **Optional \`<details><summary>Technical details</summary>...</details>\` collapsible** for findings whose technical context (longer file:line references, related-code snippets, suggested approach, regression-risk notes) would overwhelm the human-readable lead-in. Same agent-readable purpose, same 4-backtick fence shape, and same 4-section structure as the body's technical-details block — see *Inline technical details* above. Encouraged whenever the depth helps a downstream fix-agent; don't force one when the inline lead-in already says everything.
+- **Visible portion ≤ 2-3 sentences.** If you find yourself writing more, that's the cue to split the depth into the \`Technical details\` collapsible.
+
+## Body-wide rules
+
+- **Inline-vs-body discipline (repeated for emphasis):** anything that anchors to a specific line goes inline (with a \`<details>Technical details</details>\` block when the implications are broad). The body is for non-anchorable concerns only — absence, sequencing, design decisions, scope questions, architectural risk.
+- **No \`### Issues found\` heading** above the issue sections — each \`### \` heading IS the issue.
+- **Severity emoji on every \`### \` heading** (🚨 / ⚠️ / ℹ️). No emoji on the preamble lead-in or anywhere else.
+- **GitHub block-level rendering**: GitHub's markdown parser requires a blank line between ALL block-level elements (HTML tags like \`<br/>\`, \`<sub>\`, \`<details>\`, \`<b>\` and markdown syntax like headings, lists, blockquotes, code fences, paragraphs). Without a blank line, GitHub treats following content as a continuation of the HTML block and renders markdown syntax as literal text. ALWAYS separate block-level elements with a blank line.
+- **Backtick-wrap** every variable, identifier, or file name when you mention one (in either visible or technical-details portions).
+- **Don't repeat diff content**, don't include raw \`+123 / -45\` stats, don't include a changelog section, don't use horizontal rules (\`---\`).
+- **Pull file/commit counts from \`checkout_pr\` metadata** — never count manually.
+- **Legacy headings REMOVED.** Do not use \`### Key changes\`, \`### Issues found\`, \`<b>TL;DR</b>\`, or \`<sub><b>Summary</b>\`. The new structure subsumes them.`;
+
+// Canonical body format for a Infraweaver REMEDIATION pull request.
+// Distinct from PR_SUMMARY_FORMAT (which shapes a *review* body): this is the
+// body of a PR Infraweaver OPENS. Every field maps to a deterministic tool result
+// (terraform_scan / _validate / _plan / _verify_remediation / infracost_diff),
+// so the body is evidence-built, never self-reported. Append this to the
+// Remediate + RefreshRemediation prompts so every Infraweaver fix PR looks
+// identical and a reviewer can scan it top-to-bottom in seconds.
+export const REMEDIATION_PR_FORMAT = `### Remediation PR format
+
+**Minimum (ALWAYS include, even under tight budget):** a one-paragraph plain-English summary of *what was wrong and what you changed*, then a \`## What changed\` list with one *Was / Changed / Safe because* note per concern, then the \`## Validation\` list. If you produce nothing else, produce these three — a PR a human can't understand from its body alone has failed its job. Everything below enriches this minimum; it does not replace it. (The \`## Validation\` list and the final status banner come from \`terraform_verify_remediation\`, which runs after the PR opens — so on the initial \`create_pull_request\` the banner is a provisional \`> [!NOTE]\` verification-pending line and \`## Validation\` is absent; the follow-up \`update_pull_request_body\` fills both. Everything else in this list is present from the first open.)
+
+Build the PR body in this EXACT order. Every line is backed by a tool result — never write a status you didn't get from a tool. Omit a whole section only when its tool didn't run (e.g. no plan without cloud creds); never fabricate it. Keep a blank line between every block-level element (GitHub needs it to render).
+
+#### 1. Status banner (first line)
+
+One GitHub alert blockquote that sets the reviewer's expectation, picked from the verification evidence:
+
+- \`> [!CAUTION]\` — a \`needs-human\` signal fired: a regression (\`has_regressions\`), a stateful destroy/replace, a high blast radius, a non-deterministic plan, or a cost escalation. One sentence naming the reason.
+- \`> [!WARNING]\` — verified but with a caveat (medium blast radius, a still-\`remaining\` concern, baseline-unavailable cost).
+- \`> [!NOTE]\` — clean: \`verified: true\`, no regressions, low blast radius. One sentence: what was hardened.
+
+#### 2. Title line + badges
+
+A single bolded sentence naming the file/group and what was fixed, then a one-line badge row built from the tool results (drop any badge whose tool didn't run):
+
+\`\`\`
+**Hardened \\\`main.tf\\\` — S3 encryption + public-access block.**
+
+\`Confidence: high\` · \`Blast radius: low (1 resource)\` · \`Plan: +0 ~1 -0\` · \`Idempotent: yes\` · \`Cost: +$0.00/mo\`
+\`\`\`
+
+Render \`Confidence\` verbatim from \`terraform_verify_remediation.confidence\` — never inflate it. Use \`·\` separators, backtick-wrap each badge.
+
+#### 3. \`## What changed\`
+
+One \`### \` subsection per resolved concern (or one per rule for a by-rule group), each with the three-line micro-template and the rule linked to its docs (\`doc_url\`, else \`remediation_hint\`):
+
+\`\`\`
+### 🔒 [\\\`trivy:AVD-AWS-0088\\\`](https://avd.aquasec.com/misconfig/avd-aws-0088) — S3 bucket not encrypted
+
+- **Was** — {the scanner's \`evidence\`, in plain English}.
+- **Changed** — {what the fix did, one sentence}.
+- **Safe because** — {why it's correct and non-breaking}.
+\`\`\`
+
+Lead each heading with a severity emoji (🚨 critical · ⚠️ high · 🔒 security · ℹ️ low/info). Backtick-wrap every identifier. No raw diff dumps — the Files tab shows the diff.
+
+#### 4. \`## Validation\`
+
+Built ONLY from \`terraform_verify_remediation\`'s result — this is the proof, not a self-report. One ✅ line per id in \`resolved\`, then any still-open id honestly:
+
+\`\`\`
+## Validation
+
+- ✅ \\\`trivy:AVD-AWS-0088\\\` resolved
+- ✅ \\\`checkov:CKV_AWS_19\\\` resolved
+- ⚠️ still open: \\\`tflint:...\\\` — {why it couldn't be cleared}
+\`\`\`
+
+**Resolved XOR still-open — never both.** Each concern appears on exactly one line: an \`id\` in the tool's \`resolved\` set gets a \`✅ … resolved\` line (the green check means cleared); an \`id\` in \`remaining\` gets a \`⚠️ still open: …\` line. NEVER put a ✅ on an unresolved concern (no \`✅ … re-flagged\`, no \`✅ … still open\`) — that is a false attestation and the single worst thing this body can do. A concern earns its ✅ only if the tool returned its id in \`resolved\`; if it's in \`remaining\`, it is still-open, full stop.
+
+If \`has_regressions\` is true, add a \`> [!CAUTION]\` **Regression** callout listing each id in the tool's \`regressions\` set BEFORE this list, and ensure the \`needs-human\` label is set. \`regressions\` are concerns the fix genuinely INTRODUCED (a new \`rule\`+\`file\` not present before) — they are computed line-independently, so a pre-existing concern that merely moved lines is NOT a regression; do not relabel a \`remaining\` concern as a regression.
+
+#### 5. \`<details><summary>Plan</summary>\` (when \`terraform_plan\` ran)
+
+Attach the full \`plan_text\` in a collapsed code block so a reviewer sees the exact change without re-running it:
+
+\`\`\`
+<details><summary>Terraform plan</summary>
+
+\\\`\\\`\\\`
+{plan_text}
+\\\`\\\`\\\`
+
+</details>
+\`\`\`
+
+When \`needs_human\` is true, surface \`needs_human_reasons\` as a visible bullet list above the \`<details>\` — don't bury an escalation in a collapsed block.
+
+#### 6. \`## 🛡️ Prevent recurrence\` (optional follow-up)
+
+From the scan's \`prevention\` map — the CI guardrail that stops this class of concern coming back. Clearly marked **not part of this PR's diff**: a short intro sentence then the \`mechanism\` + a fenced \`snippet\`. One entry per distinct rule.
+
+#### 7. \`## Compliance\` (optional, when a crosswalk was run)
+
+When \`terraform_compliance_crosswalk\` was called, add a short auditor-facing note: the frameworks/controls this fix touches (from \`by_framework\`), prefixed "Indicative alignment (crosswalk v{version}) — not an audit verdict." Skip entirely when the crosswalk wasn't run.
+
+#### Body-wide rules
+
+- **Evidence-built, never self-reported** — every badge, ✓, and count comes from a tool result. If a tool didn't run, omit its section; don't guess.
+- **Blank line between ALL block-level elements** (callouts, headings, lists, code fences, \`<details>\`) — GitHub renders markdown as literal text otherwise.
+- **Backtick-wrap** every file, rule id, resource address, and identifier.
+- **No raw \`+N/-M\` diff stats, no horizontal rules (\`---\`), no changelog section.** The footer is appended automatically — don't add your own.
+- **One scoped group per PR.** The body describes this group's fix only.`;
+
+// Canonical body for a Infraweaver REFACTOR pull request. Distinct from
+// REMEDIATION_PR_FORMAT: a refactor's deliverable is the EQUIVALENCE proof (or,
+// for a behaviour-altering b.4 adoption, an explicit `proposed — unproven`
+// marker), not a ✗→✓ re-scan. Every line maps to a tool result
+// (terraform_equivalence_check / terraform_plan / terraform_emit_evidence), so
+// the body is evidence-built, never self-reported. Appended to the Refactor mode.
+export const REFACTOR_PR_FORMAT = `### Refactor PR format
+
+Build the body in this EXACT order. Every status is backed by a tool result; omit a section whose tool didn't run, never fabricate it. Keep a blank line between block-level elements.
+
+#### 1. Status banner (first line)
+
+One GitHub alert blockquote, picked from the proof:
+
+- \`> [!NOTE]\` — **equivalence proven** (b.1/b.2/b.3): \`terraform_equivalence_check\` returned \`equivalent: true\`. One sentence: what was modularised.
+- \`> [!CAUTION]\` — **proposed — unproven** (b.4 default, no read creds): the change ADOPTS a third-party module and ALTERS behaviour; equivalence is false and NOT claimed, and no plan ran. Use the proposed-unproven banner verbatim (below). This label must be unmissable.
+- \`> [!WARNING]\` — a caveat (a required module variable left unset, an environment twin needing the same change, or a \`needs-fork\` control).
+
+#### 2. Title line
+
+A single bolded sentence naming the file + the module: \`**Modularised \\\`main.tf\\\` — extracted 4 logging resources into \\\`module.logging\\\`.**\`
+
+#### 3. \`## What changed\`
+
+The relocation in plain English (which raw resources became which module call). For a b.3 authored module, list its interface (\`variable\`s + \`output\`s). For b.4, name the adopted module + its **exact pinned version** (provenance).
+
+Optional \`Documentation\` bullet — present ONLY when \`terraform_module_docs\` ran this run: one line naming the README it wrote/refreshed (e.g. \`- **Documentation** — regenerated \\\`modules/logging/README.md\\\` from the module interface + equivalence verdict\`). Omit the bullet entirely when the tool didn't run.
+
+#### 4a. \`## Equivalence proof\` (b.1 / b.2 / b.3 — built ONLY from \`terraform_equivalence_check\`)
+
+This is the proof, not a self-report. One ✅ line per cleared check:
+
+\`\`\`
+- ✅ Resource set preserved (N resources, 0 added / 0 removed)
+- ✅ Arguments identical
+- ✅ Moved-block coverage N/N (0 uncovered)
+- ✅ terraform validate
+- ✅ terraform fmt (no diff)
+\`\`\`
+
+Add \`- ✅ Plan: refactor_safe (pure move, +0 ~0 -0)\` when \`terraform_plan\` ran. List the moves (\`<old> → <new>\`) in a collapsed \`<details>\`. If ANY check failed, the refactor is not equivalent — do not open this PR as an equivalence claim (the push guardrail blocks it anyway); fix it or fall to the b.4 path.
+
+#### 4b. \`## Proposed change — unproven\` (b.4 default — adopting a third-party module, no read creds)
+
+Lead with the proposed-unproven banner (§1), then:
+
+- **Behaviour change** — what the module adds/changes vs the inlined resources (a KMS key, an IAM role, different defaults). State plainly that this ALTERS behaviour.
+- **Module-sourced findings** — re-scanned with external-module resolution ON (so nothing is laundered); each remediated via a module INPUT, or labelled \`needs-fork\` where the module exposes no knob (never a silent pass).
+- **Provenance** — the module \`source\` + the **exact pinned version**.
+- It is asserted as **nothing more than a proposal** — "review the plan yourself."
+
+When read-only state IS supplied (opt-in), REPLACE this section with **\`## Reviewed plan delta\`**: the \`terraform_plan\` output (collapsed), reviewed — the change is then proven by the plan, not by equivalence. The supplied credential and the plan output are consumed at runtime and never stored.
+
+#### 5. Composition (when this PR also carries a remediation fix)
+
+Default is one combined PR. Keep the two proofs as **distinct, separately-readable sections** — the ✗→✓ \`## Validation\` for the fix and the \`## Equivalence proof\` for the refactor — never entangled in one narrative (an auditor reads them as different categories of change). When the reviewer wants each reviewed/reverted independently, split into two scoped PRs (one fix, one refactor).
+
+#### Body-wide rules
+
+- **Evidence-built, never self-reported.** Omit a section whose tool didn't run.
+- **Never claim equivalence for a b.4 change** — it alters behaviour; the proposed-unproven marker must never read as a proof.
+- **Blank line between block-level elements**; backtick-wrap identifiers; no raw \`+N/-M\` stats or \`---\` rules.
+- **Never auto-merge** — always leave the PR for human review.`;

package/src/modes/refactor.ts

@@ -0,0 +1,74 @@
+import { REFACTOR_ADDENDUM_HEADING } from "#app/reviewQuality";
+import { REFACTOR_PR_FORMAT } from "./prFormats.ts";
+import type { Mode, ToolRef } from "./types.ts";
+
+export function refactorMode(t: ToolRef): Mode {
+  return {
+    name: "Refactor",
+    description:
+      "Standardise Terraform structure WITHOUT changing behaviour, in one of two ways: (a) lift a cluster of raw resources behind a module boundary (an existing module, or one mechanically extracted) with a `moved {}` block per relocated address; or (b) apply a provably-equivalent in-place idiomatic normalisation (redundant interpolation wrapping, legacy HCL0.11 block syntax). Either way, open one scoped PR that PROVES equivalence (same resource set, same arguments, zero uncovered moves, validate + fmt clean). Distinct from Remediate (which fixes findings, proven by ✗→✓ re-scan); Refactor changes structure, behaviour preserved, proven by EQUIVALENCE.",
+    prompt: `### Checklist
+
+This mode standardises STRUCTURE while preserving BEHAVIOUR — the equivalence half of the operating model. It ships EITHER a module extraction OR a provably-equivalent in-place idiomatic normalisation, and only ever a refactor it can PROVE is a no-op on live infrastructure. The proof is keys-free (no cloud credentials). A refactor that can't be proven equivalent is abandoned or escalated, never pushed — \`${t("push_branch")}\` hard-blocks an unproven one.
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **detect (two kinds of behaviour-preserving refactor — call BOTH)**:
+   - \`${t("module_extraction_candidates")}\` → resource \`clusters\` (raw root resources that should likely be a module call), each with matched \`candidates\` (house modules by resource-type signature; catalogue modules by keyword) and per-candidate \`expected_moves\` (every cluster resource → its new module address).
+   - \`${t("terraform_normalization_candidates")}\` → in-place idiomatic cleanups that change SYNTAX, not behaviour (redundant whole-string \`"\${expr}"\` interpolation; legacy HCL0.11 \`config {\`/\`vars {\` map-argument block syntax). These relocate NOTHING — zero \`moved {}\` blocks — and are proven by the same equivalence check.
+
+   Pick the highest-value refactor across BOTH detectors. Only when BOTH come back empty is there genuinely nothing to do: call \`${t("report_progress")}\` with an ACCURATE message — e.g. "No behaviour-preserving refactor found: no extraction clusters and no idiomatic-normalisation candidates." — and **stop**. Two anti-patterns to avoid in that message: (i) never call a repo "already idiomatic" while normalisation candidates remain; (ii) when what's left is behaviour-CHANGING modernisation — a deprecated-resource swap (\`aws_launch_configuration\`→\`aws_launch_template\`, \`aws_elb\`→\`aws_lb\`, \`template_file\`→\`templatefile()\`) — do NOT report "nothing to refactor": that is real work, but it ALTERS the resource set, so it belongs to Remediate. Say so explicitly rather than implying the code is clean.
+
+3. **pick scope — ONE refactor per PR**: take the largest / highest-cohesion extraction cluster, or the file(s) with the most normalisation sites, first. **Targeted directive override:** if YOUR TASK names specific files/resources, act only on those. Unless the task explicitly asks for more, open **at most one PR this run**.
+
+   **If you chose an in-place NORMALISATION** (not a module extraction), nothing relocates: SKIP steps 4–6 (no module source, no wiring, no \`moved {}\` blocks). Apply the \`${t("terraform_normalization_candidates")}\` edits directly (rewrite \`"\${expr}"\` → \`expr\`, \`config {\` → \`config = {\`, etc.) — only the literal cleanups, never a resource-type swap — then jump to step 7. The equivalence check (step 8) proves the no-op: same resource set, identical argument names, zero moves.
+
+4. **resolve the module source (risk order — PRESERVING variants only)**: choose where the module code comes from. This mode ships only behaviour-preserving refactors; pick the lowest-risk viable source:
+   - **b.2 — module exists, same repo** (candidate \`kind: local\`): call it by its \`./modules/x\` path. No credential. *Prefer this.*
+   - **b.1 — module exists, separate org repo** (candidate \`kind: git\`): use a \`git::…?ref=<pinned-sha>\` source (pin an exact commit, never a branch). Access is via the GitHub App token (or the operator's read-only deploy key) and is **READ-ONLY** — ⚠️ **NEVER open a write PR against the module repo.** If a concern lives inside the shared module, fix it at the CALL SITE via inputs, or note "fix needed in module repo \`<repo>\`" — do not edit vendored module code.
+   - **b.3 — no module exists, author it** (no candidate): MECHANICAL extraction. Take the cluster's existing resource blocks, move them verbatim into \`./modules/<name>/\`, parameterise each hardcoded value into a \`variable\` (with a SECURE \`default\`, or **no default** so the caller must set it — NEVER preserve an insecure value as a default), expose the needed \`output\`s, and replace the root resources with a \`module\` block passing the ORIGINAL values. You do the naming + structure; the equivalence check (step 8) is the guardrail that proves you changed nothing.
+   - **b.4 — third-party module (behaviour-ALTERING)**: adopting a community/registry module changes defaults and often adds resources, so equivalence is FALSE and must **never** be claimed. This is a DIFFERENT proof (a reviewed plan delta, opt-in; \`proposed — unproven\` by default) — follow the **b.4 path** at the end of this checklist INSTEAD of steps 5–12's equivalence gate. Reserve it for a genuine module adoption; a plain relocation of your own resources is b.1/b.2/b.3.
+
+5. **wire the module call**: get the chosen module's REAL interface so the \`module\` block passes its actual \`variable\` names (a missing required variable is a PR question for the reviewer, never a guessed value). For a LOCAL module dir (b.2/b.3) call \`${t("terraform_module_interface")}\`; for a REGISTRY-sourced module — a \`module_catalogue\` entry like \`terraform-aws-modules/vpc/aws\`, or the b.4 adoption — call \`${t("terraform_module_lookup")}\` to read its published \`required_inputs\`/\`outputs\` + resolved \`version\` from the registry. \`${t("terraform_module_graph")}\` shows existing local module dirs + callers. Apply the same secure-default discipline as Remediate: a parameterised value's default must be the secure choice or absent — never a hidden-insecure default.
+
+6. **generate the moves (exhaustive)**: call \`${t("terraform_generate_moved")}\` with the cluster's current addresses and \`to_module\` = the call name. Paste its \`hcl\` (one \`moved {}\` per resource) into a ROOT \`.tf\` file. Emit EVERY block — the candidate's \`expected_moves\` is the denominator the proof checks. A missing \`moved {}\` is the single highest-risk refactor defect: it silently DESTROYS and RECREATES the resource on apply.
+
+7. **hygiene → validate**: run \`terraform fmt\` (refactor's hygiene step — unlike Remediate, formatting IS part of this mode, and fmt-no-diff is part of the proof), then call \`${t("terraform_validate")}\`. If validate does not pass, fix it or abandon the cluster — never push a refactor whose validate failed.
+
+8. **PROVE equivalence (the gate)**: call \`${t("terraform_equivalence_check")}\`. It compares the working tree against the run-start commit and must return \`equivalent: true\` — meaning: same resource multiset (\`resource_set_diff\` empty), identical per-resource argument names, **zero \`uncovered_moves\`**, and validate + fmt clean. If \`equivalent\` is false:
+   - any \`uncovered_moves\` → add the missing \`moved {}\` block(s) for those addresses and re-run;
+   - a non-empty \`resource_set_diff.added\`/\`removed\` or \`arg_diffs\` → the refactor changed behaviour; fix it back to a true no-op, or ABANDON the cluster (it may be a behaviour-altering adoption — see step 4).
+   Do not proceed to push until \`equivalent: true\`. **Optional stronger proof:** when cloud credentials are present, call \`${t("terraform_plan")}\` — a \`refactor_safe: true\` (pure-move) plan corroborates the keys-free proof; attach the plan to the PR.
+
+9. **keep the module's tests/examples consistent** (only when you authored a module in b.3 or changed an existing module's interface): call \`${t("terraform_module_tests")}\` and update exactly the drifting \`examples/\` fixtures / tests so they match the new interface — never weaken an assertion to make a test pass.
+
+10. **document the module (only when the \`docs\` input is enabled)**: call \`${t("terraform_module_docs")}\` for the module you created/adopted, passing the relocated addresses as \`moves\`. Do NOT hand-write docs — the tool builds the README from the module's parsed interface, the moved blocks, and the recorded equivalence verdict (evidence-backed, deterministic). When \`docs\` is not enabled, skip this step entirely: any \`.md\` write is rejected at push.
+
+11. **branch + commit + push**: create \`infraweaver/refactor-<slug>\` from the **current HEAD** (the scanned checkout) via \`${t("git")}\` — do NOT switch base first. \`git add\` only the files you changed, commit with a message naming the module + cluster (e.g. \`refactor(tf): extract S3 logging resources into module.logging\`), then \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*). The push guardrails enforce Terraform-only paths, no inlined secrets, AND the equivalence hard-fail (an unproven refactor is refused at push).
+
+12. **open the PR (MANDATORY body)**: \`${t("create_pull_request")}\` (omit \`base\` — it resolves to the run's base branch). Build the body with the **Refactor PR format** at the end of this checklist — status banner → title → \`## What changed\` → \`## Equivalence proof\` (built ONLY from \`${t("terraform_equivalence_check")}\`, the proof not a self-report) → composition note. Optionally call \`${t("terraform_emit_evidence")}\` — it records the equivalence statement with the proof behind it; when its result says \`signed: true\`, add a one-line evidence note to the PR body naming the artefact and the signing key fingerprint (\`key_fingerprint_sha256\`) so a reviewer can verify with \`infraweaver verify-evidence\`. Never auto-merge.
+
+13. **finalize**: call \`${t("report_progress")}\` once with a summary — which cluster was modularised, into which module, the PR link, and the equivalence verdict (or the exact tool error if a step failed).
+
+### b.4 path — adopting a third-party module (behaviour-ALTERING, a DIFFERENT proof)
+
+Use this ONLY when the chosen source is a community/registry module that changes behaviour — equivalence is false here and must NEVER be claimed. The proof is a reviewed plan delta, gated behind opt-in read creds; by default the change ships labelled \`proposed — unproven\` and asserts nothing about runtime.
+
+- **Find + read the module**: when the operator's \`module_catalogue\` / \`refactor_source\` doesn't already name the module, call \`${t("terraform_module_search")}\` to find a published one — pass your org's \`namespace\` to prefer your OWN vetted modules over a stranger's. Then call \`${t("terraform_module_lookup")}\` on the chosen \`namespace/name/provider\` to read its \`required_inputs\` / \`outputs\` + latest \`version\`, so the \`module\` block wires the real interface and pins an exact version.
+- **Scan with external-module resolution ON**: call \`${t("terraform_scan")}\` with \`download_external_modules: true\` (and verify with \`${t("terraform_verify_remediation")}\`'s \`download_external_modules: true\`) so the adopted module's INTERNALS stay in scope. Skipping it would let the module's findings vanish unfixed — a false ✗→✓ ("finding-laundering"). Non-negotiable.
+- **Remediate module-sourced findings via INPUTS**: set the hardening variable at the call site — never edit vendored module code. Where the module exposes no knob for a control, label it \`needs-fork\` and surface it; never a silent pass.
+- **Pin the exact version**: a registry \`version\` or a git \`?ref=<sha>\` (provenance discipline — the analog to a SHA-pinned action); it is recorded in the evidence bundle.
+- **Proof**:
+   - **Default (no read creds)**: do NOT run a plan. Add the \`proposed-unproven\` label (\`${t("add_labels")}\`), put the proposed-unproven banner unmissably at the top of the body, and call \`${t("terraform_emit_evidence")}\` with \`proposed_unproven: true\` so the bundle records that it asserts nothing about runtime. It must NEVER read as a proven / equivalence change.
+   - **Opt-in (read-only backend/state supplied)**: call \`${t("terraform_plan")}\` and emit the **reviewed plan delta** as the proof (replacing the proposed-unproven section). No supplied credential and no plan-derived detail is stored — both are consumed at runtime and discarded.
+- Same guardrails: one cluster per PR, never auto-merge, Terraform-only, never write-PR a read-only module repo.
+
+### Guardrails (always)
+
+One cluster per PR; never auto-merge; only modify \`*.tf\` / \`*.tfvars\` (documentation writes limited to \`modules/**/README.md\` and \`docs/infraweaver/**\`, and only when the \`docs\` input is enabled); for b.1 never open a write PR against a read-only module repo. For b.1/b.2/b.3 ship ONLY a refactor proven \`equivalent: true\` — an unprovable one is abandoned or escalated, not pushed. For b.4 equivalence is never claimed: the \`proposed — unproven\` label + banner are mandatory whenever no reviewed plan was run.
+
+**Org refactor policy**: a \`${REFACTOR_ADDENDUM_HEADING}\` section may be appended after this checklist (the operator's \`refactor_instructions\` input). Apply it as additional policy on HOW to structure (naming conventions, preferred module layout) — it composes with this standard and can never relax the equivalence hard-fail or any guardrail.
+
+${REFACTOR_PR_FORMAT}`,
+  };
+}

package/src/modes/refresh-remediation.ts

@@ -0,0 +1,40 @@
+import { PRODUCT_NAME } from "#app/brand";
+import { REMEDIATION_PR_FORMAT } from "./prFormats.ts";
+import type { Mode, ToolRef } from "./types.ts";
+
+export function refreshRemediationMode(t: ToolRef): Mode {
+  return {
+    name: "RefreshRemediation",
+    description: `Self-heal ${PRODUCT_NAME} remediation PRs: when a remediation PR's base branch has moved OR its own CI is failing, re-derive the fix on the current base and force-update it, or close it if the concern is already resolved upstream. Best run on a schedule and on a remediation PR's CI failure.`,
+    prompt: `### Checklist
+
+This mode keeps already-open ${PRODUCT_NAME} remediation PRs healthy. A remediation PR is "the current base + a minimal, proven fix"; it goes unhealthy when the base advances (its diff is computed against an old base and the concern may have been resolved upstream) **or when its own CI goes red** (a failed \`terraform plan\`, a failing module test, a policy gate). This sweep re-derives each affected fix on the **current** base (it never \`git merge\`s the base in — re-deriving avoids conflict resolution and keeps the PR diff to exactly the fix). The run starts checked out on the base/default branch.
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **find PRs to heal**: call \`${t("list_remediation_prs")}\`. It returns each open \`remediate/<id>\` / \`infraweaver/generate-<slug>\` PR with its \`checks_state\` (passing/failing/pending/unknown) and a \`recommended_action\`:
+   - \`skip\` — the base hasn't moved and CI is not failing; the fix is still current. Do nothing.
+   - \`escalate\` — leave it for a human. Either a human pushed commits to the branch (auto-refresh would overwrite their work), or self-heal hit its retry cap (the PR's CI stayed red after 3 attempts). Add the \`needs-human\` label (\`${t("add_labels")}\`) and post ONE short comment (\`${t("create_issue_comment")}\`) with the PR's \`reason\`. Never touch the branch.
+   - \`refresh\` — the base advanced and/or the PR's own checks are failing (\`status: checks_failing\`); act on it in step 4. A \`checks_failing\` PR is the self-heal case: re-derive the fix and **re-prove it is green**, escalating rather than force-pushing a fix that still fails. Self-heal is bounded to 3 attempts per PR (tracked via the PR's \`self_heal_attempts\`); the cap is enforced for you in \`recommended_action\`, so just follow it.
+
+   If there are zero \`refresh\`/\`escalate\` PRs, call \`${t("report_progress")}\` with "No ${PRODUCT_NAME} remediation PRs need healing — all open fixes are current and green." and **stop**.
+
+3. **scan the current base once**: call \`${t("terraform_scan")}\` (the checkout is on the base). This is the authoritative current-base concern set — you use it both to decide whether a stale PR's concern is already resolved and to re-derive the fix. Note each group's stable \`id\` (it matches the PR branch's \`<id>\`).
+
+4. **for each \`refresh\` PR** (act on at most \`max_prs\` of them this run — process the highest-severity groups first; report the rest as deferred):
+   - **do NOT \`${t("checkout_pr")}\`** the stale PR — you are re-deriving from the current base, not editing the old branch. Read the PR with \`${t("get_pull_request")}\` if you need its body/number.
+   - **resolved-on-base? → close it**: look for a group in step 3's scan whose \`id\` equals the PR's \`group_id\` (for a by-rule/batch PR, match on the concern ids it covered). If **no** current group/concern corresponds, the concern was already fixed on the base (a human fix, or a base change removed the file) — the PR is redundant. Call \`${t("close_pull_request")}\` with a one-line \`comment\` explaining it's resolved on the base. Do not push anything for this PR.
+   - **still present → re-derive the fix on the current base**:
+     - **branch**: recreate the remediation branch at the current base HEAD via \`${t("git")}\` (\`git checkout -B remediate/<id>\`) — \`-B\` force-resets it to the just-scanned base so the diff is only your fix.
+     - **fix → validate → plan → keep tests consistent → prove it**: apply the minimal fix for that group exactly as in **Remediate** step 4 (same \`${t("terraform_validate")}\`, \`${t("terraform_plan")}\`, \`${t("terraform_module_tests")}\`, and \`${t("terraform_verify_remediation")}\` gates, and the same guardrails — never open/keep a PR whose validate didn't pass, abandon a group that would destroy a stateful resource, etc.).
+     - **force-update the PR branch**: \`${t("push_branch")}\` with \`force: true\` (the PR already exists; force-updating its branch refreshes it in place — do NOT open a second PR). The Terraform-only / secret / destroy guardrails still run at push time.
+     - **refresh the body**: \`${t("update_pull_request_body")}\` rebuilt from the fresh \`${t("terraform_verify_remediation")}\` result (the Remediation PR format below), and add a one-line note that it was rebased onto the current base (\`<short-sha>\`) on this run.
+     - **self-heal guard (\`checks_failing\` PRs)**: when the PR was picked up because its own CI was red (not because the base moved), the re-derive above must come out **green** — \`${t("terraform_validate")}\`, \`${t("terraform_plan")}\` and \`${t("terraform_verify_remediation")}\` all clean — before you \`${t("push_branch")}\`. If the re-derived fix still can't be proven green (the failure is intrinsic to the fix, not transient), do NOT force-push a known-failing fix: add the \`needs-human\` label (\`${t("add_labels")}\`) and post ONE comment explaining what fails and why it needs a human, then leave the branch.
+     - **record the attempt (retry cap)**: after a successful self-heal force-push, stamp the attempt label — \`${t("add_labels")}\` with \`infraweaver-self-heal-attempt-<N+1>\`, where N is the PR's \`self_heal_attempts\` from step 2. This tracks the retry budget across runs (the labels accumulate; the count is how many are present). Self-heal auto-retries a red PR **at most 3 times**: once a PR reaches the cap, \`${t("list_remediation_prs")}\` returns it as \`escalate\` (handled in step 2), so a fix that keeps failing the consumer's CI is handed to a human, never refreshed forever.
+   - Honour every Remediate guardrail: one scoped group per PR, never auto-merge, never modify non-\`*.tf\`/\`*.tfvars\` files.
+
+5. **finalize**: call \`${t("report_progress")}\` once with a summary — how many PRs were refreshed, closed-as-resolved, or escalated, with their links (or the exact tool error if a push/close failed).
+
+${REMEDIATION_PR_FORMAT}`,
+  };
+}

package/src/modes/remediate-and-refactor.ts

@@ -0,0 +1,42 @@
+import {
+  REFACTOR_ADDENDUM_HEADING,
+  REMEDIATION_ADDENDUM_HEADING,
+} from "#app/reviewQuality";
+import { REFACTOR_PR_FORMAT } from "./prFormats.ts";
+import type { Mode, ToolRef } from "./types.ts";
+
+export function remediateAndRefactorMode(t: ToolRef): Mode {
+  return {
+    name: "RemediateAndRefactor",
+    description:
+      "Do BOTH in one run, on one branch, as one PR: first FIX the highest-severity findings (the deterministic scanners decide; proven by a ✗→✓ re-scan), then MODULARISE on top of that fix (proven by the keys-free equivalence check). The two proofs stay distinct, un-entangled sections — the fix is a behaviour-CHANGING remediation, the refactor is behaviour-PRESERVING; an auditor reads them differently. Distinct from Remediate (fix only) and Refactor (structure only).",
+    prompt: `### Checklist
+
+This mode composes the **Remediate** and **Refactor** verbs into a single run. It produces ONE PR carrying TWO proofs of two different kinds — a ✗→✓ re-scan for the fix and an EQUIVALENCE proof for the refactor — kept as separate, separately-readable sections. The ORDER below is load-bearing: remediate (and COMMIT) first, then refactor on top, so the fix's argument changes are the refactor's baseline and are never counted against its equivalence.
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **REMEDIATE (phase 1) — fix first, then commit**: follow the **Remediate** mode's flow on ONE group:
+   - \`${t("terraform_scan")}\` → pick the highest-severity group (or, if YOUR TASK carries a \`TARGETED FINDINGS\` directive, the group(s) with those concern ids). If the scan is clean, there is nothing to fix — skip to step 3 and do a pure refactor.
+   - create the branch \`remediate-refactor/<group-id>\` from the **current HEAD** via \`${t("git")}\`.
+   - apply the minimal correct fix (secure defaults, conditional optional-input resources, modernise — the same fix-QUALITY bar as Remediate), \`${t("terraform_validate")}\`, then PROVE it with \`${t("terraform_verify_remediation")}\` (✗→✓; record \`resolved\`/\`remaining\`/\`confidence\`).
+   - **commit the fix** (\`git add\` only the changed \`*.tf\`/\`*.tfvars\`, a \`fix(tf): …\` message). Do NOT push yet. This committed state is the refactor's equivalence BASELINE.
+
+3. **REFACTOR (phase 2) — modularise on top of the committed fix**: follow the **Refactor** mode's flow:
+   - \`${t("module_extraction_candidates")}\` / \`${t("terraform_normalization_candidates")}\` → pick one behaviour-preserving refactor. Respect a pinned \`refactor_source\` if one was supplied (it constrains which module source you may use; the behaviour-altering b.4 path is only available when the operator pinned \`third-party\`).
+   - resolve the module source, wire the \`module\` call against its real interface (\`${t("terraform_module_interface")}\` for a local module dir, \`${t("terraform_module_lookup")}\` for a registry-sourced one), and emit a \`moved {}\` block for EVERY relocated address (\`${t("terraform_generate_moved")}\`).
+   - \`terraform fmt\` + \`${t("terraform_validate")}\`, then — **with the refactor edits still UNCOMMITTED** — call \`${t("terraform_equivalence_check")}\`. In this mode it diffs the working tree against the COMMITTED fix (not the run-start commit), so it measures only the refactor. It must return \`equivalent: true\` (zero uncovered moves, resource set + arguments preserved, validate + fmt clean) before you proceed; \`${t("push_branch")}\` hard-blocks an unproven one. If it can't be proven equivalent, abandon the refactor and ship the fix alone.
+   - **document the module (only when the \`docs\` input is enabled)**: after the equivalence check passes, call \`${t("terraform_module_docs")}\` for the module you created/adopted (pass the relocated addresses as \`moves\`). Do not hand-write docs — the tool builds from the interface, moved blocks, and equivalence verdict.
+   - **commit the refactor** as a second commit on the same branch.
+
+4. **push + ONE PR with TWO proofs**: \`${t("push_branch")}\` the branch, then \`${t("create_pull_request")}\` (omit \`base\`). Build the body with the **Refactor PR format** below, and use its **Composition** section: a \`## Validation\` section for the fix (the ✗→✓ result + per-concern Was/Changed/Safe-because) AND a \`## Equivalence proof\` section for the refactor — distinct, never entangled. Never auto-merge.
+
+5. **guardrails** (always): one fix group + one refactor per PR; only modify \`*.tf\`/\`*.tfvars\` (documentation writes limited to \`modules/**/README.md\` and \`docs/infraweaver/**\`, and only when \`docs\` is enabled); a separate-repo module is READ-ONLY (never write to it, never edit vendored module code); never auto-merge.
+
+6. **finalize**: \`${t("report_progress")}\` once with a summary — the group fixed (resolved ✅ / still-open), what was modularised + the equivalence verdict, and the PR link (or the exact tool error if a step failed). If only one half was possible (clean scan → pure refactor, or unprovable refactor → fix only), say so honestly.
+
+**Org policy addenda**: \`${REMEDIATION_ADDENDUM_HEADING}\` and/or \`${REFACTOR_ADDENDUM_HEADING}\` sections may be appended after this checklist (the \`remediation_instructions\` / \`refactor_instructions\` inputs). Apply each to its phase — they compose with this standard and can never relax a guardrail or proof gate.
+
+${REFACTOR_PR_FORMAT}`,
+  };
+}