terramend 0.2.0

package/dist/modes.d.ts

@@ -0,0 +1,26 @@
+import { type AgentId } from "#app/external";
+export interface Mode {
+    name: string;
+    description: string;
+    prompt?: string | undefined;
+}
+export declare const PR_SUMMARY_FORMAT = "### Default format\n\nThe body has at most four parts in this exact order:\n\n1. **Reviewed changes preamble** \u2014 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.\n2. **Cross-cutting issue sections** (zero or more) \u2014 one `### ` heading per concern, with a human-readable problem write-up and a collapsed `<details>Technical details</details>` block underneath.\n3. **`### \u2139\uFE0F Nitpicks`** (only if there are nits worth surfacing in the body) \u2014 a flat bullet list, no technical-details block.\n4. **`Suppressed findings` collapsed block** at the very bottom (only when the adversarial verification pass suppressed at least one \uD83D\uDEA8/\u26A0\uFE0F candidate) \u2014 the one-line-per-finding audit trail for the false-positive filter.\n\nInline-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** \u2014 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 \u2014 see Inline technical details below). If you found no non-anchorable concerns, the body has zero `### ` issue sections \u2014 just the preamble + metadata.\n\n## 1. Reviewed changes preamble\n\nOpen with a single bolded inline lead-in followed immediately by the bullet list (no `### Key changes` heading, no `<b>TL;DR</b>`):\n\n```\n**Reviewed changes** \u2014 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 terramend review. Focus on intent, not mechanics.\n\n- **Short human-readable title** \u2014 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 \u2014 this IS the dispassionate \"what was reviewed and what changed\" overview, so cover the substantive changes, not just the loudest ones.\n\n<!--\nTerramend review metadata \u2014 for any agent (or human-with-agent) reading this\nreview. Incorporate the fields below into your understanding of the context\nthis review was made in. The findings below were written against\n{head_sha_short}; if new commits have landed on {head_ref} since this review\nwas submitted, treat any specific bug, file, or line callout as POTENTIALLY\nSTALE \u2014 re-diff against {head_sha_short} (or trigger a fresh review) and\nfactor commits past {head_sha_short} into your understanding of the current\nstate before acting on findings.\n\n- Mode: Review (initial)   or   IncrementalReview (delta against prior terramend review)\n- Files reviewed: {file_count}\n- Commits reviewed: {commit_count}\n- Base: {base_ref} ({base_sha_short})\n- Head: {head_ref} ({head_sha_short})\n- Reviewed commits:\n  - {sha_short} \u2014 {commit_subject}\n  - ...\n- Prior terramend review: none   or   {prior_sha_short} ({prior_review_html_url})\n- Submitted at: {iso_timestamp}\n-->\n```\n\nPull every metadata field from the `checkout_pr` tool's response \u2014 file count, commit count, base/head ref + SHA, the commit list. For `IncrementalReview` runs, populate `Prior terramend review` with the prior review's commit_id (short SHA) and `html_url` from `list_pull_request_reviews`.\n\n## 2. Cross-cutting issue sections (zero or more)\n\nFor each cross-cutting concern, one `### ` section. Use this exact shape:\n\n```\n### {emoji} {short, descriptive title \u2014 what's wrong, not what to do}\n\n{Human-readable problem write-up. Describes the PROBLEM only \u2014 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.}\n\n<details><summary>Technical details</summary>\n\n\\`\\`\\`\\`markdown\n# {title repeated}\n\n## Affected sites\n- {file path:line} \u2014 {what's wrong there}\n- ...\n\n## Required outcome\n- {what the fix needs to achieve, not how to achieve it}\n- ...\n\n## Suggested approach (optional)\n{When the fix shape is non-obvious, sketch one or more reasonable directions. Skip when the outcome alone makes the fix obvious.}\n\n## Open questions for the human (optional)\n- {Any decision an implementing agent shouldn't make unilaterally \u2014 pricing thresholds, breaking-change policy, naming, scope of follow-up.}\n\\`\\`\\`\\`\n\n</details>\n```\n\nConcrete example of the visible part of a non-anchored section (technical-details block unchanged from the template above):\n\n```\n### \u2139\uFE0F Legacy `opencode.ts` has no documented deletion plan\n\nThe 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.\n```\n\nThe 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.\n\n**Heading severity emoji** \u2014 every `### ` heading carries one:\n\n- \uD83D\uDEA8 critical \u2014 blocks merge (data loss, security, broken core flow)\n- \u26A0\uFE0F important \u2014 must address before merging (regression, missing validation, incorrect behavior)\n- \u2139\uFE0F informational \u2014 surfaced for awareness; mergeable as-is\n\n**Visible problem write-up rules:**\n\n- **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'\") \u2014 in that case, fold it into the problem statement and skip the suggested-approach block in technical details too.\n- **Never two successive plain paragraphs.** Every transition between block-level elements must alternate prose with structure: paragraph \u2192 bullet list \u2192 paragraph; paragraph \u2192 code fence \u2192 bullet list; paragraph \u2192 table \u2192 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.\n- **Per-paragraph budget:** ~3 sentences max. Past that, you're explaining where you should be structuring.\n- **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.\n\n**Technical-details block rules:**\n\n- 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 \u2014 a fix-agent will pull the body down and use this block as the brief.\n- File paths and `file:line` refs are encouraged (and necessary) \u2014 the next agent uses these to navigate. Identifier density is fine here.\n- 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 \u2014 the implementing agent writes those.\n- 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.\n\n## Inline technical details\n\nInline comments are short (~2-3 sentences) by default. When an inline finding has broader implications worth recording for a fix-agent \u2014 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 \u2014 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`).\n\nGitHub 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.\n\n## 3. `### \u2139\uFE0F Nitpicks` (optional, last content section)\n\nOnly when there are nits that for some reason can't be inlined. Filepaths in nit text are fine \u2014 these are simple enough that a human or agent reads once and acts. No technical-details block.\n\n```\n### \u2139\uFE0F Nitpicks\n\n- {nit, with file path inline if useful, \u2264 ~200 chars}\n- ...\n```\n\n## 4. `Suppressed findings` (optional, very last)\n\nOnly when the adversarial verification pass (see the checklist) suppressed at least one \uD83D\uDEA8/\u26A0\uFE0F candidate. One collapsed block, always the last element in the body, with the count in the summary line:\n\n```\n<details><summary>\uD83D\uDDD1\uFE0F Suppressed findings (2)</summary>\n\n- \u26A0\uFE0F `networking/main.tf:42` \u2014 claimed the subnet exposes the DB publicly \u2014 refuted: `publicly_accessible = false` at `db.tf:18`.\n- \uD83D\uDEA8 `api/auth.ts:77` \u2014 claimed JWT signature bypass \u2014 refuted: the unverified decode is dev-only, gated by the `NODE_ENV` check two lines above.\n\n</details>\n```\n\nOne bullet per suppressed finding: severity emoji, `file:line`, the claim in a few words, the refutation in a few words. One line each \u2014 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.\n\n## Inline comment shape\n\nInline comments use the same severity framing as body `### ` sections, scaled down for line-anchored use:\n\n- **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 \u2014 describe what's wrong with it. Optionally prefix the visible line with a severity emoji (\uD83D\uDEA8 / \u26A0\uFE0F / \u2139\uFE0F) when severity isn't obvious from context.\n- **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 \u2014 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.\n- **Visible portion \u2264 2-3 sentences.** If you find yourself writing more, that's the cue to split the depth into the `Technical details` collapsible.\n\n## Body-wide rules\n\n- **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 \u2014 absence, sequencing, design decisions, scope questions, architectural risk.\n- **No `### Issues found` heading** above the issue sections \u2014 each `### ` heading IS the issue.\n- **Severity emoji on every `### ` heading** (\uD83D\uDEA8 / \u26A0\uFE0F / \u2139\uFE0F). No emoji on the preamble lead-in or anywhere else.\n- **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.\n- **Backtick-wrap** every variable, identifier, or file name when you mention one (in either visible or technical-details portions).\n- **Don't repeat diff content**, don't include raw `+123 / -45` stats, don't include a changelog section, don't use horizontal rules (`---`).\n- **Pull file/commit counts from `checkout_pr` metadata** \u2014 never count manually.\n- **Legacy headings REMOVED.** Do not use `### Key changes`, `### Issues found`, `<b>TL;DR</b>`, or `<sub><b>Summary</b>`. The new structure subsumes them.";
+export declare const REMEDIATION_PR_FORMAT = "### Remediation PR format\n\n**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 (\u2717 \u2192 \u2713)` list. If you produce nothing else, produce these three \u2014 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.\n\nBuild the PR body in this EXACT order. Every line is backed by a tool result \u2014 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).\n\n#### 1. Status banner (first line)\n\nOne GitHub alert blockquote that sets the reviewer's expectation, picked from the verification evidence:\n\n- `> [!CAUTION]` \u2014 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.\n- `> [!WARNING]` \u2014 verified but with a caveat (medium blast radius, a still-`remaining` concern, baseline-unavailable cost).\n- `> [!NOTE]` \u2014 clean: `verified: true`, no regressions, low blast radius. One sentence: what was hardened.\n\n#### 2. Title line + badges\n\nA 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):\n\n```\n**Hardened \\`main.tf\\` \u2014 S3 encryption + public-access block.**\n\n`Confidence: high` \u00B7 `Blast radius: low (1 resource)` \u00B7 `Plan: +0 ~1 -0` \u00B7 `Idempotent: yes` \u00B7 `Cost: +$0.00/mo`\n```\n\nRender `Confidence` verbatim from `terraform_verify_remediation.confidence` \u2014 never inflate it. Use `\u00B7` separators, backtick-wrap each badge.\n\n#### 3. `## What changed`\n\nOne `### ` subsection per resolved concern (or one per rule for a by-rule group), each with the \u00A75.17 three-line micro-template and the rule linked to its docs (`doc_url`, else `remediation_hint`):\n\n```\n### \uD83D\uDD12 [\\`trivy:AVD-AWS-0088\\`](https://avd.aquasec.com/misconfig/avd-aws-0088) \u2014 S3 bucket not encrypted\n\n- **Was** \u2014 {the scanner's `evidence`, in plain English}.\n- **Changed** \u2014 {what the fix did, one sentence}.\n- **Safe because** \u2014 {why it's correct and non-breaking}.\n```\n\nLead each heading with a severity emoji (\uD83D\uDEA8 critical \u00B7 \u26A0\uFE0F high \u00B7 \uD83D\uDD12 security \u00B7 \u2139\uFE0F low/info). Backtick-wrap every identifier. No raw diff dumps \u2014 the Files tab shows the diff.\n\n#### 4. `## Validation (\u2717 \u2192 \u2713)`\n\nBuilt ONLY from `terraform_verify_remediation`'s result \u2014 this is the proof, not a self-report. One line per id in `resolved`, then any still-open id honestly:\n\n```\n## Validation (\u2717 \u2192 \u2713)\n\n- \u2717 \u2192 \u2713 \\`trivy:AVD-AWS-0088\\` resolved\n- \u2717 \u2192 \u2713 \\`checkov:CKV_AWS_19\\` resolved\n- \u26A0\uFE0F still open: \\`tflint:...\\` \u2014 {why it couldn't be cleared}\n```\n\nIf `has_regressions` is true, add a `> [!CAUTION]` **Regression** callout listing each new concern id BEFORE this list, and ensure the `needs-human` label is set. Never mark an id \u2713 unless the tool returned it in `resolved`.\n\n#### 5. `<details><summary>Plan</summary>` (when `terraform_plan` ran)\n\nAttach the full `plan_text` in a collapsed code block so a reviewer sees the exact change without re-running it:\n\n```\n<details><summary>Terraform plan</summary>\n\n\\`\\`\\`\n{plan_text}\n\\`\\`\\`\n\n</details>\n```\n\nWhen `needs_human` is true, surface `needs_human_reasons` as a visible bullet list above the `<details>` \u2014 don't bury an escalation in a collapsed block.\n\n#### 6. `## \uD83D\uDEE1\uFE0F Prevent recurrence` (optional follow-up)\n\nFrom the scan's `prevention` map \u2014 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.\n\n#### 7. `## Compliance` (optional, when a crosswalk was run)\n\nWhen `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}) \u2014 not an audit verdict.\" Skip entirely when the crosswalk wasn't run.\n\n#### Body-wide rules\n\n- **Evidence-built, never self-reported** \u2014 every badge, \u2713, and count comes from a tool result. If a tool didn't run, omit its section; don't guess.\n- **Blank line between ALL block-level elements** (callouts, headings, lists, code fences, `<details>`) \u2014 GitHub renders markdown as literal text otherwise.\n- **Backtick-wrap** every file, rule id, resource address, and identifier.\n- **No raw `+N/-M` diff stats, no horizontal rules (`---`), no changelog section.** The footer is appended automatically \u2014 don't add your own.\n- **One scoped group per PR.** The body describes this group's fix only.";
+export declare function computeModes(agentId: AgentId): Mode[];
+export declare const modes: Mode[];
+/** built-in mode names in canonical casing. used to validate / canonicalize the
+ * `mode` action input so a CI run can pin a mode deterministically instead of
+ * relying on the agent's prompt-driven `select_mode` choice. mode names are
+ * agent-independent (only the embedded tool refs differ per agent), so the
+ * opencode-rendered list is the authoritative name set. */
+export declare const BUILTIN_MODE_NAMES: readonly string[];
+/**
+ * modes that legitimately never modify the working tree. used by the post-run
+ * dirty-tree gate to suppress the "commit and push" nudge — those modes
+ * complete by submitting a review (`Review` / `IncrementalReview`) or by
+ * posting a Plan comment (`Plan`), not by touching files. any leftover in the
+ * tree at end-of-run is incidental tool noise (e.g. a `node_modules/` from a
+ * stray install attempt) on an ephemeral worktree; nudging the agent to
+ * commit it would produce a spurious PR.
+ */
+export declare const NON_COMMITTING_MODES: ReadonlySet<string>;

