fix(pm): name the ratchet invocation CI runs in dispatch-gates' test-file entry (#8611)

* fix(pm): name the ratchet invocation CI runs in the dispatch-gates test-file entry

The convention entry for a change that adds a test file emitted
check:type-check-coverage with a rationale that describes the TEST_DEBT
ratchet — a half only check:type-check-debt (--re-measure) runs. A dev
seat that ran the named command in good faith reported green while the
ratchet had never run locally; CI then found four new type errors.

Both invocations are now emitted, each stating the question it answers,
and the ratchet line carries its built-closure prerequisite inline with
the exact build command lint.yml runs before that step — an unexplained
throw on a cold worktree reads as "not applicable to me".

Fixes #8545

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WuTtyckQa1VcXwgd52JpN

* docs(pm): correct check-dispatch-gates' header on comment masking, and fix the sweep count

The header justified its unquoted repo paths with "watch-hint extraction
... does not skip comments". extractWatchHints has opened with
maskComments since #8478, and that function's docblock names this file as
the specimen it retires — so the file carrying the workaround was still
explaining it as live behaviour.

Measured with extractWatchHints, every repo path in the header rewritten
into backticks: 1 hint today (the module-body constant, the same hint the
file ships with) against 10 under the pre-masking extractor. Comment
masking alone accounts for it. The incident is kept as history, the
section now says the convention is no longer required, and the rule that
survives is stated: a module-body literal is what masking cannot reach.
The separate-gate-file argument gets today's numbers too — 4 hints, not
49, and three of them are directory bases wide enough to keep the
decision standing on narrower grounds.

Fixes #8604

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WuTtyckQa1VcXwgd52JpN

---------

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

Author: hotlong

scripts/pm/check-dispatch-gates.mjs

@@ -6,8 +6,6 @@
  *
  *   node scripts/pm/check-dispatch-gates.mjs   # runs the tool's --self-test
  *
- * ⚠️ This header names repo paths UNQUOTED on purpose — see the last section.
- *
  * ## Why the gate exists
  *
  * scripts/pm/dispatch-gates.mjs derives the "local gates for this card" line of
@@ -53,21 +51,48 @@
  * none"), so shipping it as the price of gating the tool would have taken more
  * from every dispatch prompt than the gate gives back.
  *
+ * Those numbers are PRE-MASKING, and the decision they justify survives on
+ * narrower grounds than they describe. maskSelfTests now blanks the fixture
+ * half outright: measured on this tree, the tool's own source yields 4 hints,
+ * not 49 — .github/workflows, which it really reads, and packages/plugins,
+ * packages/drivers, packages/services, the bases its package resolver probes.
+ * Those three are real reads and still cover three of the largest directories
+ * in the tree, so a directly-wired gate would print MATCHED for every card
+ * under them — a smaller fabrication than the fixture one, of the same kind.
+ * The spec filter path from the incident above no longer matches at all.
+ *
  * A separate gate file is also what the other two pm gates look like
  * (check-skill-line-ratchet.mjs, check-skill-id-lint.mjs). Its watch hints are
  * the one constant below: this gate is matched for a card that edits the tool,
  * and for nothing else — which is the blind spot #8162 is about.
  *
- * ## Why the paths above are unquoted
+ * ## Why the paths above are unquoted, and why that is no longer required
  *
