plans and docs

conductor/tracks/ts_cpp_tree_sitter_20260308/metadata.json

@@ -0,0 +1,16 @@
+{
+  "track_id": "ts_cpp_tree_sitter_20260308",
+  "title": "Tree-Sitter C/C++ MCP Tools",
+  "status": "pending",
+  "created": "2026-03-08",
+  "priority": "high",
+  "owner": "tier2-tech-lead",
+  "description": "Add tree-sitter-based C and C++ parsing to mcp_client with skeleton and outline tools (ts_c_*, ts_cpp_*)",
+  "dependencies": [],
+  "out_of_scope": [
+    "Cross-file symbol resolution",
+    "gencpp integration",
+    "Template instantiation analysis",
+    "Macro expansion"
+  ]
+}

conductor/tracks/ts_cpp_tree_sitter_20260308/plan.md

@@ -0,0 +1,100 @@
+# Plan: Tree-Sitter C/C++ MCP Tools
+
+## Overview
+Add tree-sitter-based C and C++ parsing to mcp_client with skeleton and outline tools.
+
+## Phase 1: Dependencies
+Focus: Add tree-sitter C/C++ grammars
+
+- [ ] Task 1.1: Add tree-sitter-c and tree-sitter-cpp to pyproject.toml
+  - WHERE: pyproject.toml:16-17
+  - WHAT: Add `"tree-sitter-c>=0.23.0", "tree-sitter-cpp>=0.3.0"` to dependencies
+  - HOW: Edit dependencies array
+  - SAFETY: No breaking changes
+
+## Phase 2: ASTParser Extensions
+Focus: Extend ASTParser to support C/C++ languages
+
+- [ ] Task 2.1: Modify ASTParser.__init__ to accept "c" and "cpp" languages
+  - WHERE: src/file_cache.py:22-28
+  - WHAT: Add language loading for tree-sitter-c and tree-sitter-cpp
+  - HOW: Import tree_sitter_c, tree_sitter_cpp; load Language(tree_sitter_c.language()) etc.
+  - SAFETY: Maintain existing Python support
+
+- [ ] Task 2.2: Implement C skeleton extraction
+  - WHERE: src/file_cache.py (new method or extend get_skeleton)
+  - WHAT: Extract function_definition, struct_specifier, enum_specifier, typedef, union_specifier
+  - HOW: Tree-sitter node traversal similar to Python pattern
+  - SAFETY: New method, no modifications to existing
+
+- [ ] Task 2.3: Implement C++ skeleton extraction
+  - WHERE: src/file_cache.py
+  - WHAT: Add class_specifier, template_declaration, access_specifier, namespace_specifier
+  - HOW: Extend C skeleton logic with C++ specific nodes
+  - SAFETY: New method
+
+- [ ] Task 2.4: Implement code outline for C and C++
+  - WHERE: src/file_cache.py
+  - WHAT: Return hierarchical structure with line ranges (matching py_get_code_outline format)
+  - HOW: Similar to Python get_code_outline pattern
+  - SAFETY: New method
+
+## Phase 3: MCP Tool Integration
+Focus: Add tools to mcp_client dispatch
+
+- [ ] Task 3.1: Add ts_c_get_skeleton tool
+  - WHERE: src/mcp_client.py (add function and register)
+  - WHAT: Tool that calls file_cache ASTParser for C skeleton
+  - HOW: Follow py_get_skeleton pattern
+  - SAFETY: New tool, no modifications to existing
+
+- [ ] Task 3.2: Add ts_cpp_get_skeleton tool
+  - WHERE: src/mcp_client.py
+  - WHAT: Tool that calls file_cache ASTParser for C++ skeleton
+  - HOW: Same as above with cpp language
+  - SAFETY: New tool
+
+- [ ] Task 3.3: Add ts_c_get_code_outline tool
+  - WHERE: src/mcp_client.py
+  - WHAT: Tool that calls file_cache for C code outline
+  - HOW: Follow py_get_code_outline pattern
+  - SAFETY: New tool
+
+- [ ] Task 3.4: Add ts_cpp_get_code_outline tool
+  - WHERE: src/mcp_client.py
+  - WHAT: Tool that calls file_cache for C++ code outline
+  - HOW: Same as above with cpp language
+  - SAFETY: New tool
+
+- [ ] Task 3.5: Register tools in get_tool_schemas
+  - WHERE: src/mcp_client.py:998-1000
+  - WHAT: Add schemas for all 4 new tools
+  - HOW: Append to MCP_TOOL_SPECS list
+  - SAFETY: Append only
+
+## Phase 4: Tests
+Focus: Verify C/C++ tools work correctly
+
+- [ ] Task 4.1: Write tests for ts_c_get_skeleton
+  - WHERE: tests/test_ts_c_tools.py (new file)
+  - WHAT: Test C skeleton extraction on sample C code
+  - HOW: Use pytest with sample C file content
+  - SAFETY: New test file
+
+- [ ] Task 4.2: Write tests for ts_cpp_get_skeleton
+  - WHERE: tests/test_ts_cpp_tools.py (new file)
+  - WHAT: Test C++ skeleton extraction on sample C++ code
+  - HOW: Use pytest with sample C++ code
+  - SAFETY: New test file
+
+- [ ] Task 4.3: Write tests for code outline tools
+  - WHERE: tests/test_ts_c_tools.py / test_ts_cpp_tools.py
+  - WHAT: Test line range extraction
+  - HOW: Assert correct line numbers
+  - SAFETY: New tests
+
+- [ ] Task 4.4: Integration test - verify tools dispatch correctly
+  - WHERE: tests/test_mcp_client.py
+  - WHAT: Test dispatch of ts_c_* and ts_cpp_* tools
+  - HOW: Mock file_cache, verify correct function called
+  - SAFETY: Additive test

