chore(rules-audit): 9 quick-win cleanups from 2026-05-28 catalogue audit (#382)

## Summary

Smallest mechanical cleanups from the 2026-05-28 Hypatia rules audit. 7
files, 40 insertions, 21 deletions.

| # | Change | Audit ref |
|---|---|---|
| 1 | Add `affinescript`/`affine` to `@allowed_languages` (was missing —
active bug) | Part 5.6 |
| 2 | Remove `rescript` from `@allowed_languages` (banned 2026-04-30) |
Part 4.1 |
| 3 | `@banned_languages` "typescript" => "affinescript" (was
"rescript") | Part 4.1 |
| 4 | `root_hygiene` tsconfig.json reason corrected → "use AffineScript"
| Part 4.1 |
| 5 | DELETE `:mu_plugin_no_guard` — WordPress/PHP both banned, dead
rule | Part 4.7 |
| 6 | DELETE `:ncl_missing_spdx` — duplicate of
`security_errors/missing_spdx` | Part 3.3 |
| 7 | DELETE `hex-ex-doc-xss` — targets ex_doc < 0.31.0 (2023), no live
signal | Part 4.8 |
| 8 | SD012 tombstone comment | Part 4.5 |
| 9 | HYP-DOG-002 tombstone comment | Part 4.4 |
| 10 | Fix `missing_permissions` suggestion: "read-all" → granular (was
contradicting `scorecard_compliance/token_permissions`) | Part 3.2 |

## Test plan

- [x] 26/26 lang-policy + security_errors tests pass via standalone
elixir
- [x] All 7 modules compile clean
- [ ] CI green

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

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

lib/rules/cicd_rules.ex

@@ -291,10 +291,11 @@ defmodule Hypatia.Rules.CicdRules do
       reason: "Unfilled RSR template placeholder",
       exception: "rsr-template-repo"},
     %{id: :deno_all_perms, pattern: ~r/deno\s+run\s+-A\b/,
-      reason: "Deno -A (all permissions) banned -- use specific --allow-* flags"},
-    %{id: :mu_plugin_no_guard, pattern: ~r/define\(\s*['"]WP_DEBUG['"]/,
-      reason: "WordPress mu-plugins must guard constants with defined() check",
-      applies_to: ["*/mu-plugins/*.php"]}
+      reason: "Deno -A (all permissions) banned -- use specific --allow-* flags"}
+    # REMOVED 2026-05-28: :mu_plugin_no_guard targeted WordPress mu-plugins
+    # (PHP). PHP is fully banned estate-wide; no estate repo can have a
+    # mu-plugins/*.php path. The rule could never fire. See Hypatia audit
+    # 2026-05-28, Part 4.7.
   ]
 
   def blocked_patterns, do: @blocked_patterns

lib/rules/code_safety.ex

@@ -369,9 +369,10 @@ defmodule Hypatia.Rules.CodeSafety do
     %{id: :ncl_banned_language_ref, severity: :high,
       pattern: ~r/language\s*=\s*"(typescript|go|python|java|kotlin|swift|dart)"/, cwe: "CWE-1104",
       description: "Banned language referenced in Nickel build target"},
-    %{id: :ncl_missing_spdx, severity: :medium,
-      pattern: ~r/\A(?!.*SPDX-License-Identifier).{0,500}\z/s, cwe: "CWE-1104",
-      description: "Nickel file missing SPDX-License-Identifier header"},
+    # REMOVED 2026-05-28: :ncl_missing_spdx — exact duplicate of
+    # security_errors/missing_spdx which already covers any file type.
+    # Nickel files have no scope distinction worth a separate rule. See
+    # Hypatia audit 2026-05-28, Part 3.3.
     %{id: :ncl_k9_missing_pedigree, severity: :high,
       pattern: ~r/\AK9!(?!.*pedigree\s*=).+\z/s, cwe: "CWE-1104",
       description: "K9 contractile missing pedigree section"},

lib/rules/dogfooding.ex

@@ -96,6 +96,13 @@ defmodule Hypatia.Rules.Dogfooding do
     end
   end
 
+  # ─── HYP-DOG-002: TOMBSTONE ──────────────────────────────────────────
+  # HYP-DOG-002 was never implemented; gap left between DOG-001 and
+  # DOG-003 during a prior renumbering. Documented as a tombstone (not
+  # filled) per Hypatia audit 2026-05-28, Part 4.4: reusing this slot
+  # for a fresh rule could collide with an operator's mental model
+  # from logs. New rules should take HYP-DOG-011+.
+
   # ─── HYP-DOG-003: Renamed tool references ────────────────────────────
 
   defp check_stale_names(findings, repo_path) do

lib/rules/root_hygiene.ex

@@ -103,7 +103,7 @@ defmodule Hypatia.Rules.RootHygiene do
       action: :delete},
     %{pattern: ".npmrc", reason: "npm banned -- use Deno", severity: :medium,
       action: :delete},
