Worked examples

A gate decision, and what the surface refuses

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

Both --gate and --decision are required with no defaults. A stop1 gate is an owner act: it asks for the one-time code on your terminal before anything is written. 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 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:docs/plan.md \
  --return RETURN_notes.md=consumed
saphan teardown mcp-projection-budget --verify-archive

Refused until the projection shows merged and the worktree is clean; every return artifact's fate is recorded (landed:<path> is hash-checked against the worktree's copy; a bare landed is recorded as an unverified claim). The second line re-verifies the archive and removes the worktree. 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, the stream's total
saphan ledger show                    # session and workspace totals
saphan board export --format html --out fleet-report.html