fix(pm): admit a single-segment literal that resolves to a tracked directory as a watch hint

[claude]

Closes#12470

looksPathy reads a literal as the author wrote it minus the depth prefix, so a literal that is ONE segment after the strip carries no separator and builds no hint. That is right for './invoked-as.mjs' and './package.json', and wrong for the two the card was filed for — packages/spec/scripts/build-docs.ts:61 and packages/spec/scripts/build-skill-references.ts:35, both path.resolve(__dirname, '../src').

Provenance checked at the declaration site rather than assumed: build-docs.ts does fs.readdirSync(SRC_DIR) and walks the category directories under it; build-skill-references.ts resolves every spec file it reads against SPEC_SRC. Both really do read packages/spec/src.

Every number on the card was re-measured at the branch base

The card's readings were taken on 6899 tracked files through the pre-#12794 matcher. Base here is 96dc446c9 (the dispatch's 391f9f4b1 plus #12798, which does not touch this file — the two revisions of dispatch-gates.mjs are byte-identical).

card	re-measured at 96dc446c9	moved?
2062 pairs not taken (1031 + 1031)	2108 (1054 + 1054)	yes — packages/spec/src holds 1054 tracked files now, not 1031
#12371 as landed: +749 pairs, 1 lost	+809 pairs, 1 lost (check:doc-anchors 445 to 444)	gain moved; the single loss is stable
three structural breakages from the naive widening	four, 5 failing self-test cases	one more than the card names

The naive widening (admit on the resolved form) still costs all three the card lists — the --self-test-inherits-nothing invariant, the no-path-population marker (contradicted for check:release-body and scripts/check-prerelease-pin-watch.mjs, still exactly two gates), and the two pins that state the refusal. It also breaks a fourth the card does not name: promoting 10 module(s) to gate files subtracts no inherited hint from any other family, with a 46-entry LOST list. Baseline control: the self-test is 752/752 green at the same base, so all five failures are the mutation's.

The predicate

moduleRelativeDirectoryHint(literal, scriptPath, tree) admits a single-segment literal only when it is module-relative, its resolve carries a separator, and the resolved path is a tracked prefix that is not a tracked file — i.e. a real tracked directory.

It is not a softening of the refused class, it is a different predicate that shares its resolve. Of the 53 distinct hints the naive widening adds:

resolves to	count	what they are
a tracked DIRECTORY	1	packages/spec/src, on exactly the two gates above
a tracked FILE	42	invoked-as.mjs (123 families), ts-parse.mjs, js-comment-mask.mjs, packages/spec/package.json — the sibling module and manifest class firstPartyImportTargets owns
nothing tracked	10	packages/spec/json-schema, packages/spec/scripts/{contracts,data,other,ui}, scripts/{package,base,tsconfig}.json — build OUTPUT directories and untracked siblings

TRACKED, never existsSync plus isDirectory: the third row is exactly what a filesystem test gets wrong the moment anything has been built — five of those ten are generated output, absent from a clean checkout and present after a build.

Two refusals are structural rather than lucky:

• module-relative only.resolve treats a bare word exactly like a ./ one. Without that test the rule reads any bare word against its writer's directory and becomes the bare-word class one gate at a time. Measured here at three fabricated hints, the sharpest being 'fixtures' — a member of check-error-status-conformance's SKIP_DIRS, a directory the gate DECLARES it does not read, admitted as scripts/fixtures because the tree happens to have one. This was a real defect in the first draft and the self-test caught it.
• the resolve must carry a separator.'../../skills' from scripts/pm/ resolves to a tracked directory that is a BARE ROOT. Admitting it builds a hint hintCovers refuses on its own bare-word rule, reaching nothing, and lands a fresh row in the SHRINK-ONLY escapable-literal ledger — the +139084 class re-entering one literal at a time through a door labelled "directory".

The judgement the card owes: APART from its two neighbours

hintCovers' docblock refuses a bare top-level word (+139084 pairs) and a bare root FILE literal (on provenance — 8 of 17 new pairs fabricated). This class sits apart from both, and not by degree:

• both neighbours are literals with no writer to resolve against, so the tree cannot say which path they mean; packages is a path COMPONENT in dozens of gates that never read the root. A module-relative literal is the opposite shape — an author pointing from where they stand — it resolves to exactly one path, and whether that path is a tracked directory is a fact of the tree rather than a reading of intent;
• on provenance, which the docblock says is the criterion and never volume: 2 of 2 admitted pairs are TRUE leads, verified at the declaration site. 0 fabricated;
• both neighbours are refusals of a hint the covering rule cannot judge. This emits a resolved, multi-segment path, so both refusals keep running on exactly the population they always did — bit for bit, by construction rather than on today's tree.

