# Queues and Dependency Graph UI Specification **Status:** Canonical UI specification. **Purpose:** Define the Queues page and the visual dependency graph used to inspect Plans, Tasks, execution order, and blockers. ## 1. Primary user questions The Queues experience must answer, without requiring raw logs or provider internals: ```text What is running now? What goes next? Why does it go next? What is blocked? What does it depend on? What depends on it? Can I move it? If not, why not? Where does this work sit in the wider Project? ``` ## 2. Page structure The Queues page is a first-class Operations surface separate from system Health. Recommended primary navigation: ```text OPERATIONS Queues Health ``` The Queues page has two peer views of the same underlying work/dependency model: ```text [ Queue ] [ Graph ] ``` Neither view is a decorative visualization. Both are operational navigation surfaces. ## 3. Queue view ### 3.1 Sections Default queue view groups work into: ```text RUNNING READY / NEXT BLOCKED WAITING ON YOU PAUSED RECENTLY COMPLETED ``` Within `READY / NEXT`, the first item must be visually explicit as the current next dispatch candidate. ### 3.2 Queue row content Each Task row should show at minimum: - Task title; - owning Plan; - linked Goal(s) where useful; - readiness state; - queue position / priority; - dependency summary; - blocking prerequisite when blocked; - whether user action is required; - current or next Factory action when applicable. The entire primary row surface opens the Task. Do not add a redundant `Open Task` button. The Plan name is independently clickable and opens the Plan. ### 3.3 Dependency affordance Tasks with dependencies must never hide that fact. Show a compact dependency affordance such as: ```text Depends on 2 ``` or when blocked: ```text Blocked by 2 prerequisites ``` Selecting or hovering/focusing the affordance reveals the concrete prerequisite Tasks and their Plans. A Task that is blocking other work should also expose: ```text Blocks 3 ``` This lets the user recognize leverage points in the queue. ## 4. Dependency-aware drag and drop Drag/drop communicates constraints **before** the user commits the move. ### 4.1 Legal range preview When drag starts, AWP visually distinguishes: - legal drop positions; - illegal positions caused by prerequisites; - illegal positions caused by dependents; - policy-locked positions. The preferred interaction is a visible legal range around the dragged Task rather than waiting until drop to display an error. Example: ```text Task C Depends on: Task A, Task B Blocks: Task F legal placement: after B before F ``` ### 4.2 Invalid drop behavior If the user drags Task C above Task B when C depends on B: 1. the illegal drop slot is visibly unavailable; 2. the dependency edge / prerequisite row is emphasized; 3. an inline explanation appears, for example: ```text Cannot place "Build release UI" before "Expose release API". This Task depends on it. ``` 4. releasing the pointer does not mutate queue order; 5. focus remains predictable for keyboard and assistive-technology users. Do not silently snap without explanation. ### 4.3 Keyboard parity Every drag/drop operation has keyboard-accessible move commands: ```text Move up Move down Move before... Move after... ``` Invalid operations use the same dependency explanation as pointer interaction. ## 5. Graph view: compound directed dependency graph The required visualization is a **compound directed dependency graph (DAG)**. This is preferable to a generic node chart because it must represent both hierarchy and dependency flow: ```text Project contains Plans contain Tasks Task -> Task dependency edges ``` Plans are expandable/collapsible group containers. Tasks are nodes inside those Plan groups. Hard dependencies are directed edges from prerequisite to dependent. ### 5.1 Direction Default edge semantics: ```text Prerequisite ---> Dependent ``` The visual legend must state this explicitly. A left-to-right layout is preferred for dependency progression because it makes long prerequisite chains easier to scan. A top-to-bottom alternative may be used responsively when it produces materially better legibility. ### 5.2 Plan groups Each Plan is a visible compound group containing its Tasks. Plan group header shows: - Plan title; - Goal linkage where useful; - progress / state summary; - blocked Task count; - running Task count. Clicking the Plan header opens the Plan page. Plans can collapse to reduce graph density while preserving cross-plan edges through an aggregate Plan boundary marker. ### 5.3 Task nodes Each Task node shows compact operational state: ```text Task title state small dependency/blocker indicator ``` Clicking the Task opens the Task page. Keyboard focus and Enter/Space provide equivalent navigation. ### 5.4 Edge types Initial graph distinguishes at least: ```text HARD DEPENDENCY ``` Additional relationship types may be added later, but they must not be visually conflated with execution dependencies. Cross-plan edges are fully supported and should be visually obvious. ### 5.5 Highlight behavior Selecting a Task highlights: - the selected Task; - all direct prerequisites; - all direct dependents; - optionally the full upstream/downstream chain through a secondary control. Non-related graph content is de-emphasized, not removed. Selecting a Plan highlights its Tasks and cross-plan edges entering or leaving the Plan. ### 5.6 Navigation and filtering Graph controls should support: - search by Plan / Task title; - filter by state; - filter to blocked work; - filter to one Goal; - show only upstream dependencies of selected node; - show only downstream dependents; - expand all / collapse all Plans; - reset view. The graph should preserve the current Project scope by default. ## 6. Graph and queue synchronization Queue and Graph are two projections of one source of truth. When a Task is selected in Queue view and the user switches to Graph view, preserve Task selection where practical. When a dependency is created or removed, both views update from the same domain state. Queue priority does not become an edge. Dependency edges express legality; queue order expresses preferred dispatch order among legal choices. ## 7. Empty / dense / blocked states ### Empty Explain that no queueable work exists and link to the relevant planning surface. ### Dense graph Progressive disclosure is mandatory: - collapse Plans; - focus subgraphs; - search; - upstream/downstream isolation; - state filtering. Do not shrink hundreds of nodes into an unreadable poster. ### Blocked chain If a selected Task is blocked transitively, show the shortest or most relevant prerequisite chain, for example: ```text Translate modal E2E waits on Worker harness waits on staging credentials ``` ## 8. Project Overview integration The Project Overview should include a compact operational card for: ```text NEXT TO FACTORY ``` showing the first dispatch candidate plus nearby blocked/waiting context. It links to Queues rather than reproducing the full queue. The Overview's dominant content remains current Goals, attention required, blockers, current Plans/FactoryRuns, next work, and recent progress. Vision and Settings remain secondary tab-level destinations. ## 9. Accessibility - Never encode dependency/blocking state by color alone. - Every graph edge has a text-equivalent relationship available to assistive technology. - Nodes are keyboard navigable. - Graph selection has visible focus. - Drag/drop has keyboard parity. - Invalid reordering announces the specific prerequisite/dependent that prevents the move. - Zoom/pan must not trap keyboard focus. ## 10. Acceptance criteria - A user can identify the next dispatch candidate in one scan. - A Task with dependencies visibly communicates that fact in Queue view. - Dragging a Task before an unmet prerequisite is prevented before mutation and explained. - The Graph view displays Plans as groups and Tasks as nodes with directed dependency edges. - Cross-plan dependencies remain understandable. - Clicking a Plan navigates to that Plan; clicking a Task navigates to that Task. - Selecting a Task makes upstream and downstream relationships visually obvious. - Dense projects remain usable through collapse, focus, search, and filtering. - Queue and Graph never disagree about dependency state.