Proposals, plans and review
Agents stage revisions into a workstream's proposal, grouped into plans, and a person accepts them one by one, all at once or as a group (or the agent, with Agent autonomy on).
The proposal
A workstream has at most one open proposal, opened by the first staging. Its states are Draft and Ready (the agent says a review pass can start with proposal_ready, and may keep staging), then Completed or Discarded. A proposal completes itself when nothing is left pending after an accept or a withdraw; the agent's next staging opens a new one.
Staged revisions
Each document an agent stages with spec_apply is a revision:
A pending revision needs attention while a thread is open on its artefact.
Accepting
Accept is a person's act, for an Editor or above, or an agent's with proposal_accept in a project with Agent autonomy on. It merges the staged document onto the workstream's current version: fields nobody touched since the agent read apply; an overlap is refused as stale, and the agent stages again. A revision that refers to another pending revision is accepted with it, in dependency order.
- Accept all accepts every pending revision matching the kinds you see (and, by default, without open threads) in one step. It skips plans and their members, and revisions held by a change request or by a blocking question of their agent.
- A revision in a plan is accepted only with its plan, with Accept group.
- A revision held by a change request, or by a blocking question its agent asked, cannot be accepted until the thread ends.
An agent's merge of a conflict, staged with task_resolveConflict, is a revision too. Accepting it resolves the conflict with that merge, as long as Main and the workstream did not move since the agent merged.
Withdraw and discard
Withdraw drops one pending revision. Discard drops the whole proposal, and its pending revisions become Withdrawn. An agent may discard only a proposal whose pending revisions are all its own; otherwise it withdraws its own with proposal_withdraw. Withdrawing a plan withdraws only the plan: its pending revisions leave it and stay pending.
Plans and accept group
An agent groups what it stages into plans, one per intended task:
spec_applywith a plan: a label and the task, either a new one with its name, description and key, or an open task of the workstream by number;proposal_plancreates a plan or changes its task;proposal_assignmoves the agent's own revisions into or out of a plan.
{
"plan": {
"label": "Reserve stock",
"task": { "mode": "new", "name": "Reserve stock", "externalKey": "KAN-43" }
}
}A revision staged again stays in its plan, an agent's conflict merge included. A person can move any pending revision between plans with Move to plan. Plans show first on the Proposals page, with their members. Accept group:
- accepts every member in dependency order;
- creates the task (Draft, with the plan's name, description and key) or uses the existing one;
- scopes the accepted changes into it;
- ends the change requests on the accepted artefacts (outcome changed), and resolves the conflict of a staged merge it carries;
- optionally marks the task Ready in the same step (Accept group and Ready), with Ready's own checks.
Accept group is refused:
- when the plan changed since you looked (you see what was added or removed);
- when a member is held by a change request or by a blocking question of its agent (the plan says which);
- when a member depends on a pending revision outside the plan;
- when another open task already covers one of its artefacts;
- for a task past Draft, until you confirm that its agreement changes.
Warning
Accept group and Ready is all or nothing
When Ready refuses, for example because of a person's blocking question on one of the changes, nothing is accepted. An Admin can go on with a reason, which is recorded on the task.
Change requests
Instead of accepting, a reviewer can open a change request on a pending revision. It is a thread that holds that revision's accept, alone or in its plan, until the agent stages the artefact again and a revision of it is accepted, which resolves the request (outcome changed). Withdrawing the revision, or discarding the proposal, ends it as withdrawn.
Next steps
- Threads, questions and change requests: every kind of thread and what it holds.
- Tasks and publishing: what happens to a task after its plan is accepted.