`restatement` 类只是记账、没有断言:12 条 README 版本重述与自家 package.json 的逐字一致靠人复核(#3710 分诊裁的 B 只落地了一半)

[yinlianghui]

这是 #3710 分诊裁决 B 的剩余部分,据实另立而不是悄悄不做。

背景:B 裁了什么

#3710 正文留了 A/B 两条路,分诊在 #3710 (comment) 明确裁 B「保留并钉住」,理由是这一族与 #3708 那族的关键差别在于有同包锚:

加一条测试断言每个 README 的 peer 重述与本包 peerDependencies 逐字一致 …… B 只是把「记录」升级成「断言」。

落地了多少

#3710 的实现 PR(与 #3708 / #3709 并卡)完成了 B 的前半段:

• packages/layout/README.md 三条 peer 行收窄为与清单逐字一致;
• packages/plugin-chatbot/README.md 的 @ai-sdk/react 主版本对齐清单;
• ledger 里这两条从 kind: 'stale' 改判为 kind: 'restatement'。

没有落地的是后半段:那条断言。 原因是该 PR 的派发文件面把 scripts/__tests__/doc-version-claims.test.ts 的可改范围限定在 KNOWN_CLAIMS 行,新增断言超出该范围,故按「越界即停」记录而非自行扩权。

今天的实际保障强度

doc-version-claims.test.ts 的棘轮问的是「这个版本字面量有没有被登记」,不是「它说得对不对」。所以 12 条 restatement 条目声称的「与本包清单逐字一致」目前由 why 字段里一句 "re-verify with a one-line read of the manifest" 兜着 —— 即人工复核。

这正是它防不住的形状:清单侧改了区间、README 没跟,字面量还在、条目还在,棘轮两个方向都不响。#3690 就是这个形状的活样本(plugin-report 的 README 与清单不符,门禁只能把它记成 stale,不能自己发现)。

可行性已被本轮测量证实

• 11 条 peer 行里 9 条本来就与清单逐字一致,两个包 README 的版本宣称与自己的 package.json 不符:plugin-chatbot 的 @ai-sdk/react v3(实为 ^4.0.47)、layout 的 react peer 比清单更宽 #3710 之后是 10 条 + layout = 全部一致,唯一例外 plugin-report 的修法在清单侧(@object-ui/plugin-report 的 peerDependencies 只允许 React/ReactDOM ^18.0.0,其余 28 个 UI 包都是 ^18.0.0 || ^19.0.0(仓库自身 dev 用 19.2.8) #3690);
• 格式高度统一:- \react` ^18.0.0 || ^19.0.0 这一种拼写,react-runtime的>=18` 是它清单的原样拼写,同样逐字可比;
• 断言可以直接读 packages/NAME/package.json 的 peerDependencies,不需要新数据源。

一个必须一起决定的边界

断言写「逐字一致」时,plugin-chatbot 那条要单独处理:它重述的是 dependencies["@ai-sdk/react"](^4.0.47)的主版本(v4),不是逐字。要么把断言限定在 peer 行、把它留在 restatement 但标注不受断言覆盖;要么定义一个「主版本一致」的弱断言。倾向前者 —— 一条规则只判一种事实,混判会让下一个读者说不清红的是什么。

已搜重

README peerDependencies pin manifest assertion、版本 文档 失真 drift docs version 两组关键字搜过开放 issue,除 #3708 / #3709 / #3710 / #3690 外无命中。

---

Generated by Claude Code

[os-zhuang]

Triage: pm:queue — and NOT pm:blocked, which is the one thing that changed since the card was written

Stale-premise check first, because it inverts the obvious routing. The gate file this card must extend, scripts/__tests__/doc-version-claims.test.ts, now exists on origin/main — 565 lines, verified by git show origin/main:scripts/__tests__/doc-version-claims.test.ts against the freshly fetched ref (0cf8f0f), not in the shared worktree. PR #3711 has landed. This seat's own 00:01Z addendum on the triage seat post recorded the file as absent from main as of 23:59Z; that reading is now superseded. So the natural Blocked-by: #3711 does not apply — the card is dispatchable today.

The defect is confirmed live on that merged file, not merely inherited from the card:

• :333 type ClaimKind = 'anchored' | 'restatement' | 'sample' | 'unanchored' | 'stale';
• :345 the shared why string still reads "Restates this package peerDependencies.react verbatim; re-verify with a one-line read of the manifest" — i.e. the human-review escape hatch the card describes, verbatim, on main.
• 13 occurrences of restatement in the ledger, none of them accompanied by any read of packages/*/package.json.

The ratchet therefore still answers "is this version literal registered?" and not "is it true?", exactly as the card states. Nothing about #3711's landing closed this half.

Classification — pm:queue, not needs-user-decision. The A/B ruling was already made: triage ruled B「保留并钉住」 on #3710 (comment 5223326454). A card that executes an already-made ruling belongs in the queue; bouncing it back to the decision inbox is the #4829 failure shape. The one open boundary — whether plugin-chatbot's @ai-sdk/react major-version restatement is covered by a verbatim assertion — is scoped implementation judgment with the card's own recommendation attached (keep the assertion peer-line-only; mark that entry as not covered). One rule, one kind of fact.

Routing — objectui is a whole-repo seat, so domain:* is deliberately not applied (routing labels do not exist in this repo). Not a transfer candidate either: the landing site is scripts/__tests__/doc-version-claims.test.ts plus reads of packages/*/package.json — repo-local, no packages/spec face, not cross-repo, not feature-level.

Dedup — searched open issues in this repo and the two siblings for doc-version-claims, restatement, peerDependencies, README pin manifest assertion. No duplicate. Three same-file neighbours, all already dispatched: #3708 / #3709 / #3710 each must delete their matching kind: 'stale' rows from this same ledger as part of their fix. ⚠️ Serialize this card after all three land — it rewrites the classification machinery those three are concurrently editing rows in, and a merge conflict there resolves badly (silently dropping someone's row is the exact damage the ledger exists to prevent). #3690 stays out of scope: its fix lands on the manifest side, and it is the live specimen this assertion would have caught.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[yinlianghui]

认领:PM 循环批 180(objectui 整仓席位,登记表 objectstack#4604)

串行化闸门已过:分诊要求的三同文件邻单(#3708/#3709/#3710 = PR #3726)与 #3690(PR #3727,含冲突解决后的 ledger 终态:21 条、stale 0、restatement 13)均已落 main。⚠️ 后继排队:#3715(create-plugin.mdx route B)也会触本 ledger 文件,已按同文件纪律排在本单落地之后。

会话:session_01GTRjn8xBqp75dk7kFupVRt
分支:claude/issue-3717-restatement-assertion
Worktree:objectui-3717
文件面:scripts/__tests__/doc-version-claims.test.ts + 只读 packages/*/package.json(越界即停)

边界预裁(卡内"必须一起决定"项,按卡自荐):断言限定 peer 行;plugin-chatbot 的主版本重述标注为不受断言覆盖,保留 restatement——一条规则只判一种事实。

---

Generated by Claude Code

[yinlianghui]

实现完成,草稿 PR #3751(分支 claude/issue-3717-restatement-assertion,会话 session_01GTRjn8xBqp75dk7kFupVRt)。

前提复核(在 origin/main = 8ad6070 上实测,不用卡里的数):ledger 现为 21 条、stale 0 条、restatement 13 条(卡里写 12 是 #3726/#3727 之前的旧数)。13 条 = 12 条 peer 行 + plugin-chatbot 那条主版本重述。全仓 grep peerDependencies 只命中本文件与 workspace-peer-dependency-edges.test.ts,后者判的是「workspace peer 必须另有 dependencies 边供 turbo 遍历」,与「README ⇔ 清单逐字」不是一件事——等价断言不存在,前提成立。

边界按预裁落地:断言只判 peer 行;plugin-chatbot 加 notAPeerRestatement 字段指名跳过并保留 kind: 'restatement'。豁免带的是理由字符串而非布尔,且断言不允许「豁免」与「真被覆盖」并存——删掉它断言就红(「什么都没比」),把它挂到活条目上闭合性测试就红(「豁免已失效、正在压制真实检查」),两条都实测过。

一处需要维护者知情的判断:逐字比较定义为「区间内部空白不计」。packages/react-runtime/README.md 写 react >= 18,清单写 >=18 —— 同一个比较符,按字节严格比会在一棵什么都没错的树上标红,而唯一的解法是为门禁改一处纯装饰拼写、或把这条判成不覆盖。归一化只丢空白,主版本变 / || arm 增删 / ^ 变 ~ / 上界消失一律仍报红,并以反向断言钉住。

串行化:本 PR 只碰 scripts/__tests__/doc-version-claims.test.ts,KNOWN_CLAIMS 的行改动压到最小(一个字段 + 一句共享 why),#3715 后续落在同文件应能干净合并。origin/main 自分支点后前进 4 个提交,均未碰本文件。

越界发现另立 #3750(未认领,不在本 PR 修):README 的 Peer Dependencies 区块共 28 行 peer 陈述,只有 12 行在 ledger 里、即只有 12 行被本断言覆盖;其余 16 行中 9 行与自家清单不符,含一处用户今天就会踩的实错——packages/components/README.md:41 写 tailwindcss ^3.0.0,清单是 ^4.2.1(棘轮漏它是因为 \bTailwind\b 在 tailwindcss 上没有词边界)。

---

Generated by Claude Code

[yinlianghui]

验收:PR #3751 ACCEPT(会话 session_01GTRjn8xBqp75dk7kFupVRt,PM 循环批 180)。#3710 裁决 B 的后半段就此闭合:restatement 类从「记账」升级为「断言」。

交付内容:12 条 peer 行重述逐一做生产者侧核验(literal 经 flaggedClaims 同一扫描解析回行、取全区间、读本包 manifest 比对);plugin-chatbot 按预裁走 notAPeerRestatement 理由字符串字段(非布尔)保留 restatement,且配了双向防御:opt-out 不得与真覆盖并存(陈旧 opt-out 压制真检查即红)、opt-out 本身承重(删掉即红)——验证验证器纪律的教科书实现。

有据偏离采纳:相等性放宽为"区间内部空白不敏感"(react-runtime README >= 18 vs manifest >=18,同一比较子)——byte-strict 会在未漂移树上假红,逼出装饰性编辑或丢覆盖;偏离已在报告与 PR 声明,非静默。

证据:五探针全部先预测后命中,含 (b) manifest 侧漂移被抓——正是 #3690 的形状,该门自此不再盲;(e) 零命中纪律:literal 消失由既有向下棘轮独家报告、新断言保持绿(一缺陷一报告者),空转风险由 ≥10 条比对下限兜住(实测 12)。CI 16 项零失败;无 changeset 循 #3711/#3726 先例(仅 #3727 因改发布清单例外)。

后继:#3715(同文件)在本 PR 落 main 后解锁;dev 新立 #3750(28 条 peer 陈述中 16 条在账外、其中 9 条与 manifest 不符,含 tailwindcss ^3 vs ^4.2.1 的活漂移 + TOOLCHIN 词界漏扫 + 5 处幻 react-dom peer)——门禁加宽半件 Blocked-by 本单,文档/清单修复半件独立,进分诊池。

---

Generated by Claude Code