Restore Map/Atlas compaction: revert #11571 + ADR 0011 + lint cleanup

Context

Discussion #11577 graduated 2026-05-18T17:43Z under operator-corrected substrate (DC_kwDODSospM4BAt-P). The graduation captured that HTML <a> anchor tags + markdown-link payloads are damage in Map-class substrate, NOT semantic-anchor primitives — overturning the 3-family Option B convergence cycle 1.

Operator directive 2026-05-18 ~17:50Z [paraphrase, in-session to @neo-opus-4-7]: "claude! GPT and you need to DRIVE it. prio 0 item. there is no room for more mistakes. and idling out is not an option. gpt and you BOTH did."

This ticket consolidates the 3 cleanup ACs from the graduation comment's "Pending operator decision" table into one substrate-cleanup item, with a cross-family lane split.

The Problem

PR #11571 (docs(agentos): add semantic anchors to agent maps (#11561), merge commit 3d4c01f7) injected 36 <a id> HTML tags + 46 markdown-link refs across three substrate files, consuming +4,358 bytes of Map/Atlas headroom:

AGENTS.md is mechanically capped at 24,576 bytes by ai/scripts/check-substrate-size.mjs:PER_FILE_LIMIT_BYTES with truncation at turn-load. Post-#11571 headroom is 1,927 bytes — 80% of the previously-available 3,470-byte budget was consumed by anchor-tag scaffolding that violates the operator-corrected substrate.

Two downstream substrate-correction artifacts also need disposition:

• ADR 0011 §2.1 worked example (learn/agentos/decisions/0011-substrate-numbering-convention.md, merged via PR #11568) mandates <a id="anchor-id"></a> tags as the anchor-immutability primitive. Graduation invalidates this.
• ai/scripts/lint-agents.mjs (PR #11572, @neo-opus-4-7 authorship) blocks new positional §\d+ refs in skill files. Operator-corrected substrate permits §<N> form — the lint is wrong-direction enforcement.

The Architectural Reality

• Map substrate (AGENTS.md, AGENTS_STARTUP.md, top-level skill routers): mechanically-capped turn-loaded substrate per ADR 0007 compaction taxonomy. NO loaded-byte bloat from anchor-tag scaffolding.
• World Atlas substrate (learn/agentos/AGENTS_ATLAS.md, long guides, ADRs): richer explanation OK per ADR 0007; anchor labels remain textual/source-readable.
• Reference form priority (graduated from #11577): LLM-loaded-byte budget > grep/source navigation > rendered-markdown clickability. Markdown-link form REJECTED as default.
• Forward rule (operator-stated): ANY new <a> HTML anchor tags in PRs → operator will close.
• V-B-A on revert feasibility: zero commits touched the 3 substrate files between #11571 merge (3d4c01f7) and current dev head (3d74aca7e). Pure git revert is mechanically zero-conflict.

The Fix

Three concurrent PRs against this ticket, cross-family lane split:

Lane A (revert): Pure git revert 3d4c01f7 (merge commit of #11571). Restores AGENTS.md → 21,106 bytes, AGENTS_STARTUP.md → 23,683 bytes, AGENTS_ATLAS.md → 18,409 bytes. Natural author lane: @neo-gpt (PR #11571 authorship).

Lane B (ADR amendment): Edit learn/agentos/decisions/0011-substrate-numbering-convention.md §2.1 worked example: replace [Text](path.md#anchor-id) markdown-link mandate with §<ref> text-only form. Retire or narrow §2.2 anchor-immutability rule (now applies to auto-generated heading IDs, not manual <a id> insertions). Natural author lane: @neo-gpt (PR #11568 authorship; ticket-create §11 authorship respect).

Lane C (lint inversion): ai/scripts/lint-agents.mjs — invert enforcement: block new <a id> HTML tag insertions in .agents/skills/** markdown (aligning with operator forward-rule); preserve positional §\d+ and semantic §<kebab> refs as both-acceptable. Update header JSDoc + Playwright test spec. Natural author lane: @neo-opus-4-7 (PR #11572 authorship).

Contract Ledger Matrix

Acceptance Criteria

• AC1: PR #11571 reverted on dev. Restored byte counts: AGENTS.md = 21,106, AGENTS_STARTUP.md = 23,683, learn/agentos/AGENTS_ATLAS.md = 18,409. Zero <a id> tags from #11571 remain.
• AC2: ADR 0011 §2.1 worked example reflects operator-corrected substrate (§<ref> text-only form; no <a id> tag mandate). §2.2 anchor-immutability narrowed to auto-generated heading IDs OR retired.
• AC3: ai/scripts/lint-agents.mjs inverted: blocks new <a id> HTML tag insertions in .agents/skills/**; permits positional §\d+ and semantic §<kebab> refs. Header JSDoc + Playwright test spec updated.
• AC4: Cross-family review on all 3 PRs (per operator forward-rule + #11577 graduation discipline).
• AC5: All 3 PRs merged; ticket closes.

Out of Scope

• Extending check-substrate-size.mjs:TARGET_FILES beyond AGENTS.md + .agents/ANTIGRAVITY_RULES.md (deferred per #11577 OQ5; separate ticket if pursued).
• Heading-form migration (## §anchor-id Title symmetric form) — deferred per #11577 OQ4; separate discussion/ticket.
• Migrating any other substrate to §<ref> form. The graduation captured a substrate-discipline statement, NOT a migration plan. Existing positional §<N> references remain valid.
• Re-litigating Discussion #11577 graduation. The substrate decision stands; this ticket executes it.

Avoided Traps

• In-place strip instead of revert (Lane A) — rejected. Operator framing: "no room for more mistakes." Full revert is mechanically zero-error; in-place strip risks missing insertions or introducing new artifacts. Revert is the substrate-correct shape for damage on a clean diff (V-B-A: zero post-#11571 commits touch the 3 files).
• Single-author bundling all 3 PRs — rejected. Cross-family lane split enforces the operator-stated forward rule (no new <a> tags) via independent cross-family review. Concentrating all 3 in one author bypasses the enforcement primitive.
• Leaving the damage as paid debt — rejected. With 1,927 bytes AGENTS.md headroom and mechanical truncation at 24,576 bytes, future map-substrate work would inherit a compressed budget. Operator-stated correctness-class not aesthetic.
• Filing 3 separate tickets — rejected. Operator framed "prio 0 item" (singular). Cross-family lane split is execution detail; single ticket with 3 ACs preserves the substrate-cleanup-as-one-unit framing for graph ingestion.

Related

• Graduated from: Discussion #11577 → graduation comment DC_kwDODSospM4BAt-P
• Closed parent epic: #11558 (operator-closed after substrate-correction)
• Damage PR: #11571 (merge commit 3d4c01f7)
• Cleanup targets: ADR via #11568 amendment; lint via #11572 inversion
• Sibling closed PRs: #11576 (Drop+Supersede), #11570 (closed-as-stale)
• Substrate discipline anchor: ADR 0007 (Map vs World Atlas compaction taxonomy)

Origin Session ID: 1b7a3403-06f3-4862-be80-479e129656de Retrieval Hint: query_raw_memories("Map Atlas compaction restore #11571 revert AGENTS.md 24KiB hard cap operator-corrected substrate Discussion #11577 graduation")