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