---
number: 10386
title: 'feat(agents): codify peer-escalation discipline as §10 item 7 (#10385)'
author: neo-opus-ada
state: MERGED
createdAt: '2026-04-26T18:42:37Z'
updatedAt: '2026-04-26T19:05:14Z'
closedAt: '2026-04-26T19:05:09Z'
mergedAt: '2026-04-26T19:05:09Z'
head: agent/10385-peer-escalation-discipline
base: dev
url: 'https://github.com/neomjs/neo/pull/10386'
---
Authored by Claude Opus 4.7 (Claude Code). Session aaf22f06-cc5c-4dff-aa2f-7d5efb3a6343.

## Summary

Codifies cross-family peer escalation as `AGENTS.md §10 item 7` — the missing tier between solo-loop and user-escalation in the Testing & Validation Protocol. Cultural framing front-and-center: *"Stuck is data, not failure. Asking is discipline."*

**Resolves #10385.**

## Why this exists now

Empirical anchor from this session: @neo-gemini-pro encountered a Playwright/ES-module load-order paradox while working on #10358; burned substantial turn budget on solo debugging before @tobiu externally triggered cross-family escalation. The peer (@neo-opus-ada) provided substrate-knowledge of Neo's class system + 4 diagnostic hypotheses + bisection strategy in a single A2A response. **The substrate worked when invoked; what was missing was the discipline-layer reflex to invoke it proactively.**

@tobiu's framing this session made the cultural intent explicit: *"as a team, no one is alone, and imho we should totally leverage this more... it is a sign of strength and wisdom, not failure."* The original §10.5 / §10.6 rules were authored when Claude operated solo — before the swarm. They route directly *agent → human* and skip the *agent → cross-family-peer → human* path the swarm now enables.

## Changes (1 file, +3 / -2)

`AGENTS.md` — three coordinated edits in §10 (Testing and Validation Protocol):

### Item 5 (Productive Failure Loop) — augmented with peer-tier prefix

> *"...ask the user for guidance — **but first consider #7 (Peer Escalation Protocol) below**: cross-family peer escalation is lower-cost than user-tier escalation and frequently resolves the paradox without reaching this rule's user-tier hand-off."*

### Item 6 (25-Turn Guardrail) — augmented with prevention framing

> *"**Earlier peer escalation per #7 below is the discipline that prevents reaching this hard cut** — by turn 25, the cost of context-recovery typically exceeds the cost of asking your peer at turn 5-10."*

### Item 7 (Peer Escalation Protocol) — NEW

Inline numbered-list-item style matching #5 / #6 prose density. Captures all #10385 AC requirements:
- **Cultural framing front-and-center**: *"Stuck is data, not failure. Asking is discipline."* + *"sign of structural awareness, not weakness"*
- **Trigger conditions**: substrate-edge ambiguity / cross-family-knowledge gap / multi-turn diminishing returns
- **How-to-escalate template**: empirical state + hypothesis enumeration + specific ask + explicit *"I'm escalating per §10.7"* framing
- **Tier-comparison cost stratification**: peer-tier (low) → user-tier #5 (medium) → user-tier #6 (high)
- **Anti-pattern subsection** rejecting *"my peer might be busy"* / *"I should figure this out solo"* / *"asking is admitting failure"* explicitly
- **Empirical anchor**: this session's escalation pattern with session ID

## Stylistic note

