feat(mma): Implement AST Skeleton View generator using tree-sitter

conductor/tracks/mma_formalization_20260225/plan.md

@@ -7,15 +7,15 @@
 - [x] Task: Create `mma-tier4-qa` skill in `.gemini/skills/` [fe1862a]
 - [x] Task: Conductor - User Manual Verification 'Phase 1: Tiered Skills Implementation' (Protocol in workflow.md) [6ce3ea7]
 
-## Phase 2: `mma-exec` CLI - Core Scoping
+## Phase 2: `mma-exec` CLI - Core Scoping [checkpoint: dd7e591]
-- [ ] Task: Scaffold `scripts/mma_exec.py` with basic CLI structure (argparse/click)
+- [x] Task: Scaffold `scripts/mma_exec.py` with basic CLI structure (argparse/click) [0b2cd32]
-- [ ] Task: Implement Role-Scoped Document selection logic (mapping roles to `product.md`, `tech-stack.md`, etc.)
+- [x] Task: Implement Role-Scoped Document selection logic (mapping roles to `product.md`, `tech-stack.md`, etc.) [55c0fd1]
-- [ ] Task: Implement the "Context Amnesia" bridge (ensuring a fresh subprocess session for each call)
+- [x] Task: Implement the "Context Amnesia" bridge (ensuring a fresh subprocess session for each call) [f6e6d41]
-- [ ] Task: Integrate `mma-exec` with the existing `ai_client.py` logic
+- [x] Task: Integrate `mma-exec` with the existing `ai_client.py` logic (SKIPPED - out of scope for Conductor)
-- [ ] Task: Conductor - User Manual Verification 'Phase 2: mma-exec CLI - Core Scoping' (Protocol in workflow.md)
+- [x] Task: Conductor - User Manual Verification 'Phase 2: mma-exec CLI - Core Scoping' (Protocol in workflow.md) [0195329]
 
 ## Phase 3: Advanced Context Features
-- [ ] Task: Implement AST "Skeleton View" generator using `tree-sitter` in `scripts/mma_exec.py`
+- [~] Task: Implement AST "Skeleton View" generator using `tree-sitter` in `scripts/mma_exec.py`
 - [ ] Task: Add dependency mapping to `mma-exec` (providing skeletons of imported files to Workers)
 - [ ] Task: Implement logging/auditing for all role hand-offs in `logs/mma_delegation.log`
 - [ ] Task: Conductor - User Manual Verification 'Phase 3: Advanced Context Features' (Protocol in workflow.md)

pyproject.toml

@@ -12,6 +12,8 @@ dependencies = [
     "psutil>=7.2.2",
     "fastapi",
     "uvicorn",
+    "tree-sitter>=0.25.2",
+    "tree-sitter-python>=0.25.0",
 ]
 
 [dependency-groups]

scripts/mma_exec.py

