manual_slop/conductor/tracks/mma_implementation_20260224/migration_epics.md

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.