# 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).