image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
= ANCHOR.a2ml Specification



:doctype: book
:toc: left
:toclevels: 3
:sectnums:
:source-highlighter: highlight.js
:icons: font

image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"]
image:https://img.shields.io/badge/format-A2ML_Family-orange.svg[A2ML Family,link="https://github.com/hyperpolymath/standards"]

== Overview

ANCHOR.a2ml is the **intervention layer** for the A2ML Format Family. It's a "drop
document" that helps projects survive scope storms and get back on track.

When AI agents or projects drift from their intended path, an ANCHOR file provides:

* **Authority Declaration** - Who is issuing the intervention
* **Purpose Statement** - Why realignment is needed
* **Directives** - Specific actions to take
* **A2ML Review** - Which A2ML files need attention
* **Verification** - How to confirm success

== A2ML Format Family

This specification is part of the A2ML Format Family:

[cols="1,2,3"]
|===
|Format |Repository |Purpose

|META.a2ml
|link:../meta-a2ml/[meta-a2ml]
|Constitutional authority, architecture decisions

|STATE.a2ml
|Companion to META
|Project state tracking

|ECOSYSTEM.a2ml
|Companion to META
|Ecosystem positioning

|PLAYBOOK.a2ml
|link:../playbook-a2ml/[playbook-a2ml]
|Executable plans derived from META

|AGENTIC.a2ml
|link:../agentic-a2ml/[agentic-a2ml]
|Operational gating for AI agents

|NEUROSYM.a2ml
|link:../neurosym-a2ml/[neurosym-a2ml]
|Symbolic semantics, proof obligations

|**ANCHOR.a2ml**
|anchor-a2ml (this repo)
|**Project recalibration/realignment**
|===

All formats are satellites of https://github.com/hyperpolymath/standards[hyperpolymath/standards].

== When to Use ANCHOR

Use ANCHOR.a2ml when:

* **Scope Drift** - Project has expanded beyond intended boundaries
* **Direction Change** - Strategic pivot requires explicit realignment
* **Stock-Taking** - Periodic review and verification of alignment
* **Course Correction** - AI agent has accumulated incorrect assumptions

== Quick Start

=== 1. Create the ANCHOR file

Name it `ANCHOR.a2ml` or `ANCHOR-[purpose]-[date].a2ml`.

=== 2. Define Authority

[source,toml]
----
[anchor.authority.superintendent]
name = "Project Owner"
role = "owner"

[anchor.authority.issued]
date = "2026-01-03"
----

=== 3. State Purpose

[source,toml]
----
[anchor.purpose]
type = "scope-arrest"
summary = "Halt scope expansion and stabilize"
----

=== 4. Add Directives

[source,toml]
----
[[anchor.directives.immediate]]
action = "halt-new-features"
priority = "critical"
----

=== 5. Drop into Repository

Place in root or `.machine_readable/` directory.

=== 6. Instruct AI

Tell the AI: "Go to the ANCHOR.a2ml file first."

See `examples/` for complete examples.

== Execution Pipeline Position

ANCHOR operates at the **intervention tier** - above normal execution:

[source]
----
INTERVENTION LAYER:
  ANCHOR.a2ml     <- Recalibration directives

EXECUTION PIPELINE:
  1. META validation
  2. AGENTIC gating
  3. NEUROSYM semantics
  4. PLAYBOOK derivation
  5. Execution
  6. ECOSYSTEM check
  7. STATE update
----

ANCHOR can override or reset any level of the execution pipeline.

== Specification

The complete normative specification is in link:spec/ANCHOR-FORMAT-SPEC.adoc[spec/ANCHOR-FORMAT-SPEC.adoc].

== Repository Structure

[source]
----
anchor-a2ml/
+-- spec/
|   +-- ANCHOR-FORMAT-SPEC.adoc    # Normative specification
+-- examples/
|   +-- minimal.a2ml                # Minimal valid ANCHOR file
|   +-- comprehensive.a2ml          # Full-featured example
+-- .machine_readable/
|   +-- STATE.a2ml                  # Project state
|   +-- META.a2ml                   # Architecture decisions
|   +-- ECOSYSTEM.a2ml              # Ecosystem position
+-- README.adoc                     # This file
----

== Contributing

Contributions are welcome. Please ensure:

* All changes follow the normative specification
* Examples validate against the spec
* SPDX license headers on all files

== License

PMPL-1.0-or-later with Palimpsest philosophical overlay. See LICENSE.
