a625dbe055
Rewrite SKILL.md to state the stance (reconnoitre, then route all work through Pipelines runs; manage and debug, never implement), keep the existing authoring/operations index, and route to four new references. Add references/orchestration.md (stance, work items, brief template, hard constraints, pipeline choice, running and watching), references/lanes.md (worktrees, devices, sync/merge, restart-replay cursor fix), references/debugging.md (eight symptom/confirm/do playbooks) and references/delivery.md (artifacts, LAN URLs, WIP naming, install boundaries), each with a clearly labelled project example where Android/device specifics apply. Append orchestration verification habits to references/verification.md and add the four new files to install.go's managed inventory.
82 lines
4.6 KiB
Markdown
82 lines
4.6 KiB
Markdown
# Parallel lanes
|
|
|
|
A lane is one sequence of runs in its own workspace, on its own branch, with its own
|
|
device. Several lanes run concurrently without colliding, and each lane advances its
|
|
own list of briefs one item at a time.
|
|
|
|
## Why lanes, and what separates them
|
|
|
|
Runs in different resolved workspaces execute concurrently; a second run in a
|
|
workspace an active run is already changing is refused, naming the conflicting run
|
|
(`references/operations.md`). That guard is what makes lanes safe: give each lane its
|
|
own checkout so its runs never share a workspace. Concurrency is **between lanes**,
|
|
never inside one.
|
|
|
|
- **One git worktree per lane, on its own branch.** Create it with
|
|
`git worktree add <path> -b <lane> main`. Never run two lanes in the same tree, and
|
|
never run a lane in the main checkout while another lane is merging into it.
|
|
- **One emulator or device per lane.** Name the lane's serial explicitly in every
|
|
brief dispatched to that lane, and forbid the serials the other lanes own. Never
|
|
point two lanes at one device, and never at the operator's physical device.
|
|
- **One work list per lane** — a plain file of brief filenames, read one at a time.
|
|
- A brief for a lane must name the lane's worktree and device, so the run cannot
|
|
stray onto another lane's tree or device.
|
|
|
|
## Sync and merge
|
|
|
|
- **Sync before each item:** merge `main` into the lane branch so the item builds on
|
|
the latest tree. If the sync conflicts, abort the merge and continue on the older
|
|
base rather than hand-resolving mid-tick; record that it happened.
|
|
- **Merge back only when main's tree is idle.** The main-lane publishes a busy marker
|
|
while one of its items runs; merging lanes wait for it. Never merge into `main`
|
|
while a run is using `main`'s working tree.
|
|
- **One lane merges at a time** — take a lock around the merge so two lanes cannot
|
|
merge simultaneously.
|
|
- **Record a conflict, do not force it.** On a merge conflict into `main`, abort the
|
|
merge and leave the work on the branch for a human to resolve; write it to a
|
|
conflicts log. Never force-push, rebase, or otherwise rewrite around a conflict.
|
|
The committer stage may resolve a conflict inside its own workspace, but a lane
|
|
never silently discards the other side's work.
|
|
- **Clear stale markers.** A marker left by a lane that died must not stall the
|
|
others forever; expire markers older than a bounded age.
|
|
|
|
## The restart-replay hazard
|
|
|
|
A lane script that simply re-reads its list from the top **replays completed items**
|
|
after a crash or restart: it re-invokes the model, repeats side effects and may
|
|
re-commit already-landed work. A list is a plan, not a resume point.
|
|
|
|
- **Fix: persist a cursor.** After each item is fully committed and merged, append it
|
|
to a per-lane `done` file. On startup, skip every item already recorded there and
|
|
resume from the first unrecorded one. Record an item only once it has landed; an
|
|
item that failed twice stays unrecorded so a later restart retries it deliberately.
|
|
- An **interrupted run is not replayed automatically**; a retry is explicit
|
|
(`references/operations.md`). Do not restart a lane to "get back to where it was"
|
|
without the cursor, or it will re-run finished items. Never relaunch a duplicate of
|
|
a run that is still active — reattach with its request key instead.
|
|
|
|
## Coordinating the shared server
|
|
|
|
- **Do not restart the shared Pipelines or OpenCode server while any lane has a run
|
|
in flight.** A restart interrupts in-flight runs (`references/debugging.md`). A
|
|
deploy/restart tick must first ask the other lanes to stop starting runs, wait for
|
|
active runs to reach zero, then restart; if runs will not drain, defer.
|
|
- All lanes read the one logical endpoint; a lane's workspace is what separates it,
|
|
not a separate server.
|
|
- A run that pauses the world (touching shared state, restarting a service) must hold
|
|
the busy marker for the whole pause, not only while a model call runs.
|
|
|
|
## Example (this repository, not a rule)
|
|
|
|
The repository runs several lanes at once. Concretely, at the time of writing:
|
|
|
|
- Worktrees `lane-app2` (branch `lane-app2`) and `lane-go` (branch `lane-go`) under
|
|
the temp directory, with a third main lane in `/Users/alan/repos/pipelines`.
|
|
- Emulator ownership: lane A uses `emulator-5554`, lane B uses `emulator-5556`; a
|
|
brief names its own serial and states the other's is forbidden.
|
|
- The main lane uses a busy marker while its item runs; the app lanes merge into
|
|
`main` when it is idle and record conflicts instead of forcing them.
|
|
- Restarts are deferred: a deploy tick waits for active runs to reach zero before it
|
|
stops the server. This is the pattern the general rules above describe, not a
|
|
hardcoded configuration a new project must copy.
|