docs(agents): before editing a workflow file, derive its test readers with git grep and run them (objectui#9198)

[claude]

Fixes #9198

One line added to the workflows discipline in AGENTS.md. No collector, no gate, no script.

Governed surface — this PR is DRAFT and draft is its finished state

node scripts/check-governed-queue-guard.mjs --test AGENTS.md (exit 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).

It is not flipped ready, not enqueued, no auto-merge is armed, and no review is submitted from this side.

The specification — the director seat's class-one ruling, quoted

From comment 5651818810 on #9198, 2026-09-13. One substitution, made deliberately and flagged here
rather than silently: the ruling's placeholder is written with angle brackets, and this repository's
own rule on GitHub body rewrites (AGENTS.md, the section on GitHub rewriting body bytes, mitigation
one) says placeholders must be spelled as words because tag-shaped fragments are eaten on save —
backticks and fenced blocks do not protect them. The placeholder below is therefore spelled NAME.yml;
nothing else is changed.

One line in the dev-round guidance this repository's rounds read: before editing
.github/workflows/NAME.yml, git grep -l 'NAME.yml' -- '**/__tests__/**' '**/*.test.*' and run
every hit locally; a workflow edit that reddens an un-listed pin is a finding against the habit,
⛔ not against the round. The 22-reader structural blind spot (directory enumeration, shared
helpers, gate scripts walking the tree) is recorded on this card as the evidence a future collector
card would need, with the objectui#8953 sibling.

Its authority line is 「零拉动 ⇒ 荐不扩散」: ⛔ no collector, ⛔ no gate, ⛔ no script — the habit line only.

Premise readings

All three taken in the worktree at origin/main 541ce4e0 on 2026-09-14, between 10:09Z and 10:12Z.

P1 — where the workflows discipline lives, anchored by content, and the control that no such line
already exists. The section heading 「本仓到底跑不跑 X?」 is at :387; the two git cat-file -e probes
are at :390 and :391; the enumeration-versus-read paragraph and its for f in .github/workflows/*.yml
loop follow at :397 and :403. Control: git grep -n "__tests__" origin/main -- AGENTS.md returns
exactly two hits, at :221 and :457 — neither inside :383–:410, so nothing in that section named a test
reader before this change. Positive control on the same grep, so that a zero could have failed:
git grep -n "cat-file" origin/main -- AGENTS.md hits :390 and :391, inside the region. P1 holds.

P2 — the dev-round guidance this repository's rounds read is AGENTS.md. ls .claude/agents/ on
the tip: No such file or directory, exit 2. Enumerated from the same ref as the read rather than from
a working-tree glob, per this file's own enumeration rule: git ls-tree -r --name-only origin/main .claude/ returns 14 entries — four hook scripts and their four self-tests, launch.json,
settings.json, and two internal skills — and no agents/ path. os-dev.md does not exist anywhere
in the tree. P2 holds; the ruling's landing point resolves here.

P3 — the ruling's own control, re-run on the tip. git grep -l 'lint.yml' -- '**/__tests__/**' '**/*.test.*' returns 21 files, matching the card's reading at its own ref, and
scripts/__tests__/ci-cd-pipeline-doc.test.ts — the pin that actually went red on the round the card
was found in — is among them. Same command against the origin/main ref returns the same 21. That is
the whole basis for a habit rather than an instrument: the one measured incident is inside the search's
hits. The card's runtime collector was ⛔ not re-run; that instrument is exactly what the ruling declines
to build.

The line

Added at :397–:398 of AGENTS.md (net +3 including the blank separator; nothing moved or reflowed),
between the positive-control paragraph and the enumeration-versus-read subsection — where a reader is
standing when they are about to touch a workflow file:

**改 `.github/workflows/X.yml` 之前,先把读它的测试推导出来、别凭名字回忆:** `git grep -l 'X.yml' -- '**/__tests__/**' '**/*.test.*'`,命中逐个本地跑。
一次 workflow 编辑把一个没列出来的钉子弄红,是对这条习惯的发现,⛔ 不是对那一轮的发现;这条搜索两个方向都会错,它看不见的那半记在 objectui#9198 上,不在本条覆盖内。

The placeholder is spelled X.yml, which is how :390 directly above already spells it, so the reader
copies one convention rather than two. No count is written into the prose: the blind spot points at
#9198 instead of restating its numbers, which is Coding Standard #9 applied to the line itself.

Changeset

.changeset/issue-9198-workflow-test-readers-habit.md, empty frontmatter — the declared-once form for
a change that publishes nothing. node scripts/check-changeset-presence.mjs agrees it is not owed
(0 of them published source of a package the release covers); it is written anyway in the shape of
.changeset/issue-8875-cite-by-content-convention.md, the sibling AGENTS.md change. major is not
declared, so the 39-package fixed group is not moved.

Gates

The gate list was derived, not recalled — objectui has no dispatch-gates script. Sources: the root
package.json scripts; the workflow files that name AGENTS.md, enumerated git-side as
git grep -l 'AGENTS.md' -- '.github/workflows/*.yml' (11: changeset-guard, changeset-presence,
changeset-release, ci, control-bytes, dependabot-auto-merge, docs-links, governed-surface-guard,
hook-selftests, lint, shell-escape-residue); and the tests that read AGENTS.md, derived by the very
habit this PR adds — this is the habit applied to itself.

git grep -l 'AGENTS.md' -- '**/__tests__/**' '**/*.test.*' returns 371 files, and every one of
them was run: 20 under scripts/__tests__/ and the remaining 351 in a second invocation through the
shared verify lock. All exit codes captured before any pipe.

check	command	exit	evidence
governed surface	node scripts/check-governed-queue-guard.mjs --test AGENTS.md	3	quoted above — 3 is the GOVERNED verdict, the intended answer
governed self-test	pnpm check:governed-queue-guard	0	OK check-governed-queue-guard self-test: 185 cases pass
habit applied to itself, part 1	pnpm exec vitest run over the 20 scripts/__tests__ hits	0	Test Files 20 passed (20) · Tests 775 passed (775) · 25.83s
habit applied to itself, part 2	pnpm exec vitest run over the other 351 hits, under the verify lock	0	Test Files 351 passed (351) · Tests 6296 passed, 1 skipped (6297) · VERDICT command-exit 0 · held the lock 442s
control bytes	pnpm check:control-bytes	0	✅ check-control-bytes: OK (scanned 7658 tracked text file(s); skipped 85 binary)
lint	pnpm lint --concurrency=2, under the verify lock	0	Tasks: 47 successful, 47 total · VERDICT command-exit 0 · held the lock 182s; the 830 warnings are pre-existing no-explicit-any and 0 errors
type-check	pnpm type-check --concurrency=2, under the verify lock	0	Tasks: 81 successful, 81 total · VERDICT command-exit 0 · held the lock 435s
changeset presence	node scripts/check-changeset-presence.mjs	0	✅ No source or published contract of a released package changed in this range
changeset no-major	node scripts/check-changeset-no-major.mjs	0	✅ No changeset declares a major bump.
changeset claims	pnpm check:changeset-claims	0	report-only; 1 file(s) changed outside .changeset/ read against 1070 pending bodies, no finding raised against this diff
line citations	pnpm check:new-line-citations	0	VERDICT new-cross-file-line-citations: 0 new citation(s)
shell escape residue	pnpm check:shell-escape-residue	0	✅ OK (5/5 root(s) resolved -- AGENTS.md: 1 file(s), 15 fence(s) ...)
doc links	node scripts/check-doc-links.mjs	0	Links are valid across 17 scan roots.

Beyond the gate, the control-character scan was also run by hand over both changed files —
grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' returns exit 1 on each.

Acceptance notes

• Region. The diff is a pure 3-line insertion at :396–:398 of AGENTS.md; git diff --stat reports
  3 insertions and 0 deletions in that file. The two sibling region claims on the same file — finding: AGENTS.md forbids new URL(<相对路径>, import.meta.url) as fatal, and the tree carries 21 live instances of it inside the transform that sentence names — plus four comments asserting the hazard #9191 at
  :232–:239 and PR docs(agents): record the merge_group leg's SECOND refusal predicate (the contract-review carrier) #9466 at :519 — are untouched. If this lands second, origin/main gets merged in
  first.
• The habit applied to itself is a weaker instrument on a doc than on a workflow, and the numbers say
  so. For lint.yml the command returns 21 files. For AGENTS.md it returns 371, of which 342
  mention the filename only on comment lines (// AGENTS.md §测试纪律 and the like) and 9 more carry it
  inside a test name or an assertion message; 63 of the 351 non-scripts hits reference any node:fs
  read surface at all. That is the text-search false-positive direction the card measured, at a
  different magnitude, and it is why the line is scoped to .github/workflows files, whose names are
  distinctive, rather than to any path. Noted, not filed — this is an observation about the line's
  reach, not a defect in anything.
• Nothing in the diff can move an un-listed pin. Both changed files are Markdown; eslint's config in
  this repo matches only **/*.{ts,tsx} and **/*.tsx and registers no Markdown processor, and .md
  is not a tsc input — so lint and type-check were run in full anyway rather than relied on for
  coverage of this diff.
• No collector was built and no gate was added, per the ruling's authority line. The 22 readers the
  text search misses stay recorded on finding(test-infra): "which tests read this workflow file" is recalled by name, not derived — measured: 35 readers, name-recall found 6 #9198 as the evidence a future card would need; they are ⛔ not
  addressed here.

Clause-②: no

---

Generated by Claude Code

[claude]

Contract review

Served-tier: 9/9 CONTRACT_REVIEW_TIER
Head-sha: 14ea4a0d274ef026ffdeb1a7bc5efbb05feb28a7

In-seat record on a GOVERNED surface (objectui AGENTS.md, rules tier — one of the four pieces; the landing waits for an authorized approval under ruling C), domain:skills execution PM seat, 2026-09-14T10:40Z. Spelled from node scripts/pm/check-clause2-carriers.mjs --template on objectstack origin/main; the stamp control is the reviewing round's own count off the seat's transcript. The dev's os-dev-report is comment 5662673660 on objectui#9198; the judgments below are the seat's own reading of the diff and of the tree.

① Derived judgments

• One hunk, inside the claim, nothing else. AGENTS.md +3/−0 at :397–:399 on the head (a two-line paragraph and its blank separator between the positive-control paragraph and the 「枚举和读取」 subsection), inside the region claimed at :383–:410 on 541ce4e0; .changeset/issue-9198-workflow-test-readers-habit.md with empty frontmatter (no release). No script, no gate, no test, no config — the ruling's 「⛔ no collector」 is honoured in the file list.
• The line is the ruling's line. It states the habit (derive the readers with git grep -l 'X.yml' -- '**/__tests__/**' '**/*.test.*' before editing a workflow file, run every hit), the finding-against-the-habit clause, and its own limit (the search is wrong in both directions; the half it cannot see is recorded on objectui#9198). The placeholder is spelled X.yml as :390 spells it, in the section's Chinese register with the ⛔ marker where the ruling has one.
• The ruling's control, re-read by the seat. git grep -l 'lint.yml' -- '**/__tests__/**' '**/*.test.*' on 541ce4e0 reads 21 files and scripts/__tests__/ci-cd-pipeline-doc.test.ts — the pin that went red on the round the card was found in — is among them; no __tests__ mention existed inside :383–:410 before this change (control 0).
• Register and mechanics. The PR body's six angle brackets are blockquote markers, not placeholders; no model identifier; Clause-②: no on its own line; the changeset follows PR docs(agents): cite by content, not by line address (#8875 clause 1) #9301's no-release shape.
• Gates as reported. check-governed-queue-guard --test AGENTS.md exit 3 (governed, quoted); self-test 185; the 371 AGENTS.md-mentioning test files run in two invocations (775 + 6296 tests, all green, under the verify lock); lint (47 tasks) and type-check (81 tasks) in full under the lock; check:control-bytes, the changeset trio, check:new-line-citations, check:shell-escape-residue, check-doc-links all exit 0. CI on the head at the seat's read: 24 success, 3 skipped, 7 in progress — the landing step re-reads it green before anything moves.

② Semver level

None. AGENTS.md and a no-release changeset only.

③ Boundary flags

• Governed rules-layer surface: objectui AGENTS.md. Four-piece applied: ACCEPT on the card, draft kept, needs-user-decision on this PR, reviewers os-zhuang + hotlong requested. ⛔ This seat never approves; ⛔ no ready / enqueue / auto-merge before an authorized APPROVED review (os-zhuang / hotlong, latest-decisive, not dismissed); after one exists this seat lands per ruling C.
• Clause ②: no, judged the same. One guidance line that narrows a habit; nothing accepted or refused changes; no gate strength moves (the ruling declines a gate).
• Region-parallel on the same governed file: objectui PR docs(agents): the Vite rewrite claim does not reproduce anywhere (objectui#9191) #9486 (this seat, :232–:239) and PR docs(agents): record the merge_group leg's SECOND refusal predicate (the contract-review carrier) #9466 (another seat, :519) hold disjoint hunks; whichever lands second merges origin/main first and the seat re-issues its record on the merged head. mergeable_state read behind at review time (main advanced), which is that clause, not a conflict.
• Observed by the dev, not filed: the habit applied to a doc file is a weaker instrument than on a workflow (371 mentions of AGENTS.md in test files, 342 on comment lines), which is why the line is scoped to .github/workflows files. An observation about reach, not a defect.

Implemented-by: claude/issue-9198-agents-workflow-readers-habit
Reviewed-by: session_01DAcomhvR9kKizeYgg89Vo8

VERDICT: PASS

---

Generated by Claude Code

[claude]

维护者速读

这个 PR 往 objectui AGENTS.md 的 workflow 纪律段加一条习惯,共 3 行,不加工具、不加门禁。 起因是卡 #9198:有一轮改 lint.yml 前凭名字回忆了六个会读它的测试,漏了不按 workflow 命名的那一个,CI 红了一回。总监席已裁(5651818810):不建收集器,只写一句习惯 —— 改 .github/workflows/X.yml 之前先 git grep -l 'X.yml' -- '**/__tests__/**' '**/*.test.*' 把读它的测试推导出来、逐个本地跑;漏掉的钉子红了算这条习惯的发现,不算那一轮的。

dev 把这条习惯用在了它自己身上:改 AGENTS.md 前 grep 出 371 个提到它的测试文件,全跑了一遍(7071 例通过),lint 与 type-check 全量也是绿的。落点在 :397–:399,在 git cat-file -e 那两行探针的正下方,不碰别的段落。

为什么要你点:AGENTS.md 是受管面,按裁决 C 需要 os-zhuang 或 hotlong 一次 approve,之后由本席落地。它和 PR #9486 改的是同一文件的不同区域,后落地的那个先合一次 main。

要不要批准这条习惯行? 是 / 否。

---

Generated by Claude Code

[claude]

Landing under ruling C — domain:skills seat, 2026-09-14T10:47Z. An authorized APPROVED review exists: 5196688837 by os-zhuang (GOVERNED_APPROVERS), submitted 2026-09-14T10:45Z on the reviewed head 14ea4a0d274ef026ffdeb1a7bc5efbb05feb28a7, not dismissed. The review of record naming that head is 5662678528 (**VERDICT: PASS**); check-clause2-carriers --pair 9489 re-read exit 0 at 2026-09-14T10:46Z. The approver flipped the PR ready and armed auto-merge in the same minute (the platform stores the repo's merge method whatever is sent, objectstack#18127), so the seat leaves both as set, clears needs-user-decision in this act (the decision is made), and reads the landing by content on origin/main — the four test shards still running at this stamp gate the queue, not the seat. objectui PR #9486 holds a disjoint region of the same file and lands second; its dev merges origin/main first only if GitHub reports a conflict.

---

Generated by Claude Code