Tracer bullet: a linear Spec run to a ready Spec PR #141

Parent

#139

What to build

The tracer bullet for Spec runs: thirdshift <Issue URL> on a Spec works through its Tickets one at a time, in dependency order, and ends with a ready Spec PR.

• Detecting a Spec. After preflight, thirdshift reads the issue's sub-issues with one GraphQL query (number, state, labels, whether it has sub-issues of its own, and its blockedBy issues with their states). Any sub-issue, open or closed, makes the issue a Spec. An issue with no sub-issues is an ordinary Run, unchanged.
• Spec branch. Chosen like any Issue branch for the Spec (issue-<n>, or the numbered form, with an existing one meaning continue per ADR 0002), branched off the Base branch and pushed to origin before any Ticket starts.
• Ticket Runs. Each ready Ticket (open, every blocker closed; lowest number first) runs as a child process of the same thirdshift binary: a Merge run on the Ticket's Issue URL from the same Launch directory, told through a hidden argument (not in help) to use the Spec branch as its Base branch and to send no Run notification and do no launch.pull of its own. Closed Tickets count as done. The child's stderr is relayed with a #<n>: prefix, and the Spec run adds its own lines (starting #<n>, #<n> landed).
• Preflight (Origin match, Base branch, User config, notification checks, launch.pull) runs once in the Spec run before any Ticket starts.
• The Spec PR. Once every Ticket has landed, thirdshift opens the Spec PR from the Spec branch into the Base branch, titled from the Spec, with Closes #<spec> in its body, marks it ready for review, prints its URL on stdout and exits 0.
• Harness. The fake gh serves a Spec's sub-issues, labels, nested sub-issues and blockedBy links through the GraphQL query thirdshift uses, with a helper to set up a Spec and its graph. The fake claude picks a session's script by the issue in its prompt and that issue's session count, not by global call order, with a helper for "the agent does X for Ticket #n".

Later Tickets add the Spec review, the Repair loop on the Spec PR, parallelism, failures, the draft Spec PR, reruns, notifications and interrupts. In this Ticket a Ticket that fails may simply end the Spec run with exit 1.

See ADR 0006 and the glossary's Spec run terms.

Acceptance criteria

• An issue with no sub-issues still runs as an ordinary Run, exactly as before
• A Spec with a linear chain of Tickets runs each Ticket in dependency order, each a Merge run whose PR targets the Spec branch and is merged into it
• Each Ticket's Issue branch branches off the Spec branch, and its prompts name the Spec branch as the base
• Closed Tickets are not run
• The Spec branch is pushed before the first Ticket starts
• When every Ticket has landed, a Spec PR from the Spec branch into the Base branch exists, is ready for review, and its body contains Closes #<spec>
• The Spec run prints the Spec PR URL on stdout and exits 0
• Relayed Ticket lines on stderr carry the #<n>: prefix
• Ticket Runs send no Run notification and don't fast-forward the Launch directory
• The hidden argument doesn't appear in help
• Tests drive the compiled binary through the end-to-end harness, with the fake gh and fake claude extended as described

Blocked by

None (can start immediately)