[FEATURE] Persistent governance context to address context dilution

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Developer-editable instructions (CLAUDE.md, hook output) share the context window with working content. As sessions grow, instructions dilute. At 15KB of instructions in 500KB of conversation, they occupy 3% of context and sit furthest from the model's recency bias. Rules followed at session start stop being followed after sustained work; not by decision, but by distance.

Compaction discards instruction text alongside working content. On 1M context windows, compaction may never fire, removing the only hook-triggerable re-orientation boundary.

I maintain a structured instruction set (~15KB) loaded via hooks. Instructions govern coding standards, file routing, session state, and style rules. These instructions must apply consistently throughout a session, not only at the start.

Proposed Solution

A persistent governance context: a small, developer-defined region the model processes every turn, separate from the conversation context.

A designated file (~/.claude/GOVERNANCE.md or a project-level equivalent) whose contents the system injects into a privileged position on every turn, alongside the system prompt, but developer-controlled. Not conversation context. Not subject to compaction or summarisation.

Required properties:

| Property | Requirement |
|---|---|
| Fixed-size | Bounded (~15KB); cannot grow with conversation |
| Always-visible | Processed every turn, not only at session start |
| Non-dilutable | Maintains priority regardless of conversation length |
| Refreshable | Updatable mid-session via hooks or commands |
| Separate from context | Outside the message stream; not subject to compaction or summarisation |

Contents (developer-defined): the subset of instructions that must govern every turn. Examples: coding standards, style rules, forbidden patterns; routing rules (what files to read before starting work); session state (current task, active plan); diagnostic markers that detect instruction-following failure.

Alternative Solutions

Current mitigations, all of which delay dilution but cannot prevent it:

• SessionStart hook injects core instructions at session open
• PostCompact hook re-injects the same instructions after compaction
• Manual /compact as a deliberate boundary between tasks
• Planned refresh points at task boundaries re-orient the model to its instructions

Re-injected instructions enter the context window and begin diluting again immediately. The model cannot discard context; only a person or the system (at limits) can remove it.

Why existing mechanisms fall short:

| Mechanism | Limitation |
|---|---|
| System prompt | Not developer-editable; Anthropic-controlled |
| CLAUDE.md | Loaded as context; dilutes with growth; sometimes skipped (#44329) |
| SessionStart hook | Output enters context; dilutes over time |
| PostCompact hook | Re-injects after compaction; same dilution applies |
| Extended thinking | Generated fresh each turn; no persistence; no privileged input |
| MCP servers | Demand-driven (model calls them); not supply-driven governance |

Priority

Critical. This is the structural limitation that all other mitigations work around. Every workaround adds context volume, which accelerates the problem it tries to solve.

Priority

Critical - Blocking my work

Feature Category

API and model interactions

Use Case Example

1. Session starts. SessionStart hook injects ~8KB of instructions: coding standards, file routing table, active task state, style rules.
2. Work proceeds. After ~100K tokens of conversation (reading files, writing code, discussing decisions), the instructions occupy less than 8% of context and sit at maximum distance from the current turn.
3. Style rules stop being followed. The model writes "user" in documentation where the style guide requires "person". Code patterns drift from documented conventions. File routing is skipped.
4. I notice and trigger a manual refresh. The model re-reads instruction files, adding another ~8KB to context. Compliance recovers briefly.
5. Work continues. The refresh text itself begins to dilute. By ~300K tokens, even recent refreshes lose priority. I must choose between compacting (losing working context) or accepting degraded instruction-following.
6. At ~400K tokens, instruction-following fray is consistently observable. I trigger /compact, losing working context, to restore compliance via PostCompact hook re-injection.

With a persistent governance context, steps 3–6 do not occur. The 8-15KB of instructions maintain consistent priority regardless of conversation length.

Additional Context

Related issues:

• #35309 (instructions disregarded mid-session despite confirmation)
• #19471 (CLAUDE.md instructions ignored after context compaction)
• #44329 (CLAUDE.md sometimes skipped at session start)
• #44465, #44461, #44431 (instructions ignored under context pressure)
• #42796 (thinking depth regression; read-to-edit ratio collapse in long sessions)

Calibration data: first observed consistent instruction-following fray at ~398K tokens (1M context window, Opus model, ~15KB instruction set). Fray manifests as style guide violations, skipped file reads, and routing table non-compliance.

Platform optimisations compound the problem: the Read tool caches previously read files and refuses to re-read them if it considers the content unchanged. The cache persists across compaction; it tracks the entire process lifetime, not the context window. A developer who re-reads an instruction file for re-orientation (bringing it back to the recency window after dilution) gets a stub response instead of the file contents. The optimisation treats re-orientation and change detection as identical, suppressing the one that matters most under context pressure. This is the same structural pattern: the system enforces efficiency at a layer below where the developer can intervene, and the enforcement undermines the developer's ability to maintain instruction priority.

Design constraint: the governance context must be fixed-size to prevent developers from recreating the dilution problem by stuffing unbounded content into the privileged region.