docs(agents): a "verified" claim points at the instrument, never at its answer

[claude]

Fixes #7833

Director seat ruling, summon #20, decision batch #108 item 5, route A: objectui's AGENTS.md gains one rule — a claim that something was verified is only as good as the check that re-verifies it on every commit — stated in the shape the repo has converged on three times: when declaring something verified, point at the instrument (the script or test that re-derives it), never write the number or the assertion itself.

⚠️ The maintainer finalises the wording. This PR lands a draft of it. See the 「维护者速读」 comment below for the options in letter form.

What landed

One bullet, #9, at the end of section 5 「Coding Standards (the Commandments)」, plus a changeset. That is the whole diff.

#9 — A "verified" claim is only as good as the check that re-verifies it (objectui#7833). Prose that declares something checked, counted, aligned or covered — in a doc, a code comment, a script or workflow header, or this file — states a fact that was derived once, when it was written, and is derived never again; no later reading can tell such an assertion from a live one. So when you declare something verified, point at the instrument that re-derives it — the script, the gate, the test — and never write down its answer: "the count this gate prints", not the count; "the list this script enumerates", not the list. A figure that is still correct is the dangerous case, not the safe one — a reader who spot-checks it confirms it and is still wrong once the population it described has moved out from under it. Where nothing re-derives the claim, say that in the text rather than let it read as live. This file is not exempt: it has carried such a claim and needed a repair (objectui#7800). The measured instances behind this rule sit on objectui#7833 — pointed at, not copied here, which is this rule applied to itself.

⭐ The rule carries no figure of its own — deliberately

A rule that says "never write the number" and then writes one is an instance of the defect it names, landing in the most-read file in the repo. So the text names no count of anything. The evidence is reached the way the rule prescribes: by address, not by copy — objectui#7833 carries the measured instances, and a card number is an address, not a measurement. Reproducing the list here in the file would have restarted exactly the clock the rule is about.

Checked against the narrow pattern the objectui#7448 twins pin (a numeral qualifying a document-population noun): the bullet contains no numeral at all outside the issue references, which that pattern excludes by construction.

Why section 5, in English, and not section 9

Placement decided the language, not the other way round.

• The artefacts the rule governs — docs, code comments, script and workflow headers — are precisely the ones commandment #-1 enumerates when it says the codebase is English-only: "code comments, docs (README.md, docs/*.md)". The parenthetical that grants Chinese is scoped to "operational sections" of this instruction file; section 5 is not one of them.
• Section 5 is the repo's list of standards for what you write, and it already carries a documentation commandment (#2) and a principle-plus-shape commandment (#0.1, contract-first). This rule is the same species: a principle and a fixed shape, no mechanism, no process, no checklist.
• Section 9 is operational discipline for driving the tooling in this repo. It is the richest neighbourhood for the idea — it already holds 「没跑对照的空结果不是一次读数」 and 「每次发布后回读」, which are the read-time half of the same principle — but the rule being landed here is the write-time half, and it must reach contributors who never open those subsections.

The alternative placement is a real one and the maintainer can take it; it is option B in the 速读 below.

The evidence — measured, not asserted

The five instances the card measured this round:

instance	the claim	how it went false
objectui#7505	a doc fragment marked "checked against the shipped dist/index.d.ts"	the gate structurally cannot compile a declared fragment, so nothing ever re-checked it — false twice
objectui#7528	"one total over 52 chunks" in present-tense prose	three counts in play at once: the prose, the file's own frozen baseline, and the gate's live output
objectui#7362	a fix list enumerated by name	entries expired as they were fixed; nothing re-derived the list
objectui#7433	a population count	rotted three times
objectui#7448	184 pages (144 .mdx + 40 .md)	a precisely correct count of the population the gate had stopped having — a reader who spot-checked it would have confirmed it and still been wrong about the scan surface

⭐ The sixth, verified on this tree before citing it, and the strongest one available: it is in AGENTS.md itself. objectui#7800's defect was the 「怎么跑测试」 section asserting that the package-level test form reaches 「和 CI 同一个结论」. That was true when written — a claim about what objectui#3240 had just changed — and nothing re-derived it, so it went false while continuing to read as live. Its repair is already in main and in this branch's base; it narrows the claim to what measurement supports ("同一份配置不等于同一个结论") and adds the corrective writer-side rule. It is the file arguing about itself.

⭐ And a seventh, which landed on main after the card was written — objectui#9076, which is the commit this branch is cut from. Same shape: a gate header restated a ceiling and a baseline as literals, an authorised re-baseline moved the constants, the prose stayed, and for days nothing went red "because nothing fails on a number written in a comment". Its fix is this rule's prescribed shape, arrived at independently again: the header now names its subjects and renders neither, and the gate's verdict line prints the live reading on every run. The rule is describing something the repo is still paying for.

Verification