-    %{pattern: "tsconfig.json", reason: "TypeScript banned -- use ReScript", severity: :high,
+    %{pattern: "tsconfig.json", reason: "TypeScript banned -- use AffineScript", severity: :high,
       action: :flag},
     %{pattern: "go.mod", reason: "Go banned -- use Rust", severity: :high,
       action: :flag},

lib/rules/rules.ex

@@ -334,14 +334,11 @@ defmodule Hypatia.Rules do
             findings
           end
 
-        # ex_doc -- older versions have XSS in generated docs
-        findings =
-          if Regex.match?(~r/"ex_doc":\s*\{[^}]*"version":\s*"0\.(2[0-9]\.|30\.[0-5])"/, content) do
-            [%{rule: "hex-ex-doc-xss", severity: :low,
-               description: "ex_doc < 0.31.0 may generate docs with XSS -- update to >= 0.31.0"} | findings]
-          else
-            findings
-          end
+        # REMOVED 2026-05-28: hex-ex-doc-xss — targeted ex_doc < 0.31.0,
+        # which was released 2023-12. Any actively-maintained Elixir
+        # repo in the estate has long since updated; very-low-signal
+        # rule that produces noise without value. See Hypatia audit
+        # 2026-05-28, Part 4.8.
 
         # nimble_parsec -- stack overflow on deeply nested input
         findings =

lib/rules/security_errors.ex

@@ -174,7 +174,7 @@ defmodule Hypatia.Rules.SecurityErrors do
   # ---------------------------------------------------------------------------
 
   @fix_suggestions %{
-    "TokenPermissionsID" => "Add \"permissions: read-all\" at workflow level",
+    "TokenPermissionsID" => "Add granular workflow-level permissions (e.g. contents: read; scope each job's permissions to the minimum needed). NOTE: do NOT use \"read-all\" -- scorecard_compliance/token_permissions flags read-all as HIGH severity per current OSSF guidance.",
     "PinnedDependenciesID" => "Replace @vN with @SHA # vN format",
     "SecurityPolicyID" => "Create SECURITY.md with vulnerability reporting instructions",
     "BranchProtectionID" => "Enable branch protection via Settings > Branches",
@@ -206,9 +206,9 @@ defmodule Hypatia.Rules.SecurityErrors do
     "rust-toolchain-sha-missing-input" => "Add \"with: toolchain: stable\" to dtolnay step",
     "workflow-linter-self-detection" => "Add grep -v filters for grep/echo/comments",
     "unpinned_action" => "Replace @vN with @SHA # vN format",
-    "missing_permissions" => "Add \"permissions: read-all\" at workflow level",
+    "missing_permissions" => "Add granular workflow-level permissions (e.g. contents: read; scope each job's permissions to the minimum needed). NOTE: do NOT use \"read-all\" -- scorecard_compliance/token_permissions flags read-all as HIGH severity per current OSSF guidance.",
     "missing_spdx" => "Add SPDX-License-Identifier header to file",
-    "missing-workflow-permissions" => "Add \"permissions: read-all\" at workflow level",
+    "missing-workflow-permissions" => "Add granular workflow-level permissions (e.g. contents: read; scope each job's permissions to the minimum needed). NOTE: do NOT use \"read-all\" -- scorecard_compliance/token_permissions flags read-all as HIGH severity per current OSSF guidance.",
     "missing-spdx-header" => "Add SPDX-License-Identifier header to file",
     "stub-crypto-function" => "Replace stub with real cryptographic implementation or add compile_error! guard",
     "stub-hash-return" => "Replace format!(\"stub:...\") with real hash computation",
@@ -458,13 +458,19 @@ defmodule Hypatia.Rules.SecurityErrors do
   # RSR Language Policy
   # ---------------------------------------------------------------------------
 
+  # Policy refresh 2026-05-28: rescript REMOVED (banned 2026-04-30 per
+  # estate policy refresh — migration target is AffineScript directly,
+  # not through ReScript). affinescript ADDED. typescript replacement
+  # corrected from "rescript" → "affinescript".
   @allowed_languages MapSet.new([
-    "rescript", "rust", "gleam", "julia", "logtalk", "haskell",
+    "affinescript", "affine",
+    "rust", "gleam", "julia", "logtalk", "haskell",
     "bash", "nickel", "guile", "ocaml", "ada", "elixir", "zig", "idris2"
   ])
 
   @banned_languages %{
-    "typescript" => "rescript",
+    "typescript" => "affinescript",
+    "rescript" => "affinescript",
     "nodejs" => "deno",
     "golang" => "rust",
     "python" => "julia",

lib/rules/structural_drift.ex

@@ -515,6 +515,13 @@ defmodule Hypatia.Rules.StructuralDrift do
     end)
   end
 
+  # ─── SD012: TOMBSTONE ────────────────────────────────────────────────
+  # SD012 was never implemented; gap left between SD011 and SD013
+  # during a prior renumbering. Documented as a tombstone (rather than
+  # deleted from the sequence) per Hypatia audit 2026-05-28, Part 4.5:
+  # reusing the SD012 slot for a fresh rule could collide with an
+  # operator's mental model from logs. New rules should take SD014+.
+
   # ─── SD013: Path-specific gitignore patterns ───────────────────────────
 
   @path_specific_artifacts [