manual_slop/MMA_UX_SPEC.md

MMA Observability & UX Specification

1. Goal

Implement the visible surface area of the 4-Tier Hierarchical Multi-Model Architecture within gui_2.py. This ensures the user can monitor, control, and debug the multi-agent execution flow.

2. Core Components

2.1 MMA Dashboard Panel

• Visibility: A new dockable panel named "MMA Dashboard".
• Track Status: Display the current active Track ID and overall progress (e.g., "3/10 Tickets Complete").
• Ticket DAG Visualization: A list or simple graph representing the Ticket queue.
  • Each ticket shows: ID, Target, Status (Pending, Running, Paused, Complete, Blocked).
  • Visual indicators for dependencies (e.g., indented or linked).

2.2 The Execution Clutch (HITL)

• Step Mode Toggle: A global or per-track checkbox to enable "Step Mode".
• Pause Points:
  • Pre-Execution: When a Tier 3 worker generates a tool call (e.g., write_file), the engine pauses.
  • UI Interaction: The GUI displays the proposed script/change and provides:
    • [Approve]: Proceed with execution.
    • [Edit Payload]: Open the Memory Mutator.
    • [Abort]: Mark the ticket as Blocked/Cancelled.
• Visual Feedback: Tactile/Arcade-style blinking or color changes when the engine is "Paused for HITL".

2.3 Memory Mutator (The "Debug" Superpower)

• Functionality: A modal or dedicated text area that allows the user to edit the raw JSON conversation history of a paused worker.
• Use Case: Fixing AI hallucinations or providing specific guidance mid-turn without restarting the context window.
• Integration: After editing, the "Approve" button sends the modified history back to the engine.

2.4 Tiered Metrics & Logs

• Observability: Show which model (Tier 1, 2, 3, or 4) is currently active.
• Sub-Agent Logs: Provide quick links to open the timestamped log files generated by mma_exec.py.

3. Technical Integration

• Event Bus: Use the existing AsyncEventQueue to push StateUpdateEvents from the ConductorEngine to the GUI.
• Non-Blocking: Ensure the UI remains responsive (FPS > 60) even when multiple tickets are processing or the engine is waiting for user input.