land-the-work.md

Landing order

The readers of this page are the orchestrator and the agents. The base rule covers each command of this page that uses origin/<base branch>.

Land the work

The steps to land a ticket are in "Run one ticket". This section gives the rules between tickets.

• After tasker approve, each agent sends the orchestrator the list of files that the plan changes. tasker refine and tasker approve also print a warning when another task in progress changes the same file.
• If the edit of a shared file is not required, the agent removes it in a refine. If it is required, the orchestrator sets the landing order.
• When the orchestrator sets the landing order, it tells the later agent which ticket must land first. The earlier ticket is the ticket that must land first. The later agent is the agent of the ticket that lands after it. The earlier agent is the agent of the earlier ticket.
• The later agent does the steps of "Run one ticket" up to tasker accept in step 9. Before it runs tasker accept, it waits until the issue of the earlier ticket is closed. While the later agent waits, the task is in awaiting_work_review.
• The start state is the state of the earlier task before a wait on a landing order of the overlap rule. Before the orchestrator tells the later agent to wait, it reads this state with tasker show <issue>. The orchestrator reads it before each wait, also before a new wait. If the earlier task is far from landing, for example in awaiting_plan_review, the orchestrator tells the user. If the start state is before awaiting_work_review, the hold rule also applies. If tasker show <issue> fails, the failure rule applies, and the start state is unknown.
• To wait, the later agent reads the state of the issue of the earlier ticket one time: gh issue view <number> --json state -q .state. If the state is OPEN, the later agent reads it again every 30 seconds until it is CLOSED. The later agent waits at most 60 minutes from the first read. With each read of the issue state, the later agent also reads the state of the earlier task on the state: line of tasker show <earlier issue>, for example state: landed. If the earlier task is in landed, finishing or finished, the later agent follows the bullet "When the issue of the earlier ticket is closed". After the tasker update-branch of that bullet, the later agent stops reading the task state. The 60-minute limit still counts from the first read of the issue state. If tasker show <earlier issue> fails, the later agent reads no more task states in this wait, and it waits for the close of the issue.
• If the state is still OPEN 60 minutes after the first read, the later agent stops waiting. To stop waiting means that the later agent stops reading the issue state and the state of the earlier task.
• If the earlier agent stops or ends its work before the issue of the earlier ticket closes, the orchestrator tells the later agent to stop waiting. Then the later agent stops waiting. For example, the earlier agent stops after its last loop of "Review findings". Or it reports a rebase conflict that it does not fix (see docs/dev/rebase-conflicts.md). Or it stops in the CI wait, for example when no run showed.
• This bullet covers two tickets of the orchestrator. If the earlier agent stops to wait for a decision of the user, the orchestrator changes the landing order at once. It changes the order as the bullet "If the orchestrator changes the landing order" says. It does not let the later agent wait until the end of its 60 minutes. In one milestone, two waits of 60 minutes were lost this way. For a landing order of the overlap rule, the bullet "Only the user changes a landing order of the overlap rule" applies.
• If the later agent stops waiting, for either reason, it stops and reports that it stopped waiting, and why.
• After the later agent reports that it stopped waiting, the orchestrator decides the next step and tells the user. For a landing order between two tickets of the orchestrator, the orchestrator tells the later agent to wait again. Or it changes the landing order so that the later ticket lands first. For a landing order of the overlap rule, the stuck-task rule gives the next step.
• Only the user changes a landing order of the overlap rule, because the earlier ticket belongs to another orchestrator. If the user swaps the order, the user tells each orchestrator the new order. Each orchestrator tells its own agent, as the overlap rule says. Then the two tickets swap roles, as the sentences of the bullet "If the orchestrator changes the landing order" from "Then the two tickets swap roles." say. The first sentence of that bullet, where the orchestrator tells both agents, covers only two tickets of the orchestrator. If the user postpones the earlier ticket, the user does this through the orchestrator of that ticket. That orchestrator does the steps of the defer rule. The task of the earlier ticket becomes a parked task, and the paragraph of the defer rule that starts "A parked task stays in flight" applies. The user tells the orchestrator of the later ticket that the earlier ticket is postponed, as in the swap case. That orchestrator then tells the later agent to continue step 9 of "Run one ticket" from tasker accept. Another orchestrator can relay a change of a landing order from the user. Then the orchestrator that gets the relay asks its own user to confirm the change before it tells its agent, as A decision of the user says. Until the user confirms, the old order stays: the landing order before the relay. The reason: a message from another session is not an answer of the user. The relayed order can also differ from an answer that the user gave before to the orchestrator that gets the relay. When the user confirms, the orchestrator that gets the relay tells its agent the new order, as the overlap rule says. The orchestrator that gets the relay also tells the other orchestrator with SendMessage that its user confirmed. The orchestrator that relays the change does not tell its own agent the new order until the other orchestrator reports that its user confirmed. Otherwise the two agents follow opposite orders for a time. If the user of the orchestrator that gets the relay rejects the change, that orchestrator tells the other orchestrator with SendMessage. Then the old order stays for both orchestrators.
• If the orchestrator tells the later agent to wait again, or to start the wait under the hold rule, the later agent starts a new wait as in the "To wait" bullet. The new limit is 60 minutes from the new first read. The task stays in awaiting_work_review.
• If the orchestrator changes the landing order, it tells both agents the new order. Then the two tickets swap roles. The ticket that was the later ticket becomes the earlier ticket, and its agent becomes the earlier agent. The ticket that was the earlier ticket becomes the later ticket, and its agent becomes the later agent. From then on, "earlier" and "later" name the roles in the new landing order. If the new earlier agent waits before tasker accept, its task is in awaiting_work_review, and it continues step 9 of "Run one ticket" from tasker accept. Otherwise, it continues its steps of "Run one ticket", and it does not wait before tasker accept. Step 9 of Run one ticket gives the state after each command. Before the new later agent runs tasker accept in step 9, it follows the wait rules of this section, from the bullet "The later agent does the steps of ...". The orchestrator changes a landing order only between two of its own tickets. For a landing order of the overlap rule, the bullet "Only the user changes a landing order of the overlap rule" applies.
• When the issue of the earlier ticket is closed, or when the earlier task is in landed, finishing or finished, the later agent runs tasker update-branch. The later agent reads the state of the earlier task as the bullet "To wait" says. In landed, the work of the earlier ticket is already on main. The CI wait and tasker finish of the earlier agent can still take up to 30 minutes. On 2026-10-17, the user told the agent of #231 to run tasker update-branch while the task of its parent #229 was in landed and waited for its CI run. The task goes from awaiting_work_review to executed. For a stacked task, the base rule says what this update does. The later agent then reads the base branch: line again, as the base rule says. Then the later agent continues step 9 of "Run one ticket" from its tasker verify. If tasker verify fails, the later agent follows the verify-failure rule. If the issue of the earlier ticket is still open when the later agent reaches tasker accept, the later agent waits for the close, as the bullet "To wait" says. If the later agent did not start that wait yet, for example under the hold rule, it starts the wait. If the later agent already ran tasker update-branch after the earlier ticket landed, the sentences above do not apply. The later agent runs no second tasker update-branch and continues step 9 of "Run one ticket" from tasker accept. The git merge-base --is-ancestor origin/<base branch> tasker/<task branch> of the diff read right before tasker accept finds a later move of the base branch. On 2026-10-17, the agent of #248 updated its branch from executed after its parent #252 landed, and then asked the orchestrator about a second update.
• The later agent of a stacked task never runs tasker merge before the issue of the parent is closed, because tasker merge refuses a stacked task.
• If a refine, or the tasker review <issue> "<feedback>" of the add-work rule, must change a file that another ticket changed and landed after this task started, the agent runs tasker update-branch first. Otherwise the new work uses the old text of the file, and the rebase at landing can conflict.
• If the task is in reviewed (a refine of step 8) or in awaiting_work_review (work for the add-work rule), tasker update-branch moves the task to executed. Then the agent runs tasker verify. If the verify passes, the task goes to awaiting_work_review, and the agent runs tasker review. If it fails, the agent follows the verify-failure rule.
• The new review is a full review pass. It reports the open findings again as still open, and it can also report new findings.
• If the new review has findings, the task goes to reviewed, and the agent goes to step 6. Steps 6 to 8 then read, dismiss and refine all the open findings. If the agent must also add work (the task was in awaiting_work_review), the agent puts that work in the feedback of the refine of step 8. If the agent dismisses all the findings in step 7 instead, the task goes to awaiting_work_review, and the agent follows the add-work rule instead of going to step 9.
• If the new review has no findings, the task stays in awaiting_work_review, and tasker refine refuses to run. In that case, if the agent still must make the change, it follows the add-work rule. Otherwise, the agent goes to step 9.
• If the task was in reviewed, the review before tasker update-branch and the review after it count as one loop of "Review findings".
• If the task is in awaiting_plan_review (a refine of step 4), tasker update-branch keeps the task in awaiting_plan_review. Then the agent runs the refine of step 4.
• If a stacked task is in approved and its parent is in landed, tasker update-branch moves the base of the task to the base of the parent. On 2026-10-18 at 08:09, the parent #340 of #347 was in landed, and origin/main was the tip of #340. tasker update-branch of #347 printed that the parent landed, and it moved the base to main. The head of the task did not move, so no demotion happened. The task stayed in approved with its approval, and no refine was needed.
• If tasker update-branch reports a rebase conflict, the agent follows docs/dev/rebase-conflicts.md. The agent does not copy that procedure.
• Before the orchestrator sends added work or an answer to an agent, the orchestrator reads the state of the task with tasker show <issue>. The orchestrator runs this command itself. It does not send a message to the agent only to learn the state, because a message to an agent that has ended starts the agent again (see "Terms" in "Quota"). The message with the work or the answer names the state that the orchestrator found. The state can change while a message waits, and the next command then depends on the new state.
• When the orchestrator edits an issue body, or posts a comment that starts with ## Change of scope or ## Design gap, while the agent of that ticket runs, the orchestrator sends all the changes together, before the next refine of the agent. On #117, edits that arrived one by one cost extra refines. After a comment that starts with ## Change of scope, the orchestrator also posts the open-question note of the change-of-scope comment on each open issue with no task that names the changed fact.
• This bullet covers a change to an issue in flight by an orchestrator. The requester is the orchestrator that wants the change. The requester does not edit the body. The orchestrator of the task is the orchestrator of the milestone of the issue. Before it changes an issue, the requester first runs tasker status and looks for the full issue key in the output. The requester counts the issue as in flight when the output lists a task for it. If the output lists no task for the issue, the requester does not follow this bullet. If tasker status fails, the failure rule applies. The requester posts no comment, files no issue and leaves the body as it is. If the issue is in flight, the requester chooses by the kind of change: it puts a correction of what the ticket builds in a comment on the issue, and a new requirement in a new issue. For a correction, the requester first asks its user, as the stop rule says. Then the requester posts a change-of-scope comment. Then the requester reads the milestone of the issue with gh issue view <number> --json milestone -q '.milestone.title'. If gh issue view fails, the failure rule applies, and the requester leaves the comment on the issue and the body as it is. If the command prints an empty line (the issue has no milestone), the requester leaves the comment on the issue and the body as it is, and it tells the user. If the issue is of the own milestone of the requester, the requester is the orchestrator of the task. In that case, the orchestrator of the task sends no message. If the issue is of another milestone, the requester sends the orchestrator of the task one message with SendMessage that gives the link of the comment. The requester sends the message to the session name of the form orchestrator-<milestone> of the notice rule. The requester counts a missing session with the name of the milestone as a failed message. If SendMessage fails, the failure rule applies, and the requester leaves the comment on the issue and the body as it is. Before the orchestrator of the task sends the link of the comment, the orchestrator of the task reads the state of the task with tasker show <issue>, as the bullet "Before the orchestrator sends added work or an answer to an agent" of Land the work says. If tasker show <issue> fails, the failure rule applies to the orchestrator of the task. The orchestrator of the task sends no link to its agent. The comment stays on the issue. If the task is in accepted or a later state (merging, landed, finishing, cleanup_failed or finished), the orchestrator of the task sends no link to its agent. The orchestrator of the task tells the user and the requester that no step takes the correction. If the issue is of the own milestone of the requester, the two orchestrators are one session, and the orchestrator of the task tells only the user. If the two orchestrators are not one session, the orchestrator of the task tells the requester with SendMessage, to the session of the requester. If SendMessage fails, the failure rule applies to the orchestrator of the task. The comment stays on the issue, and the body stays as it is. The user decides the next step, for example a new issue after the landing. Otherwise, the orchestrator of the task sends the link of the comment to its agent, and the agent of the task follows the steps of the section "The change-of-scope comment" of plan-review.md. The orchestrator of the task makes no decision about an edit. For a new requirement, the requester files a new issue with the steps of Before a post of issues.md, in the milestone that The milestone of an issue of planning.md gives. The requester sends no message for a new requirement. On 2026-10-15, orchestrator-m8 edited one bullet of the body of #194 (Docs) while the task of #194 was in review loop 1, and orchestrator-docs learned of the edit only from a later message.
• When the final report of the agent of a ticket says that the ticket landed, the orchestrator of the ticket does these steps in this order. The final report says this when the agent ran tasker finish, which closes the issue. First, the orchestrator deletes the jobs of the ticket, as Delete the job says. Then the orchestrator does the re-read rule. Then the orchestrator does the memory step. Then the orchestrator does the notice rule. Last, the orchestrator reads the board for the next ticket, as Pick the tickets says. In the memory step, the orchestrator searches its memory files for the number of the issue. If the search finds no file with the number, the memory step is complete. In each file that names the issue, the orchestrator deletes the lines that the landed docs now hold. The orchestrator reads the landed docs in its local clone, after the re-read rule. If no line is left besides the frontmatter and the links, the orchestrator deletes the file and its line in the index of the memory. If a search, an edit or a delete of a memory file fails, the orchestrator tells the user the step and the error. The memory file then stays as it was, and the orchestrator continues with the next step of the order. The orchestrator does these steps for each ticket, also for a ticket of the milestone "Docs". The user decided the memory step on 2026-10-17 and the order on 2026-10-18.

