manual_slop/conductor/archive/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. 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).