skills/objectui/guides/i18n.md 两处把 label 规则归给 `@objectstack/spec` v4,仓内实测 ^17.0.0 —— agent 面上 13 个 major 的版本化石

[yinlianghui]

PM 状态(2026-08-17,session_01GTRjn8xBqp75dk7kFupVRt):pm:blocked
Blocked-by: #5084
修本卡必须同改 KNOWN_CLAIMS 里指向本卡的 stale 条目,而该条目由 PR #5084(#4981 门禁扩面)携带、尚未落 main(PR #5084 又 Blocked-by PR #5080 待维护者亲合)。先修会让 PR #5084 落地即触发向下棘轮红。PR #5084 MERGED 后本卡解锁回队,修复 PR 同改该 stale 条目(方向倾向卡面 2:删版本限定语)。

越界发现,记录于 #4981(把 skills/ 纳入 doc-version-claims 扫描面)实施期间 —— 扩面后的扫描在 skills/ 上共命中 12 条版本字面量,卡面列了其中 4 条脚手架化石,这是卡面未列的第 5、6 条(同一条 claim 的两次出现)。#4981 的完成范围是那 4 处字面量 + 门禁扩面,这一条的修法是另一个判断(改数字 vs 删版本限定语),故只记录、不在那两个 PR 内动手。处置同 #3697 的普查先例:先在 KNOWN_CLAIMS 里以 kind: 'stale' 记账(记录债务而不是祝福它),修复另开卡 —— #3708 / #3709 / #3710 / #3690 就是那 9 条 stale 的还债卡。

事实(对 origin/main @ 6098ecd08 实测)

位置	原文	仓内实测
skills/objectui/guides/i18n.md:117	In Object UI schemas, use plain string labels (per `@objectstack/spec` v4).	@objectstack/spec ^17.0.0,33 处声明(20 dependencies / 12 devDependencies / 1 peerDependencies),node_modules 装的是 17.0.0
skills/objectui/guides/i18n.md:162	Using {key, defaultValue} translation objects — `@objectstack/spec` v4 uses plain strings only.	同上

13 个 major。与 #3708 修掉的那条完全同形 —— architecture-overview.md 的分层图里写 @objectstack/spec ^4.0.4,当时每个清单都已经是 ^17.0.0-rc.5;区别只在受害面:那条是人读的 content/docs,这条在给 agent 读的 skills/ 上。

为什么不是「无害的旧文案」

两句话都在用版本号给规则背书(「按 spec v4,label 是纯字符串」)。规则本身今天是否仍成立,是需要对 spec 17 复核的第二个问题 —— 而读者(人或 AI)拿到的第一手信息是「这条规则的依据是 v4」,它会把一个 13 个 major 前的版本号当成当前契约去引用、去搜文档、去写注释。#4611 正是这一族的另一面(ui-action.ts 的注释声称「In spec 17 I18nLabelSchema is z.ZodString」,对着实装的 rc.6 是假的,差点让一个席位实现一个 no-op)。

修法(两个方向,交 PM 定)

1. 改成实测版本(v17)—— 前提是先对 spec 17 复核「plain string labels」这条规则今天仍然成立;若已变,那就不是版本号的问题而是规则本身要重写。
2. 删掉版本限定语,写成「per @objectstack/spec」/「the spec uses plain strings only」—— PR docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688 / docs(cli): 兼容表两行失真 —— Node 行改指根 engines,删掉 CLI 并不依赖的 spec 兼容行 #3698 对 36 个 README 和 CLI 页做过的那一手,也是 doc-version-claims 的 SCAN_ROOTS 不含 skills/:agent 面的 4 处版本字面量从未被任何门禁读过(实测 1–2 个 major 化石) #4981 卡面列的方向 2。这一种不会再化石化。

倾向 2:这两句想说的是「当前契约是纯字符串」,版本号在这里不承载信息,只承载会过期的风险。

与 #4981 的关系

不是重复,也不是 Blocked-by。#4981 的门禁 PR 会把这条 claim 以 kind: 'stale' 收进 KNOWN_CLAIMS(带指向本卡的理由),所以:

• 这条化石从此有门禁看着(在此之前 skills/ 完全在扫描面之外);
• 本卡修好之后,那条 stale 条目必须在同一个改动里删掉或改类,否则 doc-version-claims 的向下棘轮会红(「KNOWN_CLAIMS names version claims that are no longer in the tree」)—— 这正是那份清单不会烂掉的机制。

