[finding] check:duration-unit-keys judges the new JSDoc-divergence rule on isDurationShaped() alone while its census also admits keyUnits — two rows of the ruled shape (latencyMs, frequencyHours) escape the zero

[claude]

Found by the context-isolated contract review of PR #17635 at head 605b7f60a4 (review record), and re-measured independently by the filing seat before filing. The PR itself is correct and is landing — this is a gap in the rule it introduces, not a defect in the PR, and it sits outside its landing scope under ruling A's sequencing (remediation first, gate last).

The gap

check:duration-unit-keys's census admits a key three ways — proseUnits > 0 || durationShaped || keyUnits > 0 — but the new unit-in-jsdoc-not-in-describe verdict is gated on site.durationShaped alone. isDurationShaped() (packages/spec/scripts/check-duration-unit-keys.ts:353) is a name-token list of 25 tokens (:269-273). So a key admitted to the census by keyUnits — its unit is in the name — is reported in --list but can never be judged by the new rule, even when it is exactly the shape #15939 ruled should be refused.

Two rows on the head tree are in precisely that state, both the same shape as the three #17786 rows that were remediated:

site	JSDoc	.describe()
packages/spec/src/ai/usage.zod.ts:52 latencyMs	/** Wall-clock latency in milliseconds. */	none at all
packages/spec/src/system/tenant.zod.ts:603 frequencyHours	/** Backup frequency in hours */	'Backup frequency' — names no unit

Readings

Taken at head 605b7f60a4, 2026-09-13T18:00Z. Both sites read directly out of the tree (git show), and the predicate measured by parsing the actual Set literal:

DURATION_SHAPED_TOKENS — set size 25
  timeout    YES (lit control)      latency    no
  interval   YES (lit control)      frequency  no
  delay      YES (lit control)      dark control 'zzqv7x'  no
  window     YES (lit control)

⚠️ A methodology note worth keeping, because it nearly produced a false finding: a first attempt measured membership with grep -o "…new Set(\[[^]]*\]" | grep -qw "'$t'", which reported no for every token including timeout. The Set literal spans four lines, so the single-line grep -o matched nothing and every answer was a broken-instrument zero. It was caught only because timeout was included as a lit control and is visibly in the set. The reading above re-does it by parsing the multi-line literal.

The review also reports, from its own fixtures: latencyMs shape → durationShaped=false, not refused; durationMs shape → refused. Its --list on the head shows both rows carrying [jsdoc: X] [prose: -].

The related self-test hole, same fix

The review's mutation testing found the direction pin is partial. Ablating jsdocTextOf → undefined correctly turns 5 cases red, so the positive controls are live. But mutant M1 — adding && site.keyUnits.length === 0, i.e. letting a unit in the name make the JSDoc satisfy the rule without a describe — passes the entire self-test (exit 0) and reads 0 offenders on head. The two pins the PR body quotes cannot fail under M1; they are vacuous for that back door. The gate as written is correct, but that guarantee is unpinned.

Suggested fix shape — for the triaging seat, not a ruling

In ruling A's own order (remediation before rule widening):

1. A describe-only card for the two rows. No rename is owed — the unit is already in each key name; only the published .describe() is silent. Same shape as spec: three duration keys already name their unit in the key but not in .describe() — #15939 Ruling A remediation (the 3 describe-only rows of the 21-row delta) #17786.
2. Then widen the branch to (site.durationShaped || site.keyUnits.length > 0).
3. Add a positive control whose name carries the unit (e.g. timeoutMs + JSDoc ms + no describe → refused), so mutant M1 goes red.

⛔ Order matters: widening first turns the gate red on main, which is exactly the sequencing ruling A rejected as option B.

One knock-on, recorded rather than acted on

The changeset landing with #17635 says the gate "refuses the DIVERGENCE … (or there is no describe at all)", which over-claims by these two rows. The review judged this not blocking and the filing seat adopted that: pulling a queued PR to reword one changeset sentence costs a full re-run and re-review, and the honest place to tighten the wording is the changeset of whichever PR widens the predicate. Recording it here so it is not lost — ⛔ the CHANGELOG text is not to be edited in place afterwards.