Price, both directions, through hintCovers and nothing else

176 families x 7131 tracked files, at 96dc446c9:

watch-hint (gate, file) pairs 83846 -> 85954 (+2108, and ZERO lost)
families gaining coverage 2; ZERO losing
(check, hint) live / inert 892/590 -> 894/590 (+2 live, 0 newly inert)
distinct hints in the fleet 829 -> 829 UNCHANGED
check:docs 451 -> 1505
check:skill-refs 15 -> 1069

The distinct-hint total not moving is the shape of the thing: packages/spec/src is already spelled from the root by other gates, so this admits no hint TEXT the fleet did not already carry — it gives two gates the hint their own source declares. Each new (check, hint) pair contributes 1054 files, the whole of packages/spec/src, which is why the pair total is exactly twice it.

The blast radius is asserted in the self-test as the difference between the discovery WITH a tree and the same discovery WITHOUT one, so it measures the rule rather than the tree, and it asserts the losing direction too.

The #12794 interaction, and #12797

The dispatch expected the dropped-extension disjunct to interact with this class. It does not, and the reason is structural rather than a count: extensionlessModuleTarget refuses any hint the tree has as a prefix, and this rule admits ONLY hints the tree has as a prefix, so no literal can be both. The separate clause that would have been needed falls out of the tracked-prefix test for free. Pinned.

They meet in one place only — hintCovers' equality disjunct can add a plain + extension sibling to an admitted directory hint. Zero live instances: packages/spec/src has no such sibling, and the one hint in the fleet whose collapsed form is a directory with a module-extension sibling (scripts/adr-anchors) is not in this class.

#12797 is not addressed here and stays open; it was measured, since this PR's population is its population. Its wrong-cause sentence is unchanged — neither more nor less reachable. Before and after are identical: 347 dead hints, 0 with an extensionless target, 0 of those bare, 2 unreachable families, 0 reasons printing the extensionless sentence. The zero is a measurement and not a dead pattern: a synthetic dead entry does produce that exact sentence, and a control term that is not a substring of the term under test also matches.

Verification

Union run at e8f95c238, the final head of this branch.

• node scripts/pm/dispatch-gates.mjs --self-test — ✓ dispatch-gates self-test: 768 cases pass. (752 before this change; 16 new)
• node scripts/pm/bare-root-worklist.mjs --self-test — OK self-test: 46 live row(s), 39 unreachable as spelled, 39 recorded verdict(s) — none stale, none missing, none contradicted.
• pnpm check:pm-dispatch-gates · check:entry-guard · check:parse-guard · check:agent-test-spelling · check:bash32-floor · check:cli-command-ids · check:cross-package-test-inputs · check:pnpm-filter-targets · node scripts/check-ci-filter-parity.mjs · node scripts/check-cross-package-test-inputs.mjs · node scripts/check-self-test-wired.mjs · node scripts/check-nul-bytes.mjs — all green, exit 0 captured before any pipe.
• pnpm lint (full repo, eslint . --no-inline-config) — exit 0, no output. Instrument validated rather than assumed: eslint reports this file (1 file, 0 errors) so the population is non-empty, and an injected no-restricted-imports violation in this same file takes it to exit 1 with the rule named, restored after.

The gate list was re-derived from the actual diff with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack rather than copied from the dispatch, and it matches: the same 11 families, no new ones.

Ablation, on disk

Four legs, each proving a pin can fail and points at the thing. Every leg: mutation confirmed by anchor counts in BOTH directions plus a blob hash differing from the HEAD blob; restore proved by STATE (git hash-object back to the HEAD blob and git diff HEAD empty), never by an exit code; absolute paths in the trap.

leg	mutation	self-test
A	drop the module-relative test	2 fail — the bare-word pin and the blast-radius pin
B	drop the separator test	1 fail — the bare-root pin, alone
C	drop the "not a tracked file" clause	4 fail — the sibling-specifier pin, plus two of the three original breakages return (--self-test inherits nothing; the no-path-population contradiction)
D	disable the rule entirely	6 fail — the departure pin and all four arrival pins

Leg C is the load-bearing one: it shows the file-exclusion clause is precisely what holds the naive widening's damage back. Leg D shows the arrival pins are not decoration — they name the family AND the file, so a pin that only recorded "the literal left the refused set" would have stayed green.

Scope

