docs(src): Update documentation for src/ layout and sloppy.py entry point

Readme.md

@@ -35,24 +35,26 @@ The **MMA (Multi-Model Agent)** system decomposes epics into tracks, tracks into
 
 ## Module Map
 
-| File | Lines | Role |
+Core implementation resides in the `src/` directory.
-|---|---|---|
+
-| `gui_2.py` | ~3080 | Primary ImGui interface — App class, frame-sync, HITL dialogs |
+| File | Role |
-| `ai_client.py` | ~1800 | Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, Gemini CLI) |
+|---|---|
-| `mcp_client.py` | ~870 | 26 MCP tools with filesystem sandboxing and tool dispatch |
+| `src/gui_2.py` | Primary ImGui interface — App class, frame-sync, HITL dialogs |
-| `api_hooks.py` | ~330 | HookServer — REST API for external automation on `:8999` |
+| `src/ai_client.py` | Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, Gemini CLI) |
-| `api_hook_client.py` | ~245 | Python client for the Hook API (used by tests and external tooling) |
+| `src/mcp_client.py` | 26 MCP tools with filesystem sandboxing and tool dispatch |
-| `multi_agent_conductor.py` | ~250 | ConductorEngine — Tier 2 orchestration loop with DAG execution |
+| `src/api_hooks.py` | HookServer — REST API for external automation on `:8999` |
-| `conductor_tech_lead.py` | ~100 | Tier 2 ticket generation from track briefs |
+| `src/api_hook_client.py` | Python client for the Hook API (used by tests and external tooling) |
-| `dag_engine.py` | ~100 | TrackDAG (dependency graph) + ExecutionEngine (tick-based state machine) |
+| `src/multi_agent_conductor.py` | ConductorEngine — Tier 2 orchestration loop with DAG execution |
-| `models.py` | ~100 | Ticket, Track, WorkerContext dataclasses |
+| `src/conductor_tech_lead.py` | Tier 2 ticket generation from track briefs |
-| `events.py` | ~89 | EventEmitter, AsyncEventQueue, UserRequestEvent |
+| `src/dag_engine.py` | TrackDAG (dependency graph) + ExecutionEngine (tick-based state machine) |
-| `project_manager.py` | ~300 | TOML config persistence, discussion management, track state |
+| `src/models.py` | Ticket, Track, WorkerContext dataclasses |
-| `session_logger.py` | ~200 | JSON-L + markdown audit trails (comms, tools, CLI, hooks) |
+| `src/events.py` | EventEmitter, AsyncEventQueue, UserRequestEvent |
-| `shell_runner.py` | ~100 | PowerShell execution with timeout, env config, QA callback |
+| `src/project_manager.py` | TOML config persistence, discussion management, track state |
-| `file_cache.py` | ~150 | ASTParser (tree-sitter) — skeleton and curated views |
+| `src/session_logger.py` | JSON-L + markdown audit trails (comms, tools, CLI, hooks) |
-| `summarize.py` | ~120 | Heuristic file summaries (imports, classes, functions) |
+| `src/shell_runner.py` | PowerShell execution with timeout, env config, QA callback |
-| `outline_tool.py` | ~80 | Hierarchical code outline via stdlib `ast` |
+| `src/file_cache.py` | ASTParser (tree-sitter) — skeleton and curated views |
+| `src/summarize.py` | Heuristic file summaries (imports, classes, functions) |
+| `src/outline_tool.py` | Hierarchical code outline via stdlib `ast` |
 
 ---
 
@@ -89,8 +91,8 @@ api_key = "YOUR_KEY"
 ### Running
 
 ```powershell
-uv run gui_2.py                        # Normal mode
+uv run sloppy.py                        # Normal mode
-uv run gui_2.py --enable-test-hooks    # With Hook API on :8999
+uv run sloppy.py --enable-test-hooks    # With Hook API on :8999
 ```
 
 ### Running Tests

conductor/tech-stack.md

