Substrate-wide ## §semantic_concept_name heading form for all agent content

Context

Operator-direction 2026-05-18 ~22:00Z (paraphrase): "AGENTS.md heading anchors (## §mailbox_check_protocol) — operator-explicit, twice. limiting it to agents md would be stupid. anchor format for all agent content."

This ticket implements the substrate-wide convention — semantic-concept-named pure-anchor headings across ALL agent content. Trivial mechanical change; substrate-correct downstream-enabling: stable cross-substrate references, KB ingestion uniformity, graph node-naming uniformity, cross-document drops in tickets/PRs/discussions all resolve consistently.

Subsumes the ADR-amendment scope of #11591 (terminology restoration); this ticket is the broader substrate-wide convention + application that #11591 was scoped within.

The Problem

Current heading form across agent content is positional (## 21. The Mailbox Check Protocol (Pre-Flight at Turn Start)). Symptoms:

• Cross-substrate references rely on position; "swiss-cheese decay" under compaction (the original #11558 framing)
• KB ingestion can't reliably index by concept (positional anchors aren't semantic)
• Graph node names lose stability across substrate evolution
• Document-drops in tickets/PRs/discussions can't reliably link to specific concepts
• Byte budget bloated by heading prose duplication (## 21. The Mailbox Check Protocol ~30 bytes overhead vs ## §mailbox_check_protocol ~6 bytes overhead per heading)

Empirical anchor: Discussion #11577 graduated the corrected reference form (semantic §<ref> text-token, no HTML <a id> scaffolding). The graduated decision targeted REFERENCE form only — the heading form was implicit but unrealized. This ticket completes the convention.

The Architectural Reality

Pure-anchor heading form: ## §semantic_concept_name. Properties:

• Self-documenting: anchor IS the heading; no positional-tracking overhead
• Byte-cheapest: ~5-6 chars per heading vs ~30-60 chars current
• Cross-substrate stable: same identifier in AGENTS.md / skills / Atlas / ADRs / CLAUDE.md
• KB ingestion friendly: anchor names are concept-bearing tokens (LLM-extractable + graph-indexable)
• Cross-document drop friendly: §mailbox_check_protocol resolves consistently regardless of which agent-content file references it
• Lint-compatible: my own PR #11586 lint-agents.mjs:ANCHOR_TAG_PATTERN blocks HTML <a id> insertions but permits §<kebab> semantic text-refs. No regression.

Section descriptive prose lives in the section BODY (first paragraph), not in the heading. The heading is the anchor; the body is the explanation.

The Fix

Substrate-wide convention defined in amended ADR 0011 (currently scoped under #11591; this ticket subsumes that scope):

<h2 class="neo-h2" data-record-id="6">§semantic_concept_name</h2>

[Section body explaining the concept...]

In-substrate cross-references use §semantic_concept_name (matches the heading form):

See §mailbox_check_protocol for the protocol details.

Application phases (operator-decision on sequencing; ticket carries all phases):

• Phase 1 (proof-of-concept): ADR 0011 amendment + AGENTS.md conversion + direct-consumer cross-reference updates (.claude/CLAUDE.md, learn/agentos/measurements/cognitive-load-baseline-2026-05.md line 134/184)
• Phase 2: AGENTS_ATLAS.md + AGENTS_STARTUP.md (turn-loaded Map substrate)
• Phase 3: .agents/skills/**/*.md (SKILL.md + references payloads — also enables Map-vs-World-Atlas compaction per ADR 0007)
• Phase 4: learn/agentos/**/*.md (ADRs, guides, measurements, decisions)
• Phase 5: cross-content references in learn/, code JSDoc references to AGENTS.md/skill substrate

Acceptance Criteria

• AC1 (Phase 1 / convention land): ADR 0011 amended to define ## §semantic_concept_name substrate-wide heading form. AGENTS.md converted. Direct consumer cross-references updated.
• AC2 (Phase 2): AGENTS_ATLAS.md + AGENTS_STARTUP.md converted.
• AC3 (Phase 3): All .agents/skills/**/*.md converted (SKILL.md headings + references-payload headings).
• AC4 (Phase 4): All learn/agentos/**/*.md converted (ADRs, guides, measurements).
• AC5 (Phase 5): Code JSDoc + cross-content references updated to use §semantic_concept_name form.
• AC6: Cross-family review on each phase per pull-request-workflow.md §6.1.
• AC7: Each phase PR uses Refs #N (non-magic, partial-lane discipline) until the FINAL phase PR which uses Resolves #N.

Contract Ledger Matrix

Out of Scope

• HTML <a id> anchor-tag insertion — explicitly REJECTED per Discussion #11577 graduation + operator forward-rule (any new <a> tags in PRs → operator closes). PR #11586 lint-agents.mjs mechanically enforces this.
• Migrating historical/archaeology positional §N references (kept per ADR 0011 §2.3 historical-classification carve-out).
• Skill bloat audit (separate concern — covered by #11598 OQ4 future ticket).

Avoided Traps

• Limiting to AGENTS.md only — REJECTED per operator-direction (this turn). Two-tier system (one form for AGENTS.md, another for skills) would defeat cross-substrate reference stability.
• Hybrid form ## §21. The Mailbox Check Protocol — REJECTED. Retains positional number → re-introduces swiss-cheese decay risk. Pure anchor form is byte-cheapest + position-independent.
• Author all 5 phases in ONE PR — REJECTED per partial-lane discipline + operator's "step by step" framing. Phase 1 ships first as proof-of-concept; subsequent phases follow.
• File separate tickets per phase — REJECTED. ONE ticket carries all phases; phase PRs reference Refs #N until final phase uses Resolves #N. Avoids ticket-fanout (the META operator named in #11598).

Related

• Operator direction: in-session 2026-05-18 ~22:00Z (this turn)
• Source META Discussion: #11598 OQ2 (operator-broadened scope this turn)
• Reference-form authority: Discussion #11577 graduation comment DC_kwDODSospM4BAt-P
• ADR to amend: ADR 0011 — adds substrate-wide heading-form to §2.x
• Subsumes: #11591 (ADR 0011 terminology restore scope) — work happens here under broader scope
• Lint enforcement (already shipped): PR #11586 lint-agents.mjs blocks HTML <a> tag regressions; permits semantic §<kebab> form
• Substrate-cap mechanism: ai/scripts/check-substrate-size.mjs (24,576 byte cap — heading conversion reclaims ~400-800 bytes of AGENTS.md headroom)

Origin Session ID: 1b7a3403-06f3-4862-be80-479e129656de Retrieval Hint: query_raw_memories("substrate-wide heading anchor §semantic_concept_name agent content all files AGENTS.md AGENTS_ATLAS skills learn/agentos KB ingestion graph cross-substrate")