feat(context): AST symbol extraction and structural codebase outline for repository context engine

[Kaap10]

Problem Statement

Currently, RepositoryContextEngine performs plain-text BM25 ranking across repository files and injects whole file text snippets into the LLM system prompt. For repositories with large modules, this consumes a substantial portion of the 128k token budget on imports and boilerplates, while missing architectural relationships (which class inherits from which, which functions are exported).

Proposed Architecture & Solution

1. Symbol Extractor Module (src/terminal_agent/context/symbols.py):
   • Parse Python files using standard library ast.parse into structured symbols:
     • Classes with docstrings and method signatures.
     • Standalone functions with parameter types and return type annotations.
     • Exported module constants.
2. Compact Repository Skeleton Index:
   • Generate an outline:

     src/auth/service.py:
       class AuthService:
         def login(self, username: str, password: str) -> AuthToken
         def refresh_token(self, token: str) -> bool
     

3. Context Injection:
   • Embed the compact symbol outline in the initial context prompt. The agent can then use read_file with precise line ranges instead of loading oversized files.

Files to Modify / Create

• src/terminal_agent/context/symbols.py (New)
• src/terminal_agent/context/engine.py
• tests/unit/test_context.py

Acceptance Criteria

• AST parser extracts top-level functions, classes, and methods without executing any code.
• Symbol generation completes under 200ms for repositories with up to 1,000 files.
• Context engine prompt size reduced by over 40% while preserving symbol visibility.
• Syntax error handling in unparsable or non-Python files fails gracefully without crashing the context engine.