Task lifecycle

You will be able to take a task from planned to closed — claim it, work it, record what you learned, prove it is finished, and close it — and read every refusal you meet along the way as an instruction rather than an obstacle.

Audience: anyone operating commission, human or agent. Assumes: your first task.

Five statuses, and no sixth

There is no blocked. Blocked is derived from unmet dependencies every time you ask, which is why the board can never disagree with the graph and why nobody has to remember to unblock anything. See positioning.md §6.

The transitions that exist

Anything else is refused, and the refusal names what is allowed:

cannot move myapp-1 from done to in_progress
hint: done is terminal; 'commission reopen myapp-1' first

Statuses move only through commission commands. There is no --status flag and no way to write one directly, which is what makes the event log a complete account rather than a partial one.

Claim before you work

A claim is a lease, not an assignment. assignee says who owns a task across sessions; a claim says who is holding it right now.

commission claim myapp-2
commission claim myapp-2 --lease 2h
commission claim myapp-2 --lease 0

The default lease is eight hours. --lease 0 never expires — use it deliberately, because a claim that cannot expire is a claim that can wedge a task when the session behind it dies.

commission start claims the task for you if nobody holds it, so the common path is one command:

commission start myapp-2

A second actor attempting the same claim is refused, and told what to do instead:

myapp-2 is already claimed by claude:api
hint: pick another with 'commission ready', or 'commission release myapp-2' if that claim is stale (lease expires 2026-07-27T22:54:38.906Z)

Expired leases are reclaimable by anyone. That is the recovery path for a crashed agent: nobody has to notice, and nothing has to be administered. If you are doing forty minutes of work without touching commission, extend instead of letting it lapse:

commission heartbeat myapp-2

Drop a claim you are not using — yours, or a stale one:

commission release myapp-2

Closing a task and reopening one both end the lease automatically. A finished task is held by nobody, and a reopened one goes straight back to the frontier.

Starting is refused when the task is blocked

commission start myapp-4

cannot start myapp-4: blocked by myapp-2 (open)
  missing: myapp-2
hint: finish the blockers first, or 'commission start myapp-4 --force' to override deliberately

This one is forceable, because “I know, I am going to do it anyway” is a real and defensible position. --force requires -m "<why>" and the reason goes into the event log.

Work leaves a trail

commission note myapp-2 -m "express.json() consumed the raw body — signature check needs the buffer"
commission check myapp-2 0
commission evidence myapp-2 pr=https://github.com/acme/myapp/pull/14 test=ci-2211

• Notes are for the next session. Decisions, dead ends, discoveries — the reasoning that is otherwise lost in a chat log. They are carried in every future context bundle and are full-text searchable.
• Criteria are ticked when they are actually met. commission check <id> <n> takes the position number printed by commission show.
• Evidence is what a gate requires. Attach real references; a fabricated benchmark to get past a gate is worse than an unfinished task, because the next person believes it.

If a judgement call comes up that is not yours to make, escalate rather than guessing:

commission ask myapp-2 -m "Reject unsigned webhooks, or log and continue?" --blocking

While a blocking question is open, no agent may claim the task — the claim is refused and names the question. A human answers, the answer is recorded on the task, and it appears in every later context bundle as a decision. See execution policies.

Review is optional, and it is not approval

commission review myapp-2

in_review is a status: the work exists and is waiting on a look. It changes nothing about whether the task may close. Human sign-off is a separate fact recorded by commission approve, and no status can substitute for it — see approval is not completion.

Closing, and the four things that refuse it

commission done myapp-2

done is a predicate, not a status assignment. Commission checks four things, in this order:

Two of them cannot be forced, and the reasons are different. A parent task whose children are unfinished is not finished by definition. And an agent that could --force past a human approval would make “human approval” a naming convention rather than a control.

Everything else is forceable, deliberately:

commission done myapp-2 --force -m "criterion 1 is obsolete after the API change; tracked in myapp-9"

--force without -m is itself refused. A silent override destroys the context the next session needs, so Commission makes you leave it behind.

Cancelling and reopening

commission cancel myapp-3 -m "the vendor shipped this upstream"
commission cancel myapp-4 --superseded-by myapp-2

Cancellation always carries a reason or a replacement. Six months later “why did we drop this?” is answerable from the log, which is the entire point.

commission reopen myapp-2

Reopen moves a done or cancelled task back to open, releases any claim, and puts it back on the frontier. Nothing is destroyed — the criteria, evidence, notes, and approvals are all still there. An approval survives the reopen itself; it goes stale the moment the work changes, which is a narrower and more useful trigger than “anything happened”. See approval is not completion.

The whole sequence

commission claim myapp-2
commission start myapp-2
commission note myapp-2 -m "express.json() consumed the raw body — signature check needs the buffer"
commission check myapp-2 0
commission evidence myapp-2 pr=https://github.com/acme/myapp/pull/14 test=ci-2211
commission review myapp-2
commission done myapp-2

Every command on this page is executed by tests/docs.test.ts against a scratch database.

Related

• Execution policies — who may do what, and approval versus completion.
• Parallel work — several agents on one frontier.
• Exit codes and the refusal shape.
• CLI reference — every flag on every command above.

Part of Guides.