Context
Epic #11558 migrates live instruction substrate away from positional §N references. The AGENTS.md / AGENTS_ATLAS.md pair is the core turn-loaded map and atlas substrate, so this partition should happen separately from skill and ADR/documentation migrations.
The Problem
AGENTS.md and AGENTS_ATLAS.md currently contain fragmented section numbering and cross-file §N references. This creates recurring LLM parsing cost and makes instruction identity depend on compaction-sensitive positions.
The Architectural Reality
AGENTS.md is turn-loaded memory; AGENTS_ATLAS.md carries detailed expansion. Discussion #11557 v5 selected semantic anchors as the stable identity primitive. This ticket touches high-blast instruction substrate and must follow the new ADR from #11559 plus the lint guard from #11560 once available.
The Fix
Add stable semantic anchors to AGENTS.md and AGENTS_ATLAS.md and migrate live cross-references between these files away from positional §N references.
Expected scope:
AGENTS.md
learn/agentos/AGENTS_ATLAS.md
- references from startup or nearby agent docs only if they point into AGENTS/ATLAS live sections
Discussion Criteria Mapping
- OQ3 Atlas numbering audit -> AGENTS_ATLAS.md included in migration scope.
- OQ4 semantic stability -> use stable explicit IDs, not volatile raw heading text.
- Step 2.5 consumer sweep -> preserve human and agent readability.
- Active/archive boundary -> live instruction refs migrate; historical references stay intentional.
Acceptance Criteria
Out of Scope
- Migrating
.agents/skills/** references.
- Migrating ADR and general docs references.
- Changing the actual policy content beyond anchor/reference mechanics.
Avoided Traps / Gold Standards Rejected
- Contiguous renumbering is rejected as a temporary cosmetic repair.
- Rewriting unrelated AGENTS content to save bytes is rejected; this ticket is about anchor identity only.
Related
Origin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da
Retrieval Hint: "AGENTS.md AGENTS_ATLAS.md semantic anchors cross references Option C #11558"
Context
Epic #11558 migrates live instruction substrate away from positional
§Nreferences. The AGENTS.md / AGENTS_ATLAS.md pair is the core turn-loaded map and atlas substrate, so this partition should happen separately from skill and ADR/documentation migrations.The Problem
AGENTS.md and AGENTS_ATLAS.md currently contain fragmented section numbering and cross-file
§Nreferences. This creates recurring LLM parsing cost and makes instruction identity depend on compaction-sensitive positions.The Architectural Reality
AGENTS.md is turn-loaded memory; AGENTS_ATLAS.md carries detailed expansion. Discussion #11557 v5 selected semantic anchors as the stable identity primitive. This ticket touches high-blast instruction substrate and must follow the new ADR from #11559 plus the lint guard from #11560 once available.
The Fix
Add stable semantic anchors to AGENTS.md and AGENTS_ATLAS.md and migrate live cross-references between these files away from positional
§Nreferences.Expected scope:
AGENTS.mdlearn/agentos/AGENTS_ATLAS.mdDiscussion Criteria Mapping
Acceptance Criteria
§Nidentity.Out of Scope
.agents/skills/**references.Avoided Traps / Gold Standards Rejected
Related
Origin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da Retrieval Hint: "AGENTS.md AGENTS_ATLAS.md semantic anchors cross references Option C #11558"