docs(agents): principles-only os-dev definition — lessons distilled in place, no issue-ID citations

[os-zhuang]

Fixes#7903

ADR-class by the recorded governance note (an agent definition governs every dev session's behavior): draft, human merge only — ⛔ no queue entry, no auto-merge. Independent of the #7885 PR (PR₁): branched off current origin/main, no file overlap, either merge order works (PR₁'s ID-lint carries a self-expiring exact-count waiver for this file).

What this is

.claude/agents/os-dev.md rewritten to the same writing standard as the pm-dispatch principles rewrite (maintainer rulings 2026-08-12: 「只需要说原则,不需要写细节」;「处理 issue 时犯的错应该总结成经验,保留 issue id没有意义」): 686 → 356 lines, zero issue-ID citations (81 removed; every lesson now self-contained — failure mode + discipline + boundary), maintainer rulings kept as date + verbatim quote.

The three-way sorting rule applied:

1. Mechanized ⇒ one principle line: worktree guard, stash guard (kept with its alternatives since the reflex it blocks is the reverse-verification move), the os-regen merge four-step (now scripts/pm/os-regen-merge.sh), nul-byte gate (its header cited as the authority instead of re-arguing the harms).
2. Deleted: incident storytelling, per-incident counts and timings, duplicated rationale; the model-pin comment compressed from 46 lines of narrative to the pin's floor-not-ceiling contract, the resolution order, and its two traps.
3. Kept as data: the report-contract JSON, the toolchain-trap table, gate-family names, the resource-discipline constants (flock lock path, heap cap, worker caps), the attribution-footer forms.

Everything binding survived as a rule: the six ground rules, resource discipline (foreground pipeline, PID-only kills, unforced worktree removal), local verification scope, the standard clauses (build-first, prefix filter direction, reverse verification with its three directions, spec anchor / MERGE-state trap, rejection-envelope code+status, key-vs-value criterion, fixture triage's three dispositions + consumption-radius sweep), Definition of done (Fixes/Part-of rule, skip-changeset read-back, report-at-draft-PR-time with the platform-subscription override), terminating cleanly (report twice GitHub-first with marker read-back, monitors never outlive their subject, silence-is-not-success + the PM probe backstop), the three-axis escalation frame (frame-sync anchors verbatim), and byte/sanitizer discipline.

Deviation to review

356 lines vs the ~200–300 target. The remaining ~60 lines over target are load-bearing rules I judged non-droppable under the no-silent-semantic-loss red line (mostly the standard clauses and definition-of-done, which dispatch prompts deliberately do NOT repeat — this file is their only home). If you want it tighter, the candidates are named sections, not sentence trims — say which section may lose semantics.

Gate status (honest, at draft-PR time)

Local, all green: check:agent-model-declared (pin kept), check:skill-frame-sync (4 copies isomorphic; anchors preserved verbatim), check:nul-bytes, check:doc-authoring; zero #[0-9]{3,} matches (PR₁'s new lint goes fully strict on this file once both land). CI: in_progress at report time — the PM owns convergence.

No changeset: .claude/-only change (skip-changeset applied).

---

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 12, 2026 6:42am

[os-zhuang]

同意合并