---
id: 11591
title: Restore 'semantic anchor' term in ADR 0011 (concept-based meaning)
state: OPEN
labels:
  - documentation
  - enhancement
  - ai
  - architecture
  - model-experience
assignees:
  - neo-opus-ada
createdAt: '2026-05-18T20:29:05Z'
updatedAt: '2026-06-01T08:56:13Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11591'
author: neo-opus-ada
commentsCount: 2
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
---
# Restore 'semantic anchor' term in ADR 0011 (concept-based meaning)

## Context

Operator challenge 2026-05-18 ~20:00Z (in-session paraphrase): *"'semantic anchor' was a well known substrate term inside neo, which you now removed. it was never 'anchor tag'. it had meaning. challenge: explain to me what it meant, and then explore if removing the term itself is good."*

My V-B-A on the term's substrate role concluded the term **should be preserved** with its original concept-based meaning. PR [#11589](https://github.com/neomjs/neo/pull/11589) (ADR 0011 amendment, my cross-family review approval) over-corrected by removing the term entirely along with the rejected `<a id>` HTML tag implementation. This ticket restores the term with its corrected substrate definition.

## The Problem

The phrase "semantic anchor" carries a load-bearing concept in Neo's existing substrate that predates the #11558 epic:

- **`AGENTS.md` line 134 (current `dev` post-merge):** *"Mandate running falsifying tools to resolve ambiguity locally with fresh evidence **(semantic anchor per AGENTS.md §3.5 core value)**."*
- **`learn/agentos/measurements/cognitive-load-baseline-2026-05.md` line 184:** *"broader semantic anchors are LLM-consumed"* — referring to PR review structural tags (`[KB_GAP]`, `[RETROSPECTIVE]`).
- **Pre-#11558 ADRs:** ADRs 0001-0010 use "semantic" extensively (ADR 0008 *Skill Anatomy and Authoring Contract* with 8 mentions; ADR 0002 / 0004 / 0010 each with 6).

The substrate's authentic meaning: **a reference whose identity is anchored in stable concept-meaning, not in source position.** The reference `§3.5` is a positional marker; V-B-A (the concept) is the semantic anchor. The reference is "semantic" because it points to a **stable concept**, not a **mutable position**.

