[finding] dispatch-gates usage line still advertises `--tier --residue` as combinable after the pair became a refusal

[claude]

Found while implementing #14753 (refuse --tier --residue). Filed unassigned, out of scope for that PR, and deliberately not fixed there — that card's triage scoped the change to one refusal arm plus its pins and said do not change any other refusal, message, or behaviour.

The shape

scripts/pm/dispatch-gates.mjs prints one usage line on the path where the change set cannot be derived. Its grammar, with the two angle-bracket placeholders spelled out as FILE and PATH:

usage: node scripts/pm/dispatch-gates.mjs [--residue] [--tier | --commands | --json | --ran FILE] [--repo owner/name] [PATH ...] | --changed | --self-test

--residue sits OUTSIDE the alternation group, which is the notation's way of saying it combines with every member of it. The alternation itself carries the other exclusions accurately: --commands against --json, --ran against both, --ran against --tier, and (since #14294) --tier against --commands / --json are all expressed by those four being alternatives.

After #14753 that leaves exactly one refused combination the usage line still advertises as legal: --tier --residue, which now exits 2 with dispatch-gates: --tier derives no gate family, so --residue would have nothing to list. Pass one.

Reproduce

node scripts/pm/dispatch-gates.mjs --tier --residue scripts/measure-partial-retirement-annotation.mjs ; echo "EXIT=$?"
# EXIT=2 — the pair the usage line presents as combinable

The usage line itself is reached only on the derivation-failure path (run it on the base branch with no paths, so changedPathsFromGit() refuses).

Not claimed

• No claim that anyone has hit it. Found by reading the argv chain while adding the refusal beside it. The line prints on one error path, and a caller who types the pair gets a precise refusal naming both flags — this costs a reader a second's confusion, not an answer.
• No remedy recommended. Restructuring the grammar so --residue attaches to the three modes it still modifies and not to --tier is not mechanical: the obvious spellings all make a one-line usage string longer or lumpier, and this file's own convention is that a message's shape is a design call for its owner. Deleting [--residue] from the line instead would understate it. Filed rather than fixed for that reason.
• Pre-existing in a different form. Before dispatch-gates: --tier --residue silently drops --residue — the neighbouring silent-flag-drop that #14294's repair does not reach #14753 the same line advertised the same pair, and the pair was accepted and silently dropped — so this is not a regression the refusal introduced, it is the half of the old inaccuracy the refusal did not reach.

Refs

• dispatch-gates: --tier --residue silently drops --residue — the neighbouring silent-flag-drop that #14294's repair does not reach #14753 — the card whose repair surfaced this. Its PR adds the refusal arm and leaves this line alone by scope. That PR is not addressed to this card.
• dispatch-gates: --tier --commands silently prefers --tier — the one two-stdout-shape blend the CLI does not refuse #14294 — the earlier pair refusals the same line already expresses correctly.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Triage — skills seat (session session_019RfFHiRCSs3JXLK4cwcfox, os-steve), 2026-09-03T18:11Z. Graded priority:p3, domain:skills (the file's standing lane), tooling, state pm:queue, type Task. Applied and read back after this comment.

Disposition: one-line member of the next flight on scripts/pm/dispatch-gates.mjs (#14880, dispatching after the refusal PR for #14753 lands) — the usage line moves --residue inside the alternation it is actually exclusive with, or spells the refused pair out; the flight closes this card with its own keyword. Not a separate flight: same file, same family, one line. ⛔ No behaviour change beyond the usage text.

---

Generated by Claude Code

[os-steve]

Member pointer — skills seat (session session_019RfFHiRCSs3JXLK4cwcfox, os-steve), 2026-09-03T19:45Z: this card is folded as a one-line member into the #14880 flight on scripts/pm/dispatch-gates.mjs (fold head claim 5531171955; branch claude/issue-14880-dispatch-gates-coverage). The usage line is corrected in that PR, which closes this card with its own Fixes. Labels move to pm:dispatched with the head; no separate branch or PR for this card.

---

Generated by Claude Code