Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .docket.example.yml
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,14 @@ run:
# scope: any layer
max_attempts: 2

# max_consecutive_halts — how many changes picked from the queue may halt in a row before a
# tracked implement-next loop stops. A halted change always waits for a person; under this limit
# the loop moves on to the next build-ready change instead of ending the drain. 2 by default;
# 1 stops the loop at the first halt. A clean build resets the count, and so does
# `docket run reset-halts`. A whole number of 1 or more.
# scope: any layer
max_consecutive_halts: 2


# ═══ review — what implement-next fixes after review ══════════════════════════════════════

Expand Down
3 changes: 3 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,9 @@ broken: surface it, never rebuild the run tracker by hand.
or dispatch `docket-implement-next` again with the explicit change id, the continuation id, and the
same key, and run `run.verdict` with `<key>` again. Every `run-stop` and every
`run-observe` forbids re-dispatch; `run-halted` means a human is needed.
`run-next <key> run-halted <id>` also forbids re-dispatching that change; only a loop driver
(`/loop`) may go on to its next run, with a fresh `run.start`; a single dispatch stops, as on
`run-stop`.

## Stopping a dispatched run — there is no automatic Stop button

Expand Down
3 changes: 3 additions & 0 deletions cursor-rules/run-tracker.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ broken: surface it, never rebuild the run tracker by hand.
or dispatch `docket-implement-next` again with the explicit change id, the continuation id, and the
same key, and run `run.verdict` with `<key>` again. Every `run-stop` and every
`run-observe` forbids re-dispatch; `run-halted` means a human is needed.
`run-next <key> run-halted <id>` also forbids re-dispatching that change; only a loop driver
(`/loop`) may go on to its next run, with a fresh `run.start`; a single dispatch stops, as on
`run-stop`.

## Stopping a dispatched run — there is no automatic Stop button

Expand Down
20 changes: 20 additions & 0 deletions docs/concepts/run-tracker.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ verdict, not the worker's report, says what may happen next.
├─ run-continue ────► the same attempt is still working: resume it or
│ dispatch again with its continuation id;
│ same key, spends no retry
├─ run-next ────────► this change needs a human; never re-dispatch it.
│ A loop may start its next run (fresh run start);
│ a single dispatch stops
├─ run-stop ────────► no re-dispatch; run-stop … run-halted means the
│ change needs a human
└─ run-observe ─────► an unattributed read (no key); never authorizes
Expand Down Expand Up @@ -94,6 +97,21 @@ verdict, not the worker's report, says what may happen next.
again with the change id and the continuation id it names, keeping the
same key and spending no retry. Every `run-stop` and every `run-observe`
forbids a re-dispatch.
- **The halt count.** The tracker keeps one count per repository of
implement-next runs in a row that halted on a change picked from the
queue (no id, or a set of two or more ids — a loop, or a one-off
"implement the next change"). A halt on a named run or a resume never touches it.
While the count stays under `run.max_consecutive_halts` (default 2), such
a halt prints `run-next <key> run-halted <id>` instead of
`run-stop <key> run-halted <id>`: the halted change is never
re-dispatched, but a loop may start a fresh run for the next change. The
halt that reaches the limit prints `run-stop … run-halted` with a note
asking the person whether to reset the count. Only a clean build
(`run-done … run-complete`), named or picked, sets the count back to 0,
and so does `docket run reset-halts`, which runs only on the person's explicit yes, never on the agent's own. Each run
changes the count at most once, however often its verdict is read again.
The count lives in the repository's state folder, so every session and
worktree shares it.
- **Verifying a change** (`docket run verify --id <id>`) checks one
change's run against its postconditions — workspace and remote heads,
build evidence, the pull request, the plan and results files, the claim
Expand Down Expand Up @@ -176,6 +194,8 @@ blocks as `mutation-pending:<op>`.
than guessing.
- Only `run-retry-once` and `run-continue` authorize another dispatch;
every stop or observe line forbids it.
- A halt never re-dispatches its change: `run-next` only lets a loop start
a new run for the next change, and only the person resets the halt count.
- The verdict always exits 0; the decision lives in the report line, not
the exit code.
- A probe that cannot prove a process is alive is not evidence that it
Expand Down
40 changes: 37 additions & 3 deletions docs/guide/building-without-supervision.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,9 @@ whatever starts them keys on the outcome each run declares. Every run ends by de
- **halted** — something needs a human (an escalation, an invalidated design, a broken precondition).

A driver keys on these with one simple rule: **continue on `advanced` or `contended`, stop on
`drained` or `halted`.** The contract is deliberately driver-agnostic — a human re-issuing the
`drained` or `halted`** — except that a tracked loop carries on past `halted` when the run
tracker's verdict is `run-next` (see [When a change halts mid-drain](#when-a-change-halts-mid-drain)).
The contract is deliberately driver-agnostic — a human re-issuing the
plain request between runs satisfies it exactly as well as any automated driver, so nothing here
depends on a particular tool.

