docs(devx): correct the stale collector claim on the js-comment-mask entry

[os-elon]

Fixes#12934

Comment-only correction to one entry's rationale in scripts/cross-package-test-inputs.mjs. One hunk, zero non-comment lines changed.

What was wrong

The @objectstack/cli entry's rationale for declaring the js-comment-mask.mjs pair claimed, in the present tense, that this gate "did NOT demand the declaration" and that a relative import specifier escaping the package "is not one of the spellings it knows". #10452 made both false, and the rationale was never re-read against it.

That claim is load-bearing in the direction that costs something: it tells the next author an import-only coupling is a hand-maintained courtesy the gate will not ask for, which is the belief this gate exists to make unnecessary (#7802).

What it says now

Past-tensed as history, then corrected, naming #10452 as the point the behaviour changed. Deliberately not deleted: before #10452 the gate genuinely did not demand it, and that history is what the neighbouring sites in this file carry.

The correction is verified against the gate, not against its neighbours

Two comments agreeing with each other is not evidence about behaviour, so the claim was reproduced on a scratch mutation, reverted after each leg. Both legs of the instrument are shown — the same gate returns zero and non-zero in this run:

Baseline (instrument can return zero) — node scripts/check-cross-package-test-inputs.mjs --self-test && node scripts/check-cross-package-test-inputs.mjs, exit 0:

All 117 self-test cases passed.
OK: 23 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.

Leg A — undeclared package. One escaping relative import specifier added to packages/objectql/src/action-activation.test.ts (a package with no declaration). Mutation proved on disk before the reading: injected-marker count 1, blob hash moved 1232bb3f to a936970f. Gate exit 1:

- @objectstack/objectql has test(s) that read outside the package but declares no input radius.
packages/objectql/src/action-activation.test.ts
Add an entry to CROSS_PACKAGE_TEST_INPUTS in scripts/cross-package-test-inputs.mjs

Leg B — declared package, path not covered. The @objectstack/runtime entry's scripts/js-comment-mask.mjs glob deleted, its .d.mts sibling left in place. Mutation proved on disk: glob-line count 10 to 9, blob hash moved e5d5da04 to 310e2c89. Gate exit 1:

- @objectstack/runtime names path(s) no declared glob covers, so a change to them would not
re-run its tests:
scripts/js-comment-mask.mjs (named in packages/runtime/src/error-envelope.conformance.test.ts)
Widen the package's globs to cover them.

Leg B is the one that settles the wording: the gate resolves the escaping relative specifier to a repo-relative path and attributes it to the importing test. It does not merely see the spelling.

Restore proved on both legs by observation, not by exit code: worktree clean and each file's hash back to its HEAD blob.

One refinement of the card's evidence, reported rather than written into the comment: the card says the gate "printed the exact inputs list each one needed". Neither failure shape printed an inputs list here. Leg A points at the turbo.json inputs as a second step ("then run this gate again for the turbo.json inputs it requires") and Leg B says "Widen the package's globs to cover them". The inputs list belongs to the turbo.json limb, which fires once the globs are declared. The comment therefore claims only what was measured — that the gate names the resolved path and the test that imports it.

Scope held

The four sites in this file that already describe the post-#10452 truth were read and left byte-identical (verified against origin/main). The collector and every gate behaviour are untouched — this card owed prose and nothing else.

Note for the reader locating these: the triage line numbers were from 2026-08-28 and three of the four have since moved by 30 lines. Located by content.

Verification

Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack. The first derivation printed STALE TREE and still exited 0; the branch was synced onto origin/main and re-derived clean. All runs below are at commit 9e5a9e873d, which is the branch tip.

All 12 derived families green, each exit captured before any pipe:

agent-test-spelling exit=0 entry-guard exit=0
bash32-floor exit=0 parse-guard exit=0
cli-command-ids exit=0 pnpm-filter-targets exit=0
cross-package-test-inputs exit=0 watch-hint-literal exit=0
nul-bytes exit=0 ci-filter-parity exit=0
shard-attestation exit=0 check-cross-package-test-inputs exit=0

check-ci-filter-parity and check-shard-attestation first answered exit 1 with PREREQUISITE NOT MET — the dependency yaml is not installed. That is not measured and is not a red gate; both are green above after pnpm install in the worktree.

Convention pair for a gate-script edit, both green: scripts/pm/bare-root-worklist.mjs --self-test (exit 0) and pnpm check:pm-dispatch-gates (exit 0, "dispatch-gates self-test: 872 cases pass").

check-test-completeness.mjs answers a standalone run with exit 1 and a usage line. That is an invocation error, not a finding — the known shape recorded on #13110. Not treated as a failure and not touched here.

No changeset, derived not asserted

check:published-files passes and no package files whitelist reaches repo-root scripts/; the edited file is named only by the root package.json script wiring. The change ships to no consumer, so no changeset is owed and skip-changeset applies.

No ablation owed

Stated rather than manufactured: the diff changes zero executable lines, so there is nothing whose removal could move a test verdict. The mutation discipline was still applied in full to the two verification legs above, where it does bite.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 33240915666 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (1/6) — 失败步骤: Run this shard's tests

  @objectstack/cli:test: FAIL test/serve-publishes-bound-port.e2e.test.ts > #13062 the non-zero half — nothing an ordinary boot publishes may move > publishes exactly the port it was asked for when th
  ↳ 失败原因: (这条 FAIL 之后 12 行内没有可识别的原因行 —— 点进 job 看)
  @objectstack/cli:test: FAIL test/serve-publishes-bound-port.e2e.test.ts > #13062 the non-zero half — nothing an ordinary boot publishes may move > follows the DEV AUTO-SHIFT onto the port it really ↳ 失败原因: @objectstack/cli:test: Error: ENOENT: no such file or directory, open '/tmp/os-bound-port-home-4VJyFP/runtime.env_local.json'
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

跨 PR 相同签名（24h，按失败测试文件聚合）：

• test/serve-publishes-bound-port.e2e.test.ts — 24h 内已弹出 7 个 PR（fix(ci): count speculative-stack inheritance as one hit in merge-queue triage #13107、fix(rest): the /data declared-4xx body carries human language in error, not the ADR-0111 CODE: prefix #13124、feat(metadata): the artifact door registers stack-declared capabilities (#12892 step 1) #13125、fix(tooling): declare kebab-case diagnostic codes a separate vocabulary, in one place #13130、docs(kernel): teach the dot-qualified view item name in metadata-service.mdx #13133、docs(devx): correct the stale collector claim on the js-comment-mask entry #13140、fix(scripts): close an ADR-0087 framed region at the same or a shallower heading, not at any heading #13142），分属 5 条投机栈 ⇒ 5 次独立命中。汇总 issue：Queue-flake anchor: test/serve-publishes-bound-port.e2e.test.ts #13175（新建）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 6 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)