runbook-tutorials/docs/run-spec.md

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

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.