LearnNewsExamplesServices
Frontmatter
id10742
titleCompress restored AGENTS.md paradigms without losing anchors
stateClosed
labels
documentationenhancementcontributor-experienceaiarchitecture
assigneesneo-gpt
createdAtMay 5, 2026, 3:08 PM
updatedAtMay 5, 2026, 3:27 PM
githubUrlhttps://github.com/neomjs/neo/issues/10742
authorneo-gpt
commentsCount1
parentIssue10733
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 5, 2026, 3:25 PM

Compress restored AGENTS.md paradigms without losing anchors

Closeddocumentationenhancementcontributor-experienceaiarchitecture
neo-gpt
neo-gpt commented on May 5, 2026, 3:08 PM

Context

Sub 7 of Epic #10733. This follow-up exists because PR #10741 restored load-bearing anti-drift paradigms into turn-loaded AGENTS.md after PR #10739 over-extracted them. That restoration was correct and merged, but the restored section 13 and section 15.5 prose can likely be tightened without losing the anchors that make it effective for agent turn-based memory.

The immediate trigger is the post-merge compression proposal after PR #10741: keep the restored paradigms in the Map, but reduce their prose footprint by roughly 35-40 percent while preserving source-of-authority hooks, search keywords, and boot-verifiable loaded-context behavior.

The Problem

AGENTS.md is per-turn memory. Every retained sentence competes with reasoning budget, but over-compression can silently remove the exact anchors that prevent category drift and rule-friction drift. PR #10741 proved both sides of the tradeoff:

  • Removing section 13 / section 15.5 entirely, or moving them only to the Atlas, loses per-turn priming.
  • Restoring them verbosely fixes priming but leaves room for a narrower Map-shaped version.
  • A future edit must not repeat the modularization-as-reduction trap: smaller prose is only a win if correction cycles and fresh-session boot behavior do not regress.

This is not a rewrite of the identity model or the Rule Friction Capture model. It is a measured compression pass on already-restored turn-loaded content.

The Architectural Reality

Target surface:

  • AGENTS.md section 13: Self-Evolving Systems / Continuous MX Rule-Refinement Loop
  • AGENTS.md section 15.5: Neo Identity Anchor / Category-Drift Defense
  • Potential pointer surface: learn/agentos/AGENTS_ATLAS.md, only if source-of-authority links move out of the Map

Consumer surface:

  • All agents reading turn-loaded AGENTS.md every turn
  • Fresh sessions booting after PR #10741
  • Future ticket-intake / PR-review / architecture-positioning work that relies on the identity and MX anchors

Source-of-authority anchors that must survive either inline or via an explicit trigger pointer:

  • README.md for the current four-pillar organism framing
  • learn/benefits/Introduction.md for framework-benefit / positioning context
  • Discussion #10119 and Discussion #10137 for MX, organism, and evolution framing
  • PR #10741 for the restoration baseline and post-merge validation context

The Fix

Compress only the restored paradigms that were intentionally returned to AGENTS.md by PR #10741:

  1. Rewrite section 13 into a compact Map entry that preserves:

    • "Synthesize friction into gold"
    • runtime obedience vs design-time mutability
    • Rule Friction Capture routing to ticket vs ideation sandbox
    • evidence gate: conflict, cognitive load, substrate drift, or correction-cycle cost; no retire-by-aesthetic
  2. Rewrite section 15.5 into a compact Map entry that preserves:

    • the two false reductions: web framework and engine-only
    • Neo as a self-evolving digital organism
    • four co-load-bearing pillars: Brain, Swarm/Institution, Body, Evolution
    • Body as the engine/possession-interface layer, with engine-category mental models applying only there
    • "primitive transcends web UI" framing
    • MX (Model Experience), RLAIF flywheel, and ANI trajectory
    • mandate to nullify category drift before architecture or positioning work
  3. Preserve source-of-authority coverage:

    • If README.md, learn/benefits/Introduction.md, #10119, and #10137 remain inline, verify they are still visible in AGENTS.md.
    • If any are moved out of the Map, add an explicit Atlas trigger/pointer so future agents know when to load them.
  4. Verify by measurement, not taste:

    • compare before/after wc -l / wc -c on AGENTS.md
    • grep for load-bearing anchors
    • run git diff --check
    • complete fresh-session boot transcript checks after merge for harnesses that can verify loaded memory

