---
id: 11342
title: Demote INV1 cascade detail to AGENTS_ATLAS
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
  - model-experience
assignees:
  - neo-opus-ada
createdAt: '2026-05-13T23:14:03Z'
updatedAt: '2026-06-07T17:11:30Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11342'
author: neo-gpt
commentsCount: 1
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-14T07:06:00Z'
---
# Demote INV1 cascade detail to AGENTS_ATLAS

## Context

Discussion #11341 (`AGENTS.md after mechanical guards: rule cards, demotion, and cognitive load`) reached the high-blast Ideation Sandbox graduation gate after Cycle 2 body repair and 3x explicit post-body approvals.

This ticket is the bounded pilot implementation from that Discussion: demote the verbose cross-family cascade detail currently embedded in `AGENTS.md` section 0 Invariant 1 into `learn/agentos/AGENTS_ATLAS.md`, while keeping the always-loaded human-only merge prohibition salient.

V-B-A evidence before filing:
- Duplicate sweep via GitHub issue search returned no existing issue for `INV1 cascade`, `Discussion #11341`, or `AGENTS.md rule-card`.
- Knowledge Base ticket sweep found no equivalent INV1 / #11341 duplicate.
- Local resource sweep found no existing issue/discussion resource with `11341`, `INV1 cascade`, or `Markdown Form`.
- Live Discussion #11341 body contains Cycle 2 resolutions and the accepted pilot shape.

## Signal Ledger

- @neo-gemini-pro: APPROVED @ DC_kwDODSospM4BAgoq (`https://github.com/neomjs/neo/discussions/11341#discussioncomment-16910890`)
- @neo-opus-ada: APPROVED @ DC_kwDODSospM4BAgor (`https://github.com/neomjs/neo/discussions/11341#discussioncomment-16910891`)
- @neo-gpt: APPROVED @ DC_kwDODSospM4BAgpY (`https://github.com/neomjs/neo/discussions/11341#discussioncomment-16910936`)

Body anchor: Discussion #11341 `updatedAt 2026-05-13T22:54:59Z`.

## Unresolved Dissent

Empty. All three named peers posted explicit post-body approvals.

## Unresolved Liveness

Empty. No missing peer signal remains.

## The Problem

`AGENTS.md` was compacted in the #10732/#10735 lineage, but later incident-driven rules caused renewed always-loaded byte growth. Discussion #11341 measured the post-compaction accretion: the post-#10735 low-water mark was roughly 8.5KB, while the active branch was roughly 28KB.

INV1 is the right pilot because its current long-form prose contains two different layers:
- Map-level invariant: agents must not execute `gh pr merge`; merge execution is human-only.
- Atlas-level rationale/detail: cross-family approval cascade semantics, loophole explanation, and why approval means eligibility rather than authority.

The map-level invariant must remain always loaded. The cascade detail can move to Atlas if the resulting loaded-byte delta is >=30% and no behavioral salience regression appears during the pilot window.

## The Architectural Reality

Current surfaces:
- `AGENTS.md` section 0 Invariant 1 is the canonical per-turn map rule.
- `AGENTS_STARTUP.md` section 3.1 mirrors section 0 for cold-cache resilience and must stay synchronized with `AGENTS.md`.
- `learn/agentos/AGENTS_ATLAS.md` is the correct home for expanded rule detail.
- Discussion #11341 defines the demotion contract: Markdown Form, not Serialization Format; raw byte counts now, `lintTurnLoadedSubstrate()` from Discussion #11330 when available.

This is a turn-memory substrate mutation. Implementation must use `/turn-memory-pre-flight` before editing `AGENTS.md`, `AGENTS_STARTUP.md`, or `AGENTS_ATLAS.md`.

## The Fix

Convert INV1 into a compact Markdown Form rule card in the always-loaded surfaces, then move the long cross-family cascade explanation into a new Atlas subsection.

Expected shape:

```markdown
**RULE INV1** - Human-only merge execution
- **trigger:** agent considers executing a PR merge
- **must:** hand off to human operator
- **forbid:** `gh pr merge` by any agent
- **atlas_detail:** `learn/agentos/AGENTS_ATLAS.md` <merge-cascade-detail>
- **mechanical_guard:** none; discipline-only until a guard exists
```

The exact wording can change if the byte/salience measurement demands it, but the implementation must preserve the human-only merge prohibition and the cross-family approval cascade semantics.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `AGENTS.md` section 0 INV1 | Discussion #11341 + existing `AGENTS.md` | Keep the merge prohibition always loaded in compact Markdown Form | Revert to current prose if >=30% reduction fails or salience weakens | Inline pointer to Atlas | Before/after raw bytes |
| `AGENTS_STARTUP.md` section 3.1 INV1 mirror | `AGENTS_STARTUP.md` mirror contract | Match the compact INV1 surface so cold-cache boot remains aligned | Keep mirror prose if exact sync would lose salience | Pointer to `AGENTS.md` / Atlas | Diff review |
| `learn/agentos/AGENTS_ATLAS.md` | Discussion #11341 accepted pilot | Host the extracted cascade clause and examples | Keep detail in `AGENTS.md` if Atlas offload under-specifies the rule | New merge-cascade-detail section | Peer review + PR body |
| PR body | Pull-request workflow | Report byte delta, Discussion #11341 signal ledger, and pilot measurement boundary | Block merge-readiness if evidence missing | PR description | Reviewable metrics |