- * Watch-hint extraction reads any quoted-looking span, backticks included, and
- * does not skip comments. Written the ordinary way, with each path in backticks,
- * this header alone yielded ten hints — packages/spec/src, packages/objectql,
+ * The incident is real and worth keeping. Watch-hint extraction reads any
+ * quoted-looking span, backticks included, and it USED TO read comments as
+ * well. Written the ordinary way, with each path in backticks, this header
+ * alone yielded ten hints — packages/spec/src, packages/objectql,
  * packages/plugins, packages/drivers, .claude/agents, .changeset among them —
  * and reproduced, from the file explaining the pollution, the exact false
  * MATCHED leads it exists to avoid (measured, not predicted: the first draft of
- * this file did it). So paths are named unquoted here, and the only quoted path
- * in this file is the one input this gate genuinely has.
+ * this file did it). Hence the convention.
+ *
+ * The extractor no longer works that way: extractWatchHints opens with
+ * maskComments, whose own docblock names this file as the specimen it retires.
+ * Measured on this tree, with every repo path this header names rewritten into
+ * backticks: 1 hint under today's extractor — scripts/pm/dispatch-gates.mjs,
+ * the same single hint the file ships with — against 10 under the pre-masking
+ * one, reaching spec, objectql, plugins, drivers, .claude/agents and .changeset
+ * exactly as the incident describes. Comment masking alone accounts for the
+ * difference: masking self-test bodies instead changes nothing here, because
+ * this file has none.
+ *
+ * So the unquoting is no longer load-bearing, and this section is history
+ * rather than an instruction: quoting a path in a comment here is now free, and
+ * the paths stay unquoted because rewriting them buys nothing. What is NOT free
+ * is a path literal in a module body — masking cannot reach one — so the one
+ * quoted path below is still the one input this gate genuinely has, and that is
+ * the rule to carry into a new gate's header rather than the unquoting.
  *
  * Nothing else belongs in this file. Assertions go in the tool's own self-test,
  * beside the code they judge; this is the CI invocation and its reason.

scripts/pm/dispatch-gates.mjs

@@ -719,6 +719,31 @@ export function i18nBundlePackageDirs() {
  *   CI does not silently stop being suggested — the run prints it as STALE and
  *   says to fix this table. A hand-written list that reports its own rot is a
  *   different object from one that quietly ages.
+ * - Every `name` here is an INVOCATION, not a script. One check script can be
+ *   wired into CI under two package scripts that answer different questions, and
+ *   a rationale that names the script instead of the invocation sends a seat to
+ *   a command which cannot reproduce the failure it describes.
+ *   `check:type-check-coverage` and `check:type-check-debt` are one file
+ *   (`scripts/check-type-check-coverage.mjs`); only the second passes
+ *   `--re-measure`, which is the half a new test file's type errors move. This
+ *   entry named the first while explaining the second, so a dev seat ran it in
+ *   good faith, reported the union green, and CI found four new type errors.
+ *   Swept over this tree when that was fixed: the workflows discover 96
+ *   families resolving to 73 distinct script files, and 8 of those files are
+ *   reached by more than one family — 7 of the 8 in the other shape, a `check:`
+ *   script beside a direct `node scripts/check-x.mjs` step in a second
+ *   workflow, which `derive` discovers as its own family and prints with its
+ *   own runnable invocation. The pair below is the only one where two ROOT
+ *   SCRIPTS differ by a flag, so this is a one-off today and what generalises
+ *   is the rule, not the fix.
+ * - Prose in a `why` is a MODULE-BODY string, so it is scanned for watch hints
+ *   like any other literal — comment masking cannot reach it. The ratchet
+ *   entry's remedy command therefore spells its `--filter` values unquoted (and
+ *   says to quote them for the shell): measured, the shell-quoted spelling adds
+ *   both of its glob filter values to THIS file's own hint set as hints, inert
+ *   only because `hintCovers` rejects one that collapses to a bare top-level
+ *   directory. A gate list that fabricates hints out of its own explanations is
+ *   the failure this whole script is written against.
  * - Each entry is deletable, with a stated criterion:
  *   - test-file entry: when a gate on it grows a discoverable path literal,
  *     the ordinary derivation names it and its line becomes redundant.
@@ -741,7 +766,11 @@ export const CHANGE_KIND_GATES = [
       },
       {
         name: 'check:type-check-coverage',
-        why: "TEST_DEBT ratchets a package's test-layer type errors, so a new test file that does not typecheck cleanly moves it",
+        why: "the STRUCTURAL half: a package whose test files sit outside every tsc program accounting for it must carry a TEST_DEBT entry, so a new test file no tsconfig reaches moves this one. It re-measures no count — the ratchet is the invocation below",
+      },
+      {
+        name: 'check:type-check-debt',
+        why: "the RATCHET half, and the invocation CI runs for it: `--re-measure` re-runs tsc per ledger entry and fails when a count drifts up, so a new test file that does not typecheck cleanly moves it. Needs the workspace closure BUILT — on an unbuilt worktree it refuses outright, and that throw means NOT MEASURED, never `not applicable to me`. Build first, exactly as lint.yml does: pnpm exec turbo run build --filter=./packages/* --filter=./packages/*/* (quote the filter values for your shell)",
       },
     ],
   },
