docs: define v1 requirements for DX milestone

.planning/REQUIREMENTS.md

@@ -0,0 +1,98 @@
+# Requirements: Flynn Operator DX
+
+**Defined:** 2026-02-09
+**Core Value:** Make Flynn easier to reason about, configure, and monitor
+
+## v1 Requirements
+
+Requirements for this milestone. Each maps to roadmap phases.
+
+### Daemon Decomposition
+
+- [ ] **DECO-01**: Model client creation logic extracted from daemon/index.ts into src/daemon/models.ts with the same public interface
+- [ ] **DECO-02**: Channel adapter setup logic extracted into src/daemon/channels.ts
+- [ ] **DECO-03**: Agent cache and factory logic extracted into src/daemon/agents.ts
+- [ ] **DECO-04**: Memory store and vector store initialization extracted into src/daemon/memory.ts
+- [ ] **DECO-05**: Tool registration and policy wiring extracted into src/daemon/tools.ts
+- [ ] **DECO-06**: Message routing logic extracted into src/daemon/routing.ts (test file already exists)
+- [ ] **DECO-07**: daemon/index.ts reduced to a thin composition root that imports and wires extracted modules
+- [ ] **DECO-08**: All 1077+ existing tests continue to pass after decomposition
+
+### Config Overlays
+
+- [ ] **CONF-01**: User can set FLYNN_ENV environment variable to select a config overlay (e.g., docker, production)
+- [ ] **CONF-02**: Config loader merges environment-specific overlay file on top of base config with deep merge
+- [ ] **CONF-03**: flynn doctor validates that the selected environment overlay file exists when FLYNN_ENV is set
+
+### Live Ops Dashboard
+
+- [ ] **DASH-01**: Dashboard shows core counters: messages processed, active sessions, queue depth, daemon uptime
+- [ ] **DASH-02**: Dashboard shows model call metrics: per-call latency, tokens/sec throughput, error rates by provider
+- [ ] **DASH-03**: Dashboard shows live event stream: scrollable log of errors and events with timestamps and context
+- [ ] **DASH-04**: Dashboard shows active request tracking: in-flight requests, recent tool executions, active agent sessions
+- [ ] **DASH-05**: Gateway exposes /health endpoint returning JSON status for liveness/readiness checks
+
+## v2 Requirements
+
+Deferred to future milestone. Tracked but not in current roadmap.
+
+### Observability
+
+- **OBSV-01**: Structured JSON logging framework (pino or similar) replacing console.log
+- **OBSV-02**: Request tracing with correlation IDs across channel → agent → model → tool chain
+- **OBSV-03**: Prometheus-compatible metrics endpoint for external monitoring
+
+### Config
+
+- **CONF-04**: Deep merge semantics for overlay files (objects merge, arrays replace)
+- **CONF-05**: Convention-based overlay file discovery (config/default.yaml + config/{env}.yaml)
+- **CONF-06**: Hot reload of config changes without daemon restart
+
+### Code Quality
+
+- **QUAL-01**: ESLint configuration with @typescript-eslint/recommended
+- **QUAL-02**: Reduce `as any` casts by creating proper mock factories and wrapper types
+- **QUAL-03**: Test coverage for security-sensitive file tools
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| New channel adapters | Not the focus — separate milestone |
+| Agent intelligence (sub-agents, planning) | Separate milestone |
+| Companion apps (macOS, iOS, Android) | Massive scope, different project |
+| Skill registry / marketplace | Community feature, premature |
+| Onboard wizard | Operator already knows the system |
+| Multi-tenant / team features | Single-operator tool |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| DECO-01 | — | Pending |
+| DECO-02 | — | Pending |
+| DECO-03 | — | Pending |
+| DECO-04 | — | Pending |
+| DECO-05 | — | Pending |
+| DECO-06 | — | Pending |
+| DECO-07 | — | Pending |
+| DECO-08 | — | Pending |
+| CONF-01 | — | Pending |
+| CONF-02 | — | Pending |
+| CONF-03 | — | Pending |
+| DASH-01 | — | Pending |
+| DASH-02 | — | Pending |
+| DASH-03 | — | Pending |
+| DASH-04 | — | Pending |
+| DASH-05 | — | Pending |
+
+**Coverage:**
+- v1 requirements: 16 total
+- Mapped to phases: 0
+- Unmapped: 16
+
+---
+*Requirements defined: 2026-02-09*
+*Last updated: 2026-02-09 after initial definition*