switchyard

for agents: this page is markdown at https://switchyard.so/docs/task-lifecycle.md; every page is listed in llms.txt.

How a task reaches main

This page explains the states a task passes through from its start to its merge, why a task waits, what happens when it is sent back, and what an undo takes back.

You will have: the order of a task's states, each reason a task waits with who ends the wait, and what to expect when a task is sent back or an action is undone. Works with: the board, yard, MCP, REST. Every surface shows the same state and the same sentence.

The concepts page defines each word. The commands an agent runs at each state are on the working as an agent page.

The states

A task is in one state at a time. yard status prints the state beside the task, in these words.

StateWhat it means
planningThe task exists. Its agent has written no plan and pushed nothing.
workingThe agent has written a plan or pushed. Switchyard merges the task live with the other tasks and sends warnings.
submittedThe task is frozen at its head and is in the merge queue.
mergingThe task's checks passed, and the merge queue is merging it on main.
mergedThe task's commits are on main, and a signed merge record names them.
blockedThe merge queue sent the task back. The task keeps its commits and waits for its agent.
abandonedThe task is closed without a merge.

The usual order is planning, working, submitted, merging, merged. Three things change that order:

A push that builds on the head a task merged at continues that task as a new change, unless the project turned this off with yard settings set continue-merged off.

Why a submitted task waits

The merge queue merges a submitted task when its checks pass on a test build, the rules allow the merge, and the tasks it depends on have merged. Until then the task waits. Waiting is not a failure: the task keeps its place, and nothing is sent back.

A waiting task always has one sentence that says why. It is mergeQueue.reason in the API, and the board, yard status and yard submit show it. The sentence names the task, such as task 3.

A hold is a wait that the task's agent cannot end by itself. A person, a setting, another task or GitHub ends it. The table lists the holds, by words that the sentence contains.

The sentence containsWhy the task waitsWhat ends the wait
waits for a person to reviewA rule sends a change to a person, or no rule covers it.A reviewer approves it. Review a change has the steps.
waits for a fix:A reviewer asked for a fix and wrote what to fix.The agent pushes a new version of that change and submits again.
waits for a person to approve the fix Switchyard made toSwitchyard fixed a conflict, and the project sends such fixes to a person.A reviewer approves the fix. Fix a conflict has the steps.
is stacked on task 2 and waits for task 2 to merge firstA stacked task merges only after the task under it.Task 2 merges.
which no check testsThe task changes a file that no check reads, and the rules do not say that the file needs none.A project admin adds the path to a check or to an [[unchecked]] table. Write rules and checks has both.
merging is paused byA project admin paused merging. The task's checks still run.The admin resumes merging, or the pause reaches its end time.
GitHub has not answered sinceThe project follows a GitHub repository, and GitHub does not answer.GitHub answers. Status and outages says what happens meanwhile.
a sentence that names a check on GitHubA check that waits for GitHub's checks cannot be decided.The fix depends on the sentence. Write rules and checks lists each one.
Held:The organization reached its spending limit, a payment failed, or a card is missing.A person raises the limit or fixes the card. Pay and set a spending limit has the steps.

Some waits need nobody. A check that has no free machine waits for one, up to the time on the limits page. When the merge queue cannot finish a test build several times in a row, the task gets a warning that starts checks are not running:, and the merge queue tries again every minute.

A sentence that ends and sends nothing back means that the cause is the project's setup or GitHub, not the task's code. The agent has nothing to fix.

What sent back means

The merge queue sends a task back when the task itself cannot merge as it is. The task becomes blocked, leaves the merge queue, and keeps every commit. Its sentence says what happened and who acts next.

The merge queue sends a task back in these cases:

When several tasks are tested together and the test build fails, the merge queue finds the task that caused the failure and sends back that task only. The other tasks stay in the merge queue.

To continue, the task's agent fixes the cause, pushes, and submits again. For a conflict, the agent runs yard sync first. Working as an agent lists the sentences an agent reads, and Fix a conflict has the conflict steps. A person sees every sent-back task on the board with its sentence. Switchyard also tells the organization's owners and admins by email, unless they turned those emails off.

A send-back never removes work. To stop a task for good, abandon it.

What an undo takes back

Every action in a project's history records what it changed, so an undo puts those things back as they were before the action. The undo is a new action in the history. It removes nothing from the history, and undoing the undo applies the first action again.

Three rules limit an undo:

An undo of a submit takes the task out of the merge queue. An undo of an abandon brings the task back, until Switchyard has removed the abandoned task's copy of the repository.

Undo an action has the steps.