Tooling: Add claude-md-length check to keep auto-injected CLAUDE.md docs lean

The CLAUDE.md/DETAILS.md split moved depth into the pull tier, but nothing stopped the push-tier `CLAUDE.md` files (auto-injected into agent context, so every word costs tokens in every session that touches the area) from regrowing. This warn-only check guards the ~600-word budget.

- New `claude-md-length` check (warn-only, never fails the suite, `IsFast`, `NotInCI`): warns when any `CLAUDE.md` exceeds 600 words. `DETAILS.md` is the deliberately-unlimited pull tier and is NOT scanned. Reuses `findClaudeMdFiles` and `strings.Fields` (matches `wc -w`).
- `claude-md-length-allowlist.json` seeded with the 66 `CLAUDE.md` files currently over 600 words at their current counts. Mirrors file-length's allowlist semantics exactly: suppress up to recorded count + 10% buffer, local-run shrink-wrap (drop dead/under-threshold, ratchet >10% slack down), CI report-only. Adding/raising an entry needs explicit consent; the fix for an oversized doc is to move depth into `DETAILS.md`.
- Go tests cover word counting, detection, DETAILS.md exclusion, allowlist suppress/buffer/exceed, and every shrink-wrap verdict (dead/under-threshold/ratchet/small-slack/CI-report-only).
- Wired per the registry↔CI contract via a `NotInCI` reason (warn-only metrics carry no workflow step), so `ci-coverage` stays green. Extended `.claude/rules/file-length-allowlist.md` and the check-authoring docs; AGENTS.md now notes the budget is watched.

Author: vdavid

.claude/rules/file-length-allowlist.md