@@ -1077,8 +1106,8 @@ function selfTest() {
 
   const resolved = (name) => `pnpm ${name}`;
   const kindHit = changeKindLines(['packages/objectql/src/engine.test.ts'], resolved);
-  t('a test path emits the convention section', kindHit.length === 3 && kindHit[0].includes('adds or edits a test file'));
-  // Both halves anchor on the rendered DELIMITERS (`- pnpm x   —`), for the
+  t('a test path emits the convention section', kindHit.length === 4 && kindHit[0].includes('adds or edits a test file'));
+  // All three halves anchor on the rendered DELIMITERS (`- pnpm x   —`), for the
   // reason the i18n entry's pins below state at length: a bare `includes` is
   // satisfied by every name that merely STARTS WITH the expected one, so a
   // prefix-preserving rename is invisible to it — the single rot class the STALE
@@ -1087,7 +1116,20 @@ function selfTest() {
   // `check:type-check-coverage-v2` in CHANGE_KIND_GATES left the substring form
   // green at 61/61 while the live run printed both as STALE; anchored, the same
   // rename fails this case. The two conventions in this file now agree.
-  t('the section names both convention gates, runnably', kindHit.some((l) => l.includes('- pnpm check:query-options-erasure   —')) && kindHit.some((l) => l.includes('- pnpm check:type-check-coverage   —')));
+  //
+  // The coverage/debt PAIR is pinned as a pair on purpose (#8545): they are two
+  // invocations of one script, and the anchored form is what tells them apart —
+  // `includes('pnpm check:type-check-coverage')` is satisfied by the debt line's
+  // absence AND by a `-v2` rename, which is how a rationale describing the
+  // ratchet went on naming the invocation that never runs it.
+  t('the section names all three convention gates, runnably', kindHit.some((l) => l.includes('- pnpm check:query-options-erasure   —')) && kindHit.some((l) => l.includes('- pnpm check:type-check-coverage   —')) && kindHit.some((l) => l.includes('- pnpm check:type-check-debt   —')));
+  // The ratchet line's prerequisite is part of the product, not decoration: a
+  // seat that runs `--re-measure` on an unbuilt worktree gets a throw, and an
+  // unexplained throw reads as "not applicable to me" — which is a green report
+  // over a gate that never ran. So the printed line must carry both the
+  // condition and a command that satisfies it.
+  const debtLine = kindHit.find((l) => l.includes('- pnpm check:type-check-debt   —')) ?? '';
+  t('the ratchet line states its built-closure prerequisite', /closure BUILT|BUILT closure/.test(debtLine) && debtLine.includes('turbo run build'));
   t('a non-test path emits nothing', changeKindLines(['scripts/pm/dispatch-gates.mjs'], resolved).length === 0);
 
   // i18n change-kind derivation — the pure judgments first, each mirroring one
@@ -1287,7 +1329,14 @@ function selfTest() {
   // The table's own rot detector: a name no live run discovers must say so,
   // never disappear quietly.
   const stale = changeKindLines(['a.test.ts'], () => null);
-  t('an undiscoverable gate renders as STALE', stale.filter((l) => l.includes('STALE')).length === 2);
+  t('an undiscoverable gate renders as STALE', stale.filter((l) => l.includes('STALE')).length === 3);
+  // Per NAME, anchored on both sides of the rendered name (`⚠ x: STALE`), so the
+  // pair that shares one script is reported apart: a count alone stays green if
+  // one of the two is dropped from the table and something else is added, and a
+  // leading substring stays green through a `-v2` rename — the two ways this
+  // table has actually rotted.
+  t('the coverage half renders STALE under its own name', stale.some((l) => l.includes('⚠ check:type-check-coverage: STALE')));
+  t('the ratchet half renders STALE under its own name', stale.some((l) => l.includes('⚠ check:type-check-debt: STALE')));
   const i18nStale = changeKindLines(['packages/services/service-messaging/scripts/i18n-extract.config.ts'], () => null);
   t('an undiscoverable check:i18n renders as STALE', i18nStale.filter((l) => l.includes('⚠ check:i18n: STALE')).length === 1);
   t('every declared convention gate carries a reason', CHANGE_KIND_GATES.every((k) => k.gates.every((g) => g.name && g.why)));