# Show HN: Runbook.v1 – governed workflow execution for MCP (fail-closed)

> Source: <https://github.com/CorpusIQ/runbook-spec>
> Published: 2026-08-18 20:34:11+00:00

**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.

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}
}
```

**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.**Version pinning is absolute.** The exact version is bound for the life of the run. It is never pasted into chat as untrusted prose.**The tool surface is an allow-list.** The model can only see and call tools declared in the manifest.**Checkpoints are observed, not self-reported.** The host derives checkpoint state from the tool-call stream. The model never claims compliance.**Completion is host-evaluated.** The host decides whether the runbook completed and emits a machine-readable receipt.**Required mode is never silently downgraded.** If the host cannot honor the contract, it returns`runbook_failed`

instead of a normal answer.

```
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
```

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.

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

MIT