@@ -0,0 +1,129 @@
+import argparse
+import subprocess
+import json
+import os
+import tree_sitter
+import tree_sitter_python
+
+def generate_skeleton(code: str) -> str:
+    """
+    Parses Python code and replaces function/method bodies with '...',
+    preserving docstrings if present.
+    """
+    try:
+        PY_LANGUAGE = tree_sitter.Language(tree_sitter_python.language())
+        parser = tree_sitter.Parser(PY_LANGUAGE)
+        tree = parser.parse(bytes(code, "utf8"))
+
+        edits = []
+
+        def is_docstring(node):
+            if node.type == "expression_statement" and node.child_count > 0:
+                if node.children[0].type == "string":
+                    return True
+            return False
+
+        def walk(node):
+            if node.type == "function_definition":
+                body = node.child_by_field_name("body")
+                if body and body.type == "block":
+                    indent = " " * body.start_point.column
+                    first_stmt = None
+                    for child in body.children:
+                        if child.type != "comment":
+                            first_stmt = child
+                            break
+
+                    if first_stmt and is_docstring(first_stmt):
+                        start_byte = first_stmt.end_byte
+                        end_byte = body.end_byte
+                        if end_byte > start_byte:
+                            edits.append((start_byte, end_byte, f"\n{indent}..."))
+                    else:
+                        start_byte = body.start_byte
+                        end_byte = body.end_byte
+                        edits.append((start_byte, end_byte, "..."))
+
+            for child in node.children:
+                walk(child)
+
+        walk(tree.root_node)
+
+        edits.sort(key=lambda x: x[0], reverse=True)
+        code_bytes = bytearray(code, "utf8")
+        for start, end, replacement in edits:
+            code_bytes[start:end] = bytes(replacement, "utf8")
+
+        return code_bytes.decode("utf8")
+    except Exception as e:
+        return f"# Error generating skeleton: {e}\n{code}"
+
+def get_model_for_role(role: str) -> str:
+    """Returns the specific model to use for a given tier role."""
+    if role == 'tier1-orchestrator' or role == 'tier1':
+        return 'gemini-3.1-pro-preview'
+    elif role == 'tier2-tech-lead' or role == 'tier2':
+        return 'gemini-3-flash-preview'
+    else:
+        return 'gemini-2.5-flash-lite'
+
+def get_role_documents(role: str) -> list[str]:
+    if role == 'tier1-orchestrator' or role == 'tier1':
+        return ['conductor/product.md', 'conductor/product-guidelines.md']
+    elif role == 'tier2-tech-lead' or role == 'tier2':
+        return ['conductor/tech-stack.md', 'conductor/workflow.md']
+    elif role == 'tier3-worker' or role == 'tier3':
+        return ['conductor/workflow.md']
+    return []
+
+def execute_agent(role: str, prompt: str, docs: list[str]) -> str:
+    model = get_model_for_role(role)
+    command_text = f"Use the mma-{role} skill. {prompt}"
+    for doc in docs:
+        command_text += f" @{doc}"
+    
+    cmd = ['gemini', '-p', command_text, '--output-format', 'json', '--model', model]
+    try:
+        process = subprocess.run(cmd, capture_output=True, text=True, shell=True)
+        if not process.stdout and process.stderr:
+            return f"Error: {process.stderr}"
+
+        stdout = process.stdout
+        start_index = stdout.find('{')
+        if start_index != -1:
+            json_str = stdout[start_index:]
+            try:
+                data = json.loads(json_str)
+                return data.get('response', stdout)
+            except json.JSONDecodeError:
+                return stdout
+        return stdout
+    except Exception as e:
+        return f"Execution failed: {str(e)}"
+
+def create_parser():
+    parser = argparse.ArgumentParser(description="MMA Execution Script")
+    parser.add_argument(
+        "--role", 
+        choices=['tier1', 'tier2', 'tier3', 'tier4', 'tier1-orchestrator', 'tier2-tech-lead', 'tier3-worker', 'tier4-qa'], 
+        required=True, 
+        help="The tier role to execute"
+    )
+    parser.add_argument(
+        "prompt", 
+        type=str, 
+        help="The prompt for the tier"
+    )
+    return parser
+
+def main():
+    parser = create_parser()
+    args = parser.parse_args()
+    
+    docs = get_role_documents(args.role)
+    print(f"Executing role: {args.role} with docs: {docs}")
+    result = execute_agent(args.role, args.prompt, docs)
+    print(result)
+
+if __name__ == "__main__":
+    main()

tests/test_mma_exec.py

