Merge branch 'worktree-docs-overhaul-a-standard' into worktree-docs-overhaul-b-agents

# Conflicts:
#	docs/AGENTS.md
#	docs/rfc/implemented/process/2026-07-04-doc-tiers-and-budgets.md
#	scripts/doc-budgets.manifest.json

.agents/skills/dsh-doc-standards/SKILL.md

@@ -40,7 +40,7 @@ Compression discipline: every load-bearing rule survives — as one to three lin
 
 1. Relocate: does the new content belong in a linked home (RFC, postmortem, cookbook, README) with a one-line pointer left behind?
 2. Condense: can existing prose in the doc pay for the addition — a story compressed to its rule, a duplicate converted to a link?
-3. Only then raise the ceiling: edit `scripts/doc-budgets.manifest.json` and justify the raise explicitly in the PR description. After any rewrite that shrinks a budgeted doc, ratchet its ceiling down to the new size plus modest headroom in the same PR.
+3. Only then raise the ceiling: edit `scripts/doc-budgets.manifest.json` and justify the raise explicitly in the PR description. After any rewrite that shrinks a budgeted doc, ratchet its ceiling down to the new size plus working headroom (at least 5%) in the same PR.
 
 ## Validation and PR hygiene
 

docs/AGENTS.md

@@ -36,13 +36,13 @@ Placement test: a story about a bug → postmortem. Why we chose X → RFC. How
 
 Standing docs accrete: every PR has a lesson it wants to append, and without displacement pressure nothing ever leaves. The gate is that pressure. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) lists the accretion-prone standing docs with a word ceiling each; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget.
 
-- Ceilings are an enforcement frontier: a ceiling starts at the doc's current size (freezing further growth) and ratchets down as the doc is brought to its target. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file (which carries the standard) ≤ 1,250; `packages/README.md` ≤ 600.
+- Ceilings are an enforcement frontier with working headroom: a ceiling sits at least 5% above the doc's current size — routine edits pass, real growth trips the gate — and ratchets down, keeping the margin, as the doc reaches target. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file (which carries the standard) ≤ 1,250; `packages/README.md` ≤ 600.
 - When the gate goes red, the fix is to relocate or condense per the taxonomy above. Raising a ceiling is the last resort: the PR must justify it; the manifest diff is the reviewable act.
 - Unbudgeted tiers (package READMEs, RFCs, reference matrices) have no ceiling — length is legitimate there when every row is a fact. Review and the slop checklist govern them instead.
 
 ## The slop checklist
 
-Hunt these in any doc you write or review; the [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) skill runs this list as an audit:
+Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) skill runs this list as an audit:
 
 - The same rule stated in more than one home. Grep a distinctive phrase; keep one home, convert the rest to links.
 - Narrated history: "previously", "now", "no longer", "used to", "renamed", "was moved", references to PRs or commits. State the current fact; the why belongs in an RFC, the story in a postmortem or git.
