---
name: roll-loop
license: MIT
allowed-tools: "Read, Glob, Grep, Write, Edit, Bash(git:*), Bash(cat:*), Skill"
description: "Load when configuring, explaining, or operating Roll session-driven backlog execution loop that takes Todo work and dispatches US/FIX/REFACTOR items."
---
# Roll Loop

This hub keeps the routing boundary, hard gates, and execution skeleton in the initial context. Load the heavier runbook only when the task actually needs the detailed contract.

## Load

Load when configuring, explaining, or operating Roll session-driven backlog execution loop that takes Todo work and dispatches US/FIX/REFACTOR items.

## How It Runs

The loop runs **because someone started it**. `roll loop go` takes the next eligible
card, delivers it, and moves on. There is no scheduler: nothing starts a run that an
owner did not ask for, and between runs nothing advances.

A run does outlive the terminal — by default `go` puts the worker in a detached tmux
window, so closing your window stops you watching, not the run. What ends a run is its
own scope: the cards finishing, `--max-cycles` / `--for`, the dead-loop breaker,
`roll loop pause`, or killing the tmux session. `--no-tmux` keeps it in the foreground.

`roll loop pause` stops autonomous card selection within a session; `roll loop resume`
releases it. A tripped correction breaker pauses too. An explicitly-scoped one-shot
(`roll loop go --cards <id>`) still runs while paused — the owner named that card on
this invocation, so it is their decision, not autonomous progress.

Continuous progress never bypasses pause, route, evidence, Evaluator, or
release gates.

## When Not to Use

- One-shot story execution by a human agent; load roll-build or roll-fix.
- Architecture scan; load roll-.dream.

## Read On Demand

- Read [the full contract](references/full-contract.md) before executing the workflow end to end, recovering from failures, or checking exact output templates.
- Keep this hub in context for trigger boundaries and hard gates.

## Workflow Skeleton

1. Read BACKLOG for Todo items.
2. Route US/FIX/REFACTOR to the right skill.
3. Run bounded cycles with fresh context.
4. Persist events, runs, alerts, and status.
5. Pause on repeated failure.

## Delivery Lifecycle (US-DELIV-001..007)

最后一公里 = 一个 reconcile 闭环，没有任何独立守护进程。

- A cycle ends at publish: branch pushed + PR opened → `awaiting_merge`; the loop is released to pick the next card. Nothing blocks on merge.
- The **Delivery Reconciler** advances delivery opportunistically — cycle boundaries, read paths, and explicit `roll loop reconcile`: CI-green PRs are merged self-drive (`gh pr merge --squash`); merged PRs reconcile from `main` (L1 PR-state / L2 patch-id) to `delivered`; external / manual merges reconcile to `delivered_external` (first-class); insufficient evidence stays `awaiting_merge` — never misjudge.
- Reconcile is idempotent and crash-safe: any single `roll` invocation can advance the truth.

## Hard Gates

- Loop never cuts a release autonomously.
- Fail-loud and PAUSE beat silent fallback.

- NEVER run `git push` or `gh pr create` yourself inside a loop cycle: the RUNNER owns publish — it pushes the branch, opens the PR, and runs the attest/peer gates first. A self-published PR bypasses every gate (FIX-245: the runner adopts it and logs a discipline breach, but the gates have already been jumped). Finish your TCR commits and stop; publishing is not your step.
  循环内严禁自己 push/开 PR——发布由 runner 负责(先过闸再出门);自开 PR = 跳闸违纪。

## Gotchas

- Loop dispatches backlog items; it must not merge releases or bypass human-on-the-loop decisions.
- Fail-loud pause behavior is preferable to silent fallback when repeated execution breaks.

## Maintenance

- Description changes require updates in `route-cases/skills.json`.
- New observed failures should add a gotcha and the matching positive or negative route case.
- Heavy examples, templates, recovery paths, and deterministic snippets belong in `references/`, `assets/`, or `scripts/`, not in this hub.