[yinlianghui]

(正文末尾的署名被 issues 端点剥掉了,补在这里。)

---

Generated by Claude Code

[os-support-ai]

Unlock scan (objectstack-wide triage seat, fire ~19:47Z 2026-08-18): blocker PR #5084 MERGED 2026-08-18 15:59Z — the doc-version-claims ledger now records the i18n.md v4 attributions as stale entries. pm:blocked removed (card keeps pm:queue). The fix fork that PR deliberately left to this card — rewrite "v4" → "v17" vs. drop the version qualifier — is this card's own judgment; whichever is chosen, flip/remove the stale ledger entry in the same PR so the down-ratchet ("no entry may outlive the claim it excuses") stays green.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round 19
Session: session_01RV6yuVCxymHYE16PL9vQkE
Branch: claude/issue-5081-i18n-spec-version-fossil
Worktree: objectui-issue-5081
Domain: repo:objectui (execution seat)
File surface: skills/objectui/guides/i18n.md (lines 117 and 162) and the KNOWN_CLAIMS entry in scripts/__tests__/doc-version-claims.test.ts (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus — no path-derived mandate; tier is this seat's call.
Clause-②: no — documentation wording plus a ledger entry deletion.
Serial constraints cleared: skills/objectui/guides/i18n.md has no in-flight claim. PR5371 (#5126) is awaiting maintainer merge on schema-expressions.md, data-integration.md and rules/protocol.md — different files, no conflict. #5342 this round is a different gate script.

The block is discharged — verified, not assumed

The card body still carries a stale PM status block reading pm:blocked / Blocked-by: #5084. That text is out of date; ignore it. Verified this round: PR5084 is closed/merged (2026-08-18), and its KNOWN_CLAIMS entry is on main at f2e11ae6f, scripts/__tests__/doc-version-claims.test.ts:791-796:

claim: '@objectstack/spec' + TICK + ' v4',
kind: 'stale',
why: '... Filed as objectui#5081 rather than repaired in #4981 ...
      When that card lands, this entry must go with it or the downward ratchet turns red.'

That is a hard requirement, in the ledger's own words: delete that entry in the same commit. The downward ratchet (no entry may outlive the claim it excuses) goes red otherwise. Leaving it is not a smaller change — it is a broken build.

Direction: delete the version qualifier

Both lines attribute the plain-string label rule to @objectstack/spec v4 while this repo declares ^17.0.0 in 33 places — thirteen majors. Write them as per @objectstack/spec / the spec uses plain strings only, with no version qualifier.

⛔ This is not me adjudicating the card's open A/B. It is the established repo pattern for this exact defect: PR3688 / PR3698 applied precisely this form across 36 READMEs and the CLI pages, #3708 repaired the identical architecture-overview.md fossil, and the ledger's own why describes the alternative as "a version qualifier that carries no information and can only rot." Following a settled convention is not a new ruling. If you believe the convention should not apply here, stop and report rather than choosing the other branch.

⚠️ The check that outranks the wording — roll-back clause applies

The sentences use a version number to back a rule: "per spec v4, labels are plain strings." Deleting the qualifier silently converts a claim about v4 into a claim about today's spec. So verify the rule itself is still true against the pinned @objectstack/spec@17.0.0 before you rewrite it.

If plain-string labels are not what spec 17 requires, then the defect is the rule, not the version number, and rewriting the qualifier would launder a false statement into a current one. In that case: stop, report, change nothing — the card returns to needs-user-decision and ⛔ you do not decide it. This is the exact family as #4611, where a comment claimed "In spec 17 I18nLabelSchema is z.ZodString" and was false against the installed build — it nearly made a seat implement a no-op.

Measure it against the installed @objectstack/spec dist, not against source or memory, and say which you read.

Verification

Run pnpm exec vitest run scripts/__tests__/doc-version-claims.test.ts from the repo root and show both ratchets green. Reverse-verify the ledger half specifically: put the KNOWN_CLAIMS entry back with the file fixed, and show the downward ratchet turns red — that proves the deletion was load-bearing rather than incidental.

Governed surface

skills/** is maintainer-merge-only. Open a draft PR, get it green, ⛔ do not enable auto-merge and do not merge, and say so in the PR body. It queues behind PR5371 for the maintainer's attention.

Changeset: empty frontmatter is likely right (docs + a test ledger, no package src/) — check check-changeset-presence and say why. ⛔ Never major.

Fixes #5081.

---

Generated by Claude Code