docs(pm-dispatch): principles-only SKILL.md rewrite — lessons distilled in place, no issue-ID citations

[os-zhuang]

Fixes #7885
Fixes #7765
Fixes #7767
Fixes #7899

ADR-class (skills root): draft, human merge only — ⛔ no queue entry, no auto-merge.

What this is

The PM operating protocol rewritten to principles + state machine + lookup data per the 2026-08-12 rulings (「现有的项目经理 skills 应该大幅简化,只需要说原则,不需要写细节」;「处理 issue 时犯的错应该总结成经验,保留 issue id没有意义」). Every incident-backed rule is now a self-contained lesson (failure mode + discipline + boundary); zero issue-ID citations in operative text (mechanically enforced, see Gate work); maintainer rulings keep date + verbatim quote. Hot-file cost: SKILL.md 2,568 → 686 lines (−73% on the text every seat loads every round). At-that-moment operational detail moves to references/ fact tables loaded on demand (~465 lines across 6 files, including the pre-existing compile-surfaces table).

Structure per the closed design round: single file with per-role duty sections (triage / executor / queue steward / epic), explicit role entry args (/pm-dispatch triage / steward / [domain] / epic:#N — all legacy arg forms kept working; grep across hooks/workflows/docs found nothing hard-coding the old forms), and probe-first startup (idle seat = one query, then self-retire).

Sweep checklist — where each member card's substance lives

• pm-dispatch SKILL structural optimization: role-split loading, issue-ID removal (lessons distilled in place), probe-first startup (maintainer-directed) #7885 (carrier) → the rewrite itself: role sections + entry args + probe-first (SKILL.md §入口与角色); ID removal with lint; references/incidents.md deleted; ratchet lowered; high-risk sequences mechanized (scripts/pm/os-regen-merge.sh, scripts/pm/ensure-pm-labels.sh).
• pm-dispatch SKILL: 5-hour usage-limit outages — queryable signals, cross-wall recovery timer (hourly cron, not send_later chains), wall-death playbook anchor #7765 (outage detection & cross-wall recovery) → SKILL.md §断粮与跨墙恢复 (principles) + references/platform-readings.md §断粮检测与跨墙恢复细则 (readings): ccusage blocks per-container reading with its three named blind spots (single-container view; cost-not-allowance — no agent-facing account-level quota surface; locally-inferred window start); the wall signal's embedded reset time (available at hit time, not queryable before); timer discipline — one-shot at reset+buffer when the reset time is known, hourly cron Routine over send_later chains in dead windows, criteria-only idempotent fired text, cron self-deletion after the first successful fire; and the recovery playbook anchor (probe in-flight cloud cards → direct-acceptance / transcript revival → re-arm patrols). 机制假设 verification level: platform tool docs describe send_later as a run-once trigger that self-disables after firing (ended_reason=run_once_fired); whether a firing during an account-wide outage is retried is undocumented and unmeasured, so the timer principle is worded as conservative design rationale, not measured fact.
• pm-dispatch SKILL Guardrails: dangling sentence fragment "someone else, never dispatch a needs-user-decision issue." — the bullet it belonged to is lost #7767 (lost Guardrails bullet) → restored as a whole bullet in §Guardrails: "决定属于维护者:永不代维护者回答产品/架构问题(唯一例外:已裁的代裁车道,边界恰与其置信门重合);永不派发 assignee 是别人的 issue;永不派发带 needs-user-decision 的 issue" — plus the same prohibitions in the State-model rows (assignee row, needs-user-decision row) and the all-seats invariant "先认领后动工;assignee 不是你 ⇒ 永不碰". The dangling fragment is gone with the rewrite; no binding rule was lost in the interim (the state model carried the second half throughout).
• pm-dispatch step 8: triage-seat four-lens auto-adjudication of high-confidence decision cards — human floor for feature-add / ADR / protocol-change (maintainer-directed) #7899 (triage adjudication) → §分诊座位职责「高置信决策卡的分诊代裁」, with both 2026-08-12 ruling quotes verbatim: human floor (功能新增 / ADR / 协议变化 / destructive + the six ruled additions: security/permission boundary, gate weakening, spend/quota/fleet-shape/model-tier, new runtime dependency; the accept-set/public-surface boundary test routes expansion to the floor; the flip-back clause returns a card mid-implementation); confidence gates (four-lens unanimity; not on the floor; no narrowing/overturning of existing rulings; veto-window execution with the four-lens block + auto-adjudicated marker + a 代裁清单 section in every round report; adjudication pass runs on claude-fable-5). The Guardrails "never answer on the maintainer's behalf" rule carries the lane as its single bounded exception.

References disposition (design B + the on-demand pattern)

• references/incidents.md deleted (1,587 lines) — git history is the archive; no §「…」 pointer machinery survives anywhere.
• references/compile-surfaces.md kept (operational lookup data), IDs removed.
• New on-demand fact tables (same sanctioned pattern as compile-surfaces): platform-readings.md (GitHub API behavior facts), seat-post-protocol.md (takeover/handover/release-board mechanics), landing-operations.md (post-ACCEPT landing), dispatch-runbook.md (cloud-card parameters, handoff, stall/replay/lost-report procedures), review-checklist.md (per-report criteria). Judgment call, flagged for review: decision A said "single-file principles-only"; I read that as ruling out the role-split module loading, not the compile-surfaces-style data tables — the hot file stays one file of principles, and these tables are consulted at the moment their operation happens. If you want any of them folded back, say which — but SKILL.md cannot absorb them and stay under the 700-line cap.

Gate work

• Ratchet lowered 2568 → 686 (scripts/pm/check-skill-line-ratchet.mjs, header updated — it no longer instructs moving case law into incidents.md).
• New ID-lint scripts/pm/check-skill-id-lint.mjs (pnpm check:pm-skill-id-lint, wired in lint.yml next to the ratchet): .claude/skills/pm-dispatch/**/*.md + .claude/agents/os-dev.md must not match #[0-9]{3,}. Zero matches in every rewritten file. os-dev.md carries an exact-count legacy waiver (81) that self-expires: it passes at exactly 81 (untouched legacy) or exactly 0 (the rewrite in its own PR) and is red at anything else — so the two PRs stay merge-order-independent, IDs cannot creep in meanwhile, and a partial cleanup must finish the job. Deleting the waiver entry after both PRs land is an optional one-line cleanup.
• Mechanized sequences (design C): scripts/pm/os-regen-merge.sh (the generated-artifacts merge four-step; the ordering — commit the merge before regenerating — is the trap the prose used to carry) and scripts/pm/ensure-pm-labels.sh (label vocabulary, idempotent; retired labels deliberately absent). Prose keeps one principle line pointing at each.
• Frame-sync adapted: the three-axis frame keeps its anchors verbatim in both files; one self-test fixture mutated the internal copy via an issue-ID pattern that no longer exists by design — swapped for an equivalent wording-only mutation (scripts/check-skill-frame-sync.mjs).

Dropped, with rationale — for line-by-line review

1. All issue-ID citations and incidents.md pointers — ruled (2026-08-12); lessons are distilled in place.
2. 沿革 / historical-evolution sections (domain:spec-tooling 沿革, engine/spec/metadata split histories, Model-tiering two-tier→three-tier supersession notes, the deleted-borrowing tombstone narrative) — the current rule survives in full (including ⛔ 不借调); superseded states and how we got here live in git history.
3. Worked-example narratives and measured samples (claim-race specimens, the two-seat nine-card timing table, seat-post compression byte counts, per-incident replay counts) — the principle each one taught survives; the numbers were samples, not norms (the text now says so where it matters, e.g. "判死基线是本车道实测,⛔ 不是本文任何常数").
4. One-time completed-state records (release-board initial cleanups executed, label migrations completed, legacy [决策] title note) — completed actions, not rules; the standing prohibitions (只有增量、⛔ 永不全量重扫; retired labels not recreated) survive.
5. The middle Model-tiering quote 「派发使用云卡片,用 Fable 5 模型」 — it was this batch's dispatch instruction, not a standing rule; the standing policy survives via the other two quotes (floor/ceiling + the mandatory claude-fable-5 clause for pm-dispatch cards, quoted verbatim).
6. The "counted titles rot" micro-rule (「不写条数在标题,要数量数编号」) — the rewritten text carries no counted titles, so the rule has no remaining anchor; flagged here in case you want it kept as a general authoring principle.
7. Seat-post issue numbers in the vocabulary table — replaced by the label:pm:seat index query (the numbers were navigation data; the ruled ID-removal covers them, and the index is the lookup that cannot rot).

Deviations to review

• 686 lines vs the ~500 target (hard cap 700 respected): the ~500 point was reachable only by dropping rules; per the red line I kept semantics and spent the gap. The ratchet is set to 686 — tighten opportunistically from here.
• PR₂ (os-dev.md, Fixes #7903) lands at 356 lines vs its ~200–300 target, same reason, reported there.

Gate status (honest, at draft-PR time)

Local, all green: check:pm-skill-ratchet (686/686), check:pm-skill-id-lint (8 files clean, self-test 9/9), check:skill-frame-sync (12/12 self-test, 4 copies isomorphic), check:skill-frame-freshness, check:doc-authoring (375 files), check:nul-bytes (7,244 files), @objectstack/lint check:doc-formula-expressions (dependency closure built first). Branch is merged up to current origin/main. CI: in_progress at report time — the PM owns convergence.

No changeset: .claude/ + scripts/ + workflow-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:37am

[os-zhuang]

同意合并