The tasks ready to build right now: open, settled, every dependency done — RANKED, best first, by (blocks + 1) x the task's priority x the standing of the ROADMAP TARGET it serves, so reach and urgency combine at both altitudes rather than one overriding the rest. A task whose target still waits on an unshipped target sorts below every task whose roadmap row is clear. Each row carries the roadmap standing that ranked it. The rank is a starting order, not a decision. A task a worker has marked in progress (start_task) is NOT listed, so this is safe to dispatch straight from.

claims reports every claim the project holds — one row per in-progress task, each with its stale_for_minutes (whole minutes since the last heartbeat). It is an age, not a verdict: a healthy build shows a small number and a worker that died still holding a task shows a growing one, so a console displays the age and a dispatcher sweeps the quiet ones with claims.filter((c) => c.stale_for_minutes >= claimStaleMinutes) (default 15). A claim is never auto-released — release one deliberately with edit_task { spec: "replan" }.

scope draws a LANE: only tasks whose folders touch it are listed, so two dispatchers can run side by side without ever writing the same files. Folder containment counts either way (src covers src/orders), a task with no scope is in every lane, and no filter means everything. Each row also carries overlap: the ids of tasks being worked right now whose scope touches that row's, computed across ALL lanes, because a claim in another lane is exactly what a lane filter would otherwise hide. Normally empty; non-empty means dispatching it would put two workers over the same folders.

tags carries the row's plain GitHub labels, so a dispatcher can branch on the KIND of work without a second call. spike is the one this flow reads: a spike ticket's deliverable is a drafted ticket, not merged code, so it is briefed differently. Labels are adopted from the issue on every pull, so one added in the web UI reaches the dispatcher.

Where every roadmap target stands: its tasks counted by status, the ones ready to dispatch, the targets it still WAITS ON, and the targets that wait on IT — in dependency order. Nothing here is hand-maintained: progress is DERIVED from the tasks pointing at each target, so it cannot go stale. Read this before choosing work — list_ready ranks tasks, this says which target they serve and which rows gate which releases.

The tasks the planning stage owns: never specced, or sent back by a build (replan). Resubmitted records come FIRST — a replan is a build already stalled, waiting on a spec.

The open plan as dependency-ordered layers. Errors on a dependency cycle. Pass target to scope it to one roadmap target — what a build dispatched that target should read, since a target is self-contained and ships as one stack. A dep outside the target that has not shipped errors here as an unmet dependency, which means the target is mis-scoped.

Every task, full records — the whole graph, open and done. For the scannable working subsets use list_ready / list_planning; for one task use get_task.

Every project this server's cache directory holds, each with its task counts by status and when the cache last changed. The ONE tool that takes no project: it answers about the server itself, not one project — so a console can list what to open without a human typing paths. Read-only and local: it never touches a provider or the network. updated_at is the cache file's mtime, so a project edited only on GitHub shows an older stamp until a sync. Rows are sorted by project.

One task's full record, or null if no task carries that id.

Create a task. deps/scope accept an array or a comma string. Fails if the id exists.

Create a roadmap TARGET — the row a set of tasks serves, and the altitude that decides which work matters. A target is never offered by list_ready and is NEVER BUILT: it groups work, and its progress is derived from the tasks that name it (add_task/edit_task target). On GitHub it is an issue whose sub-issues are those tasks.

A target is a NAME and a PARAGRAPH, both required: title, and a brief that is the WHY — what makes this worth building, and now — never an implementation spec. If you cannot write the why, it is not a target yet; file it as a task, or leave it unfiled.

It cannot carry build fields (scope, contract, tier, qa, stage, discovered_from): nothing ever builds a target, so those describe work that does not exist. It cannot serve another target either — the roadmap is one altitude. deps are the targets that must SHIP first, and they rank every task underneath: a target waiting on an unshipped target sorts its work below rows that are clear, and priority multiplies the rank of everything it holds.

Widen an open task's scope and/or set its brief. Refuses a done task (it orphans work). It only ever ADDS scope — to narrow one, remove a field, or set a label, use edit_task.

Edit any field of a task — title, brief, contract, deps, scope, tier, qa, priority, spec, stage, kind, tags, target, type. Only the fields passed change; the id is fixed. Rewrites the issue body and labels. Unlike amend_task, it can narrow scope and edit a done task.

To REMOVE a field rather than change it, name it in clear — that is the only way a field:value label comes off an issue without opening the GitHub UI. Setting a field back to its default (tier 3, qa subagent, priority normal, spec settled) also drops its label, since absence already means the default.

Mark a task in progress — the FIRST thing a worker does when it picks one up. The task leaves list_ready, so nothing dispatches it twice, and its board card moves to In Progress. It clears itself: closing the task or sending it back to spec:replan releases it.

Mark a task done (closes its issue).

PERMANENTLY delete a task and its GitHub issue (deleteIssue) from every layer, deepest-first. Needs the token's delete-issue permission (repo admin/triage); a normal token cannot. Irreversible — to just mark a task done, use close_task instead.

A task's trail: its GitHub issue comment thread, every comment an entry (people's comments included), oldest first. Empty when the task has no issue yet.

Append one entry to a task's trail by posting a comment on its GitHub issue, so a later session can backtrack it. Requires the task to have an issue (sync it first).

Reconcile the repo with GitHub: pull every issue into the local cache, push seed tasks.

Answers: to start working on this task, what has to be done first? Returns its open prerequisites as dependency-ordered layers (work layer 1 first). startable=true means nothing is in the way.

Answers: what is the biggest blocker right now? Open tasks ranked by how much of the plan transitively waits on them — the first entry is the single biggest bottleneck. Each entry says what it blocks (with the high-priority subset called out) and what has to happen to get to it (unblockedBy, dependency-ordered).

The configuration for a project, layer by layer: CLI flags, the global spec (applies to every repo), this repo's override, and the effective result.

Configure preferences centrally — they propagate to every provider layer. scope=global writes the spec that applies to all repos; scope=repo overrides it for this repo only.