The overlap rule

Several orchestrators can run at the same time, for example one for each milestone. Before a ticket starts, and each time an agent sends the list of files after tasker approve, the orchestrator compares the files with each task in flight of every milestone, not only of its own milestone. Before the start, the files are the files that the issue names. tasker status lists the tasks in flight, and tasker show-plan <issue> gives the files of each plan. gh issue view <number> --json milestone gives the milestone of a task.

For a shared file, the overlap rule sets a landing order. A ticket of an earlier milestone lands first. A ticket of the same milestone or of no milestone follows the bullets of Land the work. For a ticket of the milestone "Docs" and a ticket of a numbered milestone, the Docs rule applies instead. Each orchestrator tells its own agent the landing order, also when its ticket lands first. For a stacked ticket and its parent, the stacked-ticket rule wins over the sentence "A ticket of an earlier milestone lands first".

The Docs rule

This rule covers only a shared file between a ticket of the milestone "Docs" and a ticket of a numbered milestone. The orchestrator of each ticket still does the compare of the overlap rule. For these two tickets, the orchestrator of each ticket sets no landing order for the shared file. The orchestrator of each ticket sends no landing order to the other orchestrator. When the orchestrator of a ticket finds such a shared file, it tells its own agent that the Docs rule covers that file and that the fourth case of the stop rule does not apply to that file. If the agent already stopped under the fourth case for that file, this message is the answer, and the agent continues with step 4 of Run one ticket. For these two tickets, the Docs rule wins over the second sentence of the bullet "If the edit of a shared file is not required". The first sentence of that bullet still applies. Each ticket lands when it is ready. If the other ticket lands first, the agent of the ticket that lands second runs tasker update-branch as the diff read says. For these two tickets, these rules do not apply: the bullet "When the orchestrator sets the landing order", the wait rules, the bullet "When the issue of the earlier ticket is closed", the early update of Review findings and, for the shared file, the fourth case of the stop rule. The wait rules are the bullets of Land the work from "The later agent does the steps of ..." to "If the orchestrator changes the landing order", the hold rule and the stuck-task rule. These bullets include the start-state bullet ("The start state is ..."), the bullet "To wait" and the bullet "Only the user changes a landing order of the overlap rule". The user decided this rule on 2026-10-15. For a stacked ticket and its parent, the stacked-ticket rule wins over this rule.

