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

[os-zhuang]

Fixes#7943

ADR-class (repo-wide agent governance): draft PR, human merge — no auto-merge, no queue entry.

What this is

The AGENTS.md principles-only rewrite under the 2026-08-12 rulings (「只需要说原则,不需要写细节」;「保留 issue id没有意义」), applying the same three-way sorting rule as the SKILL.md and os-dev.md rewrites:

1. Mechanize ⇒ principle + pointer — everything a hook or CI gate already enforces shrinks to the rule plus its script name; the script header is the authority on detail.
2. Distill — incident narratives become self-contained lessons in place (failure mode + discipline + boundary), zero issue-ID citations; maintainer rulings keep date + verbatim quote (the four rulings quoted — GitHub-English 2026-08-08, ADR human-merge 2026-08-08, release human-only 2026-08-07, read-seam scope 2026-08-06 — are untouched bytes).
3. Keep as data — command blocks, the dev-server/layout/domain/routing tables, the regenerate-gate table, the ADR-0087 disposition markers.

Measured: 1,050 → 818 lines; 84,665 → 66,935 chars (−21%); issue-ID citations 123 → 0.

Invariants deliberately preserved

• All 15 Prime Directives survive whole — every normative clause kept; only narrative evidence was distilled.
• Section names, the Multi-agent discipline numbering (§7/§8/§9/§10 anchors are cited by script headers repo-wide), and the Route & surface ownership rule numbering are unchanged. Two in-file references to "§7's third re-arm situation" were retargeted to "§7's draft-flip re-arm note" because the re-arm list is now prose.
• The RELEASE-OWNED guardrail row is byte-preserved on one line — check:docs-audit-scope anchors on it (assertGuardrailAnchored); the gate and its self-tests run green on this branch.
• The 「AGENTS.md wins」 conflict rule (pm-dispatch SKILL defers to AGENTS.md) is not inverted or blurred; the header now states the same rule from this side ("when any other instruction file conflicts with this one, AGENTS.md wins") — an addition, flagged here for review.
• CLAUDE.md's mirrored rules stay consistent in the same PR: its two ID-carrying passages are distilled to match (claim-comment lesson; stash-swap incident), everything else untouched.

ID-lint scan-set extension (same PR)

scripts/pm/check-skill-id-lint.mjs: AGENTS.md added to EXTRA_FILES. No legacy waiver needed — the rewrite and the scan-set extension travel in one PR, so there is no merge-order dependence (with both batch PRs from one dispatch, going straight to zero was preferred over the waiver pattern). Adjacent one-line cleanup blessed by the script's own header: the dead os-dev.md legacy entry (81) is deleted — it had become worse than dead weight, since it would still have passed a file that re-acquired exactly 81 IDs — and the self-test now exercises the waiver mechanism with a synthetic entry plus a new case asserting the scanned files carry no waiver. Self-test: 10/10 green.

Dropped-with-rationale list (for line-by-line review)

Nothing below removes a rule; each entry is narrative/measurement whose normative content survives in distilled form:

• All 123 issue/PR-number citations (incl. objectui#NNNN, cloud#NNN, "today #NNNN") — per the 2026-08-12 ruling; lessons restated self-contained.
• Communication: the measured half-Chinese/half-English PR-body incident (two PR numbers, same-day detail) → one sentence on why the rule is split per channel.
• Build & Test: ratchet-history narrative (the 2.25x drift figure survives as the rationale clause; the pre-fix gate-design story goes); phantom-check discovery story (the "seventeen pins in one package" count survives).
• Prime 10: the 9-declared/3-enforced/6-final validation-rule numbers → the shape (trim + implement; call-site over switch).
• Prime 12: the named alias-graduation history (conversion-entry ids, protocol 17, the six tracked stragglers) → "paid down exactly that way, emptying and deleting the executor shim"; worked example kept without repo/issue names.
• Prime 13: the three ADR ids and issue-churn chronology of the sys_member.role reversal → "a reversal of three accepted ADRs… held for a day".
• Prime 14: merge timestamps, PR numbers, seat names of the two post-ruling ADR merges → "merged, twice, by two different AI seats within one hour of the ruling (both ratified retroactively, explicitly setting no precedent)".
• Prime 15: rc.4 run id/actor/package-count/tag-sha measurements and the rc.3 date → "shipped a full release candidate end to end … twice in one week"; the pin-fresh-skipped and version-commit-never-reached-main forensics dropped.
• §7 (merge queue): the subscriber inventory measurement (workflow list, 2742 merge_group runs), per-incident timestamps of the eject/re-arm and armed-red cases, the advisory-red incident chain → principles ("full suite vs affected-only", "armed red hides", "advisory rides through") kept with the 2026-08-07 required-set ruling; the unmeasured-405 note kept in one sentence.
• §9: the stale-dist gate's design history → "content-hash, never mtime" + the existence-not-freshness caveat.
• §11: the explicit merge=os-regen path list and the still-single-file list → pointer to .gitattributes + check:merge-driver (which reconcile both directions mechanically) and sharded-artifacts.ts; the 310KB-conflict incident → one clause.
• Spec-artifacts section: gate-history narratives (filtered-job retirement, the check-that-edited-the-tree incident, reconciliation-before-CI incidents, the two-red-builds example) → the principle bullets; check:dual-source-exports / check:exported-any / react-parity / sdui-manifest cautions all kept, shorter.
• Degradation section: the incident chain and family issue lists → "the founding incident" narrative kept in three lines; the two ledger entry-kind names (unfixed-degradation / reviewed-legitimate) summarized as "read the entries and their reasons, never the count" (the kinds are defined in the script).
• Startup section: the three incidents keep their content, lose their issue numbers and subsystem file names; the open kernel-contract follow-up pointer dropped (it lives on the issue tracker, not in operative text).
• Patterns/Route-ownership: retired-example and retired-/data-surface names → generalized ("a retired duplicate data surface"); the three re-learned invariants kept.
• Post-task: the shipped-unregistered-removal example loses its PR/issue ids; the "1 in 7" measurement and all four ADR-0087 markers kept verbatim.

Gates (local, honest readings)

• check:pm-skill-id-lint — green, now 9 files incl. AGENTS.md at 0 citations (self-test 10/10)
• check:pm-skill-ratchet — green (SKILL.md untouched by this PR; 686/686)
• check:skill-frame-sync — green (4 copies isomorphic)
• check:doc-authoring — green (375 files)
• check:nul-bytes — green (7,279 files)
• check:docs-audit-scope — green (guardrail anchor + 22-case self-test + release-owned routing), run because it anchors on this file

---

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 8:23am

[os-zhuang]

同意合并