finding: check:duration-unit-keys reads .describe() but not JSDoc — a duration key documenting its unit only in JSDoc never enters the population, and one card already recorded a wrong reason because of it

[claude]

Observation filed from stack card 4/6 of #14478 (PR #15938). Not fixed there — it is outside that card's population and touches the gate's own reading surface, which card 6/6 owns.

The shape

check:duration-unit-keys reads a key's unit prose from its .describe() (and from .meta({ description })), and its own self-test pins that behaviour: "a describe declared through .meta({ description }) is READ — no exemption by blindness". It does not read the JSDoc block immediately above the key.

So a duration-shaped z.number() whose name carries no unit, and whose unit is stated only in its JSDoc, is invisible to the population. It is not exempt by either declared structural exemption (EpochMs, externalVocabulary) — it simply never enters the count. The rule's own premise is that the unit must not live in prose alone; here it lives in a less discoverable prose channel than the one the rule already rejects.

Three verified instances, read rather than pattern-matched

Measured on claude/issue-15679-system-duration-unit-in-key-name @ 45a35896c:

site	JSDoc says	.describe() says
packages/spec/src/kernel/plugin-security-advanced.zod.ts:294 timeout	"Execution timeout in milliseconds"	'Maximum execution time' — no unit
packages/spec/src/system/metrics.zod.ts:552 window	"Window size in seconds"	'Window size' — no unit
packages/spec/src/system/metrics.zod.ts:626 interval	"Export interval in seconds"	no .describe() at all

Why the first one is the sharp end

