manual_slop/conductor/tracks/documentation_refresh_20260224/spec.md

Track Specification: Deep Architectural Documentation Refresh

Overview

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.

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

• 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

• 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

• Documenting legacy gui_legacy.py code beyond its role as a fallback.
• Visual diagram generation (focusing on high-quality text-based architectural mapping).