Files
pipelines/internal/author/skill/references/queue.md
T
alan 8f3ebf74ad skill: replace the lane model with the work queue
The lane machinery is gone: work is a markdown queue, items run in parallel in
their own worktrees, the committer stage lands its own work, land-check.sh gates
cleanup, branches are never deleted, and pipelines wait (rather than a driver
script) is what wakes a session. references/lanes.md becomes references/queue.md;
the remaining lane references in work/orchestration/debugging/delivery/format and
SKILL.md are rewritten, and the installer now prunes a managed file it no longer
bundles when the copy is unmodified.
2026-10-18 01:12:21 +01:00

75 lines
4.3 KiB
Markdown

# The work queue
There are no lanes. Work is a **markdown queue** of items and a handful of rules that keep several
items moving at once without losing any of them.
## The queue is a file you can read
- One markdown file lists the items, numbered, each saying what it is, the **brief** that carries the
task, and its state. Read it top to bottom and take the first unfinished item.
- An item is done when it is **committed to main, verified, and — if it changed the app or the
server — deployed and installed**. Mark it in the file.
- The file is the resume point. A session that dies and comes back reads it and continues; nothing
is replayed because nothing is inferred from "what was I doing".
## Parallel by default
Run independent items **concurrently**. Serialisation is the exception and must be justified by a real
conflict, never by caution, and never presented as the operator's decision.
Serialize only when:
- two items edit the **same files** at the same time and the merge cost would exceed the gain;
- the **one capture device** is the bottleneck — implementation still runs concurrently, captures
queue on the device lock;
- the provider's **spend cap** is close, because tripping it fails every run in flight at once.
## One worktree and branch per item
- `git worktree add -b <item> <path> main`, and the brief names that worktree. Runs in different
workspaces execute concurrently; a second run in a workspace an active run is changing is refused,
naming the conflicting run (`references/operations.md`). One worktree per item is what keeps that
guard from being a bottleneck.
- The brief also names the **device** the item may use and forbids the others, so two items never
fight over one phone. Never use the operator's own device unless the brief explicitly allows it.
- Choose the pipeline by area (`references/orchestration.md`); each area pipeline reads the project's
own map — `android/AGENTS.md`, `internal/tui/AGENTS.md`, `internal/server/AGENTS.md` — for the
build, test, run and capture commands. The pipeline carries how that technology is worked on
anywhere; the map carries what is specific to this repository.
## Landing is the pipeline's job
- The **committer stage lands its own work**: after committing, it merges `main` into its branch,
resolves any conflict there with the context of the change it just made, runs the checks again, then
merges the branch into `main` and verifies its ancestry.
- There is **no merger process, no resolver pipeline and no escalation from pipeline to pipeline**. A
conflict is resolved by the stage that caused it, in the run that caused it.
- Merging needs `main`'s tree for a moment: the committer takes a lock and retries, so a concurrent
landing cannot corrupt it.
## The landing gate, and what must never happen
- After every item, and **before any cleanup or before starting the next item**, run
`land-check.sh <branch>`. It must report the branch as an **ancestor of main**.
- If it refuses: do not remove the worktree, do not touch the branch, do not start the next item.
Report the landing failure and the commits that are not in main.
- **Never delete a branch.** Deleting a branch whose commits are not yet in main leaves them
unreferenced — that is how six finished items were lost in one day. Removing a worktree is fine, the
commits live on the branch. A cherry-pick's *deletions* need the same scrutiny as its conflicts:
replaying an older commit can delete a file that a later refactor added.
## Waiting without a scripting harness
- `pipelines wait <run-id> […​]` blocks until the runs finish and exits; run it as a **background
task** so the session is woken exactly when the batch is done. A run that failed is still a
finished run: it exits 0 and says what happened.
- Do not build a polling loop, a cursor file or a driver script to answer "is it done yet", and do not
infer progress from an earlier read. Ask the server, or wait on it.
## The shared server
- **Do not restart, rebuild or redeploy the shared Pipelines or OpenCode server while any item has a
run in flight** — a restart interrupts in-flight runs (`references/debugging.md`). A deploy must
wait for active runs to reach zero, and deploys are the operator's step.
- All items read the one logical endpoint; a worktree separates them, not a second server.