docs(AGENTS.md): re-take the trap-one app-shell test-file count with its instrument

[yinlianghui]

Fixes #8390

The trap-one passage in AGENTS.md (the wrong-cwd false-green lesson) cited app-shell as having 281 test files. That figure is the evidence the passage uses to teach why Test Files 22 passed (22) is the console's suite and not app-shell's — so a stale count weakens the lesson exactly where the reader is being asked to trust a count.

Triage's hard constraint (5582330894) is carried out verbatim: the two live readings are re-taken on the tree this PR edits, each is written with the instrument that produced it, and neither is collapsed into the other.

The two readings, re-taken on 4857776

Both commands run from the repo root, on the branch's base commit 4857776:

instrument	command	reading
find, two extensions under src/	find packages/app-shell/src -name '*.test.ts' -o -name '*.test.tsx' | wc -l	664
the runner's own collection	pnpm exec vitest list --filesOnly packages/app-shell/ | wc -l	664

Breakdown of the find reading: 210 .test.ts + 454 .test.tsx. Breakdown of the runner reading by project: 206 unit + 445 dom + 13 dom-heavy.

A control on the find spelling, because the card's spelling has no parentheses and -o binds loosely: find ... \( -name '*.test.ts' -o -name '*.test.tsx' \) -print also reads 664, so GNU find's implicit -print did apply to the whole expression and the unparenthesised spelling is not silently counting one extension.

Reported honestly: the card's divergence does NOT reproduce

The card recorded find 633 vs the runner 649 and asked that the gap be explained. On this tree the two instruments agree exactly — not approximately: the two file sets are byte-identical, comm -23 and comm -13 over the two sorted lists are both empty, and the runner lists 664 distinct paths with no file collected by two projects.

So the premise behind "explain why they differ" is falsified, and the fix does not invent a divergence to satisfy it. What the added note says instead is the true and more useful thing: why the two are not guaranteed to agree, and why they happen to today.

• find is rooted at packages/app-shell/src; the three projects' include globs walk packages/** and each carries an exclude.
• Today they coincide only because app-shell currently has zero test files outside src/: find packages/app-shell \( -name '*.test.ts' -o -name '*.test.tsx' \) -not -path 'packages/app-shell/src/*' returns nothing.

The likeliest reading of the card's own 633/649 gap is therefore not an instrument disagreement at all but two different tree states — its find was taken by the filing seat, its runner figure came from PR #8389's suite run. app-shell went 633 to 664 in a single day, which is the same magnitude as that gap. That is itself the lesson, so the note tells the reader to quote the commit along with the instrument.

The runner instrument: why vitest list --filesOnly, and its control

The dispatch permits a collect-only mode in place of a full suite run. vitest list --filesOnly is the runner's own collection pass — same config, same projects, same globs — with no test execution, so it is both cheaper and reproducible in seconds by a reader of the doc.

Its equivalence to the count in a real run's Test Files (N) line was measured, not assumed, on a small package under the shared verify lock:

--- LIST ---   pnpm exec vitest list --filesOnly packages/permissions/   -> 9 lines
--- RUN ---    pnpm exec vitest run packages/permissions/                -> Test Files  9 passed (9)

Both legs ran in one locked invocation; os-verify-lock: VERDICT command-exit 0.

The card's own grep lesson, re-measured

The card recorded a measurement error of its own: the first grep used 281 files, hit nothing, and read as "the claim does not reproduce" — the passage is Chinese and spells it 281 个. Both spellings, plus the lit control, before and after:

pattern	before (4857776)	after
grep -c "281 files" AGENTS.md	0	0
grep -c "281 个" AGENTS.md	1	0
grep -c "app-shell" AGENTS.md (lit control)	2	5

The before column reproduces the card's reading exactly: the ASCII spelling is a false zero in both states, and only the lit control distinguishes "the pattern is wrong" from "the claim is wrong".

The change

One number replaced, plus a four-line sub-bullet carrying both instruments and the caveat. The passage's mechanism argument is untouched.

Before:

  成功。于是跑的是 `@object-ui/console` 的 22 个文件、报 `Test Files 22 passed (22)`,而本包
  (app-shell 有 281 个)一个都没跑。**没有 "0 tests matched" 信号** —— 计数是 22 不是 0,
  `passWithNoTests` 根本不参与,按包级约定验证的 agent 会据此报「整包绿」。

