[meta] Soften AGENTS.md §9 "Single Full-Read Rule" framing for frontier-context-era models (preserve efficiency guidance)

The Finding

AGENTS.md §9 "Preventing Context Corruption (State Management)" currently reads:

Working on the Neo platform requires long, complex sessions. To prevent your context window from becoming corrupted with multiple competing versions of the same file after several edits, you MUST adhere to this protocol:

1. The Single Full-Read Rule: You should generally only perform a full read_file on a specific file once per session to establish your baseline understanding.
2. Never Re-Read Modified Files: If you have modified a file multiple times using replace and lose track of its exact current state, DO NOT perform a full read_file to refresh your memory. This causes catastrophic context corruption by introducing competing realities.

The efficiency motivation (use git diff over re-read when possible — cheaper, clearer delta) remains correct. The corruption framing is context-scarcity-era thinking: frontier models (Opus 4.7 at 1M context; Claude Sonnet 4.6; Gemini 3.1 Pro) disambiguate multiple file versions by context ordering without "catastrophic corruption." The word "catastrophic" overstates the risk for frontier models and undersells the legitimate efficiency point.

Surfaced Via

Session 62d6f155-e57f-4279-9b59-36c9e4ecbc5e (2026-04-19). While running an audit for context-scarcity-era rules in AGENTS.md at tobi's request, identified §9's framing as the one concrete finding. The 25-turn Guardrail (§10.6) was initially flagged but corrected — it's thrashing-detection, not context-budget, and remains well-calibrated across model eras.

Multi-Harness Constraint (why this is a Fat Ticket, not find-and-replace)

One AGENTS.md loads identically into every harness: Claude Code, Antigravity, Gemini CLI, and into agents running smaller local models (e.g., gemma4-31b via MLX per AGENTS_STARTUP.md §7 agent profiles). Smaller-context harnesses MAY still benefit from strict single-full-read discipline because re-reading a large file genuinely does eat their budget.

The fix must be conditional or dual-framed, not a blanket relaxation. Two candidate shapes:

Option A — Reframe with efficiency as primary motivation:

1. The Single Full-Read Rule (Efficiency): Prefer git diff or surgical grep_search with context over a full re-read when reconciling the current state of a file you've modified. Full re-reads are wasteful when a delta is available; on smaller-context models they also risk "competing realities" confusion.

Keeps the guidance, softens "catastrophic" to "wasteful + risk on smaller models," makes the rule model-capability-aware without naming specific models.

Option B — Explicit per-capability split:

1. The Single Full-Read Rule:
   • Frontier models (≥200k context, e.g., Opus 4.7, Sonnet 4.6, Gemini 3.1 Pro): prefer git diff for reconciliation as an efficiency discipline — not a correctness requirement. Re-reading modified files is tolerable if delta extraction would be harder.
   • Smaller models (<200k context, local inference): adhere strictly to the Single Full-Read Rule — full re-reads after edits genuinely risk competing-reality confusion at smaller context budgets.

More prescriptive but named-model-specific, which ages with the model lineup.

Lean A — safer against model-era drift, preserves the rule's intent, still model-aware.

Acceptance Criteria

• AGENTS.md §9 reframed to separate efficiency discipline (preserved, universal) from corruption framing (softened, made capability-aware)
• "Catastrophic context corruption" language removed or scoped to smaller-context models explicitly
• No other rules in §9 (use git diff, use grep_search, No Shell Fallbacks) touched — those remain universally correct
• Cross-reference the fix in the durable feedback memory chain (feedback_verify_written_claims_against_precedent.md) as the canonical example of an operational-heuristic correction

Scope Exclusions

• Other AGENTS.md rules (25-turn guardrail, etc.) — audited and confirmed still-correct in this session
• Per-skill context-budget guidance (e.g., neural-link/operational-handbook.md depth limits) — those are API-response-size pragmatic defaults, not context-era rules, and remain correct

Related

• AGENTS.md §9 — the target rule
• feedback_verify_written_claims_against_precedent.md — the class of discipline failure this audit and fix formalize
• #10079 — the prospective Hypothesis gate strengthening that would prevent future similar rules from landing un-audited
• Session 62d6f155 turns where this was surfaced

Origin Session ID

62d6f155-e57f-4279-9b59-36c9e4ecbc5e