wrong archive location

conductor/archive/documentation_refresh_20260224/spec.md

@@ -0,0 +1,45 @@
+# Track Specification: Deep Architectural Documentation Refresh
+
+## Overview
+This track implements a high-density, expert-level documentation suite for the Manual Slop project. The documentation style is strictly modeled after the **pedagogical and narrative standards** of `gencpp` and `VEFontCache-Odin`. It moves beyond simple "User Guides" to provide a **"USA Graphics Company"** architectural reference: high information density, tactical technical transparency, and a narrative intent that guides a developer from high-level philosophy to low-level implementation.
+
+## Pedagogical Goals
+1.  **Narrative Intent:** Documentation must transition the reader through a logical learning journey: **Philosophy/Mental Model -> Architectural Boundaries -> Implementation Logic -> Verification/Simulation.**
+2.  **High Information Density:** Eliminate conversational filler and "fluff." Every sentence must provide architectural signal (state transitions, data flows, constraints).
+3.  **Technical Transparency:** Document the "How" and "Why" behind design decisions (e.g., *Why* the dual-threaded `Asyncio` loop? *How* does the "Execution Clutch" bridge the thread gap?).
+4.  **Architectural Mapping:** Use precise symbol names (`AsyncEventQueue`, `_pending_gui_tasks`, `HookServer`) to map the documentation directly to the source code.
+5.  **Multi-Layered Depth:** Each major component (Architecture, Tools, Simulations) must have its own dedicated, expert-level guide. No consolidation into single, shallow files.
+
+## Functional Requirements (Documentation Areas)
+
+### 1. Core Architecture (`docs/guide_architecture.md`)
+-   **System Philosophy:** The "Decoupled State Machine" mental model.
+-   **Application Lifetime:** The multi-threaded boot sequence and the "Dual-Flush" persistence model.
+-   **The Task Pipeline:** Detailed producer-consumer synchronization between the GUI (Main) and AI (Daemon) threads.
+-   **The Execution Clutch (HITL):** Detailed state machine for human-in-the-loop interception and payload mutation.
+
+### 2. Tooling & IPC Reference (`docs/guide_tools.md`)
+-   **MCP Bridge:** Low-level security constraints and filesystem sandboxing.
+-   **Hook API:** A full technical reference for the REST/IPC interface (endpoints, payloads, diagnostics).
+-   **IPC Flow:** The `ask/respond` sequence for synchronous human-in-the-loop requests.
+
+### 3. Verification & Simulation Framework (`docs/guide_simulations.md`)
+-   **Infrastructure:** The `--enable-test-hooks` flag and the `live_gui` pytest fixture.
+-   **Lifecycle:** The "Puppeteer" pattern for driving the GUI via automated clients.
+-   **Mocking Strategy:** Script-based AI provider mocking via `mock_gemini_cli.py`.
+-   **Visual Assertion:** Examples of verifying the rendered state (DAG, Terminal streams) rather than just API returns.
+
+### 4. Product Vision & Roadmap (`Readme.md`)
+-   **Technological Identity:** High-density experimental tool for local AI orchestration.
+-   **Pedagogical Landing:** Direct links to the deep-dive guides to establish the project's expert-level tone immediately.
+
+## Acceptance Criteria for Expert Review (Claude Opus)
+-   [ ] **Zero Filler:** No introductory "In this section..." or "Now we will..." conversational markers.
+-   [ ] **Structural Parity:** Documentation follows the `gencpp` pattern (Philosophy -> Code Paths -> Interface).
+-   [ ] **Expert-Level Detail:** Includes data structures, locking mechanisms, and thread-safety constraints.
+-   [ ] **Narrative Cohesion:** The documents feel like a single, expert-authored manual for a complex graphics or systems engine.
+-   [ ] **Tactile Interaction:** Explains the "Linear Execution Clutch" as a physical shift in the application's processing gears.
+
+## Out of Scope
+-   Documenting legacy `gui_legacy.py` code beyond its role as a fallback.
+-   Visual diagram generation (focusing on high-signal text-based architectural mapping).