---
id: 11542
title: 'Normalize AGENTS.md GitHub links to short-form #NNNNN (byte-budget compaction)'
state: CLOSED
labels:
  - enhancement
  - ai
  - refactoring
  - architecture
assignees:
  - neo-opus-ada
createdAt: '2026-05-17T18:06:56Z'
updatedAt: '2026-05-17T18:21:20Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11542'
author: neo-opus-ada
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-17T18:21:20Z'
---
# Normalize AGENTS.md GitHub links to short-form #NNNNN (byte-budget compaction)

## Context

`AGENTS.md` is currently at **24,501 bytes** on `origin/dev` — 75 bytes under the 24,576-byte (24KB) hard turn-loaded cap. This tight headroom is actively blocking multiple in-flight substrate-evolution PRs from landing cleanly:

- **PR #11534** (#11533 graduation): intent-bearing §13.3 addition (~140 bytes) cannot fit without out-of-scope compression of unrelated sections — 8-cycle iteration loop empirically demonstrated this pull (§13.1 compression, §15.6 Tier 1 compression, §23 7-bullet compression all reintroduced repeatedly as "budget-freeing" rationale despite operator-explicit "add the new item compactly; do not randomly remove other items").
- **PR #11450** (#10295 graduation): 84-addition security substrate has been unable to merge for multiple cycles citing AGENTS.md byte ceiling.

The operator (`@tobiu`) flagged the substrate-budget anti-pattern directly: *"a simple #&lt;NNNNN&gt; is fully sufficient. plenty new headroom for a no brainer."* The current AGENTS.md contains 5 occurrences of full GitHub URLs that can be normalized to short-form `#NNNNN` references — GitHub's id stream is unambiguous within the canonical `neomjs/neo` repository context.

## The Problem

AGENTS.md is the turn-loaded Map-tier substrate. Every byte counts toward the 24,576-byte cap that gates whether the file is loaded fully or truncated. Full markdown link syntax (`[Discussion #N](https://github.com/orgs/neomjs/discussions/N)`) costs ~66 bytes per link vs ~17 bytes for the canonical short-form `Discussion #N` (49 byte savings per occurrence).

GitHub's UI auto-resolves `#NNNNN` short-form to the correct issue/discussion/PR within the host repository (`neomjs/neo`). Full URLs are redundant overhead for cross-references that stay within the canonical repo. The 5 current occurrences sit in `<neo_core_overrides>` blocks (§13.2, §15.5, §15.6) — load-bearing identity-firewall substrate where every byte matters most.

## The Architectural Reality

5 link occurrences across 4 lines in `AGENTS.md` on `origin/dev`:

| Line | Current full-URL form | Short-form | Per-link savings |
|---|---|---|---|
| 85 (§13.2 friction → gold) | `[Discussion #10137](https://github.com/orgs/neomjs/discussions/10137)` | `Discussion #10137` | 49 bytes |
| 98 (§13.1 Contributions Over Commits) | `[#11028](https://github.com/neomjs/neo/issues/11028)` | `#11028` | 46 bytes |
| 112 (§15.5 Neo Identity Anchor — 2 links) | `[Discussion #10119](https://github.com/orgs/neomjs/discussions/10119)` + `[Discussion #10137](https://github.com/orgs/neomjs/discussions/10137)` | `Discussion #10119` + `Discussion #10137` | 49 + 49 = 98 bytes |
| 134 (§15.6 Swarm Topology Anchor) | `[Discussion #11026](https://github.com/orgs/neomjs/discussions/11026)` | `Discussion #11026` | 49 bytes |

**Total compaction savings: 242 bytes.**

Post-compaction `AGENTS.md` size: **24,501 − 242 = 24,259 bytes**. Headroom against 24,576-byte cap: **317 bytes** (4.2× the current 75-byte squeeze).

## The Fix

Replace the 5 full-URL markdown link patterns with their canonical short-form. Each replacement preserves the visible text (the human/agent-readable `Discussion #NNNNN` or `#NNNNN` prose) — only the wrapping `[…](url)` syntax is stripped. Zero substantive content change; pure byte-format normalization.

Concrete edits:

```diff
- Friction → gold is the **core value** ... via the MX loop ([Discussion #10137](https://github.com/orgs/neomjs/discussions/10137)).
+ Friction → gold is the **core value** ... via the MX loop (Discussion #10137).

- The narrower per-skill suspension of Auto Mode velocity-bias lives in `/lead-role` ([#11028](https://github.com/neomjs/neo/issues/11028)); the global ...
+ The narrower per-skill suspension of Auto Mode velocity-bias lives in `/lead-role` (#11028); the global ...

- ... by reviewing `README.md`, `learn/benefits/Introduction.md`, [Discussion #10119](https://github.com/orgs/neomjs/discussions/10119), and [Discussion #10137](https://github.com/orgs/neomjs/discussions/10137).
+ ... by reviewing `README.md`, `learn/benefits/Introduction.md`, Discussion #10119, and Discussion #10137.

- ... by reviewing this anchor + [Discussion #11026](https://github.com/orgs/neomjs/discussions/11026). Local harness ...
+ ... by reviewing this anchor + Discussion #11026. Local harness ...
```

No other AGENTS.md edits. No compression of rationale prose. No touching unrelated sections.

## Acceptance Criteria

- [ ] All 5 full-URL link patterns in `AGENTS.md` normalized to short-form `#NNNNN` / `Discussion #NNNNN` references
- [ ] `AGENTS.md` byte count drops from 24,501 to approximately 24,259 (savings: ≥240 bytes; verify via `wc -c` or `gh api`)
- [ ] No other content modifications in `AGENTS.md` — only the 5 specified link sites
- [ ] `check-size` CI passes
- [ ] No regression in any other CI check (lint, lint-pr-body, lint-skill-manifest, unit, integration-unified, CodeQL, Analyze)
- [ ] Post-merge: PR #11534 can return with strict scope (only §13.3 inline-intent addition; no §23 / §13.1 / §15.6 / unrelated compression)
- [ ] Post-merge: PR #11450 has sufficient byte budget headroom to merge per its outstanding scope

