fix(pm): mark CI-measured-only gate families instead of listing them as runnable

[baozhoutao]

Fixes #14004

dispatch-gates advertised node scripts/pm/check-governed-queue-guard.mjs among the families under "Local gates for this card (paste into the dispatch prompt)", and emitted it from --commands, whose caption promises one runnable command per line. That gate judges the merge-queue event payload and nothing else, so outside a workflow run its only possible outcome is EXIT=1. Every dev on a .claude/agents/** diff harvested 10 commands and got 9 green and 1 structurally red on a clean tree.

The derivation now classifies such a family by SHAPE, marks it in the human rendering, flags it in --json, and omits it from --commands.

⛔ scripts/pm/check-governed-queue-guard.mjs is NOT touched. Its refusal is correct and deliberate — "could not look" must never exit 0 — and triage ruled option 2 out: 「不要改那个门禁。」 The defect was upstream of it, and that is where this lands.

Premise re-check (fresh origin/main, fa1eca3)

what the card measured	re-measured here
a diff touching .claude/agents/os-dev.md derives the queue-guard row among the local gates	still true — 10 families, the guard among them
the guard refuses locally with EXIT=1	still true, byte-for-byte the same refusal text
grep -c 'GITHUB_EVENT_PATH|ciOnly|ci-only' scripts/pm/dispatch-gates.mjs is zero	still 0 — nothing at the derivation layer marked the row

Premise valid; the card is live.

The shape criterion — measured, which is the part triage left to this lane

Triage leaned to shape detection over a hand-maintained list and explicitly left the criterion's cost to be measured here. Measured on fa1eca3, over the 200 discovered families:

limb	what it reads	families selected
1 — payload dependence	the gate's own source ACCESSES process.env.GITHUB_EVENT_PATH (dotted or bracketed, through a local env alias too), with comments and self-test bodies masked	1
2 — no local invocation	a direct workflow run: family (never a check:* npm script) whose file no root manifest script names	43
conjunction (the rule)	both	1 — scripts/pm/check-governed-queue-guard.mjs

Cost of the derivation itself: zero new I/O. discoverFamilies already reads every family file once for four other answers; the payload dependence is a fifth answer off that same read, so it cannot describe a different revision of the gate than the hints printed beside it.

Three narrowings, each with the measurement that chose it:

1. The conjunction, not limb 1 alone. Limb 2 buys nothing today (1 either way) and is not there for today. This classification SUBTRACTS a row from --commands; a subtraction that fires wrongly is silent (a real gate quietly missing from the runnable list, every dispatch order still reading normal), while a miss is loud (the status quo). The same trade one screen up in that file — declaredInheritedPopulation — was decided the same direction by maintainer ruling on 2026-08-28. A gate with a check:* name, or one that reads the payload with a git fallback, keeps its place in the list and keeps its loud red.
2. GITHUB_EVENT_PATH alone, not the wider GITHUB_EVENT_NAME / GITHUB_BASE_REF / GITHUB_HEAD_REF / GITHUB_REF_NAME family — those are routinely read WITH a local fallback, while the payload path is the run's input or nothing. Measured: exactly one tracked file in the repo names any of the five, so widening the set changes zero classifications. The narrowing is a statement about tomorrow's gate, not today's count.
3. Comments and self-test bodies masked, the same normalization extractWatchHints applies. Today the masked and unmasked answers agree (one file names the variable and also accesses it), so the masking costs nothing — it is the difference between classifying a gate and classifying its docblock, in the direction where a false positive is silent.

⚠️ What the rule does NOT claim: that the gate refuses. It reads a dependence, not a control-flow proof. That is why the family stays NAMED, with its provenance and the reason printed beside it, in every rendering — an annotation a reader can check against the gate, never a family this tool quietly disappears.

Not shipped, and the measurement that decided it: annotating the row with the gate's offline --self-test entry point. The workflow does invoke node scripts/pm/check-governed-queue-guard.mjs --self-test at governed-surface-guard.yml:104, but that invocation is deliberately not a discovered family (extractCheckInvocations skips a --self-test key whose script already has a check- basename, to avoid splitting one family into two), so surfacing it would need a second scan of the workflow text rather than data already in hand. Out of proportion to the row it decorates.

Before / after, on a diff touching .claude/agents/os-dev.md

BEFORE — 10 rows in the pasted block, the last one structurally red wherever a dev runs it:

Local gates for this card (paste into the dispatch prompt):
  - pnpm check:agent-model-declared   [lint.yml]   matched via ...
  ... 8 more ...
  - node scripts/pm/check-governed-queue-guard.mjs   [governed-surface-guard.yml]   matched via .claude/agents/os-dev.md ⇢ gate source '.claude/agents/os-dev.md'

10 matched families — 9 pnpm, 1 direct node.
Reconciliation — 10 famil(ies): this card's WHOLE runnable answer ...

--commands emitted all ten.

AFTER — 9 runnable rows in the pasted block; the family is still named, once, under its own heading past the blank line the published harvest stops at:

Local gates for this card (paste into the dispatch prompt):
  - pnpm check:agent-model-declared   [lint.yml]   matched via ...
  ... 8 more, all pnpm ...

9 matched families — 9 pnpm, 0 direct node.
  ⇒ Harvest with --commands ...

CI-measured only — matched by path, and NOT runnable here (1 famil(ies)):
  - node scripts/pm/check-governed-queue-guard.mjs   [governed-surface-guard.yml]   matched via .claude/agents/os-dev.md ⇢ gate source '.claude/agents/os-dev.md'
      ↳ reads the workflow event payload (GITHUB_EVENT_PATH) and is invoked only by its workflow — outside a run there is no payload to judge, and a guard that "could not look" must never exit 0, so a local run of this can only ever exit nonzero. CI measures it on the PR; there is nothing to run here, and a red from running it anyway is not a finding.
  ⇒ Derived from the gate's own source, not from a list of names: a family that reads the payload and has no local invocation classifies itself.

Reconciliation — 9 famil(ies): this card's WHOLE runnable answer, and the number to assert a harvest against.
  9 named by PATH (the matched block) + 0 named by change KIND (the convention block) ⇒ 9 distinct.
  + 1 famil(ies) this card's paths reach are CI-MEASURED ONLY and sit OUTSIDE this total — they read the workflow event payload, so no local run of them can produce a verdict. Named under their own heading above, carried on their row in --json, and omitted from --commands by design.

--commands now prints 9, and its stderr accounting names the omission out loud beside the two omissions that mode already declared (pending-changeset families, always-runs tail) — a quiet omission inside a fix for a quiet omission is how that defect reproduces itself one layer up.

--json keeps the family as a matched row and flags it (matched[].ciOnly.env), so a machine consumer READS the omission instead of inferring it from a missing row.

--tier is structurally unaffected: its CLI branch never enters derive, discoverFamilies, commandsFor or the reconciliation.

Self-test

pnpm check:pm-dispatch-gates (the documented entry — it spawns the tool's --self-test) at 4b6dca186:

✓ dispatch-gates self-test: 1174 cases pass.
os-verify-lock: VERDICT command-exit 0 · held the lock 687s (11m27s) · waited 1s

0 failing cases. 34 of the 1174 are new here.

New cases, in the halves the file separates:

• Unit — limb 1 reads both access spellings; a comment-only mention, a message string, a self-test fixture and an unrelated env read are each NOT classified; the LIVE guard source still carries the dependence (a fixture-only pin would stay green if that gate were rewritten). Limb 2 refuses a family a root manifest script names, refuses a check:* family outright, and limb 1 is pinned as REQUIRED (without it limb 2 alone would subtract 43 families).
• Live derivation — exactly one family classifies, and it is the queue guard; check:nul-bytes does not; and at least one directly-invoked gate that reads no payload does not either, so the rule discriminates rather than sweeping.
• Renderings — --commands omits the row and keeps the runnable one, and keeps it omitted when a change KIND names the same family (the other section it could arrive through); the reconciliation closes on that input and carries the omission as its own term rather than charging it to a repeat; a card whose ONLY match is CI-measured still says so at a total of zero rather than reading as "nothing matched".
• End to end, on .claude/agents/os-dev.md — a CONTROL that the family is still derived at all (a rule that dropped it entirely would pass every case below); the real published harvest snippet, driven with real awk/sed over the real rendering, no longer yields the command; --commands agrees with that harvest exactly; the human rendering still names the family with its workflow, provenance and reason; --json flags it and excludes it from commands; the stderr accounting says so.

Gates run

Derived on the real changeset with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths — the script takes the change set off the merge base itself), plus the two the dispatch named. All run at 4b6dca186, each exit code captured before any pipe:

gate	reading
check:pm-dispatch-gates	0 — "✓ dispatch-gates self-test: 1174 cases pass." (11m27s under the shared verify lock)
check:declared-population-live	0 — "156 of 200 famil(ies) declare a path population, and every one of them reaches this tree's 7811 tracked file(s)"
check:ratchet-remedy-authority	0 — "183 scripts swept; 12 mark the expanding remedy ⛔ MAINTAINER-ONLY, 6 turn it down outright, 165 hand out no ratchet-expanding remedy"
check:nul-bytes · check:agent-test-spelling · check:bash32-floor · check:cli-command-ids · check:cross-package-test-inputs · check:entry-guard · check:parse-guard · check:pnpm-filter-targets · check:watch-hint-literal	0 each
check-ci-filter-parity · check-cross-package-test-inputs · check-self-test-wired · check-shard-attestation	0 each
check-test-completeness	NOT MEASURED, exit 3 — it grades a saved turbo run test log and the family names it with no argument; its own banner says this branch is unreachable in CI and is not a red

Also self-scanned for control bytes beyond the gate (grep -naP over the edited file, exit 1 = none).

The two yaml-importing gates first returned exit 3 PREREQUISITE NOT MET in a fresh worktree; re-run after pnpm install they are green, and that first reading is recorded as NOT MEASURED rather than as a pass.

Changeset route

skip-changeset. The diff is one file, scripts/pm/dispatch-gates.mjs — PM tooling that publishes nothing from any package, so there is no user-visible change to record. Label applied at PR-open time (never left for the Check Changeset step to redden first) and read back.

---

Generated by Claude Code