Skip to main content

Review Lanes

Review lanes are role worktrees used for reviewing another lane's branch. Early consumer use found that detached FETCH_HEAD reviews are easy to lose and hard to repeat, so fairway should document named review branches as the default pattern.

Principles​

  • Review is routed by config, not by whoever is idle.
  • The claimant cannot approve their own work.
  • Review branches are named and disposable.
  • Reviewer/merge lanes can own the integration step when the orchestrator is not doing it: verify the scratch branch, merge locally into the configured main branch, and push the integrated main branch for CI.
  • Findings live in fairway review records or artifacts, not random repo-root files.
  • Model/provider diversity is useful when practical, but provider choice never bypasses role ownership or gates.

Inside the reviewer lane worktree:

git fetch origin
git rebase origin/main
git fetch origin agent/backend
git branch -f review/backend origin/agent/backend
git switch review/backend
fairway record review T-042 --reviewer arch --verdict approve --reason "schema and API impact reviewed"

The branch name should be derived from config:

review/{source-role}

fairway route review <task-id> determines which review role(s) are required. fairway merge-ready <task-id> verifies the required approvals exist before the coordinator merges.

Reviewer/Merge Lane​

When execution is split across disposable provider threads, the merge lane is the control point that prevents remote branch sprawl:

  1. fetch or inspect the worker branch locally,
  2. run focused validation and review,
  3. record the Fairway review verdict,
  4. merge or squash into the configured main branch locally,
  5. push the main branch or approved integration branch with push intent main-validation or integration,
  6. record CI/deploy evidence and close out the worker branch.

After the last required review domain is approved, fairway coordinator plan surfaces a review-complete handback for the coordinator or reviewer/merge lane. That handback is a signal to run fairway merge-ready <task-id> and continue the configured merge/push/release workflow if it passes. It is not approval to auto-merge or push, and it does not replace merge-ready.

Once the coordinator records the merge/push/closeout decision, record normal evidence such as push intent, lane closeout, release-run/release-verify output, or an explicit review-handback-ack evidence row. Coordinator plan treats those records, and terminal tasks with recorded completion commits, as closed for review-handback purposes so older completed work does not reappear as a fresh next action.

The merge lane should not push every provider thread branch just to get CI. Worker branches are scratch by default; the merged batch is the remote validation unit unless a review, release, backup, or exception intent is recorded.

Future Command​

fairway review checkout <task-id> [--source-role <role>]

This should:

  1. resolve the source role branch,
  2. fetch it,
  3. create or reset review/{source-role},
  4. switch the current review worktree to that branch,
  5. print the task detail and required review routes.