@@ -57,4 +57,4 @@ Hunt these in any doc you write or review; the [dsh-doc-standards](../.agents/sk
 
 When one doc refers to another doc, an RFC, a package README, or any file in the repo, link it with a relative Markdown link to the actual path — never bare prose or a number ("see RFC 005"), which is uncheckable and rots on rename. `pnpm run verify-md-links` (part of `doc-sync`; see [the cross-link lint RFC](rfc/implemented/process/2026-06-18-markdown-cross-link-lint.md)) fails when a relative target does not exist, so a rename that orphans a link is caught before review. This is also why RFC files carry dates and topics instead of stable numbers: they survive moves between lifecycle and class folders without dangling references.
 
-The gate checks file existence, not `#anchor` validity — a stale heading fragment on a real file still passes, so verify anchors yourself when linking to one.
+The gate checks file existence, not `#anchor` validity — verify anchors yourself when linking to one.

docs/rfc/implemented/process/2026-07-04-doc-tiers-and-budgets.md

@@ -8,7 +8,7 @@ The repo's standing docs accrete. Root `AGENTS.md` reached 8,130 words through 5
 
 - **A tier taxonomy with one home per fact.** [docs/AGENTS.md](../../../AGENTS.md) is the documentation standard: it assigns every Markdown tier a single job (standing orders, system map, type catalog, decision records, incident stories, how-tos, per-package contracts, generated catalogs, workflows), forbids restating a fact outside its home tier (link instead), and carries the slop checklist used when writing or reviewing any doc.
 - **A narrow, hard budget gate.** [scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) joins `doc-sync`: every doc listed in [scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) must stay under its word ceiling (`wc -w` semantics, whole file), and a budgeted file that is missing fails the gate so a rename cannot silently orphan its budget. Scope is deliberately only the accretion-prone standing docs — the root and subtree `AGENTS.md` files, `architecture.md`, `packages/README.md`, and the standing policy docs they evict content into (`docs/testing.md`, `docs/defensive-patterns.md`). Reference docs, RFCs, and package READMEs are unbudgeted: length is legitimate there when every row is a fact, and review plus the slop checklist govern them.
-- **Ceilings are an enforcement frontier that ratchets.** A ceiling starts at the doc's current size, freezing growth from day one, and ratchets down as the doc is brought to its target budget (root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; subtree `AGENTS.md` ≤ 600; `packages/README.md` ≤ 600) — the same rollout mechanism as the [translation-pairing `required` list](2026-07-02-bilingual-docs-and-pairing-gate.md). When the gate goes red the fix is to relocate or condense per the taxonomy; raising a ceiling is permitted only with explicit justification in the PR description, the manifest diff being the reviewable act.
+- **Ceilings are an enforcement frontier that ratchets.** A ceiling sits at least 5% above the doc's current size — working headroom, so routine wording edits pass while real growth still trips the gate — and ratchets down, keeping that margin, as the doc is brought to its target budget (root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; subtree `AGENTS.md` ≤ 600; `packages/README.md` ≤ 600) — the same rollout mechanism as the [translation-pairing `required` list](2026-07-02-bilingual-docs-and-pairing-gate.md). When the gate goes red the fix is to relocate or condense per the taxonomy; raising a ceiling is permitted only with explicit justification in the PR description, the manifest diff being the reviewable act.
 - **A thin workflow skill, contracts in docs.** [.agents/skills/dsh-doc-standards](../../../../.agents/skills/dsh-doc-standards/SKILL.md) carries the placement/audit/red-gate workflow and defers to the standard as its source of truth, the same split as [dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md) over the i18n contract.
 
 ## Alternatives considered

scripts/doc-budgets.manifest.json

@@ -1,10 +1,10 @@
 {
-  "AGENTS.md": 1500,
-  "docs/AGENTS.md": 1250,
-  "docs/architecture.md": 3897,
+  "AGENTS.md": 1575,
+  "docs/AGENTS.md": 1315,
+  "docs/architecture.md": 4095,
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 800,
-  "examples/AGENTS.md": 579,
+  "examples/AGENTS.md": 610,
   "packages/AGENTS.md": 450,
-  "packages/README.md": 600
+  "packages/README.md": 605
 }

scripts/verify-doc-budgets.ts

@@ -13,9 +13,10 @@
  * matrix is the right kind of long), and the standard governs them through
  * review, not a ceiling.
  *
- * The manifest is an enforcement frontier, i18n-rollout style: ceilings start
- * at a doc's current size (freezing further growth) and ratchet DOWN as the
- * doc is brought to its target budget. A manifest entry whose file is missing
+ * The manifest is an enforcement frontier, i18n-rollout style: a ceiling sits
+ * at least 5% above the doc's current size (working headroom, so routine
+ * wording edits pass while real growth trips the gate) and ratchets DOWN,
+ * keeping that margin, as the doc is brought to its target budget. A manifest entry whose file is missing
  * fails the gate, so a rename cannot silently orphan its budget.
  *
  * Words are counted `wc -w` style over the whole file (whitespace-delimited