Product iterations

An iteration belongs to a product or ops project at /projects/<id>/iterations. Create it with an immutable X.Y series. Project/version pairs are unique. The project defines its repository manifest.

Todos carry one iteration_id. Batch moves require one project, current todo revisions and a request key. They atomically update membership and retain history on both iterations. Released or cancelled iterations cannot receive work. Project progress excludes closed todos and includes completed todos. Iteration progress includes every current member, including closed and completed work.

Scope#

An iteration runs planned, active, then released or cancelled. The first change to active records started_at: the todos it holds then are its baseline. A todo that joins afterwards, created in it or moved in, is out of plan (out_of_plan on the todo, todo_list out_of_plan=true), with who added it, when and the optional iteration_reason or move reason. A todo leaving a started iteration is recorded as removed. Before the start, membership changes are planning and leave no trace in scope. Out-of-plan work needs nobody's approval; it makes scope change visible.

In the web app the iteration page shows Out of plan beside the other counts (it opens the filtered list), and Scope changes lists the baseline, the present scope, additions and removals with who, when and why.

Closing#

iteration_update never releases or cancels. iteration_close does, at the current revision with a request key, and every unfinished todo in the iteration (requirement, todo, in progress or blocked, not closed) needs one carry: move to another open iteration of the project, unplan, or keep with a reason. The carries and the status change commit together; a release cannot leave unfinished work unaccounted for. Aidy proposes the carries as one iteration_close for you to confirm.

On the iteration page, Release and Cancel iteration open the same close-out: every unfinished todo is listed with its destination (the next open iteration by default, back to unplanned, or kept here with a reason), set one by one or all at once; Let Aidy propose asks Aidy instead. The status menu of Edit iteration offers only planned, active and blocked.

A cancelled iteration without deliveries can be deleted (iteration_delete with its current revision) by its owner, its creator, the project's owner and members, or a Work manager. Its todos stay in the project, unplanned, and the project's history keeps who deleted which version when.

Brief#

planning_brief measures a project and its current iteration (or a given one) in one read: status counts; risks (overdue, blocked, a due day pushed later twice or more); this week's completions and logged time; each assignee's open todos and estimated minutes against the working days left before the iteration's due day (480 minutes a day); unestimated todos and done todos with no logged time; the iteration's baseline, current scope, every change since the start; and a daily burndown of scope and remaining work in todos and estimated minutes, replayed from scope and completion times. The project and iteration pages draw it, and Aidy writes status updates from it (Ask Aidy on the iteration page). Load and capacity marks an assignee whose estimated open work exceeds the working days left in red.

acahti iteration create --body-file iteration.json
# {"project_id":"turbomesh","version":"1.4","title":"Autumn delivery","owner":"alice"}
acahti mcp call planning_move_todos '{"items":[{"id":42,"revision":3}],"iteration_id":12,"request_key":"move-42-12"}'
acahti iteration close 12 --body-file close.json
# {"revision":4,"status":"released","request_key":"release-1.4","carry":[{"todo_id":43,"action":"move","iteration_id":13}]}
acahti mcp call planning_brief '{"project":"turbomesh"}'
acahti delivery draft --iteration 12
acahti delivery submit --body-file delivery.json
acahti delivery list --iteration 12
acahti delivery view 7
acahti delivery retry 7

Delivery input contains iteration_id, request_key, summary, changelog, todo_ids and repositories. A delivery names at least one todo of the iteration it delivers; work without a todo cannot be delivered. delivery_draft lists the iteration's todos, done ones first, marking those an earlier delivery carried, and drafts a changelog line per chosen todo (by default the done ones not yet delivered). Deliveries list their todos, and todo_get lists a todo's deliveries. In Submit delivery you tick the todos; the changelog draft follows the selection until you edit it, and Let Aidy draft it asks Aidy for a changelog grouped into features and fixes. A todo's page shows the versions that delivered it. Each project repository supplies name, a full commit sha, branch, and changed. Unchanged repositories also supply an existing tag matching that SHA. Changed repositories receive the same new vX.Y.Z tag. Repository write access, existence of branch and commit, and unchanged tags are validated before allocation, including commit reachability from the selected branch. Existing tags are never moved.

The project allocates Z transactionally, starting at 1. A delivery's manifest, version, actor and changelog are immutable. Replaying the same request returns the same delivery; changing its payload requires a new request key. Failed allocated versions are retained. Retry resumes the same tags and version. A durable recovery task retries interrupted dispatch up to five attempts; an explicit retry remains available afterwards. Publishing tags invokes the repositories' existing tag pipelines. Partial dispatch is visible with errors and repository evidence. Marking an iteration released does not deploy it.

The delivery timeline displays changelogs and pipeline results matched by exact repository, tag ref and commit SHA. The dispatch step means tags were published; pipeline success is displayed separately and is never inferred from dispatch. The iteration page and each delivery also show their Track flow.

Agents use the same REST/MCP service as the browser. Structured execution steps (planning_run_step, planning_run_steps) include parent relationships, dependencies, evidence, attempts and optimistic revisions. Cycles and missing references are rejected. Trace and the read-only DAG render these same steps. Aidy can draft and update iterations too; each write waits for your confirmation.

iteration_list with state=current lists unfinished iterations (planned, active or blocked). Todos without an iteration are planned with the normal move command.