automaton/tasks/dashboard-spec.md

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.