Working with git
One stream's journey: the worktree it is given, delivery to a remote machine, the return, verification, and the merge a human makes.
One stream's journey, from the working tree it is given to the merge commit a human makes
For the operator who runs streams and the owner who decides them.
After reading it you can deliver a base and a branch to a machine, bring work home, verify it, record a gate decision, merge, and tear the stream down.
Before you start: an installed fleet with at least one admitted machine, and human gates read once.
Read this once, in order. It is a path a reader walks, not a verb catalogue: five acts, each
with the verb that performs it and the refusal it gives when a precondition is missing. Every
verb here takes --workspace <absolute path to your workspace root>; that argument is omitted
from the examples below only to keep the lines short.
The whole path, in one place
| the act | the verb | rehearsal |
|---|---|---|
| deliver the base to a machine | saphan machine refresh-repo <machine> --repo <repository> | saphan dry-run … |
| deliver a branch to a machine | saphan machine deliver-branch <machine> --repo <repository> --branch <branch> | saphan dry-run … |
| bring status, branch and review artifacts home | saphan return <stream> | — |
| verify a stream's tree | saphan verify-stream <stream> | — |
| measure the branch merged onto its trunk (advisory) | saphan verify-union <stream> | — |
| record a gate decision | saphan gate <stream> --gate <gate> --decision <decision> --actor <name> | — |
| ask what is legal now | saphan fleet next --stream <stream> | — |
| merge | saphan merge <stream> --actor <name> | saphan dry-run merge … |
| observe the merge into the record | saphan fleet observe <stream> | — |
| archive the channel and record the teardown gate | saphan teardown <stream> | — |
The rest of this section
| Page | What it answers |
|---|---|
| Pull requests and forge integrations | What the product does and does not do against your forge, and what a forge-side merge is designed to require. |
| The channel documents | The documents an agent reads and writes at the root of a worktree: what each is, who writes it, and what happens when a key is missing. |
What this section does not cover
⚠ It does not teach git. Branches, worktrees and merge commits are assumed. ⚠ Writing to a forge is not something the product does — what it can and cannot do against yours is on Pull requests and forge integrations, including the parts that do not exist.