HTTP API: proceed

The decision a session starts from (ADR 0177): the issue to take, every READY issue it passed over with the constraint that issue failed and the hold that failed it, and the terms of the order, composed from the plan, every checkout's board and every linked machine's live claims. Writes nothing.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

proceed

GET /api/v1/proceed/plan proceed.plan

What to proceed with, and why

The READY issues in the plan's hand-out order (the asked milestone first, then wave, priority and id, as `plan.next`), each refused when another worker holds it: a live mesh claim names it as its issue or a hold claims its record (`claimed`), a board or mesh announcement names its id as a word of its own (`named`, quoted beside it), or a live exclusive mesh claim of another session meets its scope (`scope_held`); advisory holds over its scope are listed as `shared_with` and refuse nothing. The first issue nothing refuses is `selected`, with what it unblocks, what finishes it and the commands that take it; `reason` says why in one sentence, and `sources` whether the board and the mesh could be read. A decision that could not read the board, or a declared mesh, is `provisional` and gives no commands. The caller's own session (its mesh claims on this runtime, and its board announcements) is never held against it; a session of the same name on another runtime is another worker. Composed by the server holding this checkout's lease, which holds the board and the mesh; the command line asks it. Writes nothing.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_proceed_plan
$ proceed plan

Query parameters

name	type	required	description	examples
milestone	string	no	The milestone whose READY issues come first; the active milestone when absent. The rest of the plan follows it, as for `plan.next`.	milestone_and_session: "a-session-proceeds"
session	string	no	The mesh session the decision is for, whose own claims are not held against it. Absent, the calling MCP session's board session (`board-<peer>`); over the command line, none.	milestone_and_session: "board-p1"
local	boolean	no	Compose in the process that answers and never ask the checkout's leaseholder: what a forwarded request says, so that it is never forwarded again.	default: falsemilestone_and_session: true

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/proceed/plan?milestone=a-session-proceeds&session=board-p1&local=false"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	ProceedDecision	What to proceed with, and why: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/proceed/step proceed.step

Proceed: the next step, as one work order

One step of a session that proceeds, as a work order a loop acts on: `do`, the capability to run next and its input — `devtask.implement` for the issue `proceed.plan` selects, under the idempotency key `devtask.implement` defaults to, so that a repeated order is one execution; `fan_out`, the other free READY issues declared parallel safe that share no path with it, at most four; `report`, what to announce on the board, as `peers.announce` takes it; and `next_due_at`, the next five-minute boundary after `at`, when to step again. Given an `intent`, only the issues serving its unmet criteria (`intent_realization.work`) are ordered, and an intent whose every criterion has current evidence, or that is satisfied, cancelled or superseded, answers `done` with nothing to run and nothing scheduled; without one, the whole plan is stepped and is done when no unfinished issue is left. Each item names the model `models.route` selects for a worker and the effort of the issue's profile. A provisional decision orders nothing. The same state answers the same order: `key` is the digest of everything but the moment, so a step repeated over unchanged state carries the same key at any later time. Writes nothing.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_proceed_step
$ proceed step

Query parameters

name	type	required	description	examples
intent	string	no	The intent the session realises, by id. The step is `done` when its realisation is met, and only issues serving its unmet criteria are ordered. Empty: the whole plan, done when no unfinished issue is left.	one_intent: "a-brief-is-reconciled-into-the-plan"whole_plan: ""
milestone	string	no	The milestone whose READY issues come first, as for `proceed.plan`; the active one when absent.
session	string	no	The mesh session the step is for, whose own claims are not held against it, as for `proceed.plan`.
at	string	no	The moment the step is taken at, RFC 3339 in UTC to the second (`2026-10-23T10:00:00Z`); the clock when absent. Only `next_due_at` depends on it.	one_intent: "2026-10-23T10:00:00Z"whole_plan: "2026-10-23T10:00:00Z"
local	boolean	no	Compose in the process that answers and never ask the checkout's leaseholder, as for `proceed.plan`.	one_intent: truewhole_plan: true

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/proceed/step?intent=a-brief-is-reconciled-into-the-plan&at=2026-10-23T10%3A00%3A00Z&local=true"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	WorkOrder	Proceed: the next step, as one work order: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

OrderOutcome

"implement" | "wait" | "done"

What one step decided.

implementAn issue is ordered: run do, and fan_out beside it.
waitNothing may be taken now — every candidate is held, waits on something, or the decision is provisional — so step again at next_due_at.
doneNothing is left to do; schedule nothing.

Used by WorkOrder

ProceedCandidate

object

One READY issue as the decision saw it.

property	type	required	description
issue	string	yes	The issue's id.
title	string	yes	Its title.
milestone	string	yes	Its milestone.
terms	ProceedTerms → ProceedTerms	yes	The terms its place in the order was decided by.
refused	array of ProceedRefusal → ProceedRefusal	yes	The constraints it failed, each with the hold that failed it; empty for an eligible issue.
shared_with	array of string	yes	Advisory holds that meet its scope: refused by none of them, shared with each.
scope	array of string	yes	The paths it touches.
finishes_with	ProceedEvidence → ProceedEvidence	yes	What finishes it: the objective and its evidence tally.

Used by ProceedDecision

ProceedConstraint

"claimed" | "named" | "scope_held"

A constraint an issue must meet before a session may take it.

claimedAnother worker holds the issue itself: a live mesh claim names it as its issue, or a hold claims its record.
namedA hold's words name the issue's id as a word of their own: how the board takes work, and how a mention reads.
scope_heldA live exclusive mesh claim of another session meets the issue's scope, so claiming it would be refused.

Used by ProceedRefusal

ProceedDecision

object

