docs(mma): Draft Track 1 - The Memory Foundations

conductor/tracks/mma_implementation_20260224/migration_epics.md

@@ -0,0 +1,30 @@
+# MMA Migration: Epics and Detailed Tasks
+
+## Track 1: The Memory Foundations (AST Parser)
+
+**Goal:** Build the engine that prevents token-bloat by turning massive source files into curated memory views.
+
+### 1. TDD Approach for `tree-sitter` Integration
+- Create `tests/test_file_cache_ast.py`.
+- 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.
+- **Red Phase:** Ensure tests fail because `ASTParser` does not exist.
+- **Green Phase:** Implement the tree-sitter logic iteratively until strings match exactly.
+
+### 2. `ASTParser` Extraction Rules (Tasks)
+- **Task 1.1: Dependency Setup**
+  - Add `tree-sitter` and `tree-sitter-python` to `pyproject.toml` / `requirements.txt`.
+- **Task 1.2: Core Parser Class**
+  - Create `ASTParser` in `file_cache.py` that initializes the language parser.
+- **Task 1.3: Skeleton View Extraction**
+  - Write query to extract `function_definition` and `class_definition`.
+  - Keep signatures, parameters, and return type hints.
+  - Replace all bodies with `pass`.
+- **Task 1.4: Curated View Extraction**
+  - 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.
+  - Replace all other function bodies with `... # Hidden`.
+
+### 3. Acceptance Testing Criteria
+- **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.