The delivery cycle in depth

The in-depth companion of the delivery workflow: what the cycle is, how each stage works, which realization runs it, how it is configured, and how unattended work flows through it.

This page is a map, not a second copy of the territory. Exact argument names, refusal identifiers, schema fields and script paths live in the owning skill, script or guideline and are linked from here, so a change there cannot leave this page stale on that fact. Where this page and an owner disagree, the owner wins and this page is the bug.

Contents

1. The cycle and its authority
2. The stages, one by one
3. Three realizations, and which to use
4. Profiles: engine, model, effort, context per stage
5. Cycle Hooks
6. The merge stage and the merge gate
7. Host adapters: PM tool and code host
8. Automation as one whole
9. Timeouts, stalls and retries by surface
10. Where to go next

1. The cycle and its authority

A delivery cycle drives ONE card to a review-approved pull request, and optionally to a merge. It is a state machine with two entries and two stage sequences:

Figure: two ways in (a fresh card at the top, a PR with findings on the left), one loop, and every exit is a human decision point.

One rule authority. cycle-state.mjs alone decides what is due: stage order, retry budgets, round caps, resume after an interruption, and per-stage context freshness. Every realization asks it "what is next?", dispatches exactly that stage, forgets everything but the answer, and asks again. No coordinator, skill or driver holds a cycle rule of its own, which is why the three realizations in section 3 behave identically.

State is files, not memory. Each stage publishes a handoff under the run directory; the next question is answered from those files. A cycle interrupted at any point resumes from its first incomplete stage.

Independence is structural. The agent that implements never reviews; the agent that writes a finding's failing test is never its fixer; the validator never repairs. Only independent review activities are recorded as evidence.

