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

prep doc track.

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-03-01 08:57:01 -05:00
parent efaf4e98c4
commit 27e67df4e3
3 changed files with 80 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
conductor/tracks/documentation_refresh_20260224/plan.md
View File

@@ -1,34 +1,38 @@
# Implementation Plan: Documentation Refresh and Context Cleanup
This plan follows the project's standard task workflow to modernize documentation and decommission redundant context files.
## Phase 1: Context Cleanup
Permanently remove redundant files and update project-wide references.
# Implementation Plan: Deep Architectural Documentation Refresh
## Phase 1: Context Cleanup & Research
- [ ] Task: Audit references to `MainContext.md` across the project.
- [ ] Task: Write failing test that verifies the absence of `MainContext.md` and related broken links.
- [ ] Task: Delete `MainContext.md` and update any identified references.
- [ ] Task: Verify that all internal links remain functional.
- [ ] Task: Conductor - User Manual Verification 'Context Cleanup' (Protocol in workflow.md)
- [ ] 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.
- [ ] Task: Analyze the `live_gui` fixture in `tests/conftest.py` and the simulation loop in `tests/visual_sim_mma_v2.py`.
## Phase 2: Core Documentation Refresh
Update the Architecture and Tools guides to reflect recent architectural changes.
## Phase 2: Core Architecture Deep Dive
Update `docs/guide_architecture.md` with expert-level detail.
- [ ] Task: Document the Dual-Threaded App Lifetime: Main GUI loop vs. Daemon execution threads.
- [ ] Task: Detail the `AsyncEventQueue` and `EventEmitter` roles in the decoupling strategy.
- [ ] Task: Explain the `_pending_gui_tasks` synchronization mechanism for bridging the Hook Server and GUI.
- [ ] Task: Document the "Linear Execution Clutch" and its deterministic state machine.
- [ ] Task: Verify the architectural descriptions against the actual implementation.
- [ ] Task: Conductor - User Manual Verification 'Phase 2: Core Architecture Deep Dive' (Protocol in workflow.md)
- [ ] Task: Audit `docs/guide_architecture.md` against current code (e.g., `EventEmitter`, `ApiHookClient`, Conductor).
- [ ] Task: Update `docs/guide_architecture.md` with current Conductor-driven architecture and dual-GUI structure.
- [ ] Task: Audit `docs/guide_tools.md` for toolset accuracy.
- [ ] Task: Update `docs/guide_tools.md` to include API hook client and performance monitoring documentation.
- [ ] Task: Verify documentation alignment with actual implementation.
- [ ] Task: Conductor - User Manual Verification 'Core Documentation Refresh' (Protocol in workflow.md)
## Phase 3: Hook System & Tooling Technical Reference
Update `docs/guide_tools.md` to include low-level API details.
- [ ] Task: Create a comprehensive API reference for all `HookServer` endpoints.
- [ ] Task: Document the `ApiHookClient` implementation, including retries and polling strategies.
- [ ] Task: Update the MCP toolset guide with current native tool implementations.
- [ ] Task: Document the `ask/respond` IPC flow for "Human-in-the-Loop" confirmations.
- [ ] Task: Conductor - User Manual Verification 'Phase 3: Hook System & Tooling Technical Reference' (Protocol in workflow.md)
## Phase 3: README Refresh and Link Validation
Modernize the primary project entry point and ensure documentation integrity.
## Phase 4: Verification & Simulation Framework
Create the new `docs/guide_simulations.md` guide.
- [ ] Task: Detail the Live GUI testing infrastructure: `--enable-test-hooks` and the `live_gui` fixture.
- [ ] Task: Breakdown the Simulation Lifecycle: Startup, Polling, Interaction, and Assertion.
- [ ] Task: Document the mock provider strategy using `tests/mock_gemini_cli.py`.
- [ ] Task: Provide examples of visual verification tests (e.g., MMA lifecycle).
- [ ] Task: Conductor - User Manual Verification 'Phase 4: Verification & Simulation Framework' (Protocol in workflow.md)
- [ ] Task: Audit `Readme.md` for accuracy of setup instructions and feature highlights.
- [ ] Task: Write failing test (or link audit) that identifies outdated setup steps or broken links.
- [ ] Task: Update `Readme.md` with `uv` setup, current project vision, and feature lists (Conductor, GUI 2.0).
- [ ] Task: Perform a project-wide link validation of all Markdown files in `./docs/` and the root.
- [ ] Task: Verify setup instructions by performing a manual walkthrough of the Readme steps.
- [ ] Task: Conductor - User Manual Verification 'README Refresh and Link Validation' (Protocol in workflow.md)
---
[checkpoint: (SHA will be recorded here)]
## Phase 5: README & Roadmap Update
- [ ] Task: Update `Readme.md` with current setup (`uv`, `credentials.toml`) and vision.
- [ ] Task: Perform a project-wide link validation of all Markdown files.
- [ ] Task: Verify the high-density information style across all documentation.
- [ ] Task: Conductor - User Manual Verification 'Phase 5: README & Roadmap Update' (Protocol in workflow.md)

69
conductor/tracks/documentation_refresh_20260224/spec.md
View File

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