Context
Discussion #11557 graduated to Epic #11558 with cross-family consensus on Option C: global semantic-anchor migration for AGENTS.md / AGENTS_ATLAS.md / skill and documentation references. The first required substrate partition is the policy authority: a new ADR that defines the semantic-anchor convention and deprecates positional §N references for live instruction substrate.
The Problem
The current positional section-number scheme has decayed under byte-budget compaction. Agents and humans still cite §N references across skills and docs, which makes reference identity depend on mutable section position instead of stable meaning. Without an ADR, downstream PRs have no durable authority for anchor format, alias preservation, active-vs-archive handling, or lint scope.
The Architectural Reality
ADR 0007 remains the canonical compaction taxonomy and its historical baseline must not be rewritten. Discussion #11557 v5 selects a new policy layer, not an ADR 0007 mutation. Existing ADR numbers 0009 and 0010 are occupied; the implementation must choose the next available ADR number against current origin/dev.
The Fix
Author a new ADR, likely learn/agentos/decisions/0011-substrate-numbering-convention.md if still available at implementation time, defining:
- stable explicit semantic IDs as the reference identity for live instruction substrate
- alias preservation when headings are renamed
- active/live refs vs historical/archaeology refs
- deprecation of new
§N positional references in live skill / instruction surfaces
- migration partitioning under Epic #11558
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| Semantic anchor policy |
New ADR |
Stable semantic IDs replace positional §N for live substrate refs |
Historical refs may preserve original numbering with explicit archaeology status |
New ADR |
Discussion #11557 v5 + StepBack DC_kwDODSospM4BArSy |
| Heading rename behavior |
New ADR |
Existing anchor IDs remain immutable; old IDs preserved as aliases |
Errata class for intentional archaeology |
New ADR |
GPT approval DC_kwDODSospM4BArTV |
Discussion Criteria Mapping
- OQ4 semantic-name stability -> ADR AC for immutable explicit IDs and alias preservation.
- Step 2.5 path determinism -> ADR AC for identity resolved by anchor ID, not heading text or position.
- Active/archive boundary -> ADR AC for live vs historical reference handling.
- OQ6 ADR vehicle -> this ticket.
Acceptance Criteria
Out of Scope
- Migrating every reference in this ticket.
- Rewriting ADR 0007 historical baseline.
- Adding lint implementation.
Avoided Traps / Gold Standards Rejected
- Reusing ADR 0007 as mutable policy clay is rejected because ADR 0007's baseline is historical.
- Contiguous renumbering is rejected because it recreates the same decay class after the next compaction.
Related
- Parent Epic: #11558
- Discussion: #11557
- StepBack:
DC_kwDODSospM4BArSy
- GPT approval:
DC_kwDODSospM4BArTV
Origin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da
Retrieval Hint: "#11557 Option C semantic anchor policy ADR path determinism state mutability active archive"
Context
Discussion #11557 graduated to Epic #11558 with cross-family consensus on Option C: global semantic-anchor migration for AGENTS.md / AGENTS_ATLAS.md / skill and documentation references. The first required substrate partition is the policy authority: a new ADR that defines the semantic-anchor convention and deprecates positional
§Nreferences for live instruction substrate.The Problem
The current positional section-number scheme has decayed under byte-budget compaction. Agents and humans still cite
§Nreferences across skills and docs, which makes reference identity depend on mutable section position instead of stable meaning. Without an ADR, downstream PRs have no durable authority for anchor format, alias preservation, active-vs-archive handling, or lint scope.The Architectural Reality
ADR 0007 remains the canonical compaction taxonomy and its historical baseline must not be rewritten. Discussion #11557 v5 selects a new policy layer, not an ADR 0007 mutation. Existing ADR numbers 0009 and 0010 are occupied; the implementation must choose the next available ADR number against current
origin/dev.The Fix
Author a new ADR, likely
learn/agentos/decisions/0011-substrate-numbering-convention.mdif still available at implementation time, defining:§Npositional references in live skill / instruction surfacesContract Ledger Matrix
§Nfor live substrate refsDC_kwDODSospM4BArSyDC_kwDODSospM4BArTVDiscussion Criteria Mapping
Acceptance Criteria
Out of Scope
Avoided Traps / Gold Standards Rejected
Related
DC_kwDODSospM4BArSyDC_kwDODSospM4BArTVOrigin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da Retrieval Hint: "#11557 Option C semantic anchor policy ADR path determinism state mutability active archive"