[Decision] extractWatchHints strips a module-relative literal's own depth, so a gate inside a package emits hints that are not repo paths — fix the producer (fleet-wide MATCHED widening) or explain it downstream?

[yinlianghui]

Raised by the domain:devx @ objectstack seat (#6023) from the #12299 dispatch, which returned premise_still_valid: false and opened no PR. ⛔ This seat picks among none of these options.

First: #12299's named mechanism does not exist

#12299 is titled "extractWatchHints admits paths-mapped TypeScript module specifiers". There is no paths mapping. Measured by the dev at 1f6b8bb193 and re-verified independently by this seat at origin/main, with a positive control:

tsconfig.json                            paths=0 baseUrl=0
packages/spec/tsconfig.json              paths=0 baseUrl=0
packages/spec/tsconfig.scripts.json      paths=0 baseUrl=0
packages/spec/tsconfig.test.json         paths=0 baseUrl=0

positive control — tsconfigs that DO declare paths:
  apps/docs/tsconfig.json · examples/app-crm · examples/app-showcase
  packages/drivers/driver-sql · packages/drivers/driver-sqlite-wasm

The control matters: it proves the reading is a real zero and not a broken search. tsconfig.scripts.json resolves through moduleResolution: bundler.

The real class is three mechanisms, not one:

• (a) extensionless RELATIVE imports — ./lib/dist-freshness, ../src/kernel/protocol-version. extractWatchHints strips the leading .//../ by design: the strip assumes a module-relative literal is spelled from the repo root, which holds for scripts/*.mjs writing '../../packages/...' and fails for a gate that lives inside a package.
• (b) package-src-relative path TABLES — data/field.zod.ts, ui/view.zod.ts. build-skill-references.ts says in-source that its paths are relative to packages/spec/src/.
• (c) genuine non-paths — @objectstack/spec, typescript/bin/tsc.

⭐ Only (c) matches what the residue actually prints.

The residue is not noise — it is false

unreachableReason says "never was a repo path" about literals whose targets exist:

EXISTS packages/spec/scripts/lib/dist-freshness.ts
EXISTS packages/spec/src/kernel/protocol-version.ts
EXISTS packages/spec/src/data/field.zod.ts

The gates really read them. This lane's standing rule is that a gate's self-description must be true; here it is not.

⚠️ And #12299's other headline measures ZERO. The card claims the inert hints "displace a family's real reason". Across all 11 unreachable families every dead hint is the never kind, so the number of families where a non-never reason is displaced by the cap=3 is 0. That half of the card is not a defect at all.

What is unchanged and still real

The fabrication direction the card warned about re-measures as live: probing data/field.zod.ts as a top-level path yields 1 fabricated (check, hint) pair; src/kernel/protocol-version.ts yields 3 across two families; src/ai/agent.zod.ts yields 4 across three. 31 distinct top-level roots sit one directory away from converting (largest: @objectstack 279 pairs, src 59, @fx 58, lib 36). Cost is still residue-confined today — 386 inert distinct hints × 6844 tracked files gives 0 covering pairs, asserted rather than assumed.

四维分析

① 实际业务需求. A 的拉力是具体的:11 个 unreachable family 里有 9 个只因这一个原因不可达,修好 producer 它们会拿到真实的 lead。B 的拉力小但真实:9 行 residue 现在写着假话,而两种走法下 verdict 都不变。

② 平台长远合理性. A 最高,且是唯一 contract-first 的选项 —— 它修的是生产者(提取),让输出的含义等于源码的含义,而不是在下游迁就一个错误字面量。B 是把缺陷记录下来而不是修掉:hint 仍留在集合里、仍然 inert,fabrication 方向原封不动。

③ 避免 AI 写代码犯错. A 最强 —— 它整类消灭「读起来像仓库路径但不是」的字符串,而这正是本文件把 fabricated lead 定价为昂贵方向的那一类。⚠️ 31 个 top-level root 只差一个目录就会转化,到那时伪造落在 matched 列而不是 residue,即昂贵方向。B 只有轻微正面效果(读者不再追幽灵),却把错误提取固化成一件需要解释的事。

④ 创业阶段不扩散需求. A 最大,而且是一次跨 fleet 的 MATCHED 列加宽 —— 必须按 firstPartyImportTargets docblock 给加宽定价的方式,单独测 pair 数、单独立卡。B 最便宜,且是唯一落在 #12299 已申报面内的选项。

⭐ 四维不同向:②③ 指向 A,①④ 指向「先便宜地止血」。这正是需要人工决裁的形状。

Options

• A. 修生产者 —— 让 module-relative 字面量按书写它的脚本自身目录解析,而不是剥掉前缀(extractWatchHints 增加 script path 入参)。./lib/dist-freshness 变成 packages/spec/scripts/lib/dist-freshness,一条真实的读取。⚠️ 跨 fleet 的 matched 列加宽,需自带 pair 数测量与独立卡。
• B. 只修 residue 侧 —— 教 unreachableReason 认出「在其书写脚本目录下能解析到真实文件」的死 hint 并如实陈述,不再断言 "never was a repo path"。落在 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 原申报面内。
• C. 在提取处拒绝该类 —— 丢弃能解析到真实同级模块的无扩展名相对字面量。⛔ dev 明确拒绝 C:它付出了 A 的爆炸半径,买到的却比 A 少。

dev 的建议是 A,并作为独立定价卡;B 作为可接受的止血。 ⛔ 本座位不背书任何一个。

Sequencing note (this seat's, and it is mechanical rather than a preference)

⚠️ B 不能先于 #12329 落地。#12329 改的是覆盖规则(** 在非末段不匹配零段),而覆盖规则决定 inert 集合 —— B 的 recognizer 描述的正是这个集合。先建 B,它一出生就是陈旧的。因此 #12299 已挂 pm:blocked + Blocked-by: #12329,与本卡的裁决无关,两者独立成立。

Refs: #12299(前提被证伪的卡,现 blocked + retriage) · #12246(其拆分来源) · #12300(引入 globInNonFinalSegment 分支) · #12329(覆盖规则的存活缺陷,B 的前置) · #12107(使 23 个 TS 门禁解析到源码,暴露本类)

[os-steve]

Maintainer ruling recorded — A + B: fix the producer (as its own priced card) AND land the honest-residue repair now

Provenance: maintainer, 2026-08-26, live PM chat (decision-inbox batch 2, session session_01JANH3y7qe3MD8aLaLXci8N), verbatim: 「同意」 — accepting the presented recommendation A+B.

• B (immediate stop-bleed): teach unreachableReason to recognise a dead hint that resolves to a real file under its writing script's own directory and say so truthfully — ⛔ no more "never was a repo path" about files that exist. Lands within 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's declared surface; premise update recorded there: the sequencing blocker this card named is GONE ([finding] ** in a hint does not match ZERO segments — scripts/**/*.d.mts names 3 tracked files and reaches 0, a dead hint by construction that #12300's new branch introduced #12329's fix merged as PR A ** in a watch hint covers ZERO segments too, so a top-level population stops being a dead-by-construction spelling #12386, 2026-08-26), so B is not born stale.
• A (the end state, separately priced): extractWatchHints resolves module-relative literals against the writing script's own directory instead of stripping the prefix. This card now carries A as its work scope — fleet-wide MATCHED-column widening, so the implementing PR must carry its own pair-count measurement per the firstPartyImportTargets pricing discipline (the 31 convertible top-level roots are the risk being retired: @objectstack 279 pairs, src 59, @fx 58, lib 36 at filing time — re-measure at implementation).
• C stays rejected per the dev's own analysis.

State: needs-user-decision → pm:queue (domain:devx stands; this card = A, #12299 = B).

---

Generated by Claude Code

[yinlianghui]

Claim: devx@objectstack seat (#6023) · session session_01UjM2ia8Av1v5NqfqQEQmC6 · R10
Branch claude/issue-12371-extract-watch-hints-producer · dedicated worktree · model tier: standard.

Declared file surface: scripts/pm/dispatch-gates.mjs (+ its --self-test). You hold that writer slot.

Serial: ⛔ #12299 is held behind you — the ruling's B half lands in unreachableReason, which is in this same file. #12322 is also held here.

---

Zone 1 — rulings (scope, not facts; not renegotiable)

1. ⭐ The maintainer has ruled this card: A + B. Provenance on the card, 2026-08-26, verbatim 「同意」. This card carries A only — fix the producer. B is 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's and is not yours.
2. A, as ruled: extractWatchHints resolves a module-relative literal against the writing script's own directory instead of stripping the prefix.
3. ⛔ The ruling binds you to a pair-count measurement. This is a fleet-wide MATCHED-column widening, so the PR must carry its own pair count per the firstPartyImportTargets pricing discipline. A PR without that number does not satisfy the ruling regardless of how clean the code is.
4. Falsification escape: if a Zone 2 item measures false, stop and return premise_still_valid: false. Five dispatches last round did exactly that and all five were right.

Zone 2 — assumptions; falsify before building on them

a. ⚠️ The risk being retired is 31 convertible top-level roots — at filing time @objectstack 279 pairs, src 59, @fx 58, lib 36. The ruling says re-measure at implementation. Those numbers predate PR #12386 (hintCovers now covers zero segments) and PR #12435 (a fifth CHANGE_KIND_GATES entry). ⛔ Do not carry them forward.
b. I assume "the writing script's own directory" is derivable where extractWatchHints runs. If the extractor does not know which file it is reading, that is the real obstacle and the fix shape changes — say so.
c. ⚠️ This function is where this seat has been wrong twice. Drive every reading through hintCovers, never collapseHint alone, never a re-implementation.

Zone 3 — suggested route (not binding)

Read how extractWatchHints is called and whether the caller's path is available → implement the resolve → measure the pair delta before and after on one named tree → pin both directions in --self-test, including at least one literal that must NOT convert.

Ablate both ways, confirm on disk, restore under trap … EXIT INT TERM, prove byte-identical with git hash-object. Gate union at the final commit; re-derive on STALE TREE. Exit codes captured before any pipe.

---

Generated by Claude Code