ed/manual_slop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

wrong archive location

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-03-01 13:17:34 -05:00
parent 3d398f1905
commit cf7938a843
8 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
conductor/archive/documentation_refresh_20260224/index.md Normal file
View File

@@ -0,0 +1,5 @@
# Track documentation_refresh_20260224 Context
- [Specification](./spec.md)
- [Implementation Plan](./plan.md)
- [Metadata](./metadata.json)

8
conductor/archive/documentation_refresh_20260224/metadata.json Normal file
View File

@@ -0,0 +1,8 @@
{
"track_id": "documentation_refresh_20260224",
"type": "chore",
"status": "new",
"created_at": "2026-02-24T18:35:00Z",
"updated_at": "2026-02-24T18:35:00Z",
"description": "Update ./docs/* & ./Readme.md, review ./MainContext.md significance (should we keep it..)."
}

38
conductor/archive/documentation_refresh_20260224/plan.md Normal file
View File

@@ -0,0 +1,38 @@
# Implementation Plan: Deep Architectural Documentation Refresh
## Phase 1: Context Cleanup & Research
- [x] Task: Audit references to `MainContext.md` across the project.
- [x] Task: Delete `MainContext.md` and update any identified references.
- [x] Task: Execute `py_get_skeleton` and `py_get_code_outline` for `events.py`, `api_hooks.py`, `api_hook_client.py`, and `gui_2.py` to create a technical map for the guides.
- [x] Task: Analyze the `live_gui` fixture in `tests/conftest.py` and the simulation loop in `tests/visual_sim_mma_v2.py`.
## Phase 2: Core Architecture Deep Dive
Update `docs/guide_architecture.md` with expert-level detail.
- [x] Task: Document the Dual-Threaded App Lifetime: Main GUI loop vs. Daemon execution threads.
- [x] Task: Detail the `AsyncEventQueue` and `EventEmitter` roles in the decoupling strategy.
- [x] Task: Explain the `_pending_gui_tasks` synchronization mechanism for bridging the Hook Server and GUI.
- [x] Task: Document the "Linear Execution Clutch" and its deterministic state machine.
- [x] Task: Verify the architectural descriptions against the actual implementation.
- [x] Task: Conductor - User Manual Verification 'Phase 2: Core Architecture Deep Dive' (Protocol in workflow.md)
## Phase 3: Hook System & Tooling Technical Reference
Update `docs/guide_tools.md` to include low-level API details.
- [x] Task: Create a comprehensive API reference for all `HookServer` endpoints.
- [x] Task: Document the `ApiHookClient` implementation, including retries and polling strategies.
- [x] Task: Update the MCP toolset guide with current native tool implementations.
- [x] Task: Document the `ask/respond` IPC flow for "Human-in-the-Loop" confirmations.
- [x] Task: Conductor - User Manual Verification 'Phase 3: Hook System & Tooling Technical Reference' (Protocol in workflow.md)
## Phase 4: Verification & Simulation Framework
Create the new `docs/guide_simulations.md` guide.
- [x] Task: Detail the Live GUI testing infrastructure: `--enable-test-hooks` and the `live_gui` fixture.
- [x] Task: Breakdown the Simulation Lifecycle: Startup, Polling, Interaction, and Assertion.
- [x] Task: Document the mock provider strategy using `tests/mock_gemini_cli.py`.
- [x] Task: Provide examples of visual verification tests (e.g., MMA lifecycle).
- [x] Task: Conductor - User Manual Verification 'Phase 4: Verification & Simulation Framework' (Protocol in workflow.md)
## Phase 5: README & Roadmap Update
- [x] Task: Update `Readme.md` with current setup (`uv`, `credentials.toml`) and vision.
- [x] Task: Perform a project-wide link validation of all Markdown files.
- [x] Task: Verify the high-density information style across all documentation.
- [x] Task: Conductor - User Manual Verification 'Phase 5: README & Roadmap Update' (Protocol in workflow.md)

45
conductor/archive/documentation_refresh_20260224/spec.md Normal file
View File

@@ -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).