package/dist/prep/index.d.ts

@@ -0,0 +1,7 @@
+import type { PrepOptions, PrepResult } from "#app/prep/types";
+export type { PrepOptions, PrepResult } from "#app/prep/types";
+/**
+ * run all prep steps sequentially.
+ * failures are logged as warnings but don't stop the run.
+ */
+export declare function runPrepPhase(options: PrepOptions): Promise<PrepResult[]>;

package/dist/prep/installNodeDependencies.d.ts

@@ -0,0 +1,2 @@
+import type { PrepDefinition } from "#app/prep/types";
+export declare const installNodeDependencies: PrepDefinition;

package/dist/prep/installPythonDependencies.d.ts

@@ -0,0 +1,2 @@
+import type { PrepDefinition } from "#app/prep/types";
+export declare const installPythonDependencies: PrepDefinition;

package/dist/prep/types.d.ts

@@ -0,0 +1,31 @@
+interface PrepResultBase {
+    dependenciesInstalled: boolean;
+    issues: string[];
+}
+export type NodePackageManager = "npm" | "pnpm" | "yarn" | "bun" | "deno";
+export interface NodePrepResult extends PrepResultBase {
+    language: "node";
+    packageManager: NodePackageManager;
+}
+export type PythonPackageManager = "pip" | "pipenv" | "poetry";
+export interface PythonPrepResult extends PrepResultBase {
+    language: "python";
+    packageManager: PythonPackageManager;
+    configFile: string;
+}
+export interface UnknownLanguagePrepResult extends PrepResultBase {
+    language: "unknown";
+}
+export type PrepResult = NodePrepResult | PythonPrepResult | UnknownLanguagePrepResult;
+export type PrepOptions = {
+    /** when true, lifecycle scripts (postinstall, etc.) are suppressed */
+    ignoreScripts: boolean;
+    /** directory the corepack shim is installed into (see `packageManagerBinDir`) */
+    binDir: string;
+};
+export interface PrepDefinition {
+    name: string;
+    shouldRun: () => Promise<boolean> | boolean;
+    run: (options: PrepOptions) => Promise<PrepResult>;
+}
+export {};

