gitea
79b783864e
- Rewrite vram_detect in Python with fixed config parsing and 10KB read limit
- Add pytest suite (72 tests) covering dashboard core, app security, and VRAM
- Standardize all prompts to .automaton/tasks/{task-name}/ path
- Reconcile dashboard spec with web implementation; remove themes.py
- Remove half-implemented refresh.py file watcher
- Harden dashboard static-file serving and task-name validation
- Add uncommitted-change guard to update.sh and real Gitea URLs
- Add AGENTS.md, Gitea CI workflow, and template documentation
169 lines
7.4 KiB
Markdown
169 lines
7.4 KiB
Markdown
# 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.
|