A ticket's statuses and labels

Orion keeps its state on the ticket itself, as labels, so anyone looking at the tracker can see what Orion is doing with a ticket and what happens next.

The watch decides what to do from labels alone. Orion also moves the status (To Do, In Progress, In Review, Done) so a sprint board reads correctly; a workflow without one of those statuses gets a warning and the run carries on. A ticket counts as finished when its status is in the tracker's Done category, whatever the workflow calls it: Done, Closed, Cancelled, Won't Do.

The labels

Queue state

A ticket carries at most one of these at a time. They are the labels the watch acts on.

Label	Means	Put on by	Taken off by
ORION	Work is requested. The name is tracker.queue_label in orion.json; ORION is the default and the one a watch spanning projects expects.	You; orion queue add KEY; orion plan (on every story and task an agent can do); an automatic retry; a run handed back because the tracker or a credential failed	The claim, when a watch (or orion work KEY) starts the ticket; orion queue remove KEY
orion-working	An agent is on it. This is the lock: no second run may start the ticket while it is there.	The claim	Whatever ends the run: hand-off to orion-ready or orion-ci-wait, failure, a hand-back to the queue, a forced stop, or the watch finding the claim abandoned
orion-ready	The agent finished, QA passed, the branch is pushed, and nothing is running. It waits for the next integration batch. It is not a claim and holds no worker slot.	The end of a run when batch integration is on; the watch, when a run finished but the label did not follow	Landing; the batch convicting it (it becomes orion-failed)
orion-ci-wait	A pull request is open for this ticket alone and its CI is running. Used when batch integration is off.	The end of a run when batch integration is off	Merge (landing); the pull request being closed unmerged; CI failing (it becomes orion-failed)
orion-failed	It needs attention, or an automatic retry.	A run that failed or was blocked; red CI; the done-check finding the work does not meet the ticket; a batch convicting it	An automatic retry; orion queue add KEY --reset

If an interrupted write leaves two of these on one ticket, Orion reads the more urgent: orion-failed over orion-working over orion-ci-wait over orion-ready over the queue label.

Who holds it: orion-stage-<actor>

Beside orion-working, a stage label names the agent holding the claim: orion-stage-implementer, orion-stage-qa, and so on. It carries the agent's id, so renaming an agent does not leave stale labels behind. It is for people to read: nothing in Orion decides anything from it. It comes off with orion-working.

Description rewrites

An agent never overwrites a ticket's description directly, since git keeps no copy of what the tracker held. It posts the before and after as a comment and adds orion-desc-pending. To decide, add orion-desc-approved or orion-desc-rejected to the ticket; Orion applies or drops the change, then removes orion-desc-pending and your decision label.

Created by a plan: orion-spec-<feature>

Every epic, story and task orion plan creates from a spec-kit task list carries orion-spec-<feature>. It marks identity rather than state: a re-run of orion plan uses it to find what the last run made and link to it, so nothing is created twice.

The journey

Planning puts the work in the queue

orion plan KEY creates the Epic / Story / Task tree and puts ORION on every story and task an agent can do. A task whose description has a line starting with HUMAN is created but never queued. Where the project uses releases, a ticket must also sit on an open version before the watch will claim it.

Claimed

The watch picks the next queued ticket whose dependencies have landed. The claim swaps the queue label for orion-working in one write, adds the stage label, assigns the ticket, and moves it to In Progress.

Worked

Routing picks the agent, the agent implements, QA tests and returns findings for fix rounds, and the branch is pushed. The stage label follows the claim from agent to agent.

If the run cannot start because the tracker or a credential failed, the ticket goes back: ORION returns, orion-working comes off, and the status returns to To Do. This does not count as a failure or use up a retry.

If the ticket turns out to need no change at all, Orion clears every label it owns, moves it to Done, and comments why.

Waiting to land

With batch integration on (the default for projects orion plan creates), the run ends with orion-ready and the ticket moves to In Review. The next batch assembles every ready branch, runs CI once for the set, and lands it. If the batch is red, Orion isolates the ticket that broke it; that ticket becomes orion-failed and the rest land.

With batch integration off, each ticket opens its own pull request, ends with orion-ci-wait, and moves to In Review. A red build goes back to the agent first when ci.auto_fix is on. A pull request closed without merging loses orion-ci-wait and keeps its status for a person to set.

Merge approval is covered in Slack and approvals.

Landed

Orion clears every label it owns and moves the ticket to Done. A story also closes its sub-tasks, except HUMAN ones: those stay open, and the landing comment names them.

Failed

orion-failed replaces whichever state the ticket was in. When the work branch moves past the point the ticket failed on, the watch requeues it on its own (ORION back on, orion-failed off, status back to To Do), at most twice; after that it is named under NEEDS YOU. What to do then is in the recovery runbook.

Stopped

A second Ctrl-C on orion watch kills running agents and puts their tickets back in the queue: orion-working and the stage label come off. See how a watch stops.

Claims nobody is holding

The watch checks every orion-working ticket on each pass:

• A ticket someone moved to Done by hand keeps the lock until the watch clears it.
• If the process holding the claim is gone, the watch takes the label off and tells you to re-label the ticket with ORION.
• If the holder is alive but the ticket's own log shows its run finished, the watch moves the ticket to orion-ready so the integration queue can see it.

The design of claims is in ADR 0032.

What you can do from the tracker

You want to	Do this
Ask for work	Add ORION, or orion queue add KEY
Take work back off the list	Remove ORION, or orion queue remove KEY (refused while an agent or CI owns the ticket, or it waits for a batch)
Retry a failed ticket now	orion queue add KEY --reset
Steer an agent	Comment on the ticket
Decide a description rewrite	Add orion-desc-approved or orion-desc-rejected
See where everything is	orion queue

danger

Never remove orion-working from a live ticket

The label is the lock. Removing it from a ticket an agent is still working lets a second run start on the same ticket.

When a ticket is failed, held or stuck, see the recovery runbook.

Statuses and labels here are named in Jira's terms, since Jira is the tracker Orion's native path supports today.