agents(os-dev): the verify-lock waiting discipline as protocol, and the finding admission threshold

[claude]

Fixes #16262
Fixes #16351

Governed surface (.claude/**): draft PR, human merge. This is the LAST half of #16351 — its SKILL.md / core-rules.md / AGENTS.md half rides flight I's PR as Refs.

One file, .claude/agents/os-dev.md, line-neutral at 403/403: every added line is paid by a fold inside the same numbered rule block, every line is at or under 120 bytes (LC_ALL=C awk, measured max 120 — the file already carried four 120-byte lines), and the diff stays in the rules-only register (no dates, quotations, issue numbers, narrative or model names).

What lands

Rules 1 and 7 — the verify-lock waiting discipline as protocol (the maintainer ruling on #14944, Q3 A). One foreground call takes the full wait budget and stays blocked until the lock is granted or the call returns 99; never poll-and-retry; OS_VERIFY_LOCK_SLOT is always set before the first attempt. A 99 is read as NOT MEASURED and the interval goes to lock-free work; a re-acquisition RESUMES the parked place under the same slot name (再取以同名续位,⛔ 不从队尾重排) — the ruling's fourth part — and is not a re-entry from the tail. The dispatch brief's gloss "no re-entering the queue on a 99" is carried as that distinction: the tail re-entry is forbidden, the same-slot resume is the sanctioned continuation.

Rule 3 — the finding admission threshold (#16351, maintainer-directed). The two sentences 「顺路撞见的无关缺陷立成新的无 assignee issue」 and 「观察类发现(死代码、未演练漂移、外观抛光)打 finding 标签,⛔ 不打 pm:queue」 become the threshold: exactly three classes file a card — (a) a reproducible defect (repro or failing probe named), (b) a violation of a declared contract (the contract text cited), (c) a trap that leads an AI authoring metadata to write what the runtime refuses or silently drops. Everything else (observations, dead code, drift not yet exercised, polish, style, doc nits, naming) is not a card: it goes under a ## 验收备注 section of the PR body and into the report's out_of_scope_findings as noted, not filed: …, read by the seat at ACCEPT. The dedup / channel / 归挂 lines stay for the cards that ARE filed. The report-shape example at the end of the file gains the second spelling in place.

改前 → 改后 (every touched line, with the fold that paid for it)

where	改前	改后	paid by
rule 3 header (L41)	顺路撞见的无关缺陷立成新的无 assignee issue。	顺路发现 ⛔ 不在本 PR 修,只有三类立卡且不打标签:	rewrite in place; carries the old L42 「⛔ 永不在本 PR 里修它」 and the old L58 「不打标签」
rule 3 L42 (new)	列进 out_of_scope_findings;⛔ 永不在本 PR 里修它。	(a) 可复现缺陷(复现或失败探针具名);(b) 违背已声明契约(引契约原文);	the old L42's two clauses moved to L41 and L45
rule 3 L43 (new)	—	(c) 让 AI 写出运行时拒收或静默丢弃的元数据的陷阱;三类内 ⛔ 不因看着小揣着不报。	old L57 deleted whole (observation-class cards no longer exist)
rule 3 L44 (new)	—	其余 ⛔ 不立卡:观察、死代码、未演练漂移、抛光、风格、文档 nit、命名。	old L58 deleted: 「具体缺陷」 qualifier, 「留给 PM 分诊」, 「平实立单」, 「分诊轮定级」 — superseded by the evidence requirement in (a)–(c); its 「⛔ 不因看着小揣着不报」 survives on L43
rule 3 L45 (new)	—	它们进 PR ## 验收备注,报告 out_of_scope_findings 记 noted, not filed: …,席位 ACCEPT 时读。	old L52+L53 folded into one line, deleting the restated rationale 「发现永不因通道断而消失」 (the 「立不成 ⇒ 写进报告交 PM 代立」 half already says it)
rule 3 L55	立不成 ⇒ 发现连同缘由写进报告交 PM 代立。 + ⛔ 不查重硬立与静默弃报同为禁形:发现永不因通道断而消失。	立不成 ⇒ 发现连同缘由写进报告交 PM 代立;⛔ 不查重硬立与静默弃报同为禁形。	the fold above
rule 1 L76	入口点保证:等待预算钉死在一次前台调用内;按到达序授予;99 专指没排到;报持锁时长。	一次前台调用领全部等待预算,阻塞到拿锁或 99;⛔ 不轮询重试,恒设 OS_VERIFY_LOCK_SLOT。	in place: 「等待预算钉死在一次前台调用内」 is the same fact as the new protocol sentence; 「报持锁时长」 (the wrapper's own self-report) deleted; 「按到达序授予」 moves to L79, 「99 专指没排到」 to rule 7
rule 1 L79	…;排队是常态,不是挂死。	…;按到达序授予,排队是常态,不是挂死。	in place (120 bytes)
rule 7 L95	循环:拿到 99 就把间隔花在无锁工作上(测试、changeset、PR 正文、包内 typecheck)。	99 专指没排到,读作 NOT MEASURED;把间隔花在无锁工作上(写测试、changeset、PR 正文)。	in place: the 「循环」 framing (reads as poll-and-retry) and the 「包内 typecheck」 example deleted; 「测试」 restored to 「写测试」 (lock-free work is writing tests, running them takes the lock)
rule 7 L96	然后带同名再跑一次:OS_VERIFY_LOCK_SLOT=SLOT_NAME 在第一次尝试之前就设好。	再取以同名续位,⛔ 不从队尾重排:OS_VERIFY_LOCK_SLOT=SLOT_NAME 在第一次尝试前就设好。	in place: 「然后…再跑一次」 (a retry) becomes a resume; 「之」 dropped for width
report example L374	["filed as #N: one-line description"]	["filed as #N: one-line description", "noted, not filed: one-line observation"]	in place

(In this table the slot placeholder and the issue placeholder are spelled SLOT_NAME and #N; the file keeps its angle-bracket spellings — the GitHub sanitizer eats angle-bracket fragments in bodies.)

Untouched, as ruled: the PR-state line (L38), the ratchet block and the clause-② carrier line (L279–L291, flight B's), the four-axis frame, the rest of the report JSON contract.

Merge-tree proof

• git merge-tree --write-tree HEAD f5c08e9589 (flight B's head, PR docs(agents,skills,pm): make the remaining one-shot-executor fences executable, and re-lock the retirement pin #16357) → exit 0, 0 CONFLICT lines (tree cd052574e2f68cd9484b1a99c7078b1febb35657).
• git merge-tree --write-tree HEAD origin/main at f377394ae2 → exit 0, 0 CONFLICT lines.

Gates (union run at 9a1f16843c, the final commit; every exit captured before any pipe)

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (no path passed; change set from the merge base: 1 path). Reconciled: dispatch-gates --ran → 16 derived, 16 run, 0 NOT-MEASURED, 0 UNRUN (exit 0).

• pnpm check:pm-skill-ratchet exit 0 — ✓ check-skill-line-ratchet: .claude/agents/os-dev.md is 403 lines (ceiling 403; headroom 0). (self-test + live; zero advisories)
• pnpm check:pm-skill-id-lint exit 0 — ✓ check-skill-id-lint: 26 file(s) clean
• pnpm check:skill-frame-sync exit 0 — 2 copies of the decision frame are structurally isomorphic across 2 files
• pnpm check:pm-governed-prose exit 0 — 2 instruction surface(s) name all 5 registered governed surfaces
• pnpm check:pm-governed-merges exit 0 (self-test, 274 assertions)
• node scripts/pm/check-governed-merges.mjs --test .claude/agents/os-dev.md → exit 3 — GOVERNED — a human merge is the review record for this PR
• node scripts/pm/check-half-states.mjs --self-test exit 0 — 2553 cases pass; every removed or rewritten sentence grepped over scripts/, .claude/hooks, .github → 0 hits each (14 sentences); positive controls fire (decision_frame 2 hits in scripts, assertEngineDeleteDispatch 72)
• pnpm check:agent-model-declared exit 0 · pnpm check:agent-test-spelling exit 0 · pnpm check:doc-authoring exit 0 · pnpm check:nul-bytes exit 0 (scanned 8030 text file(s) … no raw ASCII control bytes)
• all five .claude/hooks/*.selftest.sh exit 0 (52 / 130 / 120 / 53 / 38 passed, 0 failed)
• whole-tree families: check-closing-keyword-parity (+ --self-test) exit 0 · check-comment-mask-corpus exit 0 · check-governed-queue-guard --self-test exit 0 · check:driver-memory-census exit 0 · check:refd-timer-probe exit 0 · check:watch-hint-literal exit 0
• pnpm --filter @objectstack/lint run check:doc-formula-expressions: first run exit 3 = PREREQUISITE NOT MET (formula + lint not built — not a measurement); after turbo run build --filter=@objectstack/formula --filter=@objectstack/lint through the lock → exit 0 — ✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 430 files / 1371 TS blocks judged clean
• whole-repo pnpm lint through bash scripts/pm/os-verify-lock.sh under OS_VERIFY_LOCK_SLOT=issue-16262, one call, full budget, lock free at arrival: VERDICT command-exit 0 · held the lock 111s (1m51s) · waited 0s (shared-box seconds)
• control bytes: grep -naP over the file → none; model identifiers in the diff → none

验收备注

noted, not filed (none of these is a reproducible defect, a declared-contract violation or a metadata-authoring trap):

• os-dev.md rule 3 line 「大宗读走零配额档:公开仓单卡网页内嵌 JSON payload 载原始 body + 全评论」 over-claims against platform-readings.md (「只有 body 精确」; the timeline renders the first 15 items). The next line already delegates the boundary to platform-readings; a doc nit, left as is.
• Label of a dev-filed card: this PR keeps the old L58 disposition (filed cards carry no label; the triage seat grades) now that the observation-class finding instruction is gone. skills(pm-dispatch, os-dev, AGENTS.md): finding admission threshold — only a reproducible defect, a contract violation, or a metadata-authoring trap becomes a card; everything else rides the PR's acceptance notes (maintainer-directed, both repos) #16351 §5 reads as if a dev-filed card may carry finding (待首次定级). Either reading is one word on L41; see the report's open_questions.
• The dispatch brief's parenthetical "no re-entering the queue on a 99" vs the ruling's "always set OS_VERIFY_LOCK_SLOT so a timed-out place is resumed": read as tail re-entry forbidden, same-slot resume sanctioned; the text says exactly that.
• os-verify-lock.sh reported held the lock 2s for a turbo build whose log ran 2,228 lines — a cache replay from the shared .turbo cache; consistent, not a finding.

维护者速读(草稿)

改了什么。 只改一个文件 .claude/agents/os-dev.md(开发 agent 的工作合同),行数不变(403/403)。两处:① 验证锁的等待纪律写成协议——一次前台调用领满预算、阻塞到拿锁或超时,不轮询重试,恒设 OS_VERIFY_LOCK_SLOT,超时读作「未测量」,再取时以同名续位;② 顺路发现的立卡门槛——只有可复现缺陷、契约违背、会让 AI 写错元数据的陷阱三类才立卡,其余写进 PR 的「验收备注」并在报告里记 noted, not filed。

为什么改。 ① 锁的等待方式之前只写了机制,没写成可被追责的纪律,实测里守约者反而排不到;裁决(#14944 Q3 A)要求写进合同。② 舰队每次飞行都立一到三张观察类卡,几乎全是 p3,队列只涨不消;您的指示是从源头减流,预期入流减半。

风险与代价(含回滚)。 风险低:纯文本规则,不碰代码和门禁脚本;所有派生门禁与全仓 lint 绿。可能的代价是把本应立卡的缺陷记成「备注」——已用三类证据判据兜住,且席位在验收时复读备注,实属三类的由席位补立。回滚即 revert 这一个提交。

席位意见。 (留空)

你要做的。 确认三类门槛的措辞与「立下的卡不打标签、由分诊定级」这一处置(或改为由 dev 打 finding),然后人工合并本草案 PR;不需要改代码。

---

Generated by Claude Code

[claude]

ACCEPT — contract-tier review of PR #16375, head 9a1f16843c (skills seat, 2026-09-06T16:3xZ).

Implemented-by: claude/issue-16262-os-dev-lock-discipline-and-finding-threshold (os-dev subagent, contract tier — launched at tier, no refusal)
Reviewed-by: session_019RfFHiRCSs3JXLK4cwcfox (skills seat)

Verified in a detached compare worktree at the PR head, not from the report:

• One file, .claude/agents/os-dev.md, +11/−11, line-neutral at 403/403, every added line paid inside its own numbered block. Dev contract: the verify-lock waiting discipline (acquire once, stay blocked, always name OS_VERIFY_LOCK_SLOT) — the #14944 ruling's Q3 A half #16262 (the [finding] The dispatch cap counts CARDS, but the binding resource is one container-wide heavy-verify lock — measured convoy: holder 284s, queue depth 3, waits of 442s/376s/312s #14944 ruling's Q3 A half): rule 1 now states the waiting discipline as protocol — one foreground call takes the whole wait budget and blocks to the lock or 99, ⛔ no poll-and-retry, OS_VERIFY_LOCK_SLOT always set — with the arrival-order guarantee folded into the VERDICT line; rule 7 reads a 99 as NOT MEASURED, spends the interval on lock-free work (the example list corrected to 写测试 — running tests takes the lock), and makes the re-acquisition a same-slot resume, ⛔ never a tail re-entry. skills(pm-dispatch, os-dev, AGENTS.md): finding admission threshold — only a reproducible defect, a contract violation, or a metadata-authoring trap becomes a card; everything else rides the PR's acceptance notes (maintainer-directed, both repos) #16351's last half: rule 3's out-of-scope block carries the maintainer's admission threshold — only (a) a reproducible defect, (b) a declared-contract violation, (c) a metadata-authoring trap file a card, ⛔ never withheld for looking small; everything else (观察、死代码、未演练漂移、抛光、风格、文档 nit、命名) goes under the PR's ## 验收备注 and into the report as noted, not filed, read by the seat at ACCEPT — paid by folding the 立不成/禁形 pair and retiring the two old disposition lines; the dedup / channel / 归挂 lines stay for the cards that are filed; the report-shape example gains the second spelling in place. The seat read each deleted sentence against the survivors: no rule lost.
• Gates at the head: check-skill-line-ratchet exit 0 (os-dev.md 403/403, zero advisories); check-governed-merges --test exit 3; check-half-states --self-test 2553 (fourteen removed or rewritten sentences pinned nowhere, positive controls fire); check-skill-id-lint, check-skill-frame-sync exit 0; all five .claude/hooks/*.selftest.sh exit 0; every added line 97–120 bytes; git merge-tree against flight B's PR docs(agents,skills,pm): make the remaining one-shot-executor fences executable, and re-lock the retirement pin #16357 (f5c08e9589, the same file) and against main exit 0 with the driver forced off. The dev's report adds the derived union 16/16 with --ran at 0 NOT-MEASURED, the formula-examples gate green after its build prerequisite, and whole-repo pnpm lint through the verify lock in one full-budget call. PR checks on 9a1f16843c: 17 success, 12 skipped, 0 failed (29 runs, converged).
• Report hygiene: os-dev-report on Dev contract: the verify-lock waiting discipline (acquire once, stay blocked, always name OS_VERIFY_LOCK_SLOT) — the #14944 ruling's Q3 A half #16262 and skills(pm-dispatch, os-dev, AGENTS.md): finding admission threshold — only a reproducible defect, a contract violation, or a metadata-authoring trap becomes a card; everything else rides the PR's acceptance notes (maintainer-directed, both repos) #16351, JSON closes; PR body opens Fixes #16262 then Fixes #16351 (this is skills(pm-dispatch, os-dev, AGENTS.md): finding admission threshold — only a reproducible defect, a contract violation, or a metadata-authoring trap becomes a card; everything else rides the PR's acceptance notes (maintainer-directed, both repos) #16351's last half; flight I's PR skills(pm-dispatch, AGENTS.md): finding admission threshold — three classes file, the rest rides the PR's acceptance notes #16368 carries Refs); ## 验收备注 and ## 维护者速读(草稿) present; no model identifier; skip-changeset read back comparatively; zero MCP calls; four noted, not filed items are the new rule applied to itself.

Ruling on the open question — A, as landed. A dev-filed card of the three classes carries no state label; the bare-card triage grades it (the fast path to pm:queue for a real defect), and finding stays a label seats apply — the type field remains the triage seat's single product (core-rules: 类型字段由分诊席唯一生产), and a dev that must not judge severity does not pick the routing label either. If the seats later want the 发现分诊轮 as the single grading path, it is one word on that line — a follow-up, not a re-dispatch.

Landing regime: governed (.claude/**) ⇒ the PR stays a draft; reviewers os-zhuang + hotlong requested in this same act, needs-user-decision added, the final 维护者速读 posted as the next comment; human merge. On the merge #16262 and #16351 close by Fixes; with PR #16368 the maintainer's finding-threshold instruction is then fully landed on both repos' reading surface.

---

Generated by Claude Code

[claude]

维护者速读

事情:开发 agent 的工作合同 os-dev.md 一次落两条,行数不变(403/403)。① 验证锁的等待纪律写成协议(#14944 您裁的 Q3 A):一次前台调用领满预算、阻塞到拿锁或超时,不轮询重试,恒设 OS_VERIFY_LOCK_SLOT;超时读作「未测量」,再取时以同名续位而不是从队尾重排。② 您今天指示的 finding 准入门槛的后一半:dev 顺路发现只有三类立卡(可复现缺陷、契约违背、会让 AI 写错元数据的陷阱),其余写进 PR 的「验收备注」并在报告里记 noted, not filed,席位验收时复读。前一半(SKILL.md / core-rules / AGENTS.md)在 PR #16368。

为什么改:① 锁的等待方式此前只写了机制、没写成可追责的纪律,实测里守约者反而排不到;② 舰队每次飞行都立一到三张观察类卡、几乎全是 p3,队列只涨不消——从源头减流。

代价与兜底:纯文本规则,不碰代码与门禁;可能的代价是把本应立卡的缺陷记成备注,已用三类证据判据兜住,席位在验收时复读备注、实属三类的由席位补立。dev 立的卡不打状态标签、由分诊定级(席位已裁,与「类型标签由分诊席唯一产出」一致)。回滚即 revert 一个提交。

席位意见:建议合并。受管面(.claude/**),人工合并;合并后 #16262 与 #16351 关闭,您的准入门槛指示在两仓的阅读面上就全部落地了。

---

Generated by Claude Code