• node scripts/check-changeset-presence.mjs — exit 0. Printed: "Compared the working tree with 3984bab (merge-base with origin/main): 1 file(s) changed, 0 of them published source of a package the release covers, 0 of them a manifest whose published contract moved, 0 under a package changesets ignores, 1 changeset(s) added." then "✅ No source or published contract of a released package changed in this range, so no changeset is owed." The changeset is present anyway, with empty frontmatter — this repo's explicit no-release declaration.
• check-control-bytes, check-new-cross-file-line-citations, check-doc-links, check-doc-fence-languages, check-bash32-floor, check-governed-queue-guard --self-test, check-changeset-fixed, check-changeset-no-major — all exit 0, each read from its own verdict line rather than from a shell status.
• The six test files that read AGENTS.md as a corpus rather than mentioning it in a comment — the component-node vocabulary pin, the doc version-claims census, the site agent-files pin, and the doc-links, changeset-presence and governed-queue-guard suites — 6 passed (6), 230 passed (230).
• check-governed-queue-guard --test AGENTS.md classifies this diff GOVERNED, one of one path, and states the terminal shape: park as a draft, human merge.

⛔ Governed surface — this PR stops at draft

AGENTS.md is the first row on this repo's governed-surface list. ⛔ Not flipped ready, ⛔ not enqueued, ⛔ no auto-merge, ⛔ no approving review from this seat. A human merge is the review record. ⚠️ The Governed Surface Queue Guard's pull_request leg exits 0 on purpose — a governed PR sitting in draft is its healthy terminal state, and green there is not a clearance to proceed.

The contract-review-tier review the ruling originally asked for was lifted on the card by the skills seat, on a maintainer ruling; the lane seat's default-tier review plus the gates is the review of record.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

---

Generated by Claude Code

[claude]

维护者速读

事情:把「一个『已验证』的说法,只和那个每次提交都重新验证它的检查一样可靠」这条规则写进 objectui 的根 AGENTS.md。总监席已裁 A(要写),本 PR 只是起草措辞,定稿是您的。整个 diff 就是一条 bullet 加一个空 frontmatter 的 changeset,没有别的。

规则落在哪、说了什么:section 5「Coding Standards」末尾,新的 #9,英文。核心一句:声明某件事已验证时,指向那件重新推导它的仪器(脚本 / 门禁 / 测试),永不把仪器的答案抄进正文 ——「这道门禁打印的那个数」,不是那个数;「这个脚本枚举的那份清单」,不是那份清单。再加一句最要紧的:一个今天仍然正确的数字是危险的那种情况,不是安全的那种 —— 抽查会确认它,而它描述的那个总体已经不在了(这就是 #7448)。

⭐ 它对自己也守这条规则:规则正文里没有任何数字 —— 没有「五个实例」,没有任何计数。证据靠地址够着:卡号 objectui#7833 上有那张实测表。抄一份清单进 AGENTS.md,正好是重启这条规则要治的那个钟。

⭐ 一个您可能会关心的事实:这条规则最强的一个实例就在 AGENTS.md 自己里 —— objectui#7800 的缺陷,「和 CI 同一个结论」写下时为真、没有任何东西重新推导它、于是它一边失效一边读起来仍然像活的。而本分支切出的那个 commit(objectui#9076)又是同一形状的下一个,是卡片写完之后才落地的。这条规则描述的东西,仓库仍然在为它付账。

您要做的 —— 回一个字母

• A(本 PR 现在的样子,推荐):留在 section 5,作为 commandment #9,英文。理由:#-1 把英文范围划成「代码、注释、文档」,而这条规则治的正是这些产物;#-1 只把中文许可给了本文件的操作性小节,section 5 不是。它是一条写作标准,和 #2(docs-driven)、#0.1(contract-first,同样是「原则 + 形状」)同族。
• B:改放 section 9,中文小节。这是唯一真正有力的反对意见:section 9 已经装着同一条原则的读取侧一半(「没跑对照的空结果不是一次读数」「每次发布后回读」),而 objectui#7800 的修复也是落在那里的。取 B 的代价:不读那几节操作规则的贡献者看不到它,而这条规则治的是写作侧。
• C:措辞更短 —— 只留原则加那两个「写 X,不写 Y」的例子,砍掉自指那两句和「今天仍然正确的数字才危险」那句。代价:砍掉的正是 finding(gate): two doc-gate workflow headers carry hand-copied document counts that have drifted from what the gates report #7448 的教训,而没有它,读者得出的结论会是「那就把数字保持准确」——这个回应在本仓已经失败过好几次。
• D:您直接在 PR 上改字。本 PR 是 draft,maintainer_can_modify 开着。

⛔ 本 PR 不会被任何 agent 合并:AGENTS.md 是受管面,它停在 draft,人类合并就是它的复审记录。已请 os-zhuang / hotlong 复审。⚠️ Governed Surface Queue Guard 的 pull_request 那条腿是故意退出 0 的 —— 绿不代表可以往前走。

domain:devx @ objectui dev 席位的默认档措辞复审在卡片上(objectui#7833),⛔ 不是批准。

---

Generated by Claude Code