hyperpolymath
diff --git a/‎lib/rules/admin_merge_eligibility.ex‎
Lines changed: 110 additions & 2 deletions b/‎lib/rules/admin_merge_eligibility.ex‎
Lines changed: 110 additions & 2 deletions
diff --git a/‎lib/rules/branch_protection.ex‎
Lines changed: 142 additions & 3 deletions b/‎lib/rules/branch_protection.ex‎
Lines changed: 142 additions & 3 deletions
@@ -12,7 +12,12 @@ defmodule Hypatia.Rules.AdminMergeEligibility do
   replace a heavy workflow with a thin wrapper, seed a doc, or apply a
   template-level chore, so blocking on CI provides no signal.
 
-  Rule IDs AM001-AM009.
+  Rule IDs AM001-AM010.
+
+  AM010 is the only state-based recognizer in this module: a PR whose
+  only failing/missing required check is a phantom (per
+  `Hypatia.Rules.BranchProtection` BP008) is admin-eligible regardless
+  of title shape. Caller supplies the phantom-context set.
 
   Intended consumers:
 
@@ -124,10 +129,113 @@ defmodule Hypatia.Rules.AdminMergeEligibility do
       "AM006" => "language-CI (rust/elixir) reusable-wrapper replacement",
       "AM007" => "CHANGELOG.md seed in Keep-a-Changelog format",
       "AM008" => "docs-template / README / tech-debt-audit doc",
-      "AM009" => "linguist gitattributes / license-header migration"
+      "AM009" => "linguist gitattributes / license-header migration",
+      "AM010" => "phantom required check is the only blocker (paired with BP008)"
     }
   end
 