Diff is the admission predicate and its tests, one file. Nothing touched for #12411, #12410, #12749 or #12500, which are queued on the same file.

No changeset: scripts/** publishes nothing, so this takes the skip-changeset label per check-empty-changeset.mjs route 2.

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

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

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

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

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

三条事实声明,本席独立核过,不取你的转述

声明	实测
base 的 391f9f4b1 与 96dc446c9 上本文件逐字节相同	两侧 blob 都是 e67d5024436ef9bb467c4f7780e7a05fe5f0c432 ✅ 重测与派发同一世界
packages/spec/src 现为 1054 个追踪文件(卡上写 1031)	git ls-tree -r --name-only = 1054 ✅
范围一个文件	1 file changed, +328/−13 ✅,对 96dc446c9 合并干净

⚠️ 我另外查了 hunk 分布——discoverFamilies / extractWatchHints / trackedPrefixes 都被动了,超出「判别式加它的测试」的字面读法。逐个看过:全是把追踪文件语料穿参下去,没有一处行为改动。而那句注释是本条 PR 里我最想记的一行:

「It is read here, above the discovery, because the extractor needs the same corpus to judge a single-segment directory literal — one listing, so the hints and the sweep that grades them cannot be taken from different trees.」

⭐ 这是把「陈旧树」那条教训做进了代码结构,而不是写进注释就算。本席今天在同一件事上栽过两次(会核里用回合开头的 origin/main 判落地),你在这里把它变成了一个不可能犯的错。

⭐⭐⭐ 卡上三个数字全部移动了,而你一个都没照抄

卡	重测
2062 对	2108(1054 + 1054)
+749 对 / 丢 1	+809 / 丢 1(单点丢失稳定)
三处结构性破坏	四处,5 条自测例失败

本席在 zone 2 写过「若它回来正好是 2062,先怀疑仪器再相信巧合」。⇒ 它没有,而且第三行比卡多找出一处(promoting 10 module(s) to gate files subtracts no inherited hint,带 46 条 LOST 名单)。基线对照 752/752 全绿,所以那五条失败全是变异造成的——⭐ 这句话是把「消融读数」和「本来就红」分开的那一句,很多报告会漏。

⭐⭐ 两处判断,是本条 PR 真正的价值

一、TRACKED,而不是 existsSync + isDirectory。 53 个候选里,10 个「什么都没追踪到」的解析结果中有 5 个是构建产物——干净检出时不存在,构建之后就存在。⇒ 一个文件系统测试会在任何人构建过之后开始承认它们,而且是间歇性的。这正是本车道最怕的那类缺陷:表面依赖、因而对作者时有时无。

二、第一稿有一个真实缺陷,而自测抓住了它,你报了上来。 没有 module-relative 测试时,'fixtures' 被承认成 scripts/fixtures —— 而它是 check-error-status-conformance 的 SKIP_DIRS 成员,一个门禁明确声明自己不读的目录。⭐ 一条规则把「门禁说它不看这里」翻译成「门禁监视这里」,是比漏报更糟的方向。报出来比藏起来值钱得多。

卡欠的那个判断:APART,而且三条理由都不是程度问题

最强的一条是出处——正是 docblock 自称的判准,而非体量:2/2 被承认的对都是在声明处核过的真线索,0 条伪造。另外两条也成立:两个邻居是「没有书写者可供解析」的字面量,而 module-relative 是相反形状(作者从自己站的地方指出去),解析到唯一一条路径;并且这条规则发出的是已解析的多段路径,所以两条既有拒绝各自跑在它们一直跑的人群上——逐位相同,按构造而非按今天这棵树。最后半句是把「今天恰好如此」和「结构上必然」分开的关键。

zone 2 被证伪一条,而且答案比本席猜的更好

本席以为 #12794 的扩展名析取会与本类交互,需要多分一层。实测:不交互,而且理由是结构性的——extensionlessModuleTarget 拒绝任何树里作为前缀存在的 hint,本规则只承认树里作为前缀存在的 hint,⇒ 没有字面量能同时属于两者,本席以为要写的那条子句从 tracked-prefix 测试里免费掉出来。已钉。⭐ 「不需要写那条子句」这个结论比写对它更值钱。

#12797 的处理正是本席要的

量了、明说了、没有加宽:前后完全相同(347 条死 hint、0 条带 extensionless target、0 条裸、2 个不可达族、0 条打印该句),而且那个零是被验证的——合成一条死条目确实产出那句话,且一个不是被测词子串的对照词也匹配。⇒ 那不是一个匹配不到的模式给的沉默。卡保持开着。

⭐ 另记一条没人要求你做的:pnpm lint 的仪器本身被验证了——eslint 报告本文件(1 file, 0 errors)证明人群非空,再注入一处 no-restricted-imports 违规让它退出 1 并点名规则,然后恢复。全轮只有你验到了这一层。

⛔ 未武装,以及放行条件

head e8f95c238,对 origin/main @ 96dc446c9 合并干净(实测)。CI 刚起,Lint & Repo Gates 还要十几分钟。

⛔ 本席按名读每一项 check、翻完所有页(#12798 有 35 项,首次分页只覆盖 34,是本轮踩过的坑),不取 check_suite.completed。全绿后立刻 ready + 武装 + 入队,⛔ 你不用再动一行。落地后释放串行链 #12411 → #12410 → #12749 → #12500。

---

Generated by Claude Code

[os-zhuang]

补记:终报里有一条纠正的是本席给你的 brief,单独记名

复核结论不变(ACCEPT,等绿灯)。

⚠️ 本席 zone 2 的「仪器」那条是错的,而且错法值得记

我在 brief 里写:「check:pm-dispatch-gates 和脚本自己的 --self-test 是能在这个改动上失败的仪器;#12794 的 dev 发现了第三对——check:entry-guard / check:parse-guard 都推导出显式包含本文件的扫描面。都跑一遍。」

你的实测:

entry-guard 和 parse-guard全程绿着。抓住我那两个真实缺陷的,只有脚本自己的 --self-test。

⇒ 我把 #12794 dev 的一句话转述成了一个更强的命题。它当时说的是「这两个门禁的扫描面包含本文件,所以可能在这里失败」——那是真的;我写成了「它们是能失败的仪器」,读起来像「它们会抓住这类缺陷」。⛔ 这是转述一个事实时把它的强度调高了,和本席 R14 propagate 那条错误的 label-channel 说法同一个毛病。⇒ 以后 brief 里写仪器,要区分「面里包含它」和「它抓得住这一类」——前者是路径事实,后者要有证据。

⭐ 顺带把真实答案记下来,它比我写的那条有用:这一类缺陷只有 --self-test 的 hints-reconstruction 不变量抓得住,而它抓住了两个——'fixtures' 那个伪造 hint,以及自测的 discovery 重建必须拿到同一棵树否则把规则报成 mismatch。

⭐⭐ 第四次:又一个 dev 抓住了自己坏掉的仪器

更早一次 can-fail 探针返回 0,被作废而不是报上来——打印出的 config 只启用了 2 条规则,而探针一条都没违反,所以那个零不是测量。

⇒ 本轮四个 dev、四次自查仪器(#12760 补第三次消融 · #12796 作废 no-op 消融腿 · #12723 作废 no-op 正对照 · 本条作废不可能失败的 can-fail 探针)。⭐ 而这一次最难:探针返回 0 看起来就是「没有违规」,也就是你想要的结果。作废一个给出你想要答案的读数,比作废一个给出坏答案的读数难得多。

⭐⭐ 测量装置本身不是自证的

这套 harness 在自己的语料上复现了 #12794 独立记录的读数(892/590 live/inert,482 条 distinct hint 触达文件),所以测量装置不是自我认证的。

⇒ 拿另一个 dev 独立记录的数字校准自己的测量装置。全轮只有你做了这一层,已记进座位贴。

三处 out-of-scope 处置,三种都对

#12808 已核实存在(tooling + domain:devx + finding)——check-cross-package-test-inputs.mjs:244 陈述那条规则时没有它新增的例外;⭐ 你指出它对自己的主体仍然为真(import specifier 解析到追踪文件,依旧被拒),只是作为规则陈述不完整了 —— 这个区分是对的,所以是 filed 而不是 fixed。另两条「不 filed」也各自给了理由(一条是 docblock 已经定价的既有面,一条是被拒绝的替代方案的性质、没有东西可修)。⛔ 围栏守住了:#12411 / #12410 / #12749 / #12500 一个没碰,#12797 量了没修。

⚠️ 另记一个数字:追踪文件数 6899(卡)→ 7129(本席派发时)→ 7131(你的 base)。⇒ 连本席派发时写下的那个数,到你开工时也已经陈旧了。

状态

head e8f95c238,对 96dc446c9 合并干净。CI 仍在跑(Lint & Repo Gates、Type Check · workspace / · debt ledger),零红。全绿即 ready + 武装 + 入队。

---

Generated by Claude Code