xonecas.io
60255
Zn

Zoea-Nova / commit 8d271ad

docs: v1 plan

xonecas2026-02-05 8d271adb4a26eb17e7ea94027994cf53d24e1edf parent 748d124

1 file changed

documentation/plans/v1.md+511−0
@@ -0,0 +1,511 @@
1+# Zoea Nova v1 Launch Plan
2+
3+Comprehensive checklist to address all known issues, TODOs, and code analysis findings. Complete these items before tagging v1.0.0.
4+
5+---
6+
7+## Phase 1: Critical Blockers
8+
9+### 1.1 MCP Server Connection
10+
11+The upstream SpaceMolt MCP server handshake is broken. Game tools are unavailable.
12+
13+- [ ] **Implement offline/stub mode for development**
14+ - Create `internal/mcp/stub.go` with mock game responses
15+ - Add `--offline` flag to run without upstream connection
16+ - Document in AGENTS.md how to develop without game server
17+
18+- [ ] **Report issue to SpaceMolt maintainers**
19+ - Reference: `documentation/KNOWN_SERVER_ISSUES.md`
20+ - Include reproduction steps and curl commands from documentation
21+ - Track response and update KNOWN_SERVER_ISSUES.md with ticket link
22+
23+- [ ] **Add retry logic with exponential backoff**
24+ - Modify `internal/mcp/client.go` Initialize to retry 3x
25+ - Log each retry attempt
26+ - Graceful degradation if all retries fail
27+
28+### 1.2 Failing Integration Tests
29+
30+17 integration tests timeout consistently.
31+
32+- [ ] **Fix integration test pattern**
33+ - Update all tests to send quit before FinalModel()
34+ - Reference: `documentation/TUI_TESTING.md` quit pattern section
35+ - Files: `internal/tui/integration_test.go`
36+
37+- [ ] **Add integration test CI gate**
38+ - Makefile target: `make test-integration`
39+ - Fail build if any integration tests timeout
40+
41+---
42+
43+## Phase 2: Prompt & Behavior (High Priority)
44+
45+### 2.1 State-Aware ContinuePrompt
46+
47+Reduces redundant "waiting" responses during travel and cooldowns.
48+
49+- [ ] **Track mysis activity state**
50+ - Add `activityState` field to Mysis struct
51+ - States: `idle`, `traveling`, `mining`, `in_combat`, `cooldown`
52+ - Update state based on tool call results (travel, mine, attack)
53+
54+- [ ] **Suppress nudge during known wait states**
55+ - Modify `Mysis.run()` ticker logic
56+ - Skip ContinuePrompt if `activityState` is `traveling` or `cooldown`
57+ - Or extend interval (e.g., 2 minutes instead of 30s)
58+
59+- [ ] **Parse arrival_tick from tool results**
60+ - Extract `arrival_tick` from travel tool responses
61+ - Calculate wait duration from game tick time
62+ - Resume normal prompting after arrival
63+
64+### 2.2 Reinforce Critical Rules in ContinuePrompt
65+
66+Prevents drift when system prompt falls out of context window.
67+
68+- [ ] **Audit ContinuePrompt content**
69+ - Compare against SystemPrompt for missing rules
70+ - Add: collaboration rules, themed usernames, memory search
71+
72+- [ ] **Add context-aware reminders**
73+ - If recent messages show drift, include stronger reminders
74+ - Example: if mysis used real-world time, remind about game tick time
75+
76+### 2.3 Remove Real-Time Awareness
77+
78+- [ ] **Audit SystemPrompt and ContinuePrompt**
79+ - Remove any references to real-world time
80+ - Replace with game tick time instructions
81+
82+- [ ] **Add game time tool if needed**
83+ - If myses need time awareness, expose `zoea_game_time` tool
84+ - Returns current tick from last server response
85+
86+### 2.4 Captains Log Guidance
87+
88+Prevents `empty_entry` errors.
89+
90+- [ ] **Verify current prompts have examples**
91+ - SystemPrompt already has examples (lines 55-59 of mysis.go)
92+ - ContinuePrompt has reminder (line 120-121)
93+ - Test with fresh mysis to confirm no empty_entry errors
94+
95+---
96+
97+## Phase 3: Concurrency & Reliability
98+
99+### 3.1 EventBus Silent Drops
100+
101+Events vanish without logging when buffer is full.
102+
103+- [ ] **Add drop counter and logging**
104+ - Track dropped events per subscriber
105+ - Log warning every 100 dropped events
106+ - Include event type in log message
107+
108+- [ ] **Consider backpressure option**
109+ - Add `PublishBlocking(event, timeout)` method
110+ - Use for critical events (errors, state changes)
111+ - Keep non-blocking for high-frequency events (messages)
112+
113+### 3.2 Race Condition in Mysis.Stop()
114+
115+Lock ordering between `mu` and `turnMu` allows interleaving.
116+
117+- [ ] **Audit state machine transitions**
118+ - Document valid state transitions
119+ - Add tests for concurrent Start/Stop calls
120+
121+- [ ] **Consider atomic state machine**
122+ - Replace `state` field with `atomic.Value` or dedicated state machine
123+ - Or hold both locks in Stop() before state check
124+
125+### 3.3 Goroutine Leak in Nudge Ticker
126+
127+The 30-second ticker spawns goroutines even when TryLock fails.
128+
129+- [ ] **Refactor nudge logic**
130+ - Don't spawn goroutine if TryLock fails
131+ - Use channel-based signaling instead of goroutine per nudge
132+
133+---
134+
135+## Phase 4: Error Handling
136+
137+### 4.1 Silent Error Swallowing
138+
139+- [ ] **Fix proxy.go line 100**
140+ - Change `_ = err` to `log.Warn().Err(err).Msg("...")`
141+
142+- [ ] **Fix mysis.go setErrorState**
143+ - Log error if store.UpdateMysisState fails
144+ - Consider emitting error event
145+
146+- [ ] **Audit codebase for `_ = err`**
147+ - Run: `grep -n "_ = err" internal/`
148+ - Fix each occurrence with appropriate handling
149+
150+### 4.2 Time Parsing Fragility
151+
152+- [ ] **Fix memories.go time parsing**
153+ - Log warning when parse fails
154+ - Use consistent time format in all INSERTs
155+ - Add test for round-trip time storage
156+
157+---
158+
159+## Phase 5: Testing
160+
161+### 5.1 Coverage Targets
162+
163+Current: ~61%. Target: 80%+.
164+
165+| Package | Current | Target |
166+|---------|---------|--------|
167+| `cmd/zoea` | 0.0% | 20% |
168+| `internal/config` | 52.5% | 80% |
169+| `internal/mcp` | 46.0% | 75% |
170+| `internal/provider` | 36.1% | 70% |
171+| `internal/store` | 77.1% | 85% |
172+| `internal/core` | 84.1% | 85% |
173+
174+- [ ] **Add provider tests**
175+ - Test Ollama error handling paths
176+ - Test rate limiter behavior
177+ - Mock HTTP responses for tool calls
178+
179+- [ ] **Add config validation tests**
180+ - Test invalid temperature values
181+ - Test missing required fields
182+ - Test environment override precedence
183+
184+- [ ] **Add mcp proxy tests**
185+ - Test local tool routing
186+ - Test upstream fallback
187+ - Test auth interception
188+
189+### 5.2 Mock Provider Delays
190+
191+- [ ] **Add configurable delay to MockProvider**
192+ - `MockProvider.SetDelay(time.Duration)`
193+ - Use in integration tests to simulate real LLM latency
194+
195+---
196+
197+## Phase 6: Database & Performance
198+
199+### 6.1 Memory Table Growth
200+
201+No cleanup of old memories.
202+
203+- [ ] **Analyze memory growth**
204+ - Run with 16 myses for 1 hour
205+ - Measure database size and query performance
206+ - Document findings
207+
208+- [ ] **Implement retention policy (if needed)**
209+ - Option A: Keep last N memories per mysis (configurable)
210+ - Option B: Prune memories older than N days
211+ - Add `make db-prune` target
212+
213+### 6.2 MaxOpenConns=1 Bottleneck
214+
215+- [ ] **Benchmark concurrent writes**
216+ - Test with 16 myses writing simultaneously
217+ - Measure write latency and throughput
218+ - Document if acceptable for v1
219+
220+- [ ] **Consider write queue (if needed)**
221+ - Batch writes from multiple myses
222+ - Single writer goroutine with channel input
223+
224+---
225+
226+## Phase 7: Configuration & Validation
227+
228+### 7.1 Add Config Validation
229+
230+- [ ] **Validate provider config**
231+ - Temperature: 0.0 - 2.0
232+ - RateLimit: > 0
233+ - RateBurst: >= 1
234+ - Endpoint: valid URL format
235+
236+- [ ] **Validate swarm config**
237+ - MaxMyses: 1 - 100
238+
239+- [ ] **Return validation errors from Load()**
240+ - Collect all errors, return joined
241+ - Include field name and invalid value in message
242+
243+### 7.2 Reduce Config Boilerplate
244+
245+- [ ] **Refactor applyEnvOverrides**
246+ - Table-driven approach for env var mapping
247+ - Reduce from 90 lines to ~30
248+
249+---
250+
251+## Phase 8: Code Quality
252+
253+### 8.1 Type Safety Improvements
254+
255+- [ ] **Replace Event.Data interface{}**
256+ - Option A: Separate event types per data struct
257+ - Option B: Sum type using generics
258+ - Option C: Keep interface{} but add helper methods
259+
260+### 8.2 Consistent Receiver Names
261+
262+- [ ] **Audit and standardize**
263+ - Mysis: `m` (not `a`)
264+ - Store: `s`
265+ - Proxy: `p`
266+ - Model: `m`
267+
268+### 8.3 Centralize Constants
269+
270+- [ ] **Create internal/constants package or file**
271+ - Move magic numbers from mysis.go
272+ - Move timeouts and limits
273+ - Document each constant's purpose
274+
275+---
276+
277+## Phase 9: Documentation
278+
279+### 9.1 User Documentation
280+
281+- [ ] **Add install command**
282+ - `make install` copies binary to ~/.zoea-nova/bin/
283+ - Update README with installation instructions
284+
285+- [ ] **Document offline mode**
286+ - How to run without game server
287+ - What features are available in offline mode
288+
289+### 9.2 Developer Documentation
290+
291+- [ ] **Add architecture diagram**
292+ - Use mermaid in AGENTS.md
293+ - Show: Commander -> Mysis -> Provider -> LLM
294+ - Show: TUI -> EventBus -> Commander
295+
296+- [ ] **Document state machine**
297+ - Valid Mysis state transitions
298+ - When each transition occurs
299+
300+---
301+
302+## Phase 10: TODO.md Items
303+
304+From `documentation/TODO.md`:
305+
306+- [ ] **Animate message input**
307+ - Add spinner or unicode animation while sending
308+ - Show progress indicator for broadcast
309+
310+- [ ] **Make install command**
311+ - `make install` target (covered in Phase 9.1)
312+
313+- [ ] **Fix mysis tick calculation**
314+ - Investigate "calculating tick wrong" issue
315+ - Parse arrival_tick correctly from travel responses
316+ - Relate to Phase 2.1 state-aware prompting
317+
318+- [ ] **Check Ollama logs for loop stoppage**
319+ - Review Ollama server logs during mysis runs
320+ - Identify if model is returning stop token unexpectedly
321+ - May relate to prompt structure or temperature
322+
323+---
324+
325+## Phase 11: TUI Data Visibility & Test Gaps
326+
327+Audit of TUI tests for missing or malformed data displays.
328+
329+### 11.1 Missing Data in Test Fixtures
330+
331+The following data fields exist in structs but lack adequate test coverage:
332+
333+- [ ] **MysisInfo.CreatedAt not displayed**
334+ - Field exists in `MysisInfo` struct (dashboard.go:21)
335+ - Not rendered in dashboard or focus view
336+ - Consider: Show age (e.g., "2h ago") or creation date in focus view info panel
337+
338+- [ ] **MysisInfo.LastMessage timestamp not shown**
339+ - `LastMessage` content is displayed but its timestamp isn't
340+ - Consider: Show "5m ago" next to last message in dashboard
341+
342+- [ ] **LogEntry.Timestamp not displayed**
343+ - Field exists in `LogEntry` struct (focus.go:20)
344+ - `renderLogEntryImpl` never uses `entry.Timestamp`
345+ - Tests pass timestamps but rendering ignores them
346+ - Add timestamp display to each log entry (e.g., "10:30:05")
347+
348+- [ ] **LogEntry.SenderID display incomplete**
349+ - `SenderID` tracked for broadcasts but only shows "SWARM:" prefix
350+ - Could show sender mysis name: "SWARM (mysis-2):"
351+ - Requires lookup from mysis list by ID
352+
353+- [ ] **SwarmMessageInfo sender not displayed**
354+ - Dashboard shows broadcast content and time but not sender
355+ - `store.BroadcastMessage.SenderID` is retrieved but not passed to `SwarmMessageInfo`
356+ - Add `SenderID` field to `SwarmMessageInfo` and display in dashboard
357+
358+### 11.2 Test Data Consistency Issues
359+
360+- [ ] **Golden tests use hardcoded dates**
361+ - Tests use `time.Date(2026, 1, 15, ...)` which differs from current date
362+ - Consider: Document this is intentional for reproducibility
363+ - Or: Use relative time display to avoid date dependency
364+
365+- [ ] **MockProvider returns instant responses**
366+ - `MockProvider.Chat()` returns immediately
367+ - Real LLM calls take 1-30 seconds
368+ - Integration tests don't catch timing bugs
369+ - Add `SetDelay(time.Duration)` to MockProvider (covered in Phase 5.2)
370+
371+- [ ] **Test terminal size is fixed at 120x40**
372+ - `TestTerminalWidth = 120`, `TestTerminalHeight = 40`
373+ - No tests for narrow terminals (80x24) or wide terminals (200x60)
374+ - Add golden tests for different terminal sizes
375+
376+### 11.3 Missing Visual Regression Tests
377+
378+- [ ] **No golden test for errored state mysis**
379+ - Tests cover running, idle, stopped states
380+ - Missing: errored state with LastError display
381+
382+- [ ] **No golden test for loading spinner states**
383+ - `loadingSet` passed to `RenderDashboard` but not tested in golden files
384+ - Add test with `loadingSet["mysis-id"] = true`
385+
386+- [ ] **No golden test for long mysis names**
387+ - Truncation at 16 chars tested implicitly
388+ - Add explicit test with 20+ char name to verify "..."
389+
390+- [ ] **No golden test for empty last message**
391+ - Dashboard shows `LastMessage` if present
392+ - Missing test for mysis with no messages yet
393+
394+- [ ] **No golden test for multiline broadcast content**
395+ - `SwarmMessageInfo.Content` is single-line normalized (`strings.ReplaceAll`)
396+ - No test verifying newlines are stripped
397+
398+### 11.4 Integration Test Pattern Fixes
399+
400+- [ ] **17 tests fail due to FinalModel timeout**
401+ - Root cause: Tests don't send quit before FinalModel()
402+ - Affected tests (from test output):
403+ - `TestIntegration_DashboardNavigationUp`
404+ - `TestIntegration_FocusViewTransition`
405+ - `TestIntegration_HelpToggle`
406+ - `TestIntegration_BroadcastInput`
407+ - `TestIntegration_MessageInput`
408+ - (and 12 more)
409+ - Fix: Add `tm.Send(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'q'}})` before `FinalModel()`
410+
411+- [ ] **Document integration test pattern in TUI_TESTING.md**
412+ - Pattern documented but not consistently followed
413+ - Add checklist to test file header comments
414+
415+### 11.5 Data Display Improvements
416+
417+- [ ] **Add timestamp to log entries**
418+ - Render format: `[10:30:05] AI: Response text...`
419+ - Update `renderLogEntryImpl` to include timestamp
420+ - Update golden files after change
421+
422+- [ ] **Add mysis count to focus view header**
423+ - Show "MYSIS: alpha (3 of 16)" or similar
424+ - Helps user understand swarm context when focused
425+
426+- [ ] **Add scroll position indicator**
427+ - Current: Shows "↑ SCROLLED" suffix
428+ - Better: Show "Line 45/120" or percentage
429+ - Update `RenderFocusViewWithViewport` and golden files
430+
431+- [ ] **Show broadcast sender in dashboard**
432+ - Current: "14:30:05 Hello everyone"
433+ - Better: "14:30:05 [mysis-1] Hello everyone"
434+ - Requires passing sender info through SwarmMessageInfo
435+
436+---
437+
438+## Phase 12: Pre-Release Checklist
439+
440+### 12.1 Final Verification
441+
442+- [ ] **Run full test suite**
443+ - `make test` passes
444+ - No failing integration tests
445+ - Coverage >= 80%
446+
447+- [ ] **Run linter**
448+ - `make fmt` produces no changes
449+ - No warnings from go vet
450+
451+- [ ] **Manual testing**
452+ - Create 3 myses, run for 10 minutes
453+ - Send broadcasts, verify delivery
454+ - Focus view shows correct logs
455+ - Stop/start/delete work correctly
456+
457+### 12.2 Release Process
458+
459+- [ ] **Update version**
460+ - Increment version in accordance with versioning rules
461+ - Update CHANGELOG.md (if exists) or create release notes
462+
463+- [ ] **Tag release**
464+ - `git tag -a v1.0.0 -m "Zoea Nova v1.0.0"`
465+ - `git push origin v1.0.0`
466+
467+- [ ] **Update KNOWN_ISSUES.md**
468+ - Move completed items to Recently Resolved
469+ - Document any known v1 limitations
470+
471+---
472+
473+## Tracking
474+
475+| Phase | Items | Completed | Blocked |
476+|-------|-------|-----------|---------|
477+| 1. Critical Blockers | 5 | 0 | 1 (MCP server) |
478+| 2. Prompt & Behavior | 7 | 0 | 0 |
479+| 3. Concurrency | 5 | 0 | 0 |
480+| 4. Error Handling | 4 | 0 | 0 |
481+| 5. Testing | 5 | 0 | 0 |
482+| 6. Database | 3 | 0 | 0 |
483+| 7. Configuration | 3 | 0 | 0 |
484+| 8. Code Quality | 3 | 0 | 0 |
485+| 9. Documentation | 4 | 0 | 0 |
486+| 10. TODO.md | 4 | 0 | 0 |
487+| 11. TUI Data Visibility | 18 | 0 | 0 |
488+| 12. Pre-Release | 5 | 0 | 0 |
489+| **Total** | **66** | **0** | **1** |
490+
491+---
492+
493+## Notes
494+
495+- Phase 1 (MCP server) may block testing of game integration features
496+- Phases 2-4 can proceed in parallel
497+- Phase 11 (TUI) items can be worked in parallel with other phases
498+- Phase 12 depends on all other phases completing
499+
500+---
501+
502+## Timeline
503+
504+**Plan created:** 2026-02-05 14:30 UTC
505+
506+**Estimated completion:**
507+- Human solo: 3-4 weeks
508+- Human + AI assistant: 1-2 weeks
509+- Human + AI assistant (aggressive): 1 day (user's bet)
510+
511+Let's see who wins.