conductor/tracks/ts_cpp_tree_sitter_20260308/spec.md

@@ -0,0 +1,72 @@
+# Track Specification: Tree-Sitter C/C++ MCP Tools
+
+## Overview
+
+Add tree-sitter-based C and C++ parsing support to the MCP client, providing skeleton and outline tools for C/C++ codebases. Tools will be prefixed `ts_c_` and `ts_cpp_` to distinguish from existing Python tools and leave namespace open for future gencpp integration.
+
+## Current State Audit (as of 08e003a)
+
+### Already Implemented
+- `src/file_cache.py`: ASTParser class with tree-sitter-python support
+- `src/mcp_client.py`: 26 MCP tools (all Python-prefixed: `py_get_skeleton`, `py_get_definition`, etc.)
+- `pyproject.toml`: tree-sitter>=0.25.2 and tree-sitter-python>=0.25.0 already listed
+- Existing pattern: `get_skeleton()`, `get_code_outline()` methods extract functions, classes, docstrings
+
+### Gaps to Fill (This Track's Scope)
+- No C/C++ tree-sitter grammars installed
+- No C/C++ parsing logic in ASTParser
+- No MCP tools for C/C++ code extraction
+
+## Goals
+
+1. Add tree-sitter-c and tree-sitter-cpp dependencies
+2. Extend ASTParser to support C and C++ languages
+3. Implement skeleton and outline generation for C/C++ (functions, structs, enums, classes)
+4. Add MCP tools: `ts_c_get_skeleton`, `ts_cpp_get_skeleton`, `ts_c_get_code_outline`, `ts_cpp_get_code_outline`
+5. Register tools in mcp_client dispatch
+
+## Functional Requirements
+
+### Dependencies
+- Add `tree-sitter-c` to pyproject.toml
+- Add `tree-sitter-cpp` to pyproject.toml
+
+### ASTParser Extensions
+- Modify `ASTParser.__init__` to accept "c", "cpp", "python" as valid languages
+- Load appropriate tree-sitter language grammar based on parameter
+- Reuse existing caching mechanism (`get_cached_tree`)
+- Implement C-specific node types: `function_definition`, `struct_specifier`, `enum_specifier`, `typedef`
+- Implement C++-specific node types: all C types plus `class_specifier`, `access_specifier`, `template_declaration`
+
+### MCP Tools
+| Tool Name | Description |
+|-----------|-------------|
+| `ts_c_get_skeleton` | Returns C file skeleton (function signatures, struct/union/enum definitions) |
+| `ts_cpp_get_skeleton` | Returns C++ file skeleton (above + class methods, templates, namespaces) |
+| `ts_c_get_code_outline` | Returns hierarchical C outline (functions, structs, enums, globals with line ranges) |
+| `ts_cpp_get_code_outline` | Returns hierarchical C++ outline (above + classes, templates, namespaces) |
+
+### Tool Output Format
+Match existing Python tool formats for consistency:
+- Skeleton: signatures + docstrings, bodies replaced with `...`
+- Outline: hierarchical list with `[Class] name (Lines X-Y)` format
+
+## Non-Functional Requirements
+
+- Follow existing 1-space indentation code style
+- Use exact same patterns as existing Python tree-sitter implementation
+- Maintain AST cache with mtime invalidation (reuse existing logic)
+- Tools must pass allowlist check in mcp_client
+
+## Architecture Reference
+
+- **ASTParser pattern**: `src/file_cache.py:16-333` - existing tree-sitter integration
+- **MCP tool dispatch**: `src/mcp_client.py:920-987` - tool registration and dispatch
+- **Tool schema format**: `src/mcp_client.py:998-1000` - `get_tool_schemas()`
+
+## Out of Scope
+- Cross-file symbol resolution (AI uses search tools for this)
+- Template instantiation analysis
+- Macro expansion
+- gencpp integration (future separate track)
+- Writing to C/C++ files (read-only for now)