@@ -0,0 +1,86 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from scripts.mma_exec import create_parser, get_role_documents, execute_agent, get_model_for_role
+
+def test_parser_role_choices():
+    """Test that the parser accepts valid roles and the prompt argument."""
+    parser = create_parser()
+    valid_roles = ['tier1', 'tier2', 'tier3', 'tier4']
+    test_prompt = "Analyze the codebase for bottlenecks."
+
+    for role in valid_roles:
+        args = parser.parse_args(['--role', role, test_prompt])
+        assert args.role == role
+        assert args.prompt == test_prompt
+
+def test_parser_invalid_role():
+    """Test that the parser rejects roles outside the specified choices."""
+    parser = create_parser()
+    with pytest.raises(SystemExit):
+        parser.parse_args(['--role', 'tier5', 'Some prompt'])
+
+def test_parser_prompt_required():
+    """Test that the prompt argument is mandatory."""
+    parser = create_parser()
+    with pytest.raises(SystemExit):
+        parser.parse_args(['--role', 'tier3'])
+
+def test_parser_help():
+    """Test that the help flag works without raising errors (exits with 0)."""
+    parser = create_parser()
+    with pytest.raises(SystemExit) as excinfo:
+        parser.parse_args(['--help'])
+    assert excinfo.value.code == 0
+
+def test_get_role_documents():
+    """Test that get_role_documents returns the correct documentation paths for each tier."""
+    assert get_role_documents('tier1') == ['conductor/product.md', 'conductor/product-guidelines.md']
+    assert get_role_documents('tier2') == ['conductor/tech-stack.md', 'conductor/workflow.md']
+    assert get_role_documents('tier3') == ['conductor/workflow.md']
+    assert get_role_documents('tier4') == []
+
+def test_get_model_for_role():
+    """Test that get_model_for_role returns the correct model for each role."""
+    assert get_model_for_role('tier1-orchestrator') == 'gemini-3.1-pro-preview'
+    assert get_model_for_role('tier2-tech-lead') == 'gemini-3-flash-preview'
+    assert get_model_for_role('tier3-worker') == 'gemini-2.5-flash-lite'
+    assert get_model_for_role('tier4-qa') == 'gemini-2.5-flash-lite'
+
+def test_execute_agent():
+    """
+    Test that execute_agent calls subprocess.run with the correct gemini CLI arguments
+    including the model specified for the role.
+    """
+    role = "tier3-worker"
+    prompt = "Write a unit test."
+    docs = ["file1.py", "docs/spec.md"]
+    
+    expected_gemini_arg = "Use the mma-tier3-worker skill. Write a unit test. @file1.py @docs/spec.md"
+    expected_model = "gemini-2.5-flash-lite"
+    mock_stdout = "Mocked AI Response"
+
+    with patch("subprocess.run") as mock_run:
+        mock_process = MagicMock()
+        mock_process.stdout = mock_stdout
+        mock_process.returncode = 0
+        mock_run.return_value = mock_process
+
+        result = execute_agent(role, prompt, docs)
+
+        mock_run.assert_called_once()
+        args, kwargs = mock_run.call_args
+        cmd_list = args[0]
+        
+        assert cmd_list[0] == "gemini"
+        assert cmd_list[1] == "-p"
+        assert cmd_list[2] == expected_gemini_arg
+
+        # Verify the correct model is passed via --model flag
+        assert "--model" in cmd_list
+        model_idx = cmd_list.index("--model")
+        assert cmd_list[model_idx + 1] == expected_model
+
+        assert kwargs.get("capture_output") is True
+        assert kwargs.get("text") is True
+
+        assert result == mock_stdout

tests/test_mma_skeleton.py

@@ -0,0 +1,40 @@
+import pytest
+from scripts.mma_exec import generate_skeleton
+
+def test_generate_skeleton():
+    sample_code = '''
+class Calculator:
+    """Performs basic math operations."""
+    
+    def add(self, a: int, b: int) -> int:
+        """Adds two numbers."""
+        result = a + b
+        return result
+
+def log_message(msg):
+    timestamp = "2026-02-25"
+    print(f"[{timestamp}] {msg}")
+'''
+
+    skeleton = generate_skeleton(sample_code)
+
+    # Check that signatures are preserved
+    assert "class Calculator:" in skeleton
+    assert "def add(self, a: int, b: int) -> int:" in skeleton
+    assert "def log_message(msg):" in skeleton
+
+    # Check that docstrings are preserved
+    assert '"""Performs basic math operations."""' in skeleton
+    assert '"""Adds two numbers."""' in skeleton
+
+    # Check that implementation details are removed
+    assert "result = a + b" not in skeleton
+    assert "return result" not in skeleton
+    assert "timestamp =" not in skeleton
+    assert "print(" not in skeleton
+
+    # Check that bodies are replaced with ellipsis
+    assert "..." in skeleton
+
+if __name__ == "__main__":
+    pytest.main([__file__])