2026-09-29 00:43:38 +02:00
|
|
|
# Run record `runbook-run/v0.1`
|
|
|
|
|
|
|
|
|
|
One run of one native pack, stored as JSON in
|
|
|
|
|
`<owning repo>/.local/runbook-runs/<run_id>.json` (git-ignored). Non-secret only.
|
|
|
|
|
|
|
|
|
|
| Field | Meaning |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| `run_id` | Timestamp plus random suffix |
|
|
|
|
|
| `pack_id`, `pack_path` | The pack run |
|
|
|
|
|
| `operator` | One word: the person who ran it |
|
|
|
|
|
| `params` | Resolved parameter values (validated, never secret) |
|
|
|
|
|
| `steps.<id>.state` | `todo`, `running`, `done`, `failed`, `skipped` |
|
|
|
|
|
| `steps.<id>.verification` | `kind`, `passed`, and for commands `exit_code`, `output_bytes`, `seconds`. Output text is never stored |
|
|
|
|
|
| `steps.<id>.evidence` | The facts the step declared, supplied by the operator |
|
|
|
|
|
|
|
|
|
|
## Rules
|
|
|
|
|
|
|
|
|
|
- Steps run in order; a step starts only after its predecessors are done or skipped.
|
|
|
|
|
- A step completes only with a passing verification and its declared evidence.
|
|
|
|
|
- A verify command runs only when the operator confirms (`--yes`), with a 60 s timeout.
|
|
|
|
|
- Only read-only steps may be skipped, and a run with skips never exercises a pack.
|
|
|
|
|
- Values matching the secret markers are refused everywhere they could be recorded.
|
|
|
|
|
- The engine never edits `pack.yaml`. `rtut run finish` shows the exercise-status
|
|
|
|
|
diff; `--apply` writes it, and only for a run in which every step is done.
|
|
|
|
|
|
|
|
|
|
CLI: `rtut run new|list|status|cmd|start|verify|done|fail|retry|skip|finish <pack.yaml> ...`
|
2026-09-29 11:15:58 +02:00
|
|
|
|
|
|
|
|
## Outcome, score and exercise status
|
|
|
|
|
|
|
|
|
|
A run is **open** until finalized. `rtut run finalize` (or the UI's *Close this run*) records
|
|
|
|
|
an `outcome`:
|
|
|
|
|
|
|
|
|
|
| Outcome | Rule |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| `succeeded` | every step is `done` (skipped steps do not count) |
|
|
|
|
|
| `failed` | at least one step has failed; otherwise abandon |
|
|
|
|
|
| `abandoned` | any time. An open run untouched for 7 days also counts as abandoned in the score |
|
|
|
|
|
|
|
|
|
|
A finished run is read-only, except for feedback. The **score** of a runbook is derived from
|
|
|
|
|
its run records: tried, succeeded, failed, abandoned, open, plus a tally of feedback ratings
|
|
|
|
|
(`rtut score <root>`; shown in the UI). Run records live in `.local/` of the machine that ran
|
|
|
|
|
them, so the score is per machine until run histories are shared.
|
|
|
|
|
|
|
|
|
|
Finalizing never edits the pack by itself. For a `succeeded` run the UI offers **Record pack
|
|
|
|
|
as exercised**, which shows what will be written, and on click sets
|
|
|
|
|
`exercise_status: exercised <date> by <operator>` in `pack.yaml` (`rtut run finalize ... --outcome
|
|
|
|
|
succeeded --apply` does the same). The change is an ordinary edit in the owning repository, to
|
|
|
|
|
be reviewed and committed there.
|
|
|
|
|
|
|
|
|
|
## Feedback
|
|
|
|
|
|
|
|
|
|
`feedback` entries (`rating` good|neutral|poor, `comment`, `at`) are added after a run; history
|
|
|
|
|
is kept and the latest counts. `rtut feedback <pack.yaml>` lists them.
|
|
|
|
|
|
|
|
|
|
## Captures
|
|
|
|
|
|
|
|
|
|
A step may carry optional `captures`: the command actually run, and the output that came
|
|
|
|
|
back, as documentation or for inspection when the engine cannot reach the system itself. Limits:
|
|
|
|
|
20 000 characters of output, 2 000 of command. Obvious secret markers are refused; the engine cannot
|
|
|
|
|
detect every secret, so the operator stays responsible. For `output-contains` steps the output can
|
|
|
|
|
be **pasted for verification** (`source: pasted-for-verification`), which checks the `contains` text
|
|
|
|
|
without running anything. Exit-code checks cannot be verified from pasted output.
|
