feat(reconciler): :fix_settings action class — natsci-studio calibration (#265) (#271)

Refs #260 / #263 / #265 — **do not auto-close**.

Follow-up increment to merged #264 (which explicitly deferred this).

### Problem (natsci-studio live calibration)
`BranchProtectionID` / `CodeReviewID` were `:open_escalate` — correct
(never silently dropped) but suboptimal: they are
*repository-configuration-actionable* via the GitHub settings API, not
code fixes and not non-actionable. natsci-studio dry-run: alerts #1
BranchProtection / #3 CodeReview should auto-remediate under full-auto.

### Change
Third, narrow action class between `:fix` (code) and `:open_escalate`:
- `classify/2`: `BranchProtectionID`/`CodeReviewID` → `:fix_settings`.
- `reconcile/3`: new `:policy` opt (default `:full_auto`);
`do_fix_settings/3` is an idempotent branch-protection PUT requiring ≥1
PR review on the default branch (satisfies both checks). `:conservative`
escalates instead.
- `mix hypatia.reconcile … --conservative`; summary gains
`settings_remediated`/`settings_actionable`.

### Verification
`mix compile` clean. Full suite **809/809** (+3 new tests).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: hyperpolymath

lib/mix/tasks/hypatia.reconcile.ex

@@ -5,9 +5,16 @@ defmodule Mix.Tasks.Hypatia.Reconcile do
 
   ## Usage
 
-      mix hypatia.reconcile owner/repo            # reconcile + write registry
-      mix hypatia.reconcile owner/repo --dry-run  # classify only, no mutation
-      mix hypatia.reconcile owner/repo --verify   # recurrence-defect check
+      mix hypatia.reconcile owner/repo                # reconcile + write registry
+      mix hypatia.reconcile owner/repo --dry-run      # classify only, no mutation
+      mix hypatia.reconcile owner/repo --verify       # recurrence-defect check
+      mix hypatia.reconcile owner/repo --conservative # escalate :fix_settings
+                                                      # instead of auto-applying
+
+  Policy (#265): default `:full_auto` auto-applies repo-configuration
+  remediations (`:fix_settings` — branch protection / required reviews) via
+  the GitHub settings API. `--conservative` escalates those for human review
+  instead.
 
   Requires `GITHUB_TOKEN` (security_events scope). Non-actionable and
   design-correct-exception findings are dismissed-with-rationale on GitHub
@@ -23,7 +30,9 @@ defmodule Mix.Tasks.Hypatia.Reconcile do
   @impl true
   def run(argv) do
     {opts, rest, _} =
-      OptionParser.parse(argv, switches: [dry_run: :boolean, verify: :boolean])
+      OptionParser.parse(argv,
+        switches: [dry_run: :boolean, verify: :boolean, conservative: :boolean]
+      )
 
     case rest do
       [slug] ->
@@ -34,7 +43,10 @@ defmodule Mix.Tasks.Hypatia.Reconcile do
           if opts[:verify] do
             ScorecardReconciler.verify(owner, repo)
           else
-            ScorecardReconciler.reconcile(owner, repo, dry_run: !!opts[:dry_run])
+            ScorecardReconciler.reconcile(owner, repo,
+              dry_run: !!opts[:dry_run],
+              policy: if(opts[:conservative], do: :conservative, else: :full_auto)
+            )
           end
 
         IO.puts(Jason.encode!(result, pretty: true))

lib/scorecard_reconciler.ex

@@ -48,8 +48,14 @@ defmodule Hypatia.ScorecardReconciler do
   #   :dismiss_accept  — code change *possible* but the canonical remediation
   #                      is HARMFUL / it is correct-by-design. Dismiss
   #                      "won't fix" with rationale. (SLSA pin-exempt)
-  #   :fix             — safe, deterministic remediation exists. Emit a
-  #                      fix-request (PR; auto-merge if CI-green + low-risk).
+  #   :fix             — safe, deterministic *code* remediation exists. Emit
+  #                      a fix-request (PR; auto-merge if CI-green + low-risk).
+  #   :fix_settings    — safe, deterministic *repository-configuration*
+  #                      remediation exists via the GitHub settings API
+  #                      (enable branch protection, require reviews). NOT a
+  #                      code change and NOT non-actionable — a third, narrow
+  #                      action class so config findings are auto-remediated
+  #                      under full-auto policy instead of escalated. (#265)
   #   :open_escalate   — unknown / not safely automatable. Leave OPEN and
   #                      ensure a tracking issue (never silently drop —
   #                      "didn't look" is an escaped-defect KPI breach).
@@ -58,6 +64,12 @@ defmodule Hypatia.ScorecardReconciler do
   # itself states no remediation is needed.
   @info_rules ~w(MaintainedID ContributorsID CITestsID CIIBestPracticesID)
 
+  # Scorecard rules that are repo-CONFIGURATION-actionable: not code, not
+  # non-actionable — deterministically remediable via the GitHub settings
+  # API (#265). Surfaced by the natsci-studio live calibration where these
+  # were being :open_escalate'd despite a safe automatic fix existing.
+  @settings_rules ~w(BranchProtectionID CodeReviewID)
+
   @doc """
   Pure classification of a single code-scanning alert map (as returned by
   the GitHub API). `ctx` may carry `:located_action_ref` — the `uses:` ref
@@ -91,6 +103,14 @@ defmodule Hypatia.ScorecardReconciler do
          "Pin the third-party dependency to a full-length commit SHA " <>
            "(not pin-exempt)."}
 
+      rule in @settings_rules ->
+        {:fix_settings, nil,
+         "Repository-configuration finding `#{rule}` — deterministically " <>
+           "remediable via the GitHub settings API (enable branch " <>
+           "protection / require pull-request reviews on the default " <>
+           "branch). Not a code change and not non-actionable; auto-applied " <>
+           "under full-auto policy, escalated under conservative. (#265)"}
+
       true ->
         {:open_escalate, nil,
          "No safe automated lifecycle action known for rule `#{rule}` — " <>
@@ -118,6 +138,10 @@ defmodule Hypatia.ScorecardReconciler do
   """
   def reconcile(owner, repo, opts \\ []) do
     dry = Keyword.get(opts, :dry_run, false)
+    # :full_auto (default) auto-applies :fix_settings via the settings API;
+    # :conservative escalates settings findings for human review instead of
+    # mutating repo configuration automatically. (#265)
+    policy = Keyword.get(opts, :policy, :full_auto)
 
     case fetch_open_alerts(owner, repo) do
       {:error, reason} ->
@@ -135,11 +159,24 @@ defmodule Hypatia.ScorecardReconciler do
 
             acted =
               cond do
-                dry -> :skipped_dry_run
+                dry ->
+                  :skipped_dry_run
+
                 action in [:dismiss_info, :dismiss_accept] ->
                   do_dismiss(owner, repo, number, reason_code, rationale)
-                action == :fix -> :fix_requested
-                true -> :escalated
+
+                action == :fix ->
+                  :fix_requested
+
+                action == :fix_settings and policy == :full_auto ->
+                  do_fix_settings(owner, repo, alert)
+
+                action == :fix_settings ->
+                  # :conservative — never silently drop; escalate.
+                  :escalated_conservative
+
+                true ->
+                  :escalated
               end
 
             reg_acc =
@@ -163,9 +200,10 @@ defmodule Hypatia.ScorecardReconciler do
           looked: true,
           found: length(alerts),
           classified: length(results),
-          dismissed:
-            Enum.count(results, &(&1.acted in [:dismissed, :already_dismissed])),
+          dismissed: Enum.count(results, &(&1.acted in [:dismissed, :already_dismissed])),
           fix_requested: Enum.count(results, &(&1.action == :fix)),
+          settings_remediated: Enum.count(results, &(&1.acted == :settings_remediated)),
+          settings_actionable: Enum.count(results, &(&1.action == :fix_settings)),
           escalated: Enum.count(results, &(&1.action == :open_escalate)),
           results: results
         }
@@ -185,8 +223,12 @@ defmodule Hypatia.ScorecardReconciler do
         for alert <- alerts,
             entry = Registry.get(reg, fingerprint(owner, repo, alert)),
             entry["action"] in ["dismiss_info", "dismiss_accept"] do
-          %{alert: alert["number"], fp: fingerprint(owner, repo, alert),
-            recurrence_defect: true, prior: entry}
+          %{
+            alert: alert["number"],
+            fp: fingerprint(owner, repo, alert),
+            recurrence_defect: true,
+            prior: entry
+          }
         end
 
       {:ok, %{repo: "#{owner}/#{repo}", recurrence_defects: regressions}}
@@ -205,13 +247,21 @@ defmodule Hypatia.ScorecardReconciler do
         "#{@github_api_base}/repos/#{owner}/#{repo}/code-scanning/alerts" <>
           "?state=open&per_page=#{@max_alerts}"
 
-      case System.cmd("curl", [
-             "-s", "-f",
-             "-H", "Accept: application/vnd.github+json",
-             "-H", "Authorization: Bearer #{token}",
-             "-H", "X-GitHub-Api-Version: 2022-11-28",
-             url
-           ], stderr_to_stdout: true) do
+      case System.cmd(
+             "curl",
+             [
+               "-s",
+               "-f",
+               "-H",
+               "Accept: application/vnd.github+json",
+               "-H",
+               "Authorization: Bearer #{token}",
+               "-H",
+               "X-GitHub-Api-Version: 2022-11-28",
+               url
+             ],
+             stderr_to_stdout: true
+           ) do
         {body, 0} ->
           case Jason.decode(body) do
             {:ok, a} when is_list(a) -> {:ok, a}
@@ -240,20 +290,122 @@ defmodule Hypatia.ScorecardReconciler do
     url =
       "#{@github_api_base}/repos/#{owner}/#{repo}/code-scanning/alerts/#{number}"
 
-    case System.cmd("curl", [
-           "-s", "-f", "-X", "PATCH",
-           "-H", "Accept: application/vnd.github+json",
-           "-H", "Authorization: Bearer #{token}",
-           "-H", "X-GitHub-Api-Version: 2022-11-28",
-           "-d", payload, url
-         ], stderr_to_stdout: true) do
-      {_, 0} -> :dismissed
+    case System.cmd(
+           "curl",
+           [
+             "-s",
+             "-f",
+             "-X",
+             "PATCH",
+             "-H",
+             "Accept: application/vnd.github+json",
+             "-H",
+             "Authorization: Bearer #{token}",
+             "-H",
+             "X-GitHub-Api-Version: 2022-11-28",
+             "-d",
+             payload,
+             url
+           ],
+           stderr_to_stdout: true
+         ) do
+      {_, 0} ->
+        :dismissed
+
       {err, _} ->
         Logger.warning("reconciler dismiss ##{number} failed: #{String.slice(err, 0, 160)}")
         :dismiss_failed
     end
   end
 
+  # #265: deterministic, safe, API-driven repository-configuration
+  # remediation for BranchProtectionID / CodeReviewID. Enables default-branch
+  # protection requiring at least one approving pull-request review (this one
+  # change satisfies both checks). Idempotent — the protection PUT is
+  # declarative, so re-running converges to the same state.
+  defp do_fix_settings(owner, repo, _alert) do
+    token = System.get_env("GITHUB_TOKEN")
+
+    with branch when is_binary(branch) <- default_branch(owner, repo, token) do
+      payload =
+        Jason.encode!(%{
+          "required_status_checks" => nil,
+          "enforce_admins" => false,
+          "required_pull_request_reviews" => %{
+            "required_approving_review_count" => 1,
+            "dismiss_stale_reviews" => true
+          },
+          "restrictions" => nil,
+          "allow_force_pushes" => false,
+          "allow_deletions" => false
+        })
+
+      url =
+        "#{@github_api_base}/repos/#{owner}/#{repo}/branches/#{branch}/protection"
+
+      case System.cmd(
+             "curl",
+             [
+               "-s",
+               "-f",
+               "-X",
+               "PUT",
+               "-H",
+               "Accept: application/vnd.github+json",
+               "-H",
+               "Authorization: Bearer #{token}",
+               "-H",
+               "X-GitHub-Api-Version: 2022-11-28",
+               "-d",
+               payload,
+               url
+             ],
+             stderr_to_stdout: true
+           ) do
+        {_, 0} ->
+          :settings_remediated
+
+        {err, _} ->
+          Logger.warning(
+            "reconciler fix_settings #{owner}/#{repo} failed: #{String.slice(err, 0, 160)}"
+          )
+
+          :settings_failed
+      end
+    else
+      _ -> :settings_failed
+    end
+  end
+
+  defp default_branch(owner, repo, token) do
+    url = "#{@github_api_base}/repos/#{owner}/#{repo}"
+
+    case System.cmd(
+           "curl",
+           [
+             "-s",
+             "-f",
+             "-H",
+             "Accept: application/vnd.github+json",
+             "-H",
+             "Authorization: Bearer #{token}",
+             "-H",
+             "X-GitHub-Api-Version: 2022-11-28",
+             url
+           ],
+           stderr_to_stdout: true
+         ) do
+      {body, 0} ->
+        case Jason.decode(body) do
+          {:ok, %{"default_branch" => b}} when is_binary(b) -> b
+          _ -> nil
+        end
+
+      _ ->
+        nil
+    end
+  end
+
   # Best-effort resolution of the `uses:` ref at an alert's location so
   # SLSA-class pin-exemptions are detected. Reads the workflow file at the
   # reported path+line via the contents API; nil on any miss (caller then
@@ -268,13 +420,21 @@ defmodule Hypatia.ScorecardReconciler do
          url =
            "#{@github_api_base}/repos/#{owner}/#{repo}/contents/#{path}",
          {body, 0} <-
-           System.cmd("curl", [
-             "-s", "-f",
-             "-H", "Accept: application/vnd.github.raw+json",
-             "-H", "Authorization: Bearer #{token}",
-             "-H", "X-GitHub-Api-Version: 2022-11-28",
-             url
-           ], stderr_to_stdout: true),
+           System.cmd(
+             "curl",
+             [
+               "-s",
+               "-f",
+               "-H",
+               "Accept: application/vnd.github.raw+json",
+               "-H",
+               "Authorization: Bearer #{token}",
+               "-H",
+               "X-GitHub-Api-Version: 2022-11-28",
+               url
+             ],
+             stderr_to_stdout: true
+           ),
          lines = String.split(body, "\n"),
          target when is_binary(target) <- Enum.at(lines, line - 1),
          [_, ref] <- Regex.run(~r/uses:\s*(\S+)/, target) do

test/scorecard_reconciler_test.exs

@@ -57,6 +57,23 @@ defmodule Hypatia.ScorecardReconcilerTest do
     test "unknown rule -> open_escalate (never silently dropped)" do
       assert {:open_escalate, nil, _} = R.classify(alert("SomeBrandNewRuleID"))
     end
+
+    test "BranchProtection -> fix_settings (#265, not escalate, not code fix)" do
+      {action, code, why} = R.classify(alert("BranchProtectionID"))
+      assert action == :fix_settings
+      assert code == nil
+      assert why =~ "settings API"
+    end
+
+    test "CodeReview -> fix_settings (#265)" do
+      assert {:fix_settings, nil, _} = R.classify(alert("CodeReviewID"))
+    end
+
+    test "fix_settings is distinct from :fix and :open_escalate" do
+      assert {:fix_settings, _, _} = R.classify(alert("BranchProtectionID"))
+      assert {:fix, _, _} = R.classify(alert("SASTID"))
+      assert {:open_escalate, _, _} = R.classify(alert("SomeBrandNewRuleID"))
+    end
   end
 
   describe "fingerprint/3 — stable across line drift" do