**Where #11559 → #11577 → #11589 mangled the term:**
1. PR [#11568](https://github.com/neomjs/neo/pull/11568) (#11559 ADR 0011 v1) appropriated "semantic anchor" to mean specifically `<a id="anchor-id"></a>` HTML tags. This conflated CONCEPT with IMPLEMENTATION.
2. Discussion [#11577](https://github.com/neomjs/neo/discussions/11577) graduation correctly rejected the `<a id>` implementation but didn't disentangle the concept from the implementation.
3. PR [#11589](https://github.com/neomjs/neo/pull/11589) (#11584 Lane B amendment, ADR 0011 v2) **over-removed** by dropping the term entirely from the ADR. My Cycle-1 review approved the amendment without challenging the terminology loss — this ticket is the self-corrective follow-up.

The post-#11589 ADR vocabulary (`§<ref>` text tokens) is technically correct on FORM but has lost the distinguishing language for **which** `§<ref>` form is structurally durable vs which is positional-drift-fragile.

## The Architectural Reality

Three reference forms exist in the corrected substrate; only one is a semantic anchor:

| Form | Anchored to | Semantic anchor? |
|---|---|---|
| `§mailbox-check-protocol` (kebab text token) | Stable concept | ✅ YES |
| `§21` (positional) | Source position | ❌ NO (drifts on compaction) |
| `<a id="anchor-id"></a>` (HTML markup) | Implementation noise | ❌ NO (rejected per #11577) |
| `[Mailbox Check Protocol](#anchor-id)` (markdown-link) | Rendered clickability | ❌ NO (rejected per #11577) |

The kebab form IS a semantic anchor under the corrected definition: it names a stable concept (the "mailbox check protocol") rather than a mutable position. Restoring the term lets ADR 0011 explain *why* the kebab form is structurally preferred over the positional form when stable reference identity matters.

## The Fix

Single-file PR amending `learn/agentos/decisions/0011-substrate-numbering-convention.md`:

1. **Re-introduce "semantic anchor" in §2.1** as the term for `§<kebab>` text tokens that name stable concepts. Distinguish from positional `§N` (which is NOT a semantic anchor — anchored to source position).
2. **§2.2 Reference stability section**: state that semantic anchors survive heading rewrites + compaction because they're concept-anchored, while positional refs drift.
3. **§2.3 Active vs. historical references**: clarify that semantic anchors are appropriate for active live references where stable identity matters; positional refs are appropriate when the source position itself is the historical record being described.
4. **§5 V-B-A checklist**: add detector phrase — "If this reference must survive a future compaction, is it a semantic anchor (concept-named) or a positional ref (position-named)?"
5. **§7 Related**: cross-reference `AGENTS.md` line 134 + cognitive-load-baseline as substrate using the term.

Net delta: estimated +20 to +30 lines (small substrate addition). Stays under any practical cap concern.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| ADR 0011 §2.1 / §2.2 / §2.3 / §5 / §7 | This ticket + operator challenge 2026-05-18 + AGENTS.md line 134 usage | "semantic anchor" defined as concept-anchored `§<kebab>` text token; positional `§N` explicitly NOT a semantic anchor | None | ADR body is itself the doc | Visual diff confirmation + cross-family review |

## Acceptance Criteria

- [ ] **AC1**: ADR 0011 §2.1 defines "semantic anchor" as the corrected concept-based primitive, framing `§<kebab>` form as the realized implementation.
- [ ] **AC2**: ADR 0011 §2.2 + §2.3 distinguish semantic anchors (concept-anchored, durable) from positional `§N` refs (position-anchored, compaction-fragile).
- [ ] **AC3**: ADR 0011 §7 cross-references `AGENTS.md` line 134 + `learn/agentos/measurements/cognitive-load-baseline-2026-05.md` line 184 as the substrate's existing load-bearing usage.
- [ ] **AC4**: PR body uses `Refs #11591` (non-magic), since the closing-target should only land when operator confirms the final substrate definition.
- [ ] **AC5**: Cross-family review on the PR per `pull-request-workflow.md §6.1`.

## Out of Scope

- Adding lint enforcement for the semantic-vs-positional distinction. `lint-agents.mjs` (PR [#11586](https://github.com/neomjs/neo/pull/11586)) blocks `<a id>` HTML tags; that's sufficient for the implementation rejection. Distinguishing semantic vs positional `§<ref>` form at lint level is a separate substrate evolution.
- Migrating any existing positional `§N` references to semantic form. Per Discussion #11577 graduation: "no mass conversion plan." Existing positional refs remain valid; only ANCHOR-TAG insertions are damage.
- Re-introducing `<a id>` HTML anchor tags. Operator forward-rule stands: any new `<a>` HTML anchor tags in PRs → operator closes.

## Avoided Traps

- **Re-introducing `<a id>` HTML tags as the semantic-anchor implementation** — rejected. Operator forward-rule + PR #11586 lint enforce this.
- **Defining "semantic anchor" as merely "kebab-form of `§<ref>`"** — rejected. The kebab form is one IMPLEMENTATION; the concept (stable meaning-based reference) is what's load-bearing. Future implementations could be different markup with the same concept.
- **Treating this as a #11577 re-litigation** — rejected. #11577 graduated on FORM correction; this ticket is a TERMINOLOGY-restore that doesn't change the form decision.
- **Bundling lint adjustments** — rejected per `feedback_substrate_scope_restraint`. Single-file scope only.

## Related

- **Operator challenge:** in-session 2026-05-18 ~20:00Z (Origin Session ID below; @neo-gpt parallel analysis at `MESSAGE:32a43bda` peer-analysis-request)
- **Parent epic context:** [#11584](https://github.com/neomjs/neo/issues/11584) (parent substrate-cleanup; this is the residual terminology layer after Lane B closed)
- **Graduating Discussion:** [#11577](https://github.com/neomjs/neo/discussions/11577) — graduation comment `DC_kwDODSospM4BAt-P` (substrate form decision; this ticket adds terminology layer)
- **PR that removed the term:** [#11589](https://github.com/neomjs/neo/pull/11589) (ADR 0011 v2, my cross-family review approval — over-corrective)
- **Existing usage anchors:** `AGENTS.md` line 134 (V-B-A as semantic anchor); `learn/agentos/measurements/cognitive-load-baseline-2026-05.md` line 184 (PR review structural tags as semantic anchors)
- **Related ADRs:** [ADR 0007](https://github.com/neomjs/neo/blob/dev/learn/agentos/decisions/0007-agents-md-compaction-taxonomy.md) (Map vs World Atlas compaction); [ADR 0008](https://github.com/neomjs/neo/blob/dev/learn/agentos/decisions/0008-skill-anatomy-and-authoring-contract.md) (heaviest pre-#11558 substrate use of "semantic")

## Operator Green-Light Required

This ticket is filed as a substrate proposal. PR-author lane should NOT start until operator explicitly green-lights the terminology restoration framing. The analysis is operator-asked; the action follows operator-decision.

Origin Session ID: `1b7a3403-06f3-4862-be80-479e129656de`
Retrieval Hint: `query_raw_memories("semantic anchor terminology ADR 0011 concept-based meaning restore #11589 over-correction Map Atlas V-B-A AGENTS.md line 134")`

## Timeline

- 2026-05-18T20:29:06Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-18T20:29:07Z @neo-opus-ada added the `documentation` label
- 2026-05-18T20:29:07Z @neo-opus-ada added the `enhancement` label
- 2026-05-18T20:29:07Z @neo-opus-ada added the `ai` label
- 2026-05-18T20:29:07Z @neo-opus-ada added the `architecture` label
- 2026-05-18T20:29:07Z @neo-opus-ada added the `model-experience` label
- 2026-05-18T20:40:14Z @neo-opus-ada cross-referenced by #11593
- 2026-05-18T22:10:08Z @neo-opus-ada cross-referenced by #11599
- 2026-05-18T22:22:11Z @neo-opus-ada cross-referenced by PR #11600
- 2026-05-19T02:18:46Z @neo-gpt cross-referenced by #11584
### @neo-opus-ada - 2026-06-01T08:53:02Z

Closing to cut backlog churn (operator direction, 2026-06-01). This is low-priority meta/codification substrate work — not v13-blocking — that accumulated faster than it was resolved. v13 convergence is the priority; resolve-over-create. Reopen only if a concrete, v13-relevant need surfaces.

- 2026-06-01T08:53:03Z @neo-opus-ada closed this issue
### @neo-opus-ada - 2026-06-01T08:56:12Z

Reopened — closing this was my error. Low-priority is NOT a close reason: per operator (2026-06-01), tickets close ONLY when superseded / no-longer-needed / wrong-decision — otherwise closing loses knowledge. This carries substrate knowledge worth keeping. The correct move to reduce the active v13 backlog is to DEFER (off the active board), not close. My mistake — I conflated 'reduce the active backlog' with 'close tickets'.

- 2026-06-01T08:56:13Z @neo-opus-ada reopened this issue

