From cada16c701168b31b35332514af92face82dd2a8 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sat, 4 Jul 2026 17:20:18 +0800 Subject: [PATCH] docs(budgets): ceilings carry at least 5% working headroom MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Exact-size ceilings turned every two-word wording fix into a gate event. The policy amends to: a ceiling sits at least 5% above the doc's current size (pre-rewrite) and keeps that margin when ratcheted to target — routine edits pass, real growth still trips the gate. Amended together in all four policy homes (docs/AGENTS.md § Budgets, the doc-tiers RFC, the gate script's module comment, the skill's ratchet rule) plus the manifest values, so prose and mechanics stay consistent. --- .agents/skills/dsh-doc-standards/SKILL.md | 2 +- docs/AGENTS.md | 2 +- .../process/2026-07-04-doc-tiers-and-budgets.md | 2 +- scripts/doc-budgets.manifest.json | 12 ++++++------ scripts/verify-doc-budgets.ts | 7 ++++--- 5 files changed, 13 insertions(+), 12 deletions(-) diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md index f981af9ace..7506ca5eb0 100644 --- a/.agents/skills/dsh-doc-standards/SKILL.md +++ b/.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 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 52ac672225..e66175ffd9 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -26,7 +26,7 @@ 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,000; `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 wording edits pass, real growth trips the gate — and ratchets down (keeping the margin) as the doc is brought to 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,000; `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 description must justify it, and 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. diff --git a/docs/rfc/implemented/process/2026-07-04-doc-tiers-and-budgets.md b/docs/rfc/implemented/process/2026-07-04-doc-tiers-and-budgets.md index 8c5c62ed58..428de5deaa 100644 --- a/docs/rfc/implemented/process/2026-07-04-doc-tiers-and-budgets.md +++ b/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`. 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 diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index a302493b9c..bd972fad7a 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,8 +1,8 @@ { - "AGENTS.md": 8134, - "docs/AGENTS.md": 982, - "docs/architecture.md": 3897, - "examples/AGENTS.md": 579, - "packages/AGENTS.md": 577, - "packages/README.md": 1856 + "AGENTS.md": 8545, + "docs/AGENTS.md": 1050, + "docs/architecture.md": 4095, + "examples/AGENTS.md": 610, + "packages/AGENTS.md": 610, + "packages/README.md": 1950 } diff --git a/scripts/verify-doc-budgets.ts b/scripts/verify-doc-budgets.ts index fb27e84473..1ace894410 100644 --- a/scripts/verify-doc-budgets.ts +++ b/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