@sugar-crash-studios/vibe-forge 0.4.0

package/docs/architecture/decisions/ADR-001-daemon-modularization.md

@@ -0,0 +1,122 @@
+# ADR-001: Modularize forge-daemon.sh
+
+## Status
+
+Accepted
+
+## Context
+
+`bin/forge-daemon.sh` has grown to 852 lines, containing multiple unrelated responsibilities:
+
+1. **Utility functions** (lines 56-114) - Log rotation, file trimming, safe file moves
+2. **Notification system** (lines 116-288) - Message sanitization, platform-specific toasts, task notifications
+3. **Agent status sync** (lines 290-370) - JSON-to-SQLite synchronization, status building
+4. **State management** (lines 372-496) - State file updates, task routing, daemon state
+5. **Display functions** (lines 658-775) - Status output formatting, worker display
+6. **Commands & main** (lines 560-851) - CLI interface
+
+This monolithic structure causes:
+- **Maintenance burden** - Changes to notifications require understanding the entire file
+- **Testing difficulty** - Functions can't be tested in isolation
+- **Cognitive load** - New contributors must grok 850+ lines to make changes
+- **Violation of SRP** - File handles 6+ distinct responsibilities
+
+## Decision
+
+Split `forge-daemon.sh` into focused modules under `bin/lib/daemon/`:
+
+```
+bin/lib/daemon/
+  notifications.sh  - Notification logic
+  sync.sh          - Agent status synchronization
+  state.sh         - State file management
+  routing.sh       - Task routing logic
+  display.sh       - Status display functions
+```
+
+The main `forge-daemon.sh` becomes a thin orchestrator (~150 lines):
+- Configuration loading
+- Library sourcing
+- `daemon_loop()` function
+- Command handlers that delegate to modules
+- Main entry point
+
+### Module Responsibilities
+
+| Module | Functions | Lines (approx) |
+|--------|-----------|----------------|
+| notifications.sh | `sanitize_notification_message`, `notify`, `send_system_notification`, `check_new_pending_tasks`, `check_attention_needed` | ~170 |
+| sync.sh | `sync_agent_status_to_db`, `build_worker_status` | ~80 |
+| state.sh | `update_state`, `build_attention_details`, `determine_daemon_state`, `get_poll_interval` | ~120 |
+| routing.sh | `route_completed_to_review`, `route_approved_to_merged`, `safe_move_task` | ~50 |
+| display.sh | `display_daemon_status`, `display_task_counts`, `display_attention_needed`, `get_status_icon`, `display_worker_status`, `display_recent_notifications` | ~120 |
+
+### Interface Contract
+
+Each module:
+1. Sources only the libraries it needs (colors.sh, constants.sh, etc.)
+2. Defines functions without executing code on source
+3. Uses FORGE_ROOT and other globals set by parent
+4. Documents its dependencies at the top
+
+Example module header:
+```bash
+#!/usr/bin/env bash
+# Daemon notifications module
+# Dependencies: colors.sh, constants.sh
+# Globals: FORGE_ROOT, NOTIFY_FILE, NOTIFIED_FILE, LOG_FILE
+```
+
+## Consequences
+
+### Positive
+
+- **Testability** - Individual modules can be sourced and tested in isolation
+- **Maintainability** - Changes to notifications don't risk breaking routing
+- **Readability** - Each file is <200 lines with single purpose
+- **Onboarding** - New contributors can understand one module at a time
+- **Reusability** - Notification functions could be reused elsewhere
+
+### Negative
+
+- **Source overhead** - Multiple `source` commands (minimal impact)
+- **Migration risk** - Refactoring could introduce bugs
+- **Documentation** - Need to document module interfaces
+
+### Neutral
+
+- **Directory structure** - Adds `bin/lib/daemon/` subdirectory
+- **Variable scope** - Globals still shared (could refine later)
+
+## Implementation Plan
+
+1. Create `bin/lib/daemon/` directory
+2. Extract `notifications.sh` (highest complexity, most independent)
+3. Extract `sync.sh` (clear boundaries)
+4. Extract `state.sh` (depends on sync)
+5. Extract `routing.sh` (simple, low risk)
+6. Extract `display.sh` (output only, no state changes)
+7. Update `forge-daemon.sh` to source modules
+8. Verify all tests pass
+9. Update documentation
+
+## Alternatives Considered
+
+### Alternative A: Leave as monolith
+- Pro: No migration risk
+- Con: Continued maintenance burden, harder testing
+
+### Alternative B: Full Node.js rewrite
+- Pro: Single language, better testing tools
+- Con: High effort, loses Bash transparency, not aligned with current hybrid strategy
+
+### Alternative C: Just add more comments
+- Pro: Low effort
+- Con: Doesn't address structural issues
+
+**Selected: Module extraction** - Balances improvement vs. risk, maintains Bash strategy.
+
+## References
+
+- Task: ARCH-007
+- Related: ARCH-005 (src/ directory), ARCH-010 (index files)