infraweaver 0.3.10 → 0.3.11

package/dist/internal.js

@@ -1781,6 +1781,8 @@ This mode standardises STRUCTURE while preserving BEHAVIOUR \u2014 the equivalen
    - \`${t("terraform_normalization_candidates")}\` \u2192 in-place idiomatic cleanups that change SYNTAX, not behaviour (redundant whole-string \`"\${expr}"\` interpolation; legacy HCL0.11 map-argument block syntax like \`vars {\` on a \`template_file\`). These relocate NOTHING \u2014 zero \`moved {}\` blocks \u2014 and are proven by the same equivalence check.
    - \`${t("terraform_consolidation_candidates")}\` \u2192 the SAME resource shape declared in several root directories (\`env/dev\` + \`env/staging\` + \`env/prod\`), with the single parameterised module they could all call already derived: which attributes are identical (module content) and which differ (per-environment inputs). A member root of a group will ALSO show up as a zero-candidate cluster in \`${t("module_extraction_candidates")}\` \u2014 prefer the consolidation, which does that work once for every environment instead of once per environment. Its \`near_groups\` are the opposite case: roots recognisably the same stack that DIFFER (one carries a resource the other does not), where folding them together is a design decision this mode has no basis for. Do NOT extract a near-group root's shared resources into a module on its own either \u2014 a module one twin calls and the other does not widens exactly the drift the near-group reports. Leave those roots alone and name the near-group and its \`differences\` in your report.
 
+   **A result marked \`report_only\` is an observation, not work.** The repository is a module other configurations call (\`report_only_reason\` says why), and restructuring it is churn for every caller: name those candidates in your \`${t("report_progress")}\` summary and open no PR for them. \`examples/\` roots are left out of every candidate list unless the operator set \`refactor_examples\`.
+
    **Before picking, check the interface.** \`${t("module_extraction_candidates")}\` reports \`unmapped_attributes\` per candidate and a top-level \`partial_interfaces\` list: arguments the raw resources SET that the target module does not. Adopting such a module DROPS them silently \u2014 and the equivalence check cannot catch it, because once the argument is gone it is absent from both sides. Two of these are unrecoverable rather than merely wrong (\`object_lock_enabled\` cannot be set after creation; \`force_destroy\` changes deletion semantics). So: **decline the candidate, or extend the module to expose the argument and say so in the PR body.** Deleting the argument to make the shapes match is never the fix. A candidate whose \`unmapped_attributes\` is \`null\` was NOT checked \u2014 the module is external and its code is not in this repo \u2014 which is not the same as clean.
 
    Pick the highest-value refactor across ALL THREE detectors. Only when they ALL come back empty \u2014 or all that remains is a cluster in a near-group root \u2014 is there genuinely nothing to do: call \`${t("report_progress")}\` with an ACCURATE message \u2014 e.g. "No behaviour-preserving refactor found: no extraction clusters and no idiomatic-normalisation candidates." \u2014 and **stop**. Two anti-patterns to avoid in that message: (i) never call a repo "already idiomatic" while normalisation candidates remain; (ii) when what's left is behaviour-CHANGING modernisation \u2014 a deprecated-resource swap (\`aws_launch_configuration\`\u2192\`aws_launch_template\`, \`aws_elb\`\u2192\`aws_lb\`, \`template_file\`\u2192\`templatefile()\`) \u2014 do NOT report "nothing to refactor": that is real work, but it ALTERS the resource set, so it belongs to Remediate. Say so explicitly rather than implying the code is clean.
@@ -1867,7 +1869,7 @@ This mode keeps already-open ${PRODUCT_NAME} remediation PRs healthy. A remediat
    - **resolved-on-base? \u2192 close it**: look for a group in step 3's scan whose \`id\` equals the PR's \`group_id\` (for a by-rule/batch PR, match on the concern ids it covered). If **no** current group/concern corresponds, the concern was already fixed on the base (a human fix, or a base change removed the file) \u2014 the PR is redundant. Call \`${t("close_pull_request")}\` with a one-line \`comment\` explaining it's resolved on the base. Do not push anything for this PR.
    - **still present \u2192 re-derive the fix on the current base**:
      - **read WHY the CI failed, before changing anything** (\`checks_failing\` PRs only): when step 2 gave the PR a \`failing_check_suite_id\`, call \`${t("get_check_suite_logs")}\` with that id FIRST. Re-deriving without reading the failure is exactly how attempt 2 and attempt 3 become identical repeats of attempt 1 \u2014 same fix, same red check, three times, until the retry cap escalates a PR nobody learned anything about. Use the returned \`failed_steps\` and log excerpt to decide what to do DIFFERENTLY this attempt. If the log shows the failure is not ours \u2014 a broken base, a missing credential, an unrelated flaky job \u2014 do not spend an attempt re-deriving: add \`needs-human\` (\`${t("add_labels")}\`), post ONE comment naming the failing step, and move on. Record the cause in the PR body/comment you write below, so the next attempt and any human start from what you found. When the id is absent, or the tool reports no failed runs, say so in the comment and continue with the plain re-derive rather than guessing.
-     - **branch**: recreate the remediation branch at the current base HEAD via \`${t("git")}\` (\`git checkout -B remediate/<id>\`) \u2014 \`-B\` force-resets it to the just-scanned base so the diff is only your fix.
+     - **branch**: recreate the remediation branch at the current base HEAD via \`${t("git")}\` (\`git({ command: "checkout", args: ["-B", <the PR's branch>] })\`, the \`branch\` step 2 returned) \u2014 \`-B\` force-resets it to the just-scanned base so the diff is only your fix.
      - **fix \u2192 validate \u2192 plan \u2192 keep tests consistent \u2192 prove it**: apply the minimal fix for that group exactly as in **Remediate** step 4 (same \`${t("terraform_validate")}\`, \`${t("terraform_plan")}\`, \`${t("terraform_module_tests")}\`, and \`${t("terraform_verify_remediation")}\` gates, and the same guardrails \u2014 never open/keep a PR whose validate didn't pass, abandon a group that would destroy a stateful resource, etc.).
      - **force-update the PR branch**: \`${t("push_branch")}\` with \`force: true\` (the PR already exists; force-updating its branch refreshes it in place \u2014 do NOT open a second PR). The Terraform-only / secret / destroy guardrails still run at push time.
      - **refresh the body**: \`${t("update_pull_request_body")}\` rebuilt from the fresh \`${t("terraform_verify_remediation")}\` result (the Remediation PR format below), and add a one-line note that it was rebased onto the current base (\`<short-sha>\`) on this run.
@@ -1912,8 +1914,8 @@ function remediateMode(t) {
 
 4. **for the chosen group**:
    - **base branch**: this run's base branch is resolved deterministically \u2014 \`${t("create_pull_request")}\` targets the \`base_branch\` input if set, else the branch the run started on, else the repository's default branch (\`main\`, or \`master\`). You do not choose it; just **omit** the \`base\` argument when opening the PR (below) and it is filled in.
-   - **idempotency**: the remediation branch is \`remediate/<group-id>\`. Before doing anything, check whether that branch or an open PR for it already exists (\`${t("git")}\` / \`${t("get_pull_request")}\`). If one exists, update it rather than opening a duplicate.
-   - **branch**: create \`remediate/<group-id>\` from the **current HEAD** (the checkout that was just scanned) via \`${t("git")}\` (\`git checkout -b remediate/<group-id>\`). Do NOT switch to a different base first \u2014 branching from the scanned checkout keeps the PR diff to exactly your fix.
+   - **idempotency**: the remediation branch is the group's \`branch\` (\`remediate/<group-id>\`, with a \`--<base>\` suffix when the PR targets a non-default branch) \u2014 use it exactly, never a name of your own. Before doing anything, check whether that branch or an open PR for it already exists (\`${t("git")}\` / \`${t("get_pull_request")}\`). If one exists, update it rather than opening a duplicate.
+   - **branch**: create the group's \`branch\` from the **current HEAD** (the checkout that was just scanned) via \`${t("git")}\` (\`git({ command: "checkout", args: ["-b", <branch>] })\`). Do NOT switch to a different base first \u2014 branching from the scanned checkout keeps the PR diff to exactly your fix.
    - **honest refusal (decide BEFORE fixing)**: if the group's concerns appear in the scan's \`refusal_candidates\` (the fix needs a human decision \u2014 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 \u2014 never a guessed, unverifiable PR.
    - **propose, then let me steer (when there's no single right fix)**: distinct from honest refusal (which refuses a fix a human must *decide*), this is for a finding with **2\u20133 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** \u2014 each a single line (what it does + its trade-off) \u2014 and ask the reviewer to reply \`${COMMENT_COMMAND} fix #<concern-id> with strategy <A|B|C>\`. Then **skip the PR for this group** this run and note it in your final report (it resumes when the reviewer replies). When the comment **did** select one (\`fix #<id> with strategy B\`, or a bare \`strategy B\` reply on the proposal thread), apply **exactly** that strategy \u2014 don't second-guess it. Reserve this for real forks in the road; a fix with one obvious correct answer just gets made.
    - **reuse a proven fix (optional, do this BEFORE editing)**: call \`${t("terraform_fix_memory")}\`. When proven-fix memory is enabled it returns any patterns whose \`finding_type\` matches this group's concerns \u2014 each a transformation that already passed a \`\u2717\u2192\u2713\` proof on this repo or elsewhere in the fleet, with its \`remediation_hint\` + a \`before_example\`. Use a matching pattern as your STARTING POINT (it saves you rediscovering the approach), but ADAPT it to this repo's own resources \u2014 it is a prior, never a patch to paste. You MUST still run \`${t("terraform_verify_remediation")}\` to prove \`\u2717\u2192\u2713\` here; a pattern is never blind-applied and never substitutes for the per-target proof. Returns an empty list (never an error) when memory is off or nothing matches \u2014 then fix from first principles as usual.
@@ -1973,7 +1975,7 @@ This mode composes the **Remediate** and **Refactor** verbs into a single run. I
    - **commit the fix** (\`git add\` only the changed \`*.tf\`/\`*.tfvars\`, a \`fix(tf): \u2026\` message). Do NOT push yet. This committed state is the refactor's equivalence BASELINE.
 
 3. **REFACTOR (phase 2) \u2014 modularise on top of the committed fix**: follow the **Refactor** mode's flow:
-   - \`${t("module_extraction_candidates")}\` / \`${t("terraform_normalization_candidates")}\` \u2192 pick one behaviour-preserving refactor. Respect a pinned \`refactor_source\` if one was supplied (it constrains which module source you may use; the behaviour-altering b.4 path is only available when the operator pinned \`third-party\`).
+   - \`${t("module_extraction_candidates")}\` / \`${t("terraform_normalization_candidates")}\` \u2192 pick one behaviour-preserving refactor; a result marked \`report_only\` (the repository is a module others call) is named in the summary, never proposed. Respect a pinned \`refactor_source\` if one was supplied (it constrains which module source you may use; the behaviour-altering b.4 path is only available when the operator pinned \`third-party\`).
    - resolve the module source, wire the \`module\` call against its real interface (\`${t("terraform_module_interface")}\` for a local module dir, \`${t("terraform_module_lookup")}\` for a registry-sourced one), and emit a \`moved {}\` block for EVERY relocated address (\`${t("terraform_generate_moved")}\`).
    - \`terraform fmt\` + \`${t("terraform_validate")}\`, then \u2014 **with the refactor edits still UNCOMMITTED** \u2014 call \`${t("terraform_equivalence_check")}\`. In this mode it diffs the working tree against the COMMITTED fix (not the run-start commit), so it measures only the refactor. It must return \`equivalent: true\` (zero uncovered moves, resource set + arguments preserved, validate + fmt clean) before you proceed; \`${t("push_branch")}\` hard-blocks an unproven one \u2014 and, once this run has added a \`moved {}\` block, it also hard-blocks a push that never ran the check at all, so abandoning the refactor means REVERTING its edits rather than leaving them in with the fix. If it can't be proven equivalent, abandon the refactor and ship the fix alone.
    - **document the module (only when the \`docs\` input is enabled)**: after the equivalence check passes, call \`${t("terraform_module_docs")}\` for the module you created/adopted (pass the relocated addresses as \`moves\`). Do not hand-write docs \u2014 the tool builds from the interface, moved blocks, and equivalence verdict.

package/dist/mcp/crosswalk-digest.d.ts

@@ -1 +1 @@
-export declare const EXPECTED_CROSSWALK_DIGEST = "95afd7e402f0f1875fa0aac33aeee8b6b54f869ec65499fb727f515ee2101ee1";
+export declare const EXPECTED_CROSSWALK_DIGEST = "f583001997c4c69f84f189a14e69e4f6eb2c52bddc04ca7f404286b5280d1ff4";

package/dist/mcp/git.d.ts

@@ -44,14 +44,30 @@ export declare const NOSHELL_BLOCKED_WRITE_ARGS: string[];
  * `-o`, or attached `-o<path>`. */
 export declare function isBlockedWriteArg(arg: string): boolean;
 export declare const Git: import("arktype/internal/variants/object.ts").ObjectType<{
-    command: string;
+    command?: string;
     args?: string[];
 }, {}>;
-export declare function GitTool(ctx: GitToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+/**
+ * The subcommand and arguments of a call, however the model wrote it: the
+ * subcommand alone (the documented form), a whole `git …` command line, or the
+ * subcommand as the first of `args`. Models wrote the other two often enough
+ * to cost a turn per run, and each is unambiguous. The subcommand is checked
+ * against the same pattern the schema uses, so a flag (`-c`, `-C`,
+ * `--exec-path`) can no more arrive through `args[0]` or a command line than
+ * through `command`.
+ */
+export declare function normalizeGitCall(params: {
+    command?: string | undefined;
+    args?: string[] | undefined;
+}): {
     command: string;
+    args: string[];
+};
+export declare function GitTool(ctx: GitToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    command?: string;
     args?: string[];
 }, {
-    command: string;
+    command?: string;
     args?: string[];
 }>> & {
     mutates?: boolean;

package/dist/mcp/localContext.d.ts

@@ -13,7 +13,7 @@ import type { ResolvedPayload } from "../utils/config/payload.js";
  * needs more (octokit, push, PR state) belongs on `ToolContext`, not here.
  */
 export interface LocalToolContext {
-    payload: Pick<ResolvedPayload, "cwd" | "scanScope" | "iacLanguages" | "severityThreshold" | "grouping" | "autonomyThreshold" | "repeatedLiteralThreshold" | "varFiles" | "costIncreaseBlockUsd" | "moduleCatalogue" | "allowReplace" | "allowMajorUpgrade" | "toolsEnabled" | "allowedPaths" | "toolsNetwork" | "gitleaks" | "terratest" | "docs" | "terraformMcp" | "moduleFetchToken" | "moduleFetchSshKey" | "registryToken" | "registryHost" | "opentofuMcp" | "fixMemory">;
+    payload: Pick<ResolvedPayload, "cwd" | "scanScope" | "iacLanguages" | "severityThreshold" | "grouping" | "autonomyThreshold" | "repeatedLiteralThreshold" | "varFiles" | "costIncreaseBlockUsd" | "moduleCatalogue" | "allowReplace" | "allowMajorUpgrade" | "toolsEnabled" | "allowedPaths" | "toolsNetwork" | "gitleaks" | "terratest" | "docs" | "terraformMcp" | "moduleFetchToken" | "moduleFetchSshKey" | "registryToken" | "registryHost" | "opentofuMcp" | "fixMemory" | "baseBranch" | "refactorExamples">;
     toolState: ToolState;
     tmpdir: string;
     /** resolved upstream model specifier driving this run's agent (e.g.
@@ -23,4 +23,12 @@ export interface LocalToolContext {
      * bundle's PROVENANCE block — recording WHO produced the evidence, not
      * just what was found. */
     resolvedModel?: string | undefined;
+    /** the repository, for its default branch. The Action's full `ToolContext`
+     * carries it; a local session has none, so its remediation branches keep the
+     * plain `remediate/<id>` name. */
+    repo?: {
+        data: {
+            default_branch?: string | null;
+        };
+    } | undefined;
 }

package/dist/mcp/shell.d.ts

@@ -1,7 +1,7 @@
 import type { ToolContext } from "./server.js";
 export declare const ShellParams: import("arktype/internal/variants/object.ts").ObjectType<{
     command: string;
-    description: string;
+    description?: string;
     timeout?: number;
     working_directory?: string;
     background?: boolean;
@@ -38,13 +38,13 @@ export declare function createCappedBuffer(limit: number): {
 };
 export declare function ShellTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
     command: string;
-    description: string;
+    description?: string;
     timeout?: number;
     working_directory?: string;
     background?: boolean;
 }, {
     command: string;
-    description: string;
+    description?: string;
     timeout?: number;
     working_directory?: string;
     background?: boolean;

package/dist/mcp/staleFix.d.ts

@@ -2,8 +2,20 @@ import type { GitHubToolContext } from "./capabilityContext.js";
 /** true when `branch` is a Infraweaver remediation/generation branch. */
 export declare function isRemediationBranch(branch: string): boolean;
 /** the `<group-id>` of a `remediate/<group-id>` branch (the scan group id that
- * keys the fix), or null for a generation branch / non-remediation branch. */
+ * keys the fix), or null for a generation branch / non-remediation branch. A
+ * `--<base>` suffix (see [[remediationBranchSuffix]]) is not part of the id. */
 export declare function groupIdFromBranch(branch: string): string | null;
+/**
+ * What a remediation branch name carries after its group id: nothing when the
+ * PR targets the repository default branch, `--<base>` otherwise.
+ *
+ * The group id is a hash of the file (or rule) alone, so the same fix aimed at
+ * two base branches — or at two repos whose roots are both `main.tf` — named
+ * the same branch, and a run that found it taken improvised another name the
+ * refresh and concurrency tools could not see. A default-branch fix keeps the
+ * plain name, so the PRs already open under it are still found and refreshed.
+ */
+export declare function remediationBranchSuffix(base: string | undefined, defaultBranch: string | undefined): string;
 /** true when a commit-author LOGIN is Infraweaver's bot (so a commit by it is NOT
  * a human edit). A null/absent login is treated as non-human here for backward
  * compatibility of this login-only helper — but prefer {@link isBotCommit}, which

package/dist/mcp/terraform/hardcodedSecrets.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A credential written into the configuration as a string literal, by the
+ * name of the argument that holds it.
+ *
+ * WHY BY NAME. The secret scanners look at the VALUE — a known key format, or a
+ * string with enough entropy — so a hand-made password (`"cg-flagshop-Pr0d!…"`)
+ * slips past all of them. Terraform says more than a text scanner can see: the
+ * value sits in an argument, a map key or a variable whose name says what it
+ * holds. A literal in `password`, `client_secret` or a Lambda environment
+ * variable called `auth` is in the repository whatever it looks like.
+ *
+ * WHAT IS READ. Every `name = "…"` line inside a `resource`, `data`,
+ * `provider`, `module` or `locals` block, at any depth, so
+ * `environment { variables = { auth = "…" } }` and `jsonencode({ … })` objects
+ * are reached; and the `default` of a `variable` whose name is a secret's. Not
+ * read: comments, heredoc bodies, a name/value pair split across two keys
+ * (`[{ name = "PASSWORD", value = "…" }]`), and a value that starts on a later
+ * line than its name.
+ *
+ * WHAT IS NOT A FINDING. A reference, a function call, an interpolation, an
+ * empty string, or a placeholder made only of `*` / `x` / `<…>`. Neither is an
+ * argument whose name only mentions a secret (`password_length`, `secret_name`,
+ * `token_validity_units`, `creation_token`): the last word of the name decides.
+ *
+ * Arguments the provider can take write-only (`aws_db_instance.password`) may
+ * also be reported by `secret-persisted-to-state`, which says something else:
+ * that the value reaches state. This one says it is in git.
+ */
+import type { SourceFile } from "./tree.js";
+import { type Concern } from "./types.js";
+/** True when an argument, map key or variable called `name` holds a secret. */
+export declare function isSecretName(name: string): boolean;
+export interface HardcodedSecret {
+    /** the argument, map key or variable name. */
+    name: string;
+    /** what holds it: `resource "aws_lambda_function" "x"`, `variable "db_password"`, … */
+    holder: string;
+    line: number;
+}
+/**
+ * Every secret-named literal in one file. Pure.
+ *
+ * One pass over the lines rather than a block parse: every assignment line is
+ * the same question whatever block it sits in, and the native pack's block
+ * parser is shared by every scanner and budgeted (see nativeScan.perf.test).
+ */
+export declare function findHardcodedSecrets(hcl: string): HardcodedSecret[];
+/** Scan an already-read tree into native concerns. Pure; no I/O of its own. */
+export declare function scanHardcodedSecrets(files: readonly SourceFile[]): Concern[];

package/dist/mcp/terraform/nativeRules.d.ts

@@ -20,6 +20,7 @@ export interface NativeRule {
 }
 export declare const SECRET_PERSISTED_TO_STATE = "secret-persisted-to-state";
 export declare const COMMITTED_STATE_FILE = "committed-state-file";
+export declare const HARDCODED_SECRET_ARGUMENT = "hardcoded-secret-argument";
 export declare const IMPERATIVE_ACTION_TRIGGER = "imperative-action-trigger";
 export declare const DYNAMIC_DESTROY_PROTECTION = "dynamic-destroy-protection";
 export declare const DEPRECATED_STATE_LOCKING = "deprecated-state-locking";

package/dist/mcp/terraform/refactorScope.d.ts

@@ -0,0 +1,12 @@
+/** true for a path inside an `examples/` (or `example/`) directory, at any depth. */
+export declare function isExamplePath(path: string): boolean;
+/**
+ * Why the repository at `cwd` reads as a reusable module rather than a
+ * deployment, or null when it does not.
+ */
+export declare function libraryRepoReason(cwd: string): string | null;
+/** what a detector tool adds to its result when the repository is a library. */
+export declare function reportOnly(reason: string | null): {
+    report_only?: true;
+    report_only_reason?: string;
+};

package/dist/mcp/terraform/tools/scan.d.ts

@@ -42,6 +42,7 @@ export declare function runScan(ctx: LocalToolContext, { scan_scope, severity_th
     };
     groups: {
         id: string;
+        branch?: string;
         file: string;
         files?: string[];
         grouping?: "file" | "rule";

package/dist/mcp/terraform/types.d.ts

@@ -242,6 +242,9 @@ export interface ConcernGroup {
     /** stable id — the remediation branch/PR key (`remediate/<id>`). Derived from
      * the file (by-file grouping) or the rule (by-rule grouping). */
     id: string;
+    /** the branch its fix is pushed to: `remediate/<id>`, plus `--<base>` when the
+     * PR targets a branch other than the repository default. */
+    branch?: string;
     /** the group's primary file (by-file) or a human label like "3 files"
      * (by-rule); `files` carries the full list for by-rule groups. */
     file: string;

package/dist/utils/config/payload.d.ts

@@ -64,6 +64,7 @@ export declare const Inputs: import("arktype/internal/variants/object.ts").Objec
     registry_token?: string | undefined;
     registry_host?: string | undefined;
     refactor_source?: string | undefined;
+    refactor_examples?: string | undefined;
     review_instructions?: string | undefined;
     fp_filtering_instructions?: string | undefined;
     remediation_instructions?: string | undefined;
@@ -151,6 +152,7 @@ managedCredentials?: {
     registryToken: string | undefined;
     registryHost: string | undefined;
     refactorSource: import("../prompt/promptDirectives.js").RefactorSource | undefined;
+    refactorExamples: boolean;
     remediationCommand: import("../github/remediationCommand.js").RemediationCommand | null;
     baseBranch: string | undefined;
     allowReplace: string[] | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infraweaver",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "GitHub Action that remediates Terraform to best practices and opens one scoped pull request per concern.",
   "keywords": [
     "ai-coding-agent",

package/src/agents/claude.ts

@@ -60,6 +60,7 @@ import {
   getUnsubmittedReview,
 } from "#app/agents/postRun";
 import { buildGracePrompt, buildGraceQuotas, shouldRunGraceTurn } from "#app/agents/quotaReserve";
+import { quotaTokens } from "#app/agents/quotaTokens";
 import { REVIEWER_AGENT_NAME, REVIEWER_SYSTEM_PROMPT } from "#app/agents/reviewer";
 import { ORCHESTRATOR_LABEL, SessionLabeler, withLabel } from "#app/agents/sessionLabeler";
 import {
@@ -637,7 +638,7 @@ function timerFor(state: ClaudeRunState, label: string): ThinkingTimer {
 function chargeTokenQuota(state: ClaudeRunState): void {
   const quota = state.params.tokenQuota;
   if (!quota || state.stopRun.signal.aborted) return;
-  if (!quota.observe(state.quotaSource, state.accumulatedTokens)) return;
+  if (!quota.observe(state.quotaSource, quotaTokens(state.accumulatedTokens))) return;
   log.info(`» ${state.params.label}: ${quota.gap()}`);
   state.stopRun.abort(new TokenQuotaExceededError(quota.gap()));
 }

package/src/agents/opencode.ts

@@ -85,6 +85,7 @@ import {
   runPostRunRetryLoop,
   shouldRunReflection,
 } from "#app/agents/postRun";
+import { quotaTokens } from "#app/agents/quotaTokens";
 import { REVIEWER_AGENT_NAME } from "#app/agents/reviewer";
 import { ORCHESTRATOR_LABEL, SessionLabeler, withLabel } from "#app/agents/sessionLabeler";
 import {
@@ -458,7 +459,7 @@ export function newTurn(): TurnAccumulator {
 export function chargeTokenQuota(ctx: RunnerContext): void {
   const quota = ctx.tokenQuota;
   if (!quota || !ctx.currentTurn || ctx.tokenQuotaExceeded) return;
-  if (!quota.observe(ctx.currentTurn.quotaSource, ctx.currentTurn.tokens)) return;
+  if (!quota.observe(ctx.currentTurn.quotaSource, quotaTokens(ctx.currentTurn.tokens))) return;
   ctx.tokenQuotaExceeded = true;
   log.info(`» ${ctx.label}: ${quota.gap()}`);
   ctx.abortRun?.(new TokenQuotaExceededError(quota.gap()));

package/src/agents/quotaTokens.ts

@@ -0,0 +1,25 @@
+/**
+ * What one run's token usage counts against its token quota.
+ *
+ * Every turn re-reads the whole conversation from the prompt cache, so on a
+ * long-context run cache reads are almost all of the volume: a Remediate run on
+ * a 68 KB `main.tf` reached 8.5M tokens in four minutes of ordinary progress,
+ * ~95% of it cache reads. Counted 1:1, the quota stopped legitimate work long
+ * before it could stop a runaway. A cache read is billed at a tenth of an input
+ * token, so it is weighted the same here: a loop that keeps re-reading a large
+ * context still reaches the ceiling, and its cost — what the quota exists to
+ * bound — is measured as it is billed.
+ */
+const CACHE_READ_WEIGHT = 0.1;
+
+export interface TokenUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** The pre-summed total the run's token quota observes. */
+export function quotaTokens(t: TokenUsage): number {
+  return t.input + t.output + t.cacheWrite + t.cacheRead * CACHE_READ_WEIGHT;
+}

package/src/mcp/crosswalk-digest.ts

@@ -3,4 +3,4 @@
 // verified fail-closed before any compliance verdict is produced; see crosswalk.ts.
 // Regenerate this file whenever the crosswalk tables in crosswalk.ts change intentionally.
 export const EXPECTED_CROSSWALK_DIGEST =
-  "95afd7e402f0f1875fa0aac33aeee8b6b54f869ec65499fb727f515ee2101ee1";
+  "f583001997c4c69f84f189a14e69e4f6eb2c52bddc04ca7f404286b5280d1ff4";

package/src/mcp/crosswalk.ts

@@ -939,6 +939,8 @@ const THEME_LOCKED: ReadonlyMap<string, string> = new Map([
   // does NOT also cite `encryption-at-rest`: whether the repository is encrypted is
   // not what the finding establishes.
   ["committed-state-file", "secrets-management"],
+  // a credential in the code is the same CIS 16.4 failure one step earlier than state in git
+  ["hardcoded-secret-argument", "secrets-management"],
 ]);
 
 /** the bare rule id, with any `<source>:` namespace stripped. */

package/src/mcp/git.ts

@@ -936,11 +936,53 @@ const subcommandPattern = regex("^[a-z][a-z0-9-]*$");
 
 // exported so the security tests validate against the REAL schema rather than a
 // second copy of the pattern that could drift from it.
+// a whole command line in `command` (`git checkout -b fix`), the way the shell
+// tool takes one. Its subcommand is held to the same pattern once split.
+const commandLinePattern = regex("^git\\s+[a-z][a-z0-9-]*(?:\\s.*)?$");
+
 export const Git = type({
-  command: type(subcommandPattern).describe("Git command (e.g., 'status', 'log', 'diff')"),
+  command: type(subcommandPattern)
+    .or(type(commandLinePattern))
+    .describe("Git command (e.g., 'status', 'log', 'diff')")
+    .optional(),
   args: type.string.array().describe("Additional arguments for the git command").optional(),
 });
 
+/** a command line split into words, honouring single and double quotes. */
+function splitWords(line: string): string[] {
+  return [...line.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3] ?? "");
+}
+
+/**
+ * The subcommand and arguments of a call, however the model wrote it: the
+ * subcommand alone (the documented form), a whole `git …` command line, or the
+ * subcommand as the first of `args`. Models wrote the other two often enough
+ * to cost a turn per run, and each is unambiguous. The subcommand is checked
+ * against the same pattern the schema uses, so a flag (`-c`, `-C`,
+ * `--exec-path`) can no more arrive through `args[0]` or a command line than
+ * through `command`.
+ */
+export function normalizeGitCall(params: {
+  command?: string | undefined;
+  args?: string[] | undefined;
+}): {
+  command: string;
+  args: string[];
+} {
+  let words: string[];
+  if (params.command === undefined) words = [...(params.args ?? [])];
+  else if (/^git\s/.test(params.command))
+    words = [...splitWords(params.command).slice(1), ...(params.args ?? [])];
+  else return { command: params.command, args: params.args ?? [] };
+  const [command, ...args] = words[0] === "git" ? words.slice(1) : words;
+  if (command === undefined || !/^[a-z][a-z0-9-]*$/.test(command)) {
+    throw new Error(
+      `command must be a Git subcommand such as 'status' or 'checkout' (was "${command ?? ""}")`,
+    );
+  }
+  return { command, args };
+}
+
 export function GitTool(ctx: GitToolContext) {
   return tool({
     name: "git",
@@ -958,8 +1000,7 @@ export function GitTool(ctx: GitToolContext) {
       "git pull is not available — use git_fetch then this tool with command 'merge'.",
     parameters: Git,
     execute: execute(async (params) => {
-      const command = params.command;
-      const args = params.args ?? [];
+      const { command, args } = normalizeGitCall(params);
 
       // guard: {command:"status",args:["status"]} → `git status status`, where
       // git silently treats args[0] as a pathspec. when nothing matches the

package/src/mcp/localContext.ts

@@ -62,6 +62,10 @@ export interface LocalToolContext {
     // the local stdio MCP server too, so a CLI/IDE session benefits from a
     // committed `.infraweaver.fix-library.json`.
     | "fixMemory"
+    // the PR base a remediation branch is named for (see remediationBranchSuffix)
+    | "baseBranch"
+    // whether Refactor may propose changes inside `examples/` (refactorScope)
+    | "refactorExamples"
   >;
   toolState: ToolState;
   tmpdir: string;
@@ -72,4 +76,8 @@ export interface LocalToolContext {
    * bundle's PROVENANCE block — recording WHO produced the evidence, not
    * just what was found. */
   resolvedModel?: string | undefined;
+  /** the repository, for its default branch. The Action's full `ToolContext`
+   * carries it; a local session has none, so its remediation branches keep the
+   * plain `remediate/<id>` name. */
+  repo?: { data: { default_branch?: string | null } } | undefined;
 }

package/src/mcp/localServer.ts

@@ -111,6 +111,9 @@ export function buildLocalContext(options: LocalMcpOptions): LocalToolContext {
       // blocked_destructive informationally with push_will_block: false.
       allowReplace: undefined,
       allowMajorUpgrade: undefined,
+      // no PR surface, so remediation branches keep their plain names
+      baseBranch: undefined,
+      refactorExamples: false,
       moduleCatalogue: options.moduleCatalogue,
       toolsEnabled: parseToolSelection(options.toolsEnabled),
       // no allowed_paths input on the local server, so the one writing tool

package/src/mcp/moduleExtraction.ts

@@ -42,6 +42,7 @@ import {
   readFetchedGitModules,
   readFetchedRegistryModuleDirs,
 } from "#app/mcp/terraform/refactor/workspace";
+import { isExamplePath, libraryRepoReason, reportOnly } from "#app/mcp/terraform/refactorScope";
 import { scanSessionOf } from "#app/mcp/terraform/scanSession";
 import { log } from "#app/utils/cli";
 import { pushInto } from "#app/utils/collect";
@@ -915,7 +916,8 @@ export function ModuleExtractionCandidatesTool(ctx: LocalToolContext) {
         cwd,
         ctx.payload.moduleCatalogue,
         ctx.toolState.orgModuleHcl,
-      );
+      ).filter((c) => ctx.payload.refactorExamples || !isExamplePath(c.cluster.file));
+      const library = libraryRepoReason(cwd);
       const matched = candidates.filter((c) => c.candidates.length > 0);
       // Record every candidate's reason, keyed by source, for create_pull_request:
       // when a refactor PR's diff adopts one of these modules and the agent left
@@ -943,6 +945,7 @@ export function ModuleExtractionCandidatesTool(ctx: LocalToolContext) {
             : ""),
       );
       return toolOk({
+        ...reportOnly(library),
         cluster_count: candidates.length,
         matched_count: matched.length,
         candidates,

package/src/mcp/shell.ts

@@ -17,7 +17,7 @@ import { log } from "#app/utils/log";
 
 export const ShellParams = type({
   command: "string",
-  description: "string",
+  "description?": "string",
   "timeout?": type.number.describe(
     "Timeout in MILLISECONDS (not seconds). Default 30000 (30s), max 120000 (2m). e.g. timeout: 180000 for 3 minutes; timeout: 180 means 180ms and will kill the process almost immediately.",
   ),
@@ -455,7 +455,7 @@ export function ShellTool(ctx: ToolContext) {
   return tool({
     name: "shell",
     timeoutMs: 120_000,
-    description: `Execute shell commands securely. Environment is filtered to remove API keys and secrets.
+    description: `Execute shell commands securely. Environment is filtered to remove API keys and secrets. NOT for git: any command running \`git\` is refused here — use the git tool (and push_branch / git_fetch).
 
 Example: \`shell({ command: "pnpm test", description: "run the test suite" })\`.
 

package/src/mcp/staleFix.ts

@@ -38,9 +38,28 @@ export function isRemediationBranch(branch: string): boolean {
 }
 
 /** the `<group-id>` of a `remediate/<group-id>` branch (the scan group id that
- * keys the fix), or null for a generation branch / non-remediation branch. */
+ * keys the fix), or null for a generation branch / non-remediation branch. A
+ * `--<base>` suffix (see [[remediationBranchSuffix]]) is not part of the id. */
 export function groupIdFromBranch(branch: string): string | null {
-  return branch.match(/^remediate\/(.+)$/)?.[1] ?? null;
+  return branch.match(/^remediate\/(.+?)(?:--.+)?$/)?.[1] ?? null;
+}
+
+/**
+ * What a remediation branch name carries after its group id: nothing when the
+ * PR targets the repository default branch, `--<base>` otherwise.
+ *
+ * The group id is a hash of the file (or rule) alone, so the same fix aimed at
+ * two base branches — or at two repos whose roots are both `main.tf` — named
+ * the same branch, and a run that found it taken improvised another name the
+ * refresh and concurrency tools could not see. A default-branch fix keeps the
+ * plain name, so the PRs already open under it are still found and refreshed.
+ */
+export function remediationBranchSuffix(
+  base: string | undefined,
+  defaultBranch: string | undefined,
+): string {
+  if (!base || !defaultBranch || base === defaultBranch) return "";
+  return `--${base.replace(/[^A-Za-z0-9._-]+/g, "-")}`;
 }
 
 /** core matcher: a NON-EMPTY identity string (a GitHub login or a git author

package/src/mcp/terraform/concernResult.ts

@@ -1,4 +1,5 @@
 import type { LocalToolContext } from "#app/mcp/localContext";
+import { remediationBranchSuffix } from "#app/mcp/staleFix";
 import {
   capSeededConcerns,
   type PrioritySignals,
@@ -65,6 +66,18 @@ export function annotateConcerns(
   );
 }
 
+/** The branch this run's PRs target, as `create_pull_request` resolves it: the
+ *  `base_branch` input, else the branch the run started on, else the default. */
+function remediationBaseOf(ctx: LocalToolContext): string | undefined {
+  const head = ctx.toolState.initialHead;
+  return (
+    ctx.payload.baseBranch?.trim() ||
+    (head?.kind === "branch" ? head.name : undefined) ||
+    ctx.repo?.data.default_branch?.trim() ||
+    undefined
+  );
+}
+
 /**
  * The shared concerns→result pipeline behind `terraform_scan` and `read_findings`:
  * capture the line-pinned + line-independent baseline (so verify's regression diff
@@ -141,10 +154,17 @@ export function buildConcernResult(
     active,
     opts.autonomyThreshold,
   );
-  const groups = opts.priority
-    ? prioritizeGroups(annotatedGroups, active, opts.priority)
-    : annotatedGroups;
-  const batchPlan = planBatches(groups);
+  const suffix = remediationBranchSuffix(
+    remediationBaseOf(ctx),
+    ctx.repo?.data.default_branch?.trim() || undefined,
+  );
+  const groups = (
+    opts.priority ? prioritizeGroups(annotatedGroups, active, opts.priority) : annotatedGroups
+  ).map((g) => ({ ...g, branch: `remediate/${g.id}${suffix}` }));
+  const planned = planBatches(groups);
+  const batchPlan = planned.batch_branch
+    ? { ...planned, batch_branch: `${planned.batch_branch}${suffix}` }
+    : planned;
 
   const bySeverity: Record<string, number> = {};
   for (const c of active) bySeverity[c.severity] = (bySeverity[c.severity] ?? 0) + 1;