manual_slop/MMA_Support/Implementation_Tracks.md

Iteration Plan (Implementation Tracks)

To safely refactor a linear, single-agent codebase into the 4-Tier Multi-Model Architecture without breaking the working prototype, the implementation should be sequenced into these five isolated Epics (Tracks):

Track 1: The Memory Foundations (AST Parser)

Goal: Build the engine that prevents token-bloat by turning massive source files into curated memory views. Implementation Details:

1. Integrate tree-sitter and language bindings into file_cache.py.
2. Build ASTParser extraction rules:
   • Skeleton View: Strip function/class bodies, preserving only signatures, parameters, and type hints.
   • Curated View: Preserve class structures, module docstrings, and bodies of functions marked # [HOT] or @core_logic. Replace standard bodies with ... # Hidden.
3. Acceptance: file_cache.get_curated_view('script.py') returns a perfectly formatted summary string in the terminal.

Track 2: State Machine & Data Structures

Goal: Define the rigid Python objects the AI agents will pass to each other to rely on structured data, not loose chat strings. Implementation Details:

1. Create models.py with pydantic or dataclasses for Track (Epic) and Ticket (Task).
2. Define WorkerContext holding the Ticket ID, assigned model (from agents.toml), isolated credentials.toml injection, and a messages payload array.
3. Add helper methods for state mutators (e.g., ticket.mark_blocked(), ticket.mark_complete()).
4. Acceptance: Instantiate a Track with 3 Tickets and successfully enforce state changes in Python without AI involvement.

Track 3: The Linear Orchestrator & Execution Clutch

Goal: Build the synchronous, debuggable core loop that runs a single Tier 3 Worker and pauses for human approval. Implementation Details:

1. Create multi_agent_conductor.py with a run_worker_lifecycle(ticket: Ticket) function.
2. Inject context (Raw View from file_cache.py) and format the messages array for the API.
3. Implement the Clutch (HITL): input() pause for CLI or wait state for GUI before executing the returned tool (e.g., write_file). Allow manual memory mutation of the JSON payload.
4. Acceptance: The script sends a hardcoded Ticket to DeepSeek, pauses in the terminal showing a diff, waits for user approval, applies the diff via mcp_client.py, and wipes the worker's history.

Track 4: Tier 4 QA Interception

Goal: Stop error traces from destroying the Worker's token window by routing crashes through a stateless translator. Implementation Details:

1. In shell_runner.py, intercept stderr (e.g., returncode != 0).
2. Do not append stderr to the main Worker's history. Instead, instantiate a synchronous API call to the default_cheap model.
3. Prompt: "You are an error parser. Output only a 1-2 sentence instruction on how to fix this syntax error." Send the raw stderr and target file snippet.
4. Append the translated 20-word fix to the main Worker's history as a "System Hint".
5. Acceptance: A deliberate syntax error triggers the execution engine to silently ping the cheap API, returning a 20-word correction to the Worker instead of a 200-line stack trace.

Track 5: UI Decoupling & Tier 1/2 Routing (The Final Boss)

Goal: Bring the system online by letting Tier 1 and Tier 2 dynamically generate Tickets managed by the async Event Bus. Implementation Details:

1. Implement an asyncio.Queue in multi_agent_conductor.py.
2. Write Tier 1 & 2 system prompts forcing output as strict JSON arrays (Tracks and Tickets).
3. Write the Dispatcher async loop to convert JSON into Ticket objects and push to the queue.
4. Enforce the Stub Resolver: If a Ticket archetype is contract_stubber, pause dependent Tickets, run the stubber, trigger file_cache.py to rebuild the Skeleton View, then resume.
5. Acceptance: Vague prompt ("Refactor config system") results in Tier 1 Track, Tier 2 Tickets (Interface stub + Implementation). System executes stub, updates AST, and finishes implementation automatically (or steps through if Linear toggle is on).