docs update (wip)

src/dag_engine.py

@@ -1,3 +1,31 @@
+"""
+DAG Engine - Directed Acyclic Graph execution for MMA ticket orchestration.
+
+This module provides the core graph data structures and state machine logic
+for executing implementation tickets in dependency order within the MMA
+(Multi-Model Agent) system.
+
+Key Classes:
+ - TrackDAG: Graph representation with cycle detection, topological sorting,
+   and transitive blocking propagation.
+ - ExecutionEngine: Tick-based state machine that evaluates the DAG and
+   manages task status transitions.
+
+Architecture Integration:
+ - TrackDAG is constructed from a list of Ticket objects (from models.py)
+ - ExecutionEngine is consumed by ConductorEngine (multi_agent_conductor.py)
+ - The tick() method is called in the main orchestration loop to determine
+   which tasks are ready for execution
+
+Thread Safety:
+ - This module is NOT thread-safe. Callers must synchronize access if used
+   from multiple threads (e.g., the ConductorEngine's async loop).
+
+See Also:
+ - docs/guide_mma.md for the full MMA orchestration documentation
+ - src/models.py for Ticket and Track data structures
+ - src/multi_agent_conductor.py for ConductorEngine integration
+"""
 from typing import List
 from src.models import Ticket
 

src/events.py

@@ -1,5 +1,33 @@
 """
-Decoupled event emission system for cross-module communication.
+Events - Decoupled event emission and queuing for cross-thread communication.
+
+This module provides three complementary patterns for thread-safe communication
+between the GUI main thread and background workers:
+
+1. EventEmitter: Pub/sub pattern for synchronous event broadcast
+   - Used for: API lifecycle events (request_start, response_received, tool_execution)
+   - Thread-safe: Callbacks execute on emitter's thread
+   - Example: ai_client.py emits 'request_start' and 'response_received' events
+
+2. SyncEventQueue: Producer-consumer pattern via queue.Queue
+   - Used for: Decoupled task submission where consumer polls at its own pace
+   - Thread-safe: Built on Python's thread-safe queue.Queue
+   - Example: Background workers submit tasks, main thread drains queue
+
+3. UserRequestEvent: Structured payload for AI request data
+   - Used for: Bundling prompt, context, files, and base_dir into single object
+   - Immutable data transfer object for cross-thread handoff
+
+Integration Points:
+ - ai_client.py: EventEmitter for API lifecycle events
+ - gui_2.py: Consumes events via _process_event_queue()
+ - multi_agent_conductor.py: Uses SyncEventQueue for state updates
+ - api_hooks.py: Pushes events to _api_event_queue for external visibility
+
+Thread Safety:
+ - EventEmitter: NOT thread-safe for concurrent on/emit (use from single thread)
+ - SyncEventQueue: FULLY thread-safe (built on queue.Queue)
+ - UserRequestEvent: Immutable, safe for concurrent access
 """
 import queue
 from typing import Callable, Any, Dict, List, Tuple

src/mcp_client.py