@@ -37,7 +37,7 @@
 - **psutil:** For system and process monitoring (CPU/Memory telemetry).
 - **uv:** An extremely fast Python package and project manager.
 - **pytest:** For unit and integration testing, leveraging custom fixtures for live GUI verification.
-- **Taxonomy & Artifacts:** Enforces a clean root by redirecting session logs to `logs/sessions/`, sub-agent logs to `logs/agents/`, and error logs to `logs/errors/`. Temporary test data and test logs are siloed in `tests/artifacts/` and `tests/logs/`.
+- **Taxonomy & Artifacts:** Enforces a clean root by organizing core implementation into a `src/` directory, and redirecting session logs to `logs/sessions/`, sub-agent logs to `logs/agents/`, and error logs to `logs/errors/`. Temporary test data and test logs are siloed in `tests/artifacts/` and `tests/logs/`.
 - **ApiHookClient:** A dedicated IPC client for automated GUI interaction and state inspection.
 - **mma-exec / mma.ps1:** Python-based execution engine and PowerShell wrapper for managing the 4-Tier MMA hierarchy and automated documentation mapping.
 - **dag_engine.py:** A native Python utility implementing `TrackDAG` and `ExecutionEngine` for dependency resolution, cycle detection, transitive blocking propagation, and programmable task execution loops.

conductor/tracks/codebase_migration_20260302/plan.md

@@ -17,14 +17,6 @@
 - [x] Task: Conductor - User Manual Verification 'Phase 3: Entry Point & Import Resolution' (Checkpoint: 24f385e)
 
 ## Phase 4: Final Validation & Documentation
-- [ ] Task: Full Test Suite Validation
+- [x] Task: Full Test Suite Validation
-    - [ ] WHERE: Project root
+- [x] Task: Update Core Documentation
-    - [ ] WHAT: Run `uv run pytest`. Fix any remaining path resolution issues for logs, artifacts, and configs.
-    - [ ] HOW: Verify 100% pass rate.
-    - [ ] SAFETY: Artifacts must still be written to `tests/artifacts/`.
-- [ ] Task: Update Core Documentation
-    - [ ] WHERE: `Readme.md`, `docs/`, `conductor/tech-stack.md`
-    - [ ] WHAT: Document `sloppy.py` as the new entry point. Document the `src/` directory layout.
-    - [ ] HOW: Surgical text replacement.
-    - [ ] SAFETY: Accurate representation of new structure.
 - [ ] Task: Conductor - User Manual Verification 'Phase 4: Final Validation & Documentation' (Protocol in workflow.md)

docs/guide_architecture.md

@@ -8,6 +8,28 @@
 
 Manual Slop solves a single tension: **AI reasoning is high-latency and non-deterministic; GUI interaction must be low-latency and responsive.** The engine enforces strict decoupling between three thread domains so that multi-second LLM calls never block the render loop, and every AI-generated payload passes through a human-auditable gate before execution.
 
+## Project Structure
+
+The codebase is organized into a `src/` layout to separate implementation from configuration and artifacts.
+
+```
+manual_slop/
+├── conductor/          # Conductor tracks, specs, and plans
+├── docs/               # Deep-dive architectural documentation
+├── logs/               # Session logs, agent traces, and errors
+├── scripts/            # Build, migration, and IPC bridge scripts
+├── src/                # Core Python implementation
+│   ├── ai_client.py    # LLM provider abstraction
+│   ├── gui_2.py        # Main ImGui application
+│   ├── mcp_client.py   # MCP tool implementation
+│   └── ...             # Other core modules
+├── tests/              # Pytest suite and simulation fixtures
+├── simulation/         # Workflow and agent simulation logic
+├── sloppy.py           # Primary application entry point
+├── config.toml         # Global application settings
+└── manual_slop.toml    # Project-specific configuration
+```
+
 ---
 
 ## Thread Domains

project_history.toml

@@ -8,5 +8,5 @@ active = "main"
 
 [discussions.main]
 git_commit = ""
-last_updated = "2026-03-04T10:04:31"
+last_updated = "2026-03-04T10:09:06"
 history = []