Files
kandev/docs/specs/ui/system-design/sidebar-task-tree-activity-sort.md
Carlos Florêncio 45cef11630
Architecture Lint / Architecture boundaries do not regress (push) Has been cancelled
Backend Tests / Plan external runner allocation (push) Has been cancelled
Backend Tests / Detect relevant changes (push) Has been cancelled
E2E Tests / Plan external runner allocation (push) Has been cancelled
Frontend Tests / Plan external runner allocation (push) Has been cancelled
Lint Action Pinning / All action refs are SHA-pinned (push) Has been cancelled
Lint Harness Files / Harness files pass lint (push) Has been cancelled
Backend Tests / Backend Static Checks (push) Has been cancelled
Backend Tests / Backend Tests (1/2) (push) Has been cancelled
Backend Tests / Backend Tests (2/2) (push) Has been cancelled
Backend Tests / Backend (ambient integration env) (push) Has been cancelled
Backend Tests / Run Backend Tests (push) Has been cancelled
Backend Tests / Backend Postgres (push) Has been cancelled
Backend Tests / Backend Postgres 18 (push) Has been cancelled
Backend Tests / Backend (windows) (push) Has been cancelled
E2E Tests / Detect relevant changes (push) Has been cancelled
E2E Tests / Build (push) Has been cancelled
E2E Tests / E2E Shard ${{ matrix.shard }}/14 (push) Has been cancelled
E2E Tests / Resolve Playwright runtime image (push) Has been cancelled
E2E Tests / E2E Containers Shard 1/6 (push) Has been cancelled
E2E Tests / E2E Containers Shard 2/6 (push) Has been cancelled
E2E Tests / E2E Containers Shard 3/6 (push) Has been cancelled
E2E Tests / E2E Containers Shard 4/6 (push) Has been cancelled
E2E Tests / E2E Containers Shard 5/6 (push) Has been cancelled
E2E Tests / E2E Containers Shard 6/6 (push) Has been cancelled
E2E Tests / Kubernetes Compatibility (v1.34.8) (push) Has been cancelled
E2E Tests / Kubernetes Compatibility (v1.36.1) (push) Has been cancelled
E2E Tests / Desktop E2E Smoke (push) Has been cancelled
E2E Tests / Merge E2E Reports (push) Has been cancelled
E2E Tests / E2E Tests Passed (push) Has been cancelled
Frontend Tests / Detect relevant changes (push) Has been cancelled
Frontend Tests / Run Frontend Lint, Tests, and Build (push) Has been cancelled
Frontend Tests / Frontend Tests Passed (push) Has been cancelled
feat: sort sidebar task trees by newest descendant activity (#3935)
2026-09-25 18:48:32 +01:00

6.3 KiB

status, system, requirements
status system requirements
draft ui
REQ-UI-SIDEBAR-LAST-ACTIVITY-SORT-002

Sidebar Task Tree Activity Sort System Design

Purpose and boundaries

The task system publishes each task's last_activity_at. The UI owns the saved-view ordering of a parent and its visible descendants as one sidebar tree. This design changes only the derived order used when the view's sort key is lastActivityAt. It does not change task activity publication, the saved-view wire shape, row timestamps, or other sort modes.

Requirement mapping

Requirement Design sections
REQ-UI-SIDEBAR-LAST-ACTIVITY-SORT-002 Tree activity derivation, Shared sort path, Responsive behavior, Tests

Components and responsibilities

  • TaskSwitcherItem retains each task's own lastActivityAt, updatedAt, and createdAt fields.
  • The phone task-switcher projection derives lastActivityAt from the task's status summary, falling back to that task's updatedAt and createdAt. It must not use summary freshness as activity.
  • applyView in apps/web/lib/sidebar/apply-view.ts filters tasks, builds the included parent-child map with separateSubtasks, and passes that map to applySort.
  • A pure tree-activity resolver under apps/web/lib/sidebar/ derives one maximum activity timestamp per included task subtree. Keep it separate from apply-view.ts, which is already close to the frontend file-size limit.
  • applySort uses the derived timestamp for lastActivityAt comparisons when the included map is available. The existing per-task fallback remains available for direct callers without a map.
  • Desktop useGroupedSidebarView and phone MobileTaskList continue to call the same applyView path.

Tree activity derivation

The resolver starts with the current per-task sort value: lastActivityAt, falling back to updatedAt and then createdAt. For each included task, it takes the maximum of its own value and the resolved values of all included children. This makes a root's key the newest activity anywhere in its visible tree and gives a child with descendants the same subtree semantics among its siblings.

Resolve the map in one bounded traversal with memoized subtree values and an iterative walk. A visited or active-path guard prevents malformed parent cycles from hanging the sidebar. Do not mutate task records or replace the row's own timestamp with the aggregate.

applyView calls applyFilters before separateSubtasks; therefore filtered-out descendants cannot contribute. A child whose parent is filtered out becomes a root through the existing separateSubtasks behavior. Collapse preferences only affect rendering and do not remove members from the derived map.

Shared sort path

Compare valid activity values by chronological instant, including timezone offsets and all fractional-second digits. Use the shared strict RFC3339 parser because JavaScript's Date.parse can normalize malformed wire values into a different instant. Malformed values retain the existing lexical fallback. RFC3339Nano values can have different fractional precision, so string order does not always match time order. Semantically equal instants retain stable input order, and missing values keep their existing fallback behavior.

The existing stable applySort index tiebreak handles equal aggregate values. Its direction sign gives descending and ascending order from the same maximum value. applyGroup then keeps roots and children attached and uses the sorted input; group headings keep their existing ordering rules. applySubtaskOrder and pinned-task floating still run afterward with their current precedence. Only the lastActivityAt comparator branch consumes the tree activity map; updatedAt, state, title, created, and custom order keep their existing semantics.

The parent row still receives its original TaskSwitcherItem. Its relative time describes the parent's own activity, while tree placement reflects the newest included member. No new label, icon, setting, or persisted aggregate is introduced.

Responsive behavior

The nearest phone exemplar is SessionTaskSwitcherSheet: its drawer contains MobileTaskList and the shared view editor. Desktop and phone share the derived ordering and view state. The change does not alter the phone drawer, task-row layout, navigation, touch targets, safe-area handling, or the existing single task-list scroll body.

Tests

  • A focused unit test for the resolver and applyView covers descending and ascending root order, deep descendants, siblings, equal timestamps, missing activity fallbacks, filtered-out children, orphan promotion, collapsed trees, and unchanged pin/manual/other-sort behavior.
  • A desktop Playwright scenario selects Last activity descending and shows a parent tree moving ahead of a newer standalone root after child activity, while the parent's displayed time remains its own.
  • A mobile-chrome Playwright scenario opens the existing task-switcher drawer, selects the same sort, and verifies the parent tree's order and child reachability by touch. No new mobile control or geometry is introduced.

Failure and recovery

Missing task activity uses the existing update and creation fallbacks. A missing descendant projection cannot influence the current visible tree; the next task snapshot or event recomputes the shared applyView result. No separate cache or retry path is needed.

Persistence and security

The aggregate exists only during sidebar view derivation. It adds no API field, database value, permission, or cross-workspace data access. It uses only tasks already included in the current sidebar view.