@@ -1,34 +1,56 @@
 # mcp_client.py
 """
-Note(Gemini):
-MCP-style file context tools for manual_slop.
-Exposes read-only filesystem tools the AI can call to selectively fetch file
-content on demand, instead of having everything inlined into the context block.
+MCP Client - Multi-tool filesystem and network operations with sandboxing.
 
-All access is restricted to paths that are either:
- - Explicitly listed in the project's allowed_paths set, OR
- - Contained within an allowed base_dir (must resolve to a subpath of it)
+This module implements a Model Context Protocol (MCP)-like interface for AI
+agents to interact with the filesystem and network. It provides 26 tools
+with a three-layer security model to prevent unauthorized access.
 
-This is heavily inspired by Claude's own tooling limits. We enforce safety here 
-so the AI doesn't wander outside the project workspace.
+Three-Layer Security Model:
+ 1. Allowlist Construction (configure()):
+    - Builds _allowed_paths from project file_items
+    - Populates _base_dirs from file parents and extra_base_dirs
+    - Sets _primary_base_dir for relative path resolution
+    
+ 2. Path Validation (_is_allowed()):
+    - Blacklist check: history.toml, *_history.toml, config, credentials
+    - Explicit allowlist check: _allowed_paths membership
+    - CWD fallback: allows cwd() subpaths if no base_dirs configured
+    - Base directory containment: must be subpath of _base_dirs
+    
+ 3. Resolution Gate (_resolve_and_check()):
+    - Converts relative paths using _primary_base_dir
+    - Resolves symlinks to prevent traversal attacks
+    - Returns (resolved_path, error_message) tuple
+
+Tool Categories:
+ - File I/O: read_file, list_directory, search_files, get_tree
+ - Surgical Edits: set_file_slice, edit_file
+ - AST-Based (Python): py_get_skeleton, py_get_code_outline, py_get_definition,
+   py_update_definition, py_get_signature, py_set_signature, py_get_class_summary,
+   py_get_var_declaration, py_set_var_declaration
+ - Analysis: get_file_summary, get_git_diff, py_find_usages, py_get_imports,
+   py_check_syntax, py_get_hierarchy, py_get_docstring
+ - Network: web_search, fetch_url
+ - Runtime: get_ui_performance
+
+Mutating Tools:
+ The MUTATING_TOOLS frozenset defines tools that modify files. ai_client.py
+ checks this set and routes to pre_tool_callback (GUI approval) if present.
+
+Thread Safety:
+ This module uses module-level global state (_allowed_paths, _base_dirs).
+ Call configure() before dispatch() in multi-threaded environments.
+
+See Also:
+ - docs/guide_tools.md for complete tool inventory and security model
+ - src/ai_client.py for tool dispatch integration
+ - src/shell_runner.py for PowerShell execution
 """
 # mcp_client.py
 
 #MCP-style file context tools for manual_slop.
 
-# Exposes read-only filesystem tools the AI can call to selectively fetch file
-# content on demand, instead of having everything inlined into the context block.
-# All access is restricted to paths that are either:
-#  - Explicitly listed in the project's allowed_paths set, OR
-#  - Contained within an allowed base_dir (must resolve to a subpath of it)
-
-# Tools exposed:
-#   read_file(path)              - return full UTF-8 content of a file
-#   list_directory(path)         - list entries in a directory (names + type)
-#   search_files(path, pattern)  - glob pattern search within an allowed dir
-#   get_file_summary(path)       - return the summarize.py heuristic summary
-#
-
 from __future__ import annotations
 import asyncio
 from pathlib import Path

src/models.py

@@ -1,3 +1,41 @@
+"""
+Models - Core data structures for MMA orchestration and project configuration.
+
+This module defines the primary dataclasses used throughout the Manual Slop
+application for representing tasks, tracks, and execution context.
+
+Key Data Structures:
+ - Ticket: Atomic unit of work with status, dependencies, and context requirements
+ - Track: Collection of tickets with a shared goal
+ - WorkerContext: Execution context for a Tier 3 worker
+ - Metadata: Track metadata (id, name, status, timestamps)
+ - TrackState: Serializable track state with discussion history
+ - FileItem: File configuration with auto-aggregate and force-full flags
+
+Status Machine (Ticket):
+ todo -> in_progress -> completed
+   |          |
+   v          v
+ blocked   blocked
+
+Serialization:
+ All dataclasses provide to_dict() and from_dict() class methods for TOML/JSON
+ persistence via project_manager.py.
+
+Thread Safety:
+ These dataclasses are NOT thread-safe. Callers must synchronize mutations
+ if sharing instances across threads (e.g., during ConductorEngine execution).
+
+Configuration Integration:
+ - load_config() / save_config() read/write the global config.toml
+ - AGENT_TOOL_NAMES defines the canonical list of MCP tools available to agents
+
+See Also:
+ - docs/guide_mma.md for MMA orchestration documentation
+ - src/dag_engine.py for TrackDAG and ExecutionEngine
+ - src/multi_agent_conductor.py for ConductorEngine
+ - src/project_manager.py for persistence layer
+"""
 from __future__ import annotations
 import tomllib
 import datetime