@sugar-crash-studios/vibe-forge 0.4.0

package/tasks/completed/FEATURE-001a-dashboard-wireframes.md

@@ -0,0 +1,162 @@
+---
+id: FEATURE-001a
+title: "Dashboard wireframes and UX specification"
+type: design
+priority: critical
+status: completed
+created_at: 2026-01-16T21:00:00Z
+created_by: planning-hub
+assigned_to: pixel
+parent_task: FEATURE-001
+completed_at: 2026-01-16T22:30:00Z
+completed_by: pixel
+---
+
+# Dashboard Wireframes and UX Specification
+
+## Summary
+
+Create wireframes and UX specification for the Dashboard MVP. This guides Anvil's implementation and ensures a cohesive user experience.
+
+## Deliverables
+
+### 1. Main Dashboard Wireframe
+- Three-panel layout (Tasks, Agents, Notifications)
+- Issues/Actionable panel placement
+- Header with settings and theme toggle
+- Responsive breakpoints (desktop, tablet, mobile)
+
+### 2. Interaction Specifications
+- Task card click -> detail view or expand?
+- Agent status -> what info on hover?
+- Notification -> dismiss behavior?
+- Dispatch button -> confirmation or immediate?
+
+### 3. State Documentation
+- Empty states ("No pending tasks")
+- Loading states (skeleton or spinner?)
+- Error states (connection lost, API error)
+- Success states (task dispatched)
+
+### 4. Actionable Items UX
+- How issues are displayed
+- Dispatch button placement and style
+- Confirmation flow (if any)
+- Feedback after dispatch
+
+### 5. Dark Mode Specification
+- Color palette (backgrounds, text, accents)
+- Ensure WCAG AA contrast ratios
+- Agent colors visible in dark mode
+
+### 6. Accessibility Notes
+- Keyboard navigation flow
+- Focus indicators
+- Screen reader announcements
+- Skip links if needed
+
+## User Flows to Document
+
+1. **Morning Check-in**: Open dashboard -> scan issues -> dispatch if needed
+2. **Dispatch Flow**: See issue -> click dispatch -> confirm -> see task created
+3. **Monitor Progress**: Watch agent status -> see task move through columns
+4. **Re-open Dashboard**: Dashboard was closed -> `forge dashboard` -> browser opens
+
+## Output Format
+
+Create wireframes in:
+- ASCII art (for task file / markdown docs)
+- Or simple HTML/CSS mockup in `docs/wireframes/`
+- Or describe in detail with component specifications
+
+## Design Principles (from brainstorm)
+
+1. **Progressive Disclosure** - summary first, details on demand
+2. **Immediate Feedback** - every action confirms within 100ms
+3. **Error Prevention** - dangerous actions require confirmation
+4. **Mobile Responsive** - status checks from anywhere
+
+## Acceptance Criteria
+
+- [x] Main dashboard wireframe complete
+- [x] All states documented (empty, loading, error, success)
+- [x] Actionable items dispatch flow specified
+- [x] Dark mode colors defined
+- [x] Accessibility considerations documented
+- [x] Anvil can implement without ambiguity
+
+## Completion Summary
+
+### Output Created
+
+The comprehensive UX specification was created at: `docs/wireframes/dashboard-mvp.md`
+
+### What Was Delivered
+
+1. **Main Dashboard Wireframe (ASCII Art)**
+   - Desktop layout with 3-panel top row (Tasks 40%, Agents 30%, Notifications 30%)
+   - Full-width Issues panel at bottom (the killer feature)
+   - Header with logo, settings, and theme toggle
+   - Footer with connection status
+
+2. **Component Specifications**
+   - Header component with logo, title, settings, theme toggle
+   - Tasks panel with filter tabs (Pending/Progress/Review/Done) and task cards
+   - Agents panel with status indicators and progress bars
+   - Notifications panel with type icons and action buttons
+   - Issues panel with category badges and dispatch buttons
+
+3. **Interaction Flows (4 Documented)**
+   - Morning Check-in Flow
+   - Dispatch Agent Flow (detailed step-by-step)
+   - Task Card Expansion Flow
+   - Theme Toggle Flow
+
+4. **State Documentation**
+   - Loading states: Skeleton animation with shimmer effect
+   - Empty states: Friendly messages with icons for each panel
+   - Error states: Connection lost banner, panel-specific errors, dispatch failures
+   - Success states: Toast notifications with actions
+
+5. **Actionable Items UX (The Killer Feature)**
+   - Issue card anatomy with category icons
+   - Dispatch button states (default, hover, active, loading, disabled)
+   - Confirmation modal design
+   - Post-dispatch feedback sequence (0ms -> 200-500ms timeline)
+
+6. **Dark Mode Specification**
+   - Complete color palette with 15+ tokens
+   - Agent colors optimized for dark backgrounds
+   - Light mode alternative palette
+   - WCAG AA contrast ratios verified
+   - CSS variable implementation example
+
+7. **Accessibility**
+   - Keyboard navigation with global and panel shortcuts
+   - Focus indicators (2px outline with offset)
+   - ARIA live regions for announcements
+   - Semantic landmarks
+   - Color-independent information design
+   - Skip links
+
+8. **Responsive Design**
+   - Desktop (1200px+): Full 3-column layout
+   - Tablet (768-1199px): 2-column stacked layout
+   - Mobile (320-767px): Single column with tab bar
+
+9. **Keyboard Shortcuts**
+   - Quick reference card design
+   - Navigation: 1-4 for panels, j/k for lists
+   - Actions: d for dispatch, r for refresh, t for theme
+
+10. **Implementation Notes for Anvil**
+    - Priority order for implementation
+    - Animation guidelines with durations and easing
+    - Testing checklist
+
+## References
+
+- Parent feature: `tasks/pending/FEATURE-001-dashboard-mvp.md`
+- Brainstorm: `context/feature-brainstorm.md`
+- Pixel personality: `agents/pixel/personality.md`
+- **Output file: `docs/wireframes/dashboard-mvp.md`**