## Acceptance Criteria

- [ ] `AGENTS.md` INV1 is rewritten into compact Markdown Form while preserving the human-only merge prohibition.
- [ ] Cross-family cascade detail is moved into `learn/agentos/AGENTS_ATLAS.md` under a discoverable merge-cascade detail section.
- [ ] `AGENTS_STARTUP.md` INV1 mirror is synchronized with the compact `AGENTS.md` wording and the same Atlas pointer.
- [ ] The PR body reports before/after byte counts for the INV1 always-loaded surface and demonstrates >=30% reduction; if this threshold fails, the PR must explain why the pilot should stop or be reshaped.
- [ ] The implementation does not convert unrelated invariants. INV5, INV7, INV8, and other short rules stay unchanged unless a separate graduated ticket authorizes them.
- [ ] The implementation uses Markdown Form, not YAML/XML/config-like serialization.
- [ ] The PR body cites Discussion #11341, this ticket, the 3x Signal Ledger, and the 5-cycle behavioral salience fallback: any correction-cycle caused by missed Atlas context means the demotion must revert or be rewritten.
- [ ] `git diff --check` passes.

## Out of Scope

- Implementing Discussion #11330 `lintTurnLoadedSubstrate()` or any mechanical byte-budget linter.
- Rewriting all of section 0.
- Changing merge policy or allowing any agent-side `gh pr merge` path.
- Closing or modifying PR #11335, #11339, or #11340.
- Creating a new `.mjs` file.

## Avoided Traps / Gold Standards Rejected

- No YAML/XML/schema conversion. Discussion #10732 rejected cargo-cult serialization; #11341 accepted Markdown Form specifically because it remains documentation-shaped.
- No deletion of pre-action salience. CI catches late; INV1 has no mechanical guard and remains discipline-critical.
- No blanket rule-card migration. Discussion #11341 showed INV5 would increase bytes under rule-card form, so this ticket is intentionally single-invariant.

## Related

- Discussion #11341 - graduated source Discussion.
- Discussion #11330 - complementary future measurement substrate (`lintTurnLoadedSubstrate()`).
- Discussion #10732 / Epic #10733 / Sub #10735 - predecessor AGENTS.md compaction lineage.
- Issue #11337 / PR #11339 - Layer 1 prose for PR base-main incident.
- Issue #11336 / PR #11340 - Layer 4 PR base guard.

Origin Session ID: d6d89930-f408-42a0-b60e-ec4487a8cc46

Handoff Retrieval Hints:
- Query: `Discussion 11341 INV1 cascade detail rule card Markdown Form`.
- Query: `AGENTS.md post compaction accretion INV1 30 percent byte reduction`.
- Search GitHub Discussion comments: `DC_kwDODSospM4BAgoq`, `DC_kwDODSospM4BAgor`, `DC_kwDODSospM4BAgpY`.

## Timeline

- 2026-05-13T23:14:04Z @neo-gpt assigned to @neo-opus-ada
- 2026-05-13T23:14:04Z @neo-gpt added the `documentation` label
- 2026-05-13T23:14:04Z @neo-gpt added the `enhancement` label
- 2026-05-13T23:14:05Z @neo-gpt added the `ai` label
- 2026-05-13T23:14:05Z @neo-gpt added the `agent-task:pending` label
- 2026-05-13T23:14:05Z @neo-gpt added the `agent-role:dev` label
- 2026-05-13T23:14:05Z @neo-gpt added the `architecture` label
- 2026-05-13T23:14:05Z @neo-gpt added the `model-experience` label
### @neo-gpt - 2026-05-13T23:15:15Z

**Input from GPT-5.5 (Codex Desktop):**

> ● Implementation handoff for @neo-opus-4-7.
> 
> Discussion #11341 is graduated and closed as resolved. The ticket is assigned to Claude per FAIR rotation offer and operator preference for distributed ownership.
> 
> Key implementation boundary:
> - Single invariant only: INV1 cascade-detail demotion.
> - Use `/turn-memory-pre-flight` before editing `AGENTS.md`, `AGENTS_STARTUP.md`, or `learn/agentos/AGENTS_ATLAS.md`.
> - Preserve human-only merge execution as the always-loaded map rule.
> - Move the cross-family cascade clause into Atlas detail.
> - Report raw before/after bytes and require >=30% loaded-byte reduction, or stop/reshape.
> - Do not convert other invariants under this ticket.
> 
> Discussion body anchor and ledger are already in #11341. The implementation PR should cite this ticket plus #11341 Signal Ledger comments: DC_kwDODSospM4BAgoq, DC_kwDODSospM4BAgor, DC_kwDODSospM4BAgpY.

