Substrate Numbering Semantic Anchor Migration

Context

After successive byte-budget-driven compaction passes (such as ADR 0007), the AGENTS.md and AGENTS_ATLAS.md cross-file positional numbering scheme (e.g., §21) decayed from a contiguous state to a fragmented "swiss-cheese" pattern. This positional decay creates an ongoing cognitive parsing cost for LLMs and introduces tokenization disconnects between headings (e.g., ## 21.) and inline references (§21).

The Problem

The cumulative LLM-readability cost of maintaining and parsing a fragmented positional numbering system across all future turns, sessions, and cross-family agents dwarfs the one-time migration effort. Preserving this positional decay as a "feature" violates substrate correctness principles optimized for LLM consumption.

The Architectural Reality

The positional numbering convention (§N) is structurally load-bearing and heavily referenced across .agents/skills/, learn/agentos/, AGENTS.md, and AGENTS_ATLAS.md. Positional decay introduces a structural hallucination risk whenever reference targets are shifted or compacted.

The Fix

Execute Option C: Semantic Anchor Migration globally. This eliminates the positional numbering convention entirely. We will replace all §N positional references with stable, explicit, and immutable semantic anchors (e.g., <a name="mailbox-check-protocol"></a>). The migration cascade will be governed by strict correctness substrates: new linting rules, CI enforcement, and explicit cross-family review, partitioned by substrate layer to bound blast radius.

Contract Ledger Matrix

Discussion Criteria Mapping (from Discussion #11557)

• OQ1 (Reference-class): Active/live instructions migrate to semantic anchors; historical/archaeology refs are preserved intentionally or get errata class.
• OQ2 (#11551 renumbering): Prospectively mooted as positional numbering is eliminated globally.
• OQ3 (Atlas numbering): AGENTS_ATLAS.md is fully included in the Option C semantic migration scope.
• OQ4 (Semantic-name stability): Use stable explicit IDs (kebab-case) verified by lint. If heading text changes, aliases must be preserved.
• OQ5 (AGENTS_STARTUP scope): Mapped to the AGENTS.md and AGENTS_ATLAS.md partition (#11561) for outbound reference migration.
• OQ6 (ADR vehicle): A new ADR will be authored at implementation time to serve as canonical authority.
• Migration blast-radius cascade: Epic ACs will enforce strict migration partitions and lint validations to manage the [⚠ PARTIAL] risk on blast-radius identified in the Step 2.5 Architectural Step-Back.

3-Family Signal Ledger

• Gemini (Cycle-4 StepBack): APPROVED
• Opus: APPROVED
• GPT: APPROVED
• Unresolved Dissent: empty
• Unresolved Liveness: empty

Acceptance Criteria

• Sub-ticket created: Author a new ADR establishing the Semantic Anchor Policy and deprecating positional numbering.
• Sub-ticket created: Extend ai/scripts/lint-agents.mjs (and CI workflow) to flag any new §N positional references in skill files as violations.
• Sub-ticket created: Execute semantic migration partition for AGENTS.md and AGENTS_ATLAS.md (injecting anchors and updating inter-file links).
• Sub-ticket created: Execute semantic migration partition for .agents/skills/ (updating all outgoing references to the new anchors).
• Sub-ticket created: Execute semantic migration partition for ADRs and miscellaneous documentation.
• Cross-family review explicitly obtained on migration PRs as an invariant merge gate.

Out of Scope

• Re-numbering or migrating historical/archaeological documentation where preserving original numbering is intentional and contextually appropriate.
• Arbitrary renaming of sections unrelated to the migration effort (minimize noise).

Avoided Traps / Gold Standards Rejected

• Codifying position-preservation (Option A/D): Rejected because it permanently preserves the LLM parsing cost and codifies the "swiss-cheese" decay as a feature.
• Contiguous renumbering (Option B): Rejected as a proven anti-pattern that temporarily fixes the symptom but recreates the exact same decay on the next compaction cycle.

Related

• Discussion: #11557 (Approved graduation trace for Option C globally)
• Dependencies: ADR 0007 (Compaction taxonomy)

Origin Session ID: d1aee218-8c42-4562-b2ec-f597284fa9d7 Retrieval Hint: "Semantic anchor migration", "Substrate Numbering Option C", "Discussion #11557"