tegwick
1398b8f95a
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: sonnet Assistant-Process: 295952@bnt-lap001 Assistant-Session: e93f64ad-516c-46eb-9666-aad8d300c477
81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
# Runbook pack specification v0.1
|
|
|
|
Status: supported, no longer extended. New packs use v0.2 (`docs/pack-spec-v0.2.md`); v0.1 packs keep running unchanged.
|
|
|
|
A **runbook pack** is a directory `runbooks/<pack-dir>/` in the repository that
|
|
owns the procedure. It contains `pack.yaml`, validated by
|
|
`rtut/schema/runbook-pack.schema.json`, plus optional supporting files. The engine
|
|
discovers packs by scanning `runbooks/*/pack.yaml` under a repository root, or
|
|
under any root given on the command line.
|
|
|
|
## Manifest
|
|
|
|
| Field | Required | Meaning |
|
|
| --- | --- | --- |
|
|
| `spec` | yes | Literal `runbook-pack/v0.1` |
|
|
| `id` | yes | Stable dotted id, lower-case, e.g. `nk.ssh-certificates` |
|
|
| `title`, `outcome` | title yes | What the operator is doing; what is true afterwards |
|
|
| `owner` | yes | The repository that owns the procedure |
|
|
| `exercise_status` | no | **Deprecated and ignored.** Maturity is derived from run history; old packs that carry it still load |
|
|
| `engine` | yes | `native` or `legacy-command` |
|
|
| `parameters` | no | Operator-supplied, non-secret values |
|
|
| `prerequisites` | no | `{text, owner}` list |
|
|
| `steps` | native | Ordered steps (below) |
|
|
| `threat_checks` | native | What must never be logged, committed or pasted |
|
|
| `ownership` | no | Concern-to-owner table |
|
|
| `legacy` | legacy | How to launch the existing console |
|
|
|
|
## Parameters
|
|
|
|
Each parameter has `id` (`[a-z][a-z0-9_]*`), `label`, `type`
|
|
(`string|text|enum|path|bool|int`), optional `values`, `default`, `pattern`, `help`.
|
|
`text` is single-line free text for use inside double quotes: spaces are allowed and
|
|
shell metacharacters (`; & | ` $ < > \ ' "`) are not. Every other type also rejects spaces.
|
|
|
|
**`secret` may only be `false`**: a parameter is never a secret. Steps refer to
|
|
parameters as `{{id}}`. An undefined placeholder, an unused parameter, an
|
|
`enum` without `values`, or a default that violates its `pattern`/`values` is a
|
|
validation error.
|
|
|
|
## Steps
|
|
|
|
Every step has `id`, `title`, `owner` (the repo or tool that does the work),
|
|
and `verify`. Optional: `description`, `command` (a template shown to the
|
|
operator, copyable, never run by the engine unless a future execution mode is
|
|
enabled for that step), `risk` (`read-only|changes-state|attended|destructive`),
|
|
`rollback`, `evidence`.
|
|
|
|
`verify` is mandatory, so a runbook cannot be prose only:
|
|
|
|
- `done_when`: the observable outcome, in words;
|
|
- `command` and `expect` (`manual|exit-0|output-contains`, with `contains`).
|
|
|
|
A step with `risk` of `changes-state`, `attended` or `destructive` must state a
|
|
`rollback` (which may say "not reversible" and why).
|
|
|
|
Commands are relative to the root of the repository that owns the pack. Verify
|
|
commands run there, so a pack can call `make` targets and repo-relative scripts.
|
|
|
|
## Maturity, not a status field
|
|
|
|
How far a pack can be trusted is earned, not declared: `draft`, `reviewed`, `rehearsed`, `proven`, or `stale`, derived from the
|
|
runs of the pack at its current revision (`docs/maturity-and-projects.md`). The earlier `exercise_status` field is retired.
|
|
|
|
## Secrets
|
|
|
|
The engine must not collect, store, log or transmit secret values. The
|
|
validator rejects manifests containing secret-looking markers (`hvs.…`,
|
|
private-key blocks, `otpauth://`).
|
|
|
|
## Legacy packs
|
|
|
|
`engine: legacy-command` wraps an existing guided console unchanged. `legacy.command`
|
|
is the argv to launch, `legacy.cwd` is relative to the pack root's repository,
|
|
`legacy.url` is where the console serves. The engine lists, describes and
|
|
launches it; it does not interpret its internals. Migration to `native` is
|
|
optional and per pack.
|
|
|
|
## Versioning
|
|
|
|
`spec` names the version. A change that invalidates existing packs raises the
|
|
version; the engine keeps loading older versions it declares support for.
|