Pass over a Spec that has no Ticket a Spec run could start #884

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: A Pickup run passes over a Spec that has no Ticket a Spec run could start, so it makes no Claim, push or failure email for a run that can only fail.

Current behavior:
A Spec is a Ready issue as long as at least one of its Tickets is open. Pickup skips a Spec only when every Ticket is closed (the "every Ticket is closed" pass-over reason). A Spec whose open Tickets are all Unready is still taken. One example is a Spec whose last open Ticket is needs-info. The Spec run then claims the Spec (in-progress), pushes the Spec branch, finds nothing it can start, and ends as a Failed spec run with Tickets not done: #<n> and #<n> unready: labelled needs-info. The Claim stays on, so the Spec looks taken, and the operator gets a failure email for a run that could never do anything.

Seen on Educational-Travel-Adventures/tourbot#880 on 2026-10-20: its only open Ticket, #883, had been needs-info since 2026-09-04. So any Pickup pass since then would have failed the same way, and only the Claim kept later passes from repeating it.

Desired behavior:
When choosing a Ready issue, a Spec with no startable Ticket is passed over with a line on stderr naming why each open Ticket can't run. For example: #880 has no Ticket that can start: #883 labelled needs-info.

A startable Ticket uses the same rule a Spec run uses to pick its next Ticket, as if nothing were running yet. The Ticket must:

• be open;
• be in the Spec's repository;
• have no sub-issues;
• have no open blocker;
• not be an Unready Ticket (ready-for-human, needs-info, wontfix or needs-triage).

Define that rule once and use it in both places, so Pickup and the Spec run can't disagree.

• A Spec whose Tickets are all closed keeps its existing "every Ticket is closed" reason. That check comes first.
• The new check applies whether or not the Spec was started before, including a Spec handed back with ready-for-agent, because a Spec run on it would also fail.
• A Spec with at least one startable Ticket is still a Ready issue. Its other Tickets are handled by the Spec run as they are today.
• Once a Ticket becomes startable (someone takes its Unready label off, or its blocker closes), a later Pickup pass takes the Spec, subject to the other Ready issue gates.
• Architect runs use the same Ready issue search, so the rule applies there too.

Key interfaces:

• The Ready issue pass-over Reason enum gets a new variant for "no startable Ticket", which carries enough to name each open Ticket and why it can't start.
• The per-Ticket facts the pass-over check needs (open, repository, labels, open blockers, sub-issues) are the ones the Spec run's Ticket board already reads. Pickup currently reads only whether each sub-issue is open, so this adds reads, but only for Specs that pass every earlier gate.
• docs/guide.md's Ready issue list and GLOSSARY.md (Ready issue, and a new term for a startable Ticket if the agent defines one) are updated to describe the new gate.

Acceptance criteria

• A Pickup run passes over a Spec whose only open Ticket is labelled needs-info. It makes no label change and pushes nothing, and stderr names the Spec, the Ticket and the label.
• A Pickup run passes over a Spec whose open Tickets are all blocked by an open Unready Ticket, or by an open issue outside the Spec, and stderr names why each Ticket can't start.
• A Pickup run still takes a Spec with one startable Ticket and one Unready Ticket.
• A Spec whose Tickets are all closed is still passed over with "every Ticket is closed", not the new reason.
• A handed-back Spec (in-progress removed, then ready-for-agent applied) with no startable Ticket is passed over.
• After the Unready label comes off the Ticket and the settling window has passed, the next Pickup pass takes the Spec.
• Pickup's check and the Spec run's choice of next Ticket use the same rule, defined in one place.
• docs/guide.md lists the new Ready issue condition.

Owning area

Pickup's Ready issue gates for Specs

Out of scope:

• How a Spec run that does start reports Tickets still waiting on a human: a "waiting" outcome versus a failed one. That is Distinguish Spec runs waiting for the Day shift from failed Spec runs #585.
• Comments or labels on the issue when a Claim ends: Say which machine holds a Claim #833.
• Changing which labels make an Unready Ticket.
• Taking off, or putting back, any triage or in-progress label automatically.