# Track Specification: Robust Live Simulation Verification

## Overview
Establish a robust, visual simulation framework to prevent regressions in the complex GUI and asynchronous orchestration layers. This track replaces manual human verification with an automated script that clicks through the GUI and verifies the rendered state.

## Goals
1.  **Simulation Framework Setup:** Build a dedicated test script (`tests/visual_sim_mma_v2.py`) utilizing `ApiHookClient` to control the live GUI.
2.  **Simulate Epic Planning:** Automate the clicking of "New Epic", inputting a prompt, and verifying the expected Tier 1 tracks appear in the UI.
3.  **Simulate Execution & Spawning:** Automate the selection of a track, the generation of the DAG, and the interaction with the HITL Approval modal.

## Constraints
-   Must run against a live instance of the application using `--enable-test-hooks`.
-   Must fail loudly if the visual state (e.g., rendered DAG nodes, text box contents) does not match expectations.

## Context & Origins
This track was born from the "Human Verification" phase of the initial MMA Orchestrator prototype (`mma_orchestrator_integration_20260226`). We realized that while the backend API plumbing for the hierarchical MMA tiers (Tiers 1-4) was technically functional, the product lacked the necessary state management, UX visualization, and human-in-the-loop security gates to be usable. 

**Key Takeaways from the Prototype Phase:**
- The Tier 2 (Tech Lead) needs its own track-scoped discussion history, rather than polluting the global project history.
- Tasks within a track require a DAG (Directed Acyclic Graph) engine to manage complex dependencies and blocking states.
- The GUI must visualize this DAG and stream the output of individual workers directly to their associated tasks.
- We must enforce tiered context subsetting so that Tier 3/4 workers don't receive the massive global context blob, and we need a pre-spawn approval modal so the user can intercept, review, and modify worker prompts/contexts before they execute.

**Instructions for the Implementing Agent:**
As you execute this track, ensure you maintain alignment with the other Phase 2 tracks. If you learn something that impacts the dependent tracks, please append a similar "Context Summary" to their `spec.md` files before concluding your run.

## Execution Order & Dependencies
This is a multi-track phase. To ensure architectural integrity, these tracks **MUST** be executed in the following strict order:
1. **MMA Data Architecture & DAG Engine:** (Builds the state and execution foundation)
2. **Tiered Context Scoping & HITL Approval:** (Builds the security and context subsetting on top of the state)
3. **MMA Dashboard Visualization Overhaul:** (Builds the UI to visualize the state and subsets)
4. **[CURRENT] Robust Live Simulation Verification:** (Builds the tests to verify the UI and state)

**Prerequisites for this track:** `MMA Dashboard Visualization Overhaul` MUST be completed (`[x]`) before starting this track.

## Session Compression (2026-02-28)
**Current State & Glaring Issues:**
1. **Brittle Interception System:** The visual simulation (`tests/visual_sim_mma_v2.py`) relies heavily on polling an `api_hooks.py` endpoint (`/api/gui/mma_status`) that aggregates several boolean flags (`pending_approval`, `pending_spawn`). This has proven extremely brittle. For example, `mock_gemini_cli.py` defaults to emitting a `read_file` tool call, which triggers the *general* tool approval popup (`_pending_ask`), freezing the test because it was expecting the *MMA spawn* popup (`_pending_mma_spawn`) or the *Track Proposal* modal.
2. **Mock Pollution in App Domain:** Previous attempts to fix the simulation shoehorned test-specific mock JSON responses directly into `ai_client.py` and `scripts/mma_exec.py`. This conflates the test environment with the production application codebase.
3. **Popup Handling Failures:** The GUI's state machine for closing popups (like `_show_track_proposal_modal` in `_cb_accept_tracks`) is desynchronized from the hook API. The test clicks "Accept", the tracks generate, but the UI state doesn't cleanly reset, leading to endless timeouts during test runs.

**Next Steps for the Handoff:**
- Completely rip out the hardcoded mock JSON arrays from `ai_client.py` and `scripts/mma_exec.py`.
- Refactor `tests/mock_gemini_cli.py` to be a pure, standalone mock that perfectly simulates the expected streaming behavior of `gemini_cli` without relying on the app to intercept specific magic prompts.
- Stabilize the hook API (`api_hooks.py`) so the test script can unambiguously distinguish between a general tool approval, an MMA step approval, and an MMA worker spawn approval, instead of relying on a fragile `pending_approval` catch-all.

**Session Compression (2026-02-28, Late Session Addendum)**
**Current Blocker:** The Tier 3 worker simulation is stuck. The orchestration loop in `multi_agent_conductor.py` correctly starts `run_worker_lifecycle`, and `ai_client.py` successfully sends a mock response back from `gemini_cli`. However, the visual test never sees this output in `mma_streams`.
- The GUI expects `handle_ai_response` to carry the final AI response (including `stream_id` mapping to a specific Tier 3 worker string).
- In earlier attempts, we tried manually pushing a `handle_ai_response` event back into the GUI's `event_queue` at the end of `run_worker_lifecycle`, but it seems the GUI is still looping infinitely, showing `Polling streams: ['Tier 1']`. The state machine doesn't seem to recognize that the Tier 3 task is done or correctly populate the stream dictionary for the UI to pick up.
- **Handoff Directive:** The next agent needs to trace exactly how a successful AI response from a *subprocess/thread* (which `run_worker_lifecycle` operates in) is supposed to bubble up to `self.mma_streams` in `gui_2.py`. Is `events.emit("response_received")` or `handle_ai_response` missing? Why is the test only seeing `'Tier 1'` in the `mma_streams` keys? Focus on the handoff between `ai_client.py` completing a run and `gui_2.py` rendering the result.