Summary Tasks and WBS Rollup
This is for anyone building or reading a project plan who wants to group related tasks into phases or deliverables. A summary task is a parent row in the Work Breakdown Structure (WBS) — the tree of phases and tasks that makes up the plan. A summary’s duration, dates, and progress are computed automatically from its children; you never edit them directly on the summary itself.

Use summary tasks to group related work into phases, deliverables, or work packages.
What rolls up
Section titled “What rolls up”| Field | Rollup rule |
|---|---|
| Start | Earliest start date among the children |
| Finish | Latest finish date among the children |
| Duration | Span from Start to Finish (working days, per the project calendar) |
| % complete | Duration-weighted average of the children’s own percent complete |
| Critical | Marked critical if any task beneath it is on the critical path — the chain of dependent work driving the project’s finish date |
Summary tasks cannot hold resource assignments, time entries, or direct dependencies. Add those on leaf tasks; the rollup will update on the next scheduler run.
The write restriction above is strictest for a phase — a summary with a real task nested under it, as opposed to one whose only children are checklist subtasks. See Phases below for exactly what’s locked, why, and how the two cases differ.
Phases
Section titled “Phases”A phase is a summary task with at least one structural child — another
task, not a checklist subtask — nested under it in the WBS. It is not a field
you set: TruePPM never stores “this row is a phase” anywhere (ADR-0293).
The server derives it on every read, the same way it derives whether a row is
a summary at all, from whether the row has a real task beneath it in the tree.
Give a row a structural child — by indenting a task under it (Alt + →),
reparenting one onto it, or using + Phase below — and it becomes a
phase; remove its last structural child and it stops being one.
This is the distinction that matters: a task broken into subtasks in its detail drawer is a summary (it has children) but not a phase, because subtasks are checklist items, not structural WBS children. It keeps its own assignee, status, and logged time exactly as a leaf task does. Only a row with a real task nested under it in the outline becomes a phase and picks up the locks below.
What a phase cannot carry
Section titled “What a phase cannot carry”A phase is a pure rollup — its status, estimate, and assignee are all computed from its children — so the API refuses a direct write to any of them, and refuses to let a checklist subtask be added straight into one:
| Write | Refusal message |
|---|---|
status | ”Phase status is rolled up from its children and cannot be set directly.” |
the three-point estimate (optimistic_duration / most_likely_duration / pessimistic_duration) | “Phase estimates are rolled up from its children and cannot be set directly.” |
assignee | ”A phase cannot be assigned — it is a rollup of its children, which carry their own assignees.” |
| a logged time entry — manual, PATCH, or the running timer | ”Time cannot be logged against a phase — it rolls up the logged time of its child tasks. Log against a leaf task instead.” |
| adding a drawer subtask under a phase | ”Phases group work — add tasks inside the phase, not subtasks.” |
percent_complete | the pre-existing summary-task lock above, unchanged |
A phase’s status is computed from the status of the leaf tasks beneath it, at
any depth, and refreshed on every schedule recompute. Backlog leaves are ignored
unless every leaf is in the backlog. The phase is Complete when every other
leaf is complete, In review when the rest are complete or in review, In
progress when any leaf is underway or any leaf is complete, and Not started
otherwise. A successor of a completed phase is therefore no longer shown as
blocked, and the schedule-performance index counts leaf work only. Task
responses carry status_source (derived on a phase, none on an empty
container, committed on ordinary work) and status_rollup_count (how many
leaves the status was read from).
Each lock fires only when a write actually tries to change the locked value — a PATCH that omits the field, or resends the value already stored, still succeeds. Set the assignee and log time on the leaf tasks inside the phase instead; the phase rolls both up automatically. This is enforced in the API itself, so an MCP client or any other direct caller is refused identically to the UI.
Each refusal above also carries a stable internal code
(phase_status_rollup_locked, phase_estimate_rollup_locked,
assignee_on_phase, time_log_on_phase, subtask_on_phase) — but don’t
branch a client on it. Per the error reference,
this whole family never reaches the response body as a code key; only the
field-keyed message above does. Match on the field name, not the code.
Adding a phase
Section titled “Adding a phase”The + Phase button next to + Item and + Milestone inserts a new
summary row at the insertion point and creates its first task inside it in
the same action, so a phase is never left empty. With a task row focused
instead, the same button turns that row into a phase by adding a new first
task inside it — its label states which of the two it is about to do. The
keyboard shortcut is ⌥⌘P (Ctrl+Alt+P on Windows and Linux) and works
either way, regardless of whether the button is showing.
+ Phase is off by default in the toolbar — turn it on from Display →
Outline → Structure buttons if you’d rather click than use the shortcut.
Indenting a task under another task (Alt + →) makes the same structural
change and needs no toggle.
A newly-inserted phase with no task inside it yet shows a small dashed hint beside its name (“This phase has no items yet”); the hint disappears the moment the row gains a real child, because at that point it already is one.
A task that drives a Start-to-Start or Start-to-Finish link cannot become a summary
Section titled “A task that drives a Start-to-Start or Start-to-Finish link cannot become a summary”A summary task cannot be the predecessor of a Start-to-Start (SS) or Start-to-Finish (SF) link: a summary starts when its earliest subtask starts, but the scheduler applies the link to every subtask, so the successor would wait for the latest one (scheduler conventions). Finish-to-Start and Finish-to-Finish links from a summary are fine.
So any move that would give such a task its first child is refused, and nothing moves: indenting a task under it, outdenting the task itself when it would adopt the tasks below it, reparenting or dragging a task onto it, reordering its level so that it lands where another task’s children sit, restoring its last child from the trash, undoing an earlier move that had taken its children away, and creating a task or a subtask inside it. The message names the links in the way:
“Design” cannot become a summary task: it drives “Build” (SS) with a Start-to-Start or Start-to-Finish link, and a summary cannot drive a successor from its start. Change those links to Finish-to-Start or Finish-to-Finish, or delete them, first.
The same goes for the other end of a summary: from 0.5 a Finish-to-Finish or Start-to-Finish link into a summary task is refused with a 400 when you save it, and an import skips it with a warning. A summary finishes when its last subtask does, so applying the link to every subtask would force even a short, unrelated subtask to finish with the predecessor. Link to the subtask that should finish with it instead. Finish-to-Start and Start-to-Start links into a summary are unaffected: they constrain its start, which every subtask shares. 0.4 accepts such a link and applies it to every subtask (#4437).
Retype or delete those links, or move them to one of the subtasks, then try the move again. A task that is already a summary is not affected by this check. Restoring a deleted task or project from the trash leaves any of its old Start-to-Start or Start-to-Finish links deleted when their predecessor has become a summary in the meantime; its other links come back. Nothing on screen says so: re-add the link from one of the summary’s subtasks if you still need it.
Over the API, indent, outdent, reparent, reorder and task restore answer 400
with code: "summary_start_link" and a blocking_dependencies list. Each entry
gives the link’s id and dep_type, plus the successor_id, which is null when
the successor is in another project. Structural undo answers 409 with the same
code and list. Creating a task with parent_id answers 400 with the message under
parent_id and no code.
A summary cannot be linked to one of its own subtasks
Section titled “A summary cannot be linked to one of its own subtasks”A move will be refused when it would put a summary over a task it is linked to: with
Design → Build on adjacent rows, indenting Build under Design would leave Design
linked to its own subtask, which the scheduler treats as a cycle. Indent, outdent and
reparent will answer 400 with code: "summary_descendant_link" and the same
blocking_dependencies list, and nothing will move. Delete or change the link, then
try the move again. Saving such a link as a dependency is already refused.
Restoring a task from the trash will be refused for the same reason. A deleted task
keeps its old outline position, so if another task now sits above that position and
the two are linked, bringing the task back would put the link between a summary and
its own subtask. Restore will answer 400 with code: "cyclic_dependency" and an
offending list of task ids, and nothing will be restored: no task, subtask or link
comes back. Delete the link or move the other task, then restore again. This applies
to links on any task that comes back with the restore, not only the one you clicked.
Restoring a whole project from the trash will apply the same refusal and bring back
nothing, since a half-restored project is worse than none.
One other way to end up with such a link is not refused yet: an MS Project, CSV or Jira import (#4856).
Phases and sprints
Section titled “Phases and sprints”Assigning a phase to a sprint is refused outright on the sprint field —
“Phases group work; assign the tasks inside it to the sprint instead” —
because a phase has no status or estimate of its own to burn down. (The
refusal carries the internal code phase_in_sprint_forbidden, which, like the
rollup-lock codes above, never reaches the response body — match on the field
name, not the code.) Unlike TruePPM’s other sprint-composition guardrails,
this one is not escalatable or relaxable by a project’s guardrail policy; it
applies unconditionally. Assign the phase’s individual tasks to the sprint
instead. See Sprint windows on the schedule
for how a sprint-driven phase reads on the Schedule.
Gantt visual
Section titled “Gantt visual”Summary bars render as an 8px-tall filled bar with filled-diamond end-caps at the start and finish dates — the same diamond geometry used for milestones, rotated 45°. The end-caps disambiguate a summary from a regular task bar at a glance.
A chevron on the summary row collapses and expands the subtree:
▸— collapsed▾— expanded
Collapsing a summary only hides its descendants from the list; it does not affect the schedule or the rollup.
The row states how many tasks are in the subtree beside its name — 4 inside
when the summary is open, 4 hidden when it is folded. This is drawn on the
row itself, not in a tooltip: a collapsed summary is otherwise indistinguishable
from one with no children at all, and that has to survive a glance down the
outline rather than requiring a hover on every row you are unsure about. The
same words are on the chevron’s accessible name, so screen-reader and sighted
users read the identical phrase.
Keyboard shortcuts (WBS view)
Section titled “Keyboard shortcuts (WBS view)”When a task row is focused in the WBS view:
| Shortcut | Action |
|---|---|
Alt + → | Indent — make this task a child of the task above it |
Alt + ← | Outdent — move this task up one level in the hierarchy |
Alt + ↑ / Alt + ↓ | Reorder within the current parent |
↑ / ↓ | Move focus to the previous / next visible task |
Enter on chevron | Toggle expand / collapse of the focused summary |
Plain Tab and Shift + Tab are deliberately left alone on a focused row — they fall through to the browser’s normal focus traversal, so a keyboard user can always Tab out of the grid.
Every indent and outdent announces what happened to screen-reader users — “Task indented”, “Cannot outdent: task is already at root level”, and so on.
Expanding or collapsing a summary announces "<Name> expanded, N inside." or
"<Name> collapsed, N hidden." — the same words the row and the chevron use, so
there is one vocabulary for the fact rather than one per surface. A summary with
no children states no count at all.
Drag-and-drop indent
Section titled “Drag-and-drop indent”Dragging a task row onto a summary row in the WBS view re-parents the dragged task under that summary. A drop-zone indicator highlights the target summary, and an aria-live region announces "<Task> will become child of <Summary>" on hover before the drop commits.
Dropping onto the empty area below a summary’s children inserts at the end of that subtree. The scheduler recomputes the rollup on the next tick.
GET /api/v1/tasks/?project={id}Returns the full hierarchy with each task’s wbs_path (ltree) and parent_id. Summary rows carry a read-only is_summary annotation so clients can render the chevron without a second query.
See the API reference for the complete schema.
Source
Section titled “Source”| Path | Purpose |
|---|---|
src/features/grid/OutlineMode.tsx | Outline table with keyboard + DnD handlers |
src/features/schedule/engine/GanttRenderer.ts | drawSummaryBar — 8px bar with diamond end-caps |
src/features/schedule/wbsAnnouncement.ts | Expand / collapse aria-live formatter |
src/hooks/useTaskMutations.ts | useIndentTask, useOutdentTask, useReorderTasks |
src/stores/wbsStore.ts | Expanded / collapsed state per summary |