Runbooks

Runbooks turn a known operating scenario into a reviewable sequence of observations, decisions and typed actions. They should be executable by the same API and worker gates as a manual operation, not by a scheduler with special authority.

Proposed operating flow

author runbook -> validate steps and targets -> dry-run
       |                                      |
       |                                      +--> evidence, impact, policy reasons
       v
schedule window -> approval for exact revision -> enqueue worker
       |                                      |
       +--> pause / cancel ------------------+--> verify + audit

Schedule

A schedule should identify the organization, immutable runbook revision, target scope, timezone, allowed window and next run. At trigger time the server re-resolves membership, entitlements, policy, target identity and evidence. A schedule must not carry a bearer credential or bypass an approval that has expired.

Dry-run

Dry-run is a bounded preview. It may collect read-only state, render the typed operations, estimate cost or blast radius and report policy decisions. It must not call executeAction, apply OpenTofu, send a deployment command or change desired state. An incomplete or stale preview is a limitation, not a successful run.

Approval

Approval binds to the exact runbook revision, target snapshot, plan digest and expiry. Risk 0 reads can proceed automatically; risk 1 requires confirmation; risk 2 requires explicit approval; risk 3 additionally requires an elevated role, typed target confirmation, a second confirmation, a written reason and fresh revalidation.

The current product exposes the plan_runbook AI tool, which produces an operational runbook for a scenario. A persisted runbook scheduler and dedicated runbook API are not yet wired into the current route set. Treat scheduling and dry-run above as the operating contract for that future surface, not as a claim that a cron job currently executes runbooks.