package/dist/reviewQuality.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Review-quality controls for the Review / IncrementalReview modes: a curated
+ * false-positive precedents list and an adversarial per-finding verification
+ * pass. Both are embedded into the mode prompts (modes.ts) — the precedents
+ * also travel verbatim inside every verification dispatch, since subagents
+ * never see the orchestrator's prompt.
+ *
+ * Provenance: adapted from Anthropic's claude-code-security-review action
+ * (MIT) — its hard-exclusion rules, its LLM-judge "PRECEDENTS" list, and the
+ * /security-review slash command's refute-subagent pattern. See
+ * CLAUDE-CODE-SECURITY-REVIEW-VS-TERRAMEND.md (workspace root) §5.1–5.2 for
+ * the comparison that motivated this. Deliberate divergences from upstream:
+ *   - CCSR judges findings via sequential direct API calls; we dispatch
+ *     parallel read-only reviewfrog subagents (machine-gated, see
+ *     agents/subagentToolGates.ts) so verification adds one round of wall
+ *     time regardless of finding count.
+ *   - CCSR's judge gates on a bare confidence number; we gate on an explicit
+ *     verdict (confirmed/refuted/uncertain) plus confidence, because the
+ *     verdict is what the orchestrator acts on and the number alone invites
+ *     anchoring.
+ *   - CCSR drops "secrets stored on disk" findings (handled by a separate
+ *     pipeline there). Terramend reviews IaC where a hardcoded credential is
+ *     a core finding, so that exclusion is intentionally NOT inherited.
+ * Kept as-is from upstream: fail-open semantics (a broken verifier must
+ * never silently swallow a true positive) and suppression auditability
+ * (excluded findings are listed, never deleted).
+ */
+/**
+ * False-positive precedents applied at aggregation time and inside every
+ * verification dispatch. Each entry encodes a recurring FP class; a candidate
+ * matching one needs specific evidence that the precedent does not apply, or
+ * it gets dropped. Ordered: hard exclusions (never post) → general code
+ * precedents → Terraform/IaC precedents → the final signal-quality bar.
+ */
+export declare const REVIEW_FINDING_PRECEDENTS = "### Finding precedents (false-positive control)\n\nApply these when deciding whether a candidate finding is worth posting, and include this whole section verbatim in every verification dispatch. Each precedent encodes a recurring false-positive class: a candidate that matches one is dropped unless you have specific evidence the precedent does not apply here.\n\n**Hard exclusions \u2014 never post:**\n\n- Denial-of-service / resource-exhaustion concerns without a concrete, cheap-to-trigger attack path: missing rate limiting, \"unbounded\" loops over trusted input, \"could exhaust memory/CPU\".\n- Theoretical race conditions or timing attacks. Post a race only when it is concretely reachable and concretely harmful.\n- Memory-safety findings (buffer overflow, use-after-free, OOB) in memory-safe languages \u2014 Rust, Go, JS/TS, Python, Java, HCL.\n- Security findings whose anchor is a documentation file \u2014 a code snippet in `.md`/`.mdx` is not an attack surface. (Stale or incorrect docs remain valid *impact* findings; this exclusion is only for treating doc content as exploitable.)\n- \"Lack of hardening\" with no vulnerability: code is not required to implement every best practice, only to avoid concrete flaws.\n- Vulnerable-dependency reports based on version strings alone \u2014 dependency scanning is a separate pipeline with its own remediation flow.\n\n**General precedents:**\n\n- Environment variables, CLI flags, and workflow-dispatch inputs are operator-trusted. An attack that requires controlling them is invalid.\n- A missing permission/auth check in client-side code is not a finding; the server is the enforcement boundary. The same applies to client-side input validation.\n- React/Angular-class frameworks escape output by default \u2014 an XSS claim needs `dangerouslySetInnerHTML`, `bypassSecurityTrustHtml`, or an equivalent unsafe API in the diff.\n- SSRF requires control of host or protocol; path-only control is not SSRF. Neither SSRF nor path traversal applies to purely client-side code.\n- Command injection in shell scripts needs a named untrusted-input path; developer-invoked scripts taking developer-supplied arguments don't qualify.\n- Un-sanitized user input reaching logs is log spoofing, not a vulnerability. A logging finding is valid only when it exposes secrets, credentials, or PII.\n- UUIDs are unguessable; an attack that requires guessing one is invalid.\n\n**Terraform / IaC precedents:**\n\n- `0.0.0.0/0` **egress** is common and usually intentional \u2014 flag open **ingress**, or egress only with a concrete exfiltration concern attached.\n- Values from `*.tfvars`, `locals`, and module input variables are operator-trusted; \"what if this variable is malicious\" is invalid without naming an untrusted writer.\n- Missing encryption / versioning / access-logging on resources that demonstrably hold no sensitive data (short-retention log groups, test fixtures, scratch buckets) is \u2139\uFE0F at most, never \uD83D\uDEA8.\n- Unpinned provider or module versions are style feedback for first-party modules; \u26A0\uFE0F only for third-party module sources, where the unpinned ref is supply-chain surface.\n- Do not infer state drift, plan outcomes, or \"this will destroy/replace the database\" from static HCL \u2014 only `terraform plan` evidence supports those claims. Without plan evidence, phrase the concern as an open question, not a finding.\n- Missing tags and naming-convention deviations are nitpicks, not findings.\n- When a deterministic scanner rule covers the same issue (trivy `AVD-*`, checkov `CKV_*`, tflint), cite the rule id in the finding \u2014 that makes it \u2717\u2192\u2713 verifiable downstream instead of an unverifiable reviewer opinion.\n\n**Signal-quality bar** \u2014 a surviving candidate must still answer yes to all three: Is there a concrete failure or attack path? Is it a real risk rather than a theoretical best practice? Could the author act on it exactly as written?";
+/**
+ * Adversarial verification pass, spliced into the aggregation step of Review
+ * and IncrementalReview (between the non-anchored-concern hunt and comment
+ * drafting). The 0-or-2+ lens rule does not apply here — that rule buys
+ * independence between discovery perspectives; verification is a per-claim
+ * judgment with no orthogonality to purchase, so one finding = one dispatch
+ * is correct even when there is exactly one finding.
+ */
+export declare const FINDING_VERIFICATION_PASS = "**Adversarial verification \u2014 required before posting any \uD83D\uDEA8/\u26A0\uFE0F finding.** A candidate finding is a hypothesis until an independent pass has tried to kill it; your own trace is not independent, because you found it. For every candidate you intend to post at \uD83D\uDEA8 critical or \u26A0\uFE0F important, dispatch one `reviewfrog` verification subagent \u2014 ALL of them in a single assistant turn as parallel Task tool_use blocks. One candidate = one subagent, and dispatching exactly one is fine here: the 0-or-2+ rule governs discovery lenses, where independence between perspectives is the point; verification is per-claim judgment with no orthogonality to buy. Skip verification only for:\n\n   - \u2139\uFE0F informational findings and nitpicks (post on your own judgment), and\n   - findings whose evidence is deterministic tool output \u2014 a scanner concern id, a failing test, a compiler/type error. Those re-verify mechanically and need no judge.\n\n   Each verification dispatch contains, in order:\n   - the absolute `diffPath` (and `incrementalDiffPath` when available) named verbatim \u2014 the reviewer's baked-in system prompt selects its first action on this token;\n   - the single finding under test: file, line, intended severity, the claim, and the evidence you collected;\n   - the **Finding precedents** section \u2014 plus any `### Finding precedents \u2014 org addendum` section from your instructions \u2014 included verbatim (the subagent cannot see your prompt);\n   - this charge: \"Attempt to REFUTE this finding. Read the actual code \u2014 do not trust the claim's description of it. Apply the finding precedents. Report a verdict (`confirmed` / `refuted` / `uncertain`), a confidence score 1\u201310, and a 2\u20133 sentence justification quoting the code that decides it. When the attack or failure path is theoretical rather than demonstrated, bias toward `refuted`.\"\n\n   Set the Task `description` to `verify:<file>:<line>` so parallel verifications are distinguishable in CI logs. Asking for a verdict schema is correct here and does not violate the discovery-lens \"no finding schema\" discipline \u2014 the subagent is judging one claim, not exploring.\n\n   Gate on what comes back:\n   - `refuted` at confidence \u2265 7 \u2192 suppress the finding and record it for the audit trail.\n   - `uncertain`, or `refuted` at lower confidence \u2192 re-read the decisive code yourself; either downgrade to \u2139\uFE0F with the uncertainty stated, or suppress. Do not post it at \uD83D\uDEA8/\u26A0\uFE0F.\n   - `confirmed` \u2192 post it; fold the verifier's justification into the comment's technical-details block when it adds evidence.\n   - errored / timed out / nothing usable \u2192 retry once; if it still fails, KEEP the finding and add `verification unavailable` to its technical details. Fail open: a broken verifier must never silently swallow a true positive, and must never block the review.\n\n   Suppressed findings are recorded, never silently deleted \u2014 list every one in the `Suppressed findings` block at the bottom of the review body (shape defined in the format below): severity, `file:line`, the claim in a few words, the refutation in a few words. An unaudited filter eats true positives invisibly; the audit trail is what lets a human catch the filter being wrong.";
+/**
+ * Heading under which `fp_filtering_instructions` (the action input carrying
+ * org-specific FP precedents) is appended to the Review mode instructions.
+ * FINDING_VERIFICATION_PASS names this heading when telling the orchestrator
+ * what to include verbatim in each verification dispatch — the two strings
+ * are a contract; change them together.
+ */
+export declare const FP_PRECEDENTS_ADDENDUM_HEADING = "### Finding precedents \u2014 org addendum";
+/**
+ * Merge the §5.5 action inputs into the per-mode user instructions that
+ * `select_mode` appends to the mode prompt (see buildOrchestratorGuidance in
+ * mcp/selectMode.ts). Both land on the "Review" key — IncrementalReview
+ * inherits Review's instructions via modeInstructionParent. Composes with
+ * (never replaces) backend-provided instructions: hosted settings and
+ * workflow-file inputs are both repo-owner-controlled surfaces.
+ */
+export declare function mergeReviewModeInstructions(base: Record<string, string>, inputs: {
+    reviewInstructions?: string | undefined;
+    fpFilteringInstructions?: string | undefined;
+}): Record<string, string>;

