terramend 0.2.0 → 0.2.1

package/src/modes.ts

@@ -185,7 +185,7 @@ Inline comments use the same severity framing as body \`### \` sections, scaled
 // and a reviewer can scan it top-to-bottom in seconds.
 export const REMEDIATION_PR_FORMAT = `### Remediation PR format
 
-**Minimum (ALWAYS include, even under tight budget):** a one-paragraph plain-English summary of *what was wrong and what you changed*, then a \`## What changed\` list with one *Was / Changed / Safe because* note per concern, then the \`## Validation (✗ → ✓)\` list. If you produce nothing else, produce these three — a PR a human can't understand from its body alone has failed its job. Everything below enriches this minimum; it does not replace it.
+**Minimum (ALWAYS include, even under tight budget):** a one-paragraph plain-English summary of *what was wrong and what you changed*, then a \`## What changed\` list with one *Was / Changed / Safe because* note per concern, then the \`## Validation\` list. If you produce nothing else, produce these three — a PR a human can't understand from its body alone has failed its job. Everything below enriches this minimum; it does not replace it.
 
 Build the PR body in this EXACT order. Every line is backed by a tool result — never write a status you didn't get from a tool. Omit a whole section only when its tool didn't run (e.g. no plan without cloud creds); never fabricate it. Keep a blank line between every block-level element (GitHub needs it to render).
 
@@ -223,19 +223,21 @@ One \`### \` subsection per resolved concern (or one per rule for a by-rule grou
 
 Lead each heading with a severity emoji (🚨 critical · ⚠️ high · 🔒 security · ℹ️ low/info). Backtick-wrap every identifier. No raw diff dumps — the Files tab shows the diff.
 
-#### 4. \`## Validation (✗ → ✓)\`
+#### 4. \`## Validation\`
 
-Built ONLY from \`terraform_verify_remediation\`'s result — this is the proof, not a self-report. One line per id in \`resolved\`, then any still-open id honestly:
+Built ONLY from \`terraform_verify_remediation\`'s result — this is the proof, not a self-report. One ✅ line per id in \`resolved\`, then any still-open id honestly:
 
 \`\`\`
-## Validation (✗ → ✓)
+## Validation
 
-- ✗ → ✓ \\\`trivy:AVD-AWS-0088\\\` resolved
-- ✗ → ✓ \\\`checkov:CKV_AWS_19\\\` resolved
+- ✅ \\\`trivy:AVD-AWS-0088\\\` resolved
+- ✅ \\\`checkov:CKV_AWS_19\\\` resolved
 - ⚠️ still open: \\\`tflint:...\\\` — {why it couldn't be cleared}
 \`\`\`
 
-If \`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 ✓ unless the tool returned it in \`resolved\`.
+**Resolved XOR still-open — never both.** Each concern appears on exactly one line: an \`id\` in the tool's \`resolved\` set gets a \`✅ … resolved\` line (the green check means cleared); an \`id\` in \`remaining\` gets a \`⚠️ still open: …\` line. NEVER put a ✅ on an unresolved concern (no \`✅ … re-flagged\`, no \`✅ … still open\`) — that is a false attestation and the single worst thing this body can do. A concern earns its ✅ only if the tool returned its id in \`resolved\`; if it's in \`remaining\`, it is still-open, full stop.
+
+If \`has_regressions\` is true, add a \`> [!CAUTION]\` **Regression** callout listing each id in the tool's \`regressions\` set BEFORE this list, and ensure the \`needs-human\` label is set. \`regressions\` are concerns the fix genuinely INTRODUCED (a new \`rule\`+\`file\` not present before) — they are computed line-independently, so a pre-existing concern that merely moved lines is NOT a regression; do not relabel a \`remaining\` concern as a regression.
 
 #### 5. \`<details><summary>Plan</summary>\` (when \`terraform_plan\` ran)
 
@@ -635,6 +637,43 @@ ${PR_SUMMARY_FORMAT}`,
 ${REVIEW_FINDING_PRECEDENTS}
 
 ${PR_SUMMARY_FORMAT}`,
+    },
+    {
+      name: "SummarizePr",
+      description:
+        "Summarize a pull request's changes in a single structured comment — what it does, the key changes, and any areas worth a closer look. Does NOT review, approve, or change code (use Review for a verdict).",
+      prompt: `### Checklist
+
+This mode posts ONE plain-English summary of what a PR does — an orientation aid, not a verdict. Do NOT approve, request changes, leave inline review comments, or modify any code. If a real review is wanted, that's the Review mode.
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **checkout**: call \`${t("checkout_pr")}\` — this returns PR metadata and a \`diffPath\`. Read the diff TOC so you understand the scope.
+
+3. **Terraform anchor (when relevant)**: call \`${t("terraform_change_summary")}\` — it returns the DETERMINISTIC Terraform block changes (resource/module/data/variable/output addresses ADDED and REMOVED, plus the Terraform files touched) vs the base. It degrades green (\`ok: false\`) when git can't resolve the base — run \`${t("git_fetch")}\` on the base ref first and retry — or when the PR has no Terraform changes (then it's a general summary). Use its counts as the factual backbone of the Terraform part of your summary instead of counting by eye.
+
+4. **read for intent**: read the \`diffPath\` (and related files as needed) to understand WHAT the PR does and WHY — not just the mechanics. Pull as much context as you need; you are the synthesizer.
+
+5. **post the summary**: call \`${t("create_issue_comment")}\` ONCE on the PR with a structured summary in this shape (omit a section when it has nothing):
+
+   \`\`\`
+   ## Summary
+   {1–2 sentences: what this PR does and why, in plain English.}
+
+   ### Key changes
+   - **{short title}** — {one sentence}; backtick-wrap files/identifiers you name.
+   - ...
+
+   ### Terraform changes
+   {only when terraform_change_summary returned data — e.g. "Adds \\\`module.vpc\\\` and \\\`aws_s3_bucket.logs\\\`; removes \\\`aws_launch_configuration.web\\\`; edits 3 files." Use its real addresses/counts.}
+
+   ### Worth a closer look (optional)
+   - {non-blocking observations a reviewer might want to focus on — risk areas, sequencing, things the diff implies but doesn't address. Phrase as orientation, not findings — this is not a review.}
+   \`\`\`
+
+   Keep it scannable: lead with intent, alternate prose with structure, backtick-wrap identifiers, no raw diff dumps, no \`+N/-M\` stats. NEVER fabricate a change — every claim must be in the diff (the Terraform counts come from the tool).
+
+6. **finalize**: call \`${t("report_progress")}\` with a one-line note that the summary was posted (or the exact error if the comment failed). Do NOT call \`${t("create_pull_request_review")}\` — this mode summarizes, it does not review.`,
     },
     {
       name: "Plan",
@@ -704,11 +743,32 @@ ${PR_SUMMARY_FORMAT}`,
    - \`git add . && git commit -m "resolve merge conflicts"\`
    - confirm a clean working tree, then push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*)
    - Call \`${t("report_progress")}\` with a summary of what was resolved (or the exact push error if push failed)`,
+    },
+    {
+      name: "Assess",
+      description:
+        "Read-only Terraform best-practice ASSESSMENT: scan with the deterministic check tools, map findings to compliance controls, and report the posture (clean / advisory / action-required) — without modifying any Terraform or opening a PR.",
+      prompt: `### Checklist
+
+This mode is **read-only** — the Assess half of Terramend's one-engine-two-modes design. It reports posture; it never fixes. Do NOT edit Terraform, commit, push, or open a PR/issue in this mode. If the findings warrant a fix, say so and recommend re-running in \`remediate\` mode.
+
+1. **task list**: create your task list for this run as your first action.
+
+2. **assess**: call \`${t("terraform_assess")}\`. It runs the scanners and returns a deterministic \`scorecard\` (overall \`posture\`, \`by_severity\` counts, \`top_risks\`, and an indicative compliance-crosswalk summary) plus a ready-to-post \`markdown\` report. This is the core deliverable — built from tool results, not your own judgement.
+
+3. **optional lenses** (fold each into the report only when it actually ran):
+   - \`${t("infracost_diff")}\` — current monthly cost (auto-skips without \`INFRACOST_API_KEY\`/the CLI).
+   - \`${t("terraform_version_currency")}\` — provider/module pins that are outdated or unpinned.
+   - \`${t("terraform_emit_sarif")}\` — when the workflow has a SARIF upload step, emit \`terramend.sarif\` so every concern also lands in the repo's Security tab (read-only, complementary).
+
+4. **report**: call \`${t("report_progress")}\` once with the assessment. Use the \`markdown\` from \`${t("terraform_assess")}\` as the base (it carries the posture banner, severity counts, top risks, and the indicative-crosswalk note verbatim — do not soften or inflate it), then append one-line **Cost** / **Version currency** notes if those lenses ran. If \`${t("set_output")}\` is available (standalone runs), also emit the structured result (\`posture\`, \`total\`, \`by_severity\`, the touched \`frameworks\`) so a CI step can gate on \`posture\`.
+
+5. **guardrails**: never modify \`*.tf\`/\`*.tfvars\`, never push, never open a PR or issue. The assessment is the only deliverable.`,
     },
     {
       name: "Remediate",
       description:
-        "Bring a repository's Terraform up to best practice: scan with the deterministic check tools, then open one scoped, reviewable PR per concern that fixes it and proves it fixed (✗→✓).",
+        "Bring a repository's Terraform up to best practice: scan with the deterministic check tools, then open one scoped, reviewable PR per concern that fixes it and proves each fix by re-scanning (✅).",
       prompt: `### Checklist
 
 1. **task list**: create your task list for this run as your first action.
@@ -729,6 +789,8 @@ ${PR_SUMMARY_FORMAT}`,
 
    **Comment command (§3.12)**: when this run was triggered by a \`@terramend fix …\` comment, the triggering body is in your prompt — honour the requested scope INSTEAD of "highest-severity group": \`fix #<concern-id>\` → act only on the group containing that concern id; \`fix all <severity>-severity\` → set the scan \`severity_threshold\` to that level and act on those groups (up to \`max_prs\`); \`fix <file>.tf\` → act on that file's group; \`fix all\` → act on the highest-severity groups up to \`max_prs\`. If the comment isn't a recognised fix command, fall back to the default scope. A **strategy suffix** — \`fix #<concern-id> with strategy B\` (or a bare \`strategy B\` reply on a proposal thread) — additionally tells you **which** fix to apply: see §26 in step 4.
 
+   **Bulk remediation (§37 — \`fix rule <rule-id>\` / \`fix all rule <rule-id>\`)**: a request to fix ONE scanner rule everywhere it fires (e.g. \`@terramend fix rule CKV_AWS_23\` — "add a description to every security group", or \`fix rule terraform_required_version\`). Re-scan with \`group_by: "rule"\` (§3.11) so that rule becomes ONE group spanning every file, then act on the single group whose \`rule_ids\` include \`<rule-id>\` — apply the SAME minimal fix at every site in its \`files\` and open ONE coherent PR (not one per file). This is the sweep path; still honour \`max_prs\` and never batch a \`needs-human\` group. Cite each fixed site in the PR body.
+
 4. **for the chosen group**:
    - **base branch**: this run's base branch is resolved deterministically — \`${t("create_pull_request")}\` targets the \`base_branch\` input if set, else the repository's default branch (\`main\`, or \`master\`). You do not choose it; just **omit** the \`base\` argument when opening the PR (below) and it is filled in.
    - **idempotency**: the remediation branch is \`remediate/<group-id>\`. Before doing anything, check whether that branch or an open PR for it already exists (\`${t("git")}\` / \`${t("get_pull_request")}\`). If one exists, update it rather than opening a duplicate.
@@ -736,6 +798,10 @@ ${PR_SUMMARY_FORMAT}`,
    - **honest refusal (§29 — decide BEFORE fixing)**: if the group's concerns appear in the scan's \`refusal_candidates\` (the fix needs a human decision — narrowing an IAM wildcard, a KMS key policy, a real ingress CIDR), do **not** guess a fix that could break the stack. Instead open a structured issue (\`${t("create_issue")}\`) describing the concern, why it isn't auto-fixed, and what a human should do, and skip the PR for that group. A proven fix or an honest refusal — never a guessed, unverifiable PR.
    - **propose, then let me steer (§26 — when there's no single right fix)**: distinct from §29 (which refuses a fix a human must *decide*), §26 is for a finding with **2–3 genuinely distinct, defensible fixes** that differ in trade-offs, not correctness (e.g. encrypt with an AWS-managed key **vs** a customer-managed KMS key; a narrow security-group rule **vs** a prefix list **vs** a VPC endpoint). When such a fork exists **and the triggering comment did not already select a strategy**, do **not** silently pick for the reviewer: via \`${t("create_issue_comment")}\` post one short comment listing the options as **A / B / C** — each a single line (what it does + its trade-off) — and ask the reviewer to reply \`@terramend fix #<concern-id> with strategy <A|B|C>\`. Then **skip the PR for this group** this run and note it in your final report (it resumes when the reviewer replies). When the comment **did** select one (\`fix #<id> with strategy B\`, or a bare \`strategy B\` reply on the proposal thread), apply **exactly** that strategy — don't second-guess it. Reserve this for real forks in the road; a fix with one obvious correct answer just gets made.
    - **fix**: edit the group's file(s), using your native file tools. For a by-file group that's the single \`file\`; for a **by-rule group (§3.11)** it's every entry in \`files\` (fix the one rule everywhere it fires). Resolve **every** concern in the group — when the scan's \`co_located\` shows several scanners flagged the same \`file:line\` (§30), they're one underlying defect: write ONE canonical fix and one explanation, not separate edits. **Only touch \`*.tf\` / \`*.tfvars\` files.** Make the smallest changes that clear the concerns — do NOT reformat or refactor unrelated code (see *SYSTEM* surgical-change rules). **Module-source awareness (§4.14):** call \`${t("terraform_module_graph")}\` first — if the concern's file is inside a \`local_module_dir\`, fix it ONCE at the module source (it propagates to all callers; note them in the PR); if the fix would require editing a registry/git/remote module, you can't fix it here — report it (open an issue naming the upstream module + version) instead. **Approved modules (§4.14):** call \`${t("list_modules")}\` and prefer a catalogue module (registry or house, pinned) when the fix is genuinely a module swap — but for a one-line fix on an existing raw resource, fix it in place. **Provider-major awareness (§4.15):** before introducing an argument or block, check \`terraform_validate\`'s \`providers\` list for the pinned \`major\` — argument names and valid blocks differ across majors. After the dir is init-ed (validate/plan ran), you can **verify an argument exists** for the installed provider with \`${t("terraform_provider_schema")}\` (pass the resource type + the arg names you added; it returns any \`unknown_args\` that would break \`plan\`). **Reusing a module?** call \`${t("terraform_module_interface")}\` on its dir to get its real \`variable\` names + which are required, so the \`module\` block you write is correct.
+   - **fix QUALITY — a real fix, not a scanner-silencer (enterprise bar)**: the goal is infrastructure that is *actually* safer, not Terraform that merely stops tripping the scanner. Three rules:
+     - **Secure defaults, never a hidden-insecure one.** When you parameterise a hardcoded value (§4.13), the new \`variable\`'s \`default\` must be the SECURE choice, or have **no \`default\`** (forcing the operator to set it). NEVER preserve the insecure value as the default — e.g. replacing \`cidr_blocks = ["0.0.0.0/0"]\` with \`var.allowed_cidr_blocks\` *defaulting to \`["0.0.0.0/0"]\`* is not a fix: the deployed behaviour is identical and you've just moved the problem somewhere a scanner may not see it. If the secure value genuinely needs a human decision, this is an honest-refusal (§29) / propose-then-steer (§26) case, not a default-to-insecure.
+     - **Optional-input resources must be conditional.** If a fix adds a resource or block that only works when an OPTIONAL input is set (e.g. an HTTPS listener that needs \`var.ssl_certificate_arn\`, which defaults to \`null\`), gate it with \`count\`/\`for_each\` or a \`dynamic\` block so it is NOT emitted — and cannot break \`plan\`/\`apply\` — when the input is unset. Do not write an always-present resource that references a null/empty value, and never claim in the PR that something is "only active when set" unless the HCL actually makes it conditional. Remember \`${t("terraform_validate")}\` can pass on HCL that still fails at \`plan\`/\`apply\` — your claim of conditionality must be in the code, not just the prose.
+     - **Modernise, don't perpetuate (§4.15).** Call \`${t("terraform_version_currency")}\` and, when you must add a \`required_providers\`/\`required_version\` block, pin a CURRENT supported major, not an ancient one chosen only to match legacy code. Flag (in the PR body, as a follow-up — not necessarily fixed in this scoped PR) deprecated patterns the scanners don't encode: the archived \`hashicorp/template\` provider + \`data "template_file"\` (modern: the built-in \`templatefile()\` function), \`aws_launch_configuration\` (→ \`aws_launch_template\`), and any provider/module pin that is several majors behind. A best-practice fix should not entrench an EOL provider.
    - **keep the module's tests/examples consistent (§28 — only when you fixed a reusable module)**: if the file(s) you changed live inside a \`local_module_dir\` (from \`${t("terraform_module_graph")}\`) AND your fix changed the module's public interface (added/removed/renamed a \`variable\`, tightened a type), call \`${t("terraform_module_tests")}\` with that module dir. It returns the module's existing \`examples/\` fixtures + \`terraform test\` (\`*.tftest.hcl\`) / Go Terratest files and the \`drift\` per asset — \`missing_required\` (a variable the asset must now set) and \`unknown_set\` (a variable the asset references that no longer exists). Update **exactly** the drifting assets so they match the new interface; **never weaken, delete, or comment out an assertion just to make a test pass** — a fix that breaks a module's contract is the test doing its job, so correct the fix or the fixture, not the assertion. \`examples/\` are \`*.tf\` (always within the push allow-list); native \`*.tftest.hcl\` / Go \`*_test.go\` files are only pushable when the \`terratest\` input is enabled — when it isn't and only those drift, note the needed test update in the PR body for a human rather than leaving the module's own tests broken. Skip this entirely for a one-off raw-resource fix that doesn't touch a module interface.
    - **validate**: call \`${t("terraform_validate")}\`. If it does not pass, fix what it reports or abandon this group — **never open a PR whose validate did not pass**. Its \`providers\` field carries the pinned provider majors (use them as above). It also returns \`unknown_arguments\` (§4.15-next): arguments you wrote that are NOT in the installed provider's schema and would break \`plan\` — treat any entry as a must-fix (correct the argument for the pinned major) even though \`passed\` doesn't gate on it. \`schema_checked: false\` means the schema wasn't available (rely on \`${t("terraform_plan")}\` then).
    - **policy gate (optional, §3.5)**: if the repo ships policy-as-code (a \`policy/\`, \`policies/\`, or \`.conftest\` dir of Rego), call \`${t("policy_check")}\` — it runs \`conftest\` against the plan JSON. It degrades green (\`ok: false\`) when conftest or a policy dir is absent. When it returns \`passed: false\`, treat it exactly like a failed validate: fix the violation (listed in \`failures\`) or label the PR \`needs-human\` and surface it — never push past a policy denial.
@@ -747,7 +813,7 @@ ${PR_SUMMARY_FORMAT}`,
      - **full plan (\`plan_text\`, §1.2)**: when present, attach it to the PR body as a collapsed \`<details><summary>Plan</summary>\\n\\n\\\`\\\`\\\`\\n…\\n\\\`\\\`\\\`\\n</details>\` block so a reviewer can see the exact planned change without re-running it.
    - **commit + push**: \`git add\` only the file you changed, commit with a message naming the file and the key rules (e.g. \`fix(tf): harden main.tf — S3 encryption + block public access\`), then \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*).
    - **open PR — with a COMPLETE body (MANDATORY)**: \`${t("create_pull_request")}\` (omit \`base\` — it resolves to the run's base branch above). The PR body is the primary deliverable a human reviews — open the PR **with a full body**, never a placeholder you intend to fill in later. At an absolute minimum the body MUST explain, in plain English: (a) **what was wrong** — each concern by \`rule_id\` + its \`evidence\`; and (b) **what you changed** to fix each one, and why it's safe. Build it with the **Remediation PR format** at the end of this checklist (status banner → title + badges → \`## What changed\` with the §5.17 *Was / Changed / Safe because* note per concern). ⚠️ \`${t("report_progress")}\` writes the GitHub Actions **job summary**, which is NOT the PR body — a good job summary does **not** substitute for a complete PR body. If you only have time/budget for one, the PR body wins.
-   - **prove it (✗→✓)**: call \`${t("terraform_verify_remediation")}\` with the group's \`concern_ids\`. It re-runs the scanners and returns the authoritative \`resolved\` / \`remaining\` sets and a \`verified\` flag — this is the proof, do NOT eyeball a scan or self-report. Then \`${t("update_pull_request_body")}\` to add a "Validation" section built **from that result**: one \`✗ → ✓ <rule_id> resolved\` line per id in \`resolved\`, and list every id in \`remaining\` honestly as still-open. Never mark a concern ✓ unless the tool returned it in \`resolved\`. Act on two more fields it returns:
+   - **prove it (re-scan)**: call \`${t("terraform_verify_remediation")}\` with the group's \`concern_ids\`. It re-runs the scanners and returns the authoritative \`resolved\` / \`remaining\` sets and a \`verified\` flag — this is the proof, do NOT eyeball a scan or self-report. Then \`${t("update_pull_request_body")}\` to add a "Validation" section built **from that result**: one \`✅ <rule_id> resolved\` line per id in \`resolved\`, and list every id in \`remaining\` honestly as still-open. Never put a ✅ on a concern unless the tool returned it in \`resolved\`. Act on two more fields it returns:
      - **regressions (§1.4)**: when \`has_regressions\` is true, the fix INTRODUCED new concerns (listed in \`regressions\`) that weren't there before — it traded one defect for another. Add a prominent **⚠️ Regression** callout listing them, add the \`needs-human\` label (\`${t("add_labels")}\`), and prefer reworking the fix to remove the regression before relying on the PR.
      - **confidence (§5.19)**: render the returned \`confidence\` (high/medium/low) as a one-line badge in the PR body (e.g. \`Confidence: high\`) with its \`confidence_reasons\`. It is computed deterministically from the verification evidence (verified + no regressions + plan idempotency + blast radius + cost) — report it verbatim, do NOT inflate it.
    - **per-finding explanation (§5.17)**: in the PR body, give each resolved concern a short three-line note — **Was** (what the scanner flagged, from its \`evidence\`), **Changed** (what your fix did), **Safe because** (why it's correct/non-breaking) — and hyperlink the \`rule_id\` to its documentation. The scan output carries a \`doc_url\` per concern (and \`doc_urls\` per group); use it, falling back to the concern's \`remediation_hint\` when no \`doc_url\` is present.
@@ -757,7 +823,7 @@ ${PR_SUMMARY_FORMAT}`,
 
 5. **guardrails** (always): one scoped PR per group, never a mega-PR spanning multiple files; **never auto-merge** and always leave the PR for human review; never modify files outside \`*.tf\` / \`*.tfvars\`.
 
-6. **finalize**: call \`${t("report_progress")}\` once with a summary — which file/group was fixed, the PR link, and the ✗→✓ result (or the exact tool error if push/PR creation failed).
+6. **finalize**: call \`${t("report_progress")}\` once with a summary — which file/group was fixed, the PR link, and the validation result (resolved ✅ / still-open) (or the exact tool error if push/PR creation failed).
 
    **SARIF for code-scanning (optional, §3.5)**: when the workflow has a SARIF upload step (it grants \`security-events: write\` and runs \`github/codeql-action/upload-sarif\` on a \`terramend.sarif\`), call \`${t("terraform_emit_sarif")}\` once at the end so the full scan also lands in the repo's Security tab — complementary to the fix PR, not a replacement for it.
 
@@ -824,7 +890,7 @@ ${REMEDIATION_PR_FORMAT}`,
 
 8. **finalize**:
    - confirm a clean working tree (only your new \`*.tf\`/\`*.tfvars\` files), then push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*).
-   - open a PR via \`${t("create_pull_request")}\` (omit \`base\` — it resolves to the run's base branch above). Use the **Remediation PR format** conventions (the same status banner + badge row + \`## What changed\` shape, and the body-wide rules) ADAPTED for generation: the body states the requirement, what was generated, the key best-practice choices (security defaults, parameters, modules, pinned versions) and any assumptions; the badge row carries \`Plan\`/\`Cost\` when those tools ran; and in place of the \`## Validation (✗ → ✓)\` section put a \`## Validation\` line stating \`terraform_validate\` passed and \`terraform_scan\` is clean (self-scan: 0 concerns).
+   - open a PR via \`${t("create_pull_request")}\` (omit \`base\` — it resolves to the run's base branch above). Use the **Remediation PR format** conventions (the same status banner + badge row + \`## What changed\` shape, and the body-wide rules) ADAPTED for generation: the body states the requirement, what was generated, the key best-practice choices (security defaults, parameters, modules, pinned versions) and any assumptions; the badge row carries \`Plan\`/\`Cost\` when those tools ran; and in place of the \`## Validation\` proof list put a \`## Validation\` line stating \`terraform_validate\` passed and \`terraform_scan\` is clean (self-scan: 0 concerns).
    - **never auto-merge** — leave the PR for human review.
    - call \`${t("report_progress")}\` once with the PR link (or the exact tool error if push/PR creation failed).
 
@@ -877,4 +943,8 @@ export const NON_COMMITTING_MODES: ReadonlySet<string> = new Set([
   "Review",
   "IncrementalReview",
   "Plan",
+  // read-only assessment — reports posture via report_progress, never touches the tree.
+  "Assess",
+  // §36 — posts a summary COMMENT, never commits to the working tree.
+  "SummarizePr",
 ]);

package/src/toolState.ts

@@ -125,6 +125,12 @@ export interface ToolState {
   // terraform_verify_remediation to compute §1.4 regressions = current −
   // baseline (concern ids the fix INTRODUCED). undefined until the first scan.
   baselineConcernIds?: string[];
+  // §27/enterprise-integrity — the LINE-INDEPENDENT keys (concernKeyOf) of the
+  // same full pre-fix baseline. terraform_verify_remediation diffs on these, not
+  // raw ids, so a fix that SHIFTS lines (almost every fix) can't make an unfixed
+  // concern look resolved nor a pre-existing one look like a regression. Set
+  // alongside baselineConcernIds by terraform_scan / read_findings.
+  baselineConcernKeys?: string[];
   // the most recent terraform_scan's reported concern set (post scope/severity
   // filtering — what the run acted on). read at end-of-run by
   // finalizeSuccessRun to emit the SARIF artifact + findings-count output

package/src/utils/moduleFetch.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildModuleFetchGitEnv,
+  moduleFetchHosts,
+  resolveModuleFetchEnv,
+} from "#app/utils/moduleFetch";
+
+describe("buildModuleFetchGitEnv", () => {
+  it("injects a Basic auth extraheader per host via GIT_CONFIG_*", () => {
+    const env = buildModuleFetchGitEnv("tok123", ["github.com"]);
+    expect(env.GIT_CONFIG_COUNT).toBe("1");
+    expect(env.GIT_CONFIG_KEY_0).toBe("http.https://github.com/.extraheader");
+    const expected = `Authorization: Basic ${Buffer.from("x-access-token:tok123").toString("base64")}`;
+    expect(env.GIT_CONFIG_VALUE_0).toBe(expected);
+  });
+
+  it("never embeds the raw token in a key/url (only in the auth header value)", () => {
+    const env = buildModuleFetchGitEnv("supersecret", ["github.com"]);
+    expect(env.GIT_CONFIG_KEY_0).not.toContain("supersecret");
+    // the token is base64'd inside the header, not present verbatim.
+    expect(env.GIT_CONFIG_VALUE_0).not.toContain("supersecret");
+  });
+
+  it("emits one entry per host and de-duplicates case-insensitively", () => {
+    const env = buildModuleFetchGitEnv("t", ["github.com", "GitHub.com", "ghe.acme.dev"]);
+    expect(env.GIT_CONFIG_COUNT).toBe("2");
+    expect(env.GIT_CONFIG_KEY_0).toBe("http.https://github.com/.extraheader");
+    expect(env.GIT_CONFIG_KEY_1).toBe("http.https://ghe.acme.dev/.extraheader");
+  });
+
+  it("returns an empty object when no usable host remains", () => {
+    expect(buildModuleFetchGitEnv("t", [])).toEqual({});
+    expect(buildModuleFetchGitEnv("t", ["  "])).toEqual({});
+  });
+});
+
+describe("moduleFetchHosts", () => {
+  it("defaults to github.com", () => {
+    expect(moduleFetchHosts(undefined)).toEqual(["github.com"]);
+  });
+
+  it("adds a GitHub Enterprise Server host from GITHUB_SERVER_URL", () => {
+    expect(moduleFetchHosts("https://ghe.acme.dev")).toEqual(["github.com", "ghe.acme.dev"]);
+  });
+
+  it("does not duplicate github.com on a github.com-hosted run", () => {
+    // GITHUB_SERVER_URL is https://github.com on github.com — the seeded host
+    // must not repeat (and is matched case-insensitively).
+    expect(moduleFetchHosts("https://github.com")).toEqual(["github.com"]);
+    expect(moduleFetchHosts("https://GitHub.com")).toEqual(["github.com"]);
+  });
+
+  it("ignores a malformed server url", () => {
+    expect(moduleFetchHosts("not a url")).toEqual(["github.com"]);
+  });
+});
+
+describe("resolveModuleFetchEnv", () => {
+  it("returns undefined without a token (the common public/registry case)", () => {
+    expect(resolveModuleFetchEnv({})).toBeUndefined();
+    expect(resolveModuleFetchEnv({ moduleFetchToken: "   " })).toBeUndefined();
+  });
+
+  it("builds the git env when a token is supplied", () => {
+    const env = resolveModuleFetchEnv({ moduleFetchToken: "abc" });
+    expect(env?.GIT_CONFIG_KEY_0).toBe("http.https://github.com/.extraheader");
+  });
+});

package/src/utils/moduleFetch.ts

@@ -0,0 +1,86 @@
+/**
+ * Org-private cross-repo module fetch (§1.5 "org-private cross-repo module
+ * fetch" — the HepCare shape).
+ *
+ * Referencing a private module from another repo in your org works today
+ * (`git::https://github.com/acme/tf-modules.git//aws/s3?ref=…`), but FETCHING it
+ * at `terraform init` does not: the action's own git is locked down (ASKPASS,
+ * `credential.helper=`) and the job token is single-repo, so terraform's child
+ * `git clone` of the module repo has no credential. This module supplies a
+ * scoped one — a PAT / GitHub App token / fine-grained token the operator passes
+ * as `module_fetch_token`.
+ *
+ * Mechanism: Git's `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_n` / `GIT_CONFIG_VALUE_n`
+ * env injection (Git ≥ 2.31). We add an `http.https://<host>/.extraheader`
+ * carrying a Basic auth header (the same pattern actions/checkout uses), scoped
+ * to the terraform subprocess only — no global/file config is mutated and the
+ * token never lands on disk. Only HTTPS `git::` sources are covered; an SSH /
+ * deploy-key source needs a key, which is out of scope here.
+ */
+
+/** the `x-access-token:<token>` Basic header value Git sends per request. */
+function basicAuthHeader(token: string): string {
+  const encoded = Buffer.from(`x-access-token:${token}`).toString("base64");
+  return `Authorization: Basic ${encoded}`;
+}
+
+/**
+ * Build the `GIT_CONFIG_*` env that authorises `git clone` of a private module
+ * over HTTPS for each host. Pure (token + hosts in, env out) so it is unit-
+ * testable without a real git. Empty/whitespace hosts are dropped; hosts are
+ * de-duplicated case-insensitively. Returns an empty object only when no usable
+ * host remains (the caller treats that as "no module-fetch credential").
+ */
+export function buildModuleFetchGitEnv(token: string, hosts: string[]): Record<string, string> {
+  const seen = new Set<string>();
+  const uniqueHosts: string[] = [];
+  for (const h of hosts) {
+    const host = h.trim().toLowerCase();
+    if (!host || seen.has(host)) continue;
+    seen.add(host);
+    uniqueHosts.push(host);
+  }
+  if (uniqueHosts.length === 0) return {};
+
+  const header = basicAuthHeader(token);
+  const env: Record<string, string> = { GIT_CONFIG_COUNT: String(uniqueHosts.length) };
+  uniqueHosts.forEach((host, i) => {
+    env[`GIT_CONFIG_KEY_${i}`] = `http.https://${host}/.extraheader`;
+    env[`GIT_CONFIG_VALUE_${i}`] = header;
+  });
+  return env;
+}
+
+/**
+ * The hosts a module-fetch credential should authorise: always github.com, plus
+ * the GitHub host the run executes against (a GitHub Enterprise Server instance
+ * via `GITHUB_SERVER_URL`) when it differs. Reads the env; pure given it.
+ */
+export function moduleFetchHosts(serverUrl = process.env.GITHUB_SERVER_URL): string[] {
+  const hosts = ["github.com"];
+  if (serverUrl) {
+    try {
+      const host = new URL(serverUrl).hostname;
+      // de-dupe case-insensitively: on github.com-hosted runs GITHUB_SERVER_URL
+      // is https://github.com, so the seeded host would otherwise repeat.
+      if (host && !hosts.some((h) => h.toLowerCase() === host.toLowerCase())) hosts.push(host);
+    } catch {
+      /* malformed GITHUB_SERVER_URL — fall back to github.com only */
+    }
+  }
+  return hosts;
+}
+
+/**
+ * Resolve the module-fetch git env for a run, or undefined when no
+ * `module_fetch_token` was supplied (the common case — public/registry/local
+ * modules need no credential). The result is merged into the env of the
+ * `terraform init`/`plan` invocations so private cross-repo modules resolve.
+ */
+export function resolveModuleFetchEnv(payload: {
+  moduleFetchToken?: string | undefined;
+}): Record<string, string> | undefined {
+  const token = payload.moduleFetchToken?.trim();
+  if (!token) return undefined;
+  return buildModuleFetchGitEnv(token, moduleFetchHosts());
+}

package/src/utils/payload.test.ts

@@ -1,4 +1,6 @@
-import { isAbsolute, resolve } from "node:path";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
 import * as core from "@actions/core";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { BUILTIN_MODE_NAMES } from "#app/modes";
@@ -399,6 +401,62 @@ describe("resolvePayload — cwd resolution", () => {
   });
 });
 
