Files
kandev/docs/plans/queued-task-moves/plan.md
T
2026-08-23 17:34:52 +00:00

281 lines
12 KiB
Markdown

---
spec: docs/specs/tasks/system-design/wip-limit-pull-system.md
created: 2026-08-12
status: completed
---
# Implementation Plan: Queued Task Moves
## Overview
Make a task move express readiness for the selected workflow step even when
that step has reached its WIP limit. The move succeeds, places the task in the
destination column, and marks it queued without consuming WIP. Capacity later
admits destination-resident queued tasks before pulling work from a configured
feeder.
The UI makes this state explicit. Limited Kanban columns show separate active
and queued areas, and the task sidebar shows a distinct WIP queue icon. Hovering
or focusing the icon discloses the task's one-based queue position, total, and
destination step on desktop and touch layouts.
No new persistence fields are required. The implementation reuses
`wip_admitted`, `queued_for_step_id`, and `queued_at`, but changes task moves
from capacity rejection to atomic destination admission.
## Confirmed Current Behavior
- `task/service.MoveTaskWithOptions` validates target WIP before the update and
returns a typed capacity conflict when the destination is full.
- The repository has atomic capacity updates and queued-task promotion, but no
atomic move operation that chooses admitted or queued placement.
- Bulk moves prevalidate capacity, so the whole request fails instead of
admitting available tasks and queueing the remainder.
- The workflow engine has a separate transition store path that also uses the
capacity-rejecting update.
- `task.moved` immediately runs both source `on_exit` and destination
`on_enter`. `task.queue_promoted` currently only handles auto-start, so it
cannot complete deferred destination entry for a queued move.
- Same-step overflow cards are visible, but the Kanban column does not separate
admitted and queued cards.
- The sidebar's existing queued count represents pending agent prompts. It is
unrelated to WIP admission and must remain visually and semantically
distinct.
## Behavioral Contract
- Moving to an unlimited or non-full limited step admits the task immediately.
- Moving to a full limited step succeeds and places the task in that step with
`wip_admitted = false`, `queued_for_step_id` equal to the step, and a durable
`queued_at` value.
- A move never redirects through `pull_from_step_id`. Feeders keep their
existing automatic-intake behavior.
- Destination-resident queued tasks are promoted before feeder-resident work.
Queue position uses the same deterministic ordering as promotion.
- A queued move runs source exit once at move time. Destination entry,
terminal-state effects, context reset, plan-mode behavior, and auto-start run
once after promotion.
- Moving an already queued task cancels its old queue/deferred-launch state and
applies admission at the new destination.
- Stepper, drag/drop, move menu, bulk, HTTP, WebSocket, MCP, approval, and
workflow-engine transition paths share the contract.
- An automatic workflow transition into a full step commits the task in that
destination queue. Destination entry waits for promotion.
- The move response and task events expose committed admission metadata.
## Backend Design
### Atomic move admission
Add one repository operation analogous to creation admission. In a single
write transaction it locks/checks the target step, updates the task as admitted
when capacity exists, or updates it as destination-resident queued when full.
It returns the committed placement so the service does not infer the result
from a stale capacity read.
For unlimited steps, preserve the ordinary update path and normalize the task
to admitted with no queue destination. For limited steps, count only admitted,
active, non-ephemeral occupants. A race for the final slot admits one task and
queues the other; neither request returns a WIP conflict.
`MoveTaskWithOptions` resolves/validates the destination, clears obsolete queue
and deferred-launch state, applies the atomic admission update, synchronizes
only effects valid for the committed placement, publishes the task update and
move event, and reconciles the vacated source. Bulk moves process each task
through the same admission boundary rather than pre-rejecting the batch.
### Event and lifecycle boundary
Extend `task.moved` data with the committed admission state. For a queued move,
the orchestrator performs source exit and deliberately skips destination entry
and target-derived state. For an admitted move, existing exit/entry behavior
continues.
Extend queue promotion handling into the single destination-entry boundary.
Promotion applies target state, runs `on_enter`, performs context reset and
terminal behavior, and handles auto-start exactly once. This must support tasks
with an existing session and tasks without one. Replayed or duplicate events
must not repeat entry effects.
The workflow engine transition store uses the same admission result and event
contract. It must not leave the engine state ahead of a destination that has
not admitted the task.
### Queue selection
Keep the existing deterministic comparator within a queue. Change selection
to exhaust destination-resident queued candidates before considering feeder
candidates. This gives the displayed one-based position the same meaning as
the next promotion order.
## Frontend Design
### Shared queue model
Add a pure queue helper that:
- identifies destination-resident queued tasks;
- sorts them with the backend promotion order;
- returns one-based position, total, and destination title;
- partitions a limited column into admitted and queued cards.
Use it from the Kanban and sidebar so both surfaces report the same order. The
existing queued-prompt count remains a separate field and badge.
### Kanban column
Within the existing column scroll owner, render admitted cards first and a
visually distinct queued area second. Show the queued-area label and count only
when the queue is non-empty. Keep the header WIP metric as `admitted/limit`.
Drag/drop into a full step succeeds and the card appears in the queued area.
The shared `KanbanColumn` preserves desktop and focused mobile-column parity.
Do not add nested vertical scrolling or horizontal page overflow.
### Sidebar
Derive queue positions from workspace workflow snapshots in
`useWorkspaceSidebarTasks` and carry a distinct WIP queue object through the
desktop and mobile item mappers. `TaskItem` renders the same semantic chip in
both task switchers.
The sidebar renders one compact queue icon on all pointer types. Its tooltip
states `Position N of M in STEP queue`, and the focusable trigger also supports
touch and keyboard users. The icon is status information, not a new action.
All new copy is localized in English, pseudo, Portuguese, and Simplified
Chinese catalogs. Queue helper and component tests cover ordering, render/hide
rules, accessibility, the separate queued-prompt badge, and mobile-safe
presentation.
### Workflow step settings
Keep `Pull from` optional. Add an info tooltip beside it that separates three
behaviors:
- Destination-resident queued tasks receive admission first.
- Kandev then pulls eligible tasks from the selected feeder when capacity is
available.
- Direct moves and automatic workflow transitions queue in the destination and
do not require a feeder.
The help also states that new tasks targeting a full step uses the selected
feeder. The tooltip is available by hover or keyboard focus on desktop and by
tap or focus on mobile, so the contract does not depend on pointer hover.
## Responsive and Mobile Contract
- **Entry point:** the existing focused mobile Kanban column and task-switcher
sheet.
- **Nearest pattern:** `MobileColumnTabs`, `SwipeableColumns`, shared
`KanbanColumn`, and shared `TaskItem`.
- **Presentation:** inline column section and inline status chip; the workflow
settings explanation is a compact info tooltip, with no modal, drawer, or
mobile-only route.
- **Scroll ownership:** the existing Kanban column and task-switcher sheet keep
their single scroll owners.
- **Touch behavior:** queue position is visible without hover; the workflow
explanation opens from the existing info icon by tap or focus.
- **Parity:** move, queue visibility, position, and promotion are available on
desktop and mobile.
## Test Strategy
### Backend
- Atomic move admission admits within capacity and queues overflow under
synchronized concurrency.
- Bulk movement fills available slots and queues the remainder.
- Moving queued work away clears old queue/deferred state and reapplies the new
target's admission rule.
- Destination-resident tasks promote before feeder tasks in deterministic
order.
- Queued moves run source exit once and destination entry only on promotion,
for existing-session and no-session cases.
- Terminal, auto-start, plan-mode, and context-reset effects are deferred.
- Service, approval, HTTP, WebSocket, MCP, and workflow-engine paths return
queued success instead of WIP conflict.
### Frontend
- The shared helper matches backend ordering and calculates stable one-based
positions.
- Kanban columns partition admitted and queued cards and preserve admitted WIP
counts.
- Sidebar queue status is separate from queued prompts, localized, accessible,
and correct in desktop and touch presentations.
### Browser E2E
- Desktop: use the UI to move a task into a full step, verify queued placement,
column partition, sidebar tooltip position, then free capacity and verify
promotion.
- Mobile Chrome: repeat the move in the focused-column flow, verify the queue
icon tooltip, promotion, touch usability, and no page-level horizontal
overflow.
- Seed prerequisite workflow/tasks through the API; perform and assert the
behavior under test through the UI.
## Public Documentation
Update `docs/public/tasks-and-workflows.md` and
`docs/public/workflow-tips.md`. Replace the manual-move conflict rule with
destination queue admission, explain destination queue priority over feeders,
and describe the Kanban/sidebar queue indicators.
## Implementation Waves
All tasks are sequential. The frontend consumes the finalized backend ordering
and lifecycle contract, and E2E/doc work validates the complete behavior.
- [x] [Task 01: Add atomic move admission](task-01-atomic-move-admission.md)
- [x] [Task 02: Defer destination lifecycle until promotion](task-02-deferred-destination-lifecycle.md)
- [x] [Task 03: Add frontend queue guidance](task-03-kanban-queue-sections.md)
- [x] [Task 04: Show sidebar queue position](task-04-sidebar-queue-position.md)
- [x] [Task 05: Complete feature verification](task-05-e2e-and-documentation.md)
## Implementation Progress
Tasks 01 through 05 are implemented. The backend now commits admitted or
destination-queued placement atomically, defers destination lifecycle work
until promotion, and prioritizes destination-resident queues over feeder work.
The web client shows the same queue order in Kanban and desktop/mobile task
switchers, with localized `Pull from` guidance in an info tooltip. The initial
Kanban boot payload now includes WIP limits and task admission metadata, and the
sidebar uses an accessible queue icon with a position tooltip. Review hardening
also keeps replay tokens available after prerequisite failures, preserves state
changes in the promotion event path, and skips failed fallback candidates while
filling capacity.
Focused backend and frontend checks pass. The broad backend regression gate,
managed browser checks, public-doc validation, and final diff review are
recorded in Task 05.
No task is marked `parallel-safe`; this package does not authorize subagents.
## Environment Prerequisite
If `apps/node_modules` is absent, run `pnpm install --frozen-lockfile` from
`apps/` before frontend tests. Do not change the lockfile.
## Risks
- Applying destination state before admission can complete, reset, or start a
task while it is still queued.
- Running source exit again during promotion can duplicate messages or agent
actions. Event data must distinguish move placement from promotion entry.
- A non-atomic count-then-update can still over-admit under concurrent moves.
- Mixing destination and feeder candidates before selection makes the sidebar
position disagree with actual promotion priority.
- Reusing the sidebar's `queuedCount` field would confuse WIP queue state with
pending agent prompts.
- Bulk move ordering must be deterministic enough to make which tasks are
admitted versus queued testable.
## Out of Scope
- User-driven queue reordering.
- Dragging cards within the queued section to change priority.
- Recursive feeder routing.
- Changes to profile-wide agent-session concurrency.