[Feature] Rules-governance diagnostics for CLAUDE.md / .claude/rules: instruction-budget warnings, duplication & conflict detection

Motivation

CLAUDE.md is explicitly advisory — the memory docs state "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead" and "there's no guarantee of strict compliance, especially for vague or conflicting instructions."

That is a defensible philosophy. But it means the only feedback loop for rule-file quality is the user noticing rules get ignored — and by then the damage has compounded. As instruction count grows, adherence degrades uniformly across all instructions, not just the newest ones. HumanLayer's analysis (Writing a good CLAUDE.md) found frontier models reliably follow roughly 150–200 instructions; Claude Code's own system prompt already consumes ~50 of those. Beyond the budget, "it doesn't simply ignore the newer instructions — it begins to ignore all of them uniformly."

This is also empirically documented, not folklore. ETH Zurich's Evaluating AGENTS.md (arXiv:2602.11988) found context files are well followed by coding agents — the failure comes from unnecessary requirements making tasks harder, while inference cost rises >20% on average. Bloat is not neutral; it is actively harmful and expensive, and nothing in the tool surfaces it.

Real user data (self-documented heavy-user harness)

A heavy user's rule stack (SOUL.md / AGENTS.md / skills) grew from 58 lines to 92 lines / 12 KB in 5 days. The maintenance failure pattern: the same rule was re-stated 3 times across files, yet a corrected version was applied only once — classic uniform-degradation behavior. No built-in tool surfaced the duplication, the growth rate, or the approach toward the instruction budget. The user ended up hand-rolling a three-layer architecture (hooks for enforcement / a small high-frequency recall layer / on-demand skills) plus external lint scripts — all to manage state the harness never measures.

This is a class of problem, not one report

• #82184 (open): project rules treated as advisory, enforcement hooks self-neutralize, compaction drops governance while preserving narrative, auto-memory outranks project instructions — plus its referenced family (#47565, #40459, #19471, #21119, #7777, #15443, #34197, #43557).
• #23075 / #4960 (self-improving CLAUDE.md): closed by staleness automation with no maintainer response. This proposal is deliberately NOT that: we are not asking for self-modification, which has real prompt-injection implications (Anthropic's containment post lists persistent memory including CLAUDE.md files as an injection persistence vector reloaded each session).

Proposal: extend /doctor with read-only rules diagnostics

1. Instruction-budget meter — estimate instruction count across CLAUDE.md + .claude/rules/*.md + loaded skills; warn when the user share approaches the ~100–150 budget remaining after the system prompt's ~50. Read-only estimate, no model call needed.
2. Duplication detector — flag the same/similar rule text across files (user CLAUDE.md vs project CLAUDE.md vs .claude/rules/*.md vs auto-memory), with a "single source of truth" suggestion per cluster.
3. Conflict detector — flag contradictory instructions within/across files — "vague or conflicting instructions" is the exact failure mode the docs disclaim.
4. Bloat/staleness signal — line-count trend plus hints for rules likely superseded by model capability (e.g. personality instructions, which the community and Anthropic's own context-engineering guide say are removable).

Deliberately not included: any form of autonomous rule editing. Diagnostics only — no new self-modification surface, no added injection risk.

Expected impact

Power users currently hand-roll this. First-class diagnostics in /doctor would (a) close the feedback loop the advisory design never had, (b) align with the documented "the more specific and concise your instructions, the more consistently Claude follows them", and (c) shrink the 60+ open "rules ignored" issue family by making the problem visible before it compounds.

Happy to provide more real-world examples or test against the nightly build.