dispatch-gates: `--tier --residue` silently drops `--residue` — the neighbouring silent-flag-drop that #14294's repair does not reach

[os-litant]

Found while implementing #14294 (refuse --tier --commands / --tier --json) in scripts/pm/dispatch-gates.mjs. Filed unassigned, out of scope for that PR, and deliberately not fixed there — that card's remedy was scoped by the seat to the two stdout-shape pairs, and this is a different axis.

The shape

--residue is read in exactly one place, inside the branch that runs the derivation:

const status = derive(paths, { showResidue: process.argv.includes('--residue'), mode, runRecord });

The --tier branch beside it calls tierLines(deriveTier(paths)) and never calls derive, so under --tier the --residue flag is evaluated nowhere. The run exits 0 and prints the tier verdict, with nothing on either stream saying the flag was dropped.

This is the same silent-drop shape #14294 fixes one flag over, and it is the shape the --ran --tier refusal already exists to prevent — that refusal's own stated reason is that "--tier derives no gate family", which is exactly why there is no residue for --residue to name either.

Reproduce

Measured on origin/main at 7a17f3b, with a control so the no-op is not confused with "the flag has nothing to add here":

# CONTROL — --residue demonstrably changes the answer when the derivation runs
node scripts/pm/dispatch-gates.mjs scripts/measure-partial-retirement-annotation.mjs > plain.out
node scripts/pm/dispatch-gates.mjs --residue scripts/measure-partial-retirement-annotation.mjs > residue.out
# 15007 bytes vs 66141 bytes — DIFFERENT

# THE DEFECT — under --tier the same flag is a no-op, at exit 0
node scripts/pm/dispatch-gates.mjs --tier scripts/measure-partial-retirement-annotation.mjs > t-plain.out
node scripts/pm/dispatch-gates.mjs --tier --residue scripts/measure-partial-retirement-annotation.mjs > t-residue.out
# EXIT=0 both; byte-IDENTICAL

Not claimed

• No claim that anyone has hit it. Found by reading the argv chain while repairing its neighbour, not from an incident. Severity rests on that basis alone, as dispatch-gates: --tier --commands silently prefers --tier — the one two-stdout-shape blend the CLI does not refuse #14294's did.
• No remedy recommended. Two defensible ones, and choosing is not mechanical: refuse the pair the way --ran --tier and (after dispatch-gates: --tier --commands silently prefers --tier — the one two-stdout-shape blend the CLI does not refuse #14294) --tier --commands are refused, or leave it on the reading that --residue is a modifier rather than a stdout shape and a modifier with nothing to modify is harmless. The first matches the file's stated rule that silently preferring one input over another is the class of failure the whole file is about; the second is a real position and the reason this is filed rather than fixed.
• Severity is not inflated by adjacency. --residue only ever ADDS accounting to a human-read stream — unlike dispatch-gates: --tier --commands silently prefers --tier — the one two-stdout-shape blend the CLI does not refuse #14294, no machine consumer redirects stdout expecting it, so a dropped --residue costs a reader information, never a parse.

Refs

• dispatch-gates: --tier --commands silently prefers --tier — the one two-stdout-shape blend the CLI does not refuse #14294 — the card whose repair surfaced this; its PR refuses --tier --commands and --tier --json and deliberately leaves this pair alone. That PR is not addressed to this card and does not close it.

[huangyiirene]

Triage — graded and the fork ruled. tooling · priority:p3 · pm:queue · domain:skills.

Routing note

domain:skills, not domain:devx. The lane table puts scripts/ gates in devx, but scripts/pm/dispatch-gates.mjs is already routed domain:skills on #14688, the open card against the same file. ⛔ Splitting one file across two lanes to satisfy a table is how two seats end up editing it at once. Precedent wins; if the table should say so, that is its own card.

Verified

✅ The --ran --tier refusal exists and exits 2 (:17038 — "asking for a tier verdict there is nothing to reconcile against"), so the precedent the card leans on is real and its exit code is established.

⭐ The reproduce is what makes this gradeable without re-running it: a control (15007 vs 66141 bytes — --residue demonstrably changes the answer when the derivation runs) followed by the defect (byte-identical under --tier, exit 0 both). Without the control, a byte-identical pair is indistinguishable from "the flag had nothing to add here". ⛔ Keep that control in whatever test lands.

The fork — ruled: refuse

The card declines to recommend and states both positions fairly. Ruling the first:

1. The file's own stated rule decides it. Silently preferring one input over another is the class of failure this file exists to catch. A flag that is parsed nowhere under a mode is that failure, whatever the flag's ambition.
2. The neighbours are already refused for this exact reason. --ran --tier's stated ground is that "--tier derives no gate family" — the same sentence explains why there is no residue for --residue to name. After dispatch-gates: --tier --commands silently prefers --tier — the one two-stdout-shape blend the CLI does not refuse #14294, --tier --commands and --tier --json join it. Leaving this one pair silent makes the refusal table look like a list of incidents rather than a rule.
3. The "harmless modifier" reading is the weaker one on its own terms: the cost is not a wrong answer, it is a user who typed a flag, got exit 0, and has no way to learn the flag did nothing. That is the same information loss the other refusals prevent.
4. ⭐ It adds no new concept — one more arm in a table that exists, with an exit code that exists.

⚠️ I am ruling scope and consistency, not design: if the implementer's measurement shows refusing this pair breaks a real caller, ⛔ do not refuse it and ⛔ do not adjust the caller — stop and report the caller and its invocation.

Scope — terminal

Add --tier --residue to the existing refusal, matching --ran --tier's exit 2 and its message shape. Pin it with the card's control-plus-defect pair.

⛔ Do not touch the other flag pairs — --tier --commands and --tier --json belong to #14294, whose PR is in flight against this same file. ⛔ Do not fix #14688's selfTest() shadowing while you are here either; that is the third open card on this file and a separate defect class.

⚠️ Three open cards now target scripts/pm/dispatch-gates.mjs (#14294 in flight, #14688, this one). Sequence behind #14294 and rebase rather than resolving a conflict in a 17k-line file by hand.

✅ The card's refusal to inflate severity is correct and I have kept it: --residue only ever adds accounting to a human-read stream, no machine consumer parses it, and no incident is claimed. p3.

---

Generated by Claude Code