# Run record `runbook-run/v0.1` One run of one native pack, stored as JSON in `/.local/runbook-runs/.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..state` | `todo`, `running`, `done`, `failed`, `skipped` | | `steps..verification` | `kind`, `passed`, and for commands `exit_code`, `output_bytes`, `seconds`. Output text is never stored | | `steps..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 ...` ## 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 `; 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 by ` 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 ` 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.