# The Anchor Protocol Specification (APS-1)

```text
Anchor Protocol Specification                         VorteXpert Labs
Document: APS-1                                       Sabber Ahamad Emon
Category: Open-Source Standards Track                 August 2026

                    The Anchor Protocol Specification
                                 (APS-1)
```

**Organization:** [VorteXpert Labs](https://github.com/vortexpert-labs)  
**Author:** [Sabber Ahamad Emon](https://github.com/sabber-ahamad-emon)  
**Status:** v1.0.0 (Approved Standard)

---

## Abstract
This document specifies the Anchor Protocol (APS-1), a formal standard for crystallizing, maintaining, and verifying consequential project orientation across human software engineers and autonomous AI coding agents.

## Status of This Memo
This memo defines an open-source engineering methodology and standard for software project context orientation. Distribution of this memo is unlimited.

---

## 1. Introduction & Core Axioms

### 1.1 The Trajectory Problem
Modern software development with autonomous AI coding agents suffers from trajectory degradation across multi-session tasks. As conversational context expands, Transformer attention degrades non-uniformly ("Lost in the Middle", Liu et al., 2023), context compaction erases negative constraints and architectural boundaries, and agents drift into zombie exploration loops.

Existing mechanisms (`AGENTS.md`, `CLAUDE.md`, ADRs, Git, RAG memory) address fragments of the problem:
- **Git** records *what syntax mutated*, but is silent on *why* alternatives were rejected.
- **ADRs** capture *past architectural decisions*, but lack active lifecycle state, project phase representation, and progressive disclosure indices for LLM prompt cache optimization.
- **Instruction Files (`AGENTS.md`)** define *agent behavior rules*, but accumulate unindexed, contradictory project state over time.
- **RAG / Vector Memory** fails on deontic logic (e.g., semantic cosine similarity clashes between positive recommendations and negative prohibitions).

The **Anchor Protocol** introduces the missing layer: **Deterministic Project Orientation**.

### 1.2 The Final Principle (Section 30 Hypothesis)
> **«The protocol is not trying to remember everything that happened. It is trying to preserve enough consequential anchors that a human or AI can understand the project's important trajectory without reconstructing that trajectory from raw sessions.»**
>
> The desired outcome is NOT: *"The AI remembers the project."*  
> The desired outcome IS: *"The project has a maintained set of anchors that keeps humans and AI oriented to what matters."*

### 1.3 Key Words for Requirement Levels
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in BCP 14, RFC 2119 / RFC 8174.

---

## 2. Epistemic Separation of Authority

The protocol enforces strict non-overlapping domains of epistemic authority:

1. **Source Code & AST:** The sole authority regarding *what is currently implemented and executable*.
2. **Git Version Control:** The sole authority regarding *line modification history, commit timestamps, and author identity*.
3. **The Anchor Layer (`.anchors/`):** The sole authority regarding *consequential project orientation, active goals, operational phase, active constraints, non-negotiable boundaries, and rejected paths*.
4. **Issue Trackers:** The authority regarding *task assignment, backlog ordering, and human schedule*.

### 2.1 The Code Supremacy Axiom
If an `ACTIVE` anchor directly contradicts source code or test suite reality:
- Code is authoritative regarding current execution.
- The Anchor **MUST** be declared **INVALIDATED** or **SUPERSEDED**.
- An AI agent **MUST NOT** mutate working codebase logic to match a stale anchor without explicit human confirmation.

---

## 3. Formal Ontology & Mathematical Model

### 3.1 The Anchor Tuple
An individual Anchor $a \in \mathcal{A}$ is an immutable 9-tuple:
$$a = \langle 	ext{id}, 	ext{type}, \sigma, 	au_{	ext{created}}, 	ext{claims}, 	ext{rationale}, \Pi, 	ext{Deps}, 	ext{Status} 
angle$$

Where:
- $	ext{id}$: Deterministic canonical identifier matching regex `^ANC-[0-9]{4}$`.
- $	ext{type} \in \{	ext{GOAL}, 	ext{STAGE}, 	ext{DECISION}, 	ext{CONSTRAINT}, 	ext{BOUNDARY}, 	ext{DISCOVERY}, 	ext{REJECTED\_PATH}\}$.
- $\sigma \in \Sigma_{	ext{lifecycle}} = \{	ext{PROPOSED}, 	ext{ACTIVE}, 	ext{SUPERSEDED}, 	ext{INVALIDATED}, 	ext{RETIRED}\}$.
- $	au_{	ext{created}}$: ISO-8601 UTC timestamp.
- $	ext{claims}$: Non-empty set of crystallized normative propositions (max 280 chars each).
- $	ext{rationale}$: High-density justification (max 1500 chars).
- $\Pi$: Provenance set (Git commit SHAs, PR URLs, benchmark paths).
- $	ext{Deps}$: Antecedent dependencies forming a strict Directed Acyclic Graph (DAG).
- $	ext{Status}$: Authority level (`HUMAN_APPROVED`, `AGENT_PROPOSED`, `SYSTEM_INVARIANT`).

### 3.2 The Crystallization Predicate ($W(c)$)
A candidate observation or conclusion $c$ in the fluid context stream is **Anchor-Worthy** ($W(c) = 	ext{True}$) if and only if:
$$W(c) \iff 	ext{Consequential}(c) \land 	ext{Established}(c) \land 	ext{NonRedundant}(c) \land 	ext{TrajectoryAltering}(c)$$

---

## 4. Anchor Lifecycle & State Machine

```mermaid
stateDiagram-v2
    [*] --> PROPOSED : Agent Drafts / Human Proposes
    PROPOSED --> ACTIVE : Human Approval / Consensus
    PROPOSED --> INVALIDATED : Flawed Premise / Rejected
    
    ACTIVE --> SUPERSEDED : New Anchor a_new supersedes a_old
    ACTIVE --> INVALIDATED : Contradiction / Empirical Error
    ACTIVE --> RETIRED : Phase / Scope Exhausted
    
    SUPERSEDED --> [*]
    INVALIDATED --> [*]
    RETIRED --> [*]
```

### 4.1 Lifecycle Invariants
1. **Dual-Layer Immutability:** The propositional body (`claims`, `rationale`, `created_at`) of an `ACTIVE` anchor **MUST NOT** be modified. Updates **MUST** occur via supersession by a newly created anchor.
2. **Monotonic Frontmatter Updates:** Only state transitions (`status`, `superseded_by`, `invalidated_by`, `updated_at`) **MAY** mutate frontmatter.
3. **Transitive Invalidation:** If anchor $a$ transitions to `INVALIDATED`, all downstream anchors declaring $a$ in `depends_on` **MUST** be flagged as `SUSPECT` and audited.

---

## 5. Canonical Repository Structure

Repositories adopting the Anchor Protocol **MUST** place orientation artifacts in the `.anchors/` root directory using a flat, modular layout:

```text
.anchors/
├── INDEX.md               <── Deterministic orientation manifest (~150-250 tokens)
├── schema.json            <── JSON Schema specification (Draft 2020-12)
├── ANC-0001-project-stage.md
├── ANC-0002-core-db-engine.md
└── ANC-0003-no-orm-constraint.md
```

### 5.1 The Root Index Manifest (`INDEX.md`)
The `INDEX.md` file is the entry point for progressive disclosure. It **MUST** contain:
1. Active Project Stage (`STAGE: PROTOTYPE | ALPHA | PRODUCTION | MAINTENANCE`).
2. Active High-Level Strategic Goals (`GOAL`).
3. An index table of all `ACTIVE` anchors with ID, Type, Title, and Scoped Modules.

---

## 6. Progressive Disclosure & Token Economics

Anchor Protocol enforces a 3-tier context hierarchy to optimize Large Language Model **Key-Value (KV) Prompt Prefix Caching**:

- **Tier 0 (Static Rules, ~150 tokens):** Tool adapter instructions (`AGENTS.md`, `CLAUDE.md`, `SKILL.md`). Cached permanently with 100% hit rate.
- **Tier 1 (Orientation Manifest, ~250 tokens):** `.anchors/INDEX.md`. Loaded on session initialization. Stable across multiple tasks with ~85–95% cache hit rate.
- **Tier 2 (Scoped Anchors, ~250 tokens each):** Loaded strictly on-demand when an agent touches a governed subsystem.

```text
Total Pre-flight Prompt Overhead = Tier 0 (~150) + Tier 1 (~250) = ~400 tokens (Constant O(1))
```

---

## 7. Agent Operating Procedure (AOP)

An AI coding agent interacting with an Anchor Protocol repository **MUST** follow this sequence:

1. **Pre-flight Orientation:**
   - Detect `.anchors/INDEX.md`.
   - Read `INDEX.md` into active context.
   - Verify task compatibility with current Project Stage and Active Constraints.
2. **In-flight Consultation:**
   - When modifying files in a module covered by an active anchor, retrieve that specific `ANC-XXXX.md` file.
   - Respect all negative constraints (`REJECTED_PATH`, `BOUNDARY`).
3. **Consequential Trigger:**
   - When an architectural decision, new invariant, or fatal flaw in an approach is identified, draft an anchor with `status: PROPOSED` and `authority: AGENT_PROPOSED`.
4. **Contradiction Resolution:**
   - If user prompts contradict an `ACTIVE` anchor, halt and prompt the user to choose between reaffirming the constraint or explicitly superseding it.
5. **Post-flight Cleanliness:**
   - Verify that no raw session transcripts, scratchpad logs, or temporary bug traces were written to `.anchors/`.

---

## 8. Anti-Patterns ("What NOT to Anchor")

The following **MUST NOT** be anchored:
1. **Ephemeral Scratchpads:** Unvalidated hypotheses and brainstorming notes.
2. **Bug Triage Logs:** Stack traces, compiler typos, and ordinary bugfixes.
3. **Session Transcripts:** Chronological narratives of conversation turns.
4. **Code Shadows:** Duplicate function signatures, ASTs, or database schemas.
5. **Framework Manuals:** Copy-pasted documentation for third-party libraries.
6. **Agile Ticket Clones:** Granular styling or micro-task checklists.

---

## 9. Brownfield Adoption

To retrofit Anchor Protocol onto an existing codebase without archaeological bloat:
1. **Passive Scan:** Identify primary framework, database engine, runtime target, and active linters.
2. **Genesis Crystallization:** Create **exactly 3 to 5 active anchors** representing active truths (Stage, Core Tech Stack, Invariants, Known Rejected Paths).
3. **Delimited Adapter Injection:** Inject non-destructive comment blocks (`<!-- ANCHOR-PROTOCOL-ADAPTER -->`) into existing tool instructions without altering existing developer runbooks.
*(See `docs/BROWNFIELD_ADOPTION.md` for full implementation)*