RuntimeConfig.resourceLimits.timeout is not a hypothetical. Card 3/6 (#15678) reasoned about it explicitly and pinned it as out of population, recording in its changeset that the key "names no unit anywhere in its prose". That reading is measurably imprecise — the JSDoc two lines above it names milliseconds. The conclusion (leave it alone, it is outside the gate's population) is still correct as a statement about the gate, but the reason recorded for a future author is wrong, and a pin test now holds it in place.

That is the cost of the blindness: it does not just miss keys, it produces confident wrong prose about why they were missed.

Not a duplicate of #15642

#15642 reports that the gate scans packages/spec/src/** only, so the same offender shape survives in other workspace packages. That is about the scanned subtree. This is about which prose channel is read inside a file the gate already scans. Both could be true and fixed independently.

Sizing — deliberately not asserted

A crude heuristic scan of packages/spec/src/**/*.zod.ts (duration-shaped numeric key, no unit token in the name, no unit in its describe, unit present in the JSDoc above) returns 60 candidate sites. That number is not a population count: reading a sample shows it includes clear false positives — byte and percentage measurements, counts, and keys that already carry a unit token. The three rows above are the ones actually read and confirmed. The real count needs the gate's own predicate applied to the JSDoc channel, which is the fix, not the triage.

Options, for whoever picks this up

1. Read the JSDoc as a prose channel too. Most faithful to the rule's premise; expands the population, so it wants its own card and its own before/after count.
2. Refuse a duration-shaped key whose JSDoc names a unit its describe does not. Narrower: it treats the divergence itself as the defect, and pushes authors to move the unit into the describe, where the gate and the reference pages both see it.
3. Leave it and correct the prose. Fix card 3/6's pin note so the recorded reason is true, and accept the blindness as declared behaviour.

I have no recommendation between these — the choice is a rule change and belongs with the maintainer ruling that shaped #14478.

---

Generated by Claude Code

[claude]

The changeset claim this card surfaced has been corrected on card 3/6's branch — claude/issue-15678-kernel-duration-unit-in-key-name, commit adad660a1, PR #15906. This card stays open: only the wrong prose was fixed, not the blindness.

What this issue reported under "Why the first one is the sharp end" was accurate. .changeset/kernel-duration-keys-unit-in-key-name.md said RuntimeConfig.resourceLimits.timeout "names no unit anywhere in its prose"; the JSDoc at packages/spec/src/kernel/plugin-security-advanced.zod.ts:291-293 names milliseconds, and only the .describe('Maximum execution time') names none. The recorded reason now says that instead, and points here for the gap:

RuntimeConfig.resourceLimits.timeout names its unit only in the JSDoc above the key ("Execution timeout in milliseconds"), a channel check:duration-unit-keys does not read: it reads .describe() and .meta({ description }), and this key's describe ("Maximum execution time") names none. The gate therefore lists it among the duration-shaped keys but deliberately does not judge it — neither an offender nor an exemption — so it is outside this rename; that JSDoc-channel gap is filed as #15939. A pin test asserts the key still parses bare, so a later sweep cannot read the four security renames as "every timeout on that file".

That is option 3 of the three listed here, applied to the prose only. Options 1 and 2 — the actual rule change — are untouched and still need the maintainer ruling this card asks for.

Corrected in four places on that branch, all carrying the identical clause: the changeset, the ADR-0087 semantic entry reason (which build-upgrade-guide.ts publishes as "Why not automatic"), its generated mirror in registry.ts, and the comment above the pin test. The pin test's title, body and assertions are byte-identical, and the key is still bare.

One refinement to this card's own framing, measured while doing it. This card says the JSDoc-only key "never enters the population" and calls the old reading's conclusion ("outside the gate's population") still correct. It is not, in the gate's own vocabulary: --list prints the key as one of the 215 census rows —

src/kernel/plugin-security-advanced.zod.ts:294  timeout  [name: -] [prose: -]  "Maximum execution time"

— and check-duration-unit-keys.ts --self-test pins that reading: "listed, not judged: duration-shaped name with no unit anywhere (the #14519 shape) is a census row". The key is inside the population and outside the verdict. The blindness this card reports is real and unchanged; what it costs is a judgment, not a census row. The corrected prose says only that, so it does not carry the imprecision forward.

Still uncorrected, and deliberately left for whoever takes this card: packages/spec/src/migrations/entries/retired-keys/18.kernel__SandboxConfig__process.timeout.ts:7-9 repeats "outside the gate's population" about the same key. Its other clause — the key's "describe names no unit at all" — is true, so it does not carry the false statement, only the imprecise one.

Verified at adad660a1: check:duration-unit-keys unmoved at 22 offender(s) among 215 duration-shaped numeric key(s) in 805 source file(s), kernel/ at 0; the pin test passes; @objectstack/spec tests 12784 passed.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:spec / tooling + finding / needs-user-decision / priority:p3

⛔ needs-user-decision 不与 pm:* 并存（先例 #15854 / #15617 / #15542）。

落点核实（origin/main，本轮实读）

门在 packages/spec，不在 scripts/：

packages/spec/package.json:290
  "check:duration-unit-keys": "tsx scripts/check-duration-unit-keys.ts --self-test && tsx scripts/check-duration-unit-keys.ts",

⇒ domain:spec（packages/spec 整包）。⛔ 不归 domain:devx：它不是仓根 scripts/ 下的门，是 spec 包自己的门。

卡片的三个实例，本席逐个取到，逐字成立：

站点	JSDoc	.describe()
packages/spec/src/kernel/plugin-security-advanced.zod.ts	* Execution timeout in **milliseconds**	.describe('Maximum execution time') — 无单位
packages/spec/src/system/metrics.zod.ts	* Window size in **seconds**	.describe('Window size') — 无单位
packages/spec/src/system/metrics.zod.ts	（interval）	interval: z.number().int().positive().optional().default(60) — 完全没有 .describe()

⚠️ 卡片给的行号（:294 / :552 / :626）是在分支 claude/issue-15679-… @ 45a35896c 上读的；本席在 main 上取到的是同样的代码但行号有小幅漂移。内容全对，行号请以 main 为准重新定位。

---

⭐ 这张卡最重的一条，不是「门漏了三个键」

而是它的第二段后果，卡片自己说得比标题清楚：

That is the cost of the blindness: it does not just miss keys, it produces confident wrong prose about why they were missed.

具体地：卡 3/6（#15678）在它的 changeset 里记下 RuntimeConfig.resourceLimits.timeout 「names no unit anywhere in its prose」——而它上面两行的 JSDoc 写着 milliseconds。结论（"在门的总体之外，别动它"）作为关于门的陈述仍然正确，但留给未来作者的理由是错的，而且现在有一条 pin 测试把它钉住了。

⇒ 这是本 lane 一整天在追的那个失败类的一个新变体：不是「读数不可能失败」，而是**「一个盲区被写成了一条确定的、带钉子的解释」**。下一个作者读到那条 pin 会相信它。

---

定级理由

• domain:spec：见上。
• tooling + finding：门的读取面缺陷，由实测（三个逐个读过的站点）而非模式匹配得出。
• ⛔ 不挂 bug：门的行为与它自己的自测一致——卡片引："a describe declared through .meta({ description }) is READ — no exemption by blindness"，即它声明自己读的是 describe 通道。⇒ main 上没有东西是假的（除了 [#14478 stack 3/6] kernel/: the 14 remaining duration keys carry their unit in the key name — ADR-0087 conversions with readers (runtime-emitted measurements included) #15678 那条 changeset 里的理由，而那是后果，不是门的缺陷）。修 JSDoc 通道属拓宽总体 ⇒ Feature 侧。
• p3：无运行期影响；受影响的是一份内部一致性门的覆盖面，以及一条留给作者的解释。⛔ 不升 p2：那三个键的单位确实被写下来了（在 JSDoc 里），作者能读到；损害是门看不见 + 一条错误的记录理由。

为什么是决定箱

卡片自陈，本席复核后同意："the choice is a rule change and belongs with the maintainer ruling that shaped #14478."

三支的性质完全不同——一支扩总体、一支新增一类拒绝、一支承认现状并改散文：

四facet

① 事实（已复核） check:duration-unit-keys（packages/spec/package.json:290）从 .describe() / .meta({ description }) 读单位，不读键上方的 JSDoc，且其自测把这一点钉成声明行为。三个已读实例的单位只存在于 JSDoc。#15678 据此记下的理由是错的，且被 pin 钉住。

② 分叉（卡片给出，本席原样转达）

1. 把 JSDoc 也当成一条散文通道读。 最忠于规则前提；扩总体 ⇒ 需要自己的卡与自己的前后计数。
2. 拒绝「JSDoc 命名了单位而 describe 没有」的时长键。 更窄：把分歧本身当成缺陷，推作者把单位挪进 describe——门和参考页都能看见的那个通道。
3. 保持现状 + 改散文。 修正卡 3/6 的 pin 注记，把盲区接受为已声明行为。

③ 各支的代价

• 支 1：⚠️ 总体会扩多少，今天没人知道。 卡片诚实地说它的粗略启发式扫描给出 60 个候选，并明确声明那不是总体计数（样本里有字节、百分比、计数、以及已带单位 token 的键等明确假阳性）。⇒ 取这一支的第一步是用门自己的谓词跑一次真实计数，⛔ 不要拿 60 这个数去排期。
• 支 2：最窄，且不需要先知道总体——它只在「两个通道都存在且不一致」时开火，那是一个可枚举的小集合。⚠️ 但它把「只在 JSDoc 写单位」的情况留在盲区里（metrics.zod.ts 的 interval 连 describe 都没有，⇒ 支 2 对它无效）。
• 支 3：零成本；但盲区原样留存，且它保证了同样的错误理由会被再写一次——因为没有任何东西会在下次发生时提醒。

④ 需要裁决者提供的东西
一句话：JSDoc 算不算这条规则意义上的「散文」？ 规则的前提是「单位不得只活在散文里」；而 JSDoc 比 describe 更不可发现（describe 会进参考页，JSDoc 不会）。⇒ 答「算」⇒ 支 1（并先跑真实计数）；答「不算，describe 才是唯一被治理的通道」⇒ 支 2 或 3，但无论哪个，#15678 那条 pin 注记都必须改 —— 支 3 的「只改散文」是那一条的最小交付物，⛔ 不是「什么都不做」。

⛔ 不重复 #15642

卡片的辨析精确且本席背书：#15642 是扫描子树的问题（门只扫 packages/spec/src/**，同型违规在其它 workspace 包里存活）；本卡是同一个文件里读哪条散文通道的问题。两者可以各自为真、各自修复。 ⛔ 不合并。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code