Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# procedure-run Card

# Handling Procedure Runs

This card is managed by the procedure engine. Agents should read it to understand execution progress but should NOT modify it directly — with one exception: the `expires` field.

Check the root `status` field for overall progress: pending → running → completed/failed/inconclusive. Each entry in `steps` also has its own status.

`inconclusive` means every step's work completed but at least one `validate` check never reached a verdict (its review ran out of turns, timed out, or returned nothing parseable). The work is unjudged, not wrong — do not redo it on that basis; read the step's `validate.error` for the reason.

Step statuses: pending → running → completed/skipped/failed. Look at a step's `precheck.status` to see why it was skipped, `run.error` for run-agent or shell failures, and `validate.error` / `validate.status` for validation failures (`validate.status: inconclusive` is a non-verdict, not a failure).

The `expires` field (stamped by the engine at completion) is when `bbx procedure gc` may delete this run's directory. Run dirs are a recent cache — git history is the archive. To retain a specific run, set `expires: never` or push the date out.

The `procedure` field names the procedure definition this run belongs to. The run card lives in `_bookkeeping/procedure/runs/<name>_<timestamp>/`.