Files
kandev/docs/specs/tasks/wip-limit-pull-system.md
T
2026-07-13 12:18:57 +01:00

65 lines
2.5 KiB
Markdown

---
status: building
---
# WIP Limit Pull System
## What
Workflow steps can define a work-in-progress limit and an optional feeder step.
`wip_limit` is a non-negative integer on each workflow step. `0` means unlimited
and preserves existing behavior. `pull_from_step_id` is empty by default; when it
is set, it must reference another step in the same workflow.
When a limited step is full, manual moves, drag/drop moves, API moves, MCP moves,
bulk moves, and workflow-engine transitions into that step are rejected instead
of overfilling the step. Same-step reordering is allowed.
When a task leaves a limited step that has a feeder configured, Kandev attempts
to pull queued tasks from the feeder into the vacated step until the step reaches
its limit or no feeder task remains. Pull order is deterministic: position ASC,
priority rank (`critical`, `high`, `medium`, `low`, none/unknown), created time
ASC, then task id ASC.
The Kanban board shows the current task count for unlimited steps and
`occupied/limit` for limited steps. If legacy or concurrent data leaves a step
over limit, the board shows the over-limit count as a warning state.
## Why
Kanban teams often work by pulling the next highest-priority task when capacity
opens instead of pushing arbitrary tasks forward. Without a step-level limit,
Kandev can start too many tasks in the same workflow stage and cannot model a
simple queue-to-work pull system.
## Data Model
`workflow_steps` stores:
- `wip_limit INTEGER NOT NULL DEFAULT 0`
- `pull_from_step_id TEXT NOT NULL DEFAULT ''`
Workflow step API responses, workflow template definitions, workflow export and
import data, task DTOs, WebSocket payloads, and MCP workflow-step config tools
all preserve these fields.
Workflow export stores the pull source portably as a step position instead of an
instance-specific UUID. Import maps that position back to the newly-created step
ID.
## Failure Modes
Moving into a full limited step returns a conflict with a user-visible message
that includes the target step and limit. Optimistic UI moves must roll back.
If a pull attempt races with another actor that fills the slot, the pull attempt
stops without overfilling the target step.
Deleting a step clears any `pull_from_step_id` that points at it.
## Scope Note
`agent_profiles.max_concurrent_sessions` is related but separate. This feature
adds per-step WIP limits and pull behavior. Kanban enforcement of profile-level
session caps remains tracked separately unless implemented in the same change.