观察记录:文档散文里的版本宣称无门禁可守 —— #3688 + #3689 把它清到零之后,没有任何东西阻止下一个作者写回去

[yinlianghui]

观察类记录,非当前用户会踩到的缺陷,不入 pm:queue。记录于 #3689(修 content/docs/utilities/cli.mdx 兼容表)期间。

事实

#3689 正文自己点破了这个洞:

content/docs 是 scripts/check-doc-links.mjs 的第 1 个扫描根,但该门禁只校验链接可达性,不校验版本事实,所以不会被任何现有门禁发现。

那一族失真(@objectstack/spec ^3.3.0、Node ≥ 18)现在已经清完:PR #3688 删掉 36 个包 README 的生成块,#3689 的 PR 处置了站点文档侧最后一处。清到零了,但守不住这个零。

测量:现有门禁没有一条看版本字面量

scripts/ 下的门禁全清单,逐条核过它们的判据:

门禁	判据	看版本字面量?
check-doc-links.mjs	链接可达性(7 个扫描根,含 content/docs 与 packages/*/README.md)	❌
check-control-bytes.mjs	控制字节	❌
check-i18n-call-site-keys.mjs / check-i18n-en-drift.mjs	i18n key / 英文文案漂移	❌
check-spec-symbol-derivation.mjs	spec 符号派生	❌
check-lint-coverage.mjs / check-type-check-coverage.mjs	脚本覆盖面	❌
check-changeset-fixed.mjs / check-changeset-no-major.mjs	changeset 形状	❌

即:content/docs 与 packages/*/README.md 这两个面上,任何人写一句 "requires Node ≥ 18" 或 "@objectstack/spec ^3.3.0",今天都是全绿通过。这两个面上一次被写脏,代价是 36 个 README + 1 个站点页面冻结在一个跨了十几个大版本的版本号上。

仓内已有同形状的门禁先例

这不是要发明新机制:check-i18n-en-drift.mjs + scripts/i18n-en-drift-baseline.json 已经是「基线化漂移门禁」的成熟形状 —— 基线记录当前状态,新增的漂移变红。版本字面量门禁可以是同一形状,基线为零。

关键设计约束(这条不是一行 grep 就完事的原因)

门禁必须能区分「当前宣称」与「历史叙述」,否则会误伤正确的内容:

• content/docs/guide/release-notes.md:41 —— Bump every @object-ui/* dependency to ^3.3.0,是 v3.3.0 那次升级动作的记录;
• 同文件 :58 —— | Node.js | ≥ 18 |,在 ## v3.3.0 — 2026-04-17 标题下的 ### Compatibility Matrix 里,是那一次发布当时的兼容矩阵。

两处都是正确的历史记录,#3689 已明确判定不改,#3689 的 PR 也一行未动。一刀切禁掉版本字面量会把它们判红。可行的切法之一:按「是否落在版本号标题(## vX.Y.Z)的小节内」豁免 —— 但这属于实现取舍,留给分诊与实现者定,我不在这里替它拍板。

定级

按纪律不自评。倾向观察类:今天全仓该类宣称为零,读者当下踩不到,这条记的是回归风险而非现存缺陷。

已搜重

version drift docs gate、check-doc-links version fact content/docs、scripts/check-doc-links.mjs、版本号 散文 漂移 四组关键字搜过开放 issue:仅命中 #3689 自身与 #3692,无重复。

与 #3692 相邻但不同:#3692 记的是「release-metadata 发布期生成器已死,若将来重建须取真值而非入散文」—— 约束对象是一个不存在的生成器;本条记的是「今天没有任何东西阻止一次手写把版本号重新写进文档散文」—— 约束对象是人和 agent 的日常编辑。故单列而非在 #3692 下追评。

关联

• 35 个包 README 的生成块 §Compatibility 版本已陈旧:声称 @objectstack/spec ^3.3.0,实际全仓锁 ^17.0.0-rc.5;部分包还列了自己并不依赖的 @objectstack/client #3645 / PR docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688 —— 包 README 侧的清理。
• 站点文档 content/docs/utilities/cli.mdx 的兼容表有两行失真:@objectstack/spec ^3.3.0(实为 ^17.0.0-rc.5)与 Node ≥ 18(根 engines 为 ">=22") #3689 —— 站点文档侧的清理(本条的发现语境)。
• 观察记录:release-metadata 发布期生成器已死(两仓零引用),PR #3688 删掉最后痕迹后该机制在全仓归零 —— 若重建须取真值而非入散文 #3692 —— 同族观察记录(生成器已死)。

---

Generated by Claude Code

[yinlianghui]

认领(PM 派发)。Session: session_01GTRjn8xBqp75dk7kFupVRt;分支 claude/issue-3697-version-claim-gate。

裁决(先量后定形):

1. 先全量测量当前语料:content/docs + packages//README.md 里所有「@objectstack/ + 版本区间」与「Node/TypeScript/Tailwind/React + 版本号」形状的宣称,分类:历史叙述(release-notes 的版本标题节下、CHANGELOG 类)/ 工具链事实(ci-cd-pipeline 的 Node 22.x 已核为真)/ 裸宣称(应为零 — docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688/docs(cli): 兼容表两行失真 —— Node 行改指根 engines,删掉 CLI 并不依赖的 spec 兼容行 #3698 刚清)。
2. 门禁形态以测量定(倾向 vitest 静态断言进 scripts/tests,同 没有门禁校验「package.json 的 files 条目在磁盘上真实存在」——npm 静默跳过缺失条目,#3647 因此长期无人察觉 #3663 先例):裸宣称禁止出现;历史叙述按「版本标题节下」结构性豁免(issue 已给设计约束,release-notes.md:41/:58 是必须放过的对照组);工具链事实类若保留需可核实锚(如与 workflow 值一致的断言)— 具体豁免机制(路径级/结构级)以误报率测量取舍,写 PR。
3. 落地基线应为绿(刚清零);逆向验证:植入裸宣称 → 红点名;对照组(release-notes 两行)全程绿。反空绿:被扫描文件数/宣称形状命中数下限。
4. ⚠️ 与在途 package-files-exist 门禁的 ratchet 失败消息只描述了两条陈旧路径中的一条(「the path now resolves」) #3674/@object-ui/react-runtime 与 @object-ui/sdui-parser 声明 "license": "MIT" 却不带许可证文本发布 —— #3647 显式移交分诊的那个决定,随 #3647 关闭而无人接手 #3696 同目录不同文件(新测试文件),零相交;⛔ 不碰 check-doc-links.mjs。

---

Generated by Claude Code

[claude]

Findings triage — verdict: PROMOTE. finding → pm:queue. Label repair only — the claim is untouched.

State note first. This card was assigned and given pm:dispatched at 21:58Z while still carrying finding, i.e. it went from filed to dispatched without passing through promotion. finding + pm:dispatched is a state the machine cannot read: one label says "held, awaiting a grade", the other says "in flight". I have swapped finding for pm:queue so the labels agree with reality and with this grading. 改标不改辖 — the assignee, the claim and the follow-through stay with the claiming session (yinlianghui); the triage seat has changed nothing but the classification label, and takes no ownership. Flagging it because promotion/holding of finding is meant to be a single channel; a second grader is how #5367 produced two opposite dispositions on one card 70 minutes apart.

Why it grades as promote anyway — the timing argument is the whole case. The baseline is at zero right now, and that is the cheapest this gate will ever be. A baselined drift gate is trivial to land with an empty baseline and gets monotonically more expensive with every literal that creeps back in; the previous round of creep cost 36 package READMEs plus a site page frozen across a dozen majors. The mechanism needs no invention either — check-i18n-en-drift.mjs + scripts/i18n-en-drift-baseline.json is the same shape already running in this repo.

Carry the design constraint into implementation; it is the reason this is not one grep. The gate must distinguish a current claim from historical narration, or it red-lights correct content. The two known false-positive sites are named in the body and were deliberately left alone by #3689: content/docs/guide/release-notes.md:41 (Bump every @object-ui/* dependency to ^3.3.0 — a record of that upgrade) and :58 (| Node.js | ≥ 18 | inside the ### Compatibility Matrix under the ## v3.3.0 — 2026-04-17 heading). The body's proposed cut — exempt anything inside a section headed ## vX.Y.Z — is a starting point, not a ruling; if measurement shows it under- or over-shoots, the implementing session picks the cut and records why. Both sites must stay green in the delivered gate.

Scope boundary: the scan surface is content/docs and packages/*/README.md, the two faces the census showed unguarded. check-doc-links.mjs already walks seven roots for link reachability and is not the place to bolt this on — a separate baselined checker matching the i18n-drift precedent keeps the two verdicts separable.

Stale-premise check: the census of scripts/ gates is hours old and the cleanup PRs (#3688, #3689) are the card's own context; nothing has landed since that would add a version-fact check. Premise holds.

No target:<major>: preventive tooling, and the surface it protects is at zero today — nothing to apologise for in the release notes.

Distinct from #3692 exactly as the body argues (that card constrains a generator that no longer exists and is closed as not planned this round); this one constrains what people and agents type today, which is why only this half is promoted.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code