Expand All @@ -167,8 +169,8 @@ build work stays isolated and the driver's own context stays small:
A change on [hold](../reference/glossary.md#hold) is skipped by both drains; it is built only
when you name it alone.

Budget and iteration caps belong to the driver, not to docket, which does not reimplement them. The
one invariant the driver never breaks is the PR handoff: **a build run never merges.** A dependency
Iteration caps belong to the driver, not to docket, which does not reimplement them; the one limit
docket keeps itself is the halt limit below. The one invariant the driver never breaks is the PR handoff: **a build run never merges.** A dependency
on a `pr` change therefore only clears between drains, once its pull request is merged outside the
drain — you clicking Merge, or a separate close-out drain
([Landing changes safely](./landing-changes.md)) — and the change reaches `done`. A dependency on a
Expand All @@ -177,10 +179,42 @@ unattended; `/loop` behavior is version- and mode-specific. The bookkeeping that
launched it, whether it finished, whether a re-dispatch is allowed — is the run tracker, described in
[The run tracker and attribution](../concepts/run-tracker.md).

docket supports **one implement loop and one finalize loop at a time**; the two may run side by
side. A second implement loop is unsupported: both loops would share one halt count, and one loop's
clean builds would keep resetting the other's halts, so a broken setup would never reach the limit.

The run tracker follows a run only when the session starts it: with a plain request in the session
(for example "implement 412") or with `/loop docket-implement-next`. In Claude Code the
implement-next skill runs forked, so a typed command goes straight to the implementer and the
session never takes the turn that would start a tracked run.
A typed `/docket-implement-next` runs untracked.
It still builds to a PR, but if it stops partway there is no automatic retry, resume, or cancel, and
its outcome can only be read unattributed (`docket run verdict --unattributed`).

### When a change halts mid-drain

A halt usually concerns one change, such as a spec with a logical error that needs you. The change
is already marked as needing you on the board, so a tracked loop does not stop the whole drain for
it. When a run halts on a change it picked from the queue, the run tracker's verdict is
`run-next <key> run-halted <id>`: the halted change is never re-dispatched, and the loop starts a
fresh run for the next build-ready change.

A setup problem would halt every change the same way, so the run tracker keeps a **count of halts
in a row** and stops the loop at `run.max_consecutive_halts` (default 2). The halt that reaches the
limit prints `run-stop <key> run-halted <id>` with a note, and the session asks you whether to reset
the count. It never resets the count on its own; on your yes it runs `docket run reset-halts`, which
you can also run yourself at any time. Set the limit to `1` to stop a loop at its first halt.

- **Which runs count.** A run that picked its change from the queue: no id, or a set of two or more
ids. That includes a one-off "implement the next change". A halt on a named run (a single id) or a resume
never reads or changes the count; that halt stops as before.
- **What resets it.** A clean build (`run-done … run-complete`) sets the count back to 0, whether
the change was named or picked, and so does `docket run reset-halts`. Nothing else does: a run
that claimed nothing, including one that halted before its claim, leaves the count alone.
- **It outlives the loop.** The count is shared by every session and worktree of the repository.
A loop stopped at the limit leaves the count there until a clean build or a reset, so the next
loop stops at its first halt. A visibility switch moves the state folder, and the count moves with
it.
- **Halted runs stay active.** Each halted run stays active so it can be resumed. A visibility
switch refuses while any run is still active, and a loop can leave up to the limit's worth of
halted runs behind; cancel each (`docket run cancel --key <key> --reason <why>`) before switching.
4 changes: 2 additions & 2 deletions docs/guide/capturing-work.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ Every docket write re-renders the board, so there is no separate step to regener

One honest caveat about dependencies: chains serialize on the PR handoff. A change that depends
on another cannot start until that dependency is `done` — its pull request merged and the change
closed out, or, for a results-artifact dependency, the change completed. Unrelated changes drain freely in parallel around it — only the dependent one waits.
closed out, or, for a results-artifact dependency, the change completed. Unrelated changes keep draining around it — only the dependent one waits.

## Priorities, types, and dependencies

Expand All @@ -110,7 +110,7 @@ Three manifest fields shape *what gets built when*, and none of them is a hard s
that the second change would be built against code that is not there yet.

Record a dependency whenever one change genuinely needs another's merged code or decision. Leave
it empty when the two pieces of work are independent — that is what lets them drain in parallel.
it empty when the two pieces of work are independent — that is what lets them drain in any order.

## Capturing an idea: designed, rough, or discovered

Expand Down
8 changes: 6 additions & 2 deletions docs/guide/landing-changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,12 @@ in [Proving the build](./proving-the-build.md).
`docket-finalize-change` ends every run declaring one of four run outcomes — `advanced` (merged one
change and closed it out), `contended` (another writer got there first, nothing merged), `drained`
(nothing eligible in scope), or `halted` (needs a human). implement-next ends with the same four
words, so a single driver keys on both drains the same way: **continue on `advanced`/`contended`,
stop on `drained`/`halted`.** The built-in `/loop` is the recommended driver:
words. A finalize driver keys on them with one rule: **continue on `advanced`/`contended`, stop on
`drained`/`halted`** — on every `halted`. An implement-next loop differs in one way: it may carry
on past a halted change when the run tracker's verdict is `run-next`
([When a change halts mid-drain](./building-without-supervision.md#when-a-change-halts-mid-drain)).
docket supports one implement loop and one finalize loop at a time; the two may run side by side.
The built-in `/loop` is the recommended driver:

- `/loop docket-finalize-change` — closes out every eligible `implemented` change, **one merge per
iteration**, stopping on `drained`.
Expand Down
3 changes: 2 additions & 1 deletion docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ Each line is a pointer: the command, what its verbs govern, and where to read th
commands, and fast-forward the primary checkout to the integration branch. Verbs:
`docket repository --help`.
- **`docket run`** — track dispatched runs and verify a change's run from claim to its handoff
(implemented with a PR, or a completed results artifact).
(implemented with a PR, or a completed results artifact); also reset the count of implement-next
halts in a row (`docket run reset-halts`).
Verbs: `docket run --help`.
- **`docket schema`** — emit request/result payload schemas and allowed values (read-only,
repository-independent). Verbs: `docket schema --help`.
Expand Down
1 change: 1 addition & 0 deletions docs/reference/config-keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Each key has one scope:
| `build.test_command` | `""` (unconfigured) | any layer | the suite the build gate runs |
| `build.max_attempts` | `4` | any layer | full suite runs a build may spend, repairs included |
| `run.max_attempts` | `2` | any layer | attempts a tracked implement-next run may make on one change |
| `run.max_consecutive_halts` | `2` | any layer | halts in a row, on changes a loop picked from the queue, before the loop stops |
| `review.min_fix_severity` | `minor` | any layer | the lowest review-finding severity the fix pass repairs |
| `review.max_fix_tasks` | `10` | any layer | the most non-blocker fix tasks one fix pass dispatches |
| `reclaim.lease_ttl` | `72` | any layer | hours a claim on an in-progress change lasts |
Expand Down
12 changes: 11 additions & 1 deletion docs/reference/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -1138,6 +1138,7 @@ code or the child's prose.
|---|---|
| `run-retry-once …` | The only line that authorises another dispatch — once, same key, for the id and unmet conditions it names. Granted at most `run.max_attempts - 1` times. |
| `run-continue <key> run-waiting <id> <continuation-id> <phase>` | Non-terminal: the same attempt still owns work. Resume it with the continuation id; spends no retry. |
| `run-next <key> run-halted <id>` | The change halted and needs a human; never re-dispatch it. Printed only for a change picked from the queue while the halt count is under `run.max_consecutive_halts`. A loop may start its next run with a fresh `run.start`; a single dispatch stops. |
| `run-done …` | Finished (e.g. `run-done run-complete`). |
| `run-stop …` | Stop; no re-dispatch (e.g. `run-stop run-tracker-unavailable takeover-ambiguous`). |
| `run-observe …` | Observe only; no re-dispatch (e.g. `run-observe run-incomplete`). |
Expand Down Expand Up @@ -1389,7 +1390,8 @@ docket finalize clear-block --id 412 --revision <v> --head <sha> --pr-number 301
Every finalize run ends with one of four outcomes: `advanced` (it closed a change out), `contended`
(another writer got there first), `drained` (nothing eligible), or `halted` (a human is needed). A
driver continues on `advanced`/`contended` and stops on `drained`/`halted`, which are the same four
words implement-next uses.
words implement-next uses. A finalize loop stops on every `halted`; only an implement-next loop may
carry on past a halted change, when its verdict is `run-next`.

**Used for:** closing out hands-free, one merge per iteration. Unlike implement-next, the finalize
drain **does merge**. Naming ids bounds the run and authorizes merges `require_pr_approval` would hold.
Expand Down Expand Up @@ -1985,10 +1987,18 @@ post-rebase repair.
next run or phase you start, never one already running. Explicit halts need a human whatever the budget. A cancel
spends no attempt.

The **halt count** is a separate limit on a loop, not on a change. `run.max_consecutive_halts` (default 2, minimum 1)
caps how many implement-next runs in a row may halt on a change picked from the queue before the loop stops. A halt
under the limit prints `run-next`; the halt that reaches it prints `run-stop … run-halted` with a note asking the
person whether to reset the count. A halt on a named run or a resume never touches the count; a clean build (`run-complete`)
sets it back to 0, and so does `docket run reset-halts`, which runs only on the person's explicit yes, never on the agent's own. The limit is read when the verdict
is printed, so a new value applies to the next halt. `1` stops a loop at its first halt.

```yaml
# .docket.yml
run:
max_attempts: 2
max_consecutive_halts: 2
build:
max_attempts: 4
```
Expand Down
Loading
Loading