Capabilities · Lanes

Lanes — build, gate, land

A lane is one task built the same way every time: its own branch and worktree, a builder, a verifier that did not write the code, and your repo's own checks. Landing is a separate step.

Build a task in its lane

A lane starts from a task on your board whose contract is written: the files it owns, what it exposes and its acceptance. /agentry:init learns where your board keeps them. 

/agentry:exec T-4
  1. The worktree. agentry lane exec start finds the contract, cuts the branch agentry/T-4 in its own worktree under .agentry/run/worktrees/, and writes the task's board cells. The builder never works in your main checkout.
  2. The builder. Works only inside the contract and reports one of DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT or BLOCKED. A file it needs and does not own is a question for you, not a quiet edit.
  3. The verifier. A fresh agent checks the work against the acceptance and returns PASS, PASS WITH NOTES or FAIL. It never fixes what it finds; notes go back to the builder for a round.
  4. The gate. Your repo's own checks, named in .agentry/workflow.json. agentry lane exec gate T-4 runs them in the worktree and records the result on the branch tip. The lane closes on a green gate and writes its episode to memory.

exec.preset sets how much checking a lane gets: standard by default, lean to verify flagged items only, strict for more notes rounds and a final verifier every time; Workflows has every key. A lane never merges and never pushes.

Land it

/agentry:merge T-4

The land runs agentry lane merge one mode at a time, each printing a step table and the next step: the preflight, your repo's merge checks, the cherry-pick onto main, the gate (or the recorded gate it may trust), then the board's done row, commit and handoff line in one board commit. It stops at the first red step. Exit 0 is done, 1 a red step, 2 a refusal.

Pushing follows merge.push: ask by default, so main is pushed only on your yes. --cleanup then removes the worktree and the branch.

Work that already reached main

Sometimes a verified lane's commits get to main another way: a fast-forward of a combined branch, or a squash. The preflight then finds nothing to land. Close the lane with: 

agentry lane merge T-4 --resolve landed
  • It checks by patch. git cherry runs over the lane's own commits. When every one is on main, the lane is recorded as merged: nothing picked, no commit made.
  • It refuses what it cannot find. A commit with no matching patch on main is named by its short SHA and subject. Add --checked only once you have checked it landed squashed or reworded; that answer is kept with the lane.
  • The board stays yours. The done row and handoff line are left for you to write. A lane stacked on this one counts it as landed, and --cleanup follows as after any land.
Gotcha "Found on main" is by patch, not by tree: a commit that landed and was reverted still counts. git's patch id ignores whitespace, so check whitespace-significant files (Python, YAML, Makefiles) by hand before closing.

A land that stopped halfway

A land left in merging that cannot go on is closed on your call, after checking main: --resolve landed when every pick is on main, --resolve rolled-back when none is (the lane is verified again). Both refuse while git is mid-pick and touch neither main nor the board.

Lost track

agentry lane exec show T-4 prints where one lane stands and its next step. /agentry:start shows every lane in flight. agentry lane --help lists the rest: note, session, spike and sweep.

Next: Memory, where a lane's episode goes.