docs(AGENTS.md): read GitHub through REST, and stop mandating GraphQL

.github/shared-rules.json

@@ -77,6 +77,45 @@
   ],
 
   "blocks": [
+    {
+      "id": "rest-not-graphql",
+      "hub": "Systemorph/MeshWeaver",
+      "required-in": [
+        "Systemorph/MeshWeaver",
+        "Systemorph/MeshWeaver.Plugins",
+        "Systemorph/MeshWeaver.Education",
+        "Systemorph/MeshWeaver.Reinsurance",
+        "Systemorph/MeshWeaver.SocialMedia",
+        "Systemorph/MeshWeaver.Manufacturing",
+        "Systemorph/Memex"
+      ],
+      "slots": [],
+      "why": [
+        "Maintainer directive, 2026-09-04: 'everyone should use rest'. The occasion was an agent",
+        "polling `gh pr view` every 5 s, which exhausted GitHub's SECONDARY rate limit for the",
+        "whole session — every concurrent agent lost GitHub access, not just the one polling.",
+        "",
+        "The rule is in a shared block rather than each repo's own prose because the failure is",
+        "FLEET-WIDE by construction: the limit is per USER, so one repo's watcher takes down every",
+        "other repo's session running as the same identity. A per-repo rule cannot express that,",
+        "and a repo that never adopted it would keep taking the others down.",
+        "",
+        "Why the diagnosis is in the text and not just the prohibition: `gh api /rate_limit` reads",
+        "a pristine 5000/5000 remaining, 0 used while GraphQL is refused. Anyone who checks the",
+        "quota concludes they are NOT rate-limited and looks elsewhere — two agents did exactly",
+        "that on the day this landed. The pairing IS the signature, so it is stated.",
+        "",
+        "No slots: the rule is identical everywhere, including the REST endpoints, because the",
+        "GitHub API is the same API from every repo. Core carries one extra sentence OUTSIDE the",
+        "block (its merge-queue paragraph keeps `dequeuePullRequest`, which REST cannot express) —",
+        "that is why the block names the merge queue as the reserved exception rather than",
+        "forbidding GraphQL outright, which would have been false guidance.",
+        "",
+        "Adopted text-first: the six satellites landed the block before this manifest entry, so",
+        "the gate was never red on a half-finished rollout (Plugins#1317, Education#268,",
+        "Reinsurance#161, SocialMedia#137, Manufacturing#51, Memex#179)."
+      ]
+    },
     {
       "id": "conserve-work-products",
       "hub": "Systemorph/MeshWeaver",

AGENTS.md

@@ -99,7 +99,7 @@ Full reference: [/gui](.claude/skills/gui/SKILL.md) · [GUI/DataBinding.md](src/
 
 🚨 **PR capability is CREDENTIAL × REPO — measure it for the repo you are in, never remember it** (`gh api repos/Systemorph/<repo> --jq '.permissions'`; `gh auth status`). The same repo answers differently to two sessions on the same day. **Never reach for `--admin`** — a refusal is information about the gate, not an obstacle to route around; on `FORBIDDEN`, re-authenticate with `! gh auth login`.
 
-🚨 **Poll the `MeshWeaver Build and Test` check SUITE by name via GraphQL and merge only on `COMPLETED/SUCCESS`.** Never wait for *all* check suites (an installed App that posts no runs leaves its suite `queued` forever), and never poll with `gh run watch` / `gh pr checks --watch` (REST rate-limit 403s masquerade as CI-red). `Consolidate test results` is the required check and the only one to require.
+🚨 **Poll the `MeshWeaver Build and Test` workflow by name over REST and merge only on `completed`/`success`** — `gh api "repos/Systemorph/MeshWeaver/actions/runs?head_sha=<sha>"`, filtered on `.name`. Never wait for *all* check suites (an installed App that posts no runs leaves its suite `queued` forever — `Azure Boards` does exactly this here), and never poll with `gh run watch` / `gh pr checks --watch`: both issue GraphQL, and exhausting the SECONDARY limit takes GitHub access away from every concurrent agent while `/rate_limit` still reads `5000/5000`. `Consolidate test results` is the required check and the only one to require.
 
 🚨 **SUBSCRIBE to a PR — one persistent `Monitor` over EVERY event you would act on**, armed when you open it: suite green, suite *any other* terminal conclusion, a new unresolved review thread, `mergeStateStatus = DIRTY`, and `MERGED`/`CLOSED`. A success-only watch is the same defect as a gate that skips on missing input — silence looks identical to "still running".
 
@@ -125,6 +125,9 @@ Full reference: [AccessControl.md](src/MeshWeaver.Documentation/Data/Architectur
 
 All docs are embedded in `src/MeshWeaver.Documentation/` and served under `Doc/` at runtime (`Data/Architecture/`, `Data/DataMesh/`, `Data/GUI/`, `Data/AI/`). **Agent and Skill node definitions ship with the AI engine, which lives in `MeshWeaver.Plugins` (#2276)** — not in this repo.
 
+<!-- shared-rule:begin rest-not-graphql -->
+🚨 **Read GitHub through REST, not GraphQL.** GraphQL exhausts first, and the limit that bites is the **SECONDARY** one — `gh api /rate_limit` keeps reporting `5000/5000 remaining, 0 used` while every GraphQL call is refused with *"API rate limit already exceeded"*. The primary quota is therefore NOT the signal; that pairing IS the secondary limit. `gh pr view --json …`, `gh pr checks` and `gh run watch` all issue GraphQL, so a watcher built on them takes the whole session's GitHub access down with it, for every concurrent agent. REST does everything a PR watcher needs: `gh api "repos/{o}/{r}/actions/runs?head_sha={sha}"` filtered on `.name` for one workflow's `status`/`conclusion`; `.../commits/{sha}/check-runs` and `.../commits/{sha}/check-suites` for the checks; `.../pulls/{n}` for `state`, `merged` and `mergeable_state`. Reserve GraphQL for what REST cannot express — merge-queue entries and `dequeuePullRequest` — and never put one in a loop. 🚨 **Fast retries EXTEND a secondary limit**: on a refusal STOP for at least 5 minutes, do not retry, and do not switch to a different GraphQL query hoping it is cheaper. Poll no faster than 60 s and run ONE watcher, not several. Two REST caveats, both measured: `pulls/{n}` answers `mergeable: null` / `mergeable_state: "unknown"` until GitHub recomputes after a push — re-read, never read that as a verdict; and a check SUITE an installed App never posts runs to stays `queued` forever, so wait on the ONE workflow you care about by name, never on all suites.<!-- shared-rule:end rest-not-graphql -->
+
 <!-- shared-rule:begin conserve-work-products -->
 **🗂️ ALWAYS conserve work products — a design, an architecture decision, an investigation finding, a manual produced while working gets COMMITTED to this repo in the same change set, every time.** The durable form is <!--slot:doc-home-->a doc page under `src/MeshWeaver.Documentation/Data/` (Architecture for platform designs; follow AuthoringDocumentation.md; add a What's New entry when user-facing)<!--/slot--> — issue comments, PR bodies, chat replies and rendered artifact pages are *pointers* to the committed page, never a substitute for it. A finding that lives only in an issue thread or a terminal is invisible to the next session<!--slot:reach--> and to the portal; the doc tree ships with the platform<!--/slot-->. Maintainer directive, 2026-08-30<!-- shared-rule:end conserve-work-products -->. This rule holds in EVERY repo of the fleet — satellites commit theirs to their own doc home.