# Playbooks

A playbook is a procedure written as **typed data**: the steps an on-call person would take, with the
edges between them, in a form an agent can propose, a person can read in full, and nothing can run until
a person has published its exact digest. There is no code in a playbook, no loop and no nested playbook,
so what a run can do is computable from its definition alone.

This page covers the definitions: the grammar, the digest, the proposal and publish path, and the reads.
Running a published playbook, its triggers and its budgets are a separate feature (MON-22).

## Who may do what

| Act | Who | How |
| --- | --- | --- |
| Propose a draft (`playbook.propose`) | An agent or a person with `configure_playbooks` | `playbooks_propose`, or `POST /orgs/:o/playbooks`. **Always asked, for the first draft and every further one.** |
| Retract the newest draft or restore (`playbook.update`), archive (`playbook.archive`) | Same | `POST /orgs/:o/playbooks/:slug/change`; an agent's own drafts through `operation_revert` |
| **Publish** a version (`playbook.publish`) | A person only: an organization owner, behind a password step-up | `POST /orgs/:o/playbooks/:slug/publish`, naming the version **and its digest** |
| Delete (`playbook.delete`) | A person only | No door yet |
| Read | Any member with org `read` | `playbooks_list`, `playbook_get`, `actions_catalog_list`, the REST reads |

A draft does nothing. It is an immutable row that no run can reach until a person publishes it. The
agent proposes, a person decides the proposal, and a person publishes: three separate acts by separate
people, which is the difference from a system where one permission creates, publishes and runs.

## The grammar

A definition has `steps` (1 to 40), optional typed `inputs` (at most 10), `limits`, an optional
`runbook`, and `essential` (false: paused while an error budget burns). Every step has an `id` and
names where it goes next. **Edges only point forward**, to a later step or to `end`, so a loop cannot be
written, and every step must be reachable from the first.

| Kind | What it does |
| --- | --- |
| `query` | Runs a **stored** query spec by its digest. The spec is never embedded, and its result is data, never a command. |
| `governed_action` | One act of one operation family: `{ family, verb, input }`. |
| `approval` | Asks people: a relation, a quorum of 1 or 2, an expiry of 5 minutes to 24 hours. **`onApproved`, `onRejected` and `onExpired` are all required**: a decision nobody makes still leads somewhere. |
| `wait` | Pauses for 1 to 240 minutes. The waits together must fit the run timeout (at most 240 minutes). |
| `branch` | Follows one of two edges on a typed comparison (`eq`, `neq`, `gt`, `lt`, `in`) of an earlier step's result. |
| `notify` | Tells the inbox or one Slack route, with **counts only**: there is no message field. |
| `customer_action` | A step in a customer's own system (MON-35). **Refused until that package registers it.** |
| `http_template` | One call from a **published action template** (DEL-22), named by `{ template, digest, input }`: the slug and the digest of the version a person published. The template (method, https URL, header names, a flat parameter schema) is not in the definition and cannot be changed by it. See "Action templates" below. |

A parameter is a typed literal (at most 200 characters, no control characters) or a whole-string
binding: `{{inputs.name}}` or `{{steps.<id>.<field>}}`. Any other `{{` is refused: there are no
expressions, no functions and no interpolation. A `query` result may be compared in a `branch` and is
**never bound into an action's input**, because it is data from telemetry.

### What a governed_action may name

`actions_catalog_list` shows every act with its class, ask floor, conditional floors, inverse, TTL and
verification signal as fields, so a client sees before a person approves which steps will stop for one.
The same function decides what the grammar accepts. A step is **refused at propose** when it names:

- a family or verb that is not in the action registry;
- a **human-only act**: any publish, delete, ship, merge, enable of a human-only switch, approval-policy
  change, or anything else the registry marks `humanOnly`. No playbook can carry an act a human must
  perform;
- a **dual-control** act, or an act whose class is **CRITICAL** (the infrastructure levers: rollback,
  scale, restart);
- a verb or object the earned-autonomy ladder forbids (`widen`, `launch`, `ship`, `resume`, `publish`,
  `certify`, `verify`, `delete`, `merge`, `erase`; a host or a credential);
- an act that is not an approvals or direct write;
- an act of the `playbook`, `playbook_run`, `action_template` or `org_skill` families: a playbook never
  writes, publishes or runs a playbook, which keeps "no nested playbooks" true by construction.

A **mitigation lever** (`mitigation.*`) keeps its own class: the step always asks a person when a run
reaches it. A draft that carries one is asked for like every other draft.

The grammar is part of the **input schema**, so a definition that breaks it is refused where it is
parsed, before a plan, an operation row, an approval request or an audit row exists. It is judged again
when the draft is stored and again at publish, so a family the registry has since made human-only stops
a version that was valid when it was proposed.

## The digest

A version's digest is the SHA-256 of its parsed definition in canonical JSON (steps, edges, inputs,
limits and runbook, with the grammar's defaults filled in) under a domain separator. Key order is not
part of a definition. A caller cannot state a digest: the plan computes it, the approver is shown the one
the apply writes, and the apply refuses a version that no longer hashes to the digest its plan carried.

