What is next

When an agent calls claim_next with no arguments, it is given the next card that is ready. This page says what ready means and what next means.

Ready

A card is ready when all three of these are true:

1. It is to do: not claimed, not done, not orphaned, not deleted.
2. Every card it depends on has cleared. See below for what clears a dependency.
3. None of the exact files it names is held by a card that is being worked on. See Scope and collisions.

Next

Among the cards that are ready, the next one is chosen by:

1. Version. Cards with a version label come before cards without one, in the order of the labels. Labels are compared as text, so 1.10 sorts before 1.2.
2. Position on the board. Within a version, the card nearer the top goes first. You set this by dragging cards on the board.

Passing version to claim_next narrows the choice to that label. It does not change the rules.

Passing card claims that card, if it is ready. Naming a card does not let an agent jump its dependencies: a card that is not ready is refused, with the reason.

Dependencies

There are two kinds, and they clear at different moments.

• Declared. You or an agent said one card needs another, with depends_on when the card was made or with link_cards later. It clears when the other card is done.
• Added by Docket. Docket ordered one card after another because both change the same file. It clears when the other card is done and merged. See Scope and collisions.

Either kind is removed with unlink_cards. An order Docket added and you removed is not added again.

Two agents at once

Two agents asking at the same moment get two different cards. Claims within a project are made one at a time, so the second is decided after the first has taken its card and its files.

When nothing is ready

claim_next says so, and says why:

no cards ready: 2 blocked on dependencies, 1 waiting on files held elsewhere, 0 orphaned and needing repair, 1 in progress

The four numbers are the cards waiting on an unfinished dependency, the cards waiting on a file another card holds, the orphaned cards, and the cards being worked on. A card waiting on both a dependency and a file is counted once, as waiting on the dependency. What to do about each is in Troubleshooting.