runbook.v1 — Governed Workflow Execution for MCP

Deterministic at the host boundary. Free reasoning between checkpoints.

runbook.v1 is an application-layer contract for MCP hosts that need governed, versioned, auditable workflows. It answers a limitation in the current MCP interaction model: an MCP server can expose a tool or workflow, but the model still decides whether to invoke it and how completely to follow it.

For enterprise workflows, execution must be required, not suggested.

The contract

A runbook is a versioned manifest resolved from a trusted skills server and executed by the host with fail-closed semantics:

{
  "runbook_id": "executive-snapshot",
  "version": "4.2.0",
  "mode": "required",
  "failure_policy": "fail_closed",
  "checkpoints": [
    {"id": "cp-revenue-qb", "kind": "tool_call", "required": true,
     "match": {"tool": "quickbooks_profit_and_loss"}},
    {"id": "cp-emit", "kind": "condition", "required": true,
     "condition": "final_output"}
  ],
  "completion": {"condition": "final_output", "receipt": true}
}

Design principles

1. Acquisition is deterministic. The host resolves the runbook by ID + version from a trusted skills server. No semantic search. Content hash, schema, and prerequisites are validated before the first model call.
2. Version pinning is absolute. The exact version is bound for the life of the run. It is never pasted into chat as untrusted prose.
3. The tool surface is an allow-list. The model can only see and call tools declared in the manifest.
4. Checkpoints are observed, not self-reported. The host derives checkpoint state from the tool-call stream. The model never claims compliance.
5. Completion is host-evaluated. The host decides whether the runbook completed and emits a machine-readable receipt.
6. Required mode is never silently downgraded. If the host cannot honor the contract, it returns runbook_failed instead of a normal answer.

Repository layout

schema/runbook.v1.schema.json   JSON Schema for the manifest
spec/runbook-v1.md              The specification
reference/python/               Reference host implementation
conformance/                    Conformance test suite (24 tests)
examples/                       Example manifests

Conformance

The reference implementation passes its own conformance suite:

python3 conformance/run_conformance.py
PASS: 24  FAIL: 0

The suite covers: schema validation, content hashing, tamper detection, prerequisite fail-closed, checkpoint observation, checkpoint timeout, allow-list enforcement, receipt emission, and missing-runbook behavior.

Why this exists

MCP won because it made agents practical. This makes them trustworthy. In enterprise procurement, those are the same word.

License

MIT