agents(os-dev): a declared narrowing that cites the affected set names the instrument's blind spot

[os-musk]

Fixes #16631

turbo ls --affected derives its set from the package dependency graph. A test that reads
another package's source off disk is not an edge in that graph, and the repo-root package
is not in the workspace list at all — so a dev report's narrowing sentence that cites the
affected set asserts a completeness the instrument does not have, and when it is wrong it is
wrong silently and green. This PR adds the standing rule that makes the sentence honest, in
the one file every dispatched dev reads in both repos.

The ruling this PR executes

No maintainer ruling exists on this card. The reporting seat's verdict, quoted from the card
body and untranslated:

D4 — the standing rule (recommended). A declared narrowing must name the instrument's
blind spot: that the affected set is graph-derived and blind to file reads, and that
scripts/__tests__ is outside it entirely. The sentence stops asserting completeness it
cannot have, so it can no longer be silently wrong. Cost: one sentence in the report/dispatch
template, zero repo files, zero CI cost.

D1/D3 (a declaration file, a mapping gate) are refused with the card's own reflexive evidence;
D2 stays opportunistic with no migration sweep; the 12 dependency-covered readers are not
recorded. The grading comment (5572475500) settles the landing: .claude/agents/os-dev.md,
fold-paid at 403/403, rules-only register, no issue numbers. The A/B placement question is the
maintainer's at the governed merge — proposed in the 速读 below, not decided here.

What was added

Two rule lines in the 「本地验证范围」 section, immediately after the block that defines what
makes a narrowing a measurement rather than a skip, and before the block on how to read a gate's
exit code:

- 收窄引 `turbo ls --affected` 须同句写明盲区:集出自包依赖图,盲于读盘取别包源码的测试。
- 仓根包不在 `turbo ls` 里,根级套件整个在图外;故只称「不在图上」,永不称「动不了」。

117 and 116 bytes — both inside the ratchet's 120-byte per-line cap, measured with
printf '%s' LINE | wc -c, not estimated.

Why this neighbourhood and not the other. The seat's grep named two candidates. L339–340
(「干净收尾」 rule 4) is about ending a turn: there, a narrowing is an escape hatch from the
lock queue, and the rule governs whether you may stop. L155–159 (「本地验证范围」) is where the
file already defines a narrowing's evidentiary shape — 「三件都在,收窄就是一次测量;缺一件,
它只是没跑」. The affected set is a second narrowing instrument of that same kind, so its required
disclosure belongs beside the first one's three evidences. Placing it after L163 rather than
after L159 keeps the eslint-union addendum (L160–163) unbroken instead of interleaving two
instruments.

Why it names no gate. pnpm check:cross-package-test-inputs exists in this repo and, in
AGENTS.md's own words, 「finds those tests by scanning source text, so it sees only the
spellings it knows」. objectui has no such gate at all. Neither added line mentions a gate, so
nothing here implies the hole is shut.

The fold — two lines added, two deleted, 403/403

Two lines were added, so two were folded. Both deletions are pure cross-reference restatements:
each said in short what the section it pointed at says in full.

Fold 1 — deleted verbatim from .claude/agents/os-dev.md:97 (資源紀律 rule 6):

   - 消融/变异脚本自带还原 trap(硬线在标准条款节的 ablation 条)。

clause	survives on origin/main at
「消融/变异脚本自带还原 trap」	.claude/agents/os-dev.md:262 — 「硬线:消融/变异脚本一律自带 trap '(restore)' EXIT INT TERM 还原。」 — states the same rule and additionally pins the trap's exact spelling and its three signals
「硬线在标准条款节的 ablation 条」 (the pointer, and the foreground-cap reason the rule was echoed inside rule 6)	.claude/agents/os-dev.md:263 — 「前台上限的 SIGTERM 可以正落在变异中途;没有 trap 的树保持变异态,之后每次测量都错。」 — the surviving hard line names 前台上限 itself, so the tie back to rule 6 is stated inside the destination, not lost with the pointer

Fold 2 — deleted verbatim from .claude/agents/os-dev.md:133 (本地验证范围, item ②):

- `packages/cli` 只欠 `unit` 层(见 Definition of done 的测试条)。

