docs(06): create gap closure plans for CLI interface issues

Phase 06: CLI Interface Gap Closure - 2 plans addressing 3 UAT-identified issues - Session persistence: Add missing set_conversation_history method - Session feedback: Add verbose messaging for session file operations - Resource display: Fix color coding with force_terminal=True - Ready for execution to close CLI interface gaps
2026-01-26 22:51:49 -05:00
parent c70ee8816e
commit 54f6b4b40d
3 changed files with 351 additions and 0 deletions
--- a/.planning/phases/06-cli-interface/06-05-PLAN.md
+++ b/.planning/phases/06-cli-interface/06-05-PLAN.md
@@ -0,0 +1,116 @@
+---
+phase: 06-cli-interface
+plan: 05
+type: execute
+wave: 1
+depends_on: [06-02]
+files_modified: [src/mai/conversation/state.py]
+autonomous: true
+gap_closure: true
+
+must_haves:
+  truths:
+    - "Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed"
+  artifacts:
+    - path: "src/mai/conversation/state.py"
+      provides: "ConversationState class with session history management"
+      contains: "set_conversation_history method"
+  key_links:
+    - from: "src/mai/conversation/state.py"
+      to: "session restoration"
+      via: "set_conversation_history method converts Ollama messages to ConversationTurn objects"
+      pattern: "def set_conversation_history"
+---
+
+<objective>
+Fix session persistence by adding missing set_conversation_history method to ConversationState class
+
+Purpose: Resolve the "ConversationState object has no attribute 'set_conversation_history'" error that prevents session restoration from working properly
+Output: Working session persistence with contextual recovery messages
+</objective>
+
+<execution_context>
+@~/.opencode/get-shit-done/workflows/execute-plan.md
+@~/.opencode/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Gap closure context from UAT
+@.planning/phases/06-cli-interface/06-UAT.md
+
+# Previous session persistence implementation
+@.planning/phases/06-cli-interface/06-02-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Fix ConversationState missing set_conversation_history method</name>
+  <files>src/mai/conversation/state.py</files>
+  <action>
+    Add the missing set_conversation_history method to the ConversationState class:
+    
+    1. Examine the existing ConversationState class structure in src/mai/conversation/state.py
+    2. Add set_conversation_history method that:
+       - Accepts a list of Ollama message dictionaries as input
+       - Converts each message back to ConversationTurn objects using the existing conversion logic
+       - Preserves the message order (user then assistant pairs)
+       - Updates the conversation history and current state appropriately
+    3. Ensure the method handles edge cases like empty lists, malformed messages, and None values
+    4. Add proper type hints for the method signature
+    
+    Reference the existing message conversion logic used when saving sessions to ensure consistent transformation.
+    
+    Gap reason: "Missing set_conversation_history method in ConversationState class"
+    Root cause: Session restoration tries to call this method but it doesn't exist
+  </action>
+  <verify>
+    # Test the method exists and works
+    python -c "
+from src.mai.conversation.state import ConversationState
+import inspect
+
+# Check method exists
+if hasattr(ConversationState, 'set_conversation_history'):
+    print('✓ set_conversation_history method exists')
+    
+    # Check method signature
+    sig = inspect.signature(ConversationState.set_conversation_history)
+    print(f'✓ Method signature: {sig}')
+else:
+    print('✗ set_conversation_history method missing')
+    exit(1)
+"
+  </verify>
+  <done>
+    ConversationState class has set_conversation_history method that can convert Ollama messages back to ConversationTurn objects for session restoration
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+Test session persistence by:
+1. Starting a conversation with a few messages
+2. Exiting the CLI
+3. Restarting the CLI
+4. Verifying the welcome message shows time elapsed and conversation history is restored
+
+Expected: No "ConversationState object has no attribute 'set_conversation_history'" error
+</verification>
+
+<success_criteria>
+- set_conversation_history method exists in ConversationState class
+- Method accepts list of Ollama message dictionaries
+- Method properly converts messages to ConversationTurn objects  
+- Session restoration works without AttributeError
+- Welcome back message shows correct time elapsed
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/06-cli-interface/06-05-SUMMARY.md`
+</output>
--- a/.planning/phases/06-cli-interface/06-06-PLAN.md
+++ b/.planning/phases/06-cli-interface/06-06-PLAN.md
@@ -0,0 +1,133 @@
+---
+phase: 06-cli-interface
+plan: 06
+type: execute
+wave: 1
+depends_on: [06-02, 06-04]
+files_modified: [src/app/__main__.py]
+autonomous: true
+gap_closure: true
+
+must_haves:
+  truths:
+    - "Messages are automatically saved to ~/.mai/session.json during conversation"
+    - "Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status"
+  artifacts:
+    - path: "src/app/__main__.py"
+      provides: "CLI with enhanced session feedback and color-coded resource display"
+      contains: "Console(force_terminal=True), session file feedback messages"
+  key_links:
+    - from: "src/app/__main__.py"
+      to: "session file creation"
+      via: "Verbose feedback for session operations"
+      pattern: "session.*created|saved|loaded"
+    - from: "src/app/__main__.py"
+      to: "resource display"
+      via: "Console with force_terminal=True for color support"
+      pattern: "Console.*force_terminal=True"
+---
+
+<objective>
+Enhance CLI user feedback for session operations and fix color-coded resource display
+
+Purpose: Address two UX issues - users can't see when/where session files are created, and resource monitoring lacks color coding in terminal
+Output: CLI with clear session feedback and working color-coded resource monitoring
+</objective>
+
+<execution_context>
+@~/.opencode/get-shit-done/workflows/execute-plan.md
+@~/.opencode/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Gap closure context from UAT
+@.planning/phases/06-cli-interface/06-UAT.md
+
+# Previous session persistence and resource monitoring implementations
+@.planning/phases/06-cli-interface/06-02-SUMMARY.md
+@.planning/phases/06-cli-interface/06-04-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Add verbose session feedback and fix resource display colors</name>
+  <files>src/app/__main__.py</files>
+  <action>
+    Fix two issues in src/app/__main__.py:
+    
+    1. **Enhance session feedback** - Add user-friendly messaging for session operations:
+       - When creating new session: "Session created at ~/.mai/session.json"
+       - When loading existing session: "Session loaded from ~/.mai/session.json"  
+       - When saving session: "Conversation saved to ~/.mai/session.json"
+       - Enhance /session command to display file path and session stats
+       - Add feedback for session file creation in ~/.mai directory
+    
+    2. **Fix resource display color coding** - Modify ResourceDisplayManager:
+       - Change Console initialization to use Console(force_terminal=True) to force color output
+       - This overrides Rich's automatic terminal detection that disables colors in non-terminal environments
+       - Ensure rich imports and conditional logic properly handle this change
+    
+    Gap reasons:
+    - "Session system works correctly, but users lack clear feedback about when/where session files are created"
+    - "Rich console detects is_terminal=False and disables color output automatically"
+    
+    Make sure to preserve existing functionality while adding these improvements.
+  </action>
+  <verify>
+    # Test session feedback displays file path
+    echo "Testing session feedback..." && python -c "
+import sys
+sys.path.insert(0, 'src')
+from pathlib import Path
+import json
+
+# Check if session feedback logic exists
+with open('src/app/__main__.py', 'r') as f:
+    content = f.read()
+    if 'Session created at' in content and 'Session loaded from' in content:
+        print('✓ Session feedback messages added')
+    else:
+        print('✗ Session feedback messages missing')
+        exit(1)
+        
+    # Check for force_terminal=True
+    if 'force_terminal=True' in content:
+        print('✓ Console force_terminal=True added')
+    else:
+        print('✗ Console force_terminal=True missing')
+        exit(1)
+"
+  </verify>
+  <done>
+    CLI now provides clear feedback about session file operations and resource monitoring displays with proper color coding
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+Test both fixes by:
+1. Start new CLI session - should see "Session created at ~/.mai/session.json"
+2. Send a message - should see color-coded resource display (not just plain text)
+3. Use /session command - should show file location information
+4. Exit and restart - should see "Session loaded from ~/.mai/session.json"
+
+Expected: Clear feedback about session file operations and working color-coded resource monitoring
+</verification>
+
+<success_criteria>
+- Session creation displays file path feedback to user
+- Session loading displays file path feedback to user  
+- /session command shows file information
+- Resource monitoring uses color-coded status indicators
+- Console initialization uses force_terminal=True for color support
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/06-cli-interface/06-06-SUMMARY.md`
+</output>
--- a/.planning/phases/06-cli-interface/06-UAT.md
+++ b/.planning/phases/06-cli-interface/06-UAT.md
@@ -0,0 +1,102 @@
+---
+status: diagnosed
+phase: 06-cli-interface
+source: [06-02-SUMMARY.md, 06-04-SUMMARY.md]
+started: 2026-01-26T20:00:00Z
+updated: 2026-01-26T20:40:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. Session persistence across restarts
+expected: Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed
+result: issue
+reported: "Welcome back message shows time elapsed but error: 'ConversationState' object has no attribute 'set_conversation_history'"
+severity: major
+
+### 2. Session management commands
+expected: Type /session to see session info, /clear to start fresh session
+result: pass
+
+### 3. Conversation history saving
+expected: Messages are automatically saved to ~/.mai/session.json during conversation
+result: issue
+reported: "There is no session.json"
+severity: major
+
+### 4. Large conversation handling
+expected: When conversation exceeds 100 messages, older messages are truncated with notification
+result: skipped
+reason: User chose to skip testing 100 message truncation feature
+
+### 5. Real-time resource monitoring
+expected: Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status
+result: issue
+reported: "not color coded, but there"
+severity: minor
+
+### 6. Responsive terminal layout
+expected: Resource display adapts to terminal width (full/compact/minimal layouts)
+result: pass
+
+### 7. Resource alerts
+expected: System shows warnings when resources are constrained (high CPU, low memory)
+result: skipped
+reason: User chose to skip testing resource constraint warnings
+
+### 8. Graceful degradation without dependencies
+expected: CLI works normally even if rich/blessed packages are missing
+result: pass
+
+## Summary
+
+total: 8
+passed: 3
+issues: 3
+pending: 0
+skipped: 2
+
+## Gaps
+
+- truth: "Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed"
+  status: failed
+  reason: "User reported: Welcome back message shows time elapsed but error: 'ConversationState' object has no attribute 'set_conversation_history'"
+  severity: major
+  test: 1
+  root_cause: "Missing set_conversation_history method in ConversationState class"
+  artifacts:
+    - path: "src/mai/conversation/state.py"
+      issue: "Missing set_conversation_history method"
+  missing:
+    - "Add set_conversation_history method to convert Ollama messages back to ConversationTurn objects"
+  debug_session: ".planning/debug/resolved/session-persistence-error.md"
+- truth: "Messages are automatically saved to ~/.mai/session.json during conversation"
+  status: failed
+  reason: "User reported: There is no session.json"
+  severity: major
+  test: 3
+  root_cause: "Session system works correctly, but users lack clear feedback about when/where session files are created"
+  artifacts:
+    - path: "src/app/__main__.py"
+      issue: "Missing user-friendly messaging about session file creation and location"
+  missing:
+    - "Add verbose feedback for session operations"
+    - "Enhance /session command with file information display"
+    - "Improve new session creation messaging"
+  debug_session: ".planning/debug/resolved/missing-session-file.md"
+- truth: "Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status"
+  status: failed
+  reason: "User reported: not color coded, but there"
+  severity: minor
+  test: 5
+  root_cause: "Rich console detects is_terminal=False and disables color output automatically"
+  artifacts:
+    - path: "src/app/__main__.py"
+      issue: "Console() initialization without force_terminal parameter"
+  missing:
+    - "Modify ResourceDisplayManager to use Console(force_terminal=True)"
+  debug_session: ".planning/debug/resolved/missing-color-coding.md"