# MMA Documentation Synthesis

## Key Takeaways

1. **Architecture Model**: 4-Tier Hierarchical Multi-Model Architecture mimicking a senior engineering department.
   - **Tier 1 (Product Manager)**: High-reasoning models (Gemini 3.1 Pro/Claude 3.5 Sonnet) focusing on Epics and Tracks.
   - **Tier 2 (Tech Lead)**: Mid-cost models (Gemini 3.0 Flash/2.5 Pro) for Track delegation, Ticket generation, and interface-driven development (Stub-and-Resolve).
   - **Tier 3 (Contributors)**: Cheap/Fast models (DeepSeek V3/R1, Gemini 2.5 Flash) acting as amnesiac workers for heads-down coding.
   - **Tier 4 (QA/Compiler)**: Ultra-cheap models (DeepSeek V3) for stateless translation of raw errors to human language.

2. **Strict Context Management**: 
   - Uses `tree-sitter` for deterministic AST extraction (`Skeleton View`, `Curated Implementation View`, `Directory Map`).
   - "Context Amnesia" ensures worker threads start fresh and do not accumulate hallucination-inducing token bloat.

3. **Data Pipelines & Formats**:
   - Tiers 1 & 2 output **Godot ECS Flat Relational Lists** (e.g., INI-style flat lists with `depends_on` pointers) to build DAGs. This avoids JSON nesting nightmares.
   - Tier 3 uses **XML tags** (`<file_path>`, `<file_content>`) to avoid string escaping friction.

4. **Execution Flow**:
   - The engine is decoupled from the UI using an `asyncio` event bus.
   - A global **"Execution Clutch"** allows falling back from `async` parallel swarm mode to strict `linear` step mode for deterministic debugging and human-in-the-loop (HITL) overrides.

## Constraints for Migration Plan

- **Security**: `credentials.toml` must be strictly isolated and ignored in version control.
- **Phased Rollout**: Migration cannot be a single rewrite. It must follow strict tracks: AST Parser -> State Machine -> Linear Orchestrator -> Tier 4 QA -> UI Decoupling.
- **Tooling Constraints**: `tree-sitter` is mandatory for AST parsing.
- **UI State**: The GUI must be fully decoupled ("dumb" renderer) responding to queue events instead of blocking on LLM calls.