After:

  成功。于是跑的是 `@object-ui/console` 的 22 个文件、报 `Test Files 22 passed (22)`,而本包
  (app-shell 有 664 个)一个都没跑。**没有 "0 tests matched" 信号** —— 计数是 22 不是 0,
  `passWithNoTests` 根本不参与,按包级约定验证的 agent 会据此报「整包绿」。
  - ⚠️ 那个 664 连**仪器**一起读、别照抄(objectui#8390:上一版写的 281 陈旧了 2.4 倍)。在
    `4857776` 上,`find packages/app-shell/src -name '*.test.ts' -o -name '*.test.tsx'` 与 runner
    自己的收集数 `pnpm exec vitest list --filesOnly packages/app-shell/` 同为 **664**,但**两者
    不保证相等** —— find 只看 `src/`,而三个 project 的 include 走 `packages/**` 且各带 `exclude`;
    今天相等,只因 app-shell 的测试文件恰好全在 `src/` 下。

Test Files 22 passed (22) is deliberately left alone. It is a quoted observation from the objectui#3378 incident — a record of what was seen then — not a present-tense claim about this tree, unlike (app-shell 有 281 个). Correcting it would falsify the record rather than refresh it.

Line budget: 188 to 193 lines in the region, net +5 for the file (6 insertions, 1 deletion). objectui has no line ratchet on AGENTS.md; line-neutral was the target and it is not met — the two instruments plus the reason cannot be stated in the one parenthesis the stale number occupied, and triage forbade collapsing them.

Governed surface — draft, human merge

node scripts/check-governed-queue-guard.mjs --test AGENTS.md exits 3:

⛔ GOVERNED — 1 of 1 path(s) are on a governed surface:
   AGENTS.md x1 — the repo-root agent instruction file
     - AGENTS.md

   One governed path governs the WHOLE pull request — proportion is not a question.
   ⛔ Do not flip it ready, enqueue it, or arm auto-merge. Park it as a DRAFT and leave the merge
      to the maintainer; a human merge IS the review record for a governed surface.
   The merge-queue run of "Governed Surface Queue Guard" refuses this diff unless an APPROVED review by an
   authorized approver (GOVERNED_APPROVERS: os-zhuang, hotlong) is on the pull request — on
   whichever commit it was left (maintainer ruling 2026-09-04).

This PR therefore stays draft: not flipped ready, not enqueued, no auto-merge, no approval left by this seat.

Gates run locally (exit code captured before any pipe)

gate	exit	verdict line
node scripts/check-control-bytes.mjs	0	check-control-bytes: OK (scanned 6955 tracked text file(s); skipped 85 binary).
node scripts/check-changeset-presence.mjs	0	No source or published contract of a released package changed in this range, so no changeset is owed.
node scripts/check-doc-links.mjs	0	Links are valid across 17 scan roots.
node scripts/check-shell-escape-residue.mjs	0	OK (5/5 root(s) resolved -- AGENTS.md: 1 file(s), 15 fence(s); ...)
node scripts/check-bash32-floor.mjs	0	13 tracked shell file(s) ... name no bash 4+ construct
node scripts/check-doc-fence-languages.mjs	0	every TypeScript block in 227 document(s) is fenced ts/tsx/typescript
node scripts/check-governed-queue-guard.mjs --self-test	0	132 cases pass
node scripts/check-governed-queue-guard.mjs --test AGENTS.md	3	GOVERNED (expected; quoted above)

Beyond the gates, a control-byte self-scan of the changed file: grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' AGENTS.md returns no match.

No build and no package test suite is owed. The diff touches one markdown file and no package: nothing to build a dependency closure for, no affected package to test. No test reads the repo-root AGENTS.md from disk — the two candidates that both mention it and read files are scripts/__tests__/site-next-agent-files-4160.test.ts (which is about the minted apps/site/AGENTS.md) and packages/plugin-grid/src/__tests__/guideCrudAppRenders.test.tsx (comment citation only). Repo-wide sweeps (pnpm lint, pnpm test, the lychee link workflow) are CI's run, not this seat's.

维护者速读(草稿)

改了什么 — AGENTS.md 里教「vitest 跑错目录会假绿」的那一段,把 app-shell 的测试文件数从陈旧的 281 换成今天实测的 664,并加了一条四行子项:两台仪器各自的命令与读数、以及它们为什么不保证相等。段落的机制论证一个字没动。

为什么改 — 那个数字不是装饰,它是这段课文用来证明「Test Files 22 passed (22) 是别人的包」的证据本身。数字陈旧 2.4 倍,恰好陈旧在读者被要求信任一个计数的地方。分诊的硬约束是:两个活读数都要写出来、都要带仪器名,不许挑一个了事。

风险与代价(含回滚) — 风险很低:改的是文档散文,无运行期影响,无契约变动,changeset 门禁判定不欠(没有已发布内容移动)。代价是文件净增 5 行 —— 两台仪器加一句原因,塞不进原来那一个括号里。回滚就是 revert 这一个提交,单文件、无依赖。⚠️ 一件要请您留意的事:卡上说两个仪器读数不同(633 对 649),在本树上复现不出来 —— 两者精确相等,连文件集合都逐一相同。所以本 PR 没有编造一个不存在的分歧,改为写「它们为何不保证相等、以及今天为什么恰好相等」;卡上那 16 的差,最可能是两个读数取自不同的树状态(app-shell 一天之内从 633 涨到 664)。

席位意见 —

你要做的 — 这是受治理面(AGENTS.md),按设计停在 draft 等您:本席没有翻 ready、没有入队、没有挂 auto-merge、没有留 approval。请您确认两点后人工合并即可 —— ① 664 这个数写进文档合不合适(它每周都在涨,子项已经明写了「连仪器和 commit 一起引、别照抄」);② 净增 5 行是否接受,若要压回 1 行,唯一的办法是放弃「两个仪器都写出来」,那与分诊的硬约束冲突,需要您裁。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01HxLw5aKDPR5RJgyUR7Exkd

---

Generated by Claude Code

[yinlianghui]

维护者速读 — PR #8747(objectui#8390,skills 席终稿,2026-09-09T03:22Z)

改了什么 — AGENTS.md 陷阱一那段里的证据数:「app-shell 有 281 个」测试文件改为 664,并加一条五行子弹,把两个仪器(find 两扩展名计数、runner 自己的 vitest list --filesOnly 收集数)与取数 commit 一起写出,说明两者为何不保证相等、今天为何恰好相等。机制论证一字不动;引用的历史读数 Test Files 22 passed (22) 保留为事故记录。一文件 +6/−1,559 → 564 行。

为什么改 — 这段教的是「计数是 22 不是 0,所以没有 0 tests matched 信号」,证据数陈旧 2.4 倍会在读者最需要信任计数的地方削弱它。分诊裁了硬约束:不得把 281 改成某一个数了事,两个读数都要写。dev 实测后发现卡上的 633 vs 649 分歧在今天的树上不复现(两套集合完全相同),照实报告而非造一个分歧出来;子弹改为讲清「为何可能不同」。

风险与代价(含回滚) — 纯指令文本,无行为;回滚 = revert 本 PR。代价:+5 行(objectui 的 AGENTS.md 无行数棘轮),且这个数天然会再陈旧 —— 子弹里钉了 commit 与仪器,让陈旧可见而不是隐形。

席位意见 — 接受。本席在分支头上复核:第 187 行与子弹如上;281 个 0 命中;控制字节 0;受管门 exit 3;CI 全绿;与同文件另一张 PR(#8751,第 289 行)区域不相邻、merge-tree 干净。

你要做的 — 合并;或由 os-zhuang / hotlong 批准,本席随即入队。看一处即可:那条五行子弹是否值 +5 行 —— 若你只要一个数,删掉子弹即回到 +0,但那就是分诊所禁的写法。

---

Generated by Claude Code

[yinlianghui]

维护者速读 — objectui PR #8747(objectui#8390,skills 席终稿,2026-09-09T06:29Z)

改了什么 — AGENTS.md 「陷阱一」那段拿 app-shell 的测试文件数当证据,原来写 281;今天两种仪器(find 数 src/ 下两种扩展名;runner 自己的收集 vitest list --filesOnly)都读到 664,而且文件集合完全一致。把数字换成 664,并加一条 5 行的子项:两种仪器各自的命令、读数所在的 commit、以及两者为何不保证相等(find 只看 src/,三个 project 的 include 走 packages/** 且各带 exclude;今天相等只因 app-shell 的测试全在 src/ 下)。一文件,+6/−1,行数 559→564。

为什么改 — 这段教的正是「计数是 22 不是 0 所以看不出跑错了包」,而它拿来对比的 281 已经陈旧 2.4 倍,读者被要求信任一个错的数。分诊硬约束(5582330894):⛔ 不得把 281 改成某一个数了事,两种仪器都要写出来并说明为何不同。卡上记的 633 vs 649 分歧在今天这棵树上没有复现——dev 如实报告,没有为迎合措辞编造一个分歧,改为说明两者何时会不同。

风险与代价(含回滚) — 纯文档;回滚 = revert 本 PR。代价:+5 行(objectui 的 AGENTS.md 没有行数棘轮,line-neutral 是目标不是门);数字本身易过期——子项让读者连仪器和 commit 一起读,而不是照抄。

席位意见 — 接受。本席在分支头上复核:第 187 行 281→664,281 个 命中 0、对照词 5;控制字节 0;changeset 不欠;CI 26 绿 / 3 跳过,mergeable: clean;与同文件另一张卡(objectui#8403,PR #8751,第 289 行)的合并树干净。

你要做的 — 合并;或由 os-zhuang / hotlong 批准,本席随即入队。看一处即可:那 5 行子项是否值得占 AGENTS.md 的篇幅——若你只要一个数,删掉子项、保留 664 即可(那样就回到「只写一个数」,与分诊约束相悖,但那是你的裁量)。

---

Generated by Claude Code

[os-zhuang]

技能中写这种数值完全没有意义呀，建议关闭