+describe("resolvePayload — .terramend.yml layering (input wins, file fills gaps)", () => {
+  const dirs: string[] = [];
+  /** write a `.terramend.yml` to a temp dir and point GITHUB_WORKSPACE at it. */
+  const withConfig = (yml: string): void => {
+    const dir = mkdtempSync(join(tmpdir(), "terramend-payload-"));
+    dirs.push(dir);
+    writeFileSync(join(dir, ".terramend.yml"), yml);
+    vi.stubEnv("GITHUB_WORKSPACE", dir);
+  };
+  afterEach(() => {
+    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+  });
+
+  it("uses the file value when the matching input is unset", () => {
+    withConfig(
+      [
+        "tools_enabled:",
+        "  - trivy",
+        "  - tflint",
+        "protected_paths:",
+        "  - prod/**",
+        "scan_scope: diff",
+      ].join("\n"),
+    );
+    setInputs({}); // no inputs — the file should fill them
+    const p = resolvePayload("p", makeRepoSettings());
+
+    expect(p.scanScope).toBe("diff");
+    expect(p.protectedPaths).toEqual(["prod/**"]);
+    // tflint named in the file is the licence-aware opt-in (same as on the input).
+    expect(p.toolsEnabled?.explicit.get("tflint")).toBe(true);
+    expect(p.toolsEnabled?.explicit.get("trivy")).toBe(true);
+  });
+
+  it("lets an explicit action input win over the file", () => {
+    withConfig("scan_scope: diff\nprotected_paths:\n  - prod/**");
+    setInputs({ scan_scope: "full", protected_paths: "iam/**" });
+    const p = resolvePayload("p", makeRepoSettings());
+
+    expect(p.scanScope).toBe("full"); // input beats the file's "diff"
+    expect(p.protectedPaths).toEqual(["iam/**"]); // input beats the file's prod/**
+  });
+
+  it("is a clean no-op when the repo has no .terramend.yml", () => {
+    const dir = mkdtempSync(join(tmpdir(), "terramend-payload-"));
+    dirs.push(dir);
+    vi.stubEnv("GITHUB_WORKSPACE", dir);
+    setInputs({});
+    const p = resolvePayload("p", makeRepoSettings());
+
+    expect(p.scanScope).toBeUndefined();
+    expect(p.protectedPaths).toBeUndefined();
+    expect(p.toolsEnabled).toBeUndefined();
+  });
+});
+
 describe("resolvePayload — Terraform remediation inputs", () => {
   it("parses every remediation input through its dedicated parser", () => {
     setInputs({
@@ -414,6 +472,8 @@ describe("resolvePayload — Terraform remediation inputs", () => {
       terratest: "on",
       base_branch: "refs/heads/release/1.2",
       allow_replace: "aws_db_instance.main, aws_s3_bucket.* ,",
+      tools_enabled: "all, -trivy",
+      module_fetch_token: "ghp_moduletoken",
     });
 
     const payload = resolvePayload("p", makeRepoSettings());
@@ -430,6 +490,11 @@ describe("resolvePayload — Terraform remediation inputs", () => {
     expect(payload.terratest).toBe(true);
     expect(payload.baseBranch).toBe("release/1.2");
     expect(payload.allowReplace).toEqual(["aws_db_instance.main", "aws_s3_bucket.*"]);
+    // §1.5 — the unified tool-selection list parses into a directive…
+    expect(payload.toolsEnabled?.base).toBe("all");
+    expect(payload.toolsEnabled?.explicit.get("trivy")).toBe(false);
+    // …and the scoped module-fetch token is carried verbatim.
+    expect(payload.moduleFetchToken).toBe("ghp_moduletoken");
   });
 
   it("degrades invalid remediation inputs to undefined / false", () => {

package/src/utils/payload.ts

@@ -6,6 +6,8 @@ import { BUILTIN_MODE_NAMES } from "#app/modes";
 import { log } from "#app/utils/cli";
 import { parseRemediationCommand } from "#app/utils/remediationCommand";
 import type { RepoSettings } from "#app/utils/runContext";
+import { loadTerramendConfig } from "#app/utils/terramendConfig";
+import { parseToolSelection } from "#app/utils/toolSelection";
 import { validateCompatibility } from "#app/utils/versioning";
 import packageJson from "#package.json" with { type: "json" };
 
@@ -71,6 +73,8 @@ export const Inputs = type({
   "module_catalogue?": type.string.or("undefined"),
   "terratest?": type.string.or("undefined"),
   "terraform_mcp?": type.string.or("undefined"),
+  "tools_enabled?": type.string.or("undefined"),
+  "module_fetch_token?": type.string.or("undefined"),
   "review_instructions?": type.string.or("undefined"),
   "fp_filtering_instructions?": type.string.or("undefined"),
 });
@@ -133,6 +137,8 @@ function resolveNonPromptInputs() {
     module_catalogue: core.getInput("module_catalogue") || undefined,
     terratest: core.getInput("terratest") || undefined,
     terraform_mcp: core.getInput("terraform_mcp") || undefined,
+    tools_enabled: core.getInput("tools_enabled") || undefined,
+    module_fetch_token: core.getInput("module_fetch_token") || undefined,
     review_instructions: core.getInput("review_instructions") || undefined,
     fp_filtering_instructions: core.getInput("fp_filtering_instructions") || undefined,
   });
@@ -189,12 +195,14 @@ function parseCostIncreaseBlock(raw: string | undefined): number | undefined {
   return Number.isFinite(n) && n > 0 ? n : undefined;
 }
 
-/** parse a comma-separated glob list (allowed_paths / protected_paths);
- * undefined when unset or empty after trimming. */
+/** parse a comma- or newline-separated glob list (allowed_paths /
+ * protected_paths); undefined when unset or empty after trimming. Newlines are
+ * accepted so a YAML block scalar in the workflow — and a list in
+ * `.terramend.yml` (joined with newlines) — parse the same as a comma list. */
 function parseGlobList(raw: string | undefined): string[] | undefined {
   if (!raw) return undefined;
   const globs = raw
-    .split(",")
+    .split(/[\n,]/)
     .map((g) => g.trim())
     .filter(Boolean);
   return globs.length > 0 ? globs : undefined;
@@ -269,7 +277,14 @@ export function resolvePayload(
     resolvedShell = "restricted";
   }
 
-  // build payload - precedence: inputs > repoSettings > fallbacks
+  const cwd = resolveCwd(inputs.cwd);
+  // §1.5 follow-up — repo-committed `.terramend.yml` policy, layered UNDER the
+  // action inputs: a workflow input always wins; the file fills the gaps. Read
+  // from the checked-out repo root; a missing file is a silent no-op. See
+  // utils/terramendConfig.ts for the trust boundary + supported keys.
+  const fileConfig = loadTerramendConfig(cwd);
+
+  // build payload - precedence: inputs > .terramend.yml > repoSettings > fallbacks
   // note: modes are NOT in payload - they come from repoSettings in main()
   return {
     "~terramend": true as const,
@@ -288,7 +303,7 @@ export function resolvePayload(
     previousRunsNote: jsonPayload?.previousRunsNote,
     event,
     timeout: inputs.timeout ?? jsonPayload?.timeout,
-    cwd: resolveCwd(inputs.cwd),
+    cwd,
     progressComment: jsonPayload?.progressComment,
     generateSummary: jsonPayload?.generateSummary,
 
@@ -299,14 +314,19 @@ export function resolvePayload(
     // Terraform remediation config — consumed by mcp/terraform.ts + the
     // Remediate mode. Defaults are applied at the consumer, not here, so
     // "unset" stays distinguishable from an explicit value.
-    scanScope: parseScanScope(inputs.scan_scope),
-    severityThreshold: parseSeverityThreshold(inputs.severity_threshold),
+    // Terraform policy fields accept a `.terramend.yml` fallback (input wins).
+    scanScope: parseScanScope(inputs.scan_scope ?? fileConfig.scan_scope),
+    severityThreshold: parseSeverityThreshold(
+      inputs.severity_threshold ?? fileConfig.severity_threshold,
+    ),
     maxPrs: parseMaxPrs(inputs.max_prs),
-    allowedPaths: parseGlobList(inputs.allowed_paths),
+    allowedPaths: parseGlobList(inputs.allowed_paths ?? fileConfig.allowed_paths),
     // §2.7 — globs the fixer must never auto-modify (inverse of allowed_paths).
-    protectedPaths: parseGlobList(inputs.protected_paths),
+    protectedPaths: parseGlobList(inputs.protected_paths ?? fileConfig.protected_paths),
     // §3.9 — minimum severity at which a security concern escalates to a human.
-    autonomyThreshold: parseSeverityThreshold(inputs.autonomy_threshold),
+    autonomyThreshold: parseSeverityThreshold(
+      inputs.autonomy_threshold ?? fileConfig.autonomy_threshold,
+    ),
     // §2.8 — opt in to the external gitleaks engine on top of the built-in
     // secret scanner (best-effort; degrades to built-in only when absent).
     gitleaks: parseBooleanInput(inputs.gitleaks),
@@ -316,7 +336,7 @@ export function resolvePayload(
     // §4.14 + module catalogue — operator-approved modules a fix/generation
     // should prefer; raw string, structured by `parseModuleCatalogue` in the
     // `list_modules` tool.
-    moduleCatalogue: inputs.module_catalogue,
+    moduleCatalogue: inputs.module_catalogue ?? fileConfig.module_catalogue,
     // §28 — opt in to scaffolding a Go Terratest smoke test + a native
     // `*.tftest.hcl` (both plan the module directly) when generating a reusable
     // module; also widens the push allow-list so the test files can be written.
@@ -326,6 +346,14 @@ export function resolvePayload(
     // and provider argument shapes). Requires docker on the runner; degrades
     // green with a note when absent. See utils/terraformMcp.ts.
     terraformMcp: parseBooleanInput(inputs.terraform_mcp),
+    // §1.5 — the unified tool-selection allow/deny list. Parsed once here into a
+    // ToolDirective; resolveToolSelection(payload) combines it with the dedicated
+    // booleans + the licence gate so every consumer agrees on which tools run.
+    toolsEnabled: parseToolSelection(inputs.tools_enabled ?? fileConfig.tools_enabled),
+    // §1.5 — scoped credential to FETCH private cross-repo `git::` modules at
+    // terraform init/plan (the HepCare shape). Injected per-subprocess via
+    // GIT_CONFIG_* by resolveModuleFetchEnv; never the action's own git.
+    moduleFetchToken: inputs.module_fetch_token,
     // §3.12 — a `@terramend fix …` command parsed from the triggering comment
     // body (the prompt), scoping the run to a specific concern/severity/file.
     // null when the prompt isn't a recognised command.

package/src/utils/remediationCommand.test.ts

@@ -95,6 +95,38 @@ describe("parseRemediationCommand (§3.12)", () => {
   });
 });
 
+describe("parseRemediationCommand — bulk remediation (§37)", () => {
+  it("parses `fix rule <rule-id>` into a rule command, preserving case", () => {
+    expect(parseRemediationCommand("@terramend fix rule CKV_AWS_23")).toEqual({
+      kind: "rule",
+      ruleId: "CKV_AWS_23",
+    });
+    expect(parseRemediationCommand("@terramend fix rule terraform_required_version")).toEqual({
+      kind: "rule",
+      ruleId: "terraform_required_version",
+    });
+  });
+
+  it("parses `fix all rule <rule-id>` and namespaced rule ids", () => {
+    expect(parseRemediationCommand("hey @terramend fix all rule CKV2_AWS_6 please")).toEqual({
+      kind: "rule",
+      ruleId: "CKV2_AWS_6",
+    });
+    expect(parseRemediationCommand("@terramend fix rule trivy:AVD-AWS-0130")).toEqual({
+      kind: "rule",
+      ruleId: "trivy:AVD-AWS-0130",
+    });
+  });
+
+  it("does not mistake the `rule` sweep for a severity / file / concern command", () => {
+    // a rule id is not hex, not a severity word, not a *.tf file.
+    const cmd = parseRemediationCommand("@terramend fix rule CKV_AWS_8");
+    expect(cmd).toEqual({ kind: "rule", ruleId: "CKV_AWS_8" });
+    // prose 'the rule about X' has a word between fix and rule → not a command.
+    expect(parseRemediationCommand("@terramend please fix the rule about tags")).toBeNull();
+  });
+});
+
 describe("parseRemediationCommand — strategy selection (§26)", () => {
   it("attaches a strategy label to a `fix #<id>` command (letter, upper-normalised)", () => {
     expect(parseRemediationCommand("@terramend fix #3a9f1c2 with strategy B")).toEqual({

package/src/utils/remediationCommand.ts

@@ -24,6 +24,9 @@ export type RemediationCommand =
   | { kind: "concern"; concernRef: string; strategy?: string }
   | { kind: "severity"; severity: Severity }
   | { kind: "file"; file: string }
+  // §37 bulk remediation — sweep ONE scanner rule across every file it fires in
+  // (one coherent PR via by-rule grouping). e.g. `@terramend fix rule CKV_AWS_23`.
+  | { kind: "rule"; ruleId: string }
   // §26 — a bare strategy pick (e.g. an in-thread reply to a proposal); the
   // concern is resolved from the comment thread the run was triggered on.
   | { kind: "strategy"; strategy: string }
@@ -71,6 +74,14 @@ export function parseRemediationCommand(body: string | undefined): RemediationCo
   const afterMention = body.slice(body.search(MENTION));
   const isSeverity = (s: string): s is Severity => (SEVERITIES as readonly string[]).includes(s);
 
+  // §37 bulk — `fix rule <rule-id>` / `fix all rule <rule-id>`. Checked FIRST and
+  // gated on the explicit `rule` keyword so a scanner rule id (`CKV_AWS_23`,
+  // `terraform_required_version`, `trivy:AVD-AWS-0088`) is never confused with a
+  // severity word, a filename, or a hex concern id. Rule ids are case-significant
+  // — kept verbatim. The fix sweeps that ONE rule across every file it fires in.
+  const rule = afterMention.match(/\bfix\s+(?:all\s+)?rule\s+([A-Za-z][A-Za-z0-9_.:-]+)\b/i);
+  if (rule) return { kind: "rule", ruleId: rule[1]! };
+
   // `fix all <sev>[-severity]` / `fix all` — but a NON-severity word after "all"
   // (prose like "fix all the bugs") is NOT the command: fall through rather than
   // silently treating it as "fix everything".