package/dist/skills/terraform-best-practices/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: terraform-best-practices
+description: Fix Terraform to best practice from a scanner concern — the minimal, correct change for a trivy/checkov/tflint/fmt/validate finding, plus the security, structure, and naming conventions a good fix must follow. Use when remediating Terraform, applying a `terraform_scan` concern, or generating new HCL that must start compliant.
+---
+
+# Terraform best-practice remediation
+
+You are fixing Terraform against a **concern** emitted by `terraform_scan` (or
+`terraform_validate`). Each concern names the producing `source`, a `rule_id`,
+the `location` (file + line), an `evidence` string (what's wrong), and often a
+`remediation_hint`. Your job is the **smallest correct change** that clears that
+concern — nothing more.
+
+## The remediation loop
+
+1. **Read the concern.** The `rule_id` tells you the class of problem; the
+   `evidence` tells you the specifics; `location.file:line` tells you where.
+2. **Open the file and understand the surrounding resource** before editing.
+   Don't fix a line in isolation — know which `resource` / `module` / `variable`
+   block it belongs to.
+3. **Apply the minimal fix** (see the catalogue below). Touch only `*.tf` /
+   `*.tfvars`. Do not reformat, reorder, or "improve" unrelated code — that
+   buries the real fix and breaks the one-concern-per-PR contract.
+4. **Re-validate** with `terraform_validate`. If it doesn't pass, your fix is
+   incomplete or introduced a new problem — fix that before opening a PR.
+5. **Confirm the concern cleared** by re-running `terraform_scan` on the branch.
+   The concern's `id` must be gone. If it isn't, say so honestly.
+
+## What a good fix looks like, by source
+
+- **`terraform-fmt:unformatted`** — run `terraform fmt` on the named file. This
+  is whitespace/alignment only; never combine it with a behavioural change in
+  the same PR.
+- **`tflint:*`** — idiomatic-HCL and provider-rule issues. Common fixes: remove
+  unused `variable`/`local`/`data` declarations; pin deprecated syntax forward;
+  add missing required provider/version constraints. Follow the rule's link.
+- **`trivy:*` / `checkov:*`** — security misconfiguration. These are the
+  high-value fixes. Apply the **secure default**, e.g.:
+  - **encryption at rest** — add the `server_side_encryption_configuration` /
+    `encryption` block (S3, RDS, EBS, etc.); prefer a CMK where the rule asks.
+  - **no public access** — set `block_public_acls`/`block_public_policy` etc. to
+    `true`; remove `acl = "public-read"`; tighten `0.0.0.0/0` ingress to the
+    real CIDR or a referenced security group.
+  - **least privilege** — replace `"*"` actions/resources in IAM policies with
+    the specific actions/ARNs actually needed.
+  - **logging / versioning** — add the access-logging, audit, or versioning
+    block the rule requires.
+- **`terraform-validate:*`** — a correctness error (bad reference, type
+  mismatch, missing required argument). Fix the actual HCL so `terraform
+  validate` passes.
+
+## Secure-default catalogue (by problem class)
+
+Copy-pasteable shapes for the highest-frequency security concerns. These target
+the **AWS provider v5+** layout (encryption / versioning / ACL / public-access
+are standalone resources, not inline `aws_s3_bucket` blocks). Adapt resource and
+attribute names to the block the concern points at — don't paste blindly.
+
+### Encryption at rest
+
+S3 — server-side encryption with a customer-managed key (preferred over `AES256`
+when the rule asks for a CMK):
+
+```hcl
+resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
+  bucket = aws_s3_bucket.this.id
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm     = "aws:kms"
+      kms_master_key_id = aws_kms_key.this.arn
+    }
+    bucket_key_enabled = true
+  }
+}
+```
+
+EBS volume / root device: `encrypted = true` (add `kms_key_id` when a CMK is
+required). RDS: `storage_encrypted = true` (+ `kms_key_id`). When `aws:kms` needs
+a key and none exists, reference an existing `aws_kms_key`/`var.*`; only add a new
+`aws_kms_key` resource if the stack genuinely has none — keep `AES256` if the rule
+is satisfied by SSE-S3 alone.
+
+### Block public access
+
+S3 — the four-flag public-access block is the canonical fix; wire it to the same
+bucket:
+
+```hcl
+resource "aws_s3_bucket_public_access_block" "this" {
+  bucket                  = aws_s3_bucket.this.id
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+```
+
+Also remove any `acl = "public-read"` (move to a private `aws_s3_bucket_acl` if an
+ACL is needed at all).
+
+### Network ingress
+
+Replace world-open ingress with the real source. Never leave `0.0.0.0/0` on admin
+ports (22/3389/database ports):
+
+```hcl
+ingress {
+  from_port       = 443
+  to_port         = 443
+  protocol        = "tcp"
+  cidr_blocks     = [var.allowed_cidr]      # or: security_groups = [aws_security_group.lb.id]
+}
+```
+
+### IAM least privilege
+
+Replace wildcard `Action`/`Resource` with the specific actions and ARNs the
+workload actually uses. If you can't determine the exact set from the surrounding
+code, this is a human decision — report it rather than guessing a narrow policy
+that breaks the stack.
+
+### Versioning & logging
+
+S3 versioning and access logging as standalone resources:
+
+```hcl
+resource "aws_s3_bucket_versioning" "this" {
+  bucket = aws_s3_bucket.this.id
+  versioning_configuration { status = "Enabled" }
+}
+```
+
+### EC2 instance metadata (IMDSv2)
+
+Require token-backed metadata to close the SSRF→credential path:
+
+```hcl
+metadata_options {
+  http_endpoint = "enabled"
+  http_tokens   = "required"
+}
+```
+
+### Deprecations & style
+
+- **Provider v4→v5 S3 split** — inline `server_side_encryption_configuration` /
+  `versioning` / `acl` / `logging` blocks on `aws_s3_bucket` are deprecated; move
+  each to its standalone resource (above). Don't bump the provider major version
+  as a side effect of a remediation — if a fix genuinely requires a newer
+  provider, report that as a blocker.
+- **`terraform-fmt:unformatted`** — run `terraform fmt` on the named file only;
+  never fold a formatting pass into a behavioural fix.
+
+## Don't over-reach
+
+- **Smallest change that clears the concern.** Add the missing block; don't
+  refactor the resource, rename it, or restructure the file around it.
+- **Don't add speculative hardening** the concern didn't ask for (extra KMS keys,
+  new modules, blanket tagging) — that's scope creep and buries the real fix.
+- **Don't widen or bump version pins** to reach a resource or attribute.
+- **One concern's blast radius only.** If the secure default would break the
+  stack or needs a human call (a real CIDR, an IAM action set, a CMK policy),
+  stop and report it instead of opening a broken or guessed PR.
+
+## Conventions every fix must honour
+
+- **Variables over hardcoded values.** Don't bake an account id, region, CIDR,
+  or ARN into a fix — reference an existing `var.*`/`local.*`, or add a typed
+  `variable` with a sensible `default` and `description` when one is genuinely
+  needed.
+- **Pin versions.** When adding a provider or module, include a version
+  constraint. Never widen an existing pin as a side effect.
+- **Approved modules first.** Call `list_modules` — if a catalogue is configured,
+  prefer the catalogue module (a registry module or a local/house module) + its
+  exact variable names over inlining a raw resource, and pin its `version`. See
+  *Using Terraform modules* below.
+- **No secrets in HCL or state.** Never introduce a literal credential. If the
+  fix needs a secret, reference a variable or a secrets data source.
+- **Idempotent, reviewable diffs.** The diff should read so a senior engineer
+  approves it without hesitation: one concern, one rationale, no churn.
+
+## Gold standards (the bar every fix is measured against)
+
+These are the non-negotiable defaults a "good" Terraform change embodies. A fix
+should never *move away* from any of these, and should move *toward* them when
+the concern is adjacent:
+
+- **Encrypt everything, at rest and in transit.** Storage encrypted (CMK where
+  the data is sensitive); TLS-only endpoints; no plaintext in state.
+- **Private by default.** No `0.0.0.0/0` to admin/database ports; public access
+  blocked unless the resource's whole purpose is to be public (and then scoped).
+- **Least privilege.** No `"*"` IAM actions/resources; scope to what the workload
+  uses. Prefer a referenced role/policy over an inline wildcard.
+- **Pinned + reproducible.** `required_version` and every `required_providers` /
+  module `version` constrained (`~>`); no floating `latest`.
+- **Parameterised, not hardcoded** (see below).
+- **Tagged + named consistently.** Match the repo's existing tag keys and naming
+  scheme; don't invent a new convention.
+- **Observable.** Logging / versioning / audit trails enabled where the provider
+  supports them and the concern is about data durability or traceability.
+- **Idempotent + deterministic.** No `timestamp()`/`uuid()`/unkeyed `random_*`
+  driving a value that lands in state — it produces a perpetual diff.
+
+When in doubt, the secure/idiomatic default from the catalogue above IS the gold
+standard. Don't gold-plate beyond the concern, but never regress one of these.
+
+## Parameterize, don't hardcode (§4.13)
+
+A value that varies by environment, account, or deployment must be a `variable`
+or `local`, never a literal baked into a resource:
+
+- **Reuse first.** If the repo already exposes `var.region` / `local.tags` /
+  `var.vpc_cidr`, reference it — don't introduce a parallel one.
+- **Introduce a typed variable** when none fits: give it a `type`, a
+  `description`, and a safe `default` only when a default is genuinely sane
+  (secrets and account-specific ids get NO default). Match the repo's existing
+  file layout — add to `variables.tf` if the repo separates them, otherwise keep
+  it next to the resource as the repo does.
+- **Derive with `locals`.** Computed/repeated values (a name prefix, a merged tag
+  map) belong in `locals`, referenced everywhere — not copy-pasted.
+- **Never inline a secret, account id, ARN, or CIDR.** A "fix" that pastes a
+  literal credential is itself a finding (and the secret-scan guardrail will
+  block the push). Reference a variable or a secrets data source.
+
+## Using Terraform modules (registry, private git libraries, your own)
+
+Prefer a well-formed module over a pile of raw resources when one cleanly fits —
+it carries the secure defaults for you. **Always call `list_modules` first**; it
+returns three things: the operator's `module_catalogue`, the
+`discovered_house_modules` (local modules already used in THIS repo), and a note.
+
+Three source kinds you'll encounter, each pinned differently:
+
+- **Public registry module** — `terraform-aws-modules/vpc/aws`. Pin with a
+  `version = "~> 5.0"` argument. The big public collections
+  ([terraform-aws-modules](https://registry.terraform.io/namespaces/terraform-aws-modules):
+  `vpc`, `s3-bucket`, `rds`, `eks`, …) are the default when nothing is configured.
+  A registry submodule is `…/aws//modules/log-group`.
+- **Private git module library** — e.g.
+  `git::https://github.com/acme/tf-modules.git//aws/s3?ref=s3-v0.1.2`. The
+  `//aws/s3` selects the module within the repo and **`?ref=s3-v0.1.2` IS the
+  version pin** (git modules have no `version` argument). Keep the exact `ref`;
+  never float it. Many orgs (e.g. UKHSA's `data-integration-terraform-modules`)
+  ship a whole library this way, tagged per-module.
+- **House module** — one of the repo's own `modules/<name>` dirs. `list_modules`
+  surfaces these under `discovered_house_modules` with their caller files — reuse
+  the existing one with its **real variable names** (read its `variables.tf`)
+  rather than re-implementing it.
+
+Rules: use the module's **exact variable names**, set the secure-relevant inputs
+the concern is about, and keep the version **pinned**. Don't introduce a module
+mid-remediation just to "improve" things — using a module is right when
+*generating* new infra or when the fix is genuinely a module swap; for a one-line
+security fix on an existing raw resource, fix the resource in place.
+
+When the **`terraform` MCP server** is registered (the `terraform_mcp` input),
+prefer querying it for the current module version and provider argument shapes
+over recalling them from memory — registry knowledge moves faster than any
+training data, and a fix written against a remembered-but-renamed argument
+breaks `plan`. Without it, `terraform_version_currency` (versions) and
+`terraform_provider_schema` (installed-provider arguments) are the fallbacks.
+
+### Authoring a reusable module (standard layout)
+
+When you GENERATE a reusable module, follow the conventional layout real module
+libraries use so it's drop-in familiar:
+
+- `main.tf` (resources), `variables.tf` (every input typed, with a `description`
+  and a `validation` block where it helps), `outputs.tf`, `versions.tf` /
+  `providers.tf` (`required_version` + `required_providers` pinned), `README.md`
+  (usage + inputs/outputs), and a `CHANGELOG.md` if the repo versions modules.
+- Do **not** generate `examples/` fixtures. Document usage in the module's
+  `README.md` instead; test coverage comes from the opt-in terratest scaffold
+  (see below), which plans the module directly.
+
+### Module-source-aware fixes (§4.14)
+
+Before fixing a concern, call `terraform_module_graph` to see where the file
+lives in the module call-graph:
+
+- **Concern inside a LOCAL module dir** (listed in `local_module_dirs`): fix it
+  **once at the module source**. The fix propagates to every caller — do not
+  patch each call site. Note the callers in the PR body so a reviewer sees the
+  blast radius.
+- **Concern that would require editing a REGISTRY / git / remote module**: that
+  source lives outside this repo — you **cannot** fix it here. Do **not** vendor
+  the module or fork it inline. Instead report it (open an issue / PR comment)
+  naming the upstream module + version and the concern, so a human routes it.
+
+### Modularization as remediation (M2)
+
+`module_extraction_candidates` finds clusters of raw resources that should be a
+module call, each matched against the repo's house modules (real resource-type
+signature + `required_variables`) and the operator's `module_catalogue`. Turn a
+candidate into a refactor PR under this contract:
+
+- **One PR per cluster**, branch `remediate/modularize-<cluster file/prefix>` —
+  never mix two clusters or a behavioural fix into a modularization PR.
+- Replace the cluster's raw resources with ONE `module` block calling the
+  candidate (pin the version for registry sources; wire the module's REAL
+  variable names from `required_variables` / `terraform_module_interface`).
+- **Preserve state with `moved {}` blocks** — one per resource, mapping the old
+  address to its new `module.<name>.` address:
+
+  ```hcl
+  moved {
+    from = aws_s3_bucket.logs
+    to   = module.logging.aws_s3_bucket.this
+  }
+  ```
+
+- **The gate:** the PR may proceed only when `terraform_validate` passes AND
+  `terraform_plan` reports `refactor_safe: true` (a pure-move plan — zero
+  add/change/destroy). Anything else means a moved block is wrong or the module
+  diverges from the raw resources — fix that or report it; never accept
+  resource churn as "the refactor".
+- A required variable you can't derive from the existing attributes is a
+  **PR question for the reviewer**, never a guessed value.
+
+### Version currency (provider + module upgrades, M3)
+
+`terraform_version_currency` reports which pinned providers and registry modules
+trail the registry's latest stable version, and which registry modules are
+unpinned. Turn its rows into upgrade PRs under this contract:
+
+- **One `chore(deps)` PR per upgrade group** — never mix a version bump with a
+  behavioural fix; a bump PR must read as "only the constraint changed".
+- **Minor/patch bumps** (`outdated` with `majors_behind: 0`) may proceed
+  autonomously: update the `version` constraint to admit `newest_satisfying` →
+  `latest`, then prove it with `terraform_validate` (and `terraform_plan` when
+  credentials exist).
+- **Major bumps** (`majors_behind > 0`) mean the provider/module interface may
+  have changed — apply only with the `needs-human` label, and consult
+  `terraform_module_interface` / `terraform_provider_schema` for what moved.
+- **Unpinned registry modules**: pin to the reported `latest` (`version = "~> X.Y"`),
+  one PR for all unpinned modules in a file group — pinning is low-risk and sweeps well.
+- An upgrade whose `terraform_plan` shows **destructive changes is never auto** —
+  escalate with the plan excerpt in the PR body.
+
+## Tests for modules (§28)
+
+Terramend does **not** create or edit `examples/` fixtures — leave any the repo
+already ships untouched. Module test coverage is **opt-in** via the `terratest`
+input:
+
+- **Terratest (opt-in).** When the `terratest` input is enabled, call
+  `scaffold_terratest` (module name + dir) to generate a plan-only Go
+  [Terratest](https://terratest.gruntwork.io/) smoke test (`test/<name>_test.go`)
+  **and** a Terraform-native `*.tftest.hcl` in the module's own `tests/` dir.
+  Both plan the **module directly** (no example fixture). Write the returned files
+  (the input also widens `allowed_paths` to permit them). If the repo already has
+  a Terratest suite, update its options/assertions to match the new interface
+  instead.
+
+In all cases: Terramend **never runs** the tests — it holds no cloud credentials,
+and Terratest needs Go + a real `apply`. It keeps the test source consistent with
+the module and flags in the PR that the suite should be run in the user's
+pipeline. **Never weaken an assertion or delete a test to go green.**
+
+## Hard rules
+
+- Only modify `*.tf` / `*.tfvars` (and, when `allowed_paths` permits — i.e. the
+  `terratest` input is on — that module's test files). Never touch CI, application
+  code, or unrelated config in a remediation PR.
+- One concern per PR. If you notice other issues, leave them for their own runs.
+- Never auto-merge. The PR is for a human to review.
+- If you cannot fix a concern cleanly (it needs a human decision, or the secure
+  default would break the stack), do **not** open a broken PR — report it
+  instead with what's blocking.