+  # ─── AM010: phantom-context-only blocker ──────────────────────────────
+
+  @doc """
+  AM010: a PR is admin-eligible if every required status-check context
+  passes EXCEPT one or more contexts that are known phantoms (per
+  `Hypatia.Rules.BranchProtection` BP008). Auto-merge cannot satisfy a
+  context that never emits a check; admin-merge is the only path.
+
+  This is a STATE check, not a title check — orthogonal to AM001-AM009.
+  Call this BEFORE `classify/1` when you have the data, and fall
+  through to title classification otherwise.
+
+  ## Inputs
+
+  `pr_state` is a map with these keys:
+
+    * `:required_contexts` — list of context names from
+      `required_status_checks.contexts` (or `.checks[*].context`).
+    * `:phantom_contexts` — list of context names known to be phantom
+      (BP008 findings, materialised as a set).
+    * `:rollup` — list of `%{"name" => name, "conclusion" => conc}`
+      maps, shaped like
+      `gh pr view <n> --json statusCheckRollup`. Conclusions matching
+      `["SUCCESS", "NEUTRAL", "SKIPPED"]` count as passing.
+
+  Returns `{:eligible, "AM010"}` when:
+
+    1. `phantom_contexts` (minus any context currently in-progress on
+       THIS PR) is non-empty, AND
+    2. every required context is either passing OR in the in-progress-
+       subtracted `phantom_contexts`.
+
+  Returns `:not_phantom_only` otherwise.
+
+  Empty `required_contexts` returns `:not_phantom_only` — if nothing
+  is required, auto-merge already works; AM010 doesn't apply.
+
+  ## ALARP type-1 safety: in-progress subtraction
+
+  BP008 derives the phantom set from the LAST N MAIN COMMITS. A
+  path-filtered workflow that happens to touch the path on THIS PR
+  (but didn't on the recent main commits) would be classified as
+  phantom even though it IS firing here. Admin-merging would bypass
+  an actively-running check.
+
+  Defence: before deciding eligibility, subtract from the phantom set
+  any context whose rollup entry is queued / pending / in_progress on
+  this PR. A truly phantom context has NO rollup entry; a sometimes-
+  firing context has a non-terminal entry. The subtraction collapses
+  the latter back into the "wait for it" path.
+  """
+  @spec am010_phantom_only_blocker?(map()) ::
+          {:eligible, String.t()} | :not_phantom_only
+  def am010_phantom_only_blocker?(pr_state) when is_map(pr_state) do
+    required = Map.get(pr_state, :required_contexts, [])
+    phantoms = MapSet.new(Map.get(pr_state, :phantom_contexts, []))
+    rollup = Map.get(pr_state, :rollup, [])
+
+    passing =
+      rollup
+      |> Enum.filter(fn entry ->
+        Map.get(entry, "conclusion") in ["SUCCESS", "NEUTRAL", "SKIPPED"]
+      end)
+      |> Enum.map(&Map.get(&1, "name"))
+      |> Enum.reject(&is_nil/1)
+      |> MapSet.new()
+
+    # ALARP Type 1 mitigation. A context flagged phantom by BP008 (sample-
+    # based, main-branch) is only safe to treat as phantom on THIS PR when
+    # it has NO rollup entry here. Any rollup entry — passing, failing,
+    # pending, in-progress — means the context IS firing on this PR; the
+    # BP008 main-branch sample was a false-negative for this commit. In
+    # all such cases admin-merging would bypass an actual check (pass-by-
+    # luck, fail-by-vote, or skip-an-in-progress run). Restrict the
+    # phantom set to contexts truly absent from this PR's rollup.
+    rollup_names =
+      rollup
+      |> Enum.map(&Map.get(&1, "name"))
+      |> Enum.reject(&is_nil/1)
+      |> MapSet.new()
+
+    phantoms_on_this_pr = MapSet.difference(phantoms, rollup_names)
+
+    cond do
+      MapSet.size(phantoms_on_this_pr) == 0 ->
+        :not_phantom_only
+
+      required == [] ->
+        :not_phantom_only
+
+      Enum.all?(required, fn ctx ->
+        MapSet.member?(passing, ctx) or MapSet.member?(phantoms_on_this_pr, ctx)
+      end) ->
+        {:eligible, "AM010"}
+
+      true ->
+        :not_phantom_only
+    end
+  end
+
+  def am010_phantom_only_blocker?(_), do: :not_phantom_only
+
   # ─── Stall detection (DBA001) ─────────────────────────────────────────
 
   @doc """
 
@@ -6,16 +6,19 @@ defmodule Hypatia.Rules.BranchProtection do
   Branch-protection hygiene rules drawn from the CIS GitHub Benchmark,
   OSSF Scorecard, and NIST SP 800-218 (SSDF) PO/PS/PW practices.
 
-  Rule IDs BP001-BP007.
+  Rule IDs BP001-BP008.
 
   These rules concern the **review and integrity controls** on the
   default branch — distinct from `BaselineHealth` (drift conditions),
   `WorkflowHardening` (workflow content) and `SupplyChain` (provenance).
 
-  All rules read from a single GitHub API endpoint:
+  Most rules read from a single GitHub API endpoint:
 
       gh api repos/{owner}/{repo}/branches/main/protection
 
+  BP008 additionally queries `/check-runs` against recent main-branch
+  commits to detect required contexts that never emit a check.
+
   ## Provenance map
 
   | Rule | Source | Upstream rule / check |
@@ -27,6 +30,7 @@ defmodule Hypatia.Rules.BranchProtection do
   | BP005 | CIS GH 1.6.x + NIST PO.3.2 | `require_code_owner_reviews: true` but CODEOWNERS missing/empty |
   | BP006 | CIS GH | `enforce_admins: false` |
   | BP007 | scorecard `Branch-Protection` tier 1 | default branch allows force-push or deletion |
+  | BP008 | this estate (2026-05-28) | required status-check context never emits a check (phantom context blocks auto-merge) |
 
   ## Dispatch
 
@@ -383,6 +387,81 @@ defmodule Hypatia.Rules.BranchProtection do
     end
   end
 
+  # ─── BP008: required context never emits a check (phantom) ──────────
+
+  @doc """
+  BP008: `main` branch protection lists a required status-check context
+  that has produced **zero** check_runs across the last N commits on
+  main. The context is *phantom*: auto-merge will wait forever for it to
+  pass, and admin-merge is the only path until it's removed (or the
+  workflow that would emit it is wired up).
+
+  Severity: `:high` — every PR is silently blocked from auto-merge.
+  Confidence: 0.85.
+
+  The empirical trigger was the 2026-05-28 estate sweep: every
+  `hyperpolymath/affinescript` PR sat in `mergeStateStatus: BLOCKED`
+  with all visible checks green, because `spark-theatre-gate / SPARK
+  Theatre Gate` was a required context that no workflow emits. 14 PRs
+  needed admin-merge to land.
+
+  Heuristic: walk the last `recent_commits` (default 5) on main, union
+  every check_run name observed, and flag any required context that
+  doesn't appear in that union. Five commits is enough signal because
+  a real CI context emits one check per commit; a context that's been
+  silent across five commits is either retired (worth removing) or
+  never wired up (worth filing).
+
+  Returns one finding per phantom context. Returns `[]` cleanly when
+  `GITHUB_TOKEN` / `HYPATIA_DISPATCH_PAT` is not set, when no contexts
+  are required, or when the recent-commits lookup fails.
+
+  ## Options
+
+    * `:recent_commits` — number of main-branch commits to sample
+      (default: 5). Lower bound 1, upper bound 20.
+  """
+  def bp008_phantom_required_context(owner, repo, opts \\ []) do
+    n =
+      opts
+      |> Keyword.get(:recent_commits, 5)
+      |> max(1)
+      |> min(20)
+
+    with {:ok, protection} <- fetch_branch_protection(owner, repo, "main"),
+         contexts when contexts != [] <- required_contexts(protection),
+         {:ok, seen} <- fetch_recent_check_names(owner, repo, n) do
+      phantoms = Enum.reject(contexts, &MapSet.member?(seen, &1))
+
+      Enum.map(phantoms, fn ctx ->
+        %{
+          rule: "BP008",
+          file: "#{owner}/#{repo}",
+          severity: :high,
+          reason:
+            "required status check `#{ctx}` has emitted zero check_runs " <>
+              "across the last #{n} commits on main — auto-merge will " <>
+              "stall on every PR until this context is removed or its " <>
+              "workflow is wired up",
+          action: :report,
+          detail: %{
+            branch: "main",
+            phantom_context: ctx,
+            sampled_commits: n,
+            fix:
+              "Either remove `#{ctx}` from required contexts " <>
+                "(`gh api -X PATCH repos/#{owner}/#{repo}/branches/main/" <>
+                "protection/required_status_checks -F 'contexts[]=...'` " <>
+                "without it), or land a workflow whose job's name is " <>
+                "exactly `#{ctx}`"
+          }
+        }
+      end)
+    else
+      _ -> []
+    end
+  end
+
   # ─── scan/2 facade ──────────────────────────────────────────────────
 
   @doc """