clause	survives on origin/main at
「packages/cli 只欠 unit 层」	.claude/agents/os-dev.md:269 — 「范围按本地验证范围节圈定;packages/cli 的卡本地只欠 unit 层,integration 层声明给 CI。」 — the same clause verbatim, plus what happens to the other tier
「(见 Definition of done 的测试条)」 (the pointer)	.claude/agents/os-dev.md:270–272 — the destination adds the run command (--project unit), the exceptions that pull integration back in locally, and the driver/kernel case; strictly more than the deleted line carried

Note on the quote above: the surviving line at :262 spells the trap's placeholder with
angle brackets; it is rendered here with round brackets because a short angle-bracket fragment
is eaten by GitHub's body sanitizer. The deleted lines are quoted byte-verbatim.

No untouched line was re-wrapped: the diff is exactly -2 / +2 and the widest line in the file
is unchanged at 120 bytes.

The five dispatched premises, each measured against the tree

#	premise	reading	verdict
1	os-dev.md is 403 lines on origin/main, pinned at 403, last touched e692515a4, and no line names the blind spot	git show origin/main:.claude/agents/os-dev.md | wc -l = 403; ratchet map row ['.claude/agents/os-dev.md', 403]; git log origin/main -1 --format=%h -- .claude/agents/os-dev.md = e692515a4; grep -n -E 'affected|narrow|收窄|turbo ls' over the file returns 10 hits, all of them the 收窄 rules at L102–103 / L155–159 / L339–340 and none naming turbo ls, --affected or the graph	holds
2a	does pnpm turbo ls list the root package here?	pnpm turbo ls in this worktree prints 80 packages (pnpm9); grep 'spec-monorepo' over that output exits 1 — @objectstack/spec-monorepo is absent, the same shape the card measured in objectui (46 packages, root absent)	holds — root is off-graph in BOTH repos
2a'	objectstack has no scripts/__tests__	git ls-tree -r --name-only origin/main -- scripts/ = 352 files, grep -c '__tests__' = 0; objectui's same read lists a populated scripts/__tests__/	holds — so the added line states the structural fact (root package absent from turbo ls ⇒ a root-level suite is entirely off-graph), which is true here and has bite there; it does not name scripts/__tests__
2b	pnpm check:cross-package-test-inputs exists here and sees only the spellings it knows; objectui has no such gate	this repo's package.json: check:cross-package-test-inputs = node scripts/check-cross-package-test-inputs.mjs --self-test && node scripts/check-cross-package-test-inputs.mjs; objectui's package.json scripts matching /cross-package|test-inputs/ = []	holds — neither added line names a gate
3	a fold candidate whose deletion breaks check:skill-frame-sync or check:pm-skill-id-lint is not a candidate	both green after the fold — ✓ check-skill-frame-sync: 2 copies of the decision frame are structurally isomorphic across 2 files; ✓ check-skill-id-lint: 26 file(s) clean (pattern /#[0-9]{3,}/g)	holds
4	objectui carries no .claude/agents/ ⇒ os-dev.md is the whole dev-contract surface for both repos	re-read myself after git -C /home/user/objectui fetch origin main: git ls-tree origin/main -- .claude/ lists exactly .claude/hooks, .claude/launch.json, .claude/settings.json, .claude/skills — no agents/	holds
5	this repo's AGENTS.md already carries a paragraph on the same blind spot	AGENTS.md L82–89 on origin/main, heading 「A test that reads outside its own package must be spelled so the gate can see it」; a grep for turbo ls|--affected over all 1068 lines returns exactly one hit, L86, inside that paragraph	holds — see the 速读 for what B would still add

Gates — derived, never hand-listed

Derived in the worktree at final HEAD 727794b5d with
node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack. Its stderr
names the repo and commit it answered for:

dispatch-gates: gate list derived from the tree of 'objectstack-ai/objectstack' at commit 727794b5d
  --repo 'objectstack-ai/objectstack' checked against this checkout's 'origin' remote — it holds.
dispatch-gates: change set derived from git — 1 path(s) vs merge base bc0ac1d1f of 'origin/main' and HEAD
  · .claude/agents/os-dev.md

Every command was run with its exit captured to a file before any pipe
(cmd > FILE 2>&1; ex=$?).

exit	command
0	node scripts/check-closing-keyword-parity.mjs
0	node scripts/check-closing-keyword-parity.mjs --self-test
0	node scripts/check-comment-mask-corpus.mjs
0	node scripts/pm/check-governed-queue-guard.mjs --self-test
0	pnpm --filter @objectstack/lint run check:doc-formula-expressions (first run exited 3 = PREREQUISITE NOT MET, not a measurement; prerequisite built under the lock, then re-run)
0	pnpm check:agent-model-declared
0	pnpm check:agent-test-spelling
0	pnpm check:doc-authoring
0	pnpm check:driver-memory-census
0	pnpm check:nul-bytes
0	pnpm check:pm-governed-merges
0	pnpm check:pm-skill-id-lint
0	pnpm check:pm-skill-ratchet
0	pnpm check:refd-timer-probe
0	pnpm check:skill-frame-sync
0	pnpm check:watch-hint-literal
3	node scripts/pm/check-governed-merges.mjs --test .claude/agents/os-dev.md — expected: 3 = GOVERNED

Reconciliation, quoted from the tool's own verdict line:

Run reconciliation — 16 derived, 16 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 16 derived famil(ies) accounted for — 16 run, 0 NOT-MEASURED.

Gate verdict lines that judge this diff, quoted as each gate printed them:

✓ check-skill-line-ratchet: .claude/agents/os-dev.md is 403 lines (ceiling 403; headroom 0).
✓ check-skill-line-ratchet: .claude/agents/os-dev.md: widest table row is 0 bytes (pin 0; headroom 0).
✓ check-skill-id-lint: 26 file(s) clean (pattern /#[0-9]{3,}/g).
✓ check-skill-frame-sync: 2 copies of the decision frame are structurally isomorphic across 2 files
check-nul-bytes: OK (scanned 8199 text file(s) -- 8199 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
✓ check-agent-model-declared: 1 agent definition(s) under .claude/agents/ all declare a model
  os-dev.md → opus

check-governed-merges --test, exit 3:

governed-surface predicate: 1 of 1 path(s) hit the register (5 surfaces, repo-agnostic).
  ⛔  GOVERNED — a human merge is the review record for this PR (#9495 regime).
      .claude/** ×1 — the agent instruction tree (skills, agents, hooks, settings)
        - .claude/agents/os-dev.md

The prerequisite build ran through the shared lock
(OS_VERIFY_LOCK_SLOT=issue-16631), which printed:
os-verify-lock: VERDICT command-exit 0 · held the lock 2s · waited 0s.

pnpm lint — a measured narrowing, with all three evidences

pnpm lint is eslint . --no-inline-config over the whole repo, a CI-owned run. It was
narrowed to the changed file, and the narrowing is a measurement, not a skip:

1. Population read from eslint's own config, not guessed. Every files: selector in
   eslint.config.mjs is a JS/TS extension glob — L971 **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs},
   L1015, L1054, L1103, L1172, L1212 **/*.{ts,tsx,mts,cts}, and L1238's
   COMMENT_SWALLOW_FILES (defined at L785 as ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}']). A
   grep for markdown|processor|**/*.md over the config exits 1 — no markdown plugin, no
   processor, no .md selector exists.
2. File count read from --format json. eslint .claude/agents/os-dev.md --no-inline-config --format json returned 1 result, 0 errors, 1 warning, and the single
   message is eslint's own "File ignored because no matching configuration was supplied."
   ⇒ 0 linted files in this diff, stated by the instrument rather than inferred.
3. Invariance over untouched files. Type-aware linting is not enabled anywhere: every
   config block's parserOptions is { ecmaVersion: 'latest', sourceType: 'module' } and
   nothing sets parserOptions.project or projectService. eslint.config.mjs L326–329 says
   so in its own words — 「this repo runs one eslint.config.mjs, which never enables
   type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY
   file, test or not」. With no cross-file type program, a markdown-only diff cannot move any
   verdict on any untouched file.

Merge-tree reading

Two readings, because main advanced between the first one and this PR's creation. Both are
recorded rather than the convenient one:

reading 1 — taken immediately before the PR was opened
  git fetch origin main && git merge-tree --write-tree --name-only origin/main HEAD
  exit:             0
  tree:             8539356db21654ecc77f73faa9c6844d119d7505
  conflicted paths: none (exit 0, tree oid only)
  origin/main:      bc0ac1d1f

reading 2 — same command, taken immediately after the PR was opened
  exit:             0
  tree:             fe5ca1e611f512adfb5a314190eba86c3e402def
  conflicted paths: none (exit 0, tree oid only)
  origin/main:      4fe00b80e

What the advance changed, measured rather than assumed. bc0ac1d1f..4fe00b80e is two
merges (PR #16597 and PR #16604). git diff --name-only over that range restricted to my
surface — .claude/agents/os-dev.md, scripts/pm/check-skill-line-ratchet.mjs,
scripts/pm/dispatch-gates.mjs, eslint.config.mjs — prints nothing, so every measurement
above still describes the tree it claims to, and the merge base of this branch and main is
still bc0ac1d1f. The range does touch package.json and .github/workflows/lint.yml, which
is where a new gate family would appear, so that was checked too rather than waved past:
comparing the two package.json script maps, exactly one family is new —
check:pm-widening-tells = node scripts/pm/check-widening-tells.mjs --self-test — and its own
workflow comment says it "has no whole-tree production run at all — its input is a DIFF
supplied by its caller, never a file in the tree". It grades the checker's fixtures, never this
diff. So the 16-family derivation above is still the complete list for these paths.

Serial constraints re-verified myself rather than recalled:
git log origin/main -1 --format=%h -- .claude/agents/os-dev.md = e692515a4; and across the
head of every open PR fetched locally, git diff --name-only origin/main...origin/BRANCH -- .claude/agents/os-dev.md produced no output for any of them — no open PR touches the path.
AGENTS.md (PR #16573), .claude/skills/pm-dispatch/** (PR #16597, PR #16625),
content/docs/releases/** and docs/adr/** are untouched by this diff.

验收备注

• noted, not filed: this repo's AGENTS.md L82–89 states the blind spot only for the
  escaping-read half, and only as a gate's rationale addressed to a test author; it never says
  the repo-root package is absent from the workspace list, so a root-level suite's total
  invisibility to the instrument is recorded nowhere in AGENTS.md. Not filed as a card
  because an omission is not a reproducible defect and the file is held by PR docs(ci, AGENTS.md): the merge queue runs the affected set, not the full package list — two stale sentences corrected #16573 anyway.
  承接者: the maintainer's A/B stroke on this very PR — if B is chosen, that paragraph is
  exactly where the missing half lands.
• noted, not filed: turbo ls reports 80 workspace packages here against the card's
  46 in objectui, so the objectui census's absolute counts do not transfer to this repo.
  No count from that census was reused in the added lines — only the structural facts, each
  re-measured here. 承接者:无.

维护者速读(草稿)

改了什么

.claude/agents/os-dev.md 加了两行规则、删了两行,文件仍是 403 行,棘轮 403/403 headroom 0。
新规则说:一句收窄若拿 turbo ls --affected 当理由,必须在同一句里写明这个工具的盲区 ——
集是从包依赖图推出来的,一个从磁盘上读别的包源码的测试根本不在图上;仓根包压根不在
turbo ls 的清单里,挂在根上的套件整个在图外。所以这句话最多只能声称「不在图上」,
永远不能声称「动不了」。删掉的两行都是纯指路重复句(各自指向的那一节把同一条规则说得更全),
每条子句在哪儿存活,上面的表里逐条给了 file:line。

为什么改

这不是补一个功能,是止住一句会静默说谎的话。CI 跑的是全农场,所以今天没有用户可见的缺陷 ——
坏的就是这句话本身:它断言了一个仪器没有的完整性,而它错的时候是绿着错的。
报告席在 objectui 上量到:73 个跨包读盘的测试是依赖图看不见的;最近 30 个已合并 PR 里有 5 个
拿受影响集当理由,5 个全都有落在集外的读盘测试。修法是一句话,不是一个门禁 ——
造一份手工声明文件或一个映射门禁(D1/D3)只会把同一个失效搬进一个会漂移的镜像里,
而卡片自身的反身证据(那次普查的机械查询迭代四次仍漏测三类)正说明那份镜像会同样不全、同样绿。

风险与代价(含回滚)

代价:两行规则文本,零仓库文件新增,零 CI 成本,棘轮不抬。风险很低但不是零 ——
新规则只约束报告的措辞,不改任何代码路径、不改任何门禁判定;它唯一能造成的伤害是让 dev
在报告里多写一句话。回滚就是 revert 这一个 commit:文件回到 403 行、两条被折的指路句原样回来,
没有生成物、没有基线、没有其它文件依赖它。折掉的两行是可独立还原的,因为它们的内容
在别处完整存活,revert 只会造成一次重复,不会造成缺失。

席位意见

(留空,待席位定稿)

你要做的

这张卡带着一个 A/B 放置问题,是您在这次受管合并时拍的:A = 只落在 agent 契约文件(本 PR 现在
的样子);B = 另外在 AGENTS.md 也写一段。我这边量到的读数供您判断:本仓 AGENTS.md L82–89
已经带了 B 的「事实」那一半 ——「a test whose reads escape its package is invisible to both
turbo ls --affected and the test task's input hashing」,而且全文 1068 行里 turbo ls 只出现
这一次;但它是写给测试作者看的门禁理由,B 还会补上三样它现在没有的:(一)这条报告措辞
规则本身(「不在图上」而非「动不了」);(二)仓根包不在工作区清单里这半个事实,AGENTS.md
一个字都没提;(三)覆盖面 ——AGENTS.md 约束每一个席位,os-dev.md 只约束被派发的 dev。
反过来说,普查是在 objectui 做的,那边既没有 check:cross-package-test-inputs 这个门禁,
AGENTS.md 也是另一个文件,所以只在本仓加 B 并不能覆盖到出问题的那个仓,而 os-dev.md
是两仓 dev 都读的同一份契约(objectui 的 .claude/ 下确实没有 agents/,我自己重读过)。
请回一个词:A(照现在合)或 B(我再补 AGENTS.md 那一段,另开一个 PR,因为该文件现在被
PR #16573 占着)。

[os-musk]

Body edited once after creation, to record a second merge-tree reading: main advanced from bc0ac1d1f to 4fe00b80e between the pre-open reading and the PR's creation, so both readings are now in the body along with a measurement of what that advance changed (nothing on this diff's surface; exactly one new gate family, and it is self-test-only).

Per AGENTS.md's edit rule the edited body was sent with no footer of its own, on the measured expectation that the platform appends its bare attribution block. It did not append one on this edit, so the attribution is recorded durably here instead of by re-sending the body.

---

Generated by Claude Code

[os-musk]

ACCEPT — flight L, PR #16656 at head 727794b5d (#16631, the D4 rule in .claude/agents/os-dev.md), contract-tier review on the seat's own readings, 2026-09-07T15:57Z.

Own readings (review worktree detached at 727794b5d, origin/main = 4fe00b80e, merge base bc0ac1d1f):

• Diff: one file, +2/−2, one commit; os-dev.md stays 403 lines; the two added lines measure 117 and 116 bytes, the file's widest line stays 120; no control bytes.
• Fold survivals read on origin/main: the deleted L97 (ablation trap pointer) is carried in full at L262–263 (「硬线:消融/变异脚本一律自带 trap … 还原。」 + the SIGTERM-mid-mutation reason); the deleted L133 (packages/cli unit-tier pointer) is carried in full at L269–272 (the same clause plus the run command and the exceptions). Neither deletion loses a clause.
• Gates re-run here: check:pm-skill-ratchet (os-dev.md is 403 lines (ceiling 403; headroom 0)), check:pm-skill-id-lint (26 files clean), check:skill-frame-sync (2 copies isomorphic), check:agent-model-declared (os-dev.md → opus), all exit 0; check-governed-merges.mjs --test .claude/agents/os-dev.md exit 3.
• git merge-tree --write-tree --name-only origin/main HEAD exit 0, tree fe5ca1e61, no conflicted path — the same tree the report's second reading names.
• Premises: the seat's own reads at 15:25Z–15:27Z (403/403, last touch e692515a4, no existing sentence on the blind spot, objectui without .claude/agents/, AGENTS.md L84–88's paragraph) all hold as the PR body re-measures them. The turbo ls root-absent reading (80 packages, @objectstack/spec-monorepo absent) is the dev's measurement, not re-run by the seat — carried as such.
• CI at 15:57Z: 35 of 37 check runs completed success/skipped; Lint & Repo Gates and Type Check · workspace in progress. Not a landing condition on this surface (human hand-merge is the review record).

Review checklist:

• ① Derived judgments: the placement after the eslint-union addendum (L163) rather than after L159 keeps one instrument's block unbroken — sound. Phrasing the root clause structurally (root package absent from turbo ls ⇒ a root-level suite is off-graph) instead of naming scripts/__tests__ is what makes one sentence true in both repos — sound, and it is exactly the measured fact. Neither line names a gate, so nothing implies the hole is closed — as briefed.
• ② semver: none — agent contract text, skip-changeset, nothing published moves.
• ③ Boundary flags: governed surface (.claude/**). Draft kept; not readied, not enqueued, no auto-merge; reviewers os-zhuang + hotlong requested and needs-user-decision set on the PR in this same wake. The dev's footer observation (an edited PR body sent without a footer came back with none) is the fourth measurement of the reading already on the ledger and is recorded on [finding] AGENTS.md's PR-body edit rule predicts a platform-appended bare footer — an MCP update_pull_request sent without a footer came back with NONE three times today; the sentence should state the channel dependence and the read-back, not a form #16633, the card that owns the AGENTS.md sentence. The AGENTS.md omission (root package absent from the workspace list is stated nowhere there) is the maintainer's B stroke — 承接者 named below.

Implemented-by: os-dev subagent a19443c4f4f247968 (container & tier as recorded on the claim 5572793008 on #16631)
Reviewed-by: domain:skills seat, session session_018dxq7YqsLDMeZDZ5AzsgJX, at CONTRACT_REVIEW_TIER (own get_session reading: session_context.model = last_served_model)

维护者速读

改了什么: dev 契约文件 .claude/agents/os-dev.md 加两行、删两行,仍是 403 行。新规则:报告里若拿「受影响包集」(turbo ls --affected)来解释为什么少跑了测试,必须在同一句写明这个工具的盲区——集合是从包依赖图推出来的,看不见「从磁盘读别的包源码」的测试,仓根包更是根本不在清单里——所以这种句子只能说「不在图上」,永远不能说「动不了」。删掉的两行是纯指路句,内容在文件别处完整存活(席位逐行核过)。

为什么改: 这句话今天在报告里是会静默说谎的:objectui 那边量到 73 个跨包读盘的测试在图上看不见,最近 30 个已合并 PR 里有 5 个拿受影响集当理由、5 个全都有集外的读盘测试。CI 跑全农场,所以没有线上缺陷;坏的是报告措辞本身。修法是一句规则,不加门禁(手工声明文件或映射门禁只会把同一个盲区搬进一个会漂移的镜像)。

风险与代价(含回滚): 两行文本,零 CI 成本,不动任何代码路径;最坏情况是 dev 报告多写半句。回滚 = revert 一个 commit。

席位意见: 复核通过,建议 A——只落在 os-dev.md:它是两仓 dev 都读的唯一一份契约(objectui 的 .claude/ 下没有 agents/,席位自己核过);本仓 AGENTS.md L82–89 已带了「读盘逃出本包的测试对 turbo ls --affected 不可见」这半个事实,只缺「仓根包不在清单里」那半句和报告措辞规则本身,而 AGENTS.md 现在被 devx PR #16573 占着。若你要 B,席位另立一张 AGENTS.md 卡排在 #16573 之后,不改本 PR。

你要做的: 认可 A 就直接手动合并本 PR(受管面,⛔ 不走队列、不挂 auto-merge);合并即关 #16631。A 还是 B?

---

Generated by Claude Code