**A published version is immutable by digest.** Publishing names the version and the digest the person
read. A different stored digest is a 409, a stored definition that no longer hashes to its digest is a
409 (`digest_tampered`), and a definition the grammar would now refuse is a 422. A published version can
never be retracted; a later publish of an older version is the rollback, and the audit row names the
previous digest.

## From proposal to publication

1. An agent calls `playbooks_propose` with a slug, a title and a definition. The first call is an
   **ask** (`input_required`) with the approval card. `playbook.propose` carries the registry's ask
   floor: no policy row, earned rung or review mode makes it apply by itself.
2. A person with `configure_playbooks` decides it. The yes is bound to the plan digest.
3. The agent retries with the same answer. One apply stores an **inert, unpublished** version against
   the revision it was asked on; if the playbook moved in between (a person renamed it, published a
   version), the answer is `TARGET_CHANGED` and nothing is stored. A replayed answer buys nothing.
4. A person reads the playbook (`playbook_get`, or the dashboard) and publishes the digest they read.

A further draft of an existing playbook is `playbook.propose` too, under the same floor: every
definition stored as a version was read by a person first. Retracting the newest unpublished draft and
restoring an archived playbook are `playbook.update` (asked by default). Archiving a draft is allowed;
archiving a published playbook is asked.

## Action templates (DEL-22)

An `http_template` step calls one **action template**: an outbound HTTP call a platform team defined, which Bucker sends and never runs as code. A template is data: a method, an https URL template with the host written out (placeholders only in the path or query), the **names** of the headers it sends, and a flat parameter schema in which no free string is longer than 200 characters. **Header values are never stored in a template**: they come from a sealed connection credential at call time, and a call whose template names headers with no credential to supply them fails closed.

- The host must already be an active `http` entry on the organization's egress allow-list (`egress.host.add` is human-only). An empty list does not mean "anything goes" for a template.
- `action_template.create` stores a draft (SENSITIVE, asked). A person publishes its digest (`action_template.publish`, human-only, `org:admin`, password step-up). A published template is immutable: archive it (`action_template.archive`) and create a new slug.
- The stored class is the declared one (`reversible`, `disruptive`, `irreversible`) raised by the method (anything but GET is at least `disruptive`) and by the host (an explicit port or an IP literal is one step up). A run that names a template starts at the highest class among its templates.
- A step pins the template's slug **and digest**; a template replaced afterwards stops serving the playbook until the new digest is read and the playbook published again. Publishing a playbook refuses a step whose template is missing, unpublished, at another digest or off the allow-list.
- The answer is untrusted text: the step stores the status, the size and a 300-character excerpt (control characters removed, credential-shaped spans masked, withheld whole if it echoes a header value) labelled `untrusted`; no reader of a run is handed the excerpt, and a `branch` after the step may read only `status`, `http_status`, `ok`, `bytes` and `truncated`. A non-2xx answer fails the step and the run; nothing retries.
- No infrastructure template (restart, scale, roll back) exists until OD-DP-01, and there is no private action runner (OD-DP-09).

## Running a playbook

A run starts from a published playbook by its digest: the digest you read (`playbook_get`) is the one the
run is bound to, so a revision published afterwards does not change what runs. `playbooks_preview` shows
the run without writing anything: for each governed step the family, the act, the class the registry
gives it and the class this plan derives, whether it will stop for a person, and the blast radius. It is
a separate read, never a flag on the run.

- **Starting asks by default.** `playbook.run` asks a person, and always asks when the playbook carries a
  mitigation lever. The first call answers with the approval card; the retry that names their yes starts
  one run.
- **Each step is decided on its own**, by the same engine and for the run's principal, with its own
  freezes, switches, floors and approvals. A step that asks waits for a person. A freeze or a switch that
  binds a person's run binds this one.
- **A refusal ends the run, and nothing retries by itself.** A human-only act is refused at run time, and
  merging is never a step.
- **A run can be cancelled** (`playbook_run.cancel`), and paused and resumed. Cancelling stops what is left;
  it does not undo steps already taken, whose inverses are the ordinary operations.

## Reads and what is untrusted

The reads share one visibility rule: a member with org `read`; a project-scoped playbook only for a
caller who can reach its project; an empty proposal never; another organization's playbook never. A
missing playbook, another organization's and an unreachable one are the same "not found".

A playbook's **title**, the **runbook** an author attached (text and owner team), every **literal
step value** and every string a **branch** compares against are written by members or agents. The tools strip control characters, cut before scanning,
mask credentials, scan and cap them under the register's classes (`plan_echo`, `comment_body`,
`tag_key`) and declare every path untrusted; the dashboard renders them as text, never as markup and
never as a link. A runbook is stored with an owner, a review date and an expiry.

## Limits

| | |
| --- | --- |
| Steps per version | 40 |
| Versions per playbook | 50 |
| Playbooks per organization | 200 (and 25 waiting for their first draft) |
| Literal parameter | 200 characters, 16 keys per step |
| Runbook text | 2,000 characters |
| Run timeout | 240 minutes; one wait 240 minutes; one approval 24 hours |