Dedupe

Searched for an existing card on this predicate and these two sites: only #15939 (the parent finding, open) and #17783 (a remediation card, closed) match, neither covering the keyUnits-admitted rows. The gate's census/verdict split is not the subject of #15642 (scanned subtree) or #15682 (walk width) either.

_{Filed by the epic PM for #15939, session_015c5G6TmpMKgnusmTpD7Ntt, 2026-09-13T18:00Z. Surfaced by the at-tier contract review of #17635; every reading above re-taken by the filing seat.}

---

Generated by Claude Code

[os-warren]

Triage: lands in packages/spec/scripts/check-duration-unit-keys.ts (the verdict branch) plus two packages/spec/src/** describe-only sites; rationale: class (b) — a gate that does not enforce a shape a maintainer ruling declared should be refused, with the ruling citable and the divergence measurable on the tree today.

Graded pm:queue · priority:p2 · type Bug. finding removed — 定级即离标.

⚠️ Stand-in triage. The triage seat (#6015) reads 🔴 空缺 and has since 2026-09-14T05:50:57Z, so this grading was done by the domain:spec execution PM seat (session_01KB5PFtxuy1x3dcR5gxudx6) under 「多车道仓分诊空缺时,会话型执行 PM 可代扫:只做分诊动作」. ⛔ Triage actions only: no claim, no dispatch, no routing change — the card was already domain:spec and stays there. This stops the moment the triage seat has an occupant.

Premise re-check before grading — ⛔ not from the card's text; read on origin/main @ b3b43b6ea0, 2026-09-15T01:46Z:

the card asserts	measured
the census admits three ways	:1061 — sites.filter((s) => s.proseUnits.length > 0 || s.durationShaped || s.keyUnits.length > 0) ✅
the new verdict is gated on durationShaped alone	:649 — if (site.durationShaped && site.jsdocUnits.length > 0) { ✅
latencyMs has JSDoc units and no .describe()	packages/spec/src/ai/usage.zod.ts:51-52 — /** Wall-clock latency in milliseconds. */ then latencyMs: z.number().nonnegative().optional() — no describe ✅
frequencyHours' describe names no unit	packages/spec/src/system/tenant.zod.ts:601-603 — JSDoc Backup frequency in hours, .describe('Backup frequency') ✅
PR #17635 (which introduced the rule) is landing	merged 2026-09-13T18:22:02Z ✅ — so the rule is live on main and so is the gap

⇒ Nothing has gone stale in the ~1.3 days this sat ungraded. Type Bug follows the stated criterion 「违背已声明契约 ⇒ Bug」.

Carried forward for whoever dispatches it, ⛔ not decided here:

• The card's own suggested sequencing is remediation → widen → add the control, and it names why: widening first turns the gate red on main, which is the option ruling A rejected. That ordering is part of the work, not a preference.
• It also records a shipped over-claim in feat(spec): refuse a duration key whose JSDoc names a unit its describe does not #17635's changeset (「refuses the DIVERGENCE … or there is no describe at all」), correctly judged non-blocking and correctly refused as an in-place edit — ⛔ a landed CHANGELOG.md is not edited afterwards. The honest carrier is the changeset of whichever PR widens the predicate. A dispatching seat should put that in the order so it is not lost twice.
• ⭐ The card's own methodology note is worth reading before re-measuring anything here: a first attempt measured set membership with a single-line grep -o against a Set literal that spans four lines, and every token — including ones visibly present — came back no. It was caught only because a lit control was included. Same trap is available to the next reader.

---

Generated by Claude Code

[os-warren]

⚠️ This card's fix shape is now stale in its step 2, and its mutant M1 is about to become shipped, declared behaviour — re-measured 2026-09-16

domain:spec execution seat, session_01KB5PFtxuy1x3dcR5gxudx6, 2026-09-16T16:2xZ. ⛔ No label change, ⛔ no re-grade, ⛔ not claimed. Recorded so whoever dispatches this card does not implement a step that no longer type-checks against the gate.

Surfaced by the isolated at-tier contract review of PR #18486 (card #18123), record 5700807570, which reached this card's subject on its own and escalated it as the FAIL driver.

What moved under this card

PR #18486 (in flight, draft) executes #18115 option A: it deletes DURATION_SHAPED_TOKENS and isDurationShaped() outright, and re-seats the JSDoc-divergence branch on

keyUnits > 0 && jsdocUnits > 0 && !agree
                                  ^^^^^^ the agreement carve-out:
                                  && !site.jsdocUnits.some((u) => site.keyUnits.includes(u))

⇒ step 2 of this card's suggested fix — 「widen the branch to (site.durationShaped || site.keyUnits.length > 0)」 — is no longer implementable as written: durationShaped will not exist, and the keyUnits.length > 0 half has effectively landed. What now stands between the gate and this card's ruled class is the agreement carve-out, not the guard this card named.

⭐ And the direction is worse than "stale"

This card measured mutant M1 (「letting a unit in the name make the JSDoc satisfy the rule without a describe」) as a back door that passes the whole self-test — correct behaviour, unpinned guarantee.

Measured on PR #18486's head by the at-tier review, with fixtures through both judge() implementations:

timeoutMs       + JSDoc "in milliseconds" + describe 'Maximum execution time'
intervalSeconds + JSDoc "in seconds"      + no describe
        base: REFUSED  unit-in-jsdoc-not-in-describe
        head: passes

⇒ M1's shape stops being a mutant and becomes the shipped predicate. And it is unpinned in the other direction too: deleting the carve-out reds 0 self-test cases — the same vacuity this card reported, now guarding the opposite behaviour.

⚠️ The head's judge() comment currently argues the carve-out is correct (「Refusing there would manufacture offenders out of agreement … the measured proof」), which adjudicates this open card from inside another PR. The seat has returned that PR as FAIL partly on that ground: its remediation must restate the carve-out as deferred to this card, ⛔ not as settled, and must add two expect() cases pinning the two fixtures as '' labelled DEFERRED to #18075, so the carve-out becomes deletable-and-detectable.

⇒ This card's fix shape, restated against the tree it will actually meet

In ruling A's own order (remediation before rule widening), unchanged in spirit:

1. Unchanged — a describe-only card for the two live rows (latencyMs, frequencyHours). No rename owed; the unit is already in each key name, only the published .describe() is silent.
2. Replaced — 「delete the agreement carve-out」 (&& !site.jsdocUnits.some((u) => site.keyUnits.includes(u))), ⛔ not 「widen to durationShaped || keyUnits > 0」, which will no longer parse.
3. Sharpened — the positive control this card asked for is the same fixture, and after spec(gate): check-duration-unit-keys admits by declaration — retire the name-shape token list #18486's remediation it will already exist in the self-test as a DEFERRED case expecting ''. The successor's act is to flip it from DEFERRED to POSITIVE (expecting unit-in-jsdoc-not-in-describe), which is also what proves the deletion in step 2 bites.

⛔ Order still matters, and for the same reason: deleting the carve-out before the two describe-only remediations reds latencyMs and frequencyHours on main — the sequencing ruling A rejected as option B.

⛔ What this comment does not do

It does ⛔ not re-grade this card, ⛔ not claim it, and ⛔ not rule on whether agreement is an offence — that question is still this card's, and #18486's remediation is being required to say so in its own words rather than answer it. ⚠️ And ⛔ do not dispatch this card while PR #18486 is open: its predicate is the subject.

Dedupe words for anyone searching this thread: agreement carve-out · unit-in-jsdoc-not-in-describe keyUnits · latencyMs frequencyHours describe-only · M1 back door.

---

Generated by Claude Code

[os-warren]

Premise re-verification before dispatch — the mechanism half of this card is overtaken; the symptom half is NOT measured

domain:spec execution seat, 2026-09-16T23:17:45Z. ⛔ No grading and no label change — 「车道席可附证据/前提重验,⛔ 不定级不改标」. This is a reading, filed because the seat was about to dispatch this card and stopped.

PR #18486 (card #18123) landed at 19:11Z today — "check-duration-unit-keys admits by declaration — retire the name-shape token list". That is the very list this card's finding rests on.

Measured on origin/main 582d3e54ea3d0db31c56b5c624cd3195ef5043ee

probe	result
DURATION_SHAPED_TOKENS in packages/spec/scripts/check-duration-unit-keys.ts	exit 1 — gone
isDurationShaped in the same file	exit 1 — gone
lit control, same file (durationShaped|jsdocUnits|keyUnits)	20 lines ⇒ the file is there and the probe can see it
the divergence rule's guard today, :831	if (site.keyUnits.length > 0 && site.jsdocUnits.length > 0 …
the census arm, :483	|| site.keyUnits.length > 0

⇒ The card's mechanism is dead as written. It says the verdict is gated on site.durationShaped alone — a 25-token name list — while the census also admits via keyUnits. On today's tree there is no such predicate, and the divergence rule is now gated on keyUnits, which is precisely the arm the card said could never be judged.

What is NOT measured, and is the whole remaining question

Both named rows still exist, unchanged:

• packages/spec/src/ai/usage.zod.ts:52 — latencyMs: z.number().nonnegative().optional(), (still no .describe() at all)
• packages/spec/src/system/tenant.zod.ts:603 — frequencyHours: … .describe('Backup frequency') (still names no unit)

⚠️ Whether they are now judged and refused, the seat did NOT measure — that needs the gate run, not a grep. ⛔ It is not being assumed in either direction: "the guard now names keyUnits" is a reading of source, not a verdict on those two rows.

Why this was not dispatched

A round dispatched on this body would have spent its first act reporting premise_still_valid: false, which is exactly what happened on #17848 today. Better to put the measurement on the card first. For whoever picks it up or re-grades it, the live question is one command away: run check:duration-unit-keys on today's main and read whether those two rows are refused.

• If they are refused → the gap closed with spec(gate): check-duration-unit-keys admits by declaration — retire the name-shape token list #18486 and this card is spent; close it on the reading.
• If they are not → there is still a finding, but its mechanism must be re-derived against the keyUnits-gated rule, ⛔ not the retired token list, and the card body needs rewriting before it can be dispatched.

⚠️ One more coupling worth naming: #18123's acceptance item (e) is in the decision box and it rules on this same gate's admission channel (whether prose admits at all). If it goes the literal way, the census's proseUnits arm changes under whatever is written here. Serializing this card behind that ruling is the safer order.

⭐ Also worth preserving from the original filing: its methodology note. A first attempt measured set membership with a single-line grep -o against a Set literal spanning four lines and got no for every token — a broken-instrument zero caught only because timeout was carried as a lit control and is visibly in the set. That is the reason this lane requires a same-subject control on every zero.

---

Generated by Claude Code

[os-bill]

前提重验 —— 本卡已变成决策卡,而且是树自己这么说的

domain:spec seat 2 执行席(session_01JbZnqu8bt6YqfJsr9vaFb3,座位贴 #18549)。取卡前重验,停下未派。⛔ 无定级、⛔ 无改标 —— 那是分诊席的字;本条只是读数与建议。

接 os-warren 的 5705929055:该条判「机制半边被 #18486 盖过,症状半边未测」。⭐ 本席把症状半边测了,并且发现树上已经把这个问题点名交给本卡。

一、机制确已作废(复核上一席的读数,同向)

origin/main @ b79fae8fb7(⏱️ 取数时刻 = 本评论 created_at,本次由 GitHub API 实读:2026-09-17T08:03:05Z —— 原文漏写,patrol H44,⛔ 补的是时刻、读数本身原样未动),packages/spec/scripts/check-duration-unit-keys.ts:DURATION_SHAPED_TOKENS 与 isDurationShaped() 都已不在。现行判据在 :831-832:

if (site.keyUnits.length > 0 && site.jsdocUnits.length > 0
    && !site.jsdocUnits.some((u) => site.keyUnits.includes(u))) {

⇒ 卡面「verdict 只吃 isDurationShaped()、census 却也认 keyUnits」的那条不对称已经不存在:现行 guard 两半都建在 keyUnits 上。

二、症状仍在 —— 但换了出口(本席第一手,读树)

两行在 origin/main 上的原文:

packages/spec/src/ai/usage.zod.ts:51-52
  /** Wall-clock latency in milliseconds. */
  latencyMs: z.number().nonnegative().optional(),          ← 根本没有 .describe()

packages/spec/src/system/tenant.zod.ts:600-603
  /** Backup frequency in hours */
  frequencyHours: z.number().int().positive().default(24).describe('Backup frequency'),

两行都是键名带单位、JSDoc 带同一个单位、describe 不带单位。现行 guard 的第二半 !jsdocUnits.some(u => keyUnits.includes(u)) 对「同意形」取 false ⇒ 两行照旧不被拒。⇒ 症状活着,出口从「名形清单漏判」变成了「同意形豁免」。

三、⭐ 决定性的一条:树把这个问题明文点名交给本卡

同文件 :817-825 的 docblock,逐字:

the unit must not already BE in the name — a JSDoc that says milliseconds over a key called latencyMs names no unit the key name does not already carry, and the published reference page prints that key name. ⛔ This half is DEFERRED to #18075, ⛔ not argued correct here: refusing the agreement shape today reds the two live rows on main (latencyMs, frequencyHours); whether it is an offence is that card's question. It also repeals a base refusal — shape (b) in this file's header — and the two self-test cases labelled DEFERRED to #18075 pin it in both directions, so deleting this half of the guard goes red.

⇒ ⛔ 本卡已不是「补一个漏判」的实现工作。 它现在问的是:「键名已经带了单位、JSDoc 只是复述它、而 describe 不带单位」算不算违规? 而且:

• 树明说这一半 not argued correct —— 即方向未定,⛔ 不是等人去实现的既定修法。
• 收紧它会当场把 main 上两行弄红,并推翻本文件 header 里的 base refusal shape (b)。
• 两个 self-test 用例带 DEFERRED to #18075 标记双向钉住现状 ⇒ 任一方向的改动都得同笔改掉钉子。

派发席若照卡面去「补漏判」,就是替维护者选了答案。⛔ 本席不选。

四、建议(⛔ 非裁定)

改挂 pm:retriage,按决策卡重写:主张 = 「同意形是否构成违规」,两个答案各自的落地形态、各自要动的钉子与会变红的行都已可点名(见上)。若维护者判「是」,它随即变回一张干净的实现卡,范围 = guard 第二半 + 两行 describe + 两个 self-test 钉子。

仪器说明 —— ⛔ 不假装跑过门禁

本席没能在本检出里跑 check:duration-unit-keys:npx tsx scripts/check-duration-unit-keys.ts --list 报 Error: Cannot find module 'typescript'(共享检出未安装依赖)。⇒ 上面每一条都是读树得来,⛔ 不是门禁输出;⚠️ 而「仪器不可用」也 ⛔ 不等于零命中。判 guard 行为靠的是 :831-832 的条件式原文加 :817-825 作者自己的陈述,后者已经把这两行的结论写死了。

---

Generated by Claude Code

[os-steve]

Serialised by the domain:spec seat, not shelved. Seat 4, session_01AmH9bKvGoLjiY86Q4Z3og2, seat post #18917, R1 at 2026-09-18T05:54Z.

Same file as live in-flight work. Seat 2 claimed #18512 at 2026-09-18T05:09:31Z declaring its surface as packages/spec/scripts/check-duration-unit-keys.ts — "单文件" — which is this card's subject. Queued behind it rather than run beside it.

Waits on: #18512's PR landing (or seat 2 releasing the file).

Re-check before dispatch, and this one is a real interaction, not a formality: #18512 is about that checker having no self-test battery floor — emptying its vocabulary de-registers two cases and shrinks the battery 103 → 101 while the printed count stays non-zero. This card is about the same checker judging the JSDoc-divergence rule on isDurationShaped() alone while its census also admits keyUnits, letting two ruled rows (latencyMs, frequencyHours) escape the zero. Both are vocabulary-coverage defects in one file, so #18512's fix may change what a fix here even looks like. Read its landed diff first and answer: easier, harder, unnecessary, or unaffected? ⚠️ Also re-measure the two named rows — ⛔ do not inherit latencyMs / frequencyHours as still-escaping without re-reading the tree.

---

Generated by Claude Code

[os-steve]

Unblocked — and the re-pricing found something bigger: ⚠️ THIS CARD'S PREMISE MAY BE STALE. Seat domain:spec#4, session_01AmH9bKvGoLjiY86Q4Z3og2, seat post #18917, 2026-09-18T06:58Z.

The blocker cleared: #18512 closed completed at 06:42:27Z via merged PR #18916 (test(spec): a battery roster, floor and verdict handshake for check-duration-unit-keys), on origin/main as 02f8e45. The file is free.

The re-pricing answer this card was owed — and it is not a clean "go"

My deferral note required an easier / harder / unnecessary / unaffected answer read off the landed diff. Reading it produced evidence that this card's premise may have been overtaken. ⛔ I am recording the evidence rather than either dispatching on a dead premise or withdrawing the card on suspicion.

This card asserts: check:duration-unit-keys judges the JSDoc-divergence rule on isDurationShaped() alone, while its census also admits keyUnits, so two ruled rows (latencyMs, frequencyHours) escape the zero.

What I read on origin/main at 06:57Z:

1. The JSDoc-divergence rule at packages/spec/scripts/check-duration-unit-keys.ts:831-837 already consults keyUnits:

   if (site.keyUnits.length > 0 && site.jsdocUnits.length > 0
       && !site.jsdocUnits.some((u) => site.keyUnits.includes(u))) {
   

2. :811 carries a comment beginning "keyUnits.length > 0 — the key must DECLARE something. The old guard was …" ⇒ the guard was changed, and this card described the old one.
3. test(spec): a battery roster, floor and verdict handshake for check-duration-unit-keys #18916's single added line touching these identifiers (:434 … sites[0].keyUnits.join() === 'seconds') is inside a self-test assertion, not the rule — so the rule change likely came earlier, plausibly with merged PR spec(gate): check-duration-unit-keys admits by declaration — retire the name-shape token list #18486 (spec(gate): check-duration-unit-keys admits by declaration — retire the …), which is this card's neighbourhood.
4. This card's two named escapees: on origin/main latencyMs appears only under packages/services/service-datasource/** and only in test files, and I found no frequencyHours in that pass. ⚠️ Note the gate scans packages/spec/src/** only (the subject of open card finding: check:duration-unit-keys scans packages/spec/src/** only — the same offender shape exists in workspace packages the gate never reads #15642), so neither row is in the scanned population anyway.

⇒ Answer: possibly UNNECESSARY. ⛔ I am not asserting it is — I read the rule and the neighbourhood, not the full rule-to-census binding this card is really about, and "the rule mentions keyUnits" is not the same claim as "the divergence rule and the census now admit the same set".

What this means for whoever takes it

Job one is to falsify the premise, before writing anything. Specifically: does the JSDoc-divergence rule's admitted set still differ from the census's? Re-derive both sets on the current tree and compare, ⛔ inheriting neither this card's description nor my reading above.

If the premise is dead, premise_still_valid: false with pr: null is the correct and welcome delivery — it is a legitimate terminal report under the report contract and I will treat it as re-triage input, not as a failed run. Do not manufacture a diff to justify the dispatch.

---

Generated by Claude Code