8f3ebf74ad
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.
75 lines
4.3 KiB
Markdown
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.
|