AGENTS.md non-contiguous section numbering — audit + decide treatment

Context

Surfaced 2026-05-18 by @tobiu post-#11551 + #11553 work: "we fixed the §21 numbering gap inside AGENTS.md. and no one actually looked into the full number ordering :)". The localized renumbering in #11551 (§22→§21 + §23→§22 after §21 retirement) plus #11553's follow-up §-ref cleanup addressed ONE gap. The broader AGENTS.md has substantial numbering discontinuities that the localized work did not surface.

The Problem

Empirical inventory of current AGENTS.md ## N. section headers (sections 0-22):

Present (9): §0, §3, §3.5, §4, §11, §13 (with §13.1, §13.2, §13.3), §15 (only §15.5 + §15.6 subsections), §21, §22

Missing (13): §1, §2, §5, §6, §7, §8, §9, §10, §12, §14, §16, §17, §18, §19, §20

The missing sections are mostly intentional move/compress-to-trigger retirements per ADR 0007 §2.1 baseline taxonomy:

• §1 Communication Style, §2 Anti-Hallucination → moved to Atlas
• §5 Strategic Co-Founder, §6 Request Triage, §7 PR Mandate, §8 Resumption Protocol, §9 Reading Files → moved
• §10 Testing Protocol → compress-to-trigger
• §12 Coding Syntax, §14 Sunset, §15.1-15.4, §16-§19 → moved
• §20 Visual Verification → compress-to-trigger

The substrate-discipline question is: what's the contract for AGENTS.md section numbering when a section is retired or moved?

#11551's choice to renumber §22→§21 + §23→§22 after the §21 (Workflow Skills) retirement broke the convention that ADR 0007's baseline appears to assume (positions preserved after move/compress-to-trigger/retire). The current state is mixed: most retirements preserved their position (§1, §2, etc. left empty); the §21 retirement got renumbered. Refs across the substrate now resolve differently depending on whether the section was retired before or after #11551.

The Architectural Reality

§N references in AGENTS.md are consumed widely:

• Skill files: .agents/skills/*/SKILL.md + references payloads (semantic-anchor migration started in #11553's 5c8db24 for select files)
• ADRs: learn/agentos/decisions/0007-agents-md-compaction-taxonomy.md, 0008-skill-anatomy-and-authoring-contract.md
• Lint scripts: ai/scripts/check-retired-primitives.mjs, check-substrate-size.mjs (JSDoc Pre-Flight comments)
• Workflow files: pull-request-workflow.md, pr-review-guide.md, etc.

Any §-number mutation cascades across this surface. #11553 demonstrated the cost (12+ files updated for a single §21 retirement) and seeded the forward-preventive alternative: semantic anchors ("Mailbox Check Protocol" instead of "§21 Mailbox Check").

The Fix

Audit + decide treatment. Three candidate strategies:

Option A — Preserve original positions strictly

• Undo #11551's renumber: restore §22 (Mailbox Check) + §23 (Edge-Case Triggers)
• Convention: section positions stable across retirements/moves; gaps are first-class historical anchors
• Cost: 1 follow-up PR + reverse-sweep across skill substrate (re-update files updated in #11553)
• Trade-off: re-creates the §-ref staleness friction that #11553 just resolved

Option B — Contiguous renumber everything

• Renumber 0, 1, 2, 3, ... contiguously (or 0, 1, 2 with 0=Critical Gates)
• Convention: section numbers are ordinal navigation indices
• Cost: massive cascade across ALL §-refs in skill files / ADRs / lint scripts
• Trade-off: brittle to future retirements; semantic-anchor refactor remains the better long-term answer

Option C — Semantic anchor migration globally (forward-preventive)

• Extend #11553's 5c8db24 pattern: replace ALL §N refs in skill substrate with semantic anchors ("Critical Gates", "Mailbox Check Protocol", "Schlagfertig Readiness", etc.)
• Convention: AGENTS.md section numbers become decorative/historical; semantic names are the canonical reference primitive
• Cost: substantial cascade BUT pays off permanently — future compactions cause zero §-ref staleness
• Trade-off: requires care to choose stable semantic names; some §-names might benefit from rename for clarity

Recommendation lean: Option C is substrate-correct long-term (matches #11553's forward-preventive direction), but the audit should validate before commitment. Option A is the smallest-blast rollback path if Option C audit reveals semantic-name instability.

Acceptance Criteria

• Inventory of all §N references across skill substrate / ADRs / lint scripts / workflow files (machine-grep-able)
• Audit doc landed in learn/agentos/audits/ or similar location with the inventory + per-reference categorization (position-stable / position-mutated / ambiguous)
• Decision recorded: A vs B vs C (or hybrid)
• Execution plan if A or C selected; if B, scope estimated; if hybrid, partition clearly identified
• Cross-family review on the decision (high-blast substrate convention)

Out of Scope

• Execution of the chosen strategy. Audit + decision first; execution is a follow-up ticket.
• Renaming sections for clarity (e.g., "Memory Core Protocol" → cleaner name). Separate concern; this audit is about numbering convention, not naming.
• Re-litigating #11551's retirement of §21 Workflow Skills. That decision stands; the question is only about the renumbering pattern post-retirement.

Avoided Traps

• Auto-renumber without audit. Would cascade-fail across the substrate. The §-ref count in skill files is non-trivial; #11553 demonstrated cost of even a 2-position shift.
• Dismiss as aesthetic. #11553 already proved §-refs cause real staleness friction (4+ commits, force-pushes, CI iteration to fix the §22→§21 + §23→§22 cleanup). The discontinuity matters when refs are consumed.
• Lock to Option C without audit. Semantic anchors are forward-preventive, but some names are unstable (sections that have been renamed across the substrate history). Audit reveals which §-positions have stable semantic names.

Related

• #11551 (the localized §21→§22→§23 renumber that surfaced the convention question)
• #11553 (the forward-preventive semantic-trigger refactor in select skill files — proves Option C is viable)
• ADR 0007 (compaction taxonomy — baseline section dispositions)
• ADR 0008 (skill anatomy + retirement-context handling)

Origin Session ID: 39eee906-3fd4-424f-9348-828b46ece38c Handoff Retrieval Hint: "AGENTS.md section numbering discontinuity audit option-A-B-C decision"