infraweaver 0.1.0

package/dist/modes/prFormats.d.ts

@@ -0,0 +1,3 @@
+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 infraweaver 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<!--\nInfraweaver 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 infraweaver 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 infraweaver 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 infraweaver 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` 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. (The `## Validation` list and the final status banner come from `terraform_verify_remediation`, which runs after the PR opens \u2014 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.)\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 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`\n\nBuilt ONLY from `terraform_verify_remediation`'s result \u2014 this is the proof, not a self-report. One \u2705 line per id in `resolved`, then any still-open id honestly:\n\n```\n## Validation\n\n- \u2705 \\`trivy:AVD-AWS-0088\\` resolved\n- \u2705 \\`checkov:CKV_AWS_19\\` resolved\n- \u26A0\uFE0F still open: \\`tflint:...\\` \u2014 {why it couldn't be cleared}\n```\n\n**Resolved XOR still-open \u2014 never both.** Each concern appears on exactly one line: an `id` in the tool's `resolved` set gets a `\u2705 \u2026 resolved` line (the green check means cleared); an `id` in `remaining` gets a `\u26A0\uFE0F still open: \u2026` line. NEVER put a \u2705 on an unresolved concern (no `\u2705 \u2026 re-flagged`, no `\u2705 \u2026 still open`) \u2014 that is a false attestation and the single worst thing this body can do. A concern earns its \u2705 only if the tool returned its id in `resolved`; if it's in `remaining`, it is still-open, full stop.\n\nIf `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) \u2014 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.\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 const REFACTOR_PR_FORMAT = "### Refactor PR format\n\nBuild 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.\n\n#### 1. Status banner (first line)\n\nOne GitHub alert blockquote, picked from the proof:\n\n- `> [!NOTE]` \u2014 **equivalence proven** (b.1/b.2/b.3): `terraform_equivalence_check` returned `equivalent: true`. One sentence: what was modularised.\n- `> [!CAUTION]` \u2014 **proposed \u2014 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.\n- `> [!WARNING]` \u2014 a caveat (a required module variable left unset, an environment twin needing the same change, or a `needs-fork` control).\n\n#### 2. Title line\n\nA single bolded sentence naming the file + the module: `**Modularised \\`main.tf\\` \u2014 extracted 4 logging resources into \\`module.logging\\`.**`\n\n#### 3. `## What changed`\n\nThe 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).\n\nOptional `Documentation` bullet \u2014 present ONLY when `terraform_module_docs` ran this run: one line naming the README it wrote/refreshed (e.g. `- **Documentation** \u2014 regenerated \\`modules/logging/README.md\\` from the module interface + equivalence verdict`). Omit the bullet entirely when the tool didn't run.\n\n#### 4a. `## Equivalence proof` (b.1 / b.2 / b.3 \u2014 built ONLY from `terraform_equivalence_check`)\n\nThis is the proof, not a self-report. One \u2705 line per cleared check:\n\n```\n- \u2705 Resource set preserved (N resources, 0 added / 0 removed)\n- \u2705 Arguments identical\n- \u2705 Moved-block coverage N/N (0 uncovered)\n- \u2705 terraform validate\n- \u2705 terraform fmt (no diff)\n```\n\nAdd `- \u2705 Plan: refactor_safe (pure move, +0 ~0 -0)` when `terraform_plan` ran. List the moves (`<old> \u2192 <new>`) in a collapsed `<details>`. If ANY check failed, the refactor is not equivalent \u2014 do not open this PR as an equivalence claim (the push guardrail blocks it anyway); fix it or fall to the b.4 path.\n\n#### 4b. `## Proposed change \u2014 unproven` (b.4 default \u2014 adopting a third-party module, no read creds)\n\nLead with the proposed-unproven banner (\u00A71), then:\n\n- **Behaviour change** \u2014 what the module adds/changes vs the inlined resources (a KMS key, an IAM role, different defaults). State plainly that this ALTERS behaviour.\n- **Module-sourced findings** \u2014 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).\n- **Provenance** \u2014 the module `source` + the **exact pinned version**.\n- It is asserted as **nothing more than a proposal** \u2014 \"review the plan yourself.\"\n\nWhen read-only state IS supplied (opt-in), REPLACE this section with **`## Reviewed plan delta`**: the `terraform_plan` output (collapsed), reviewed \u2014 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.\n\n#### 5. Composition (when this PR also carries a remediation fix)\n\nDefault is one combined PR. Keep the two proofs as **distinct, separately-readable sections** \u2014 the \u2717\u2192\u2713 `## Validation` for the fix and the `## Equivalence proof` for the refactor \u2014 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).\n\n#### Body-wide rules\n\n- **Evidence-built, never self-reported.** Omit a section whose tool didn't run.\n- **Never claim equivalence for a b.4 change** \u2014 it alters behaviour; the proposed-unproven marker must never read as a proof.\n- **Blank line between block-level elements**; backtick-wrap identifiers; no raw `+N/-M` stats or `---` rules.\n- **Never auto-merge** \u2014 always leave the PR for human review.";

