Skip to content

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.

The Grid view of Migration Tooling in Outline mode: phases, owners, percent done, start and finish dates, durations, and predecessors, with critical-path rows highlighted

Use summary tasks to group related work into phases, deliverables, or work packages.

FieldRollup rule
StartEarliest start date among the children
FinishLatest finish date among the children
DurationSpan from Start to Finish (working days, per the project calendar)
% completeDuration-weighted average of the children’s own percent complete
CriticalMarked 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.

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.

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:

WriteRefusal 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_completethe 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.

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.

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).

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.

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.

When a task row is focused in the WBS view:

ShortcutAction
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 chevronToggle 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.

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.

PathPurpose
src/features/grid/OutlineMode.tsxOutline table with keyboard + DnD handlers
src/features/schedule/engine/GanttRenderer.tsdrawSummaryBar — 8px bar with diamond end-caps
src/features/schedule/wbsAnnouncement.tsExpand / collapse aria-live formatter
src/hooks/useTaskMutations.tsuseIndentTask, useOutdentTask, useReorderTasks
src/stores/wbsStore.tsExpanded / collapsed state per summary