docs(agents): make the os-dev termination contract explicit and honest about its measured failure rate (#6586)

[os-project-manager]

Fixes #6586

What this changes

One file: .claude/agents/os-dev.md. Three edits, all in the dev agent's own operating manual.

1. A new "Terminating cleanly" section, placed directly after the Definition of done list, because termination is the last step of that order. It states:

• The structured report is the terminal action — push, draft PR, skip-changeset, the foreground CI-convergence read, then the JSON, and nothing of the dev's runs after it.
• A monitor is bound to its own deadline, never to its subject's lifetime. Cancel a watched process, cancel its monitor in the same step; finish reading a run's output, its monitor is finished too. The measured case is publish/lint 面对字面量空组合子响亮拒收 —— #5322 拍板单位元后的可选编写期信号(PD #12 形状) #5330 / PR feat(lint): refuse literal empty combinators at authoring time (#5330) #6703: one card emitted six notifications, five redundant replays of the same full report, one of them from a monitor watching a run the agent had itself cancelled via TaskStop before it ever acquired the lock.
• Stale-wake identifiability — if a monitor fires anyway, its first line names what it watched and whether that thing is still alive, before the JSON. Today those six arrivals were indistinguishable: same shape, same full JSON, so the PM had to re-adjudicate each one to discover it was a repeat.
• The ownership split either side of the report, which the issue's suggested direction guessed the other way round (see below).

2. The honesty clause, which is the point of the card. The section states plainly that following it does not mean the dev will be heard: 7 of 7 dispatches on 2026-08-08 failed to hand back cleanly after opening a correct PR, and three of those carried this clause verbatim in their dispatch prompt and failed anyway — 3 of 4 clause-carrying runs, which puts the cause outside anything a documentation change can reach. Two binding consequences follow in the text: never read your own silence as success, and the PM's probe-and-revive loop is the standing backstop, not an exception path. Every death so far was fully recoverable from transcript with zero work lost, so the cost is latency and not correctness — and the text says so, precisely so that a revived dev does not "recover" by redoing the work or opening a second PR.

3. Two existing sentences fixed in the same pass, because the addition would otherwise leave them misleading:

• Resource rule 6 says a background watcher's wake-up "never arrives". Read against the publish/lint 面对字面量空组合子响亮拒收 —— #5322 拍板单位元后的可选编写期信号(PD #12 形状) #5330 evidence that is flatly contradictory, so rule 6 now points forward, and the new section reconciles the two explicitly: a monitor fires on its own deadline, not on the dev's need — it will not rescue a mid-task stop, and it will re-invoke a dev long after it finished. Same missing binding, seen from either side.
• The Definition of done teardown bullet said "dev servers on random ports". Background monitors are also things the dev started, and they were the whole fifth sub-shape, so the bullet now names them.

Cross-reference, per the issue's third ask

The stale monitor is the same class of cost as the PM's own dispatch timers, where a deleted timer still delivers, and by delivery time its text may be several rounds behind reality — whose mitigation is that every such text opens with idempotent, re-read state before acting. The new section cites that convention by name and applies it to the dev in the other direction: before acting on any wake, re-read the real state rather than replaying the deliverable.

Deliberately NOT done, with pointers

• .claude/skills/pm-dispatch/SKILL.md is untouched. PR docs(pm-dispatch): sweep of 7 measured SKILL corrections — os-regen list drift, the unlock sweep's three duties, verification blindness, the auto-merge signature #6720 is in the merge queue editing that file. The PM-side half of this card — that the probe-and-revive loop is load-bearing rather than a fallback, and that a stale wake should be recognisable without re-reading the deliverable — belongs there and is left for a follow-up on top of docs(pm-dispatch): sweep of 7 measured SKILL corrections — os-regen list drift, the unlock sweep's three duties, verification blindness, the auto-merge signature #6720. The producer-side half, which is this PR, is the one the PM skill already points at ("The producer-side half of this rule lives in .claude/agents/os-dev.md's resource discipline").
• The issue's suggested direction 2 was not implemented, and I believe it is inverted. It proposes that remote CI belongs to the dispatching PM and the dev should report from local verification only. The current convention is the opposite and is deliberate: pm-dispatch/SKILL.md forbids the PM from subscribing to a dev's PR before the report lands, because before the report the PR is the dev's territory and two pilots step on each other. The agent definition's own CI-convergence bullet, added after fix(runtime): callData 的 ObjectQL 兜底对「记录不存在」统一答 404 RECORD_NOT_FOUND (#5138) #5584 merged red and poisoned main's merge ref, depends on the dev doing that read. So this PR keeps the CI wait and instead makes explicit that it is a foreground read ending in the report, never a licence for a background waker. The ownership sentence in the new section records the handoff point rather than moving it.

Verification

No package code changed, so there is no unit test to add and no pnpm test or pnpm typecheck that is meaningful for this diff. Saying so beats manufacturing evidence that fits the template. What was run is the gate list enumerated from .github/workflows/lint.yml, after commit, all green:

• check:skill-frame-sync — the one that reads this exact file: 4 copies of the decision frame are structurally isomorphic across 3 files, 3 axes, 40 markdown files scanned for undeclared copies.
• check:doc-authoring — 365 files clean.
• check:nul-bytes — scanned 6258 tracked text file(s); no raw ASCII control bytes. Plus a manual scan of the edited file beyond the gate's surface, no matches.
• check:role-word — 44 baselined file(s), no new occurrences.
• check:docs-audit-scope, check:quick-reference-counts, check:adr-anchors, check:skill-compatibility — all OK.
• pnpm lint — clean, exit 0.

Labels

skip-changeset: this PR touches only .claude/agents/os-dev.md, which is internal agent tooling and publishes nothing to any package, so it releases nothing and writes no changeset. Applied as a union with the labels already on the PR, not as a bare set.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 1:51pm