package/dist/modes/refactor.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function refactorMode(t: ToolRef): Mode;

package/dist/modes/refresh-remediation.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function refreshRemediationMode(t: ToolRef): Mode;

package/dist/modes/remediate-and-refactor.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function remediateAndRefactorMode(t: ToolRef): Mode;

package/dist/modes/remediate.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function remediateMode(t: ToolRef): Mode;

package/dist/modes/resolve-conflicts.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function resolveConflictsMode(t: ToolRef): Mode;

package/dist/modes/review.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function reviewMode(t: ToolRef): Mode;

package/dist/modes/summarize-pr.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function summarizePrMode(t: ToolRef): Mode;

package/dist/modes/task.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function taskMode(t: ToolRef): Mode;

package/dist/modes/terraform-code-review.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function terraformCodeReviewMode(t: ToolRef): Mode;

package/dist/modes/types.d.ts

@@ -0,0 +1,9 @@
+export interface Mode {
+    name: string;
+    description: string;
+    prompt?: string | undefined;
+    nonCommitting?: boolean | undefined;
+}
+/** binds a bare MCP tool name to its agent-specific reference (per-run, via
+ * formatMcpToolRef) — the single closure each mode factory needs from computeModes. */
+export type ToolRef = (toolName: string) => string;

package/dist/modes/update-dependencies.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, ToolRef } from "./types.ts";
+export declare function updateDependenciesMode(t: ToolRef): Mode;

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,107 @@
+/**
+ * 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 (src/modes/) — 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. Deliberate
+ * divergences from upstream:
+ *   - CCSR judges findings via sequential direct API calls; we dispatch
+ *     parallel read-only loupe subagents (machine-gated by the subagent
+ *     deny set, derived from each MCP tool's `mutates` flag) 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). Infraweaver 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). Verification mirrors discovery dispatch: each subagent tests a
+ * single falsifiable claim, so the count follows the findings — one dispatch
+ * per candidate, however many that is (including exactly one).
+ */
+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 `loupe` verification subagent \u2014 ALL of them in a single assistant turn as parallel Task tool_use blocks. One candidate = one subagent \u2014 verification mirrors discovery dispatch: each subagent tests a single falsifiable claim, so the count follows the findings (dispatch one, or several in parallel, as the candidates demand). 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.";
+/**
+ * IaC-specific refute lens for a CLOUD-MISCONFIG finding (public exposure,
+ * missing encryption, over-broad IAM, an open security group). Distinct from the
+ * generic code-review refute charge in {@link FINDING_VERIFICATION_PASS}: a
+ * Terraform misconfig is most often a FALSE POSITIVE because the control is
+ * satisfied SOMEWHERE THE SCANNER DIDN'T LOOK — a separate hardening resource, a
+ * call-site override, a disabled resource, a secure default. A reviewer applying
+ * the generic "read the code" charge can miss these IaC-specific gates. Appended
+ * to the verification charge when the finding under test is a cloud-misconfig.
+ */
+export declare const TERRAFORM_SECURITY_REFUTE_LENS = "**Terraform-security refute lens (cloud-misconfig findings).** Before confirming a cloud-misconfig finding (public exposure, missing encryption, over-broad IAM, open ingress), rule out the IaC-specific false-positive patterns \u2014 the control is frequently satisfied somewhere the per-resource scanner didn't look. The finding is REFUTED if any of these holds:\n\n   - **Satisfied by a separate hardening resource.** The control lives in a sibling resource the flagged block doesn't inline \u2014 `aws_s3_bucket_public_access_block` / `aws_s3_bucket_server_side_encryption_configuration` / `aws_s3_bucket_versioning` for an S3 bucket, a standalone `aws_security_group_rule` instead of inline `ingress`, a `aws_db_instance.storage_encrypted` set in a different file. Search the module for a resource that targets the SAME object before confirming.\n   - **Not actually deployed.** The resource is gated by `count = 0` / an empty `for_each` / a `var.enabled` that defaults false, or it lives under `examples/`, a test fixture (`*.tftest.hcl`), or a `mock`/`fixtures` path \u2014 so it never reaches production.\n   - **Overridden at the call site.** The flagged value is a module's INTERNAL default that every caller overrides via an input; or it is a `variable` whose `default` is the SECURE value (an insecure literal would be the bug \u2014 a secure-defaulted variable is not).\n   - **Already secure by provider default.** The pinned provider major makes the control the default (e.g. newer AWS provider majors encrypt by default), so the absent argument is not an exposure.\n   - **A data source, not a managed resource.** A `data` block reads existing infra and changes nothing \u2014 a misconfig \"finding\" on it has no apply-time effect.\n\n   Confirm the finding only when none of the above applies AND the exposure is reachable in the deployed resource set. When the gate is plausible but you can't locate it, return `uncertain` (not `confirmed`) and say which gate you couldn't rule out. Bias toward `refuted` for a theoretical exposure with no reachable path.";
+/**
+ * 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 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>;
+/**
+ * Heading under which `remediation_instructions` (org-specific remediation
+ * policy) is appended to the Remediate / RemediateAndRefactor mode
+ * instructions. The Remediate mode prompt (src/modes/) names this heading when
+ * telling the agent an org addendum may follow its checklist — the two strings
+ * are a contract; change them together.
+ */
+export declare const REMEDIATION_ADDENDUM_HEADING = "### Remediation policy \u2014 org addendum";
+/**
+ * Heading under which `refactor_instructions` is appended to the Refactor mode
+ * instructions (and RemediateAndRefactor's refactor phase). Same contract
+ * discipline as {@link REMEDIATION_ADDENDUM_HEADING}: the Refactor prompt in
+ * src/modes/ names this heading; change them together.
+ */
+export declare const REFACTOR_ADDENDUM_HEADING = "### Refactor policy \u2014 org addendum";
+/**
+ * Merge the composable `remediation_instructions` / `refactor_instructions`
+ * inputs into the per-mode user instructions, following
+ * {@link mergeReviewModeInstructions} exactly: each addendum is APPENDED under
+ * a fixed, exported heading; the engine-owned mode prompt is untouched and the
+ * vetted-prompt boundary in resolveEffectivePrompt is not involved at all.
+ * `remediation_instructions` lands on Remediate + RemediateAndRefactor;
+ * `refactor_instructions` lands on Refactor + RemediateAndRefactor (the
+ * combined mode runs both phases, so it receives both addenda — the analog of
+ * IncrementalReview inheriting Review, expressed by direct composition because
+ * a mode can only have one instruction parent). Returns `base` unchanged when
+ * both inputs are empty. Trust basis is the same as the review inputs: hosted
+ * settings and workflow-file inputs are both repo-owner-controlled surfaces.
+ */
+export declare function mergeRemediationModeInstructions(base: Record<string, string>, inputs: {
+    remediationInstructions?: string | undefined;
+    refactorInstructions?: string | undefined;
+}): Record<string, string>;