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
14 changes: 0 additions & 14 deletions .docket.example.yml
Original file line number Diff line number Diff line change
Expand Up @@ -156,20 +156,6 @@ review:
max_fix_tasks: 10


# ═══ reclaim — releasing abandoned claims ═════════════════════════════════════════════════

reclaim:
# lease_ttl — hours a claim on an in-progress change lasts. A change whose lease has expired,
# with no feature branch and no workspace, is eligible to return to the backlog.
# scope: any layer
lease_ttl: 72

# auto — false (default): `docket maintenance sweep` reports an eligible change as skipped
# (reclaim-auto-disabled). true: the sweep reclaims it.
# scope: any layer
auto: false


# ═══ leak_check — keeping docket out of a private repository's shared surfaces ═══════════

leak_check:
Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Index: [guide/README.md](guide/README.md)
pull request into your mainline and out of your backlog, hands-off across a whole set of changes.
- [Status: Keeping the backlog honest](guide/keeping-the-backlog-honest.md) — tell whether your backlog
still reflects reality, and fix it when it does not: the read-only status report, the maintenance
sweep, reclaiming expired claims, and recovering a halted run.
sweep, and recovering a halted run.
- [ADRs and learnings: Remembering why](guide/remembering-why.md) — where docket keeps the decisions it
made and the lessons it learned, how you record a finding, and when a lesson belongs in your
always-in-context instructions instead.
Expand Down
6 changes: 3 additions & 3 deletions docs/comparison/ai-native-sdlc-playbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ fail-closed operations. In return docket has depth the playbook never mentions.
| Scheduled security scans | Claude Security; validated findings; patches through the PR gate. | None. | Playbook only |
| Incident channels and ticket triage | Claude in Slack/Teams as first responder. | None. | Playbook only |
| Findings re-enter the pipeline | From production and scans. | From builds and close-outs, reported; a human files with `docket change create`. | Both (different source, manual capture) |
| Backlog hygiene and self-healing | Not described. | `docket status` (read-only), `maintenance sweep`, reclaim of expired branchless claims, `change resume-halted`. | docket only |
| Backlog hygiene and self-healing | Not described. | `docket status` (read-only), `maintenance sweep`, resume by id, `change resume-halted`. | docket only |
| Health checks with typed findings | Not described. | Validation, artifact integrity, derived-view drift, topology, prepare-time refusals; two judgement checks warn-only. | docket only |
| Decision ledger | Not described. | Immutable numbered ADRs; supersede and reverse as new records; 96 today. | docket only |
| Build-loop memory with relevance-gated reads | `CLAUDE.md` always in context. | Findings read per relevance at groom, plan, review; only unprompted rules promoted. Harvest and index deferred. | docket · deferred |
Expand All @@ -144,7 +144,7 @@ is current when build starts; docket assumes it is not.
|---|---|---|---|
| Governance as configuration | Skills, hooks, managed settings; `CLAUDE.md` and `REVIEW.md` reviewed like code. | Four config layers per key; shared-setting guard; every key documented in `.docket.example.yml` or the suite fails; the capability catalog is the only hard-coded CLI spelling. | Both (different content) |
| Human judgement points | Intent, plan approval, design review, PR approval, findings triage, policy changes. | Change creation and grooming, the PR merge, finalize confirmations, learnings promotion, filing discovered work, abstained stubs. Plan approval deliberately not a human point. | Both |
| Audit trail | Git history; logged hook decisions; incident conversations. | Every transition a metadata commit; marker sections; receipts and leases; frozen plan/results records; ADR supersessions as new files. | Both |
| Audit trail | Git history; logged hook decisions; incident conversations. | Every transition a metadata commit; marker sections; receipts; frozen plan/results records; ADR supersessions as new files. | Both |
| Legacy tracker integration | One system of record per artifact. | One-way GitHub Issues mirror; Projects v2 guarded but unwired. | Both (GitHub issues only) |
| Autonomy without a human channel | Scoped subagents; gates ask a human. | Abort-and-report wrappers; autonomy precedence; forked children never yield; four dispositions drive any loop. | docket only |
| Run-tracker bracketing for dispatched runs | Not described. | `run start` / `run verdict` / `run continue`; retry-once accounting in durable records. | docket only |
Expand All @@ -168,7 +168,7 @@ no-test-edits guard during repair; an intake path from production or scanner fin
| Proving the build | 4 | Build gate and evidence; gate driver and budgets; integration repair; configuring the suite | docket-build gate paragraphs, gate references, tests/README |
| Reviewing before the human does | 5 | Reviewer contract and tiers; fix loop and disposition table; why the suite runs in the build gate | docket-review section, fix-loop reference |
| Landing changes safely | 5 | Finalize end to end; blocked and relink; branch protection; /loop finalize | Closing out hands-free, hands-off finalize |
| Keeping the backlog honest | 6 | Status vs sweep; health codes; reclaim; halted recovery | Reclaiming stale claims, docket-status |
| Keeping the backlog honest | 6 | Status vs sweep; health codes; halted recovery | docket-status |
| Remembering why | 6 | ADRs; learnings and promotion; what is human-curated today | Learnings, docket-adr |
| Governing through configuration | cross | Layers and the shared-setting guard; every config block by purpose; skills map; capability catalog; dummy_mode | Configuration, convention config |
| Running on your harness | cross | Install and update; model pins; invocation paths; Cursor/Codex/opencode; runner delegation | Install, Updating, Tuning, Runner delegation, docs/* |
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/change-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ and it moves to `done` once the root of its stack lands.
truth, and the board is derived from it, never hand-edited into disagreement.
- Grooming a change to build-ready records no claim — only a build does — so a
groom and a build never fight over the same change.
- A claim records which branch will carry the work and when it was taken.
- A claim records which branch will carry the work.
- A dependency is satisfied only when it is `done`; a change waits until every
dependency is `done` before it is build-ready.
- A stacked change's base is its parent's branch while the parent is live, and
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ for whatever step you are on. Installing docket and configuring it is its own se
pull request into your mainline and out of your backlog, hands-off across a whole set of changes.
- [Status: Keeping the backlog honest](keeping-the-backlog-honest.md) — tell whether your backlog
still reflects reality, and fix it when it does not: the read-only status report, the maintenance
sweep, reclaiming expired claims, and recovering a halted run.
sweep, and recovering a halted run.
- [ADRs and learnings: Remembering why](remembering-why.md) — where docket keeps the decisions it
made and the lessons it learned, how you record a finding, and when a lesson belongs in your
always-in-context instructions instead.
Expand Down
7 changes: 2 additions & 5 deletions docs/guide/building-without-supervision.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,11 +68,8 @@ A single implement-next run walks a fixed path and then stops:
1. **Pick.** It selects the next **build-ready** change (a proposed change that has a spec and
whose dependencies are all `done`). It never touches work that is not ready.
2. **Claim.** It takes a **claim** on that change (the moment a change is picked up for building; it
records which branch will carry the work and when it was taken) with a conflict-checked write on the
change's status, so two runs in parallel can never grab the same change. The claim carries a
**claim lease** (a timestamp on a claim; when it expires with no branch behind it, the change
goes back to the queue), which is what lets a crashed run's change self-heal instead of sitting
stuck — see [Keeping the backlog honest](./keeping-the-backlog-honest.md).
records which branch will carry the work) with a conflict-checked write on the change's status,
so two runs in parallel can never grab the same change.
3. **Reconcile.** The step above — freshen the change against reality, or kill or escalate it.
4. **Plan.** It cuts a feature branch, creates an isolated working copy of the repo on that branch
(a *worktree*), commits a copy of the change's spec as the branch's first commit, and authors a
Expand Down
12 changes: 3 additions & 9 deletions docs/guide/capturing-work.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,15 +68,9 @@ parent rather than into your main line, so its code has not shipped yet — it p
[Building without supervision](./building-without-supervision.md) page covers stacking from the
build side.

There is also one edge running *backward*: `in-progress → proposed`. A **claim** (the moment a
change is picked up for building; it records which branch will carry the work and when it was
taken) carries a **claim lease** (a timestamp on a claim; when it expires with no branch behind
it, the change can go back to the queue). If a run crashes before it ever pushes a branch, the
change would otherwise sit stuck at `in-progress` forever; instead, once the lease has expired and
the change has no feature branch and no workspace, it can be reclaimed back to `proposed` —
by `docket maintenance sweep` when `reclaim.auto` is `true`, or by you with `docket change reclaim`
(the sweep reports such a change as skipped while `reclaim.auto` is `false`, the default).
Recovering these is covered in [Keeping the backlog honest](./keeping-the-backlog-honest.md).
A **claim** (the moment a change is picked up for building) records which branch will carry the
work. If a run crashes or is stopped, its change stays `in-progress` until you resume it by id —
see [Keeping the backlog honest](./keeping-the-backlog-honest.md).

The **board** (the generated overview of every change and its state, never edited by hand) is
your at-a-glance view. It groups every change into six sections — in progress, built, blocked,
Expand Down
58 changes: 12 additions & 46 deletions docs/guide/keeping-the-backlog-honest.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,25 @@
By the end of this page you can tell whether your backlog still reflects reality — and fix it
when it does not. You will know the difference between the read-only status report and the
maintenance sweep that closes out merged work, what each health finding means and how to answer
it, how a change that a crashed run left stuck goes back to the queue, and how to recover a run
that stopped and asked for you.
it, and how to recover a run that stopped, crashed, or asked for you.

## Status versus the maintenance sweep

Two different commands keep the backlog current, and it helps to keep them apart.

**`docket status` is read-only.** It reports the backlog — what is proposed, ready, in progress,
implemented, or blocked, and the build-ready queue in selection order — plus any health findings.
It never merges, archives, reclaims, or rewrites anything, so you can run it as often as you like.
It never merges, archives, or rewrites anything, so you can run it as often as you like.

**`docket maintenance sweep` does the tidying.** When a change (one unit of planned work, roughly
one pull request, tracked as one markdown file) has its pull request merged, something has to move
it to `done` and archive it. The deliberate way is to close the change out yourself right after
the merge — see [Landing changes safely](./landing-changes.md). But you do not have to: the sweep
is the safety net. In one pass it closes out every change whose pull request already merged,
retries any close-out cleanup that did not finish, and reclaims expired claims (below). That
cleanup retry also repoints the backlink in a merged pull request's description when it still
names the change's old `active/` path, even for a change archived long ago; to preview every such
pull request first and repoint them all at once, run `docket repository repair --pr-backlinks`. Every
and retries any close-out cleanup that did not finish. That cleanup retry also repoints the
backlink in a merged pull request's description when it still names the change's old `active/`
path, even for a change archived long ago; to preview every such pull request first and repoint
them all at once, run `docket repository repair --pr-backlinks`. Every
change it touches re-renders the **board** (the generated overview of every change and its state,
never edited by hand) in the same commit.

Expand Down Expand Up @@ -52,39 +51,6 @@ A dependency only counts as satisfied once the change it names reaches `done`, s
on unmerged work simply stays out of the build-ready queue; status shows which dependencies are
still unmet.

## Reclaiming expired claims

When a run crashes or is killed **before it ever pushes a branch**, its change is left stuck at
`in-progress`. Reclaim returns it to the queue, and only in the situation it can handle *safely*.

Every **claim** (the moment a change is picked up for building; it records which branch will
carry the work and when it was taken) stamps the time it was taken. A change is eligible for
reclaim only when all three hold:

- its claim lease has expired: the stamp is older than `reclaim.lease_ttl` hours (default `72`);
- no feature branch for it exists, locally or on the remote;
- no feature workspace for it exists.

An eligible change goes back to `proposed` and re-enters the queue — the one edge in a change's
life that runs backward. Anything docket cannot confirm (a probe that fails, a branch it cannot
see clearly) leaves the change alone.

- **Automatic reclaim is opt-in.** With `reclaim.auto: false` (the default) the maintenance sweep
leaves every eligible change alone and reports it as skipped with the reason
`reclaim-auto-disabled`. With `reclaim.auto: true` the sweep reclaims every eligible change
itself.
- **Run it by hand any time** with `docket change reclaim --id <id> --revision <revision>` — per
change, at its exact recorded revision — whatever `reclaim.auto` says.
- **A change that already has a branch is left to you.** A pushed branch might carry real,
un-merged work, so reclaim never touches it — the concrete risk is throwing away code nobody
backed up.

```yaml
reclaim:
lease_ttl: 72 # hours before an unattended claim counts as expired
auto: false # true => the maintenance sweep reclaims eligible changes itself
```

## Recovering a halted run

A build run ends by declaring one of four outcomes, and one of them — `halted` — means it stopped
Expand All @@ -101,13 +67,13 @@ A halted change stays `in-progress`, and the board shows it as **run halted —
Make the call it could not: re-design the change if reconcile found the design invalidated (a
fresh design conversation, see [Designing before building](./designing-before-building.md)), or
clear the blocker. Then recover the change with `docket change resume-halted`, which checks the
workspace, refreshes the claim, and removes the halt marker, and start the next run on it with
workspace and removes the halt marker, and start the next run on it with
`docket run start implement-next --resume <id>`.
- **It crashed before pushing a branch.** Nothing to recover — once the lease expires, reclaim
returns it to `proposed` as above, and the next run rebuilds from scratch.
- **It crashed after pushing a branch.** The branch holds real work, so reclaim leaves it alone.
Resume it deliberately with `docket run start implement-next --resume <id>` and name the id to
implement-next — a bare, unscoped run skips an in-progress change rather than resuming it.
- **It crashed or was stopped.** Resume it deliberately with
`docket run start implement-next --resume <id>` and name the id to implement-next — a bare,
unscoped run skips an in-progress change rather than resuming it. If the start refuses with
`resume-active-run`, nothing has confirmed the old run stopped: cancel it with
`docket run cancel --key <key> --reason <why>`, then resume.

## Before any of this: a set-up repository

Expand Down
2 changes: 1 addition & 1 deletion docs/install/global-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Two kinds of setting belong here:
[`agents/harness-defaults.yml`](../../agents/harness-defaults.yml), a shipped file you read but
never edit. To change one, see [Models](models-and-effort.md), then re-run the install.
- **Any `scope: any layer` key you want as your personal default** across repositories — for
example `review.min_fix_severity` or `reclaim.lease_ttl`. A repository's own files still win.
example `review.min_fix_severity` or `review.max_fix_tasks`. A repository's own files still win.

The canonical reference for every key is [`.docket.example.yml`](../../.docket.example.yml): every
supported key at its built-in default, with a short note and a scope tag saying which layers may
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ Each line is a pointer: the command, what its verbs govern, and where to read th
installation is current and writes nothing, and `docket install collect`, which reclaims
verified unreferenced installed version trees. Verbs: `docket install --help`.
- **`docket learning`** — record and update learning findings. Verbs: `docket learning --help`.
- **`docket maintenance`** — close out merged changes, retry close-out cleanup, and reclaim
expired claims in one pass (`docket status` stays read-only). Verbs: `docket maintenance --help`.
- **`docket maintenance`** — close out merged changes and retry close-out cleanup in one pass
(`docket status` stays read-only). Verbs: `docket maintenance --help`.
- **`docket open`** — open the board, or a change's record, spec, plan, results, or pull request,
as a GitHub page or from the local metadata checkout. Without an id it opens the change whose
branch is checked out. With `--export` it writes a clean Markdown copy of a change, spec, plan,
Expand Down
2 changes: 0 additions & 2 deletions docs/reference/config-keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,6 @@ Each key has one scope:
| `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 |
| `reclaim.auto` | `false` | any layer | whether `docket maintenance sweep` reclaims an eligible change or reports it skipped |
| `learnings.enabled` | `true` | any layer | whether learnings are written and read |
| `open.artifacts` | `github` | any layer | where `docket open` shows a shared repository's board and change artifacts: `github` pages, or the `local` metadata checkout's files |
| `gate_observation_budget` | `30` | any layer | minutes docket waits for a test-suite run it started to finish |
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/fields.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ skill is reorganized).
one unit of planned work, roughly one pull request, tracked as one markdown file) — owned by the
convention section **"Change manifest (frontmatter at the top of each change file)"**. That
section is the live list of every manifest key and its meaning: identity and title, lifecycle
status, priority and type, dependencies (`depends_on`), the claim fields that record which branch
will carry the work and when it was taken, and the spec/plan/results/pr links.
status, priority and type, dependencies (`depends_on`), the claim field that records which branch
will carry the work, and the spec/plan/results/pr links.
- **Change body sections** (the headings the manifest's prose body may carry) — owned by the
convention section **"Change body sections"**.
- **ADR fields and body** — owned by the convention section **"ADR file (`<adrs_dir>/<NNNN>-<slug>.md`)"**,
Expand Down
Loading
Loading