docs: slim CLAUDE.md to a 76-line core + pointer-loaded docs/areas, with CI budget guards

[zbigniewsobiecki]

Summary

CLAUDE.md (with AGENTS.md symlinked to it) is loaded into every Claude Code session and cat-injected when a CASCADE context pipeline includes contextFiles — inline only while under CONTEXT_OFFLOAD_CONFIG.inlineThreshold (src/agents/utils/setup.ts:readContextFiles → src/backends/shared/contextFiles.ts). It had grown to 217 lines plus 95 KB of @-imports (≈31k tokens per interactive session, 7.2k tokens whenever contextFiles ran, 89 % of the silent-offload cliff), ~44 % duplicated docs/architecture/* / in-tree READMEs, and the ## Git hooks section described hooks that don't exist.

This PR cuts it to a 76-line / ~1.7k-token core and moves path-scoped rules to engine-neutral pointer docs under docs/areas/, with CI guards so it can't re-accrete.

	Before	After
CLAUDE.md	217 lines · 28.9 KB · ~7.2k tokens	76 lines · 6.9 KB · ~1.7k tokens
Loaded per interactive session (incl. @ imports)	~124 KB · ~31k tokens	6.9 KB · ~1.7k tokens
Injected when contextFiles runs	7,223 tokens (cliff at 8,000)	1,709 tokens
src/integrations/README.md	700 lines · 72 KB	643 lines · 64 KB

What changed

• CLAUDE.md — 3-service table, commands, gotchas (incl. the corrected lefthook.yml contract: pre-commit = Biome + tsc + auth-header-provenance test; commit-msg = commitlint; pre-push = npm run test:fast), six hard invariants, an environment pointer to .env.example, a "before you touch an area, read" table, and a placement rule. Zero @ imports. AGENTS.md symlink untouched.
• docs/areas/{pm-integrations,router-dispatch,agents,backends}.md — 11–34 lines each; imperatives + links, never restatements. CASCADE runs that include contextFiles, plus interactive Claude Code, reach them through the same pointer table. (.claude/rules/ was rejected because all three engines suppress native instruction discovery, so workers would never see it.)
• Only-home facts placed before deletion — PR checkout by refs/pull/N/head → 01-services; review-context budget & debugging (REVIEW_DIFF_CONTEXT_TOKEN_LIMIT, PR context prepared fields, informational CI status) → 03-trigger-system; claimReviewDispatch, UnrecoverableError, reviewer-persona check, formatCrashReason → 03/10-resilience; integration-DB discovery chain (previously only in code) → tests/README.md; PM_COALESCE_WINDOW_MS → .env.example.
• CI guards (tests/unit/architecture-docs.test.ts, TDD — red before the rewrite): ≤ 200 lines; estimateTokens < 0.5 × CONTEXT_OFFLOAD_CONFIG.inlineThreshold (derived from the real constant); no @ imports outside code spans; no ticket IDs / spec numbers / dates in CLAUDE.md or docs/areas/; every area doc ≤ 60 lines, opens with **Applies to:**, and is linked from the root. SECURITY.md / CONTRIBUTING.md added to the link-validated set. tests/unit/repo-hygiene.test.ts pins the shared root/web/ Zod major.
• src/integrations/README.md — spec-changelog preamble, "Provider migration status" and "Post-spec-010/011/012" tables removed (durable facts folded into the current-state sections: 7th StandardStepKind, shared-step optional props, renderStandardStep); the duplicate behavioral-contract table merged into the harness section; JIRA authType now has one home here, with 08-config-credentials and getting-started pointing at it.
• Pointer fixes — SECURITY.md dead anchor, README.md, CONTRIBUTING.md (commitlint is the commit-msg hook), docs/ARCHITECTURE.md, .env.example. CHANGELOG.md entry added.
• documentation-maintenance.eta — no longer tells agents to append env vars to CLAUDE.md; wording kept generic (it serves every target repo). Pinned literals in tests/unit/agents/prompts.test.ts preserved.

Verification

• npm run verify — Biome clean, tsc clean, 620 test files / 11,212 tests passed (3 pre-existing skips).
• Worker path: readContextFiles('.') → one entry (CLAUDE.md, 6,835 chars ≈ 1.7k tokens, well under the 8k inline threshold).
• git ls-files -s AGENTS.md → still mode 120000; AGENTS.md === CLAUDE.md guard passes.
• Every deleted paragraph was grep-verified to survive in its named home before removal.

Operator follow-up

• Prompt partials resolve DB-first (src/agents/prompts/index.ts): run npm run db:seed-prompts after deploying so the edited documentation-maintenance partial replaces the seeded copy.
• Optional later add: thin .claude/rules/<area>.md stubs with paths: frontmatter saying "read docs/areas/<area>.md" would give interactive sessions auto-triggering while keeping content engine-neutral. Not included here.

Notes for the reviewer

• Directory is named docs/areas/ ("agent" is the most overloaded noun in this repo). Trivial to rename.
• Research behind the approach: Claude Code docs target < 200 lines and note imports don't save context; 2026 studies on repository context files (arXiv 2602.11988, 2607.27250, 2605.10039) find instructions are followed but repository overviews are not, and file-structure variables have null effect — hence delete + pointers rather than rearrange.

🤖 Generated with Claude Code

[nhopeatall]

⚠️ review agent failed

Error: Claude Code returned an error result: You've hit your weekly limit · resets 11pm (UTC)

_{Manual intervention may be required.}

[nhopeatall]

⚠️ review agent failed

Error: Claude Code returned an error result: You've hit your weekly limit · resets 11pm (UTC)

_{Manual intervention may be required.}

[nhopeatall]

⚠️ review agent failed

Error: Claude Code returned an error result: You've hit your weekly limit · resets 11pm (UTC)

_{Manual intervention may be required.}