Commands

Four verbs — link, why, gate, run — each built for humans and CI, not just agents. Every command takes --json and returns a documented exit code.

Every mutating command accepts --json and prints exactly one JSON object to stdout; logs go to stderr. Exit codes are consistent across the CLI:

sirius link

File a receipt by hand — useful with zero agents running. It stamps the symbols onto the issue (via amt issue comment) and the issue onto each code node (via hayven remember), so provenance exists forward and reverse.

sirius link AMT-7 --symbols auth::verify,auth::mint
sirius link AMT-7 --changed --range main..HEAD   # resolve symbols from git
sirius link --decision D-3 --symbols auth::mint
# linked issue AMT-7 → 2 symbols (forward: true, reverse: true)

sirius why

Read provenance in either direction — from a symbol back to the issues and decisions behind it, or from an issue out to the symbols it touched. Ask it a week or a year later.

sirius why auth::verify    # → the issues and decisions behind this symbol
sirius why AMT-7           # → the symbols and decisions this issue touched

sirius gate

Test-gate a completion. hayven affected-tests selects the tests for the changed files; Sirius runs them via your gate.test_cmd, and runs the full suite whenever the selection can’t be trusted. A pass advances the issue’s status; a fail files the failure as an issue comment and exits 3.

sirius gate AMT-7 --tier safe --target-status in_review
# gate safe for AMT-7: PASS [subset(3)] (3 tests) → in_review

The governing rule is “ran too much, never missed a test.” With no test_cmd configured the gate is fail-closed — it refuses to pass rather than wave a change through untested.

sirius run

The loop, across N workers. Each iteration claims an issue → maps it to symbols → locks them in Hayvenhurst → runs your agent command → gates → files the receipt → releases. Claim order is enforced (issue first, symbols second, release in reverse); a lock collision releases the issue back with a comment naming the blocker. It streams NDJSON, one object per phase:

sirius run --workers 3 --agent-cmd 'claude -p "fix the claimed issue"' --from todo
# {"worker":"sirius/oak","phase":"claim","issue":"AMT-12","claimed":true}
# {"worker":"sirius/oak","phase":"gate","result":"PASS [subset(3)]"}
# {"worker":"sirius/oak","phase":"release","status":"in_review","advanced":true}

v1 runs workers sequentially in one killable foreground process and exits when a full round finds no work. Policies — claim mode, 409 backoff, retry budget, timeouts — live in .sirius/config.json; see contracts for the full CLI surface and JSON shapes.