docs(AGENTS): rewrite the root standing orders to the 1,500-word budget

Applies the documentation standard to its biggest offender. Every rule
survives as one to three lines plus a link to its durable home; the
stories, duplicate statements, and re-narrations go:

- Situational clusters evict to new homes: docs/testing.md (tiers,
  with-key policy, real-over-mock, world-verification, real-entry-path
  guards), docs/defensive-patterns.md (the bug-class rules), and
  docs/cookbook/responding-to-pr-review-on-a-stack.md (the stacked-PR
  review procedure).
- Doc-authoring rules consolidate into docs/AGENTS.md § Writing rules
  (current-state-never-history, md-wrap, ts-block compilation, @mode,
  catalog same-change, pair same-change).
- packages/README.md drops to the group table + the extension-vs-bundle
  dependency rule; the hand ASCII graph yields to the generated
  module-graph.md; group READMEs are the canonical per-package map.
- packages/AGENTS.md keeps only its packages-specific rules (export
  shape, ctx.get, real-Loader coverage); examples/AGENTS.md repoints
  its with-key-policy link; rfc/README.md loses a narrated-history
  aside; dsh-code-review / dsh-find-simplifications / verify-md-wrap
  references follow the moved content.
- Budget manifest ratchets: AGENTS.md 8200 -> 1500 (now 1,495 words),
  packages/README.md 1900 -> 600, packages/AGENTS.md 600 -> 450; the
  two new eviction docs join the budget set (testing 800, defensive
  550); docs/AGENTS.md raises 1000 -> 1250 for the absorbed writing
  rules (the one justified increase). The doc-tiers RFC's deferred list
  prunes the two items this change ships.
This commit is contained in:
Tianyi Cui
2026-07-04 14:22:47 +08:00
parent aa36b3b36b
commit 7702a33531
16 changed files with 200 additions and 400 deletions

View File

@@ -1,8 +1,10 @@
{
"AGENTS.md": 8200,
"docs/AGENTS.md": 1000,
"AGENTS.md": 1500,
"docs/AGENTS.md": 1250,
"docs/architecture.md": 3950,
"docs/defensive-patterns.md": 550,
"docs/testing.md": 800,
"examples/AGENTS.md": 600,
"packages/AGENTS.md": 600,
"packages/README.md": 1900
"packages/AGENTS.md": 450,
"packages/README.md": 600
}

View File

@@ -1,6 +1,6 @@
/**
* Doc-sync gate: enforce the repo's "Markdown is not hard-wrapped" convention
* (AGENTS.md § Type Safety and Documentation) — prose paragraphs are written as
* (docs/AGENTS.md § Writing rules) — prose paragraphs are written as
* one physical line per paragraph and the editor soft-wraps. A hard-wrapped
* paragraph (a one-word edit reflows and re-diffs the whole block) is a defect
* this script catches before review.