package/tasks/completed/IMPL-007a-daemon-notifications-module.md

@@ -0,0 +1,82 @@
+---
+id: IMPL-007a
+title: "Extract daemon notifications module"
+type: implementation
+priority: medium
+assigned_to: anvil
+created_at: 2026-01-17T10:00:00Z
+created_by: architect
+parent_task: ARCH-007
+---
+
+## Summary
+
+Extract notification-related functions from `forge-daemon.sh` into a dedicated module `bin/lib/daemon/notifications.sh`.
+
+## Context
+
+See ADR-001: docs/architecture/decisions/ADR-001-daemon-modularization.md
+
+## Functions to Extract
+
+From `bin/forge-daemon.sh`, move these functions:
+
+1. `sanitize_notification_message()` (lines 122-134)
+2. `notify()` (lines 136-155)
+3. `send_system_notification()` (lines 158-192)
+4. `check_new_pending_tasks()` (lines 194-254)
+5. `check_attention_needed()` (lines 257-288)
+
+## Implementation
+
+### 1. Create module file
+
+```bash
+#!/usr/bin/env bash
+# bin/lib/daemon/notifications.sh
+#
+# Daemon notification functions
+#
+# Dependencies: colors.sh, constants.sh
+# Globals required: FORGE_ROOT, NOTIFY_FILE, NOTIFIED_FILE, LOG_FILE,
+#                   TASKS_PENDING, TASKS_NEEDS_CHANGES, TASKS_ATTENTION
+
+# Prevent double-sourcing
+[[ -n "${_DAEMON_NOTIFICATIONS_LOADED:-}" ]] && return 0
+_DAEMON_NOTIFICATIONS_LOADED=1
+
+# [paste functions here, maintaining exact implementation]
+```
+
+### 2. Update forge-daemon.sh
+
+Add after existing library sources:
+```bash
+# shellcheck source=lib/daemon/notifications.sh
+source "$SCRIPT_DIR/lib/daemon/notifications.sh"
+```
+
+Remove the extracted functions from forge-daemon.sh.
+
+### 3. Test
+
+```bash
+# Verify daemon still starts
+./bin/forge-daemon.sh start
+./bin/forge-daemon.sh status
+./bin/forge-daemon.sh stop
+
+# Run existing tests
+npm test
+```
+
+## Acceptance Criteria
+
+- [ ] `bin/lib/daemon/notifications.sh` created with all 5 functions
+- [ ] Module has proper header with dependencies documented
+- [ ] Module has double-source protection
+- [ ] `forge-daemon.sh` sources the new module
+- [ ] Functions removed from `forge-daemon.sh`
+- [ ] Daemon starts/stops/status works correctly
+- [ ] All existing tests pass
+- [ ] ShellCheck passes on new module

package/tasks/completed/IMPL-007b-daemon-sync-module.md