The hold rule

This rule covers a landing order of the overlap rule when the start state is before awaiting_work_review, for example awaiting_plan_review or executing. The later orchestrator is the orchestrator of the later ticket. The later orchestrator tells the later agent not to start the wait of the "To wait" bullet. The later agent stops before tasker accept. When the hold starts, the later orchestrator sends one message with SendMessage to the orchestrator of the earlier ticket. The message asks for a report when the earlier task reaches awaiting_work_review or a later state, and when the issue of the earlier ticket closes. The orchestrator of the earlier ticket sends each of these reports to the later orchestrator with SendMessage. If a message of this rule fails, the failure rule applies to the orchestrator that sends it. The later orchestrator reads the state of the earlier task again with tasker show <issue> when the orchestrator of the earlier ticket or the user reports a change. It also reads it each time it reads the board after a landing (Pick the tickets). When the earlier task is in awaiting_work_review or a later state, the later orchestrator tells the later agent to start the wait. The earlier task can go back to a state before awaiting_work_review while the later agent waits. Then the later orchestrator tells the later agent to stop waiting. Then the hold rule applies again, and the later task stays in awaiting_work_review. On 2026-10-15, #123 went from reviewed to refining while #168 waited. If the earlier task is in failed, quota_blocked or interrupted when the hold starts or during the hold, the later orchestrator tells the user. The hold stays until the user decides. When the issue of the earlier ticket is closed, or when the earlier task is in landed, finishing or finished, the later orchestrator tells the later agent to continue as the bullet "When the issue of the earlier ticket is closed" says. On #129, a wait of 60 minutes ran out while the earlier task #95 stayed in awaiting_plan_review.

The stuck-task rule

This rule covers a landing order of the overlap rule, after the later agent reports that it stopped waiting. The orchestrator reads the state of the earlier task again with tasker show <issue>. If the state is the same as the start state, the orchestrator asks the user. If the start state is unknown, or if tasker show <issue> fails, the orchestrator also asks the user. The user can swap the landing order, postpone the earlier ticket, or tell the later agent to wait again. The orchestrator does not tell the later agent to wait again without the user. If the state changed, the orchestrator can tell the later agent to wait again, and it tells the user. If the new state is before awaiting_work_review, the hold rule applies instead of a new wait. The stuck-task rule does not cover a later agent under the hold rule, because that agent started no wait and has no 60-minute limit. On #101, the later agent waited two hours, in two waits of 60 minutes, for #34 of another milestone. During that time, #34 stayed in awaiting_plan_review.