Worked examples

A gate decision, and what the surface refuses

saphan gate mcp-projection-budget --gate stop1 --decision accept \
  --actor marcin --note "plan approved; Q1 resolved as contract bump"

Both --gate and --decision are required with no defaults. The engine refuses, with nothing written:

• a decision by a non-human actor,
• vocabulary outside the closed sets above,
• a merged decision (merged is observed, never declared),
• a gate out of order — refused with the list of what the stream still owes.

Asking the fleet what is next

saphan fleet next --stream mcp-projection-budget

One read returns the stream's resolved state, every gate still owed, the legal next acts — and a ready-to-paste command per act, so "what now" never requires reconstructing the protocol from memory.

The merge that checks before it moves

saphan merge mcp-projection-budget

Ordinary preconditions are checked first: the required gates recorded, the review lane (when engaged) holding a recorded accept or accept-with-conditions, the branch state sane. Then the engine conflict-probes the current pair in a detached worktree, with no suite. A violated precondition or conflict refuses by name (class merge-preconditions) and lands nothing; a clean probe lands before the serialized act releases its lock.

Closing a stream honestly

saphan teardown mcp-projection-budget \
  --return RETURN_plan.md=landed \
  --return RETURN_notes.md=consumed

Refused until the projection shows merged and the worktree is clean; every return artifact's fate is recorded. For work that ends without landing:

saphan gate <stream> --gate stop2 --decision closed-without-merge \
  --note "superseded by <other-stream>"

The stream ends, and the record says why.

Reading the books

saphan cost mcp-projection-budget     # per-run actual vs quoted, drift, stream totals
saphan ledger show                    # session and workspace totals
saphan board export --format html --out fleet-report.html