docs(agents): name the shared container's one heavy-verify lock

[yinlianghui]

Fixes #8403

Every objectui agent that runs a heavy verification already serialises through the lock that lives in the sibling objectstack checkout — three worktrees were measured reaching for it by absolute path at the same time — but nothing in this repository's own documentation names it. This adds one bullet to AGENTS.md. ⛔ No script, ⛔ no objectui copy of the lock, ⛔ no rider on any code change: the diff is one inserted line in one file.

What changed

One line inserted into AGENTS.md, inside ### 多 agent 协作纪律(并行修改本仓库,务必遵守) (heading at line 244), at the end of the group of bullets about shared state that worktree isolation does not cover: stash stack → the four per-worktree ref namespaces → shared scratchpad → this one. It says exactly three things: the absolute path, when to reach for it (plus the --status caveat), and why this repository must not grow a copy.

⚠️ Placeholder spelling in this PR body

The bullet's usage example contains a command placeholder. In the file it is written as a normal angle-bracket placeholder, matching the section's existing style (../objectui-TASK, -b BRANCH in the worktree bullet). In this PR body the same placeholder is spelled COMMAND in capitals, because GitHub's body sanitizer deletes tag-shaped fragments even inside backticks and fenced blocks — see AGENTS.md → 「⚠️ GitHub 会改写你写进 issue/PR 正文的字节」, mitigation 1. That substitution is the only difference between the quote below and the bytes on disk.

The new bullet, in full (line 289)

• 重验证先经那把锁 —— 它住在兄弟检出 ../objectstack 里,本仓没有这个脚本。 任何重验证(全量 vitest run、计时测量、整仓 build 或整套 suite)开跑之前先经 /home/user/objectstack/scripts/pm/os-verify-lock.sh 串行化,写法 bash /home/user/objectstack/scripts/pm/os-verify-lock.sh -c 'COMMAND'。⛔ 绝不在本仓复制一份:被序列化的资源是容器,本仓和 ../objectstack 共用同一个 —— 两份 per-repo 的锁只会让一个 objectui agent 和一个 objectstack agent 同时跑重套件、而各自都以为自己持有锁,比不加锁更糟。⚠️ 而这把锁只排除其他已加锁的运行:--status 打印的持有者和队列里只有走了这个入口的那些运行,空队列不等于空箱 —— 一个没加锁就跑 turbo build 的 agent 对它完全不可见,却照样落进你的计时测量里。

Positioning evidence — the unchanged bullets on either side

line	first sentence
274 (unchanged, before)	临时文件所在的 scratchpad 目录跨会话共享 —— 提交信息与 PR 正文一律别落到那里。
289 (NEW)	重验证先经那把锁 —— 它住在兄弟检出 ../objectstack 里,本仓没有这个脚本。
290 (unchanged, after)	一个任务一个 feature 分支 + 一个 PR;绝不把任务改动直接提交到 main。

Measurements

git diff --stat origin/main      →  AGENTS.md | 1 +
                                    1 file changed, 1 insertion(+)
git diff -U0 origin/main | grep @@ →  @@ -288,0 +289 @@      (one pure-insertion hunk)
wc -l AGENTS.md                  →  559 (before)  →  560 (after)
grep -c os-verify-lock AGENTS.md →    0 (before)  →    1 (after)

The single hunk is at line 289. ⛔ Nothing between lines 165 and 200 is touched — that region is the vitest-invocation passage and objectui#8390's edit region, and the dispatch fenced it off.

Interface check — the flags quoted in the bullet are real

-c 'COMMAND' and --status are both taken from the script's own usage block (/home/user/objectstack/scripts/pm/os-verify-lock.sh, lines 4-9), not from memory. The --status caveat is the script's own printed text, verbatim from its status branch: It does NOT see unlocked … / An empty queue is NOT an idle box. — so the bullet documents behaviour the tool actually has.

⚠️ One premise in the card's Reproduce block is now falsified — the finding itself still stands

The card's Reproduce block asserts ls scripts/pm/ 2>/dev/null # objectui has no such directory, and triage (comment 5582284234) re-ran and confirmed it on 2026-09-08 09:04Z. That is no longer true. objectui now has scripts/pm/, containing exactly one file:

scripts/pm/check-half-states.mjs   added by 503cd8b (objectui#8612), 2026-09-08 16:38Z

— i.e. it landed after the card was filed and after triage verified its absence. The other two Reproduce checks still hold, and so does the finding:

check	reading now
ls /home/user/objectstack/scripts/pm/os-verify-lock.sh	present ✅
objectui has no scripts/pm/	⛔ falsified — the directory exists (one unrelated file)
objectui has no os-verify-lock.sh of its own	still true ✅ (git grep -ln 'os-verify-lock|flock' over origin/main = 0 hits repo-wide)
os-verify-lock in objectui AGENTS.md / CLAUDE.md	0 hits at 4857776c ✅ (control term guard-shared-stash = 1 hit in each, so the zero is a reading)

Consequence for this PR: one word. The bullet says 「本仓没有这个脚本」 (this repository does not have this script — true) rather than 「本仓没有 scripts/pm/」 (this repository has no scripts/pm/ — no longer true). The substantive premise the card rests on — that the one lock for this container lives in the sibling checkout and is named nowhere in objectui's own docs — is untouched.

Gates

Derived by hand from the root package.json and .github/workflows/ (objectui has no dispatch-gates.mjs; the objectstack one refuses to answer for a sister repo). Exit codes were captured by redirecting to a file first, never through a pipe.

gate	exit	verdict line
node scripts/check-governed-queue-guard.mjs --test AGENTS.md	3	⛔ GOVERNED — 1 of 1 path(s) are on a governed surface (expected; see below)
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	✅ check-shell-escape-residue: OK (5/5 root(s) resolved -- AGENTS.md: 1 file(s), 15 fence(s); …)

check-doc-links and check-shell-escape-residue are owed because both list AGENTS.md as a scanned input (a SCAN_ROOTS row and a file spec respectively). check-doc-fence-languages is not owed: its root-page set is ['README.md'] only. No package is touched, so there is no build closure and no package test suite in scope.

Governed-surface guard output, verbatim

⛔ 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 stays a draft. ⛔ Not flipped ready, ⛔ not enqueued, ⛔ no auto-merge armed, ⛔ no approving review left by this seat. A maintainer merge is the review record.

Overlap with the other in-flight AGENTS.md change: zero

objectui#8390 (branch claude/issue-8390-agents-app-shell-test-count, head 41833ad1) also edits AGENTS.md. Measured, not assumed:

its hunks : @@ -187 +187 @@   and  @@ -188,0 +189,5 @@
this hunk : @@ -288,0 +289 @@
git merge-tree --write-tree HEAD refs/…/flightI  →  exit 0, clean tree e2fe5a17

Different sections, ~100 lines apart, and the repository's only merge driver is scoped to pnpm-lock.yaml, so that exit 0 is a real content reading for AGENTS.md and not a driver deferring judgement. origin/main was re-read and merged at 4857776c (already up to date). Whichever of the two lands first, the other merges cleanly.

维护者速读(草稿)

改了什么 — objectui 根 AGENTS.md 的「多 agent 协作纪律」一节里加了一条 bullet(整个 PR 就这一行)。内容是:重验证(全量 vitest run、计时测量、整仓 build 或整套 suite)开跑前,先经兄弟检出 ../objectstack 里的那个锁脚本串行化;并写明 ⛔ 本仓绝不复制一份,以及这把锁只看得见「加了锁」的运行、空队列不等于空箱。⛔ 没动任何脚本、没动任何代码、没建任何新文件。

为什么改 — 这条约定已经是全体一致的做法,只是从来没写下来:实测有三个 objectui worktree 在同一时间按同一条绝对路径伸手去拿它,三个互不相干的任务、各自独立到达。不知道这条路径的 agent 只有两条坏路:要么不加锁跑重验证 —— 于是一个人的 turbo build 落进另一个人的计时测量里,产出一个错误读数;要么跳过重验证、报一个轻量的,这是更安静的失败。两条的代价都远高于一行散文,而且每来一个新 agent 就付一次。

风险与代价(含回滚) — 风险几乎为零:纯文档、+1 行、不改任何行为、不影响构建与发布(changeset 门禁自己判定「不欠 changeset」)。唯一的实质代价是这条 bullet 里的绝对路径绑定了当前容器的目录布局(/home/user/objectstack/...);布局若变,这一行需要跟着改 —— 但那正是文档而非脚本的好处:改一行,不改机制。回滚 = revert 这一个 commit,AGENTS.md 回到 559 行,不留任何残留。

席位意见 —

你要做的 — ① 看一眼这条 bullet 的措辞是否合你意(措辞由本席拟,卡本身明确不提议措辞,「写在哪」由 PM 席裁定为根 AGENTS.md);② 若同意,由你合并 —— 受管面 PR 按设计停在 draft 等人类合并,本席 ⛔ 不翻 ready、⛔ 不入队、⛔ 不留 approval;③ 顺带留意上面那段「前提被证伪」:卡的复现命令第二条(objectui 无 scripts/pm/)已经过时了,不影响本卡结论,但若你想让卡面保持准确,可以顺手更新卡的 Reproduce 段。

---

Generated by Claude Code

[yinlianghui]

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

改了什么 — objectui AGENTS.md「多 agent 协作纪律」一节的共享状态那组 bullet 末尾新增一条:重验证先经兄弟检出的 /home/user/objectstack/scripts/pm/os-verify-lock.sh 串行化,写法、--status 只见已加锁运行的告诫,以及为何本仓不复制一份(被序列化的是两仓共用的容器)。一文件 +1 行,559 → 560,无脚本、无副本。

为什么改 — 每个 objectui agent 跑重验证时都在按绝对路径去拿那把锁(同一时刻三个 worktree 独立到达同一路径),但本仓文档一个字都没提它;不知道的 agent 要么不加锁跑(落进别人的计时测量)、要么跳过重验证报一个轻的。约定已一致,写下来成本几乎为零。

风险与代价(含回滚) — 纯指令文本;回滚 = revert 本 PR。一条顺手更正:卡与分诊都写「objectui 无 scripts/pm/」,今天已不成立(昨天 #8612 加了 scripts/pm/check-half-states.mjs),bullet 措辞改为「本仓没有这个脚本」,实质前提不变。

席位意见 — 接受。本席在分支头上复核:第 289 行一条纯插入、os-verify-lock 0 → 1、控制字节 0、受管门 exit 3、CI 全绿;与 #8747(第 187–193 行)不相邻。

你要做的 — 合并;或由 os-zhuang / hotlong 批准,本席随即入队。看一处即可:第 289 行那条 bullet 的三件事是不是你要的口径(路径、何时用、为何不复制)。

---

Generated by Claude Code

[yinlianghui]

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

改了什么 — objectui AGENTS.md 「多 agent 协作纪律」一节的「worktree 隔离管不到的共享状态」那组 bullet(stash 栈、四个 ref 命名空间、共享 scratchpad)末尾,新增一条 bullet:重验证(全量 vitest、计时测量、整仓 build/suite)先经兄弟检出 /home/user/objectstack/scripts/pm/os-verify-lock.sh 串行化;--status 只看得见加了锁的运行,空队列不等于空箱;⛔ 本仓绝不复制一份——被序列化的是两仓共用的容器,两把 per-repo 锁会让两个 agent 同时跑重套件而各自以为持锁。一文件,+1 行(559→560)。

为什么改 — 每个 objectui agent 都在用这把锁(实测同一时刻三个 worktree 按绝对路径去取),但本仓文档一个字没提;不知道的 agent 要么不加锁跑重活(把别人的计时测量污染掉),要么跳过重验证报个轻的。分诊(5582284234)把卡上的三条「不提议」提为承接约束;「写在哪」本席裁为根 AGENTS.md 一句。

风险与代价(含回滚) — 纯文档;回滚 = revert 本 PR。零脚本、零复制。一处更正当众认:卡与分诊都说 objectui 没有 scripts/pm/,而 objectui#8612(2026-09-08)已加了 scripts/pm/check-half-states.mjs;bullet 写的是「本仓没有这个脚本」,是对的句子。

席位意见 — 接受。本席在分支头上复核:单一 hunk 在第 289 行,第 165–200 行(vitest 那段、objectui#8390 的区域)未动;os-verify-lock 0→1;控制字节 0;changeset 不欠;CI 26 绿 / 3 跳过,mergeable: clean。

你要做的 — 合并;或由 os-zhuang / hotlong 批准,本席随即入队。看一处即可:那条 bullet 里的绝对路径 /home/user/objectstack/... 是否就是你要写进仓库文档的形态(它是容器里的事实,不是仓库的约定)。

---

Generated by Claude Code