@@ -0,0 +1,71 @@
+---
+id: IMPL-007b
+title: "Extract daemon sync module"
+type: implementation
+priority: medium
+assigned_to: furnace
+created_at: 2026-01-17T10:00:00Z
+created_by: architect
+parent_task: ARCH-007
+depends_on: []
+---
+
+## Summary
+
+Extract agent status synchronization functions from `forge-daemon.sh` into `bin/lib/daemon/sync.sh`.
+
+## Context
+
+See ADR-001: docs/architecture/decisions/ADR-001-daemon-modularization.md
+
+## Functions to Extract
+
+From `bin/forge-daemon.sh`:
+
+1. `sync_agent_status_to_db()` (lines 291-328)
+2. `build_worker_status()` (lines 331-370)
+
+## Implementation
+
+### 1. Create module file
+
+```bash
+#!/usr/bin/env bash
+# bin/lib/daemon/sync.sh
+#
+# Agent status synchronization functions
+#
+# Dependencies: json.sh, database.sh, constants.sh
+# Globals required: FORGE_ROOT, FORGE_DB, AGENT_STATUS_DIR, LOG_FILE,
+#                   STALE_STATUS_THRESHOLD
+
+# Prevent double-sourcing
+[[ -n "${_DAEMON_SYNC_LOADED:-}" ]] && return 0
+_DAEMON_SYNC_LOADED=1
+
+# [paste functions here]
+```
+
+### 2. Update forge-daemon.sh
+
+Add source line and remove extracted functions.
+
+### 3. Test
+
+```bash
+./bin/forge-daemon.sh start
+./bin/forge-daemon.sh status  # Should show workers if status files exist
+./bin/forge-daemon.sh stop
+npm test
+```
+
+## Acceptance Criteria
+
+- [ ] `bin/lib/daemon/sync.sh` created with both functions
+- [ ] Module has proper header with dependencies
+- [ ] Module has double-source protection
+- [ ] `forge-daemon.sh` sources the new module
+- [ ] Functions removed from `forge-daemon.sh`
+- [ ] Worker status displays correctly in `forge daemon status`
+- [ ] All existing tests pass
+- [ ] ShellCheck passes

package/tasks/completed/IMPL-007c-daemon-state-module.md

@@ -0,0 +1,80 @@
+---
+id: IMPL-007c
+title: "Extract daemon state module"
+type: implementation
+priority: medium
+assigned_to: ember
+created_at: 2026-01-17T10:00:00Z
+created_by: architect
+parent_task: ARCH-007
+depends_on: [IMPL-007b]
+---
+
+## Summary
+
+Extract state management functions from `forge-daemon.sh` into `bin/lib/daemon/state.sh`.
+
+## Context
+
+See ADR-001: docs/architecture/decisions/ADR-001-daemon-modularization.md
+
+## Functions to Extract
+
+From `bin/forge-daemon.sh`:
+
+1. `update_state()` (lines 376-429)
+2. `build_attention_details()` (lines 431-447)
+3. `determine_daemon_state()` (lines 474-488)
+4. `get_poll_interval()` (lines 491-496)
+
+**Note:** `update_state()` calls `build_attention_details()` and `build_worker_status()` (from sync.sh), so this module depends on IMPL-007b being completed first.
+
+## Implementation
+
+### 1. Create module file
+
+```bash
+#!/usr/bin/env bash
+# bin/lib/daemon/state.sh
+#
+# Daemon state management functions
+#
+# Dependencies: database.sh, constants.sh
+# Requires: sync.sh (for build_worker_status)
+# Globals required: FORGE_ROOT, STATE_FILE, TASKS_*, AGENT_STATUS_DIR
+
+# Prevent double-sourcing
+[[ -n "${_DAEMON_STATE_LOADED:-}" ]] && return 0
+_DAEMON_STATE_LOADED=1
+
+# [paste functions here]
+```
+
+### 2. Update forge-daemon.sh
+
+Source order matters - sync.sh must come before state.sh:
+```bash
+source "$SCRIPT_DIR/lib/daemon/sync.sh"
+source "$SCRIPT_DIR/lib/daemon/state.sh"
+```
+
+### 3. Test
+
+```bash
+./bin/forge-daemon.sh start
+# Wait a few seconds
+cat context/forge-state.yaml  # Should have valid YAML
+./bin/forge-daemon.sh stop
+npm test
+```
+
+## Acceptance Criteria
+
+- [ ] `bin/lib/daemon/state.sh` created with all 4 functions
+- [ ] Module has proper header with dependencies
+- [ ] Module has double-source protection
+- [ ] Source order correct in forge-daemon.sh
+- [ ] Functions removed from `forge-daemon.sh`
+- [ ] `forge-state.yaml` updates correctly when daemon runs
+- [ ] All existing tests pass
+- [ ] ShellCheck passes

package/tasks/completed/IMPL-007d-daemon-routing-module.md

