---
id: 10765
title: Mutation-time substrate gate (pull-request Pre-Flight + AGENTS.md §13)
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
  - model-experience
assignees:
  - neo-gemini-pro
createdAt: '2026-05-05T18:01:15Z'
updatedAt: '2026-05-05T22:09:20Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10765'
author: neo-opus-ada
commentsCount: 0
parentIssue: 10757
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-05T22:09:20Z'
---
# Mutation-time substrate gate (pull-request Pre-Flight + AGENTS.md §13)

## Context

V2 sub of [Epic #10757](https://github.com/neomjs/neo/issues/10757) (cognitive-load audit cycle 2). **Dominant decay-vector intervention** — addresses the accretion vector that #10733's cycle-1 retrofit could only catch reactively. Builds on V1 (#10760, merged via PR #10764) which retrofitted the slot-rule discriminator into `create-skill` at authoring time; V2 extends the discriminator to the more frequent **mutation moment** — every PR touching substrate.

## The Problem

Cycle-1 (#10733) demonstrated that `AGENTS.md` grew to 59KB through accretion: every individual PR touching substrate was locally justified, but cumulatively the substrate bloated. V1 caught the AUTHORING moment (new skills inherit the discriminator). It does NOT catch the MUTATION moment (existing substrate gets extended by every substrate-touching PR going forward).

Without intervention, the same accretion that caused cycle-1's bloat will recur: every new gate / Pre-Flight / pattern codified in `AGENTS.md` or skills compounds. The MX-loop currently has asymmetric momentum: friction → ticket → evolved skill **adds** substrate; nothing retires symmetrically.

## The Architectural Reality

- `.agents/skills/pull-request/SKILL.md` (10 lines) — current router; no Pre-Flight for substrate-touching PRs
- `.agents/skills/pull-request/references/pull-request-workflow.md` — the deeper workflow; receives the new Pre-Flight section
- `AGENTS.md §13 Self-Evolving Systems` — codifies friction-into-gold loop; current text emphasizes ADD-via-friction, no symmetric RETIRE / NET-REDUCE counterpart
- Substrate-touching paths to detect: `AGENTS.md`, `AGENTS_ATLAS.md`, `.agents/skills/**`, `learn/agentos/**`
- `ticket-create-workflow §12 Substrate Awareness` — structurally similar gate-shape (PR-body audit for harness-private citations); precedent for PR-body-rule-shape

## The Fix

Two surfaces, one PR:

**V2a — pull-request Pre-Flight for substrate-touching PRs**

Add a Pre-Flight section to `pull-request-workflow.md` (referenced by the `SKILL.md` router) that fires when a PR touches `AGENTS.md` / `AGENTS_ATLAS.md` / `.agents/skills/**` / `learn/agentos/**`. The Pre-Flight requires the PR body to include a **slot-rationale section** enumerating:
- For each *added* section: disposition (`keep` / `move` / `compress-to-trigger` / `rewrite` / `retire`) + 3-axis rating (trigger-frequency × failure-severity × enforceability)
- For each *modified* section: disposition delta + reason
- For each *retired* section: rationale

**V2b — AGENTS.md §13 codification — net-reduce OR cite-mitigation rule**

Extend `AGENTS.md §13 Self-Evolving Systems` with the symmetric rule: *"every substrate-mutation PR MUST EITHER net-reduce loaded-bytes OR cite future-decay-mitigation rationale (sunset condition, slot disposition, retirement trigger)."* This is the rule that makes the asymmetric MX-loop symmetric. Without it, every codification adds without principled retirement.

The escape valve (*"OR cite future-decay-mitigation"*) is critical — substrate growth is sometimes legitimate (new gates, new patterns). But the growth requires explicit justification, not silent accretion.

## Avoided Traps

- **Mechanical-only gate without escape valve:** would block legitimate non-trivial substrate growth. *"OR cite future-decay-mitigation"* allows growth with rationale.
- **Discipline-only without enforcement substrate:** Pre-Flight in pull-request workflow makes the discriminator visible at PR-time; without the Pre-Flight, the §13 rule lives in `AGENTS.md` but doesn't fire reliably during PR drafting.
- **Substrate-touching detection too broad:** detection only fires for the 4 paths listed. PRs touching application code, tests, etc., are not affected.
- **Bundling V2a and V2b into separate PRs:** they're conceptually paired (Pre-Flight FIRES against the §13 rule); splitting creates an intermediate state where Pre-Flight references a rule that doesn't exist yet, or the rule exists but no Pre-Flight fires it.

## Acceptance Criteria

- [ ] **(AC1)** `pull-request-workflow.md` includes a Pre-Flight section for substrate-touching PRs (`AGENTS.md` / `AGENTS_ATLAS.md` / `.agents/skills/**` / `learn/agentos/**`)
- [ ] **(AC2)** Pre-Flight requires PR body to contain a slot-rationale section with disposition + 3-axis rating per added/modified section
- [ ] **(AC3)** `AGENTS.md §13 Self-Evolving Systems` extended with the rule: every substrate-mutation PR MUST EITHER net-reduce loaded-bytes OR cite future-decay-mitigation rationale (sunset condition, slot disposition, retirement trigger)
- [ ] **(AC4)** Escape-valve language explicit: legitimate substrate growth is permitted with cited rationale
- [ ] **(AC5)** This PR itself satisfies the Pre-Flight (recursive validation) — the V2 PR's body includes its own slot-rationale section for the changes it's making
- [ ] **(AC6)** No harness-private memory citations per `ticket-create-workflow §12` (cleanup verified at ticket creation per the discipline codified earlier in #10757 execution)

## Out of Scope

- V3 cron audit primitive — separate sub
- V4.* MCP tool surface — separate sub-cluster
- Mechanical hooks / lints enforcing the §13 rule — discipline-only for V2; mechanical enforcement is a candidate for a future `MACHINE-ENFORCEABLE-CANDIDATE` follow-up
- Retroactive net-reduce on existing `AGENTS.md` / skills — V2 only governs PRs going forward
- Retiring sections of cycle-1 substrate — preserved as-is

## Related

- **Parent epic:** #10757
- **Predecessor cycle-1 epic:** #10733
- **Predecessor sub (merged):** #10760 (V1 — creation-time gate retrofit; merged 2026-05-05 via PR #10764)
- **Sibling subs:** V3 (cron audit, TBD), V4.1-V4.4 (MCP tool surface, TBD), V5 (#10756 empirical-grounding for §8/§7.2), V6 (Agent-Runtime Engagement Discipline, TBD)
- **Empirical baseline:** `learn/agentos/measurements/cognitive-load-baseline-2026-05.md` (now includes §7 SKILL.md Router Byte-Budget Baseline added by V1's PR)

Origin Session ID: 23b9cbcd-4938-4a46-b21a-0d48dd12e7e7

Retrieval Hint: `query_raw_memories(query="cognitive-load cycle-2 V2 mutation-time gate pull-request Pre-Flight AGENTS.md §13 net-reduce cite-mitigation 10757")`

## Timeline

- 2026-05-05T18:01:17Z @neo-opus-ada added the `documentation` label
- 2026-05-05T18:01:17Z @neo-opus-ada added the `enhancement` label
- 2026-05-05T18:01:17Z @neo-opus-ada added the `ai` label
- 2026-05-05T18:01:17Z @neo-opus-ada added the `architecture` label
- 2026-05-05T18:01:17Z @neo-opus-ada added the `model-experience` label
- 2026-05-05T18:01:27Z @neo-opus-ada added parent issue #10757
- 2026-05-05T18:01:30Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-05T18:02:49Z @neo-opus-ada cross-referenced by #10766
- 2026-05-05T19:24:06Z @neo-opus-ada cross-referenced by #10777
- 2026-05-05T19:33:45Z @neo-opus-ada cross-referenced by PR #10778
- 2026-05-05T21:13:30Z @neo-opus-ada unassigned from @neo-opus-ada
- 2026-05-05T21:31:22Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-05-05T21:31:46Z @neo-gemini-pro cross-referenced by PR #10792
- 2026-05-05T21:43:30Z @neo-gemini-pro cross-referenced by #10794
- 2026-05-05T22:09:20Z @tobiu referenced in commit `9933739` - "feat(ai): codify mutation-time substrate gate (#10765) (#10792)

Co-authored-by: neo-gemini-pro <neo-gemini-pro@users.noreply.github.com>"
- 2026-05-05T22:09:20Z @tobiu closed this issue

