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
3 changes: 2 additions & 1 deletion docs/concepts/change-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ human has to memorize a flowchart to file a piece of work.
trivial mark is **needs-grooming** — it needs a design conversation first. A
proposed change that has a **spec** (the design document a change links to,
written before building) or is marked trivial, and whose dependencies are all
`done`, is **build-ready**.
`done`, is **build-ready**. A build-ready change on hold reads **on-hold**:
autonomous drains skip it, and it is built only when named.
- **in-progress** means a build has taken a **claim** — the moment a change is
picked up for building; it records which branch will carry the work and when it
was taken. Grooming a change to build-ready takes no claim; only building does,
Expand Down
3 changes: 3 additions & 0 deletions docs/guide/building-without-supervision.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,9 @@ build work stays isolated and the driver's own context stays small:
order. A named change that is not build-ready — still needs design, already in progress, or
waiting on an unmerged dependency — is skipped this drain with its reason, not waited on.

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
on a `pr` change therefore only clears between drains, once its pull request is merged outside the
Expand Down
3 changes: 3 additions & 0 deletions docs/guide/capturing-work.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,9 @@ your at-a-glance view. It groups every change into six sections — in progress,
groomed, proposed, and deferred — with one Type cell per row and a note like
`⏳ waiting on #<dep> — needs your merge` where a dependency is holding something up. The section
order and each section's sorting are configurable with `board.section_order` and `board.sorting`.
Grooming can also put a change on hold, keeping it out of autonomous builds: the Groomed table's
Readiness cell reads `build-ready` or `on hold`. The In progress table's State cell reads `building`
or `run halted — needs you`.
Every docket write re-renders the board, so there is no separate step to regenerate it.

One honest caveat about dependencies: chains serialize on the PR handoff. A change that depends
Expand Down
3 changes: 2 additions & 1 deletion docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ Each line is a pointer: the command, what its verbs govern, and where to read th
foreground root thread). Verbs: `docket agent --help`.
- **`docket capabilities`** — emit the binary's complete executable command catalog (read-only,
repository-independent). Verbs: `docket capabilities --help`.
- **`docket change`** — create and transition changes in the backlog. Verbs: `docket change --help`.
- **`docket change`** — create and transition changes in the backlog. Verbs: `docket change --help`
(`docket schema` lists the request keys, including `hold`).
- **`docket context`** — assemble read-only context bundles for the implementation workflow. Verbs: `docket context --help`.
- **`docket development`** — contributor operations against a docket checkout: install from a
checkout and run the complete test suite. Verbs: `docket development --help`.
Expand Down
28 changes: 23 additions & 5 deletions docs/reference/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -572,6 +572,21 @@ docket change resume-halted --id 412 --revision <v> --acknowledge-quiescent
**quiescent** (no longer writing). Without it, on revision drift, or on a live gate lock, the
operation refuses and writes nothing.

### Hold

A **hold** (`hold: true` on the change record) keeps an otherwise build-ready change out of
autonomous build selection; its readiness reads `on-hold` and the board shows **on hold**. A
malformed value reads as held, with a warning. Naming the change alone overrides the hold: a named
run, a claim, or `change complete` proceeds. Grooming and finalize ignore it. `change.groom` and
`change.create` set it with `hold: true` (an optional `hold_reason` writes `## Why on hold`) and
`change.groom` lifts it with `hold: false`.

**Used for:** a groomed change that needs manual steps, so a drain does not pick it up.

```sh
docket status --json | jq '.changes[] | select(.readiness=="on-hold") | .id'
```

### Owned sections / section intents (`preserve` / `replace` / `remove`)

**Owned sections** are the change-body headings that typed operations may write: `## Why`,
Expand Down Expand Up @@ -601,11 +616,12 @@ finalize run they start) takes the change the rest of the way. It is a handoff t
**Build-ready** is a proposed change that has a spec or is marked trivial and whose dependencies
are all `done`. **Needs-grooming** is a proposed change with neither a spec nor a trivial mark; it
needs a design conversation first. Anything not `proposed` reads `not-proposed`. Status reports
four more kinds: `auto-groom-blocked`, `waiting-dependency`, `stack-base-unresolved`, and `invalid`
five more kinds: `on-hold` (see [Hold](#hold)), `auto-groom-blocked`, `waiting-dependency`,
`stack-base-unresolved`, and `invalid`
(see [Readiness reason](#readiness-reason--waiting-on-n--needs-you-cells)).

**Used for:** selection. Only build-ready changes can be implemented; only needs-grooming changes
can be groomed. Selection order is priority → age (`created`) → lowest id.
**Used for:** selection. Only build-ready changes are selected for a build; a held change is built
only when named. Only needs-grooming changes can be groomed. Selection order is priority → age (`created`) → lowest id.

```sh
docket status --json | jq '.changes[] | {id, readiness, readiness_reason, unmet_dependencies}'
Expand All @@ -617,7 +633,7 @@ docket status --json | jq '.changes[] | {id, readiness, readiness_reason, unmet_
`docket status --json`, for example "ready to build" or "waiting on unmet dependencies". It is prose,
not a parseable code; key on `readiness`. The board renders the same state as cells like
**⏳ waiting on #N — not yet built**, **… — needs your merge**,
**stack parent #A killed — re-parent, un-stack, or kill**, and the "needs you" cells
**stack parent #A killed — re-parent, un-stack, or kill**, **on hold**, and the "needs you" cells
(**auto-groom blocked**, **run halted**, **finalize blocked**).

**Used for:** seeing why a change is not moving. A "needs you" cell always comes from a
Expand Down Expand Up @@ -729,7 +745,8 @@ docket change groom --request groom.json
The `change.groom` outcome that edits any `proposed` change without changing its groom state: a
needs-grooming stub stays needs-grooming, and a spec'd or trivial change stays build-ready. It can
replace the linked spec's body (only when the change links a spec) and edit owned sections, the
title, the priority, the type, the deliverable, the branch prefix, and relationship fields. It never sets `spec:`, `trivial:`, or
title, the priority, the type, the deliverable, the hold, the branch prefix, and relationship fields. A
hold moves a change between build-ready and on-hold. It never sets `spec:`, `trivial:`, or
`auto_groomable:`, and it never edits `## Auto-groom blocked`, which only abstain and re-enable
write.

Expand Down Expand Up @@ -2395,6 +2412,7 @@ docket development install --source ~/dev/docket
- [Harness](#harness)
- [Harness defaults sidecar (agents/harness-defaults.yml)](#harness-defaults-sidecar-agentsharness-defaultsyml)
- [Health check / health code](#health-check--health-code)
- [Hold](#hold)
- [Id / slug](#id--slug)
- [Implementation context](#implementation-context)
- [Implement-next / the drainer](#implement-next--the-drainer)
Expand Down
Loading
Loading