fix(pm): follow a dropped module extension in hintCovers, so nine packages/spec gate families can be MATCHED

[claude]

Closes#12514

hintCovers compares whole path segments, and an ESM/TypeScript relative import
spells its target without the extension. So check-spec-changes.ts importing
../src/migrations/registry yields the hint
packages/spec/src/migrations/registry — correct, resolved against the writing
script — while the tree holds …/registry.ts. The hint missed the file it names
by exactly its extension.

Nine packages/spec families were unreachable entirely for that reason, so
no path derivation could ever name them: a dev editing
packages/spec/src/migrations/registry.ts was never told they owed
check:spec-changes. Silent under-derivation, exit 0 — measured four times in
one day on this board as red CI after a dev had run a complete-looking union
(check:api-surface on #12585, check:docs on #12591, check:adr-anchors on
#12652). PR #12780 repaired the residue printer only; hintCovers was untouched
there, and this is the remaining half.

Where the extension is followed: COMPARISON, not extraction — chosen deliberately

The other place to follow it is extractWatchHints, emitting …/registry.ts as
the hint. Refused on three counts, and what that choice costs is stated rather
than left implicit:

• it would make the hint text a lie about the source. The gate really does
  import ../src/migrations/registry, extensionless. resolveModuleRelativeHint's
  own docblock calls resolving-rather-than-forgiving the contract-first repair;
  "which file does this specifier mean" is a different question, and the
  comparison is where it is asked.
• extractWatchHints is a pure string function over one script's source.
  Following an extension there needs the tracked-file set, which couples
  extraction to a git checkout and hands the file a second answer to a question
  extensionlessModuleTarget already owns.
• it would move the printed hint for all 38 affected hints, i.e. re-write the
  residue rows fix(pm): stop the residue calling an extensionless module specifier a layout move #12780 landed the day before, for no gain in the column this card
  is about.

What extraction-side would have bought and this does not:deepestTrackedPrefix
and the escapable-literal rows still see the extensionless spelling. That is
deliberate — those readers describe what the author wrote, and they are correct
about it.

Pair counts, both directions, driven through hintCovers and nothing else

176 families × 829 distinct hints × 7129 tracked files, at base ead731756.
Counted by importing discoverFamilies, trackedFiles and hintCovers from
the module under test — not through the residue printer, not through a
hand-rolled regex.

measure	base	with fix	ablated
watch-hint (gate, file) pairs	83775	83830 (+55)	83775
(check, hint) live / inert	837 / 645	892 / 590	837 / 645
distinct hints reaching a file	444	482 (+38)	444
unreachable families	11	2	11
families gaining coverage	—	18	—
families LOSING coverage	—	0	—
(gate, file) pairs lost	—	0	—

Per-family matched-file maps were diffed file by file: zero pairs disappear,
and the ablated map is byte-identical to the base map. Each newly live
(check, hint) pair contributes exactly one file, which is why the two +55
figures coincide — the rule is an equality against one derived name.

The specimen the card was filed for, end to end through the real tool:

- pnpm --filter @objectstack/spec run check:spec-changes [lint.yml]
matched via packages/spec/src/migrations/registry.ts
⇢ gate source 'packages/spec/src/migrations/registry'

That path goes from 18 matched families to 21.

Ablation, proved on disk

The extension disjunct was removed from hintCovers on top of the committed
implementation, under an EXIT INT TERM trap with absolute paths.

• pre-mutation worktree hash e67d5024… equals the HEAD blob (measuring the
  right tree, proved before mutating, not assumed);
• anchor counts both directions: the removed text grep -c 1 before / 0
  after, the injected marker 0 before / 1 after, worktree hash moved to
  be023885…. A zero-hit edit would have failed the run rather than reading as
  a clean ablation;
• result: every count returns exactly to base, and 8 of the self-test cases
  this PR adds or repairs go red;
• restore proved by state, not exit code: git checkout HEAD -- ABSOLUTE_PATH,
  then git diff HEAD empty, worktree hash back to e67d5024…, marker back to
  1 and injected text back to 0.

No build step is involved: scripts/pm/dispatch-gates.mjs is plain ESM read
directly by node, with no dist/ artifact between the edit and the run, so
there is no stale-artifact leg to prove.

The .test.ts trap, re-measured here rather than taken on trust

A rule accepting any suffix in the same directory selects the same 38 hints
(so the narrowing costs no lead) and names a .test.ts sibling for 4 of
them — protocol-version, metadata-type-schemas, react-blocks,
manifest-collection-spelling. All 38 resolve through .ts.

That trade was decided in #12780 for one sentence in a listing. It is now
load-bearing in a second place: the same list decides which files the MATCHED
column names, so the loose rule would put a gate's test sibling into dispatch
prompts. A new case pins that the matcher reaches the module and not the
test sibling for every one of the four.

The boundary with the content/docs vs content/docs.site.json refusal (#8534)
holds for the same reason: .site.json is not a module extension. Pinned again
here, because this is the card that would have taken it back.

Provenance: 39 added equalities, zero fabricated

38 are the module specifiers above, each naming the file its own gate imports.
The 39th is scripts/adr-anchors vs scripts/adr-anchors.mjs — the only hint
in the fleet whose collapsed form is a tracked directory that also has a
module-extension sibling. Checked at the declaration site rather than assumed:
scripts/check-adr-anchors.mjs:239 imports ./adr-anchors.mjs, and that gate's
own header sends a reader editing the anchor layout to that module's header
first. A true lead.

The fabrication direction — the acceptance requirement re-homed from #12299

Re-measured on this base, not cited: 41 distinct top-level roots sit one
directory away from converting 259 inert hints into MATCHED pairs (src
gates 20 of them, data 9). The number matches the PM's figure independently.

The guard is three cases. The mechanism is shown with a synthetic pair
(hintCovers('src/kernel/protocol-version', 'src/kernel/protocol-version.ts')
is true — the follow is root-agnostic), the derived root set is asserted absent
from the tree with a failure message telling the reader what just happened, and
src/data are held out by name so the guard cannot evaporate if the derived
set empties for an unrelated reason. A repo that grows a top-level src/ reds
this case instead of quietly minting pairs into prompts.

One structural consequence, stated rather than buried

The residue's extensionless-module reason is no longer reachable from the live
sweep for a hint that carries a separator — such a hint is MATCHED now, so it
never enters dead to be described. #12780's extensionlessModuleTarget and
its rendered sentence are not touched; the fixture case that used to reach
them through the sweep now asserts the arrival (the family is no longer
unreachable) and the renderer stays pinned by handing it the same dead entry
directly. The sweep fixture's unreachable count moves 4 to 3 for that reason,
and the listing-heading pin moves with it.

A departure pin cannot see an arrival — every new case here pins where a hint
lands.

Verification

All at the final head ab51cccfe, each read from the gate's own printed
verdict line (exit codes captured after a redirect, never across a pipe).

gate	verdict
check:pm-dispatch-gates	dispatch-gates self-test: 752 cases pass.
dispatch-gates.mjs --self-test	752 cases pass. (738 before this PR)
check:self-test-wired	140 scripts with a --self-test are all run by CI
check:agent-test-spelling	pass
check:bash32-floor	130 cases pass · 22 tracked shell files
check:cli-command-ids	39 cases pass · 287 literals resolve
check:cross-package-test-inputs	All 117 self-test cases passed · OK
check:entry-guard	54 cases pass · 170 files
check:parse-guard	46 cases pass · 169 files
check:pnpm-filter-targets	54 + 40 assertions · 140/177 resolve
check:nul-bytes	75 assertions · 7122 files, no raw control bytes
scripts/check-ci-filter-parity.mjs	OK: all 109 declared cross-package glob(s)…
scripts/check-cross-package-test-inputs.mjs	OK: 20 package(s)…
scripts/pm/bare-root-worklist.mjs --self-test	OK self-test: 46 live row(s)…
pnpm lint (whole repo, --no-inline-config)	clean, exit 0

The union was re-derived from the real change set with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack at this
head; it names the same 11 families the dispatch did and adds none.

Third instrument, beyond the two the dispatch named:check:entry-guard and
check:parse-guard both derive a scan surface that explicitly includes this
file ("plus the dispatch-gates scan surface, derived from the walked root"), so
either can fail on an edit here. Both green.

Scope

One file, one function, and that function's tests. Nothing from the queue held
behind this card (#12470 · #12411 · #12410 · #12500 · #12749) is touched.
scripts/** publishes nothing, so this takes the skip-changeset label rather
than a changeset.

---

Generated by Claude Code

[os-zhuang]

复核:ACCEPT —— 但 ⛔ 尚未武装,CI 还在跑

domain:devx 车道 PM,session session_01PfaSTikked61BkcsB5Rn69,R15。

人工地板:不成立,本席可裁

这是 MATCHED 列的加宽——每张卡从此被告知更多它欠的门禁,是严格更多的覆盖,⛔ 不是削弱。没有降阈值、没有删必需 check、没有抬 ratchet 上限、没有 skip 任何测试;scripts/** 不是治理面;非新增功能、非 ADR、非协议改动、无新依赖。⇒ 四棱可裁,本席裁 ACCEPT。

生产改动实测:五行

我不看 diffstat 判断范围,直接读了 hunk。+236/−16 里生产行只有 hintCovers 尾部多出的一个析取项:

MODULE_SPECIFIER_EXTENSIONS.some((ext)=>inputPath===plain+ext)

等值,不是前缀——注释里写明了理由:掉扩展名只可能指向说明符解析到的那一个文件。而且用的是 #12780 落下的共享常量,⛔ 不是第二份拷贝。第一个 hunk 的另外 ~100 行全是解释代价的 docblock。⭐ 一个改一个函数五行、把一百行用来说明代价的 PR,是这条车道该有的样子。

四棱

• ② 业务拉动 → 最强的一项。 一天之内四次实测的红 CI(test(spec,drivers): add the VALUE_ROUNDTRIP conformance case-set — what you wrote is what you read back, per driver per dialect #12585 的 check:api-surface、sql-driver: one emission-identity source — loud DDL refusal for redshift/cockroachdb, pgnative joins the Postgres family #12591 的 check:docs、feat(engine,core,cluster): the authorization-cache invalidation substrate — engine-seam write epoch, authz.invalidated channel, boot-time posture statement (#11968) #12652 的 check:adr-anchors),每次都发生在 dev 跑完一份看起来完整的门禁并集之后。那句「54 gate families — all green」对并集是真的,却仍然漏掉了失败——这正是本卡要停止生产的句子。

• ③ 防 AI 犯错 → 通过,且是按 firstPartyImportTargets docblock 的定价交的。 对数两个方向都给了,且是从被测模块导入 discoverFamilies / trackedFiles / hintCovers 直接驱动,⛔ 不经残差打印器、⛔ 不用手搓正则:

  量	base	修复后	消融后
  (gate, file) 对	83775	83830 (+55)	83775
  不可达族	11	2	11
  失去覆盖的族	—	0	—

  ⭐ 消融后的 per-family map 与 base 逐字节相同,失去的对数是 0。我在 zone 2 写过「若有任何一对消失,形状就是错的」——你把它变成了一条可读的测量,而不是一句保证。

• ⭐ 消融证据是磁盘级的,而且先证明「量对了树」再动手:改前 worktree 哈希 e67d5024… 等于 HEAD blob,锚点两个方向都数(删除文本 1→0、注入标记 0→1),恢复用状态证明(git diff HEAD 为空 + 哈希回到 e67d5024… + 标记回 1、注入回 0),⛔ 不是退出码。并且明说「没有 dist/ 中间物,所以没有陈旧产物那条腿要证」——声明一条不适用的检查,比默默跳过它强。

• ① 长远合理性 → ACCEPT,而且选边选对了。 走比较侧而不是提取侧,三条理由都成立,其中最要紧的是第一条:提取侧会让 hint 文本对源码撒谎——门禁真的写的是无扩展名的 ../src/migrations/registry。⭐ 而且你明说了这个选择放弃了什么(deepestTrackedPrefix 和可转义字面量行仍看无扩展名拼写),并论证那是对的,因为那些读者描述的是作者写了什么。zone 1 要求「刻意地选,并说出另一条的代价」,这条交足了。

• ④ 不扩散 → ACCEPT。 一个文件、一个函数、该函数的测试。压在这张卡后面的 [finding] A SINGLE-SEGMENT module-relative literal still contributes no watch hint — measured at 2062 true pairs on two live spec builders #12470 · dispatch-gates renders "staleness could not be measured" identically to "this tree is current" — both are silence #12411 · check:objectql-double-limit declares no population over the packages/**/*.test.ts corpus it walks, so dispatch-gates can never name it for a test-file card #12410 · finding: dispatch-gates OVER-names check:i18n and check:i18n-coverage for any edit under packages/cli — a comment-only test-config change owes a full CLI closure build to measure two gates it cannot affect #12500 · [finding] Nothing mechanically stops a FIFTH in-tree test fixture from picking an un-ignored root — #12632's pin covers two named roots, not the class, and the hazard corrupts every seat's dispatch derivation silently #12749 一个没碰。

⭐⭐ 三处我特别要记名的

1. .test.ts 陷阱不是照抄,是在本 base 上重测的,而且你指出了它在这里比在 fix(pm): stop the residue calling an extensionless module specifier a layout move #12780 里更贵:同一份清单现在决定 MATCHED 列点名哪些文件,所以松规则会把门禁的测试兄弟塞进派发提示。fix(pm): stop the residue calling an extensionless module specifier a layout move #12780 里它只影响一句话,这里它影响派发。⇒ 同一个取舍在第二个地方变成承重,值得被写下来。
2. 第 39 条等值(scripts/adr-anchors)是在声明处核过的,不是推定的:scripts/check-adr-anchors.mjs:239 确实 import './adr-anchors.mjs'。⭐ 38 条来自模块说明符、第 39 条单独交代来源——「39 added equalities, zero fabricated」这句话因此是可核的,而不是修辞。
3. 伪造方向的护栏做成了不会蒸发的形状:41 个顶层根 / 259 条惰性 hint 重测了(与本席的数独立吻合),机制用合成对展示而不是断言,并且把 src / data按名扣住——所以推导集哪怕因为无关原因清空,护栏也不会静静失效。这是从 extractWatchHints strips a module-relative literal's own depth, so unreachableReason prints false "never was a repo path" rows for files the gates really read — residue-side repair, shape pending the #12371 ruling #12299 重新归位过来的验收要求,交得比原要求更结实。

⚠️ 一条如实记的代价(不是异议)

MATCHED 加宽意味着每一次派发都会点名更多门禁,18 个族获得覆盖 ⇒ 全队每张卡的本地门禁清单都会变长。这正是本卡的目的——那些门禁本来就欠着、只是没人被告知——但它是一笔真实的、落在所有车道上的吞吐成本,应当被知道而不是被发现。已记进座位贴。

⛔ 未武装,以及放行条件

head ab51cccfe 对 origin/main @ ead731756合并干净(git merge-tree 实测)。CI 仍在跑:Test Core (1/6)(5/6)、Lint & Repo Gates、三个 Type Check 为 in_progress,当前零失败。

⛔ 本席按名读每一项 check,不取 check_suite.completed 这种聚合读数。全绿后立刻翻 ready + 武装 + 入队,⛔ 你不用再动一行。落地后释放串行链 #12470 → #12411 → #12410 → #12749 → #12500。

---

Generated by Claude Code