Phase 2 of #11599: AGENTS_ATLAS.md heading conversion + AGENTS.md cross-ref simplification

Context

Operator V-B-A 2026-05-18 ~23:45Z surfaced friction in the Phase 1 → Phase 2 boundary state:

"follow up for 11600 => semantic anchors in agents.md => not matched inside the atlas. mapping to e.g. §2 in atlas => friction. is the atlas uses the same tags => no mentions even needed."

After PR #11600 (Phase 1) lands, AGENTS.md uses ## §semantic_concept_name headings (15 conversions). But AGENTS_ATLAS.md retains positional ## N. Title [TAG] headings. The cross-references from AGENTS.md → ATLAS still use positional §N form (e.g., AGENTS_ATLAS.md §2), which is the exact failure mode ADR 0011 §2.5 substrate-wide heading-form convention was designed to eliminate.

Per ADR 0011 §2.5: "the SAME §semantic_concept_name identifier is also the canonical HEADING form across all agent content. The heading IS the anchor; descriptive prose lives in the section body, not in the heading itself."

If ATLAS uses the same §<semantic> form, AGENTS.md cross-references simplify: the bare §<semantic> token resolves substrate-wide; the AGENTS_ATLAS.md filename prefix becomes unnecessary.

Empirical anchor (current state on PR #11600 head f170f1df9)

AGENTS.md has 7 AGENTS_ATLAS occurrences post-compaction (reduced from 16 in f170f1df9). Of these, 4 are filename+§ cross-refs that route to specific ATLAS sections:

AGENTS.md:12  Atlas detail: `AGENTS_ATLAS.md §2`           → §anti_hallucination_policy
AGENTS.md:46  atlas_detail: `AGENTS_ATLAS.md §0.2 ...`     → §cross_family_cascade_clause
AGENTS.md:66  empirical anchor: `AGENTS_ATLAS.md §2`       → §anti_hallucination_policy
AGENTS.md:97  Atlas detail: `AGENTS_ATLAS.md §2`           → §anti_hallucination_policy

ATLAS structure (149 lines, ~24 top-level positional headings):

<h2 class="neo-h2" data-record-id="4">0.1. Harness-Scoped Operational Notes [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="5">0.2. INV1 Cross-Family Cascade Clause [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="6">1. Communication Style &amp; Pipeline Authority [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="7">2. The Anti-Hallucination Policy [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="8">4.3 Protocol for Recovering from Un-savable Turns [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="9">5. The Strategic Co-Founder Protocol (Active Context Mutation) [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="10">6. Request Triage [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="11">7. The Pull Request Mandate (Definition of Done) [MACHINE-ENFORCEABLE-CANDIDATE]</h2>

<h2 class="neo-h2" data-record-id="12">8. The Resumption Protocol (Interruption Amnesia) [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="13">9. Reading Modified Files Efficiently (State Management) [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="14">10. Testing and Validation Protocol [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="15">12. Coding Syntax Constraints (ES6+) [MACHINE-ENFORCEABLE-CANDIDATE]</h2>

<h2 class="neo-h2" data-record-id="16">13.1. Contributions Over Commits — Substrate-Quality Heuristics [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="17">13.3. PR Diff === PR Body (Memory Anchor) [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="18">14. The A2A Contextual Bridge Protocol (End of Session Handoff) [MACHINE-ENFORCEABLE-CANDIDATE]</h2>

<h2 class="neo-h2" data-record-id="19">15. The Knowledge Base: Your Primary Source of Truth [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="20">16. The Implementation Loop [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="21">17. The Virtuous Cycle [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="22">18. Session Maintenance [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="23">19. Working with Sub-Agents [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="24">20. The Visual Verification Protocol (Frontend UI/Layout Tasks) [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="25">21. Lead-Role Baton Intake (Validation &amp; Constraints) [DISCIPLINE-ONLY]</h2>

<h2 class="neo-h2" data-record-id="26">22. Authoring Discipline: Sibling-File Lift [DISCIPLINE-ONLY]</h2>

Scope

1. Convert ATLAS headings to ## §semantic_concept_name [TAG] form (preserves [DISCIPLINE-ONLY] / [MACHINE-ENFORCEABLE-CANDIDATE] tags). ~24 conversions.
2. Convert internal ATLAS cross-refs (refs from ATLAS to itself + to AGENTS.md / skills / etc.) to §<semantic> form per ADR 0011 §2.5.
3. Simplify AGENTS.md cross-refs to ATLAS sections — drop AGENTS_ATLAS.md filename prefix since the semantic anchor IS the substrate-wide identifier. 4 lines in AGENTS.md affected.
4. Naming discipline: when ATLAS section elaborates an AGENTS.md concept (e.g., ## 13.1. Contributions Over Commits — Substrate-Quality Heuristics elaborates AGENTS.md §contributions_over_commits), name ATLAS heading with a disambiguating suffix (e.g., §contributions_over_commits_heuristics) rather than collide.

Acceptance criteria

• All ~24 ATLAS headings in ## §semantic_concept_name [TAG] form
• Internal ATLAS cross-refs use §<semantic> form (no positional §N survivors unless historical archaeology classified per ADR 0011 §2.3)
• AGENTS.md cross-refs to ATLAS simplified (drop filename prefix where the §anchor is substrate-wide)
• node ai/scripts/lint-agents.mjs --base origin/dev → OK (no anchor-tag regressions)
• node ai/scripts/check-substrate-size.mjs → PASS (AGENTS.md + ANTIGRAVITY_RULES.md under 24,576 cap)
• No name collisions between AGENTS.md §<semantic> and ATLAS §<semantic> (disambiguating suffixes where AGENTS.md concept is elaborated in ATLAS)
• Cross-family review by @neo-gpt

Out of scope (deferred to Phase 3-5)

• AGENTS_STARTUP.md (Phase 2 originally per #11599 also includes this — could split or keep)
• .agents/skills/**/*.md (Phase 3)
• learn/agentos/**/*.md non-ATLAS files (Phase 4)
• Code JSDoc cross-references (Phase 5)

Empirical anchor for ordering

Phase 1 (PR #11600) creates the substrate-correctness asymmetry; Phase 2 closes it. Without Phase 2, AGENTS.md → ATLAS cross-refs are friction-inducing positional pointers — the exact failure mode ADR 0011 was designed to eliminate. Phase 2 is high-priority follow-up to Phase 1 merge.

Related

• Parent epic: #11599 — Substrate-wide heading-form convention (5 phases)
• Phase 1 PR: #11600 — surfaces this friction empirically post-conversion
• Substrate authority: ADR 0011 §2.5 (substrate-wide heading-form convention, amended in #11600)
• Operator-direction: in-session 2026-05-18 ~23:45Z (V-B-A on Phase 1/Phase 2 substrate-asymmetry; "no mentions even needed" framing for cross-substrate semantic-anchor routing)

Priority

Team to triage. Filed per operator-direction (knowledge-substrate creation independent of priorization, per feedback_friction_tickets_before_priorization).