fix(SD005): emit summary finding when orphan gitlink count > 5 (#380)

## Summary

- SD005 already emitted one `:critical` finding per orphan gitlink, but
the *count* (which is what predicts `actions/checkout` startup_failure)
was never surfaced as a single actionable signal
- Adds a `:high` summary finding when orphan_count > 5 with reason text
explicitly naming the `actions/checkout post-job cleanup will
startup_failure` risk
- Root cause: `developer-ecosystem@baab1534` — 69 stale gitlinks caused
scorecard workflow `startup_failure` that required manual diagnosis

## Test plan

- [ ] `mix test test/structural_drift_test.exs` — three new ExUnit
cases: no gitlinks → empty, count=6 → summary present, count=5 (at
threshold) → no summary
- [ ] Existing SD005 per-link `:critical` findings are unchanged

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

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

lib/rules/structural_drift.ex

@@ -151,13 +151,24 @@ defmodule Hypatia.Rules.StructuralDrift do
 
   # ─── SD005: Orphan gitlinks without .gitmodules ────────────────────────
 
+  # When orphan gitlink count exceeds this threshold, actions/checkout
+  # post-job cleanup (git submodule foreach) will startup_failure on
+  # every gitlink it cannot resolve. Surfaced by the developer-ecosystem
+  # fix (hyperpolymath/developer-ecosystem@baab1534): 69 mode-160000 stale
+  # gitlinks caused scorecard workflow startup_failure on every push.
+  @orphan_gitlink_checkout_failure_threshold 5
+
   @doc """
   SD005: Detect gitlinks (mode 160000) without corresponding .gitmodules entry.
   This is how stray repos-inside-repos (like svalinn in ats2-tui) happen.
   Bot `git add -A` catches stray clones and creates orphan submodule refs.
   Severity: critical (data corruption risk).
   Action: investigate -- move nested repo to canonical location, remove gitlink.
   Triggers: intensive scan + alert user.
+
+  When the orphan count exceeds #{@orphan_gitlink_checkout_failure_threshold},
+  emits one additional summary finding at severity :high with a reason that
+  explicitly names the actions/checkout startup_failure risk.
   """
   def sd005_orphan_gitlinks(repo_path) do
     gitmodules_path = Path.join(repo_path, ".gitmodules")
@@ -183,21 +194,50 @@ defmodule Hypatia.Rules.StructuralDrift do
           gitmodules_content =
             if has_gitmodules, do: File.read!(gitmodules_path), else: ""
 
-          Enum.flat_map(gitlinks, fn path ->
-            if String.contains?(gitmodules_content, "path = #{path}") do
-              []  # Legitimate submodule
-            else
+          per_link_findings =
+            Enum.flat_map(gitlinks, fn path ->
+              if String.contains?(gitmodules_content, "path = #{path}") do
+                []  # Legitimate submodule
+              else
+                [%{
+                  rule: "SD005",
+                  file: path,
+                  severity: :critical,
+                  reason: "Orphan gitlink -- submodule ref without .gitmodules entry. Likely a stray clone caught by bot git-add-all.",
+                  action: :investigate,
+                  trigger_intensive: true,
+                  alert_user: true
+                }]
+              end
+            end)
+
+          orphan_count = length(per_link_findings)
+
+          # When count > threshold, emit an additional summary finding that
+          # explicitly calls out the actions/checkout startup_failure risk.
+          # This is the count-level signal that per-link :critical findings
+          # don't surface on their own (developer-ecosystem@baab1534 had 69
+          # stale gitlinks and scorecard's startup_failure was only diagnosed
+          # after manual inspection of the submodule foreach error).
+          summary_finding =
+            if orphan_count > @orphan_gitlink_checkout_failure_threshold do
               [%{
                 rule: "SD005",
-                file: path,
-                severity: :critical,
-                reason: "Orphan gitlink -- submodule ref without .gitmodules entry. Likely a stray clone caught by bot git-add-all.",
+                file: ".git (index)",
+                severity: :high,
+                reason: "#{orphan_count} orphan gitlinks detected -- actions/checkout post-job cleanup " <>
+                        "(git submodule foreach) will startup_failure with this many stale refs. " <>
+                        "Remove all orphan gitlinks before next push.",
                 action: :investigate,
                 trigger_intensive: true,
-                alert_user: true
+                alert_user: true,
+                count: orphan_count
               }]
+            else
+              []
             end
-          end)
+
+          per_link_findings ++ summary_finding
         end
 
       _ -> []

test/structural_drift_test.exs

@@ -89,6 +89,75 @@ defmodule Hypatia.Rules.StructuralDriftTest do
     end
   end
 
+  describe "sd005_orphan_gitlinks/1" do
+    test "returns empty when no gitlinks exist", %{repo: repo} do
+      System.cmd("git", ["init"], cd: repo)
+      System.cmd("git", ["config", "user.email", "test@test.com"], cd: repo)
+      System.cmd("git", ["config", "user.name", "Test"], cd: repo)
+      File.write!(Path.join(repo, "README.md"), "# test")
+      System.cmd("git", ["add", "."], cd: repo)
+      System.cmd("git", ["commit", "-m", "init"], cd: repo)
+
+      findings = StructuralDrift.sd005_orphan_gitlinks(repo)
+      assert findings == []
+    end
+
+    test "emits summary finding when orphan count exceeds threshold", %{repo: repo} do
+      System.cmd("git", ["init"], cd: repo)
+      System.cmd("git", ["config", "user.email", "test@test.com"], cd: repo)
+      System.cmd("git", ["config", "user.name", "Test"], cd: repo)
+      File.write!(Path.join(repo, "README.md"), "# test")
+      System.cmd("git", ["add", "."], cd: repo)
+      System.cmd("git", ["commit", "-m", "init"], cd: repo)
+
+      # Inject 6 orphan gitlinks directly via git update-index (no .gitmodules)
+      fake_sha = "deadbeefdeadbeefdeadbeefdeadbeef00000001"
+      for i <- 1..6 do
+        path = "vendor/dep_#{i}"
+        File.mkdir_p!(Path.join(repo, path))
+        System.cmd("git", ["update-index", "--add", "--cacheinfo",
+                           "160000,#{fake_sha},#{path}"],
+                   cd: repo)
+      end
+
+      findings = StructuralDrift.sd005_orphan_gitlinks(repo)
+      summary = Enum.find(findings, & &1[:count] == 6)
+      assert summary != nil, "Expected a summary finding with count=6"
+      assert summary.severity == :high
+      assert summary.rule == "SD005"
+      assert String.contains?(summary.reason, "actions/checkout")
+      assert String.contains?(summary.reason, "startup_failure")
+      # Also should have 6 per-link critical findings
+      per_link = Enum.filter(findings, & &1.file != ".git (index)")
+      assert length(per_link) == 6
+      assert Enum.all?(per_link, &(&1.severity == :critical))
+    end
+
+    test "does not emit summary when orphan count is at or below threshold", %{repo: repo} do
+      System.cmd("git", ["init"], cd: repo)
+      System.cmd("git", ["config", "user.email", "test@test.com"], cd: repo)
+      System.cmd("git", ["config", "user.name", "Test"], cd: repo)
+      File.write!(Path.join(repo, "README.md"), "# test")
+      System.cmd("git", ["add", "."], cd: repo)
+      System.cmd("git", ["commit", "-m", "init"], cd: repo)
+
+      # Inject exactly 5 orphan gitlinks (at threshold — no summary)
+      fake_sha = "deadbeefdeadbeefdeadbeefdeadbeef00000002"
+      for i <- 1..5 do
+        path = "vendor/sub_#{i}"
+        File.mkdir_p!(Path.join(repo, path))
+        System.cmd("git", ["update-index", "--add", "--cacheinfo",
+                           "160000,#{fake_sha},#{path}"],
+                   cd: repo)
+      end
+
+      findings = StructuralDrift.sd005_orphan_gitlinks(repo)
+      summary = Enum.find(findings, & &1[:count] != nil)
+      assert summary == nil, "Expected no summary finding for count <= threshold"
+      assert length(findings) == 5
+    end
+  end
+
   describe "sd010_tracked_node_modules/1" do
     test "returns empty when no node_modules directory exists", %{repo: repo} do
       # Initialise a git repo so the git commands work