automaton/tasks/dashboard-spec.md

# Contract: Interactive Dashboard for Automaton Framework

## Goal

Build an interactive terminal dashboard that visualizes and monitors task progress within the automaton framework. The dashboard is **scope-aware**: when opened in `~/.automaton/`, it tracks framework development tasks; when opened in any project root (a project that has installed automaton), it tracks that project's tasks.

## Requirements

### 1. Scope-Aware Context Detection
- **1.1** The dashboard detects its scope by walking up the directory tree from the current working directory to find the nearest `.automaton/` folder.
- **1.2** If the nearest `.automaton/` folder is `~/.automaton/`, the dashboard operates in **framework mode** (tracks framework development).
- **1.3** If the nearest `.automaton/` folder is inside a project root, the dashboard operates in **project mode** (tracks that project's tasks).
- **1.4** The current scope is displayed in the dashboard header.

### 2. Kanban Board View (Primary View)
- **2.1** The board displays tasks as cards organized into columns by their current phase.
- **2.2** Columns map directly to the automaton task state machine:
  - **Backlog** — No artifacts (New state)
  - **Research** — Has SPEC.md (Research phase)
  - **Decomposition** — Has SPEC.md + DECOMPOSITION.md (Decomposition phase)
  - **Design** — Has SPEC.md + DESIGN.md (Design phase)
  - **Implement** — Has IMPLEMENTATION.md (Implement phase)
  - **Bug Find** — Has BUG_REPORT.md (Bug Find phase)
  - **Adversarial Bug Find** — Has ADVERSARIAL_BUG_REPORT.md (Adversarial Bug Find phase)
  - **Doc Review** — Has DOC_REVIEW.md (Doc Review phase)
  - **Referee** — Has VERDICT.md (Referee phase)
  - **Done** — VERDICT.md with PASS (Complete state)
  - **Blocked** — VERDICT.md with FAIL or NEEDS_REVIEW (Human Intervention)
- **2.3** Tasks with sub-tasks show a collapsed indicator (e.g., `[3/5]`) showing sub-task completion progress.
- **2.4** Tasks can be expanded to show sub-task details inline.
- **2.5** Columns are horizontally scrollable if they overflow the terminal width.

### 3. Task Cards
- **3.1** Each task card displays:
  - Task name (kebab-case folder name, human-readable)
  - Current phase/column
  - Time elapsed since task creation (if timestamp is available)
  - Sub-task progress indicator (if applicable)
  - Status indicator (e.g., ✅ PASS, ❌ FAIL, ⏸ BLOCKED, 🔄 IN PROGRESS)
- **3.2** Cards are selectable with arrow keys or mouse.
- **3.3** Selected card shows expanded details in a side panel or bottom panel.

### 4. Task Detail Panel
- **4.1** When a task card is selected, the detail panel shows:
  - Full task name and folder path
  - Current state/mapping to kanban column
  - List of artifacts present (SPEC.md, DESIGN.md, etc.) with status
  - Sub-task list (if applicable) with individual statuses
  - VERDICT.md content (if present)
  - BUG_REPORT.md content (if present)
- **4.2** The detail panel is resizable.
- **4.3** Navigating away from a task hides the detail panel.

### 5. Statistics View
- **5.1** A statistics view accessible via keybinding shows:
  - Total tasks count
  - Tasks per phase breakdown (bar chart or table)
  - Pass/Fail/Blocked rate
  - Average tasks completed per day (if timestamps available)
  - Current WIP (tasks in progress, not in Backlog or Done)
- **5.2** Statistics are calculated in real-time from the `tasks/` directory.

### 6. Timeline View
- **6.1** A timeline view accessible via keybinding shows:
  - Tasks arranged by their progress through phases over time
  - Wave visualization for decomposed tasks (Wave 1, Wave 2, etc.)
  - Sub-task parallel execution visualization
- **6.2** Timeline is scrollable and zoomable.

### 7. Filtering and Search
- **7.1** Filter tasks by phase/status using a filter bar.
- **7.2** Filter tasks by sub-task wave (for decomposed tasks).
- **7.3** Search tasks by name using a search bar.
- **7.4** Filters are combinable (e.g., show only "Research" tasks in Wave 2).

### 8. Keyboard Navigation
- **8.1** Arrow keys to move between columns and cards.
- **8.2** `Enter` to expand/collapse selected card or view task details.
- **8.3** `Space` to cycle through views (Board → Statistics → Timeline).
- **8.4** `q` or `Ctrl+C` to quit.
- **8.5** `?` to show keybindings help.
- **8.6** `f` to open filter bar.
- **8.7** `s` to open search bar.
- **8.8** `w` to cycle through waves (for decomposed tasks).

### 9. Auto-Refresh
- **9.1** The dashboard auto-refreshes when the `tasks/` directory changes (file system watch).
- **9.2** Auto-refresh interval: 2 seconds (configurable).
- **9.3** Manual refresh triggered by `r` key.
- **9.4** Refresh indicator in the header shows when a refresh occurs.

### 10. Configuration
- **10.1** Dashboard settings stored in `{project}/.automaton/dashboard-config.json`:
  - `auto_refresh_interval`: seconds between auto-refreshes (default: 2)
  - `default_view`: which view to show on startup ("board", "statistics", "timeline")
  - `column_width`: minimum width of each column in characters (default: 30)
  - `show_timelines`: show time elapsed on cards (default: true)
  - `theme`: color theme ("default", "dark", "light")
- **10.2** Configuration is scoped to the project (not global).

### 11. Color Theme
- **11.1** Default theme uses ANSI color codes for:
  - Backlog: gray
  - Research: blue
  - Decomposition: purple
  - Design: cyan
  - Implement: green
  - Bug Find: orange
  - Adversarial Bug Find: red (darker)
  - Doc Review: yellow
  - Referee: magenta
  - Done: green (bright)
  - Blocked: red
- **11.2** Theme is switchable via keybinding (`t` to cycle themes).

### 12. Sub-Task Visualization
- **12.1** For decomposed tasks, sub-tasks are shown as indented items under the parent task card.
- **12.2** Sub-task progress is shown as a fraction (e.g., `[3/5]` = 3 of 5 sub-tasks complete).
- **12.3** Clicking a sub-task shows its detail in the detail panel.
- **12.4** Sub-task waves are visualized with visual separation in the Timeline view.

### 13. Performance
- **13.1** Dashboard renders within 500ms of a refresh (for projects with up to 100 tasks).
- **13.2** No blocking I/O during rendering.
- **13.3** File system watch uses inotify (Linux) or kqueue (macOS) for efficient change detection.

### 14. Error Handling
- **14.1** If `tasks/` directory is missing, show a "No tasks found" message.
- **14.2** If a task artifact file is corrupted or unreadable, show a warning indicator on the card.
- **14.3** If the dashboard is opened outside any automaton project, show an error and exit gracefully.

### 15. Documentation
- **15.1** README.md in the dashboard module with usage instructions.
- **15.2** Keybindings reference accessible via `?` in the dashboard.
- **15.3** Configuration schema documented with default values.

---

## Non-Goals

- **15.1** Web UI (browser-based) — this is terminal-only (TUI).
- **15.2** Real-time collaboration — single-user only.
- **15.3** Task creation/editing — dashboard is read-only for task state.
- **15.4** Notification system — no push notifications or alerts.
- **15.5** Calendar integration — no date-based scheduling.
- **15.6** Integration with external PM tools — standalone only.

---

## Acceptance Criteria

- [ ] Dashboard detects scope (framework vs. project) correctly based on cwd
- [ ] Board view displays all tasks in correct Kanban columns based on state machine
- [ ] Task cards show name, phase, status, and sub-task progress
- [ ] Task detail panel shows full task information when selected
- [ ] Statistics view shows correct counts per phase and pass/fail rates
- [ ] Timeline view shows task progress and wave structure
- [ ] Filter bar filters tasks by phase and wave
- [ ] Search bar finds tasks by name
- [ ] All 11 keyboard bindings (Enter, Space, q, ?, f, s, w, t, r) work correctly
- [ ] Auto-refresh works on file system changes with 2-second interval
- [ ] Dashboard configuration file is created and read correctly
- [ ] Color themes cycle correctly with 3 themes
- [ ] Sub-task visualization shows progress fraction and expandable details
- [ ] Dashboard renders within 500ms for 100 tasks
- [ ] Error handling works for missing tasks/ directory and corrupted artifacts
- [ ] Documentation includes usage instructions and keybindings reference

---

## Risks & Mitigations

- **Risk 1**: Terminal rendering performance degrades with many tasks
  - Mitigation: Implement virtual rendering (only render visible columns/cards), lazy-load task details
- **Risk 2**: File system watch conflicts with agent writing artifacts
  - Mitigation: Use debounced file system events, handle partial writes gracefully
- **Risk 3**: Task state determination is inconsistent with Orchestrator
  - Mitigation: Use the same state machine logic as `orchestrate.md` for determining task states
- **Risk 4**: Dashboard breaks when automaton framework is upgraded
  - Mitigation: Dashboard reads state from the same artifacts the Orchestrator reads; no hardcoded state machine logic — it derives from artifact presence

---

## Notes

- The dashboard should be a separate module under `~/.automaton/` (e.g., `~/.automaton/dashboard/`) so it can be upgraded independently.
- The dashboard uses the same layered file system approach as the Orchestrator — it reads from project's `.automaton/` first, then falls back to global `~/.automaton/`.
- Task names in the dashboard should be human-readable. The kebab-case folder name (e.g., `add-user-auth`) should be converted to a display name (e.g., "Add User Auth") by replacing hyphens with spaces and capitalizing.
- The dashboard is a **read-only** view of task state — it does not modify or create artifacts. All task lifecycle operations continue through the Orchestrator.

---

## Stop Condition

When all checkboxes are checked and the dashboard is fully functional, output "CONTRACT_MET" and stop.