Rulings - PairCoder Docs

A ruling is a durable request for a human decision. When a task needs sign-off that an agent should not guess at, bpsai-pair ruling records the question, parks the task on it, and lets a driver resume once someone has decided.

Commands

Command	Description
`ruling ask`	Ask for a ruling and park a task on it
`ruling list`	List rulings, newest first
`ruling show <ruling_id>`	Print the full ruling record
`ruling rule <ruling_id>`	Record the verdict and apply it to the parked task
`ruling wait <ruling_id>`	Wait, with a time limit, for the ruling to be made

Asking for a ruling

bash

bpsai-pair ruling ask --task TASK-12 \
          --question "Ship the new export format in this release?" \
          --option ship="Ship it:Existing users must re-export" \
          --option defer="Defer to the next release" \
          --recommend defer

The task is marked as awaiting a ruling. A task waiting on a ruling does not count as a failure toward the engage circuit breaker.

Options

Flag	Required	Description
`--task`	Yes	Id of the task this ruling parks
`--question`	Yes	A one-sentence sign-off question
`--option`	No	`key=label[:consequence]`. Repeat for each choice
`--recommend`	No	Key of the option to mark as recommended
`--evidence`	No	`type:ref`. Repeat for each item
`--context`	No	Supporting detail. Keep the question itself to one sentence
`--park`	No	`task` (default) or `run`. With `run`, the run is parked and the task stays pending without the awaiting-ruling marker
`--allow-write-in` / `--no-allow-write-in`	No	Whether a verdict other than a listed option is accepted (default: allowed)
`--owner`	No	Who can rule on this. Repeat for each owner

In the default task-parking mode, only one open ruling is allowed per task.

Finding and reading rulings

bash

bpsai-pair ruling list --open
        bpsai-pair ruling show <ruling_id>

Flag	Description
`--open`	Only open rulings
`--repo`	Filter by repository slug, or `all`

Making the ruling

bash

bpsai-pair ruling rule <ruling_id> --verdict defer --by your-name \
          --note "Revisit after the migration guide ships"

Flag	Required	Description
`--verdict`	Yes	An option key, or a write-in
`--by`	Yes	Who made the ruling
`--note`	No	A note recorded with the verdict

Ruling applies the verdict to the parked task and clears its awaiting-ruling marker. A ruling that has been made cannot be edited. If someone changes their mind, ask a new ruling.

Waiting for a ruling

A driver that is resuming can wait for the decision. The wait is always bounded: it exits 0 once the ruling is made and non-zero on timeout.

bash

bpsai-pair ruling wait <ruling_id> --timeout 600

Flag	Description
`--timeout`	Time limit in seconds (default: 300)
`--interval`	Seconds between checks (default: 2)

Ruling records, task files and task state are written atomically.