What a session proceeds with: the selected issue, every READY issue in the order work is handed out with what refused it, and the sources the decision was read from.

property	type	required	description
selected	ProceedCandidate \| null → ProceedCandidate	no	The first READY issue nothing refuses; absent when there is none, and `reason` says why.
reason	string	yes	One sentence a reader can check against `candidates` and `sources`.
provisional	boolean	yes	Whether a source the decision needs could not be read (see `sources`): the selection is then what this reading would choose, and another worker's unread claim may hold it.
next	array of string	yes	What to do with the selection, as the commands that do it; empty when nothing is selected or the decision is provisional.
milestone	string	yes	The milestone whose issues were looked at first.
candidates	array of ProceedCandidate → ProceedCandidate	yes	Every READY issue in hand-out order (the plan's: asked milestone first, then wave, priority and id), each with the constraints it failed.
waiting	map of integer (uint)	yes	How many unfinished issues are not READY, by their derived status: the work that waits on a dependency, a gate or a worker.
sources	array of ProceedSource → ProceedSource	yes	What the decision was read from, and whether each source could be read.

Used by proceed.plan

ProceedEvidence

object

What finishes an issue.

property	type	required	description
objective	string	yes	The issue's objective.
have	integer (uint32)	yes	The evidence it has.
need	integer (uint32)	yes	The evidence it needs.

Used by ProceedCandidate

ProceedRefusal

object

One constraint a candidate failed.

property	type	required	description
constraint	ProceedConstraint → ProceedConstraint	yes	Which constraint.
hold	string	yes	The hold that failed it: a mesh claim's key, or `board:<checkout>:<peer>[:<claim>]`.
holder	string	yes	Who holds it, in words.
detail	string	yes	What about the hold fails the constraint.

Used by ProceedCandidate

ProceedSource

object

One source of holds and whether it could be read.

property	type	required	description
source	string	yes	`board` (every checkout's peers) or `mesh` (every linked machine's live claims).
state	ProceedSourceState → ProceedSourceState	yes	Whether it was read whole, in part, or not at all.
holds	integer (uint)	yes	How many holds of others it contributed.
summary	string	yes	What was read, or why not.

Used by ProceedDecision WorkOrder

ProceedSourceState

"read" | "partial" | "unread" | "undeclared"

How much of a source a decision could read.

readRead whole.
partialRead, with parts that could not be (a board that did not answer).
unreadNot read: the decision holds nothing of it.
undeclaredNothing to read: the repository declares no enabled mesh.

Used by ProceedSource

ProceedTerms

object

The terms of a candidate's place in the hand-out order, most significant first, and what taking it unblocks.

property	type	required	description
in_milestone	boolean	yes	Whether it belongs to the milestone looked at first.
wave	integer (uint32)	yes	Its wave: one past the longest dependency path to it.
priority	string	yes	Its priority, `p0` first.
unblocks	array of string	yes	The unfinished issues that depend on it, directly or through others, each counted once. Shown, not ranked by: the order is the plan's.

Used by ProceedCandidate

StepIntent

object

The intent a step serves, as intent_realization.work answers it.

property	type	required	description
intent	string	yes	The intent's id.
stage	IntentStage → IntentStage	yes	Its derived stage.
criteria	integer (uint)	yes	How many criteria it declares.
met	integer (uint)	yes	How many have current evidence.
unmet	array of string	yes	The criteria without current evidence, by id.
serving	array of string	yes	The issues declaring they serve an unmet criterion, in plan order: the only ones the step orders.

Used by WorkOrder

StepReport

object

What a step tells the board: the input of peers.announce.

property	type	required	description
claim	string	yes	The claim the announcement stands under.
intent	string	yes	One line: what is ordered or why nothing is.
scope	array of string	yes	The paths of every ordered item.

Used by WorkOrder

WorkItem

object

One unit of ordered work: a capability, its input, and what a worker needs to run it.

property	type	required	description
capability	string	yes	The capability to run: `devtask.implement`.
input	any	yes	Its input, exactly as the capability takes it: the issue, and the idempotency key that makes a repeated order one execution.
issue	string	yes	The issue it realises.
title	string	yes	The issue's title.
scope	array of string	yes	The paths it touches.
profile	string	yes	The execution profile the issue declares.
effort	string \| null	no	The effort that profile declares, when it declares one.
model	string \| null	no	The model `models.route` selects for a worker, when one qualifies.

Used by WorkOrder

WorkOrder

object

One step of a session that proceeds: what to run now, what may run beside it, what to tell the board and when to step again.

property	type	required	description
key	string	yes	The order's identity: the digest of every field but `next_due_at`, `at` and `sources`. The same state answers the same key at any moment.
outcome	OrderOutcome → OrderOutcome	yes	What the step decided.
done	boolean	yes	Whether there is nothing left to do: the intent's realisation is met (or it was cancelled or superseded), or, for the whole plan, no unfinished issue is left. A done order runs and schedules nothing.
reason	string	yes	One sentence a reader can check against the decision and the intent.
do	WorkItem \| null → WorkItem	no	The capability to run next and its input; absent when the step waits or is done.
fan_out	array of WorkItem → WorkItem	yes	Independent items that may run in parallel with `do`, each a worker of its own; empty when nothing may.
report	StepReport → StepReport	yes	What to announce on the board, as `peers.announce` takes it.
next_due_at	string \| null	no	When to step again, RFC 3339 in UTC: the next boundary of the cadence after `at`. Absent when the order is done.
intent	StepIntent \| null → StepIntent	no	The intent the step was taken for, as its realisation stands; absent for the whole plan.
at	string	yes	The moment the step was taken at.
sources	array of ProceedSource → ProceedSource	yes	What the decision was read from, as `proceed.plan` says it.

Used by proceed.step