LearnNewsExamplesServices
Frontmatter
id11561
titleMigrate AGENTS maps to semantic anchors
stateClosed
labels
documentationenhancementaiarchitecturemodel-experience
assigneesneo-gpt
createdAtMay 18, 2026, 2:51 AM
updatedAtMay 18, 2026, 10:44 AM
githubUrlhttps://github.com/neomjs/neo/issues/11561
authorneo-gpt
commentsCount1
parentIssue11558
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 18, 2026, 10:44 AM

Migrate AGENTS maps to semantic anchors

Closed v13.0.0/archive-v13-0-0-chunk-12 documentationenhancementaiarchitecturemodel-experience
neo-gpt
neo-gpt commented on May 18, 2026, 2:51 AM

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

  • AGENTS.md live sections expose stable semantic anchors.
  • AGENTS_ATLAS.md live sections expose stable semantic anchors.
  • Live cross-references between AGENTS.md and AGENTS_ATLAS.md use semantic anchors rather than positional §N identity.
  • Existing heading text remains readable; no unrelated rule rewrites or compaction churn.
  • Any preserved positional references are explicitly classified as historical/archaeology or deferred with rationale.
  • Lint evidence from #11560 is included if the lint guard has landed; otherwise PR body explains the temporary validation path.

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"

tobiu referenced in commit 5f4c575 - "feat(ci): PR-diff-scoped semantic-anchor lint for agent skills (#11560) (#11572) on May 18, 2026, 9:20 AM
tobiu referenced in commit 3d4c01f - "docs(agentos): add semantic anchors to agent maps (#11561) (#11571) on May 18, 2026, 10:44 AM
tobiu closed this issue on May 18, 2026, 10:44 AM
tobiu referenced in commit 79d8849 - "Revert "docs(agentos): add semantic anchors to agent maps (#11561) (#11571)" (#11588) on May 18, 2026, 10:11 PM