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
= AGENTIC.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

AGENTIC.a2ml defines **operational gating policies** for AI agent actions. It controls
*whether* a permitted action may proceed *now*, separate from constitutional permission
(META) or semantic meaning (NEUROSYM).

AGENTIC implements safety controls including:

* **Entropy Budgets** - Track accumulated operational risk
* **Risk Thresholds** - Classify operations by risk level
* **Confirmation Requirements** - Explicit user intent for high-risk operations
* **Decision Recording** - Auditable trail of all gating decisions

== 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**
|agentic-a2ml (this repo)
|**Operational gating for AI agents**

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

|ANCHOR.a2ml
|link:../anchor-a2ml/[anchor-a2ml]
|Project recalibration/realignment
|===

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

== Execution Pipeline Position

AGENTIC operates at step 2 in the execution pipeline:

[source]
----
1. META validation      <- Constitutional authority check
2. AGENTIC gating       <- THIS SPECIFICATION
3. NEUROSYM semantics   <- Proof obligations
4. PLAYBOOK derivation  <- Build executable plan
5. Execution
6. ECOSYSTEM check
7. STATE update
----

== Key Concepts

=== Explicit Present Intent

User memories, project memories, or inferred goals MUST NOT be treated as
equivalent to **explicit present user intent**. AGENTIC distinguishes between:

* **Explicit Intent** - Direct, unambiguous request in current interaction
* **Inferred Intent** - Derived from context, patterns, or history
* **No Intent** - No user indication

=== Entropy Budgets

Entropy budgets track accumulated operational risk within a session or timeframe:

[source,toml]
----
[agentic.entropy-budgets.session]
max-entropy = 100
current = 0
reset-on = "session-end"

[agentic.entropy-budgets.operation-costs]
file-read = 1
file-write = 5
file-delete = 20
external-api = 10
irreversible-action = 50
----

=== Override Requirements

If AGENTIC blocks an action, it MAY be overridden ONLY if:

1. META defines the override class
2. The user provides explicit present intent
3. The action is retyped appropriately if proof obligations are not discharged

All overrides MUST be recorded as decision records.

== Quick Start

=== Minimal AGENTIC.a2ml

[source,toml]
----
[agentic]
project = "my-project"

[agentic.gating-policies.default]
mode = "strict"
require-explicit-intent = true
----

See `examples/` for more complete examples.

== Specification

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

== Repository Structure

[source]
----
agentic-a2ml/
+-- spec/
|   +-- AGENTIC-FORMAT-SPEC.adoc    # Normative specification
+-- examples/
|   +-- minimal.a2ml                 # Minimal valid AGENTIC 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. See LICENSE.
