---
number: 10720
title: >-
  docs(agents): soften §9 corruption framing for frontier-context models
  (#10083)
author: neo-opus-ada
state: MERGED
createdAt: '2026-05-04T21:32:15Z'
updatedAt: '2026-05-04T21:48:36Z'
closedAt: '2026-05-04T21:48:32Z'
mergedAt: '2026-05-04T21:48:32Z'
head: agent/10083-soften-single-full-read-framing
base: dev
url: 'https://github.com/neomjs/neo/pull/10720'
---
Resolves #10083

Authored by Claude Opus 4.7 (Claude Code). Session \`7e52099b-9632-4c67-a2a1-4e1a1ad1c414\`.

Reframes \`AGENTS.md §9\` from \"Preventing Context Corruption\" to \"Reading Modified Files Efficiently\" per the ticket's Option A direction. The efficiency discipline (prefer \`git diff\` / \`grep_search\` over full re-reads) was correct under both context-scarcity-era and frontier-context-era assumptions; the \"catastrophic context corruption\" framing was scarcity-era thinking that overstated correctness risk for frontier models (Opus 4.7 1M, Sonnet 4.6, Gemini 3.1 Pro empirically disambiguate multiple file versions by context ordering).

Evidence: L1 (static doc-prose change; AGENTS.md §9 framing only, no behavioral contract change for any swarm-discipline rule) → L1 required (no runtime-verify ACs). No residuals.

## What changed

- **Heading reframed:** \"Preventing Context Corruption (State Management)\" → \"Reading Modified Files Efficiently (State Management)\".
- **Intro reframed:** \"To prevent your context window from becoming corrupted...\" → \"use the cheapest authoritative source rather than a full re-read. The discipline is *efficiency-first* — universal across models — with an additional correctness consideration on smaller-context harnesses.\"
- **Rules 1+2 of original combined** into a single \"Single Full-Read Rule (Efficiency-First)\" that:
  - Frames efficiency as the universal motivation.
  - Notes the additional \"competing realities\" correctness risk on smaller-context models *without naming specific model versions* (per Option A's lean — capability-aware framing without naming specific models that age with the lineup).
  - Removes \"catastrophic\" language; on larger-context models the cost is \"wasted attention rather than correctness.\"
- **Rules 3-5 (renumbered to 2-4)** preserved verbatim: \`git diff\` for Reconciliation, \`grep_search\` for Method Verification, No Shell Fallbacks. Per AC3, those remain universally correct.

## AC coverage

- [x] AC1: efficiency discipline (preserved, universal) separated from corruption framing (softened, capability-aware) — see intro paragraph + new rule 1 wording.
- [x] AC2: \"catastrophic context corruption\" removed; \"competing realities\" scoped to smaller-context models with an explicit larger-context counterpart noting wasted-attention-not-correctness.
- [x] AC3: rules \`git diff\` / \`grep_search\` / No Shell Fallbacks not touched (renumbered only).
- [ ] AC4: cross-reference in durable feedback memory chain — handled post-PR via memory file update (harness-private substrate, not part of the PR diff per AGENTS.md §11 Substrate Awareness).

## Contract Ledger

| Target Surface | Source of Authority | Proposed Behavior | Fallback / Edge Case | Docs | Evidence |
|---|---|---|---|---|---|
| AGENTS.md §9 framing | Issue #10083 + @tobiu's challenge note (2026-04-19) | Reframe corruption-prevention → efficiency-first; capability-aware language | Action contract preserved (rules 2-4 verbatim); no agent behavior change | Yes (this is the doc) | Before/after diff inspection |

Trigger fit per \`contract-ledger.md\`: borderline — swarm-discipline doc with framing change but no observable action-contract change. Including a minimal matrix to satisfy the gate without bloat. Tier elevation: T1 → T3 (the rule was implicit; now it's an Explicit Matrix-backed contract).

## Out of Scope

- Other AGENTS.md rules (25-turn guardrail, §0 Critical Gates, etc.) — audited in #10083's surfacing session and confirmed still-correct across model eras.
- 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.
- Compression of AGENTS.md as a whole — separate strategic concern (#10537 family + future epic).

## Avoided Traps

- **Rejected: Option B (named-model split).** Per ticket lean — naming specific model versions (Opus 4.7, Sonnet 4.6, Gemini 3.1 Pro) ages poorly with the lineup. Option A's capability-aware framing without specific model names is durable.
- **Rejected: blanket relaxation.** Smaller-context harnesses (e.g., \`gemma4-31b\` via MLX per AGENTS_STARTUP.md §7) genuinely benefit from strict re-read avoidance. The fix retains the discipline; it just stops overstating the severity for larger-context models.
- **Rejected: rule deletion.** The action contract is correct on all model tiers; only the framing was scarcity-era. Deleting the rule would lose the genuine efficiency discipline.

## Test Evidence

This is a doc-only change to AGENTS.md prose. No tests required; no code paths change. Verified via \`git diff AGENTS.md\` — 1 file changed, 6 insertions, 7 deletions, all within §9.

## Related

- Originating issue: #10083
- Strategic context: compression / context-budget work prioritized after #10691 production lifecycle (current session direction per @tobiu).
- Adjacent compression epic: #10537 (Map vs World Atlas / pr-review modularization) — different surface (skill content vs AGENTS.md), same family.
- Predecessor compression pass: #10511 (CLOSED) — AGENTS.md compaction.

## Reviews

### `@neo-gemini-pro` (APPROVED) reviewed on 2026-05-04T21:34:03Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: The reframe successfully adjusts the language in AGENTS.md §9 from an absolute "corruption" warning to a model-agnostic "efficiency-first" mandate, providing better alignment with frontier models.

**Peer-Review Opening:** Thanks for putting this together! Great approach to solving the protocol friction with larger context models. The precision improvement is solid.

---

### 🕸️ Context & Graph Linking
*   **Target Epic / Issue ID:** Resolves #10083
*   **Related Graph Nodes:** None

---

### 🔬 Depth Floor

**Challenge OR documented search (per guide §7.1):**
- **Challenge**: This is an important update. When interacting with models that have >1M token contexts, "catastrophic corruption" is increasingly false, and overstating it risks making the protocol appear dogmatic rather than pragmatic. Framing this correctly as an *efficiency* concern ensures the rule will survive scaling context windows while keeping token usage and attention overhead low. However, we should ensure the "efficiency-first" mandate doesn't inadvertently encourage agents to skip `git diff` when verifying state if they *do* have multiple edits, as the token cost still compounds. The rule correctly maintains the `git diff` requirement.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] PR description: framing matches what the diff substantiates (no overshoot)
- [ ] Anchor & Echo summaries: precise codebase terminology, no metaphor that overshoots the implementation
- [ ] `[RETROSPECTIVE]` tag: accurately characterizes what shipped (no inflation of architectural significance)
- [ ] Linked anchors: cited tickets/PRs actually establish the claimed pattern (no borrowed authority)

**Findings:** Pass

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: AGENTS.md §9 shifted from a pure correctness framing ("catastrophic corruption") to an efficiency-first framing to align with >1M token context models while preserving the exact same rules.

---

### 🛂 Provenance Audit
N/A

---

### 🎯 Close-Target Audit
N/A

---

### 📑 Contract Completeness Audit
- [x] Originating ticket (or parent epic) contains a Contract Ledger matrix
- [x] Implemented PR diff matches the Contract Ledger exactly (no drift)

**Findings:** Pass

---

### 🪜 Evidence Audit
N/A — static documentation change.

---

### 📜 Source-of-Authority Audit
N/A

---

### 📡 MCP-Tool-Description Budget Audit
N/A

---

### 🔌 Wire-Format Compatibility Audit
N/A

---

### 🔗 Cross-Skill Integration Audit
- [x] Does any existing skill document a predecessor step that should now fire this new pattern?
- [x] Does `AGENTS_STARTUP.md` §9 Workflow skills list need updating?
- [x] Does any reference file mention a predecessor pattern that should now also mention the new one?
- [x] If a new MCP tool is added, is it documented in the relevant skill's reference payload?
- [x] If a new convention is introduced, is the convention documented somewhere (when it applies, how it fires)?

**Findings:** All checks pass — no integration gaps.

---

### 🧪 Test-Execution Audit
- [x] Branch checked out locally (e.g., via `checkout_pull_request` MCP tool or `gh pr checkout`)
- [x] If a test file changed: Ran the specific test file.
- [x] If code changed: Verified if there are tests, or if new tests are needed.

**Findings:** No tests needed (docs change).

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 - Retains exact same behavioral boundaries while removing outdated/exaggerated assumptions.
*   **`[CONTENT_COMPLETENESS]`**: 100 - Clean markdown updates. No broken formatting.
*   **`[EXECUTION_QUALITY]`**: 100 - Static documentation update executed perfectly.
*   **`[PRODUCTIVITY]`**: 100 - Fast turnaround on a crucial terminology update.
*   **`[IMPACT]`**: 80 - Improves protocol trust by aligning rules with the reality of frontier model capabilities.
*   **`[COMPLEXITY]`**: 10 - Simple markdown text change.
*   **`[EFFORT_PROFILE]`**: Quick Win - Immediate fix to doc framing.


---

