// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
= PLAYBOOK.a2ml

image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"]
image:https://img.shields.io/badge/A2ML_Family-execution-green.svg[A2ML Family]
:toc: left
:toclevels: 2
:icons: font

Machine-readable executable plans and operational runbooks.

Part of the **A2ML Format Family** -- A2ML (Annotated Markup Language) TOML-like key-value
data formats for software engineering workflows.

== The A2ML Format Family

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

|**META.a2ml**
|Architecture decisions, governance
|hyperpolymath/meta-a2ml
|Primary

|**STATE.a2ml**
|Project state, milestones
|(companion to META)
|Primary

|**ECOSYSTEM.a2ml**
|Ecosystem positioning
|(companion to META)
|Primary

|**PLAYBOOK.a2ml**
|Executable plans, runbooks
|hyperpolymath/playbook-a2ml
|Execution

|**AGENTIC.a2ml**
|AI agent gating, safety
|hyperpolymath/agentic-a2ml
|Execution

|**NEUROSYM.a2ml**
|Symbolic semantics
|hyperpolymath/neurosym-a2ml
|Execution

|**ANCHOR.a2ml**
|Project recalibration
|hyperpolymath/anchor-a2ml
|Intervention
|===

== What is PLAYBOOK.a2ml?

PLAYBOOK.a2ml defines *how* permitted actions are executed, not *whether* they
are permitted (that's META) or *whether* they may proceed now (that's AGENTIC).

PLAYBOOKs are **derived** from:

* META rules (architectural decisions)
* STATE context (current project phase)
* Validated user intent (explicit present request)

[source,toml]
----
# SPDX-License-Identifier: MPL-2.0

[playbook.derivation-source]
type = "derived"
meta-rules = ["adr-001", "adr-015"]
state-context = "beta-phase"
timestamp = "2026-01-03T12:00:00Z"

[playbook.procedures.build]
description = "Build the project"
on-failure = "abort-and-notify"

[[playbook.procedures.build.steps]]
step = 1
action = "deno task build"
timeout = 300

[[playbook.procedures.build.steps]]
step = 2
action = "deno task test"
timeout = 600

[playbook.procedures.deploy]
description = "Deploy to production"
requires-confirmation = true
on-failure = "rollback-and-alert"

[[playbook.procedures.deploy.steps]]
step = 1
action = "backup-current"

[[playbook.procedures.deploy.steps]]
step = 2
action = "push-to-prod"

[[playbook.procedures.deploy.steps]]
step = 3
action = "verify-deployment"
----

== Why PLAYBOOK.a2ml?

[cols="1,3"]
|===
|Feature |Benefit

|*Derived Authority*
|Plans inherit authority from META, cannot introduce new permissions

|*Gated Execution*
|All execution is subject to AGENTIC safety controls

|*Auditable*
|All executions and failures are recorded in journals

|*Machine-Readable*
|Tooling can parse, validate, and execute plans

|*Rollback-Aware*
|Failure handling and rollback strategies built-in

|*Cross-Format*
|Integrates with META, STATE, AGENTIC, NEUROSYM
|===

== Execution Pipeline

PLAYBOOKs execute within a defined order:

[source]
----
1. META validation      -> Constitutional authority check
2. AGENTIC gating       -> Operational safety check
3. NEUROSYM semantics   -> Proof obligations discharge
4. PLAYBOOK derivation  -> Build executable plan
5. Execution            -> Run the plan
6. ECOSYSTEM check      -> Integrity verification
7. STATE update         -> Record success/failure
----

== Core Sections

=== Derivation Source (`derivation-source`)

Declares where the PLAYBOOK's authority comes from:

* `type` - "derived" (default) or "non-derived" (if META permits)
* `meta-rules` - Which ADRs authorize this PLAYBOOK
* `state-context` - Current project phase
* `agentic-gate` - AGENTIC status at derivation time

=== Procedures (`procedures`)

Executable plans with:

* `description` - Human-readable purpose
* `preconditions` - Required state before execution
* `steps` - Ordered actions with timeouts
* `postconditions` - Expected state after success
* `on-failure` - Failure handling strategy

=== Alerts (`alerts`)

Notification configuration:

* Severity levels (info, medium, high, critical)
* Channels (slack, pager, email)
* Escalation delays

=== Contacts (`contacts`)

On-call and escalation contacts.

== Getting Started

=== Create a PLAYBOOK.a2ml File

[source,toml]
----
# SPDX-License-Identifier: MPL-2.0
# SPDX-FileCopyrightText: 2026 Your Name
# PLAYBOOK.a2ml -- Operational Runbook

[playbook.derivation-source]
type = "derived"
meta-rules = ["adr-001"]
timestamp = "2026-01-03T00:00:00Z"

[playbook.procedures.build]
description = "Build the project"
on-failure = "abort"

[[playbook.procedures.build.steps]]
step = 1
action = "deno task build"
----

== Specification

The formal specification is in the `spec/` directory:

* link:spec/PLAYBOOK-FORMAT-SPEC.adoc[PLAYBOOK-FORMAT-SPEC.adoc] - Complete specification

== Examples

See the link:examples/[examples/] directory:

* link:examples/minimal.a2ml[minimal.a2ml] - Minimal valid PLAYBOOK
* link:examples/comprehensive.a2ml[comprehensive.a2ml] - Full-featured example

== Conformance Requirements

A PLAYBOOK is conformant if:

1. It is derived from META (or explicitly permitted as non-derived)
2. It does not bypass META or AGENTIC
3. Execution ordering is preserved
4. Failures are properly recorded

== Media Type

* **MIME Type**: `application/vnd.playbook+a2ml`
* **File Extension**: `.a2ml` (conventionally `PLAYBOOK.a2ml`)
* **Encoding**: UTF-8

== Failure Modes

If PLAYBOOK execution fails:

* The system MUST rollback or branch
* STATE MUST NOT be committed
* The failure MUST be recorded in the journal
* Alerts MUST be triggered

== Related Specifications

* link:../meta-a2ml/[META.a2ml] - Architecture decisions
* link:../agentic-a2ml/[AGENTIC.a2ml] - Operational gating
* link:../neurosym-a2ml/[NEUROSYM.a2ml] - Symbolic semantics

== License

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