Operational detail: the pair-workflow-cycle skill (in-session coordinator, #486), the cycle-state.mjs script, and the merge stage (#490) in section 6. The design is recorded in ADR-024.

2. The stages, one by one

Every stage is a skill run by one role. cycle-state.mjs also decides whether the stage gets a fresh agent (the default) or resumes the previous agent of the same role (reuse); resuming is admitted only inside one role, never into validate or verify, whose whole value is independence.

Each subsection below says what the stage is for, who runs it, what it reads and produces, when it is skipped, and how it ends. The what and why is here; the argument lists are in the skills.

implement

Figure: implement asks the state script first and publishes last; everything between is test and code, one acceptance criterion at a time.

• For: turning a refined card into verified commits and exactly one PR, written test-first, for each acceptance criterion a test that would fail without the behavior, then the code.
• Who / context: the implementer, fresh.
• Reads → produces: the card and the base branch → commits in the story worktree, a checkpoint, the PR (created or updated, never duplicated), and the stage handoff.
• Self-review: the implementer reviews its own diff against the acceptance criteria and fixes what it finds, and records nothing of it, so the verifier judges the result without the author's conclusions in front of it.
• Skipped when: a PR already exists for the card (the cycle enters at verify).
• Ends: success: handoff published, next is verify; a red gate still publishes the PR and routes one retry on the same base; a second red gate stops the cycle.

verify

Figure: verify pins the PR head before reading anything, so the verdict is about exactly one commit.

• For: an independent judgment of one exact PR head: that the sealed evidence is intact, that every acceptance criterion has a test proving it, that prior findings are resolved, and that the adopted risk-tier passes find nothing blocking.
• Who / context: the reviewer, always fresh, read-only on code. It sees the card, the PR and the code, never the implementer's checkpoint.
• Reads → produces: PR head, card, handoffs → one review with stable finding ids, a verdict and the head it reviewed, published idempotently.
• Skipped when: never. Every path to a merge or a ready PR passes through it, and a moved head needs a new one.
• Ends: approved, the cycle advances to merge (or stops ready-for-merge); blocking findings at or above the project's floor, a remediation round starts at prepare; a finding only a human can settle, escalate.

prepare

Figure: prepare turns findings into failing tests before any production edit, and the author is never the one who will fix them.

• For: turning each blocking finding into an executable acceptance contract (a failing test that proves the finding at the unfixed head, plus controls that must keep passing) before anyone touches production code.
• Who / context: the test author, fresh on the first round and eligible to reuse itself across rounds. It writes tests and fixtures only, and is never the fixer.
• Reads → produces: the findings of the last verify → test files and the contract handed to validate.
• Skipped when: a fresh card with no findings; the cycle never starts here without a review having found something.
• Ends: a contract ready for validate; or a typed refusal (the finding cannot be proven, must be split, is stale) that stops or escalates the group.

validate

Figure: validate reproduces every witness against the unfixed base; one typed rejection lists every gap, or the seal lands.

• For: an independent check that the contract really discriminates (each witness fails at the unfixed head for the intended defect, each control may pass) and a deterministic seal: the tests become an immutable snapshot commit the fixer cannot alter.
• Who / context: the contract validator, always fresh. It never repairs a contract.
• Reads → produces: the contract and the base → either one typed rejection listing every gap found, or a sealed snapshot.
• Skipped when: never inside a round: it is the gate between prepare and green.
• Ends: sealed (next is green; rejected) back to prepare for a bounded number of repairs, then the cycle stops.

green

Figure: green starts from the seal, may touch only the allowed scope, and ends with the same witnesses now passing.

• For: making the sealed tests pass by changing production code only inside the contract's allowed scope, then updating the existing PR.
• Who / context: the implementer as fixer, fresh or resumed within its own role. A sealed test is untouchable: a gap in the contract is reported, never patched around.
• Reads → produces: the seal (discovered from Git, never trusted from a prompt) → commits above the seal, the updated PR, an evidence ledger.
• Skipped when: never inside a round.
• Ends: success (next is verify; an approved test that still fails) one retry on the SAME seal; a fixer that needs a human decision posts its escalation itself.

merge

Figure: merge re-reads every signal from the host before acting; any signal that is not success parks the card instead.

• For: executing the merge of a review-approved PR, only when the project opted in. Detail in section 6.
• Who / context: nobody: it is a script, not an agent dispatch.
• Reads → produces: freshly re-read signals → a merge and a closed story, or a park with a comment on the card naming the failing signal.
• Skipped when: the project did not opt in (the default): the cycle stops ready-for-merge and a human merges.
• Ends: merged, merged with closure unfinished, or parked.

Where a human decides

The cycle never decides these for itself: decide records a maintainer's answer to a finding that needs one (the cycle leaves escalate without re-running anything); supersede sets aside an unvalidated attempt so the stage can be redone; the explicit approval of a high-risk PR (/approve) is a recorded human act the merge stage requires. The recovery paths, including a stale card lock and custody after a base merge, are in the pair-workflow-cycle skill.

3. Three realizations, and which to use

One cycle, three ways to turn its crank. They differ in who dispatches the stages, never in what the rules are.

Choosing: three questions, in order:

1. Are you in a harness with a subagent primitive, working one card with a human nearby? Use the in-session coordinator. It binds the primitive by probing the toolset, not by product name, and refuses cleanly when none is present: the console driver is then the fallback.
2. Is there no interactive session (a shell, cron, CI, a daemon) or do you want an engine the session cannot be? Use the console driver. It works on any engine and has no dependency on a vendor's orchestration tool. --parallel N is its fan-out (#491): one pair-cli run --card process per allowed card, bounded by dependencies, the mutex analysis and ## Max Parallelism, with one card failing never aborting the others.
3. Are you on Claude Code and want a whole epic's cards in parallel with the orchestration inside the session? Use the Claude parallel batch. Elsewhere the same work is the console driver's fan-out.

The in-session coordinator and the console driver run the cycle's hooks and profiles; the Claude batch runs no cycle hook (section 5). The console driver and the loop also re-select cards over time, which a one-card in-session run does not.

Links out for the mechanics: the pair-cli run reference, the pair-loop skill, and the Max Parallelism section for the ceiling.

4. Profiles: engine, model, effort, context per stage

A workflow profile declares which engine, model, effort and context policy each stage uses (a cheap model with a resumed session for prepare and green, a frontier model with a fresh session for validate and verify) without touching any skill or script. The schema, the cascade, the model classes and the refusals are owned by workflow-profiles.md (#488); both coordinators resolve it through one resolver.

Shape (abridged: the full field table is in the owner):

{
  "name": "cheap-green",
  "defaults": { "engine": "claude", "model": "by-tier", "effort": "medium", "context": "fresh" },
  "modelClasses": { "cheap": "<cheap-model-id>", "balanced": "<balanced-model-id>", "frontier": "<frontier-model-id>" },
  "stages": {
    "prepare": { "model": "cheap", "context": "reuse" },
    "validate": { "model": "frontier" },
    "green": { "model": "cheap", "context": "reuse" },
    "verify": { "model": "frontier", "effort": "high" }
  }
}

Cascade: resolved once per run, highest first:

1. an external workflow-config file, used verbatim;
2. a named profile passed for this invocation;
3. the project's declared default profile in pair.config.json;
4. the KB default: the engine's own model, default effort, fresh on every stage.

Within a profile, a stage entry overrides only the fields it declares, then defaults, then the KB default. With nothing configured, the cycle runs exactly as it did before profiles existed.

Worked mixed-model example. The profile above runs the work that needs breadth at low cost and the work that needs independence at high capability:

Because prepare and validate apply to remediation rounds only, a profile must not assume every stage runs on every card: a fresh card runs implement and verify first.

context is validated, not trusted. A stage entry asking reuse into a stage where the cycle's transition table forbids it (validate and verify above all) is rejected at load, never accepted and silently overridden at dispatch. The table is cycle-state.mjs's (the rule is in workflow-profiles.md).

Audit, not input. The resolved profile's name and content hash are recorded in every handoff but excluded from the inputs that invalidate evidence: swapping a profile between invocations re-validates nothing.

5. Cycle Hooks

## Cycle Hooks in tech/automation.md declares deterministic commands around the cycle, fail fast on a bad toolchain, realign generated mirrors before a stage, notify on an outcome, alert on a stop (#489). The schema, the per-command timeout, hook-name rules and the fail-safe default are owned by automation-policy.md.

The hooks are executed by the coordinator (the in-session skill or the console driver) never by the stage's own agent, through one shared executor, so the two cannot drift. The Claude parallel batch has no shell and runs none.

Blocking vs logging: the distinction that matters:

Every hook point and its typical use:

Stage hooks run in the story worktree, the tree the stage works on; cycle-level hooks run in the main checkout. A hook name is a pattern over the stage ids cycle-state.mjs enumerates, so a stage added later gets its hooks with no schema change; a typo is a warning at load, not a stop.

6. The merge stage and the merge gate

The merge stage (#490) is the cycle's last, and it is opt-in per project. A review-approved PR stops ready-for-merge and a human merges it: that is the default, and it is the fail-closed posture.

The default is no automatic merge. The merge gate of ## Autonomy is always unless written otherwise, and always parks every review-approved card for a human. A maintainer opts in with until: merged plus merge: never (every selected card may merge) or merge: when; has: …; lacks: … (a card matching the condition escalates instead). The legacy ## Auto-Advance section is translated to the same gate by autonomy-policy.mjs ((none) is always, a tier is when; lacks: <tier>) and keeps working (Autonomy).

What the stage re-verifies, on freshly read signals, before any merge: the conjunction that is the merge-allowed synthesis (pr-states.md):

• the card's risk tier, re-read (a mid-run raise parks the card);
• the PR's current remote head is identical to the head that was reviewed (a moved head is never merged);
• the pair-review check is success on that head;
• the pair-explicit-approval check is success on that head (below the highest-risk tier it passes by itself; at that tier it requires a recorded human approval);
• every OTHER CI check on that head (check runs and commit statuses, read through the code-host adapter) is success: a failed one refuses the merge (ci-not-green, halted), a still-running one parks it awaiting the build;
• the tier's gate set is green.

Anything unreadable, moved or not success parks the card with the failing item named: it is never merged. On success the merge follows merge-and-cascade: the adopted strategy, story close, parent cascade with read-back, branch deletion.

Relationship to the other declarations. The merge gate answers which cards may merge unattended; it is a switch, never a gate list, and it does not restate what "green" means: that is the quality model's per-tier table. The merge stage enacts it. Every realization reaches the stage through the same script, so the rule has one owner and pair-loop itself holds no merge call. Detail: the Autonomy sections.

7. Host adapters: PM tool and code host

The cycle scripts never call a host CLI themselves: they call the adapter the project's way-of-working.md binds, so every host-specific spelling (binary, arguments, URL shape, label and check vocabulary) lives in one file (#492, ADR-026). The PM tool (cards) and the code host (pull requests) are resolved independently.

The interface is eight methods:

A further optional set of primitives serves scope decisions and state lookups; omitting one fails only the feature that needs it, typed, naming the method.

Shipped adapters: GitHub and Azure DevOps. A filesystem host is the extension guide's worked example.

Adding a host is one new file plus one declaration, never an edit to an existing adapter or to cycle-state.mjs. The validated step-by-step guide, including the file layout and the checks an adapter must pass, is the Host Adapter Extension Guide. Credentials are never read, stored or printed by an adapter: the host CLI authenticates itself.

8. Automation as one whole

Unattended work is the cycle plus five things around it: a trigger, a dispatch, gates, safety rails, and a way out.

Figure: the cycle sits in the middle; the trigger and the host adapter feed it, the gates and rails bound it, and the way out is always a parked card or a human.

1. The trigger. A tracker event (a label added to a card) reaches the host adapter, the thin per-host piece that holds the credentials the trigger runs under. It calls the dispatcher; it carries no cycle rule. See github-automation.md and #492.
2. The dispatch. The console driver (or pair-loop) reads tech/automation.md and maps the card's tags through ## Workflows (automation-policy.md). A tag is an opaque routing key; an untagged card is never routed by tag. With no mapping, the card's own Definition of Ready decides: a Ready card with a task breakdown enters the cycle, a card with a PR enters at verify.
3. The gates. The ## Autonomy filter bounds --autonomous runs: a card without a listed label is skipped as ineligible, and --approve-ineligible lets exactly one run through. Unattended runs never start a preparation skill unless the prepare gate says so (always by default: a human prepares). A card that cannot be read is a clean skip.
4. The safety rails. An exclusive per-card lock (no timeout; SIGTERM and SIGINT release it, so re-running the same command continues the run); an audit trail, start, skip, end, with the start also printed as a DISPATCH-RECORD: line the adapter can post on the card; the dispatch cap; and ## Max Parallelism as the ceiling on fan-out. An escalation condition in ## Autonomy stops the cycle with one marker-keyed comment on the card.
5. The way out. The merge gate of ## Autonomy and the merge stage (section 6). By default the run ends ready-for-merge and the merge stays a human decision.

A reader can predict any card's outcome by walking these in order: is it mapped or Ready? eligible? unlocked? does a prepare or escalation condition fire? has the project opted into merge for its tier?

Worked example: a label to a PR ready for merge, no one present

Setup: ## Workflows maps auto-dev to the cycle; ## Autonomy declares filter: risk:green and leaves the merge gate at always. Card 123 is Ready, has a task breakdown, and carries risk:green.

Had the policy declared until: merged and merge: never, step 6 would have run the merge stage: re-read the signals, merge pinned to the reviewed head, close the story and cascade to its parent, or park with a comment naming the signal that failed.

The mechanics of every step are in the owner links of sections 1–7; the walk-through as a hands-on tutorial is on the docs site (Automated development).

9. Timeouts, stalls and retries by surface

What bounds a stage that hangs, and what is retried, differs by who drives the cycle. The rules of the cycle never change; the enforcement does. Single owner of this table, other pages link here.

10. Where to go next

Known limitation: a link check catches a broken anchor, not a semantic change in a linked owner. If an owner's behavior changes shape, this page is updated in the same change.

Next: Lifecycle modes, who drives the cycle and on which assistant.