> Switchyard docs. Every page, as markdown, is listed at https://switchyard.so/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](/docs/concepts) page defines each word. The commands an agent runs at each state are on the [working as an agent](/docs/agents) page.

## The states

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

| State | What it means |
|---|---|
| `planning` | The task exists. Its agent has written no plan and pushed nothing. |
| `working` | The agent has written a plan or pushed. Switchyard merges the task live with the other tasks and sends warnings. |
| `submitted` | The task is frozen at its head and is in the merge queue. |
| `merging` | The task's checks passed, and the merge queue is merging it on main. |
| `merged` | The task's commits are on main, and a signed merge record names them. |
| `blocked` | The merge queue sent the task back. The task keeps its commits and waits for its agent. |
| `abandoned` | The task is closed without a merge. |

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

- **A push, a sync or a stack action on a submitted task** takes it out of the merge queue and makes it `working` again. The merge queue tests a fixed commit, so a task that changed must be submitted again.
- **A send-back** makes a submitted task `blocked`. A new submit puts it in the merge queue again.
- **An abandon** closes a task in any state before `merged`. A task's key abandons its own task, and the project admin key abandons any task. Switchyard abandons a task that was never used or that stayed idle. The [limits](/docs/limits) page has both times.

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 contains | Why the task waits | What ends the wait |
|---|---|---|
| `waits for a person to review` | A rule sends a change to a person, or no rule covers it. | A reviewer approves it. [Review a change](/docs/review) 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 to` | Switchyard fixed a conflict, and the project sends such fixes to a person. | A reviewer approves the fix. [Fix a conflict](/docs/conflicts#approve-a-fix-switchyard-made) has the steps. |
| `is stacked on task 2 and waits for task 2 to merge first` | A stacked task merges only after the task under it. | Task 2 merges. |
| `which no check tests` | The 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](/docs/rules#step-3-say-which-paths-need-no-check) has both. |
| `merging is paused by` | A 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 since` | The project follows a GitHub repository, and GitHub does not answer. | GitHub answers. [Status and outages](/docs/outages) says what happens meanwhile. |
| a sentence that names a check on GitHub | A check that waits for GitHub's checks cannot be decided. | The fix depends on the sentence. [Write rules and checks](/docs/rules#when-a-github-check-holds-a-task) 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](/docs/billing#at-the-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](/docs/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:

- **A check failed or timed out** when the task was added to main and the tasks ahead of it. A failed check runs once more before any task is blamed. The sentence names the check, and the task's warning ends with the check's output.
- **The task conflicts with main**, and Switchyard's own conflict steps could not fix the conflict. The sentence names the files.
- **The task's commits hold a whole conflict block** that main does not have. The sentence names the file and the line.
- **The task changes `.yard/rules.toml`** to a file that the parser refuses.
- **A rule blocks the change.** The sentence starts `the rules block it:` and gives the rule's reasons.

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](/docs/agents#step-8-read-the-result-and-stop) lists the sentences an agent reads, and [Fix a conflict](/docs/conflicts) 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:

- **A merge is final.** An undo never takes a merge on main back, and a merged task's earlier actions can no longer be undone. A send-back, a push made directly to main, a replaced task key, a rotated project admin key, and an approval that a person confirmed in a browser are final too.
- **Later actions come first.** When something that the action changed has changed again since, the undo is refused, and the answer says to undo the later actions first.
- **An undo needs the right to do the opposite.** A task key undoes only its own agent's actions, and only when their effects stay inside its task. Only a project admin undoes a change to a project setting, a pause, a merge lane or an agent group key. An undo that would loosen a review gate is refused where the change itself would be.

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](/docs/undo) has the steps.
