ADR 0008 human in the loop remediation

ADR-0008: Human-in-the-loop & remediation posture (selectable)

Status: Accepted (2026-07-23)

Context

Much of the responsible-AI stance is already structurally enforced:

• The agent cannot mutate the reviewed environment — ADR-0007 makes writes to the target account impossible by construction.
• It cannot mutate the human Well-Architected record — judgment answers are proposed, not written; scanner-backed answers go only to the automation's own workload (ADR-0006).

What remains for this ADR is to (a) name the responsible-AI controls explicitly, and (b) settle the one genuinely-open decision: whether the agent proposes remediation as code, or only as guidance. Both are wanted, selectable per run.

Decision drivers

• Agent proposes, humans dispose — nothing reaches the environment or the human record without a human decision.
• Actionability where it is safe, conservatism where it is not.
• Least-privilege by mode — a capability's credential should exist only when that capability is enabled.
• Attribution, evidence-linkage, reversibility, and human accountability throughout.

Decision

Remediation posture is a per-run / per-target config flag (same pattern as ADR-0002's provider selection): report_only (default) or advisory_pr.

• report_only — findings + prose remediation recommendations. No Git write. Humans implement the fix.
• advisory_pr — additionally opens a draft pull request with proposed Terraform changes, for scanner-backed, high-confidence, deterministic fixes only (e.g. storage_encrypted = true where Checkov flagged it). Never auto-merged. Judgment findings never generate a PR. Human review, CI on the PR, and the normal deploy pipeline are the gate.

The flag also gates the credential. The Git-write scope (create branch + open PR; no merge permission; a fine-grained token / GitHub App) exists only when advisory_pr is enabled, held only by the stage that opens the PR (composes with ADR-0007's per-stage least-privilege). In report_only mode the agent has zero Git-write capability.

Responsible-AI invariants (hold in both modes)

1. No mutation of the reviewed environment — structural (ADR-0007).
2. No auto-merge / no auto-apply — nothing reaches the environment without a human merge and the normal deploy pipeline.
3. Judgment items are proposed only, never auto-actioned (ADR-0006).
4. Human accepted-risk / exception register is honoured — items a human has consciously accepted are not re-flagged every night. Humans own the finding lifecycle; this also prevents alert fatigue.
5. Every automated output is attributed, evidence-linked, and reversible; the LLM never fabricates a "fixed/resolved" status (status claims are audited against scanner evidence); scanner-derived vs judgment is always labelled.
6. Humans own every disposition decision (accept, remediate, defer).

Consequences

• Deployments start conservative and grow into it — run report_only until the reporting core is trusted, then opt individual targets into advisory_pr.
• advisory_pr adds LLM-generated-Terraform risk, bounded on five sides: scanner-backed-only, draft PR, mandatory human review, CI on the PR, and no merge permission. Judgment output never becomes code.
• Least-privilege by mode — Git-write exists only when advisory PRs are on, so the default posture has the smaller attack surface.
• The exception register keeps humans in control of what counts as a finding and prevents recurring-finding fatigue.
• Fully auditable — every proposal (WA answer, notification, PR) is attributed and reversible.

Alternatives considered

Option	Verdict	Why
Selectable report_only / advisory_pr per run	Chosen	Conservative default, actionable when trusted; credential gated by mode.
report_only only	Rejected	Less actionable; the user wants the PR option available.
advisory_pr always-on	Rejected	Git-write credential would exist even when unwanted — larger attack surface by default.
Auto-merge / auto-remediation	Rejected	Violates the stance; ADR-0007 blocks environment writes regardless.
Per-finding human approval before each PR	Viable stricter variant	Revisit if an org requires an explicit gate before any PR is opened.

Revisit trigger

• Expand advisory_pr eligibility beyond scanner-backed fixes once confidence in generated changes is demonstrated.
• Add a per-finding approval gate before a PR is opened if org policy requires human sign-off prior to any automated PR.

References

• ADR-0002 (per-run config-selection pattern reused here)
• ADR-0004 (deterministic-vs-judgment boundary — what is PR-eligible)
• ADR-0006 (proposed-not-written for the human WA record)
• ADR-0007 (no environment write; the optional Git-write is a per-stage scope)
• ADR-0009 (delivery — how recommendations reach humans)