@@ -408,7 +487,8 @@ defmodule Hypatia.Rules.BranchProtection do
           bp004_dismiss_stale_reviews_off(owner, repo) ++
           bp005_codeowners_required_but_missing(owner, repo) ++
           bp006_enforce_admins_off(owner, repo) ++
-          bp007_force_push_or_delete_allowed(owner, repo)
+          bp007_force_push_or_delete_allowed(owner, repo) ++
+          bp008_phantom_required_context(owner, repo)
       else
         []
       end
@@ -493,6 +573,30 @@ defmodule Hypatia.Rules.BranchProtection do
   defp maybe_add(list, true, item), do: list ++ [item]
   defp maybe_add(list, _, _item), do: list
 
+  # ─── Required-context extraction (BP008 helper) ─────────────────────
+  #
+  # `required_status_checks.contexts` is the legacy form; the newer
+  # `checks` array carries the same names alongside per-app pin info
+  # (`app_id`). Accept either; flatten to a string list. Returns `[]`
+  # when no required-checks block is present (BP008 then no-ops).
+
+  defp required_contexts(%{"required_status_checks" => %{"contexts" => ctxs}})
+       when is_list(ctxs) do
+    Enum.filter(ctxs, &is_binary/1)
+  end
+
+  defp required_contexts(%{"required_status_checks" => %{"checks" => checks}})
+       when is_list(checks) do
+    checks
+    |> Enum.map(fn
+      %{"context" => ctx} when is_binary(ctx) -> ctx
+      _ -> nil
+    end)
+    |> Enum.reject(&is_nil/1)
+  end
+
+  defp required_contexts(_), do: []
+
   # ─── CODEOWNERS presence ────────────────────────────────────────────
 
   # BP005 helper. GitHub looks for CODEOWNERS in three locations: root,
@@ -525,6 +629,41 @@ defmodule Hypatia.Rules.BranchProtection do
 
   # ─── GitHub API ─────────────────────────────────────────────────────
 
+  # ─── Recent main-commit check-run sampling (BP008 helper) ───────────
+  #
+  # Walks the last `n` commits on main (default-branch HEAD), collects
+  # every `check_runs[].name` observed, and returns the union as a
+  # `MapSet`. A required context absent from this set after `n` commits
+  # is a phantom. Returns `{:error, :no_token}` cleanly when no token.
+
+  defp fetch_recent_check_names(owner, repo, n) do
+    with {:ok, commits} <- curl_github("repos/#{owner}/#{repo}/commits?per_page=#{n}") do
+      shas =
+        commits
+        |> Enum.map(fn
+          %{"sha" => sha} when is_binary(sha) -> sha
+          _ -> nil
+        end)
+        |> Enum.reject(&is_nil/1)
+
+      names =
+        Enum.reduce(shas, MapSet.new(), fn sha, acc ->
+          case curl_github("repos/#{owner}/#{repo}/commits/#{sha}/check-runs?per_page=100") do
+            {:ok, %{"check_runs" => runs}} when is_list(runs) ->
+              Enum.reduce(runs, acc, fn
+                %{"name" => name}, set when is_binary(name) -> MapSet.put(set, name)
+                _, set -> set
+              end)
+
+            _ ->
+              acc
+          end
+        end)
+
+      {:ok, names}
+    end
+  end
+
   defp fetch_branch_protection(owner, repo, branch) do
     case curl_github("repos/#{owner}/#{repo}/branches/#{branch}/protection") do
       {:ok, %{"message" => "Branch not protected"}} ->