infraweaver 0.1.0

package/src/utils/payload.ts

@@ -0,0 +1,1206 @@
+import { isAbsolute, resolve } from "node:path";
+import * as core from "@actions/core";
+import { type } from "arktype";
+import { parseRunTokenQuota } from "#app/agents/tokenQuota";
+import { PRODUCT_NAME, PRODUCT_SLUG } from "#app/brand";
+import type { AuthorPermission, PayloadEvent } from "#app/external";
+import { parseToolsNetwork } from "#app/mcp/terraform/scannerEgress";
+import { BUILTIN_MODE_NAMES } from "#app/modes";
+import { applyBaseRefConfigPolicy } from "#app/utils/baseRefConfig";
+import { log } from "#app/utils/cli";
+import { parseRemediationCommand } from "#app/utils/remediationCommand";
+import type { RepoSettings } from "#app/utils/runContext";
+import { loadInfraweaverConfig } from "#app/utils/infraweaverConfig";
+import { parseToolSelection } from "#app/utils/toolSelection";
+import { validateCompatibility } from "#app/utils/versioning";
+import packageJson from "#package.json" with { type: "json" };
+
+// tool permission enum types for inputs
+const ShellPermissionInput = type.enumerated(
+  "disabled",
+  "restricted",
+  "enabled",
+);
+const PushPermissionInput = type.enumerated(
+  "disabled",
+  "restricted",
+  "enabled",
+);
+
+// schema for JSON payload passed via prompt (internal dispatch invocation)
+// note: permissions are intentionally NOT included here to prevent injection attacks
+// permissions are derived from event.authorPermission instead
+export const JsonPayload = type({
+  "~infraweaver": "true",
+  version: "string",
+  "model?": "string | undefined",
+  prompt: "string",
+  "triggerer?": "string | undefined",
+
+  "eventInstructions?": "string",
+  "previousRunsNote?": "string",
+  "event?": "object",
+  "timeout?": "string | undefined",
+  "progressComment?": type({
+    id: "string",
+    type: "'issue' | 'review'",
+  }).or("undefined"),
+  "generateSummary?": "boolean | undefined",
+});
+
+// permission levels that indicate collaborator status (have push access)
+const COLLABORATOR_PERMISSIONS: AuthorPermission[] = [
+  "admin",
+  "maintain",
+  "write",
+];
+
+// check if the event author has collaborator-level permissions
+function isCollaborator(event: PayloadEvent): boolean {
+  const perm = event.authorPermission;
+  return perm !== undefined && COLLABORATOR_PERMISSIONS.includes(perm);
+}
+
+// inputs schema - action inputs from core.getInput()
+// note: tool permissions use .or("undefined") because getInput() || undefined
+// explicitly sets the property to undefined when empty, which is different from
+// the property being absent. arktype's "prop?" means "optional to include" but
+// if included, must match the type - so we need to explicitly allow undefined.
+export const Inputs = type({
+  prompt: "string",
+  "model?": type.string.or("undefined"),
+  "mode?": type.string.or("undefined"),
+  "timeout?": type.string.or("undefined"),
+  "push?": PushPermissionInput.or("undefined"),
+  "shell?": ShellPermissionInput.or("undefined"),
+  "cwd?": type.string.or("undefined"),
+  "output_schema?": type.string.or("undefined"),
+  // Terraform remediation config (all optional; defaults applied downstream)
+  "scan_scope?": type.string.or("undefined"),
+  "iac_languages?": type.string.or("undefined"),
+  // language for user-facing prose (PR bodies, review text, summaries). en (default)
+  // | de | es | pl | ro — the LLM-authored explanations only; never the Terraform.
+  "language?": type.string.or("undefined"),
+  "severity_threshold?": type.string.or("undefined"),
+  "concern_ids?": type.string.or("undefined"),
+  "grouping?": type.string.or("undefined"),
+  "max_prs?": type.string.or("undefined"),
+  "max_run_tokens?": type.string.or("undefined"),
+  "pr_concurrent_limit?": type.string.or("undefined"),
+  "pr_hourly_limit?": type.string.or("undefined"),
+  "allowed_paths?": type.string.or("undefined"),
+  "base_branch?": type.string.or("undefined"),
+  "allow_replace?": type.string.or("undefined"),
+  "protected_paths?": type.string.or("undefined"),
+  "autonomy_threshold?": type.string.or("undefined"),
+  "required_controls?": type.string.or("undefined"),
+  "gitleaks?": type.string.or("undefined"),
+  "cost_increase_block_usd?": type.string.or("undefined"),
+  "module_catalogue?": type.string.or("undefined"),
+  "terratest?": type.string.or("undefined"),
+  "docs?": type.string.or("undefined"),
+  "terraform_mcp?": type.string.or("undefined"),
+  "opentofu_mcp?": type.string.or("undefined"),
+  "fix_memory?": type.string.or("undefined"),
+  "tools_enabled?": type.string.or("undefined"),
+  "tools_network?": type.string.or("undefined"),
+  "module_fetch_token?": type.string.or("undefined"),
+  "module_fetch_ssh_key?": type.string.or("undefined"),
+  "registry_token?": type.string.or("undefined"),
+  "registry_host?": type.string.or("undefined"),
+  // Refactor: which module-source variant the operator wants (auto | same-repo |
+  // org-repo | author | third-party). Structured scope, not prompt text — see
+  // parseRefactorSource / withRefactorSource. Gates the behaviour-altering b.4.
+  "refactor_source?": type.string.or("undefined"),
+  "review_instructions?": type.string.or("undefined"),
+  "fp_filtering_instructions?": type.string.or("undefined"),
+  "remediation_instructions?": type.string.or("undefined"),
+  "refactor_instructions?": type.string.or("undefined"),
+  // Infraweaver Cloud org token (tmnd_...) — when present, the run reports its
+  // findings/posture to Cloud after success (utils/cloudReport.ts). Optional.
+  "api_token?": type.string.or("undefined"),
+});
+
+export type Inputs = typeof Inputs.infer;
+
+function isPayloadEvent(value: unknown): value is PayloadEvent {
+  return typeof value === "object" && value !== null && "trigger" in value;
+}
+
+function resolveCwd(cwd: string | undefined): string | undefined {
+  const workspace = process.env.GITHUB_WORKSPACE;
+  if (!cwd) return workspace;
+  if (isAbsolute(cwd)) return cwd;
+  return workspace ? resolve(workspace, cwd) : cwd;
+}
+
+export type ResolvedPromptInput = string | typeof JsonPayload.infer;
+
+/**
+ * Built-in, VETTED prompts for the deterministic Terraform CI modes. When one of
+ * these modes is pinned via the action `mode:` input, the engine OWNS the prompt —
+ * a workflow-supplied prompt is ignored (see {@link resolveEffectivePrompt}) so a
+ * managed / Cloud-dispatched run can never be steered by free-form prompt text.
+ * Keyed by the canonical mode name returned by {@link parseMode}.
+ */
+export const VETTED_MODE_PROMPTS: Readonly<Record<string, string>> = {
+  Remediate: [
+    "Bring this repository's Terraform up to best practice and open ONE scoped,",
+    "reviewable pull request for the highest-severity group of issues. The",
+    "deterministic scanners decide what is wrong; you apply the minimal, correct fix",
+    "and prove it.",
+    "",
+    "Priorities, in order:",
+    "1. SECURITY — encryption at rest and in transit; no unintended public exposure;",
+    "   least-privilege IAM (no wildcard actions/resources); host hardening (e.g.",
+    "   IMDSv2); no plaintext secrets in .tf/.tfvars.",
+    "2. CORRECTNESS — must pass `terraform validate`; no deprecated syntax; pin",
+    "   provider and module versions.",
+    "3. IDIOMATIC STYLE — clear, consistent naming; prefer variables/locals and",
+    "   well-maintained modules over copy-pasted blocks. Match the file's existing",
+    "   formatting in your edit; do NOT run `terraform fmt` to reformat pre-existing",
+    "   style drift (it rewrites the whole file and buries the fix).",
+    "4. TAGGING & GOVERNANCE — consistent owner / environment / cost-center tags.",
+    "5. COST — reach best practice the cost-effective way; surface any meaningful",
+    "   monthly cost change.",
+    "",
+    "Discipline: only modify Terraform files (*.tf, *.tfvars) — never CI/workflow",
+    "files, application code, or docs. Make the smallest change that resolves each",
+    "concern; do not refactor unrelated code. Prove every fix by re-scanning the",
+    "branch (✗ → ✓). The PR body must explain, per issue, what was wrong, what",
+    "changed, and why it is safe. Never auto-merge — always leave the PR for human",
+    "review.",
+  ].join("\n"),
+  Assess: [
+    "Assess this repository's Terraform and report its security and best-practice",
+    "posture. Run the deterministic scanners, summarise the findings by severity, and",
+    "explain the highest-priority risks in priority order (security → correctness →",
+    "idiomatic style → tagging → cost). Do NOT modify any files and do NOT open a",
+    "pull request — this is a read-only assessment.",
+  ].join("\n"),
+  TerraformCodeReview: [
+    "Review the Terraform changes in this pull request and submit ONE PR review. Scope",
+    "is *.tf / *.tfvars / *.tf.json / *.tfvars.json ONLY — note any non-Terraform files",
+    "as out of scope, do not review them.",
+    "",
+    "Look for, in priority order: SECURITY misconfig (wildcard IAM, public exposure,",
+    "missing encryption, plaintext secrets, IMDSv1); STATE SAFETY (a change that forces a",
+    "destroy/replace of a stateful resource, a relocated address missing a `moved {}`",
+    "block, a flipped force_destroy / deletion_protection / prevent_destroy); CORRECTNESS",
+    "(would it pass `terraform validate`? deprecated syntax, wrong types, count/for_each",
+    "churn); VERSION & SUPPLY-CHAIN (unpinned or major-bumped provider/module pins, an",
+    "unpinned remote module source); and MODULE/INTERFACE hygiene (insecure variable",
+    "defaults, unmarked sensitive outputs).",
+    "",
+    "This is READ-ONLY — do NOT modify any files, commit, push, or open a PR. The PR",
+    "review is the only deliverable. Anchor findings to changed lines; raise a",
+    "destroy/replace or a major version bump for explicit human sign-off rather than",
+    "treating it as routine.",
+  ].join("\n"),
+  Refactor: [
+    "Standardise this repository's Terraform WITHOUT changing behaviour, and open ONE scoped,",
+    "reviewable pull request that PROVES the change is a no-op on live infrastructure. There are",
+    "two kinds of behaviour-preserving refactor — do whichever has the most value here:",
+    "  (a) MODULARISE — lift a cohesive cluster of raw resources behind a module boundary (an",
+    "      existing module, same repo or a pinned cross-repo one, or one you mechanically",
+    "      extract), with a `moved {}` block for every relocated address.",
+    "  (b) NORMALISE in place — apply provably-equivalent idiomatic cleanups that change SYNTAX,",
+    "      not behaviour: drop redundant whole-string interpolation wrapping, convert legacy",
+    "      HCL0.11 block-assignment (`config {` / `vars {`) to `= {`, split an overgrown file.",
+    "      These relocate nothing, so they need no `moved {}` blocks and are proven the same",
+    "      way (same resource set, same argument names, validate + fmt clean).",
+    "Use `module_extraction_candidates` and `terraform_normalization_candidates` to find both.",
+    "",
+    "Discipline:",
+    "1. EQUIVALENCE, not alteration — the resource set, every resource's arguments, and",
+    "   behaviour must be identical before and after. Generate a `moved {}` block for",
+    "   EVERY relocated address; a missing one silently destroys and recreates a resource.",
+    "2. PROVE it — terraform_equivalence_check must report `equivalent: true` (zero",
+    "   uncovered moves, resource set + arguments preserved, validate + fmt clean) before",
+    "   you push. When cloud credentials exist, a `refactor_safe` plan corroborates it.",
+    "3. SECURE defaults — when you parameterise a hardcoded value into a variable, its",
+    "   default must be the secure choice or absent; never preserve an insecure default.",
+    "4. Only modify Terraform files (*.tf, *.tfvars). A module in a separate repo is",
+    "   READ-ONLY — never open a write PR against it; fix at the call site via inputs.",
+    "5. NOT a refactor — swapping a resource TYPE or adding/removing a managed resource",
+    "   (e.g. aws_launch_configuration→aws_launch_template, aws_elb→aws_lb, the template_file",
+    "   data source→the templatefile() function) ALTERS behaviour. Leave it to Remediate and",
+    "   never claim equivalence for it. If that is the only work left, say so — do not report",
+    "   the repository as already idiomatic.",
+    "",
+    "Do NOT ship a refactor you cannot prove equivalent — abandon or escalate it. Never",
+    "auto-merge; always leave the PR for human review. The PR body must carry the",
+    "equivalence proof (resource-set, argument, and moved-block coverage).",
+  ].join("\n"),
+  RemediateAndRefactor: [
+    "Do BOTH a best-practice fix AND a behaviour-preserving modularisation of this repository's",
+    "Terraform, on ONE branch, and open ONE pull request that carries TWO distinct, un-entangled",
+    "proofs. The two halves are different categories of change and an auditor reads them",
+    "differently — never blur them together.",
+    "",
+    "Run them in this ORDER (the order is load-bearing — the equivalence proof depends on it):",
+    "1. REMEDIATE FIRST. Scan with the deterministic tools, take the highest-severity group (or",
+    "   the TARGETED FINDINGS group if this run named concern ids), apply the minimal correct fix,",
+    "   `terraform validate`, and prove it by re-scanning (✗ → ✓). Then COMMIT the fix on the",
+    "   branch — this committed state is the baseline the refactor's equivalence is measured",
+    "   against, so the fix's argument changes are NOT counted against the refactor.",
+    "2. REFACTOR SECOND, on top of the committed fix. Modularise a cohesive cluster (or apply an",
+    "   idiomatic in-place normalisation), authoring a `moved {}` block for EVERY relocated",
+    "   address. Run terraform_equivalence_check while the refactor edits are still UNCOMMITTED —",
+    "   it diffs the working tree against the committed fix and must return `equivalent: true`",
+    "   (same resource set, same arguments, zero uncovered moves, validate + fmt clean) before you",
+    "   commit and push. A refactor you cannot prove equivalent is abandoned, never pushed.",
+    "",
+    "Discipline: only modify Terraform files (*.tf, *.tfvars). The fix is proven by the ✗→✓",
+    "re-scan; the refactor is proven by equivalence — keep them as SEPARATE PR sections (a",
+    "`## Validation` block for the fix and a `## Equivalence proof` block for the refactor), never",
+    "one narrative. A module in a separate repo is READ-ONLY — never write to it. Respect the",
+    "pinned refactor_source if one was supplied. Never auto-merge; leave the PR for human review.",
+  ].join("\n"),
+  PolicyGate: [
+    "Run this repository's own policy-as-code (OPA/conftest Rego under policy/, policies/, or",
+    ".conftest) as a READ-ONLY gate and report whether it passes. conftest evaluates a Terraform",
+    "plan, so produce a plan first; when no cloud credentials are available the gate is",
+    "INCONCLUSIVE, not passing — say so rather than reporting a false green. Report PASS, FAIL",
+    "(list each violation: policy, resource, message), or INCONCLUSIVE, and emit a structured",
+    "result so CI can fail on a policy violation. Do NOT modify any files, commit, push, or open a",
+    "pull request — this is a read-only gate.",
+  ].join("\n"),
+  UpdateDependencies: [
+    "Upgrade this repository's outdated or unpinned Terraform provider and module versions to",
+    "current, supported pins, and open ONE scoped, reviewable pull request per provider/module that",
+    "PROVES the bump is safe.",
+    "",
+    "Discipline:",
+    "1. CLASSIFY each bump. A version-constraint-only change (patch/minor, or pinning a floating",
+    "   version) is behaviour-preserving — prove it with terraform_equivalence_check (equivalent:",
+    "   true; same resource set + arguments, validate + fmt clean). A major bump that needs code",
+    "   changes ALTERS behaviour — never claim equivalence for it.",
+    "2. PROVE a behaviour-affecting bump with a reviewed terraform plan when cloud credentials",
+    "   exist; with none, ship the PR labelled `proposed — unproven` and say the plan must be",
+    "   reviewed.",
+    "3. A stateful destroy/replace is blocked at push unless allow_replace covers it — abandon",
+    "   rather than force it. Keep a changed module's examples/tests consistent.",
+    "4. Only modify Terraform files (*.tf, *.tfvars). Pin to a CURRENT supported major, never an",
+    "   ancient one. The PR body states old → new and links the changelog. Never auto-merge.",
+  ].join("\n"),
+  ModernizeDeprecated: [
+    "Migrate this repository's DEPRECATED Terraform patterns to their modern equivalents —",
+    "aws_launch_configuration → aws_launch_template, aws_elb → aws_lb, the template_file data",
+    "source → the templatefile() function, EOL provider pins — and open ONE scoped pull request per",
+    "pattern class.",
+    "",
+    "Discipline:",
+    "1. These swaps ALTER the resource set, so equivalence is FALSE and must NEVER be claimed.",
+    "   Preserve the effective configuration; author a `moved {}` block wherever an address carries",
+    "   over, and use create_before_destroy where a replace is unavoidable.",
+    "2. PROVE with a reviewed terraform plan when cloud credentials exist; with none, ship the PR",
+    "   labelled `proposed — unproven` and state plainly that it must be reviewed before merge.",
+    "3. A stateful destroy/replace is blocked at push unless allow_replace covers it — abandon",
+    "   rather than force it. A high blast radius escalates to needs-human.",
+    "4. Only modify Terraform files (*.tf, *.tfvars); one pattern class per PR. Never auto-merge.",
+  ].join("\n"),
+  DriftDetect: [
+    "Detect whether this repository's deployed infrastructure has DRIFTED from its committed",
+    "Terraform, and report it. Drift is any change / replace / destroy a plan would make to reconcile",
+    "live state with the unchanged code. Prefer the zero-credential path: read a `terraform show -json`",
+    `plan artifact the CI already produced (${PRODUCT_NAME} never holds cloud creds); otherwise run a`,
+    "read-only terraform plan against live state.",
+    "",
+    "Discipline:",
+    "1. Drift is measured from a plan — a CI-produced plan artifact (no credentials needed) or a",
+    "   read-only plan against live state (a read-only cloud role / OIDC is enough). Only when NEITHER",
+    "   a plan artifact NOR cloud credentials are available is the result INCONCLUSIVE, not 'no drift' —",
+    "   report that plainly so a green check never masks an unchecked stack.",
+    "2. Report NO DRIFT (clean plan), DRIFT (list the drifted addresses, the blast radius, and call",
+    "   out any stateful resource whose reconciliation could destroy data), or INCONCLUSIVE. Treat a",
+    "   non-deterministic plan as a perpetual-diff smell, not true drift.",
+    `3. Do NOT modify any files, commit, push, open a PR, or apply — ${PRODUCT_NAME} never reconciles drift`,
+    "   itself; the human decides whether to revert the out-of-band change, apply, or update the code.",
+    "   Emit a structured output so a scheduled workflow can alert on drift.",
+  ].join("\n"),
+  ComplianceAudit: [
+    "Audit this repository's Terraform against the operator's required compliance controls and emit a",
+    "machine-readable OSCAL assessment-results document. This is READ-ONLY — do NOT modify any files,",
+    "commit, push, or open a PR.",
+    "",
+    "Discipline:",
+    "1. Build the audit from tool evidence, never your own judgement: assess the Terraform, then map",
+    "   the findings to controls across the supported frameworks (NCSC Cloud Principles, Cyber",
+    "   Essentials, NHS DSPT, Secure by Design, CIS, SOC 2). When required_controls are supplied, lead",
+    "   with them — report each as met, at-risk, or not-code-verifiable (honestly, never implying a",
+    "   pass for a control Terraform alone can't evidence).",
+    "2. The crosswalk is an INDICATIVE alignment, not a certified audit verdict — label it as such.",
+    "3. Emit the OSCAL assessment-results document as the audit artefact, and a structured output so",
+    "   CI can gate on an at-risk required control. The report + the OSCAL document are the only",
+    "   deliverables.",
+  ].join("\n"),
+  CostOptimization: [
+    "Reduce this repository's Terraform cost and open ONE scoped, reviewable pull request per",
+    "opportunity, each QUANTIFIED by the infracost monthly delta. Cost analysis needs infracost,",
+    `which ${PRODUCT_NAME} does not bundle — when INFRACOST_API_KEY / the infracost CLI is absent, report`,
+    "that cost data is unavailable and stop; never guess costs.",
+    "",
+    "Discipline:",
+    "1. Prefer savings with NO capacity loss (gp2 → gp3, idle/unattached resources, oversized",
+    "   instances rightsized within stated needs). Any change that reduces capacity is a human",
+    "   decision — surface the trade-off, never silently shrink production.",
+    "2. QUANTIFY every change with infracost (the PR headline is the monthly saving); validate, and",
+    "   plan when cloud credentials exist. A stateful destroy/replace is blocked at push unless",
+    "   allow_replace covers it — abandon rather than force it.",
+    "3. Only modify Terraform files (*.tf, *.tfvars); one opportunity per PR. The body is",
+    "   evidence-built from infracost + plan, never self-reported. Never auto-merge.",
+  ].join("\n"),
+};
+
+export function resolvePromptInput(): ResolvedPromptInput {
+  // Two surfaces resolve here. `prompt` is the PUBLIC input (declared in
+  // action.yml): the free-form task for an un-pinned OSS/self-hosted run — the
+  // only way to task the action when no vetted mode is pinned and there is no
+  // dispatch UI. `command` is internal plumbing (NOT declared): the
+  // `@infraweaver fix …` comment flow (comment-fix.yml) forwards the comment
+  // body through it. A pinned vetted mode (remediate/assess/…) supplies its own
+  // task and IGNORES a free-form prompt — see resolveEffectivePrompt, the
+  // security boundary — so those runs send neither; resolvePayload validates
+  // one is present otherwise.
+  const command = core.getInput("command") || core.getInput("prompt");
+  if (!command.trim()) return "";
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(command);
+  } catch {
+    // JSON parse error is fine (plain text command)
+    return command;
+  }
+
+  if (!parsed || typeof parsed !== "object" || !("~infraweaver" in parsed)) {
+    // if it doesn't look like a infraweaver payload, return the plain text command
+    return command;
+  }
+
+  // validation errors should propagate
+  const jsonPayload = JsonPayload.assert(parsed);
+  validateCompatibility(jsonPayload.version, packageJson.version);
+  return jsonPayload;
+}
+
+/**
+ * The prompt a run actually uses. For a pinned mode that ships a vetted standard
+ * (the Terraform CI modes in {@link VETTED_MODE_PROMPTS}), the engine owns the
+ * prompt: a FREE-FORM workflow prompt is IGNORED (and warned) so it can't steer a
+ * managed/CI run — this is the security boundary. Two things are deliberately NOT
+ * overridden: the internal JSON dispatch payload (trusted), and a recognised
+ * `@infraweaver fix …` command (`isRemediationCommand`) — the comment-driven flow
+ * needs the structured command to reach the agent. Otherwise the workflow prompt is
+ * used, and is required when no vetted mode supplies one.
+ */
+export function resolveEffectivePrompt(
+  rawPrompt: string,
+  fromJsonPayload: boolean,
+  mode: string | undefined,
+  isRemediationCommand: boolean,
+): string {
+  const vetted = mode ? VETTED_MODE_PROMPTS[mode] : undefined;
+  if (!fromJsonPayload && vetted && !isRemediationCommand) {
+    if (rawPrompt.trim()) {
+      log.warning(
+        `» ignoring the free-form workflow prompt for pinned mode ${mode} — ${PRODUCT_NAME} uses its built-in standard for this mode (the prompt is engine-owned).`,
+      );
+    }
+    return vetted;
+  }
+  if (!rawPrompt.trim()) {
+    const vettedModes = Object.keys(VETTED_MODE_PROMPTS)
+      .map((m) => `mode: ${m.toLowerCase()}`)
+      .join(" or ");
+    throw new Error(
+      `This run has no mode pinned and no task to run. Pin a mode that ships a built-in standard (${vettedModes}).`,
+    );
+  }
+  return rawPrompt;
+}
+
+function resolveNonPromptInputs() {
+  return Inputs.omit("prompt").assert({
+    model: core.getInput("model") || undefined,
+    mode: core.getInput("mode") || undefined,
+    timeout: core.getInput("timeout") || undefined,
+    cwd: core.getInput("cwd") || undefined,
+    push: core.getInput("push") || undefined,
+    shell: core.getInput("shell") || undefined,
+    scan_scope: core.getInput("scan_scope") || undefined,
+    iac_languages: core.getInput("iac_languages") || undefined,
+    language: core.getInput("language") || undefined,
+    severity_threshold: core.getInput("severity_threshold") || undefined,
+    concern_ids: core.getInput("concern_ids") || undefined,
+    grouping: core.getInput("grouping") || undefined,
+    max_prs: core.getInput("max_prs") || undefined,
+    max_run_tokens: core.getInput("max_run_tokens") || undefined,
+    pr_concurrent_limit: core.getInput("pr_concurrent_limit") || undefined,
+    pr_hourly_limit: core.getInput("pr_hourly_limit") || undefined,
+    allowed_paths: core.getInput("allowed_paths") || undefined,
+    base_branch: core.getInput("base_branch") || undefined,
+    allow_replace: core.getInput("allow_replace") || undefined,
+    protected_paths: core.getInput("protected_paths") || undefined,
+    autonomy_threshold: core.getInput("autonomy_threshold") || undefined,
+    required_controls: core.getInput("required_controls") || undefined,
+    gitleaks: core.getInput("gitleaks") || undefined,
+    cost_increase_block_usd:
+      core.getInput("cost_increase_block_usd") || undefined,
+    module_catalogue: core.getInput("module_catalogue") || undefined,
+    terratest: core.getInput("terratest") || undefined,
+    docs: core.getInput("docs") || undefined,
+    terraform_mcp: core.getInput("terraform_mcp") || undefined,
+    opentofu_mcp: core.getInput("opentofu_mcp") || undefined,
+    fix_memory: core.getInput("fix_memory") || undefined,
+    tools_enabled: core.getInput("tools_enabled") || undefined,
+    tools_network: core.getInput("tools_network") || undefined,
+    module_fetch_token: core.getInput("module_fetch_token") || undefined,
+    module_fetch_ssh_key: core.getInput("module_fetch_ssh_key") || undefined,
+    registry_token: core.getInput("registry_token") || undefined,
+    registry_host: core.getInput("registry_host") || undefined,
+    refactor_source: core.getInput("refactor_source") || undefined,
+    review_instructions: core.getInput("review_instructions") || undefined,
+    fp_filtering_instructions:
+      core.getInput("fp_filtering_instructions") || undefined,
+    remediation_instructions:
+      core.getInput("remediation_instructions") || undefined,
+    refactor_instructions: core.getInput("refactor_instructions") || undefined,
+    api_token: core.getInput("api_token") || undefined,
+  });
+}
+
+/**
+ * Short aliases the control plane may send for a mode, mapped to the canonical
+ * built-in name. The Cloud dispatch contract uses the terse `refresh` for the
+ * RefreshRemediation sweep (see infraweaver-ui `remediation-dispatch.ts`'s
+ * `DispatchMode`); accepting it here lets a listener workflow forward
+ * `client_payload.mode` verbatim instead of every consumer having to know the
+ * engine's exact casing. Keyed lowercase.
+ */
+const MODE_ALIASES: Readonly<Record<string, string>> = {
+  refresh: "RefreshRemediation",
+  moduleupgrade: "UpdateDependencies",
+  modernize: "ModernizeDeprecated",
+  costoptimisation: "CostOptimization",
+  tfreview: "TerraformCodeReview",
+  terraformreview: "TerraformCodeReview",
+  drift: "DriftDetect",
+  driftcheck: "DriftDetect",
+  compliance: "ComplianceAudit",
+};
+
+/**
+ * Canonicalize the `mode` input against the built-in mode names
+ * (case-insensitive), resolving any control-plane alias first. Returns the
+ * canonical name (e.g. "remediate" → "Remediate", "refresh" →
+ * "RefreshRemediation") when it matches a built-in mode, letting CI pin a mode
+ * deterministically. Unknown non-empty values warn and return undefined so the
+ * agent falls back to prompt-driven `select_mode` — mirroring how an unknown
+ * `model` slug degrades to auto-select rather than hard-failing the run.
+ */
+export function parseMode(raw: string | undefined): string | undefined {
+  const v = raw?.trim();
+  if (!v) return undefined;
+  const canonical = MODE_ALIASES[v.toLowerCase()] ?? v;
+  const match = BUILTIN_MODE_NAMES.find(
+    (name) => name.toLowerCase() === canonical.toLowerCase(),
+  );
+  if (!match) {
+    log.warning(
+      `» unknown mode "${v}" — agent will select a mode (valid: ${BUILTIN_MODE_NAMES.join(", ")})`,
+    );
+    return undefined;
+  }
+  return match;
+}
+
+/** parse scan_scope; "diff" or "full" (default). */
+function parseScanScope(raw: string | undefined): "diff" | "full" | undefined {
+  const v = raw?.trim().toLowerCase();
+  return v === "diff" || v === "full" ? v : undefined;
+}
+
+/** parse the remediation grouping strategy; "file" (default — one PR per file,
+ * smaller blast radius) or "rule" (one PR per rule across files — for sweeping,
+ * low-risk fixes). undefined when unset/invalid, so the consumer default applies. */
+function parseGrouping(raw: string | undefined): "file" | "rule" | undefined {
+  const v = raw?.trim().toLowerCase();
+  return v === "file" || v === "rule" ? v : undefined;
+}
+
+/** parse the comma-separated `concern_ids` focus list — the specific concern ids a
+ * dashboard "Remediate" dispatch targets. Structured scope (like severity/paths),
+ * NOT task text. undefined when unset. */
+export function parseConcernIds(raw: string | undefined): string[] | undefined {
+  if (!raw) return undefined;
+  const ids = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return ids.length > 0 ? ids : undefined;
+}
+
+/**
+ * Append an engine-owned "fix exactly these concern ids" directive to a Remediate
+ * run's task when the dispatch targeted specific findings (the Cloud "Remediate"
+ * button). The task text stays engine-owned — only the id list comes from the
+ * trusted dispatch — so this narrows scope without letting a customer author the
+ * prompt. A no-op when there are no targeted ids.
+ */
+export function withConcernFocus(
+  prompt: string,
+  concernIds: string[] | undefined,
+): string {
+  if (!concernIds?.length) return prompt;
+  return [
+    prompt,
+    "",
+    "TARGETED FINDINGS — this run was dispatched to remediate specific concern(s).",
+    `Act ONLY on the group(s) that contain these concern ids: ${concernIds.join(", ")}.`,
+    "Do not act on any other group — not even a higher-severity one — and do not widen",
+    "the scope. Fix exactly these concerns, prove each ✗ → ✓ by re-scanning, and open",
+    "one scoped PR for them.",
+  ].join("\n");
+}
+
+/**
+ * The five module-source variants a Refactor run can be pinned to. `auto` (the
+ * default) lets the engine pick the lowest-risk BEHAVIOUR-PRESERVING source
+ * (b.2 → b.1 → b.3) and deliberately excludes the behaviour-altering b.4. The
+ * other four map 1:1 onto the spec's b-variants and let the operator force one:
+ *   - `same-repo`   → b.2 (a module already in this repo, `./modules/x`)
+ *   - `org-repo`    → b.1 (a module in a separate org repo, fetched read-only)
+ *   - `author`      → b.3 (mechanically extract a new module)
+ *   - `third-party` → b.4 (adopt a registry/community module — ALTERS behaviour)
+ * The value is structured SCOPE, never task text: the engine still owns the
+ * Refactor prompt (the security boundary), and this only narrows which source
+ * the agent may resolve to. See {@link withRefactorSource}.
+ */
+export type RefactorSource =
+  | "auto"
+  | "same-repo"
+  | "org-repo"
+  | "author"
+  | "third-party";
+
+const REFACTOR_SOURCE_VALUES = new Set<RefactorSource>([
+  "auto",
+  "same-repo",
+  "org-repo",
+  "author",
+  "third-party",
+]);
+
+/** Aliases the control plane / a workflow may use for a refactor_source value,
+ * mapped to the canonical token. Lets the Cloud picker and a human workflow use
+ * the variant ids (b1/b2/…) or friendlier words interchangeably. Keyed lowercase. */
+const REFACTOR_SOURCE_ALIASES: Readonly<Record<string, RefactorSource>> = {
+  b2: "same-repo",
+  "same-repo-module": "same-repo",
+  local: "same-repo",
+  b1: "org-repo",
+  "org-module-repo": "org-repo",
+  git: "org-repo",
+  "cross-repo": "org-repo",
+  b3: "author",
+  "author-module": "author",
+  new: "author",
+  extract: "author",
+  b4: "third-party",
+  thirdparty: "third-party",
+  registry: "third-party",
+  external: "third-party",
+};
+
+/** parse the `refactor_source` input into a canonical {@link RefactorSource}.
+ * Unset → undefined (the consumer treats that as `auto`). An unknown value
+ * warns and falls back to `auto` rather than hard-failing the run (mirrors how
+ * an unknown `mode`/`model` degrades). */
+export function parseRefactorSource(
+  raw: string | undefined,
+): RefactorSource | undefined {
+  const v = raw?.trim().toLowerCase();
+  if (!v) return undefined;
+  if (REFACTOR_SOURCE_VALUES.has(v as RefactorSource))
+    return v as RefactorSource;
+  const aliased = REFACTOR_SOURCE_ALIASES[v];
+  if (aliased) return aliased;
+  log.warning(
+    `» unknown refactor_source "${raw}" — defaulting to auto (valid: auto, same-repo, org-repo, author, third-party)`,
+  );
+  return "auto";
+}
+
+/** the engine-owned directive appended for each pinned variant — the structured
+ * counterpart of the variant text already in the vetted Refactor prompt. */
+const REFACTOR_SOURCE_DIRECTIVES: Readonly<Record<RefactorSource, string>> = {
+  auto: [
+    "Resolve the module source automatically, lowest risk first: a module that already",
+    "exists in THIS repo (b.2), else one in a separate org repo fetched READ-ONLY (b.1),",
+    "else author a new one by mechanical extraction (b.3). Do NOT adopt a third-party /",
+    "registry module (b.4): that ALTERS behaviour and is only permitted when the operator",
+    "explicitly sets refactor_source to `third-party`. Ship only a refactor proven equivalent.",
+  ].join("\n"),
+  "same-repo": [
+    "Use ONLY a module that already exists in THIS repository (variant b.2 — a local",
+    "`./modules/x` path, candidate `kind: local`). Do not author a new module, reach into",
+    "another repo, or adopt a registry module. If no suitable in-repo module matches the",
+    "cluster, report that and stop — do not fall back to another variant.",
+  ].join("\n"),
+  "org-repo": [
+    "Use ONLY a module from the organisation's SEPARATE module repository (variant b.1 —",
+    "a `git::…?ref=<pinned-sha>` source, candidate `kind: git`), fetched READ-ONLY via the",
+    "supplied module-fetch credential. ⚠️ NEVER open a write PR against that module repo and",
+    "NEVER edit its vendored code — fix any module-internal concern at the CALL SITE via",
+    "inputs, or flag `fix needed in module repo <repo>`. If no org module matches, report and stop.",
+  ].join("\n"),
+  author: [
+    "AUTHOR a new module by MECHANICAL extraction (variant b.3): move the cluster's existing",
+    "resource blocks verbatim into `./modules/<name>/`, parameterise each hardcoded value into",
+    "a `variable` with a SECURE default (or no default), expose the needed `output`s, and",
+    "replace the root resources with a `module` call passing the original values. Do not adopt",
+    "an external module; the equivalence check is the guardrail that proves you changed nothing.",
+  ].join("\n"),
+  "third-party": [
+    "Adopt a THIRD-PARTY / registry module (variant b.4). This ALTERS behaviour: equivalence",
+    "is FALSE and must NEVER be claimed. Follow the b.4 path — scan with external-module",
+    "resolution ON (no finding-laundering), remediate module-sourced findings via INPUTS",
+    "(`needs-fork` where no knob exists), pin the EXACT version (provenance), and ship",
+    "`proposed — unproven` by default (banner + label), or a reviewed plan delta with opt-in creds.",
+  ].join("\n"),
+};
+
+/**
+ * Append the engine-owned module-source directive to a Refactor run's task when
+ * the operator pinned a `refactor_source` variant (the Cloud refactor picker, or
+ * the `refactor_source` action input). The task text stays engine-owned — only
+ * the enum comes from the trusted dispatch/input — so this narrows WHICH source
+ * the agent may resolve to without letting a customer author the prompt (the same
+ * boundary as {@link withConcernFocus}). A no-op when the variant is unset (the
+ * vetted prompt's own risk-ordered guidance applies).
+ */
+export function withRefactorSource(
+  prompt: string,
+  source: RefactorSource | undefined,
+): string {
+  if (!source) return prompt;
+  return [
+    prompt,
+    "",
+    `PINNED MODULE SOURCE — this run was dispatched with refactor_source: ${source}.`,
+    REFACTOR_SOURCE_DIRECTIVES[source],
+  ].join("\n");
+}
+
+/**
+ * The languages a run's user-facing PROSE can be written in. English is the
+ * source/default; the others are the L1 marketing languages (see
+ * `docs/I18N-AND-MULTI-REGION-PLAN.md` A.5). This governs LLM-authored
+ * explanations only — never the Terraform, the identifiers, or the evidence.
+ */
+export type UserFacingLanguage = "en" | "de" | "es" | "pl" | "ro";
+
+/** English display name of each language, used in the vetted directive. */
+const LANGUAGE_NAMES: Readonly<Record<UserFacingLanguage, string>> = {
+  en: "English",
+  de: "German",
+  es: "Spanish",
+  pl: "Polish",
+  ro: "Romanian",
+};
+
+/** Friendly aliases the control plane / a workflow may send, mapped to the code.
+ *  Keyed lowercase; an `en-*`/`de-*` regional tag collapses to its base language. */
+const LANGUAGE_ALIASES: Readonly<Record<string, UserFacingLanguage>> = {
+  english: "en",
+  german: "de",
+  deutsch: "de",
+  spanish: "es",
+  espanol: "es",
+  castellano: "es",
+  polish: "pl",
+  polski: "pl",
+  romanian: "ro",
+  romana: "ro",
+};
+
+/** parse the `language:` input into a {@link UserFacingLanguage}. Unset → "en".
+ * Accepts a code (`de`), a regional tag (`de-DE`), or a name (`German`). An
+ * unknown value warns and falls back to "en" rather than hard-failing the run —
+ * mirroring how an unknown `mode`/`model`/`refactor_source` degrades. */
+export function parseLanguage(raw: string | undefined): UserFacingLanguage {
+  const v = raw?.trim().toLowerCase();
+  if (!v) return "en";
+  const base = v.split(/[-_]/)[0] ?? v;
+  if (base in LANGUAGE_NAMES) return base as UserFacingLanguage;
+  const aliased = LANGUAGE_ALIASES[v] ?? LANGUAGE_ALIASES[base];
+  if (aliased) return aliased;
+  log.warning(
+    `» unknown language "${raw}" — writing user-facing prose in English (valid: ${Object.keys(LANGUAGE_NAMES).join(", ")})`,
+  );
+  return "en";
+}
+
+/**
+ * Append the engine-owned "write user-facing prose in <language>" directive to a
+ * run's task. Structured enum input, never workflow prose — the engine still owns
+ * the prompt (the security boundary, same as {@link withConcernFocus} /
+ * {@link withRefactorSource}). A no-op for English (the default), so existing runs
+ * are byte-for-byte unchanged. The directive is glossary-aware: it localizes the
+ * EXPLANATIONS a human reads and holds every identifier, code block, path, rule
+ * id, control name, and the product terms verbatim in English — so a translated
+ * PR body never corrupts the Terraform it describes.
+ */
+export function withLanguageDirective(
+  prompt: string,
+  language: UserFacingLanguage,
+): string {
+  if (language === "en") return prompt;
+  const name = LANGUAGE_NAMES[language];
+  return [
+    prompt,
+    "",
+    `USER-FACING LANGUAGE — write every explanation meant for a human reader (PR titles and`,
+    `bodies, review-comment text, issue / dashboard notes, and the run summary) in ${name}.`,
+    "This governs PROSE ONLY. Keep verbatim, in English: all Terraform identifiers and resource",
+    "addresses, every code block / diff / file path / CLI command / log excerpt, scanner rule",
+    "ids, severity tokens, and compliance control and framework names. Never translate the",
+    `product names ${PRODUCT_NAME}, Remediate, Assess, or Refactor. Where ${name} has no established`,
+    "technical term, keep the English one rather than inventing a translation.",
+  ].join("\n");
+}
+
+const SEVERITY_VALUES = new Set(["critical", "high", "medium", "low", "info"]);
+
+/** parse the severity_threshold input; undefined when unset or not a valid level. */
+function parseSeverityThreshold(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  const v = raw.trim().toLowerCase();
+  return SEVERITY_VALUES.has(v) ? v : undefined;
+}
+
+/** parse max_prs; a positive integer, else undefined (downstream default is 1). */
+function parseMaxPrs(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = Number.parseInt(raw.trim(), 10);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
+/** parse a PR-flood limit (pr_concurrent_limit / pr_hourly_limit): a non-negative
+ * integer where 0 means "unlimited". undefined when unset or invalid, so the
+ * downstream default applies. */
+function parsePrLimit(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = Number.parseInt(raw.trim(), 10);
+  return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+
+/** parse cost_increase_block_usd; a positive number of dollars/month, else
+ * undefined (no cost escalation). */
+function parseCostIncreaseBlock(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = Number.parseFloat(raw.trim());
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/** 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
+ * `.infraweaver.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(/[\n,]/)
+    .map((g) => g.trim())
+    .filter(Boolean);
+  return globs.length > 0 ? globs : undefined;
+}
+
+/** parse a boolean-ish action input ("true"/"1"/"yes" → true). undefined/unset
+ * and any other value → false. */
+function parseBooleanInput(raw: string | undefined): boolean {
+  if (!raw) return false;
+  return ["true", "1", "yes", "on"].includes(raw.trim().toLowerCase());
+}
+
+/** parse the base_branch override; trims and strips a leading `refs/heads/`,
+ * undefined when unset (downstream resolves the run-start branch / default). */
+export function parseBaseBranch(raw: string | undefined): string | undefined {
+  const v = raw?.trim().replace(/^refs\/heads\//, "");
+  return v || undefined;
+}
+
+/** parse the comma-separated allow_replace list — resource addresses (or globs,
+ * or `*`/`all`) permitted to be destroyed/replaced; undefined when unset. */
+export function parseAllowReplace(
+  raw: string | undefined,
+): string[] | undefined {
+  if (!raw) return undefined;
+  const entries = raw
+    .split(",")
+    .map((a) => a.trim())
+    .filter(Boolean);
+  return entries.length > 0 ? entries : undefined;
+}
+
+/**
+ * true when `actor` is Infraweaver's own GitHub identity — the bot login
+ * (`infraweaver[bot]` / `infraweaverdev[bot]`) or the bare account. used to skip
+ * self-triggered events and to recognise Infraweaver-originated review threads
+ * (the never-approve-with-outstanding-findings gate). matches with or without
+ * the `[bot]` suffix since GraphQL and REST report the login differently.
+ */
+export const isInfraweaver = (actor: string | null | undefined): boolean => {
+  actor = actor?.replace("[bot]", "");
+  return !!actor && (actor === PRODUCT_SLUG || actor === `${PRODUCT_SLUG}dev`);
+};
+
+/** Union the locally-configured required controls (action input / `.infraweaver.yml`)
+ *  with the org's Cloud "required controls" policy (delivered over run-context).
+ *  Either source can mandate a control; both are the org's own settings. Undefined
+ *  when both are empty, to preserve the "no policy" shape the gate treats as a no-op. */
+function mergeRequiredControls(
+  local: string[] | undefined,
+  org: string[],
+): string[] | undefined {
+  const merged = [...new Set([...(local ?? []), ...org])];
+  return merged.length ? merged : undefined;
+}
+
+export function resolvePayload(
+  resolvedPromptInput: ResolvedPromptInput,
+  repoSettings: RepoSettings,
+  /** The org's mandatory pack-control ids from the Cloud run-context (org-scoped).
+   *  Merged with the local `required_controls` so the dashboard policy gates CI. */
+  orgRequiredControls: string[] = [],
+  /** Cloud-managed module credentials from the run-context (the dashboard Refactor
+   *  dialog). A FALLBACK only — an explicit `module_fetch_token` / `registry_token`
+   *  input always wins. undefined when none are stored for the repo. */
+  managedCredentials?: { moduleFetchToken?: string; registryToken?: string },
+) {
+  const [rawPrompt, jsonPayload] =
+    typeof resolvedPromptInput !== "string"
+      ? [resolvedPromptInput.prompt, resolvedPromptInput]
+      : [resolvedPromptInput, undefined];
+
+  const inputs = resolveNonPromptInputs();
+
+  // Deterministic mode pin for CI (action input only). Resolved here so the prompt
+  // can be locked to the mode's vetted standard below.
+  const mode = parseMode(inputs.mode);
+
+  // A `@infraweaver fix …` command parsed from the (raw) prompt — parse from rawPrompt
+  // so the comment-driven flow survives the vetted-prompt override below.
+  const remediationCommand = parseRemediationCommand(rawPrompt);
+
+  // For a pinned vetted mode the engine owns the prompt (free-form workflow prompt
+  // ignored); a recognised fix-command and the trusted JSON dispatch payload pass
+  // through. Otherwise the workflow prompt is used and required.
+  const basePrompt = resolveEffectivePrompt(
+    rawPrompt,
+    jsonPayload !== undefined,
+    mode,
+    remediationCommand !== null,
+  );
+  // A dashboard "Remediate" dispatch targets specific findings via the structured
+  // `concern_ids` input (NOT prose). Narrow the engine-owned Remediate task to
+  // those concerns; the comment-command path carries its own scope, so skip it there.
+  const concernIds = parseConcernIds(inputs.concern_ids);
+  // a pinned module-source variant (the Cloud refactor picker / `refactor_source`
+  // input) narrows the engine-owned Refactor task to one b-variant — structured
+  // scope, not prose. Applies to Refactor and the combined Remediate+Refactor mode.
+  const refactorSource = parseRefactorSource(inputs.refactor_source);
+  const wantsConcernFocus =
+    (mode === "Remediate" || mode === "RemediateAndRefactor") &&
+    remediationCommand === null;
+  const wantsRefactorSource =
+    mode === "Refactor" || mode === "RemediateAndRefactor";
+  let prompt = basePrompt;
+  if (wantsConcernFocus) prompt = withConcernFocus(prompt, concernIds);
+  if (wantsRefactorSource) prompt = withRefactorSource(prompt, refactorSource);
+
+  // Mask credential inputs in logs the moment we read them — GitHub only auto-masks
+  // registered secrets, not arbitrary input values, so a token passed inline (or
+  // echoed by a debug line) would otherwise leak. Covers the Cloud org token and the
+  // private-module credentials (git-transport + private-registry).
+  for (const secret of [
+    inputs.api_token,
+    inputs.module_fetch_token,
+    inputs.module_fetch_ssh_key,
+    inputs.registry_token,
+  ]) {
+    if (secret) core.setSecret(secret);
+  }
+
+  // resolve event - use type guard for jsonPayload.event, fallback to unknown trigger
+  const rawEvent = jsonPayload?.event;
+  const event: PayloadEvent = isPayloadEvent(rawEvent)
+    ? rawEvent
+    : { trigger: "unknown" };
+
+  const model =
+    jsonPayload?.model ?? inputs.model ?? repoSettings.model ?? undefined;
+
+  // determine shell permission - strictest setting wins
+  // precedence: disabled > restricted > enabled
+  // non-collaborators always get at least "restricted"
+  const isNonCollaborator = !isCollaborator(event);
+  const repoShell = repoSettings.shell ?? "restricted";
+  const inputShell = inputs.shell;
+
+  // resolve shell: start with repo setting, then apply restrictions
+  let resolvedShell = repoShell;
+
+  // input can only make it stricter (disabled > restricted > enabled)
+  if (inputShell === "disabled") {
+    resolvedShell = "disabled";
+  } else if (inputShell === "restricted" && resolvedShell === "enabled") {
+    resolvedShell = "restricted";
+  }
+
+  // non-collaborators get at least "restricted" (can't have "enabled")
+  if (isNonCollaborator && resolvedShell === "enabled") {
+    resolvedShell = "restricted";
+  }
+
+  const cwd = resolveCwd(inputs.cwd);
+  // repo-committed `.infraweaver.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/infraweaverConfig.ts for the trust boundary + supported keys.
+  //
+  // On a PULL-REQUEST run the checked-out ref is the PR's own head, so the
+  // GATE-relevant keys are re-resolved from the base ref: a PR must not be able
+  // to widen `allowed_paths`, empty `required_controls`, raise
+  // `severity_threshold` or disable a scanner in the very run that reviews it.
+  // Presentational keys still come from the head. Degrades honestly (keeps the
+  // head value + logs) when the base ref isn't fetched. See utils/baseRefConfig.ts.
+  const fileConfig = applyBaseRefConfigPolicy({
+    cwd,
+    headValues: loadInfraweaverConfig(cwd),
+    baseRef: process.env.GITHUB_BASE_REF?.trim() || undefined,
+  });
+
+  // Language for user-facing prose (input wins, then `.infraweaver.yml`). Appended
+  // as an engine-owned directive to the run's task (all modes + free-form), since
+  // it only governs the language of the explanations the run writes back. A no-op
+  // for the default English, so existing runs are byte-for-byte unchanged.
+  const language = parseLanguage(inputs.language ?? fileConfig.language);
+  prompt = withLanguageDirective(prompt, language);
+
+  // build payload - precedence: inputs > .infraweaver.yml > repoSettings > fallbacks
+  // note: modes are NOT in payload - they come from repoSettings in main()
+  return {
+    "~infraweaver": true as const,
+    version: jsonPayload?.version ?? packageJson.version,
+    model,
+    // deterministic mode pin for CI (action input only — not accepted from the
+    // JSON payload, which is the internal dispatch surface). undefined → the
+    // agent chooses via select_mode as before.
+    mode,
+    prompt,
+    triggerer:
+      jsonPayload?.triggerer ??
+      // it's not a common use case but GITHUB_ACTOR can be a user when the workflow is manually triggered by a user through GitHub Actions UI
+      (!isInfraweaver(process.env.GITHUB_ACTOR)
+        ? process.env.GITHUB_ACTOR
+        : undefined),
+    eventInstructions: jsonPayload?.eventInstructions,
+    previousRunsNote: jsonPayload?.previousRunsNote,
+    event,
+    timeout: inputs.timeout ?? jsonPayload?.timeout,
+    cwd,
+    progressComment: jsonPayload?.progressComment,
+    generateSummary: jsonPayload?.generateSummary,
+
+    // permissions: inputs > repoSettings > fallbacks
+    push: inputs.push ?? repoSettings.push ?? "restricted",
+    shell: resolvedShell,
+
+    // 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.
+    // Terraform policy fields accept a `.infraweaver.yml` fallback (input wins).
+    scanScope: parseScanScope(inputs.scan_scope ?? fileConfig.scan_scope),
+    // multi-language Assess scope for the READ-ONLY surfaces only. Raw string
+    // ("auto" | "terraform" | comma list); resolved against the tree by
+    // resolveLanguageScope at scan time. Input wins, then `.infraweaver.yml`.
+    // undefined → "auto" at the consumer. The fix loop ignores this (Terraform-first).
+    iacLanguages:
+      (inputs.iac_languages ?? fileConfig.iac_languages)?.trim() || undefined,
+    severityThreshold: parseSeverityThreshold(
+      inputs.severity_threshold ?? fileConfig.severity_threshold,
+    ),
+    // repo-wide default remediation grouping (input wins, then the
+    // `.infraweaver.yml`/`.json` file). A per-scan `group_by` tool arg still wins
+    // over this. undefined → the consumer default ("file").
+    grouping: parseGrouping(inputs.grouping ?? fileConfig.grouping),
+    // specific concern ids a dashboard "Remediate" dispatch targets — narrows the
+    // run to the group(s) containing them (folded into the task by withConcernFocus
+    // above). Action-input only (not the untrusted repo file). undefined → the
+    // engine acts on the highest-severity group as usual.
+    concernIds,
+    maxPrs: parseMaxPrs(inputs.max_prs),
+    // LLM10 per-run token ceiling. Action-input only, like the PR-flood guards
+    // below and TC-0.2's `tools_network`: a safety limit a pull request could
+    // raise from `.infraweaver.yml` in the run that reviews it is not a limit.
+    maxRunTokens: parseRunTokenQuota(inputs.max_run_tokens),
+    // Cross-run PR-flood guards (action-input only, like max_prs — deliberately
+    // NOT read from the untrusted repo file, so a malicious PR can't loosen them).
+    // prConcurrentLimit caps simultaneously-open remediation PRs (consumer default
+    // 10); prHourlyLimit caps creation velocity (consumer default 0 = off). 0 =
+    // unlimited for both. See guardrails.assertUnderOpenPrCaps.
+    prConcurrentLimit: parsePrLimit(inputs.pr_concurrent_limit),
+    prHourlyLimit: parsePrLimit(inputs.pr_hourly_limit),
+    allowedPaths: parseGlobList(
+      inputs.allowed_paths ?? fileConfig.allowed_paths,
+    ),
+    // globs the fixer must never auto-modify (inverse of allowed_paths).
+    protectedPaths: parseGlobList(
+      inputs.protected_paths ?? fileConfig.protected_paths,
+    ),
+    // minimum severity at which a security concern escalates to a human.
+    autonomyThreshold: parseSeverityThreshold(
+      inputs.autonomy_threshold ?? fileConfig.autonomy_threshold,
+    ),
+    // compliance controls that must have NO open finding — a finding mapping to
+    // one fails the gate regardless of severity (the "required controls" policy:
+    // binds the crosswalk to the gate). Matched by framework / control /
+    // `framework|control` / title / theme / Cloud pack id. The local config (input
+    // > `.infraweaver.yml`) is UNIONED with the org's Cloud policy (run-context).
+    requiredControls: mergeRequiredControls(
+      parseGlobList(inputs.required_controls ?? fileConfig.required_controls),
+      orgRequiredControls,
+    ),
+    // 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),
+    // monthly $ increase at/above which a fix is escalated to a
+    // human (needs-human). undefined disables cost escalation.
+    costIncreaseBlockUsd: parseCostIncreaseBlock(
+      inputs.cost_increase_block_usd,
+    ),
+    // operator-approved modules a fix/generation
+    // should prefer; raw string, structured by `parseModuleCatalogue` in the
+    // `list_modules` tool.
+    moduleCatalogue: inputs.module_catalogue ?? fileConfig.module_catalogue,
+    // 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.
+    terratest: parseBooleanInput(inputs.terratest),
+    // opt in to evidence-backed module README generation on the refactor
+    // flow (terraform_module_docs); also widens the push allow-list to the
+    // DOCS_ALLOWED_PATHS carve-out (module READMEs + docs/infraweaver only).
+    docs: parseBooleanInput(inputs.docs),
+    // opt in to HashiCorp's terraform-mcp-server as a second MCP server
+    // for the agent (live Terraform Registry knowledge: current module versions
+    // 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),
+    // opt in to the OpenTofu Registry MCP server (registry knowledge for an
+    // OpenTofu repo) — the permissively-licensed sibling to terraform_mcp,
+    // reached at OpenTofu's hosted endpoint (no docker, no credentials). See
+    // utils/opentofuMcp.ts.
+    opentofuMcp: parseBooleanInput(inputs.opentofu_mcp),
+    // language for user-facing prose the run authors (PR bodies, review text, run
+    // summary, dashboard note). Folded into the engine-owned task by
+    // withLanguageDirective above; also threaded to the fixed-scaffolding renderers
+    // (buildDashboardBody) so section headers match. Input wins, then `.infraweaver.yml`.
+    // "en" default → no behaviour change. Never governs the Terraform itself.
+    language,
+    // §5.12 opt in to reusable proven-fix memory: capture the transformation of
+    // each finding-type that goes ✗→✓, and offer it as a proven prior when the
+    // same finding-type recurs (still re-scanning ✗→✓ per target, never
+    // blind-applying). The fleet library rides the Cloud report/run-context;
+    // a local `.infraweaver.fix-memory.json` is also read when present.
+    fixMemory: parseBooleanInput(inputs.fix_memory),
+    // 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,
+    ),
+    // per-scanner egress policy (supply-chain 0.2). Deliberately INPUT-ONLY,
+    // never `.infraweaver.yml`: a security posture must belong to the workflow
+    // that dispatches the run, not to a file the scanned ref can edit.
+    toolsNetwork: inputs.tools_network
+      ? parseToolsNetwork(inputs.tools_network)
+      : undefined,
+    // 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. The
+    // action input wins; a Cloud-managed credential (from the run-context, set in
+    // the dashboard Refactor dialog) is the fallback when no input was supplied.
+    moduleFetchToken:
+      inputs.module_fetch_token ?? managedCredentials?.moduleFetchToken,
+    // private-key counterpart for `git::ssh://…` / deploy-key module sources;
+    // written 0600 into the run tmpdir and exposed via a scoped GIT_SSH_COMMAND
+    // (resolveModuleFetchEnv), never the home dir or a committed path.
+    moduleFetchSshKey: inputs.module_fetch_ssh_key,
+    // scoped bearer token to fetch a private Terraform REGISTRY module (the
+    // refactor b.4 shape) at terraform init/plan. Re-admitted per-subprocess as
+    // `TF_TOKEN_<host>` by resolveRegistryTokenEnv (utils/registryAuth.ts); never
+    // persisted. `registryHost` names the host(s) it authorises (default: HCP).
+    // Action input wins; the Cloud-managed credential is the fallback.
+    registryToken: inputs.registry_token ?? managedCredentials?.registryToken,
+    registryHost: inputs.registry_host,
+    // which module-source variant a Refactor (or combined Remediate+Refactor) run
+    // is pinned to (auto | same-repo | org-repo | author | third-party). Folded
+    // into the engine-owned task by withRefactorSource above; also read by the
+    // Refactor mode for the b.4 consent gate. undefined → auto. Action-input/
+    // trusted-dispatch only (not the untrusted repo file).
+    refactorSource,
+    // a `@infraweaver fix …` command parsed from the triggering comment
+    // body (the raw prompt), scoping the run to a specific concern/severity/file.
+    // null when the prompt isn't a recognised command.
+    remediationCommand,
+    // explicit base-branch override; when unset the effective base is resolved
+    // at PR time (run-start branch → repo default) — see resolveBaseBranch.
+    baseBranch: parseBaseBranch(inputs.base_branch),
+    // resource addresses the operator allows the remediation to destroy/replace
+    // — consumed by the destroy-block guardrail (mcp/guardrails.ts). Unset means
+    // no destructive change to a stateful resource is permitted.
+    allowReplace: parseAllowReplace(inputs.allow_replace),
+    // org-specific review policy + FP precedents from the workflow file
+    // (owner-controlled, same trust surface as repo settings). merged into the
+    // Review mode instructions in main() via mergeReviewModeInstructions.
+    reviewInstructions: inputs.review_instructions,
+    fpFilteringInstructions: inputs.fp_filtering_instructions,
+    // org-specific remediation/refactor policy — the same composable pattern,
+    // for the pinned Terraform-write modes: appended under a fixed heading via
+    // mergeRemediationModeInstructions in main(); NEVER replaces the vetted
+    // standard and does not reopen the free-form-prompt path.
+    remediationInstructions: inputs.remediation_instructions,
+    refactorInstructions: inputs.refactor_instructions,
+    // Infraweaver Cloud org token — read by finalizeSuccessRun to report this run
+    // to Cloud (utils/cloudReport.ts). Already masked above.
+    cloudApiToken: inputs.api_token,
+  };
+}
+
+export type ResolvedPayload = ReturnType<typeof resolvePayload>;
+
+/**
+ * Parse and validate the optional `output_schema` action input. Returns the
+ * parsed object when present, or `undefined` when absent. Throws on invalid
+ * JSON or non-object payloads — these are workflow-author errors that should
+ * surface immediately, not silently degrade to "no schema".
+ */
+export function resolveOutputSchema(): Record<string, unknown> | undefined {
+  const raw = core.getInput("output_schema");
+  if (!raw) return undefined;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`invalid output_schema: not valid JSON`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`invalid output_schema: must be a JSON object`);
+  }
+  log.info("» structured output schema provided — output will be required");
+  return parsed as Record<string, unknown>;
+}