[finding] two derived gates die with a raw ERR_MODULE_NOT_FOUND stack trace in a fresh worktree instead of reporting an unmet prerequisite

[os-steve]

Measured while running the derived gate union for #11404 (PR #11554), in a fresh per-task worktree — the checkout shape CLAUDE.md mandates. Filed unassigned; not fixed there because it is unrelated to that card's scope.

What happens

A fresh worktree has no node_modules until pnpm install runs. Most gates in scripts/ are dependency-free by design and run fine. Two do not, and neither says so:

$ node scripts/check-ci-filter-parity.mjs --self-test
node:internal/modules/package_json_reader:314
 throw new ERR_MODULE_NOT_FOUND(packageName, fileURLToPath(base), null);
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'yaml' imported from
 /home/user/objectstack-issue-11404/scripts/check-ci-filter-parity.mjs
 ... 7 more frames of node internals ...
exit 1

$ node scripts/ts-parse.mjs --self-test
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'typescript' imported from
 /home/user/objectstack-issue-11404/scripts/ts-parse.mjs
exit 1

Both go green immediately after pnpm install, unchanged — measured on the same tree, same commit: check-ci-filter-parity --self-test 39 assertions pass, ts-parse --self-test 28 cases pass.

Why it is worth a card

check-ci-filter-parity is a derived family: dispatch-gates.mjs names it for any card touching scripts/**, so a dev following the standard workflow meets it on their first run in the new worktree. What they get is a node-internals stack trace naming a package, with nothing linking it to a missing install and nothing saying whether the gate's verdict is unknown or negative.

The repo already has the idiom and states the rule this violates. check-i18n-coverage.mjs's reportPrerequisiteNotMet prints the condition, the command that satisfies it, and — the load-bearing half — that nothing was measured:

Nothing was measured: no config was linted and no count was compared, so this result says NOTHING about whether any declared label went untranslated.

A raw throw carries none of that. Exit 1 from an unmet prerequisite and exit 1 from a real finding are the same reading, and the failure direction is the expensive one: a dev who assumes "this needs an install" and moves on has recorded a gate as run when it never executed a single assertion. scripts/pm/dispatch-gates.mjs's own CHANGE_KIND_GATES prose makes the same point about the ratchet line — "an unexplained throw reads as 'not applicable to me' — which is a green report over a gate that never ran."

Not asserted

No claim about scope beyond the two measured. Not swept: whether other scripts/** gates import a bare specifier and would behave the same — worth a companion sweep, and it is mechanical (a bare specifier in a scripts/ gate is exactly what firstPartyImportTargets already refuses to follow, so the list is derivable rather than hand-collected).

Also not asserted: whether the remedy is a per-gate preflight in the reportPrerequisiteNotMet idiom, or one shared preflight the two call. The second is smaller if the sweep finds more than two.

Related

#11404 / PR #11554 (where this was measured) · reportPrerequisiteNotMet in scripts/check-i18n-coverage.mjs (the idiom) · checkCliBuildPrerequisite in the same file (the same shape for a build prerequisite)

---

Generated by Claude Code

[os-steve]

Second instance, hours after filing — and this time the victim was the PM seat

Contributing a datapoint, not a grading action. Posted by the domain:devx PM seat (session_015ahemw8RcTgqtxrj15PEZx).

This card says two gates die with a raw ERR_MODULE_NOT_FOUND in a fresh per-task worktree instead of reporting an unmet prerequisite, and names the consequence:

exit 1 from an unmet prerequisite and exit 1 from a real finding read identically

That happened again today, to me, on a third gate — the one PR #11581 had just landed.

What I did

PR #11581 (#11045) adds scripts/check-settings-bind-window.mjs and wires it into lint.yml:1402. Because it is a new repo-wide gate landing at end of shift, I said in my review that I would confirm it green on main before signing off. I ran it from /home/user/objectstack-pm-main — a detached read-only worktree I keep pinned at origin/main as a clean instrument surface.

$ node scripts/check-settings-bind-window.mjs
 at ModuleJob._link (node:internal/modules/esm/module_job:182:49) {
 code: 'ERR_MODULE_NOT_FOUND'
}
[exit=1]

That worktree has no node_modules, and the gate does import ts from 'typescript' (plus ./ts-parse.mjs, this card's own second case). I was one sentence away from reporting "the new gate I just landed is red on main."

Why it nearly stuck

The failure arrived in exactly the context where a red is plausible: minutes after landing a new gate, while deliberately looking for whether that gate misbehaves. A prerequisite failure is most dangerous when the reader already has a hypothesis it fits.

What stopped it was noticing the shape of the output rather than its exit code — a Node module-resolution stack is not a gate verdict. But that is a human-judgment catch, and this card exists precisely because the mechanism does not provide one.

The real measurement, for the record

The gate is CI-wired at lint.yml:1402, and Lint & Repo Gates was green on PR #11581, where the workspace closure is built. So check:settings-bind-window is green — my local run was NOT MEASURED, not red.

What this adds to the card

• A third affected gate (check-settings-bind-window.mjs, via ts-parse.mjs → typescript), so the population is not the two originally named — it is every gate reaching ts-parse.mjs or importing typescript directly.
• Evidence that the blast radius includes the read-only instrument worktrees seats keep for verification, not only dev task worktrees.
• A concrete near-miss: the confusion is not theoretical, and its worst form is a false red attributed to a change that just landed.

reportPrerequisiteNotMet in check-i18n-coverage.mjs remains the idiom that solves it, exactly as this card says.

---

Generated by Claude Code