docs(agents): point AGENTS.md at the invocation guard pin test instead of counting its refusals (objectui#9505)

[os-try-charles]

Fixes #9505

AGENTS.md stated the invocation guard's refusal set as a count and enumerated exactly that many forms. The repair is a pointer at the instrument, ⛔ not a bigger number — per this file's own commandment #9, and matching what objectui#9504 already did inside the guard's own docstring header.

What the measurement actually found

The card's premise held, and the undercount is worse than the card assumed.

reading (merged tree 29f4c0582)	value
verdict codes evaluateVitestInvocation returns	4 — double-dash-args, package-cwd, missing-path-filter, subsumed-positional-filter
CONTROL — code: 'no-such-verdict' in the same file	0 hits, exit 1 ⇒ the reader could have found a mismatch
两条现在都会直接失败 in AGENTS.md before this branch	1
CONTROL — a nonsense token in AGENTS.md	0 hits, exit 1

⇒ the prose said 两条; the guard refuses four shapes. The card anticipated an undercount of one (objectui#7814's third refusal). It is an undercount of two — missing-path-filter was already outside the count before objectui#7814 existed. ⭐ That is the clearest possible argument for the pointer: a count in prose was wrong in a way nobody had noticed, and incrementing it to 三条 would have shipped a new false number.

Carriers of the refusal set found in AGENTS.md

I enumerated before editing, as the dispatch required. Three count/enumeration carriers, plus one boundary case:

1. The section heading — 怎么跑测试（有两种写法会静默假绿 —— 现已机械拦截）. A count, same defect, same section. Repaired (see deviation below).
2. 陷阱一 / 陷阱二 — an ordinal enumeration of exactly two. Left as narrative, and now explicitly flagged as non-exhaustive by the repaired sentence. The guard's own docstring likewise keeps its ## Trap 1/2/3 narratives; the count is what objectui#9504 removed, not the narratives.
3. The sentence the card names — 两条现在都会直接失败…. Repaired: it now names scripts/__tests__/vitest-invocation-guard.test.ts as the authority and states that the traps this section expands are not the whole set.
4. Boundary case — the 路径过滤零匹配也不再是绿的 bullet describes what is in fact the missing-path-filter verdict (its message reads vitest 调用被拒绝：路径过滤指向不存在的文件), attributing the non-zero exit to passWithNoTests alone. Not a count, so ⛔ not repaired here. Noted below.

Acceptance, item by item

1. No refusal count remains, and the paragraph points at the instrument. ✅ grep -c '两条现在都会直接失败' AGENTS.md ⇒ 0; grep -c '有两种写法会静默假绿' AGENTS.md ⇒ 0; grep -c 'scripts/__tests__/vitest-invocation-guard.test.ts' AGENTS.md ⇒ 2.
2. ⛔ No new number introduced. ✅ The replacement paragraph contains no numeral and no counting word for the refusal set; 上面的陷阱 replaces 两条.
3. The enumeration that remains matches the guard's verdicts on the merged tree, with a control. ✅ 陷阱一 = package-cwd (scripts/vitest-invocation-guard.mjs:451), 陷阱二 = double-dash-args (:432); control above returns zero, so the reader could have found a mismatch.
4. gates_weakened: NONE. ✅ Prose only. The pointer target is green and unchanged: pnpm exec vitest run scripts/__tests__/vitest-invocation-guard.test.ts ⇒ 1 file / 44 tests passed.

Declared deviation — one carrier beyond the named sentence

⚠️ The claim's file surface named the single sentence at/near :204. I also repaired carrier 1, the section heading, one line of the same paragraph-block, as a bounded in-place fix: same defect class, mechanical, the shape already pinned by the objectui#9504 precedent, no other claim holds the file (re-measured this fire: 0 of 10 open PRs touch AGENTS.md, 194 filenames examined; positive control scripts/pm/check-half-states.mjs ⇒ PR #9391, so the zero discriminates), and no new validation surface. ⭐ Leaving it would have shipped a file whose own section title still said 两种 — falsified by this PR's own body. ⛔ It is one word and trivially revertable if the seat disagrees.

Gates

command	exit
node scripts/check-governed-queue-guard.mjs --test AGENTS.md	3 — ⛔ GOVERNED — 1 of 1 path(s) are on a governed surface. That is the correct answer, ⛔ not a failure.
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-new-cross-file-line-citations.mjs	0 — VERDICT new-cross-file-line-citations: 0 new citation(s)
node scripts/check-doc-expression-carriage.mjs	0
node scripts/check-doc-fence-languages.mjs	0
node scripts/check-control-bytes.mjs	0 — scanned 7737 tracked text files
pnpm exec vitest run scripts/__tests__/vitest-invocation-guard.test.ts	0 — 1 file / 44 tests

⛔ No skip-changeset label: it is a phantom in this repo, and check-changeset-presence.mjs's own verdict line above is the authoritative "nothing owed" statement. ⛔ No labels were written at all.

Acceptance notes (out of scope, ⛔ not filed)

• noted, not filed: the 路径过滤零匹配 bullet attributes missing-path-filter's refusal to passWithNoTests alone. A missing/imprecise member, ⛔ not a copy-and-it-fails example ⇒ below the filing bar. 承接者: whoever next expands this section.
• noted, not filed: the section expands two of the guard's four verdicts; no narrative exists for missing-path-filter or subsumed-positional-filter. ⛔ Deliberately not added here — acceptance item 2 forbids a new number in this paragraph, and the repaired sentence now tells the reader the set is larger. 承接者: the seat, if it wants the doc expanded.
• noted, not filed: scripts/pm/dispatch-gates.mjs does ⛔ not exist in objectui (only scripts/pm/check-half-states.mjs does), though the claim comment quotes it against AGENTS.md. The tier conclusion is independently correct — AGENTS.md is governed but not on the 协议语义面 list — so this changes nothing here. 承接者: the PM seat's own tooling.

维护者速读（草稿）

改了什么 — AGENTS.md 的「怎么跑测试」一节里,把 vitest 调用守卫「拒绝哪几种写法」的计数换成了指向仪器的指针。动了两处、净增 3 行:小节标题里的「有两种写法」改成「有些写法」,以及正文那句「两条现在都会直接失败……」改成「上面的陷阱现在都会直接失败,它今天拒绝哪些形态不写在这里 —— 以 scripts/__tests__/vitest-invocation-guard.test.ts 为准」。⛔ 守卫本身、它拒绝什么、CI 跑什么,一个字节都没动。

为什么改 — 这是本文件自己的诫条 #9:散文里写下来的数字只在写的那一刻推导过一次,此后永不复核,而没有任何读者能把它和一条活的断言区分开。实测证明了这一点 —— 文件写着「两条」,守卫今天实际返回四个拒绝码。objectui#7814 加的那条只是第四个里的一个,另有一个(missing-path-filter)在那之前就已经落在计数之外,谁也没发现。⇒ 把「两条」改成「三条」会当场写下一个新的错数字。objectui#9504 在守卫自己的文件头里已经这么处理过同一个计数(换成指向 pin 测试的指针,而不是换成更大的数),本 PR 只是让 AGENTS.md 跟它一致。

风险与代价(含回滚) — 风险极低:纯散文,无代码、无门禁、无发布面改动,check-changeset-presence 自己判定「无 changeset 可欠」。⚠️ 已接受的代价有一个:读者现在必须多点开一个文件才能看到完整的拒绝清单,不能在 AGENTS.md 里一眼读完 —— 这正是诫条 #9 明确选择的那一边(可复核 > 就地可读)。⚠️ 另有一处越界:认领申报的文件面只点了正文那一句,我连小节标题那处同类计数一并修了(理由与证据见上方「Declared deviation」)。回滚成本 = 一次 git revert,或单独把标题那一个词改回去;⛔ 本 PR 不会自己落地 —— 受管面,draft,人工合并。

席位意见

（留空，待席位填写）

你要做的 — 读一眼上面那张「四个拒绝码 vs 文件写的两条」的表,确认你同意「指针优先于计数」这个方向,然后由维护者人工合并(⛔ 本 PR 永不翻 ready、不入队、不 auto-merge)。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_015h79niBMyoB1xcaQje3uiz

---

Generated by Claude Code

[os-try-charles]

⛔ Held out of the queue — Test (shard 1/4) is RED, and it is ⛔ NOT this PR's failure

domain:devx @ objectui seat, session_015h79niBMyoB1xcaQje3uiz, standby patrol, 2026-09-16T04:29Z.

⭐ Thank you for the approval (os-zhuang, 04:01:07Z) and the ready flip (04:01:11Z). With an authorized approval in hand this PR's landing becomes the seat's — 「批准在案后席位落地」 — but entry to the merge queue requires every check green, ⛔ not the required subset, so I am not enqueueing it yet. ⛔ auto-merge is not armed.

The failing check, and why it cannot be this diff

Check-run 104644181539, run 35048707762:

Error: Command failed: grep -rFn -I --exclude-dir node_modules ... -- /home/runner/work/objectui/objectui
grep: /home/runner/work/objectui/objectui/.vite-oracle-9408-yJYAFy: No such file or directory
 ❯ textFootprint scripts/check-i18n-dead-keys.mjs:670:14
 ❯ scripts/__tests__/check-i18n-dead-keys.test.ts:475:19

This PR's entire diff is AGENTS.md, +7/−4, prose. It touches no script, no test, no workflow. ⇒ it cannot create a temp directory, cannot change a grep, and cannot affect check-i18n-dead-keys.

Root cause, read on origin/main rather than guessed — two halves that race:

	reading
the producer	scripts/__tests__/vite-objectstack-spec-dist.test.ts:161 — fs.mkdtempSync(path.join(repoRoot, '.vite-oracle-9408-')) creates its temp dir in the repo root
the consumer	scripts/check-i18n-dead-keys.mjs:670 greps the repo root; its --exclude-dir list covers node_modules .git dist build coverage .next .turbo .changeset .objectui-tmp — ⭐ and not .vite-oracle-*

⇒ run concurrently, the directory is deleted between grep's walk and its stat, grep exits 2, and the i18n test goes red for a directory that belongs to a different test. ⚠️ The mechanism is deterministic; only the timing is not.

What I did about it, ⛔ rather than just re-running

• ⭐ Filed objectui#9591 — the race is a real shared-infrastructure defect and this lane's rule is 「谁发现 flake 谁修或立单，⛔ 不绕行」. It carries both halves, the verbatim failure, three sketched repair directions and dedup words. ⛔ I did not choose a direction; that is triage's call.
• Spent exactly ONE re-run on the failed job to confirm the first case (an error naming something the diff does not touch). ⛔ That re-run is now spent — a second failure of this check on this head is not a flake and will be treated as real.
• ⛔ No test was skipped, disabled or quarantined. ⛔ No empty commit, ⛔ no close-and-reopen.

Next, automatically

If the re-run comes back green I enqueue this PR and follow it to MERGED — your approval survives, since the predicate is 「授权账户 APPROVED 即算，⛔ 不卡 commit_id」.

⚠️ The PR is also behind (main has since taken #9581 and #9588). The merge queue rebuilds against main by itself, so ⛔ I am not pushing a merge commit onto an approved governed branch to fix that.

---

Generated by Claude Code