prep doc track.

conductor/tracks/documentation_refresh_20260224/spec.md

@@ -1,38 +1,49 @@
-# Specification: Documentation Refresh and Context Cleanup
+# Track Specification: Deep Architectural Documentation Refresh
 
 ## Overview
-This track aims to modernize the project's documentation suite (Architecture, Tools, README) to reflect recent significant architectural additions, including the Conductor framework, the development of `gui_2.py`, and the API hook verification system. It also includes the decommissioning of `MainContext.md`, which has been identified as redundant in the current project structure.
+This track implements a high-density, expert-level documentation suite for the Manual Slop project, focusing on the complex asynchronous orchestration, the 4-Tier MMA (Hierarchical Multi-Model Architecture), and the robust visual simulation framework. The documentation style adheres to the "USA Graphics Company" values of high information density, tactile interaction, and deep technical transparency, inspired by the architectural guides of `VEFontCache-Odin` and `gencpp`.
 
-## Functional Requirements
-1.  **Architecture Update (`docs/guide_architecture.md`):**
-    -   Incorporate descriptions of the Conductor framework and its role in spec-driven development.
-    -   Document the dual-GUI structure (`gui.py` and `gui_2.py`) and their respective development stages.
-    -   Detail the `EventEmitter` and `ApiHookClient` as core architectural components.
-2.  **Tools Update (`docs/guide_tools.md`):**
-    -   Refresh documentation for the current MCP toolset.
-    -   Add documentation for the API hook client and automated GUI verification tools.
-    -   Update performance monitoring tool descriptions.
-3.  **README Refresh (`Readme.md`):**
-    -   Update setup instructions (e.g., `uv`, `credentials.toml`).
-    -   Highlight new features: Conductor integration, GUI 2.0, and automated testing capabilities.
-    -   Ensure the high-level project vision aligns with the current state.
-4.  **Context Cleanup:**
-    -   Permanently remove `MainContext.md` from the project root.
-    -   Update any internal references pointing to `MainContext.md`.
+## Goals
+1.  **Architectural Deep Dive:** Document the core engine, focusing on state management, asynchronous event loops, and the decoupling of the GUI from the AI client.
+2.  **Hook System Technical Reference:** Provide a low-level guide to the `HookServer`, `HookHandler`, and the IPC mechanism used for automated verification.
+3.  **Simulation & Testing Framework:** Detail the live GUI simulation strategy, including the use of `pytest` fixtures, `ApiHookClient`, and mock providers.
+4.  **MMA Orchestration Logic:** Document the 4-Tier hierarchy (Orchestrator, Tech Lead, Worker, QA), token firewalling, and the DAG-based task execution engine.
+5.  **Event Handling System:** Explain the dual event architecture using both synchronous `EventEmitter` and asynchronous `AsyncEventQueue`.
+
+## Functional Requirements (Documentation Areas)
+
+### 1. Core Architecture (`docs/guide_architecture.md`)
+-   **Lifetime & Execution Loop:** Detailed breakdown of the application startup, the interaction between the main thread and daemon threads, and the event-driven updates.
+-   **Asynchronous Orchestration:** Documentation of the `AsyncEventQueue` and how it prevents GUI blocking during long-running AI operations.
+-   **State Synchronization:** How the `_pending_gui_tasks` queue and `threading.Lock` are used to safely bridge the Hook Server thread and the Main GUI thread.
+-   **Linear Execution Clutch:** Explanation of the deterministic debugging mode and the step-through execution logic.
+
+### 2. Tooling & Hooks (`docs/guide_tools.md`)
+-   **IPC & Hook API:** A complete reference for all `/api/` endpoints, including data structures for `mma_status`, `diagnostics`, and `ask/respond`.
+-   **ApiHookClient:** Usage guide for the requests-based client, detailing polling strategies and retry logic.
+-   **MCP Toolset:** Updated documentation for the native MCP-like tools (file I/O, search, web fetch) and their security allowlist.
+
+### 3. Verification & Simulation (`docs/guide_simulations.md` - NEW)
+-   **Live GUI Verification:** How to run the app with `--enable-test-hooks` and use the `live_gui` fixture for end-to-end testing.
+-   **Visual Simulation Lifecycle:** Detailed breakdown of `tests/visual_sim_mma_v2.py`, explaining how it simulates user interaction and verifies rendered state (e.g., DAG nodes, stream output).
+-   **Mocking AI Providers:** How to use `tests/mock_gemini_cli.py` to test the full orchestration loop without incurring API costs.
+
+### 4. README & Vision (`Readme.md`)
+-   **Setup & Telemetry:** Updated instructions for `uv` and `credentials.toml`.
+-   **Feature Roadmap:** Highlighting the MMA Dashboard, DAG engine, and the 4-Tier delegation model.
 
 ## Non-Functional Requirements
--   **Link Validation:** All internal documentation links must be verified as valid.
--   **Code-Doc Alignment:** Architectural descriptions must accurately reflect the current code structure.
--   **Clarity & Brevity:** Documentation should remain concise and targeted at expert-level developers.
+-   **Indentation & Formatting:** Follow the project's AI-optimized compact style (1-space indentation for code snippets).
+-   **High Information Density:** Avoid conversational filler; focus on state transitions, data flow, and architectural constraints.
+-   **Accurate Code Linkage:** Documentation must include specific file names and symbol references (e.g., `AsyncEventQueue`, `_cb_accept_tracks`).
 
 ## Acceptance Criteria
--   [ ] `MainContext.md` is deleted from the project.
--   [ ] `docs/guide_architecture.md` is updated and reviewed for accuracy.
--   [ ] `docs/guide_tools.md` is updated and reviewed for accuracy.
--   [ ] `Readme.md` setup and feature sections are current.
--   [ ] All internal links between `Readme.md` and the `./docs/` folder are functional.
+-   [ ] `docs/guide_architecture.md` updated with "Odin-style" depth.
+-   [ ] `docs/guide_tools.md` contains a full API reference for the Hook system.
+-   [ ] `docs/guide_simulations.md` created, detailing the visual verification suite.
+-   [ ] `Readme.md` reflects the current high-density product vision.
+-   [ ] `MainContext.md` decommissioned and references removed.
 
 ## Out of Scope
--   Automated documentation generation (e.g., Sphinx, Doxygen).
--   In-depth documentation for features still in early prototyping stages.
--   Creating new video or visual walkthroughs.
+-   Documenting legacy `gui_legacy.py` code beyond its role as a fallback.
+-   Visual diagram generation (focusing on high-quality text-based architectural mapping).