# Specification: MMA Core Engine Implementation

## 1. Overview
This track consolidates the implementation of the 4-Tier Hierarchical Multi-Model Architecture into the `manual_slop` codebase. The architecture transitions the current monolithic single-agent loop into a compartmentalized, token-efficient, and fully debuggable state machine.

## 2. Functional Requirements

### Phase 1: The Memory Foundations (AST Parser)
- Integrate `tree-sitter` and `tree-sitter-python` into `pyproject.toml` / `requirements.txt`.
- Implement `ASTParser` in `file_cache.py` to extract strict memory views (Skeleton View, Curated View).
- Strip function bodies from dependencies while preserving `@core_logic` or `# [HOT]` logic for the target modules.

### Phase 2: State Machine & Data Structures
- Create `models.py` incorporating strict Pydantic/Dataclass schemas for `Ticket`, `Track`, and `WorkerContext`.
- Enforce rigid state mutators governing dependencies between tickets (e.g., locking execution until a stub generation ticket completes).

### Phase 3: The Linear Orchestrator & Execution Clutch
- Build `multi_agent_conductor.py` and a `ConductorEngine` dispatcher loop.
- Embed the "Execution Clutch" allowing developers to pause, review, and manually rewrite payloads (JSON history mutation) before applying changes to the local filesystem.

### Phase 4: Tier 4 QA Interception
- Augment `shell_runner.py` with try/except wrappers capturing process errors (`stderr`).
- Rather than feeding raw stack traces to an expensive model, instantly forward them to a stateless `default_cheap` sub-agent for a 20-word summarization that is subsequently injected into the primary worker's context.

### Phase 5: UI Decoupling & Tier 1/2 Routing (The Final Boss)
- Disconnect `gui_2.py` from direct LLM inference requests.
- Bind the GUI to a synchronous or `asyncio.Queue` Event Bus managed by the Orchestrator, allowing dynamic tracking of parallel worker executions without thread-locking the interface.

## 3. Acceptance Criteria
- [ ] A 1000-line script can be successfully parsed into a 100-line AST Skeleton.
- [ ] Tickets properly block and resolve depending on stub-generation dependencies.
- [ ] Shell errors are compressed into >50-token hints using the cheap utility model.
- [ ] The GUI remains responsive during multi-model generation phases.

## 4. Meta-Track Reference & Source of Truth
For the original rationale, API formatting recommendations (e.g., Godot ECS schemas vs Nested JSON), and strict token firewall workflows, refer back to the architectural planning meta-track: `conductor/tracks/mma_implementation_20260224/`.

**Fallback Source of Truth:**
As a fallback, any track or sub-task should absolve its source of truth by referencing the `./MMA_Support/` directory. This directory contains the original design documents and raw discussions from which the entire `mma_implementation` track and 4-Tier Architecture were initially generated.