@@ -14,3 +14,9 @@ The `exempt` section is for generated files whose length is not actionable (for
 reason and the same consent rule applies to adding one.
 
 The file-length check is warn-only — it doesn't fail the suite — so leaving the warning is always safe.
+
+The same contract applies to `scripts/check/checks/claude-md-length-allowlist.json` (the `claude-md-length` check, which
+caps push-tier CLAUDE.md word counts): the check shrink-wraps stale `files` entries on local runs (remove gone /
+under-threshold, ratchet >10% slack down), and adding or raising an entry needs explicit user consent. If a CLAUDE.md
+you're touching exceeds its allowlisted word count, move depth into the colocated `DETAILS.md` rather than bumping the
+number; leaving the warn is safe (it's warn-only too).

AGENTS.md

@@ -100,10 +100,11 @@ Core structure:
   directory are read, so every word costs tokens in every session that touches the area. `DETAILS.md` is the pull tier:
   the area's real docs, read on demand. The litmus: could an agent editing a random file here silently break something
   without this line? Then it's `CLAUDE.md`. Everything else is `DETAILS.md`. So `CLAUDE.md` = invariants, gotchas,
-  don't-do-X-because-Y, a 2–3 line module map, and a pointer; target ~400–600 words. `DETAILS.md` = architecture
-  narrative, data flows, decision rationale with depth, edge-case catalogs. Read it in whole before structural changes
-  in an area. Never `@`-import `DETAILS.md` from a `CLAUDE.md` (that would rebuild the auto-load cost the split exists
-  to remove). See `docs/architecture.md` for the full map.
+  don't-do-X-because-Y, a 2–3 line module map, and a pointer; target ~400–600 words, watched by the warn-only
+  `claude-md-length` check (its allowlist tracks files already over 600 words). `DETAILS.md` = architecture narrative,
+  data flows, decision rationale with depth, edge-case catalogs. Read it in whole before structural changes in an area.
+  Never `@`-import `DETAILS.md` from a `CLAUDE.md` (that would rebuild the auto-load cost the split exists to remove).
+  See `docs/architecture.md` for the full map.
 
 ## Testing and checking
 
@@ -141,7 +142,7 @@ always runs fresh. See the input-fingerprint cache section in `scripts/check/CLA
   - Go: `go-vet`, `staticcheck`, `ineffassign`, `misspell`, `gocyclo`, `go-tests`.
   - API server: `typecheck`, `tests`.
   - Website: `html-validate`, `bundle-size` (both self-skip when `dist/` is absent).
-  - Warn-only metrics: `file-length`, `claude-md-reminder`, `changelog-links`.
+  - Warn-only metrics: `file-length`, `claude-md-reminder`, `claude-md-length`, `changelog-links`.
   - **Does NOT cover**: `clippy`, Rust tests, `cargo-audit`, `cargo-deny`, `jscpd`, `bindings-fresh`, desktop ESLint /
     `svelte-check` / Svelte tests, website ESLint / typecheck / build / e2e, `docker-build`, or any E2E suite.
 - **`pnpm check` — before every commit.** The full default suite (everything not marked `IsSlow`). Catches what `--fast`

scripts/check/checks/CLAUDE.md

@@ -16,7 +16,8 @@ see [`../CLAUDE.md`](../CLAUDE.md).
   `scripts-go-*`).
 - `inputs.go`: shared `Inputs` building blocks. `allowlist.go` / `directives.go`: allowlist shrink-wrap + opt-out
   tracking plumbing.
-- Warn-only scanners with their JSON allowlists: `file-length.go`, `e2e-durations.go`, `website-bundle-size.go`.
+- Warn-only scanners with their JSON allowlists: `file-length.go`, `claude-md-length.go`, `e2e-durations.go`,
+  `website-bundle-size.go`.
 
 ## Must-knows
 

scripts/check/checks/DETAILS.md

@@ -16,6 +16,8 @@ freestyle.sh remote execution), see [`../CLAUDE.md`](../CLAUDE.md).
 | `website-*.go`, `api-server-*.go`, `scripts-go-*.go` | One file per check                                                                                                                                                                                                    |
 | `file-length.go`                                     | Informational file-length scanner (warn-only, never fails). Supports an allowlist and shrink-wraps it on local runs.                                                                                                  |
 | `file-length-allowlist.json`                         | Allowlist for file-length check: `{ "exempt": { "path": reason }, "files": { "path": lineCount } }`. See § File-length allowlist.                                                                                     |
+| `claude-md-length.go`                                | Warn-only push-tier scanner: warns when a `CLAUDE.md` exceeds 600 words (`DETAILS.md` is the unlimited pull tier, not scanned). Allowlist with the same shrink-wrap semantics as file-length. See § CLAUDE.md length. |
+| `claude-md-length-allowlist.json`                    | Allowlist for claude-md-length: `{ "files": { "path": wordCount } }`. Same ratchet/consent rules as file-length.                                                                                                      |
 | `e2e-durations.go`                                   | E2E test duration flagger (warn-only): parses the Playwright JSON reports after each E2E run and flags tests over the 2 s budget. Embedded in both E2E checks, not a registry check. See § E2E test duration flagger. |
 | `e2e-duration-allowlist.json`                        | Per-platform (`macos` / `linux`) allowlist for the duration flagger: `{ "<spec>::<describe chain>::<title>": reason }`. Entries need a reason; new entries need David's OK.                                           |
 | `website-bundle-size.go`                             | Warn-only website `dist/` size budget: warns when the total grows >10% over the committed baseline. Self-skips without `dist/`. See § Website bundle-size baseline.                                                   |
@@ -169,6 +171,20 @@ mirrors the growth buffer so routine small edits don't churn the JSON.
 See `.claude/rules/file-length-allowlist.md` (repo-level) for when an entry may be raised vs lowered without user
 consent.
 
+## CLAUDE.md length
+
+`claude-md-length` (warn-only, `IsFast`) keeps the push tier lean: it warns when any `CLAUDE.md` exceeds 600 words. Each
+`CLAUDE.md` is auto-injected into every agent session that touches its directory, so words there cost tokens repeatedly;
+depth belongs in the colocated `DETAILS.md` (the pull tier), which is deliberately unlimited and NOT scanned. The check
+reuses `findClaudeMdFiles` (same walk as `claude-md-reminder`, so only files named `CLAUDE.md` count) and
+`strings.Fields` for the word count (matches `wc -w`, so seeded counts and the check agree).
+
+`claude-md-length-allowlist.json` has one `files` section mapping path → accepted word count, with the exact same
+shrink-wrap and consent discipline as file-length: a file is suppressed up to its recorded count plus a 10% buffer;
+local runs drop dead/under-threshold entries and ratchet >10%-slack entries down; CI reports what a local run would
+change. Adding or raising an entry needs David's OK (`.claude/rules/file-length-allowlist.md`); the fix for an oversized
+`CLAUDE.md` is to move depth into `DETAILS.md`, not bump the number.
+
 ## E2E test duration flagger
 
 The E2E suites were hard-won down to under 2 s per test; `e2e-durations.go` defends that. After a successful E2E run,
@@ -245,7 +261,7 @@ RUSTSEC ignores — that's a quarterly task in `docs/maintenance.md`.
 | Website    | Docker   | docker-build                                                                                                                                                                                                                                                              |
 | API server | TS       | oxfmt, eslint, typecheck, tests                                                                                                                                                                                                                                           |
 | Scripts    | Go       | gofmt, go-vet, staticcheck, ineffassign, misspell, gocyclo, nilaway, deadcode, go-tests, govulncheck                                                                                                                                                                      |
-| Other      | Metrics  | file-length (warn-only), CLAUDE.md-reminder (warn-only), changelog-commit-links, workflows-rustup (forbids `rustup target/component add` in workflows), ci-coverage (registry-to-workflows contract)                                                                      |
+| Other      | Metrics  | file-length (warn-only), CLAUDE.md-reminder (warn-only), claude-md-length (warn-only), changelog-commit-links, workflows-rustup (forbids `rustup target/component add` in workflows), ci-coverage (registry-to-workflows contract)                                        |
 | Other      | Security | workflows-hardening (SHA-pinning, no `pull_request_target`, job-scoped `id-token: write`)                                                                                                                                                                                 |
 
 ## Key decisions

scripts/check/checks/claude-md-length-allowlist.json

@@ -0,0 +1,71 @@
+{
+  "$comment": "Files under `files` are exempt from the claude-md-length warning up to their recorded word count (plus a 10% growth buffer). The push-tier CLAUDE.md is auto-injected into agent context, so it has a ~600-word budget; deeper docs belong in the pull-tier DETAILS.md, which is unlimited and not checked. The check shrink-wraps stale entries on local runs: dead entries and files back under the threshold are removed, and entries with more than 10% slack are ratcheted down to the file's current count. See `.claude/rules/file-length-allowlist.md`.",
+  "files": {
+    "apps/analytics-dashboard/CLAUDE.md": 1059,
+    "apps/desktop/scripts/CLAUDE.md": 703,
+    "apps/desktop/src-tauri/capabilities/CLAUDE.md": 1136,
+    "apps/desktop/src-tauri/src/analytics/CLAUDE.md": 1518,
+    "apps/desktop/src-tauri/src/commands/CLAUDE.md": 2229,
+    "apps/desktop/src-tauri/src/crash_reporter/CLAUDE.md": 950,
+    "apps/desktop/src-tauri/src/downloads/CLAUDE.md": 929,
+    "apps/desktop/src-tauri/src/file_system/listing/CLAUDE.md": 2395,
+    "apps/desktop/src-tauri/src/file_system/volume/friendly_error/CLAUDE.md": 1409,
+    "apps/desktop/src-tauri/src/file_system/write_operations/delete/CLAUDE.md": 1231,
+    "apps/desktop/src-tauri/src/file_system/write_operations/transfer/CLAUDE.md": 602,
+    "apps/desktop/src-tauri/src/font_metrics/CLAUDE.md": 756,
+    "apps/desktop/src-tauri/src/go_to_path/CLAUDE.md": 676,
+    "apps/desktop/src-tauri/src/icons/CLAUDE.md": 1322,
+    "apps/desktop/src-tauri/src/indexing/CLAUDE.md": 681,
+    "apps/desktop/src-tauri/src/licensing/CLAUDE.md": 1584,
+    "apps/desktop/src-tauri/src/logging/CLAUDE.md": 1234,
+    "apps/desktop/src-tauri/src/mcp/executor/CLAUDE.md": 1352,
+    "apps/desktop/src-tauri/src/mtp/CLAUDE.md": 1221,
+    "apps/desktop/src-tauri/src/mtp/connection/CLAUDE.md": 683,
+    "apps/desktop/src-tauri/src/native_drag/CLAUDE.md": 1654,
+    "apps/desktop/src-tauri/src/network/CLAUDE.md": 663,
+    "apps/desktop/src-tauri/src/quick_look/CLAUDE.md": 1218,
+    "apps/desktop/src-tauri/src/redact/CLAUDE.md": 1023,
+    "apps/desktop/src-tauri/src/search/CLAUDE.md": 1115,
+    "apps/desktop/src-tauri/src/search/ai/CLAUDE.md": 733,
+    "apps/desktop/src-tauri/src/secrets/CLAUDE.md": 752,
+    "apps/desktop/src-tauri/src/selection/CLAUDE.md": 785,
+    "apps/desktop/src-tauri/src/selection/ai/CLAUDE.md": 770,
+    "apps/desktop/src-tauri/src/settings/CLAUDE.md": 835,
+    "apps/desktop/src-tauri/src/updater/CLAUDE.md": 811,
+    "apps/desktop/src-tauri/src/volumes/CLAUDE.md": 2101,
+    "apps/desktop/src-tauri/src/volumes_linux/CLAUDE.md": 807,
+    "apps/desktop/src/lib/ai/CLAUDE.md": 959,
+    "apps/desktop/src/lib/command-palette/CLAUDE.md": 1486,
+    "apps/desktop/src/lib/commands/CLAUDE.md": 2355,
+    "apps/desktop/src/lib/downloads/CLAUDE.md": 2165,
+    "apps/desktop/src/lib/error-reporter/CLAUDE.md": 964,
+    "apps/desktop/src/lib/file-explorer/git/CLAUDE.md": 855,
+    "apps/desktop/src/lib/file-explorer/network/CLAUDE.md": 2421,
+    "apps/desktop/src/lib/file-explorer/pane/CLAUDE.md": 753,
+    "apps/desktop/src/lib/file-explorer/rename/CLAUDE.md": 992,
+    "apps/desktop/src/lib/file-explorer/selection/CLAUDE.md": 1634,
+    "apps/desktop/src/lib/file-explorer/tabs/CLAUDE.md": 1405,
+    "apps/desktop/src/lib/file-operations/delete/CLAUDE.md": 807,
+    "apps/desktop/src/lib/file-viewer/CLAUDE.md": 1129,
+    "apps/desktop/src/lib/font-metrics/CLAUDE.md": 649,
+    "apps/desktop/src/lib/go-to-path/CLAUDE.md": 1223,
+    "apps/desktop/src/lib/indexing/CLAUDE.md": 1535,
+    "apps/desktop/src/lib/licensing/CLAUDE.md": 1063,
+    "apps/desktop/src/lib/logging/CLAUDE.md": 707,
+    "apps/desktop/src/lib/query-ui/filter-chips/CLAUDE.md": 1586,
+    "apps/desktop/src/lib/selection-dialog/CLAUDE.md": 1306,
+    "apps/desktop/src/lib/settings/components/CLAUDE.md": 1103,
+    "apps/desktop/src/lib/tauri-commands/CLAUDE.md": 889,
+    "apps/desktop/src/lib/ui/CLAUDE.md": 654,
+    "apps/desktop/src/lib/updates/CLAUDE.md": 1391,
+    "apps/desktop/src/lib/utils/CLAUDE.md": 1147,
+    "apps/desktop/src/routes/(main)/CLAUDE.md": 1736,
+    "apps/desktop/src/routes/viewer/CLAUDE.md": 2461,
+    "apps/desktop/test/CLAUDE.md": 723,
+    "apps/desktop/test/e2e-linux/CLAUDE.md": 2381,
+    "apps/desktop/test/e2e-playwright/CLAUDE.md": 666,
+    "apps/desktop/test/e2e-shared/CLAUDE.md": 777,
+    "apps/website/CLAUDE.md": 1196,
+    "apps/website/public/hero/CLAUDE.md": 940
+  }
+}