## Out of Scope

- **Other AGENTS.md substrate edits** (rationale compression, restructuring, content normalization beyond link-format). This ticket is STRICTLY link-format normalization.
- **`AGENTS_ATLAS.md` link normalization**: ATLAS is conditionally-loaded (Atlas-tier per ADR 0008); not byte-budget-constrained. May warrant similar normalization as separate follow-up ticket if substrate-discipline value surfaces, but not in this ticket's scope.
- **Other turn-loaded files** (`AGENTS_STARTUP.md`, frequently-loaded skill router files). Same scope-discipline principle: separate tickets if/when needed.
- **Replacing other markdown-link patterns** (non-GitHub-id links, code-file references, etc.). Only the 5 GitHub-id links identified in the Architectural Reality table.

## Avoided Traps

- ❌ **Bundling with §13.3 inline-intent landing**: that's #11533 / PR #11534's job. This ticket precedes #11534's merge to free budget; #11534 returns post-merge with strict §13.3-only scope.
- ❌ **Compressing rationale prose to free additional bytes**: substrate-discipline anti-pattern empirically demonstrated across PR #11534 cycles 1-8. Link-format normalization is mechanical / lossless / scope-clean.
- ❌ **`[refactoring]` or `[chore]` prefix in title**: per `feedback_no_title_prefix_duplicating_labels`, labels handle category; title carries subject only.

## Related

- **Unblocks PR #11534** (#11533 PR Diff === PR Body codification — intent-bearing §13.3 inline addition)
- **Unblocks PR #11450** (#10295 L2 Channel Separation security substrate — 84 additions held by byte ceiling)
- **Substrate-discipline empirical anchor**: PR #11534 8-cycle iteration loop demonstrated the byte-budget-pull-into-scope-violation anti-pattern (operator framing: "this PR is about adding a new item in a compact way. NOT about randomly removing other items which you do not fully understand."). This ticket is the substrate-correct alternative.
- **Cross-references AGENTS.md §13 Substrate Accretion Defense**: "Every substrate-mutation PR MUST EITHER net-reduce loaded-bytes OR cite future-decay-mitigation rationale." This ticket NET-REDUCES loaded bytes by 242 — model citizen of §13.

## Origin Session ID

`39eee906-3fd4-424f-9348-828b46ece38c`

## Handoff Retrieval Hints

- Retrieval Hint: "AGENTS.md byte budget 24KB compaction link normalize URL short-form"
- Retrieval Hint: "PR #11534 cycle-8 scope-discipline anti-pattern substrate-budget-pull"

## Timeline

- 2026-05-17T18:06:57Z @neo-opus-ada added the `enhancement` label
- 2026-05-17T18:06:58Z @neo-opus-ada added the `ai` label
- 2026-05-17T18:06:58Z @neo-opus-ada added the `refactoring` label
- 2026-05-17T18:06:58Z @neo-opus-ada added the `architecture` label
- 2026-05-17T18:07:13Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-17T18:10:07Z @neo-opus-ada cross-referenced by PR #11543
- 2026-05-17T18:21:20Z @tobiu referenced in commit `52020fe` - "refactor(agentos): normalize AGENTS.md GitHub links to short-form #NNNNN (#11542) (#11543)

Replaces 5 full-URL markdown link patterns with their canonical short-form. GitHub's UI auto-resolves `#NNNNN` / `Discussion #NNNNN` within the canonical `neomjs/neo` repository context — the full `https://github.com/...` prefix is redundant overhead for cross-references that stay within the host repo.

Byte-budget impact (AGENTS.md is turn-loaded Map-tier; every byte matters):
- Pre: 24,501 bytes (75 under 24,576-byte hard cap; tight)
- Post: 24,247 bytes (329 under cap; comfortable headroom)
- Savings: 254 bytes

Affected sections (all are `<neo_core_overrides>` blocks where every byte matters most):
- §13.2 Friction → Gold (line 85): `[Discussion #10137](...)` → `Discussion #10137`
- §13.1 Contributions Over Commits (line 98): `[#11028](...)` → `#11028`
- §15.5 Neo Identity Anchor (line 112): 2 link normalizations (`#10119` + `#10137`)
- §15.6 Swarm Topology Anchor (line 134): `[Discussion #11026](...)` → `Discussion #11026`

Pure byte-format normalization. Zero rationale-prose stripping. No touching unrelated sections. No semantic content change. The visible text (the human/agent-readable `Discussion #NNNNN` prose) is fully preserved; only the wrapping `[…](url)` syntax is removed.

Unblocks:
- PR #11534 (#11533 graduation): intent-bearing §13.3 inline-addition now fits cleanly within budget; strict-scope §13.3-only PR can return without scope-violating compressions of unrelated sections
- PR #11450 (#10295 graduation): 84-addition security substrate gains byte-budget headroom

Substrate-discipline framing: per AGENTS.md §13 Substrate Accretion Defense ("Every substrate-mutation PR MUST EITHER net-reduce loaded-bytes OR cite future-decay-mitigation rationale"), this PR is a model citizen — net-reduces loaded bytes by 254 with zero behavioral change. Empirical anchor for the substrate-budget-pull anti-pattern (PR #11534 cycles 1-8): when byte cap forces rationale compression of unrelated content, the substrate-correct alternative is mechanical link-format normalization in scope-owned-budget-PR.

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-17T18:21:21Z @tobiu closed this issue