@@ -0,0 +1,77 @@
+---
+id: IMPL-007d
+title: "Extract daemon routing module"
+type: implementation
+priority: medium
+assigned_to: anvil
+created_at: 2026-01-17T10:00:00Z
+created_by: architect
+parent_task: ARCH-007
+depends_on: []
+---
+
+## Summary
+
+Extract task routing functions from `forge-daemon.sh` into `bin/lib/daemon/routing.sh`.
+
+## Context
+
+See ADR-001: docs/architecture/decisions/ADR-001-daemon-modularization.md
+
+## Functions to Extract
+
+From `bin/forge-daemon.sh`:
+
+1. `safe_move_task()` (lines 85-114) - Currently in Utility Functions section
+2. `route_completed_to_review()` (lines 449-459)
+3. `route_approved_to_merged()` (lines 461-471)
+
+## Implementation
+
+### 1. Create module file
+
+```bash
+#!/usr/bin/env bash
+# bin/lib/daemon/routing.sh
+#
+# Task routing functions
+#
+# Dependencies: constants.sh
+# Globals required: FORGE_ROOT, LOG_FILE, TASKS_COMPLETED, TASKS_REVIEW,
+#                   TASKS_APPROVED, TASKS_MERGED
+
+# Prevent double-sourcing
+[[ -n "${_DAEMON_ROUTING_LOADED:-}" ]] && return 0
+_DAEMON_ROUTING_LOADED=1
+
+# [paste functions here]
+```
+
+### 2. Update forge-daemon.sh
+
+Add source and remove functions.
+
+### 3. Test
+
+```bash
+# Create a test task in completed/
+echo "test" > tasks/completed/test-routing.md
+./bin/forge-daemon.sh start
+sleep 5
+ls tasks/review/  # Should contain test-routing.md
+./bin/forge-daemon.sh stop
+rm tasks/review/test-routing.md
+npm test
+```
+
+## Acceptance Criteria
+
+- [ ] `bin/lib/daemon/routing.sh` created with all 3 functions
+- [ ] Module has proper header with dependencies
+- [ ] Module has double-source protection
+- [ ] `forge-daemon.sh` sources the new module
+- [ ] Functions removed from `forge-daemon.sh`
+- [ ] Task routing works (completed -> review -> approved -> merged)
+- [ ] Security checks in `safe_move_task` preserved
+- [ ] All existing tests pass
+- [ ] ShellCheck passes

package/tasks/completed/IMPL-007e-daemon-display-module.md

@@ -0,0 +1,77 @@
+---
+id: IMPL-007e
+title: "Extract daemon display module"
+type: implementation
+priority: medium
+assigned_to: furnace
+created_at: 2026-01-17T10:00:00Z
+created_by: architect
+parent_task: ARCH-007
+depends_on: []
+---
+
+## Summary
+
+Extract status display functions from `forge-daemon.sh` into `bin/lib/daemon/display.sh`.
+
+## Context
+
+See ADR-001: docs/architecture/decisions/ADR-001-daemon-modularization.md
+
+## Functions to Extract
+
+From `bin/forge-daemon.sh`:
+
+1. `display_daemon_status()` (lines 663-675)
+2. `display_task_counts()` (lines 678-683)
+3. `display_attention_needed()` (lines 686-700)
+4. `get_status_icon()` (lines 703-714)
+5. `display_worker_status()` (lines 717-762)
+6. `display_recent_notifications()` (lines 765-775)
+
+## Implementation
+
+### 1. Create module file
+
+```bash
+#!/usr/bin/env bash
+# bin/lib/daemon/display.sh
+#
+# Status display functions for daemon status command
+#
+# Dependencies: colors.sh, constants.sh, json.sh
+# Globals required: FORGE_ROOT, PID_FILE, STATE_FILE, NOTIFY_FILE,
+#                   AGENT_STATUS_DIR, TASKS_ATTENTION, STALE_STATUS_THRESHOLD
+
+# Prevent double-sourcing
+[[ -n "${_DAEMON_DISPLAY_LOADED:-}" ]] && return 0
+_DAEMON_DISPLAY_LOADED=1
+
+# [paste functions here]
+```
+
+### 2. Update forge-daemon.sh
+
+Add source and remove functions. The `cmd_status()` function stays in forge-daemon.sh but calls the display functions.
+
+### 3. Test
+
+```bash
+./bin/forge-daemon.sh start
+./bin/forge-daemon.sh status  # Should show all sections with colors
+./bin/forge-daemon.sh stop
+./bin/forge-daemon.sh status  # Should show stopped status
+npm test
+```
+
+## Acceptance Criteria
+
+- [ ] `bin/lib/daemon/display.sh` created with all 6 functions
+- [ ] Module has proper header with dependencies
+- [ ] Module has double-source protection
+- [ ] `forge-daemon.sh` sources the new module
+- [ ] Functions removed from `forge-daemon.sh`
+- [ ] `forge daemon status` displays all sections correctly
+- [ ] Colors and icons display properly
+- [ ] All existing tests pass
+- [ ] ShellCheck passes

