docs(mma): Draft Track 3 - The Linear Orchestrator & Execution Clutch

conductor/tracks/mma_implementation_20260224/migration_epics.md

@@ -1,32 +1,32 @@
-# MMA Migration: Epics and Detailed Tasks
+# MMA Migration: Epics and Detailed Tasks
-
+
-## Track 1: The Memory Foundations (AST Parser)
+## Track 1: The Memory Foundations (AST Parser)
-
+
-**Goal:** Build the engine that prevents token-bloat by turning massive source files into curated memory views.
+**Goal:** Build the engine that prevents token-bloat by turning massive source files into curated memory views.
-
+
-### 1. TDD Approach for `tree-sitter` Integration
+### 1. TDD Approach for `tree-sitter` Integration
-- Create `tests/test_file_cache_ast.py`.
+- Create `tests/test_file_cache_ast.py`.
-- Define mock Python source files containing various structures (classes, functions, docstrings, `@core_logic` decorators, `# [HOT]` comments).
+- Define mock Python source files containing various structures (classes, functions, docstrings, `@core_logic` decorators, `# [HOT]` comments).
-- Write failing tests that instantiate `ASTParser` and assert that `get_skeleton_view()` and `get_curated_view()` return the precisely filtered strings.
+- Write failing tests that instantiate `ASTParser` and assert that `get_skeleton_view()` and `get_curated_view()` return the precisely filtered strings.
-- **Red Phase:** Ensure tests fail because `ASTParser` does not exist.
+- **Red Phase:** Ensure tests fail because `ASTParser` does not exist.
-- **Green Phase:** Implement the tree-sitter logic iteratively until strings match exactly.
+- **Green Phase:** Implement the tree-sitter logic iteratively until strings match exactly.
-
+
-### 2. `ASTParser` Extraction Rules (Tasks)
+### 2. `ASTParser` Extraction Rules (Tasks)
-- **Task 1.1: Dependency Setup**
+- **Task 1.1: Dependency Setup**
-  - Add `tree-sitter` and `tree-sitter-python` to `pyproject.toml` / `requirements.txt`.
+  - Add `tree-sitter` and `tree-sitter-python` to `pyproject.toml` / `requirements.txt`.
-- **Task 1.2: Core Parser Class**
+- **Task 1.2: Core Parser Class**
-  - Create `ASTParser` in `file_cache.py` that initializes the language parser.
+  - Create `ASTParser` in `file_cache.py` that initializes the language parser.
-- **Task 1.3: Skeleton View Extraction**
+- **Task 1.3: Skeleton View Extraction**
-  - Write query to extract `function_definition` and `class_definition`.
+  - Write query to extract `function_definition` and `class_definition`.
-  - Keep signatures, parameters, and return type hints.
+  - Keep signatures, parameters, and return type hints.
-  - Replace all bodies with `pass`.
+  - Replace all bodies with `pass`.
-- **Task 1.4: Curated View Extraction**
+- **Task 1.4: Curated View Extraction**
-  - Write query to keep class structures and `expression_statement` docstrings.
+  - Write query to keep class structures and `expression_statement` docstrings.
-  - Implement heuristic to preserve full bodies of functions decorated with `@core_logic` or containing `# [HOT]` comments.
+  - Implement heuristic to preserve full bodies of functions decorated with `@core_logic` or containing `# [HOT]` comments.
-  - Replace all other function bodies with `... # Hidden`.
+  - Replace all other function bodies with `... # Hidden`.
-
+
-### 3. Acceptance Testing Criteria
+### 3. Acceptance Testing Criteria
-- **Unit Tests:** All AST parsing tests pass with >90% coverage for `file_cache.py`.
+- **Unit Tests:** All AST parsing tests pass with >90% coverage for `file_cache.py`.
 - **Integration Test:** Execute the parser on a large, complex project file (e.g., `ai_client.py`). The output `Skeleton View` must be less than 15% of the original token count. The `Curated View` must correctly retain docstrings and marked functions while stripping standard bodies.
 ## Track 2: State Machine & Data Structures
 
@@ -50,4 +50,30 @@
 
 ### 3. Acceptance Testing Criteria
 - **Unit Tests:** \models.py\ has 100% test coverage for all state transitions.
-- **Integration Test:** Instantiate a \Track\ with 3 dependent \Tickets\ in Python. Programmatically mark tickets as complete and assert that the subsequent dependent tickets transition from \locked\ to \pending\ without any AI involvement.
+- **Integration Test:** Instantiate a \Track\ with 3 dependent \Tickets\ in Python. Programmatically mark tickets as complete and assert that the subsequent dependent tickets transition from \locked\ to \pending\ without any 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.
+
+### 1. TDD Approach for \multi_agent_conductor.py\
+- Create \	ests/test_conductor.py\.
+- Write tests that mock the AI client response (e.g., returning a mock tool call like \write_file\).
+- Test that \
+un_worker_lifecycle(ticket: Ticket)\ fetches the Raw View from \ile_cache.py\, formats messages, and processes the mock output.
+- Test that execution pauses (waits for a simulated human signal) when the \	rust_level\ dictates.
+- **Red Phase:** Failure occurs because \multi_agent_conductor.py\ lacks the lifecycle execution loop.
+- **Green Phase:** Implement the \ConductorEngine\ core execution block.
+
+### 2. Linear Orchestration Tasks
+- **Task 3.1: The Engine Core**
+  - Create \multi_agent_conductor.py\. Implement the \ConductorEngine\ class containing the \
+un_worker_lifecycle\ synchronous execution.
+- **Task 3.2: Context Injection**
+  - Implement logic reading the Ticket target, querying \ile_cache.py\ for the \Raw View\, and formatting the messages array for the API.
+- **Task 3.3: The HITL Execution Clutch**
+  - Before executing tools via \mcp_client.py\ or \shell_runner.py\, intercept the tool payload if the Worker's archetype dictates a \step\ mode.
+  - Wait for explicit user confirmation via a CLI prompt (or event block for UI future-proofing). Allow editing of the JSON payload.
+  - Flush history upon \TicketCompleted\.
+
+### 3. Acceptance Testing Criteria