docs(pm): describe the dispatch-gates self-test's real live-tree contact (#13229)

The "Why the self-test ONLY" section said the self-test "reads the real
pr-automation.yml and walks the real packages tree". Instrumented on this
tree, that self-test opens every workflow file and the source of every gate
the discovery finds, sweeps the tracked corpus, builds temporary git
repositories with real history and drives changedPathsFromGit against them,
and re-runs the tool's own CLI as a child process against the real checkout.

.github/workflows/lint.yml defers to this header as the authority for the
measured argument, so a reader sent here arrived at a description of a far
smaller self-test than CI runs.

Rewritten to describe the SHAPE of that contact, with no figures — the same
repair the workflow comment took, and for the same reason: any count frozen
in a comment rots without anything failing. The workflow comment itself is
deliberately untouched; it is already qualitative and correct.


Claude-Session: https://claude.ai/code/session_01CPrUz21stTFhJRUirdc4yw

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-elon

scripts/pm/check-dispatch-gates.mjs

@@ -29,10 +29,27 @@
  * and exits 0 on any completed run. There is no verdict in it for CI to hold —
  * gating on it would buy a slow read of the whole workflow tree whose exit code
  * is 0 by construction. What CI can hold is the half that HAS a verdict, the
- * self-test. That self-test is not fixture-only either: it reads the real
- * pr-automation.yml and walks the real packages tree in the cases where a
- * fixture cannot prove the point, so the derivation's contact with reality is
- * covered by this gate too.
+ * self-test. That self-test is not fixture-only either. In the cases where a
+ * fixture cannot prove the point it runs the same discovery the tool does —
+ * every workflow file in the tree, and then the source of every gate that
+ * discovery finds — sweeps the tracked corpus, builds temporary git
+ * repositories with real history and drives changedPathsFromGit against them,
+ * and re-runs the tool's own CLI as a child process against the real checkout:
+ * invoked directly, through a symlink to it, and imported by a consumer
+ * module, plus a spawned import that reads a sibling gate's live table. So the
+ * derivation's contact with reality is covered by this gate too — and most of
+ * what the paragraph above calls a slow read is already paid for here, with a
+ * verdict attached to it.
+ *
+ * ⛔ That description carries no figures, deliberately. The count of workflows,
+ * of gate sources, of files swept and of temporary repositories all move with
+ * the tree, and one frozen in a comment goes stale without anything failing —
+ * which is exactly how the older spelling of this paragraph ("it reads the
+ * real pr-automation.yml and walks the real packages tree") came to describe a
+ * self-test far smaller than the one CI runs, in the file the lint workflow
+ * sends readers to for the measured argument. A reading belongs to a named
+ * commit, not to a header. Same repair, and the same reason, as the cost note
+ * in the workflow comment that points here (#12831).
  *
  * ## Why this file exists instead of pointing the script at the tool directly
  *