refactor(governance): consolidate ruleset tools with dynamic scope challenges

Rebase onto main (which now includes #3128's per-call OAuth scope checks)
and redesign the ruleset tools around that API instead of the old
tool-name-keyed challenge middleware that motivated splitting by level.

- Collapse the 5 level-specific tools (repository_ruleset_read,
  organization_repository_ruleset_read, create_repository_ruleset,
  create_organization_repository_ruleset, create_enterprise_repository_ruleset)
  into 2: repository_ruleset_read and create_repository_ruleset. Both take a
  "level" argument (repository/organization/enterprise) and use
  scopes.DynamicChallenge to return the exact repo / read:org / admin:org /
  read:enterprise / admin:enterprise challenge for that call, using the scope
  hierarchy so a broader granted scope still satisfies the challenge.
- A missing or unrecognized "level" (or a non-string value) returns no
  challenge so normal handler argument validation produces the error,
  instead of prompting for scopes on a malformed call.
- Keep repository_ruleset_read and create_repository_ruleset as separate
  tools since ReadOnlyHint-based read-only filtering depends on that split.
- Add enterprise-level "get" and "list" read support (list issued directly
  via GET /enterprises/{enterprise}/rulesets, matching the existing rule
  suite pattern, since go-github has no typed wrapper for it) so all three
  levels have symmetric read coverage.
- Re-add read:enterprise/admin:enterprise to pkg/scopes as opt-in
  (non-default) OAuth scopes, alongside admin:org which no tool had
  previously requested, and register them in oauthScopeDefinitions so they
  are advertised in OAuth protected-resource metadata.
- Fetch the "law" toolset icon into the new icons_data_uris.txt embed
  (required_icons.txt already listed it) and bump go-github v87 -> v89 to
  match main.
- Update README/toolsnaps via script/generate-docs and UPDATE_TOOLSNAPS.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

README.md

@@ -886,64 +886,45 @@ The following sets of tools are available:
 
 <summary><picture><source media="(prefers-color-scheme: dark)" srcset="pkg/octicons/icons/law-dark.png"><source media="(prefers-color-scheme: light)" srcset="pkg/octicons/icons/law-light.png"><img src="pkg/octicons/icons/law-light.png" width="20" height="20" alt="law"></picture> Governance</summary>
 
-- **create_enterprise_repository_ruleset** - Create enterprise repository ruleset
-  - **Required OAuth Scopes**: `admin:enterprise`
-  - `bypass_actors`: The actors that can bypass the rules in this ruleset (object[], optional)
-  - `conditions`: Conditions for when this ruleset applies, e.g. {"ref_name": {"include": ["refs/heads/main"], "exclude": []}} (object, optional)
-  - `enforcement`: The enforcement level of the ruleset. 'evaluate' allows admins to test rules before enforcing them (string, required)
-  - `enterprise`: Enterprise slug (string, required)
-  - `name`: The name of the ruleset (string, required)
-  - `rules`: An array of rules within the ruleset. Each rule is an object with a 'type' (e.g. 'creation', 'deletion', 'non_fast_forward', 'required_signatures', 'pull_request', 'required_status_checks') and, for rules that need configuration, a 'parameters' object (object[], required)
-  - `target`: The target of the ruleset. Defaults to 'branch' (string, optional)
-
-- **create_organization_repository_ruleset** - Create organization repository ruleset
-  - **Required OAuth Scopes**: `admin:org`
-  - `bypass_actors`: The actors that can bypass the rules in this ruleset (object[], optional)
-  - `conditions`: Conditions for when this ruleset applies, e.g. {"ref_name": {"include": ["refs/heads/main"], "exclude": []}} (object, optional)
-  - `enforcement`: The enforcement level of the ruleset. 'evaluate' allows admins to test rules before enforcing them (string, required)
-  - `name`: The name of the ruleset (string, required)
-  - `org`: Organization name (string, required)
-  - `rules`: An array of rules within the ruleset. Each rule is an object with a 'type' (e.g. 'creation', 'deletion', 'non_fast_forward', 'required_signatures', 'pull_request', 'required_status_checks') and, for rules that need configuration, a 'parameters' object (object[], required)
-  - `target`: The target of the ruleset. Defaults to 'branch' (string, optional)
-
 - **create_repository_ruleset** - Create repository ruleset
-  - **Required OAuth Scopes**: `repo`
+  - **OAuth Challenge Scopes**: `repo`, `admin:org`, `admin:enterprise`
   - `bypass_actors`: The actors that can bypass the rules in this ruleset (object[], optional)
   - `conditions`: Conditions for when this ruleset applies, e.g. {"ref_name": {"include": ["refs/heads/main"], "exclude": []}} (object, optional)
   - `enforcement`: The enforcement level of the ruleset. 'evaluate' allows admins to test rules before enforcing them (string, required)
+  - `enterprise`: Enterprise slug. Required when level is 'enterprise'. (string, optional)
+  - `level`: The level at which the ruleset is configured:
+    - 'repository': A ruleset on a single repository (requires 'owner' and 'repo').
+    - 'organization': A ruleset covering repositories in an organization (requires 'org').
+    - 'enterprise': A ruleset covering repositories across an enterprise (requires 'enterprise'). (string, required)
   - `name`: The name of the ruleset (string, required)
-  - `owner`: Repository owner (string, required)
-  - `repo`: Repository name (string, required)
+  - `org`: Organization name. Required when level is 'organization'. (string, optional)
+  - `owner`: Repository owner. Required when level is 'repository'. (string, optional)
+  - `repo`: Repository name. Required when level is 'repository'. (string, optional)
   - `rules`: An array of rules within the ruleset. Each rule is an object with a 'type' (e.g. 'creation', 'deletion', 'non_fast_forward', 'required_signatures', 'pull_request', 'required_status_checks') and, for rules that need configuration, a 'parameters' object (object[], required)
-  - `target`: The target of the ruleset. Defaults to 'branch' (string, optional)
-
-- **organization_repository_ruleset_read** - Read organization repository rulesets
-  - **Required OAuth Scopes**: `read:org`
-  - **Accepted OAuth Scopes**: `admin:org`, `read:org`, `write:org`
-  - `method`: Operation to perform:
-    - 'get': Get a specific repository ruleset by ID (requires 'ruleset_id').
-    - 'list': List all repository rulesets for the organization. (string, required)
-  - `org`: Organization name (string, required)
-  - `page`: Page number for pagination (min 1) (number, optional)
-  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `ruleset_id`: Ruleset ID. Required for the 'get' method. (number, optional)
+  - `target`: The target of the ruleset. Defaults to 'branch'. 'repository' is only valid for 'organization' and 'enterprise' level rulesets. (string, optional)
 
 - **repository_ruleset_read** - Read repository rulesets
-  - **Required OAuth Scopes**: `repo`
+  - **OAuth Challenge Scopes**: `repo`, `read:org`, `read:enterprise`
   - `actor_name`: The handle for the GitHub user account to filter rule suites on. Used by the 'list_rule_suites' method. (string, optional)
   - `branch`: Branch name. Required for the 'get_rules_for_branch' method. (string, optional)
-  - `includes_parents`: Include rulesets configured at higher levels that also apply. Defaults to true. Used by the 'get' and 'list' methods. (boolean, optional)
+  - `enterprise`: Enterprise slug. Required when level is 'enterprise'. (string, optional)
+  - `includes_parents`: Include rulesets configured at higher levels that also apply. Defaults to true. Used by the 'get' and 'list' methods at the repository level. (boolean, optional)
+  - `level`: The level at which the ruleset is configured:
+    - 'repository': A ruleset on a single repository (requires 'owner' and 'repo').
+    - 'organization': A ruleset covering repositories in an organization (requires 'org').
+    - 'enterprise': A ruleset covering repositories across an enterprise (requires 'enterprise'). (string, required)
   - `method`: Operation to perform:
-    - 'get': Get a specific ruleset by ID (requires 'ruleset_id').
-    - 'list': List all rulesets for the repository.
-    - 'get_rules_for_branch': Get all rules that apply to a branch (requires 'branch').
-    - 'list_rule_suites': List rule suites, the evaluations of rules against pushes.
-    - 'get_rule_suite': Get a specific rule suite by ID (requires 'rule_suite_id'). (string, required)
-  - `owner`: Repository owner (string, required)
+    - 'get': Get a specific ruleset by ID (requires 'ruleset_id'). Supported at every level.
+    - 'list': List all rulesets. Supported at every level.
+    - 'get_rules_for_branch': Get all rules that apply to a branch (requires 'branch'). Repository level only.
+    - 'list_rule_suites': List rule suites, the evaluations of rules against pushes. Repository level only.
+    - 'get_rule_suite': Get a specific rule suite by ID (requires 'rule_suite_id'). Repository level only. (string, required)
+  - `org`: Organization name. Required when level is 'organization'. (string, optional)
+  - `owner`: Repository owner. Required when level is 'repository'. (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `ref`: The name of the ref (branch, tag, etc.) to filter rule suites by. Used by the 'list_rule_suites' method. (string, optional)
-  - `repo`: Repository name (string, required)
+  - `repo`: Repository name. Required when level is 'repository'. (string, optional)
   - `rule_suite_id`: Rule suite ID. Required for the 'get_rule_suite' method. (number, optional)
   - `rule_suite_result`: The rule suite result to filter by. Used by the 'list_rule_suites' method. (string, optional)
   - `ruleset_id`: Ruleset ID. Required for the 'get' method. (number, optional)

docs/scope-filtering.md

@@ -63,6 +63,7 @@ Some scopes implicitly include others:
 
 - `repo` → includes `public_repo`, `security_events`
 - `admin:org` → includes `write:org` → includes `read:org`
+- `admin:enterprise` → includes `read:enterprise`
 - `project` → includes `read:project`
 
 This means if your token has `repo`, tools requiring `security_events` will also be available.

pkg/github/__toolsnaps__/create_enterprise_repository_ruleset.snap

@@ -1,8 +1,10 @@
 {
   "annotations": {
+    "idempotentHint": false,
+    "readOnlyHint": false,
     "title": "Create repository ruleset"
   },
-  "description": "Create a new ruleset for a repository",
+  "description": "Create a new ruleset at the repository, organization, or enterprise level",
   "inputSchema": {
     "properties": {
       "bypass_actors": {
@@ -50,16 +52,33 @@
         ],
         "type": "string"
       },
+      "enterprise": {
+        "description": "Enterprise slug. Required when level is 'enterprise'.",
+        "type": "string"
+      },
+      "level": {
+        "description": "The level at which the ruleset is configured:\n- 'repository': A ruleset on a single repository (requires 'owner' and 'repo').\n- 'organization': A ruleset covering repositories in an organization (requires 'org').\n- 'enterprise': A ruleset covering repositories across an enterprise (requires 'enterprise').",
+        "enum": [
+          "repository",
+          "organization",
+          "enterprise"
+        ],
+        "type": "string"
+      },
       "name": {
         "description": "The name of the ruleset",
         "type": "string"
       },
+      "org": {
+        "description": "Organization name. Required when level is 'organization'.",
+        "type": "string"
+      },
       "owner": {
-        "description": "Repository owner",
+        "description": "Repository owner. Required when level is 'repository'.",
         "type": "string"
       },
       "repo": {
-        "description": "Repository name",
+        "description": "Repository name. Required when level is 'repository'.",
         "type": "string"
       },
       "rules": {
@@ -83,18 +102,18 @@
         "type": "array"
       },
       "target": {
-        "description": "The target of the ruleset. Defaults to 'branch'",
+        "description": "The target of the ruleset. Defaults to 'branch'. 'repository' is only valid for 'organization' and 'enterprise' level rulesets.",
         "enum": [
           "branch",
           "tag",
-          "push"
+          "push",
+          "repository"
         ],
         "type": "string"
       }
     },
     "required": [
-      "owner",
-      "repo",
+      "level",
       "name",
       "enforcement",
       "rules"