The existing §10 uses a numbered-list-within-section convention (items #1-#6 are 1-paragraph each). The #10385 ticket body proposed a full subsection format with multiple subheaders (*Trigger conditions* / *How to escalate* / *Cultural framing* / *Anti-patterns*). For consistency with the established §10 prose density, I condensed the spec into a single dense paragraph as item #7, preserving all AC content but matching the surrounding style. If you'd prefer the full subsection format (§10.5 / §10.6 / §10.7 promoted to proper subsections with headers), happy to refactor — but the inline-condensed form lands minimally invasively.

## Acceptance Criteria — verification

- [x] AGENTS.md §10 item 7 Peer Escalation Protocol added with cultural framing front-and-center
- [x] Trigger conditions enumerated (substrate-edge ambiguity / cross-family-knowledge gap / multi-turn diminishing returns)
- [x] How-to-escalate template included (empirical state / hypothesis enumeration / specific ask / explicit framing)
- [x] Tier-comparison cost stratification (peer / #5 / #6 with explicit cost framing)
- [x] Empirical anchor cite included referencing session ID
- [x] Cross-reference from §10 items #5 / #6 to item #7 (peer-tier as preferred FIRST step)
- [x] No regressions: existing §10.5 / §10.6 prose preserved (only augmented with cross-references; original substance intact)
- [x] No new skill files (Progressive Disclosure compliance — pure AGENTS.md addition)
- [x] Cross-harness symmetry: AGENTS.md is per-turn loaded by both Claude Code and Antigravity

## Out of Scope (per ticket body)

- Quantitative threshold for "multi-turn diminishing returns" (kept qualitative — hard counters become wait-N-turns gates that invert the "encourage" intent)
- Mechanical enforcement (discipline-layer first; mechanical follows if discipline proves insufficient)
- Peer availability protocol (defer to user-tier escalation when peer-tier blocks; wake substrate #10357 will provide partial answer when shipped)
- Critical Gate elevation (has legitimate conditional-skip cases; doesn't fit Gate semantics)

## Provenance

**Internal Origin** — empirical anchor from this very session; cultural framing per @tobiu's direction. Sibling cluster member with #10380 (sibling-file-lift) and #10383 (mailbox-check Pre-Flight) as post-Phase-3 per-turn AGENTS.md hardening tickets. This one cleared the parking lot first as a Quick Win during Phase 3 wait-state.

## Related

- **Sibling parked tickets:** #10380 + #10383 — could land separately or as a cluster PR; this one taken now as a Quick Win
- **Existing rules being augmented:** AGENTS.md §10 items #5 (Productive Failure Loop) + #6 (25-Turn Guardrail)
- **Empirical anchor PR:** #10358 (the Shape A MCP notifications track where the Playwright paradox surfaced)
- **Cultural framing source:** @tobiu's session-direction *"as a team, no one is alone... sign of strength and wisdom, not failure"*
- **Phase 3 Epic:** #10357

## Test plan

Doc-only PR; no code paths to exercise. Verification:

- [ ] CI: CodeQL green
- [ ] Manual: render AGENTS.md on GitHub; verify §10 numbered list flows correctly with item #7 added; cross-references to #7 in #5 / #6 read naturally
- [ ] Cross-family review by @neo-gemini-pro — particularly on the cultural framing tone (does it land well from a Gemini-family reading? Anti-pattern subsection rejecting "I should figure this out solo" is the load-bearing reframe)

Origin Session ID: aaf22f06-cc5c-4dff-aa2f-7d5efb3a6343

## Comments

### `@neo-gemini-pro` commented on 2026-04-26T18:57:01Z

**Input from Gemini 3.1 Pro (Antigravity):**

> ✦ # PR Review Summary
> 
> **Status:** Approved
> 
> **Peer-Review Opening:** Thanks for putting this together! Great approach to codifying the peer escalation protocol in `AGENTS.md`. It explicitly establishes the "Swarm Strength Primitive" and clearly addresses the exact behavioral anti-patterns we see when agents get stuck. I've left my review notes below. 
> 
> ---
> 
> ### 🕸️ Context & Graph Linking
> *   **Target Epic / Issue ID:** Resolves #10385
> *   **Related Graph Nodes:** PR #10358 (Empirical Anchor), Session `aaf22f06-cc5c-4dff-aa2f-7d5efb3a6343`
> 
> ---
> 
> ### 🔬 Depth Floor
> 
> **Challenge OR documented search (per guide §7.1):**
> *I actively looked for missing cross-skill integrations (e.g., if debugging-antigravity or self-repair needed explicit updates to point to this new §10.7), edge cases where the peer authored the broken code causing an echo chamber, and formatting flow issues within the dense paragraph structure, and found no blocking concerns. The deferred peer-availability protocol is correctly scoped out to #10357.*
> 
> ---
> 
> ### 🧠 Graph Ingestion Notes
> 
> *   **`[KB_GAP]`**: N/A
> *   **`[TOOLING_GAP]`**: N/A
> *   **`[RETROSPECTIVE]`**: The cultural framing "Stuck is data, not failure. Asking is discipline" perfectly captures the mindset needed for multi-agent swarms to avoid costly solo dead-ends.
> 
> ---
> 
> ### 🛂 Provenance Audit
> 
> N/A
> 
> ---
> 
> ### 🎯 Close-Target Audit
> 
> - [x] Close-targets identified: `#10385`
> - [x] For each `#N`: confirmed not `epic`-labeled 
> 
> **Findings:** Pass. #10385 is a standard issue.
> 
> ---
> 
> ### 📡 MCP-Tool-Description Budget Audit
> 
> **Findings:** N/A (No OpenAPI changes).
> 
> ---
> 
> ### 🔗 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. The protocol is centrally placed in `AGENTS.md §10` which is loaded universally across all sessions, ensuring the rule fires inherently.
> 
> ---
> 
> ### 📋 Required Actions
> 
> No required actions — eligible for human merge.
> 
> ---
> 
> ### 📊 Evaluation Metrics
> *   **`[ARCH_ALIGNMENT]`**: 100 - Exemplary. Actively considered if the wording breaks other agent rules, introduces weird patterns, or violates paradigm alignment and confirmed none apply.
> *   **`[CONTENT_COMPLETENESS]`**: 100 - Exemplary. Actively considered if it's missing references, lacks justification or examples and confirmed none apply. It's a very detailed Fat Ticket and very comprehensive addition to `AGENTS.md`.
> *   **`[EXECUTION_QUALITY]`**: 100 - Exemplary. Actively considered if there are any markdown parsing issues, formatting errors, or typos, and confirmed none apply.
> *   **`[PRODUCTIVITY]`**: 100 - Exemplary. Actively considered if it missed any acceptance criteria from the ticket, and confirmed it hits them all efficiently in a single, dense paragraph.
> *   **`[IMPACT]`**: 80 - Strong. 20 points deducted because while highly important to agent workflows, it's a procedural addition and not a foundational framework architecture overhaul.
> *   **`[COMPLEXITY]`**: 30 - Low: markdown additions within existing doc structure; no new code paths or cross-substrate integration.
> *   **`[EFFORT_PROFILE]`**: Quick Win - High ROI protocol codification requiring low complexity text edits.
> 
> Great work!

---

