docs: Core Phase 4 plan — Python language support

[prosdev]

Summary

Plan for adding Python as a supported language in dev-agent. 4 parts, builds entirely on existing tree-sitter infrastructure from MCP Phase 1.

Parts

Part	What	Effort
4.1	Bundle tree-sitter-python WASM (476KB) + define extraction queries	Small
4.2	Implement PythonScanner (functions, classes, methods, imports, decorators, type hints, docstrings, __all__, callees)	Medium
4.3	Add Python-specific pattern rules for dev_patterns (try/except, imports, type coverage)	Small
4.4	Test fixtures (FastAPI, pytest, dataclass, __init__.py), integration tests, docs	Medium

Key decisions

• tree-sitter WASM (not Python subprocess) — 476KB, already available
• No cross-file import resolution — name-based callees only (matches TS scanner)
• __all__ overrides _ convention for export detection
• isTestFile() refactored to language-aware pattern map
• QUERIES_BY_LANGUAGE map instead of if/else branching
• Document output parity test to prevent second-class results

Research

• Studied GitHub's stack-graphs Python tree-sitter rules (3.4k stars) — validated our node type choices
• Studied Griffe (mkdocstrings) object model — labels system inspiration
• Studied scip-python (Sourcegraph) — symbol naming conventions
• Confirmed async def is not a separate node type in tree-sitter-python

Reviews completed

1. Python expert review — found 3 blockers (WasmPatternMatcher language gate, isTestFile, integration test), all addressed
2. Senior engineer review — found 5 items (parity test, query map, isTestFile refactor, query validation, callee depth), all addressed

Generated with Claude Code