# Contract: Interactive Web Dashboard for Automaton Framework

## Goal

Build an interactive web 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 phase groups:
  - **Planning** — Backlog, Research, Decomposition
  - **Design** — Design, Test Design
  - **Implementation** — Implement
  - **Verification** — Bug Find, Adversarial Bug Find, Doc Review, Referee
  - **Blocked** — VERDICT.md with FAIL or NEEDS_REVIEW
  - **Resolution** — VERDICT.md with PASS
- **2.2** Tasks with sub-tasks show a progress indicator (e.g., `[3/5]`) showing sub-task completion progress.
- **2.3** Columns are horizontally scrollable if they overflow the viewport.

### 3. Task Cards
- **3.1** Each task card displays:
  - Task name (kebab-case folder name, human-readable)
  - Current phase
  - Sub-task progress indicator (if applicable)
  - Status indicator (✅ PASS, ❌ FAIL/BLOCKED, 🔄 IN PROGRESS)
  - Review status badge
- **3.2** Cards are clickable to open a detail panel.

### 4. Task Detail Panel
- **4.1** When a task card is clicked, a modal panel shows:
  - Full task name
  - Current state and phase group
  - List of artifacts present with status
  - Sub-task list with individual statuses
  - Review buttons (approve / request changes)
  - VERDICT.md content (if present)
  - BUG_REPORT.md content (if present)
  - SPEC.md content (if present)

### 5. Statistics View
- **5.1** A statistics view accessible via tab or keybinding shows:
  - Total tasks count
  - Tasks per phase group and per state (bar charts)
  - Pass/Fail/Blocked rate
  - Current WIP (tasks in progress)
  - Sub-task progress
  - Wave progress

### 6. Timeline View
- **6.1** A timeline view shows each task's progress through the lifecycle.
- **6.2** Sub-task completion is shown per task.

### 7. Filtering and Search
- **7.1** Filter tasks by phase/status.
- **7.2** Filter tasks by review status.
- **7.3** Filter tasks by whether they have sub-task waves.
- **7.4** Search tasks by name.

### 8. Keyboard Navigation
- **8.1** `Space` cycles through views (Board → Statistics → Timeline).
- **8.2** `1`, `2`, `3` switch to Board/Stats/Timeline views.
- **8.3** `t` cycles themes (default → dark → light).
- **8.4** `r` manually refreshes data.
- **8.5** `f` toggles the filter bar.
- **8.6** `s` focuses the search input.
- **8.7** `Esc` closes modals and clears search.
- **8.8** `?` shows keybindings help.

### 9. Auto-Refresh
- **9.1** The dashboard auto-refreshes via client-side polling (configurable interval).
- **9.2** Default auto-refresh interval: 2 seconds.
- **9.3** Manual refresh triggered by `r` key or refresh button.

### 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 elapsed time indicators (default: true)
  - `theme`: color theme ("default", "dark", "light")

### 11. Color Theme
- **11.1** Three themes are supported via CSS variables: default (dark), dark, light.
- **11.2** Theme is switchable via keybinding (`t`) or configuration.

### 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]`).
- **12.3** Sub-task statuses are shown in the detail panel and timeline.

### 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.

### 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.
- **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

- Terminal/TUI implementation.
- Real-time collaboration — single-user only.
- Task creation/editing — dashboard is read-only for task state.
- Notification system — no push notifications or alerts.
- Calendar integration — no date-based scheduling.
- 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 phase groups based on state machine
- [ ] Task cards show name, phase, status, review badge, and sub-task progress
- [ ] Task detail panel shows full task information when selected
- [ ] Statistics view shows correct counts per phase group and state
- [ ] Timeline view shows task progress
- [ ] Filter bar filters tasks by phase, review status, waves, and search
- [ ] Keyboard bindings `Space`, `1`, `2`, `3`, `t`, `r`, `f`, `s`, `Esc`, `?` work correctly
- [ ] Auto-refresh works with configurable interval
- [ ] Dashboard configuration file is created and read correctly
- [ ] Color themes cycle correctly with 3 themes
- [ ] Sub-task visualization shows progress fraction and statuses
- [ ] 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**: Web rendering performance degrades with many tasks
  - Mitigation: Efficient DOM updates, client-side filtering, pagination if needed
- **Risk 2**: Concurrent reads while agent writes artifacts
  - Mitigation: Handle read errors gracefully; agents write atomically where possible
- **Risk 3**: Task state determination is inconsistent with Orchestrator
  - Mitigation: Use the same artifact-based state machine logic as `orchestrate.md`
- **Risk 4**: Dashboard breaks when automaton framework is upgraded
  - Mitigation: Dashboard reads state from the same artifacts the Orchestrator reads

---

## Notes

- The dashboard is a separate module under `~/.automaton/automaton/dashboard/`.
- The dashboard uses the same layered file system approach as the Orchestrator.
- Task names in the dashboard should be human-readable.
- The dashboard is a **read-only** view of task state.

---

## Stop Condition

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