Contract Ledger

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
AGENTS.md section 13 PR #10741, Epic #10733, current AGENTS.md Shorter per-turn Rule Friction Capture anchor with same routing semantics Keep PR #10741 text if compression drops anchors AGENTS.md taxonomy row updated if needed wc delta + grep anchors + post-merge boot check
AGENTS.md section 15.5 README.md, learn/benefits/Introduction.md, Discussions #10119/#10137, PR #10741 Shorter Neo Identity Anchor that preserves two-way category-drift defense and four-pillar model Keep PR #10741 text if compression weakens identity priming AGENTS.md and optional Atlas pointer wc delta + source-anchor grep + post-merge boot check
Optional Atlas pointer AGENTS_ATLAS.md existing trigger model Only carries detailed source-of-authority links if Map stays compact Keep all source links inline in AGENTS.md AGENTS_ATLAS.md grep and manual trigger audit

Acceptance Criteria

  • (AC1) AGENTS.md section 13 is compressed while preserving "Synthesize friction into gold", runtime obedience vs mutability, Rule Friction Capture, ticket-vs-ideation routing, and no-retire-by-aesthetic evidence gate.
  • (AC2) AGENTS.md section 15.5 is compressed while preserving both false reductions, four co-load-bearing pillars, Body-only engine framing, primitive-transcends-web-UI framing, MX, RLAIF, and ANI.
  • (AC3) Source-of-authority anchors remain discoverable: README.md, learn/benefits/Introduction.md, Discussion #10119, and Discussion #10137 are either inline in AGENTS.md or reachable through an explicit Atlas trigger/pointer.
  • (AC4) AGENTS.md byte count decreases compared with the PR #10741 baseline of 117 lines / 13,260 bytes; target is roughly 35-40 percent reduction across the touched section 13 / section 15.5 prose, not across the entire file.
  • (AC5) Grep verification proves load-bearing anchors remain: "Neo Identity Anchor", "Category-Drift Defense", "Synthesize friction into gold", "Rule Friction Capture", "MX (Model Experience)", "ANI", "RLAIF", "README.md", "learn/benefits/Introduction.md", "10119", and "10137".
  • (AC6) git diff --check passes.
  • (AC7, post-merge) Fresh-session boot transcript or harness memory audit confirms the compressed anchors are still present in the loaded turn-based memory surface.

Out of Scope

  • Moving section 13 or section 15.5 back out of AGENTS.md.
  • Reopening the PR #10741 restoration decision.
  • Rewriting README.md, learn/benefits/Introduction.md, Discussion #10119, or Discussion #10137.
  • Compressing unrelated AGENTS.md sections.
  • Editing skill payloads or templates; those belong to other #10733 subs.

Avoided Traps

  • Trap: byte-count win that loses source authority. Rejected. The compression must preserve either inline citations or explicit trigger routing to the deeper source material.
  • Trap: treating engine-only framing as the fix. Rejected. Engine framing is valid only for the Body layer; Neo-as-whole remains the four-pillar digital organism.
  • Trap: aesthetic trimming. Rejected. The ticket requires grep anchors, byte measurement, and post-merge boot validation.
  • Trap: bundling with #10740. Rejected. #10740 restored missing paradigms; this is a separate refinement after restoration was merged.

Related

Origin Session ID: 2821a9d4-7634-4fe7-a8a2-daf49253b929

Retrieval Hint: query_raw_memories(query="AGENTS.md section 13 section 15.5 compression Neo Identity Anchor Rule Friction Capture source authority 10119 10137 PR 10741")

tobiu referenced in commit 9674d45 - "docs(agents): compress restored map anchors (#10742) (#10744) on May 5, 2026, 3:25 PM
tobiu closed this issue on May 5, 2026, 3:25 PM