fix(pm): dispatch-gates refuses an absent path unless --repo asserts whose tree it is

[os-elon-musk]

Fixes #18383

A path named on argv that is not in this tree has two readings — a surface of THIS repo that is not written yet, and a path belonging to ANOTHER repo — and a repo-relative path cannot tell them apart. The tool resolved that ambiguity silently toward the harmless reading: exit 0, the absent path filed under "apply once this card's changeset exists", the gate list derived from THIS repo's workflows. A seat read that exit code and wrote "it refuses objectui paths by design" into five dispatch texts.

Unasserted, the ambiguity is now NOT MEASURED: the run ends at exit 3 (EXIT_PREREQUISITE_NOT_MET, this tool's existing NOT MEASURED code) with the absent paths listed and both resolving spellings printed verbatim, before any family derivation runs.

The three shapes, before and after

Measured on does/not/exist.mjs, exit codes captured before any pipe. Before = origin/main 7358c1c5b; after = this branch at ab0864186.

shape	before	after
(a) absent path, no --repo	exit 0, derived 7 commands	exit 3, NOT MEASURED, absent path named, stdout empty
(b) absent path, --repo objectstack-ai/objectstack	exit 0	exit 0 — byte-identical stderr+stdout to before
(c) absent path, --repo objectstack-ai/objectui	exit 2	exit 2 — byte-identical stderr+stdout to before, same text

The card's literal Reading, --commands skills/objectui/SKILL.md AGENTS.md with no --repo, went from exit 0 to exit 3 naming skills/objectui/SKILL.md.

Controls that must NOT move, all measured at ab0864186:

control	exit
real path, no --repo (--commands scripts/pm/dispatch-gates.mjs)	0
real path, --tier packages/spec/src/index.ts	0
a glob (--commands 'packages/*/src/index.ts') — a pattern is not an absent file	0
--changed — a tree's own diff cannot be another repo's	0

The refusal text:

dispatch-gates: NOT MEASURED — an absent path may be another repo's — assert --repo to derive as a not-yet-written path of THIS repo, or name the other repo to be refused.
  1 of 1 named path(s) are absent, and no --repo says whose tree they are from: does/not/exist.mjs
  Two readings, and nothing in a repo-relative path tells them apart. Pick one — copy a line:
    --repo objectstack-ai/objectstack   — they are paths of THIS repo that are not written yet; derive as before.
    --repo owner/the-other-repo   — they are another repo's; be refused with both repos named, from a checkout of that repo.
  (Exit 3 = NOT MEASURED, distinct from the 2 a usage error and the wrong-repo refusal carry. Capture it BEFORE any pipe.)

Shape of the change

• absentDeclaredPaths() extracted from bannerLines, so the banner's count and the refusal's list are ONE reading and can never name different sets.
• absentPathVerdict() — the verdict, mirroring repoAssertionVerdict's shape. Returns ok when there is nothing absent, or when an assertion is present at all: the wrong-repo refusal runs first and keeps its own exit 2 and its own text, so --repo other is unreached by this branch.
• One dispatch branch, placed after the assertion block and before every mode branch. Guarded by argvPaths.length > 0, so only paths NAMED on argv reach it.

Applied uniformly across modes, --tier included, and that is a deliberate call worth a reviewer's eye: --tier derives no family, but the wrong-repo refusal above it ALREADY ends a --tier run over another repo's slug (measured on origin/main: --tier does/not/exist.mjs --repo objectstack-ai/objectui exits 2), so the repo an answer is about is already load-bearing there. Exempting --tier would resolve the same ambiguity silently toward the harmless reading in the one mode a claim comment pastes from. Consequence, stated plainly: --tier PATH where PATH is not yet written now exits 3 until --repo is added.

The one in-tree caller this broke, and its repair

The self-test's pending-changeset probe hands the CLI a HYPOTHETICAL changeset path — the whole point of it — with no assertion. The new branch turned that case and the one below it red. The battery named both; this was measured, not predicted. Asserting the repo is the whole repair, and it is exactly the migration every dispatcher of a not-yet-written path owes. Both cases now assert a shape in EACH branch, so the no-readable-remote path pins the refusal rather than passing over empty output.

Caller census

git grep -n "dispatch-gates.mjs" -- scripts .github .claude = 284 hits across 108 files. Almost all are prose: other gate scripts' headers citing this file. Narrowed to real invocations:

• CI / hooks: none passes a path at all. package.json wires check:pm-dispatch-gates = node scripts/pm/check-dispatch-gates.mjs --self-test && node scripts/pm/check-dispatch-gates.mjs, which reaches this tool only by spawnSync(..., '--self-test'). .github/workflows/lint.yml's eight hits are that one step plus comments. The three .claude/hooks/* hits are allowlist fixtures naming --self-test and --repo objectstack-ai/objectstack. So no CI or hook invocation passes a possibly-absent path without --repo, and none is changed here.
• Two agent-facing prose lines instruct the shape that can now refuse — .claude/skills/pm-dispatch/SKILL.md:478 and .claude/skills/checklist-test/SKILL.md:98, both spelling --tier PATHS with no --repo. A PM claiming a card for a not-yet-written file gets exit 3 there until the flag is added. ⛔ Not changed in this PR (file surface is this script only) — listed as a finding for the seat.
• scripts/git-merge-regen.mjs:119 already spells --commands --repo objectstack-ai/objectstack; unaffected.

Gates

Derived in-worktree; --commands PATH --repo objectstack-ai/objectstack and the no-path re-derivation off the real change set produced identical 30-command lists, and the list was re-derived unchanged at the final head. All 30 run, exit codes captured before any pipe, then reconciled with --ran:

✓ dispatch-gates --ran: 30 derived famil(ies) accounted for — 30 run, 0 NOT-MEASURED
  (a DERIVED zero — all 30 recorded an exit code and none of them is 3).
Run reconciliation — 30 derived, 30 run, 0 NOT-MEASURED, 0 UNRUN.

All 30 exit 0 at ab0864186, including pnpm check:pm-dispatch-gates — this tool's own battery, run exactly as lint.yml step 「PM dispatch-gates self-test」 runs it (pnpm check:pm-dispatch-gates, repo root, no extra env), detached per the file header's foreground-cap rule with the exit code captured to disk:

✓ dispatch-gates self-test: 1746 cases pass.
check:pm-dispatch-gates: the battery took 631.6s on this box.   exit 0

The patch round, stated plainly

The first pushed head 284855e7f went red on CI at exactly this step, and it reproduced locally at that same commit: ✗ dispatch-gates self-test: 7 of 1742 case(s) failed. All seven were the two blocks that drive the CLI over the pending-changeset probe path — hypothetical by design, passed with no assertion — so the new refusal fired inside them and the derivation they assert on never ran.

Fixed on the CASE side, which is what the card's contract prescribes: those probes now assert the repo, spelled once in a runCliHypothetical helper beside runCli so every probe of a not-yet-written path carries it and the next one is written through the same door. ⛔ No case was skipped, disabled or loosened; ⛔ no exemption was carved for the self-test, for a fixture directory or for a .changeset/ prefix; ⛔ the refusal itself was not weakened.

The battery went 1742 → 1746 cases: the value-bearing block's inner cases sit behind if (doc && vbRows.length >= 1), so while the outer CONTROL was red they never ran at all. Four more cases now execute — the diagnostics-increase direction, not a rewrite.

Acceptance notes

• --json needed no new shape: a refusal prints nothing on stdout and exits non-zero, which is what --repo other already did (measured on origin/main: --json ABSENT --repo objectstack-ai/objectui = exit 2, 0 bytes of stdout). The new refusal matches it.
• With this checkout's origin unreadable the refusal says the assertion cannot be CHECKED either, rather than printing a slug it does not have — noted, not filed: an unverifiable identity plus an absent path is NOT MEASURED in both directions, which is the honest answer.

---

Generated by Claude Code

---

Generated by Claude Code