package/tasks/completed/IMPL-007f-daemon-integration.md

@@ -0,0 +1,124 @@
+---
+id: IMPL-007f
+title: "Integrate daemon modules and verify"
+type: implementation
+priority: medium
+assigned_to: ember
+created_at: 2026-01-17T10:00:00Z
+created_by: architect
+parent_task: ARCH-007
+depends_on: [IMPL-007a, IMPL-007b, IMPL-007c, IMPL-007d, IMPL-007e]
+---
+
+## Summary
+
+Final integration task: ensure all daemon modules work together, verify the main daemon file is under 200 lines, and run comprehensive tests.
+
+## Context
+
+See ADR-001: docs/architecture/decisions/ADR-001-daemon-modularization.md
+
+After IMPL-007a through IMPL-007e are complete, `forge-daemon.sh` should:
+1. Be significantly smaller (~150-200 lines)
+2. Source all modules from `bin/lib/daemon/`
+3. Contain only: config, daemon_loop, commands, main
+
+## Verification Steps
+
+### 1. Line count check
+
+```bash
+wc -l bin/forge-daemon.sh  # Should be < 200 lines
+wc -l bin/lib/daemon/*.sh  # Each module should be < 200 lines
+```
+
+### 2. Source order verification
+
+`forge-daemon.sh` should source in this order:
+```bash
+# Standard libraries
+source "$SCRIPT_DIR/lib/colors.sh"
+source "$SCRIPT_DIR/lib/constants.sh"
+source "$SCRIPT_DIR/lib/config.sh"
+source "$SCRIPT_DIR/lib/json.sh"
+source "$SCRIPT_DIR/lib/database.sh"
+source "$SCRIPT_DIR/lib/util.sh"
+
+# Daemon modules
+source "$SCRIPT_DIR/lib/daemon/routing.sh"
+source "$SCRIPT_DIR/lib/daemon/notifications.sh"
+source "$SCRIPT_DIR/lib/daemon/sync.sh"
+source "$SCRIPT_DIR/lib/daemon/state.sh"
+source "$SCRIPT_DIR/lib/daemon/display.sh"
+```
+
+### 3. Comprehensive test
+
+```bash
+# Start daemon
+./bin/forge-daemon.sh start
+echo "Started"
+
+# Check status
+./bin/forge-daemon.sh status
+
+# Create test task to trigger routing
+echo -e "---\nid: TEST-001\ntitle: Test\n---\nTest" > tasks/completed/test-integration.md
+sleep 5
+
+# Verify routing
+ls tasks/review/test-integration.md && echo "Routing works"
+
+# Check notifications
+./bin/forge-daemon.sh notifications 5
+
+# Stop daemon
+./bin/forge-daemon.sh stop
+echo "Stopped"
+
+# Verify state file
+cat context/forge-state.yaml
+
+# Cleanup
+rm -f tasks/review/test-integration.md
+
+# Run unit tests
+npm test
+```
+
+### 4. ShellCheck all modules
+
+```bash
+shellcheck bin/forge-daemon.sh
+shellcheck bin/lib/daemon/*.sh
+```
+
+## Final Structure
+
+After completion:
+```
+bin/
+  forge-daemon.sh          # ~150-200 lines, orchestration only
+  lib/
+    daemon/
+      notifications.sh     # ~170 lines
+      sync.sh             # ~80 lines
+      state.sh            # ~120 lines
+      routing.sh          # ~50 lines
+      display.sh          # ~120 lines
+```
+
+## Acceptance Criteria
+
+- [ ] `forge-daemon.sh` is under 200 lines
+- [ ] All 5 modules exist in `bin/lib/daemon/`
+- [ ] Each module has proper header and double-source protection
+- [ ] Source order is correct (dependencies before dependents)
+- [ ] Daemon starts, stops, and reports status correctly
+- [ ] Task routing works (completed -> review)
+- [ ] Notifications appear in log
+- [ ] State file updates correctly
+- [ ] Worker status displays (if status files exist)
+- [ ] All existing tests pass
+- [ ] ShellCheck passes on all files
+- [ ] docs/architecture.md updated to reflect new structure