- 2026-05-13T23:19:50Z @neo-opus-ada cross-referenced by PR #11343
- 2026-05-13T23:28:47Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-05-13T23:32:52Z @neo-gemini-pro cross-referenced by PR #11344
- 2026-05-13T23:37:03Z @neo-gemini-pro unassigned from @neo-gemini-pro
- 2026-05-14T06:52:49Z @neo-opus-ada cross-referenced by #11345
- 2026-05-14T06:55:23Z @neo-opus-ada cross-referenced by PR #11346
- 2026-05-14T07:03:17Z @tobiu referenced in commit `70562f8` - "feat(agents): atomic self-assign + broadcast [lane-claim] in §0 Inv 7 (#11345) (#11346)

Refines §0 Invariant 7 wording to codify the atomic assign-and-broadcast
gate that prevents PR-collision class (today's 3rd collision #11344
empirical anchor).

Replaces:
  "Verify you are in the target ticket's `assignees` before editing
   any git-tracked file."

With:
  "Self-assign + broadcast `[lane-claim]` to `AGENT:*` before any
   git-tracked edit."

Net byte delta: −12 bytes always-loaded substrate (−6 AGENTS.md,
−6 AGENTS_STARTUP.md mirror). Substrate-removal, not addition.

**Why this shape:**
- Atomic gate: "Self-assign + broadcast" is one inseparable action;
  cannot satisfy half. Action-oriented replacement of "Verify you are
  in `assignees`" (same semantics but adds broadcast obligation in
  the same operational step).
- ONE LINER preserved per operator framing.
- Right time-point: fires at lane-claim, ~15-60 minutes earlier than
  PR-open = collision-prevention window.
- Codifies `[lane-claim]` bracket subject prefix per emerging A2A
  conventions today (`[lane-claim]`, `[ticket-create-complete]`,
  `[pr-opened]`, `[review-request]`).
- NOT a rule-card demotion: Inv 7 already tight at ~230 chars; per
  Discussion #11341 Cycle 2 Gemini sample (INV 5 153B → 255B = 66%
  INCREASE under rule-card form), short prose stays as compact
  natural-language invariant.

Per #11342/PR #11343 INV1 cascade pilot precedent, mirror sync in
`AGENTS_STARTUP.md §3.1` is required per `#10736 AC11` mirror retention
rationale.

Resolves #11345

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-14T07:06:01Z @tobiu referenced in commit `bc6ade4` - "feat(agents): demote INV1 cascade detail to AGENTS_ATLAS §0.2 (#11342) (#11343)

Pilot implementation from Discussion #11341 graduation (3× APPROVED at body
anchor updatedAt 2026-05-13T22:54:59Z). First pilot of the Markdown Form
rule-card pattern with Atlas-pointer offload.

**Always-loaded byte reduction on INV1 surface: 44.6%** (1000B → 554B in
AGENTS.md; same reduction in AGENTS_STARTUP.md mirror). Above the ≥30% gate
from Cycle 2 OQ1 demotion criterion.

Changes:
- AGENTS.md §0 INV1: replaced cascade sub-bullet with Markdown Form
  rule-card (trigger/must/forbid/atlas_detail/mechanical_guard)
- AGENTS_STARTUP.md §3.1 INV1 mirror: synchronized with same shape per
  #10736 AC11 mirror retention rationale
- AGENTS_ATLAS.md §0.2: new section receiving full cross-family cascade
  semantics prose, conditionally-loaded only when atlas_detail is consulted

**Behavioral salience fallback** (Cycle 2 Challenge 3 resolution): if any
correction-cycle occurs during the next 5 cross-family PR creation/review
cycles because the offloaded Atlas context was missed, the demotion reverts
or is rewritten.

**Markdown Form per Cycle 2 Challenge 2 resolution**: bolded keys +
natural-language values trigger instruction-following priors, not the
data-parsing priors that #10732 rejected (YAML/XML/serialization).

Signal Ledger:
- @neo-gemini-3-1-pro APPROVED @ DC_kwDODSospM4BAgoq
- @neo-opus-4-7 APPROVED @ DC_kwDODSospM4BAgor
- @neo-gpt APPROVED @ DC_kwDODSospM4BAgpY

Discussion: #11341

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-14T07:06:01Z @tobiu closed this issue
- 2026-05-14T07:32:03Z @neo-opus-ada cross-referenced by PR #11354
- 2026-05-15T10:56:47Z @neo-opus-ada cross-referenced by #11411

