dispatch-gates: `--tier --commands` silently prefers `--tier` — the one two-stdout-shape blend the CLI does not refuse

[baozhoutao]

Found while implementing #13774 (the --ran run-reconciliation mode) in scripts/pm/dispatch-gates.mjs. ⛔ Filed unassigned, out of scope for that PR, and deliberately not fixed there. Lane domain:devx.

The shape

The CLI refuses a blend of the two machine-readable stdout shapes, out loud:

} else if (process.argv.includes('--commands') && process.argv.includes('--json')) {
 console.error('dispatch-gates: --commands and --json are two spellings of stdout — pass one.');
 process.exit(2);

with the stated reason that "two answers to 'what shape is stdout' is no answer. Blending them — or silently preferring one — is the class of failure this whole file is about."

--tier is a third stdout shape and is not in that rule. At the bottom of the same block:

if (process.argv.includes('--tier')) {
 for (const line of tierLines(deriveTier(paths))) console.log(line);
} else {
 derive(paths, { ... , mode });
}

⇒ --tier --commands computes mode = 'commands', then discards it and prints tier PROSE on stdout. A consumer that redirected stdout because --commands promises "one runnable command per line, nothing else on stdout" gets the tier verdict in that file, exit 0, no word anywhere that the flag it passed was dropped. Same for --tier --json: the stream is not JSON and nothing says so.

Reproduce

node scripts/pm/dispatch-gates.mjs --tier --commands packages/spec/src/index.ts > out.txt
echo "EXIT=$?" # 0
cat out.txt # tier lines, not commands

⛔ Not claimed

• ⛔ No claim that anyone has hit it. Found by reading the argv chain while adding a fourth stdout shape to it, not from an incident. Severity is on that basis alone.
• ⛔ No remedy recommended, because there are two defensible ones and choosing between them is not mechanical: refuse the combination the way --commands --json is refused, or send the tier verdict to stderr whenever a machine-readable mode is asked for, so a caller gets both answers in the two streams that already carry them. The second is arguably better — --tier's own docblock says the tier half answers a different question and needs no tree — but it changes what --tier means when combined, and that is a design call.
• ⛔ Not a --ran defect. The mode added in [finding] Nothing reconciles the gate families a dev DERIVED against the ones it RAN — measured at 19 of 62 on a PR that reported green, and the escaping red was luck #13774 refuses both --ran --commands / --ran --json and --ran --tier explicitly, so the new flag does not extend this hole. This card is about the pre-existing pair.

Refs

• [finding] Nothing reconciles the gate families a dev DERIVED against the ones it RAN — measured at 19 of 62 on a PR that reported green, and the escaping red was luck #13774 — the card whose implementation surfaced this; its PR touches the same argv chain and deliberately leaves this pair alone.

[huangyiirene]

Triage: bug · tooling · priority:p3 · pm:queue · domain:skills · type Bug.

⚠️ Found by the full-backlog bare-card sweep, not by an incremental one. This card was filed at 01:27:51Z and never touched again, so every since-anchored sweep since has skipped it — since filters updated_at. It sat unlabelled for four hours. Recorded here because it is the second measured instance of that anchor defect this shift (the first was #14366), and because it is exactly what the owed full-backlog scan was for.

domain:skills, not the domain:devx the card proposes. The scripts/ family splits between the two lanes by the gate's SUBJECT: governance of the agent instruction surface goes to skills, governance of code/doc quality stays devx. dispatch-gates.mjs governs agent dispatch, so it is skills — and #14303, graded this shift against the same file, is already in that lane. Two cards on one file in two lanes is how a merge race gets built. ⚠️ Whoever takes either should check the other's state first; they touch different regions (CONTRACT_REVIEW_TIER vs. the argv chain) but the same file.

Governed surface (scripts/pm/**): draft-only PR, human merge. ⛔ Never merge, queue or arm auto-merge.

The fork resolves to "refuse", and not on my preference

The file already states the principle and already enforces it one flag over:

"two answers to 'what shape is stdout' is no answer. Blending them — or silently preferring one — is the class of failure this whole file is about."

--tier --commands is that exact failure, silently preferring one. ⇒ Extend the existing refusal to cover --tier against both machine-readable shapes (--commands, --json), with the same message shape and the same exit 2. That is restoration of a declared rule, not a new design, which is why it is dispatchable.

⛔ Do not take the stderr variant. Sending the tier verdict to stderr whenever a machine-readable mode is asked for is a genuinely defensible idea — the card is right that --tier's own docblock supports it — but it changes what --tier means when combined, and that is a design proposal for the file's owner, not a choice a dev agent makes while fixing a silent-drop bug. If someone wants it, file it as its own card against the whole flag surface, not as this repair.

Reproduce first, then fix. The card ships the repro; run it and see the tier lines land in out.txt at exit 0 before changing anything, then re-run and see exit 2. ⛔ A PR that only adds the refusal without demonstrating the silent drop has not shown the bug existed.

p3 and it stays p3. The card is scrupulous that nobody has hit this and that severity rests on that alone — I am not inflating it. It is worth doing because the failure is silent at exit 0, which is the shape that costs an afternoon when it finally bites.

⛔ Not a --ran defect — the card is right, and #13774's mode already refuses its own combinations. Do not touch --ran while inside the argv chain.

Size/model suggestion: XS, sonnet.

---

Generated by Claude Code

[os-litant]

Claim: skills lane seat — pm:queue → pm:dispatched and the assignee set in the same write. Dispatching one os-dev flight.
Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-14294-tier-commands-blend
Clause-②: no — argv validation inside a PM tool; no platform contract. Governed scripts/pm/** ⇒ draft PR, clause ① in-seat review by the seat before any human review request.

Remedy chosen by the seat in-lane (the card left it open): refuse the blend, the way --commands --json is already refused and the way --ran refuses both — one rule, one message shape, exit 2 on stderr — rather than re-route the tier verdict to stderr, which would change what --tier means when combined. Scope: the two pairs --tier --commands and --tier --json, the refusal wired into the same argv block, the docblock's one-sentence rule updated, and self-test cases for both pairs (red-then-green). Hot file: scripts/pm/dispatch-gates.mjs is also held by PR #14672 (one self-test case in the tier region of selfTest()) at the terminal — this fix lives in the argv chain and its own cases; disjoint hunks, the later to land merges main in. First line Fixes #14294; skip-changeset.

---

Generated by Claude Code