Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Plans › context-injection-ast-analysis

Context Injection: AST / Graph / Context Use — Analysis + Plan

Source: plans/context-injection-ast-analysis.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-14 · 77 lines.

Prose pending.

Plan text

Context Injection: AST / Graph / Context Use — Analysis + Plan

Audit date

2026-07-14

What already works (verified by existing tests)

The unified context assembler (context/assembler.py) already pulls from multiple sources and renders each into a dedicated context part:

Part Provider Status Wired?
mission mission_context.py Renders ContextData goal/handoff/pending work Yes — PipelineKGMixin._session_context_data() feeds it
plan plan_context.py Renders current/recent/upcoming GoalTasks Yes
memory memory_context.py summarize_for_thread_sync + recall_sync per thread_id Yes
artifacts artifact_digest.py Prior-stage artifact digest Yes
graph ContextInjector KG code-structure + task-type pack Yes
ast ast_context.py Complexity hotspots, branch points, missing @traces, call-graph neighborhood Yes, but only integration-tested through assembler
semantic semantic_context.py Memgraph chunk search mapped to Neo4j File roots Yes, with degradation when Memgraph/Neo4j unreachable

Gaps found

  1. No direct unit tests for ast_context.py. Coverage relies on a single assembler integration test (test_assemble_includes_ast_context_for_target_files). Degradation paths (toolkit missing, no parseable sources, empty results) are untested.

  2. AST signals are shallow. The provider reports complexity, branches, untraced symbols, and reference counts, but does not show the volk the actual public API surface (class/function signatures) of the files it is about to edit. That signal is left to the KG injector, which may not have synced the file yet.

  3. No telemetry on token spend. ContextUsage tracks per-layer tokens but the assembler never logs them, so there is no runtime visibility into which layer is consuming the context budget (context-injection-roadmap.md #4).

  4. Memory recall has no token cap. recall_sync(thread_id, user_message, limit=3) bounds count, not tokens; long memories can still blow the budget (context-injection-roadmap.md #2).

  5. ast_context.py dynamically loads scripts/serialize_codebase_ast.py on every call. The load cost is paid per volk invocation. A module-level cache would avoid repeated import/exec.

  1. Direct tests + hardening for ast_context.py

    • Add tests/context/providers/test_ast_context.py.
    • Cover: toolkit unavailable, no target files, empty results, real complexity / branches / untraced / call-graph signals.
    • Add a module-level _ast_tool cache so the toolkit is loaded once per process.

  2. Enrich AST signals with public API signatures

    • Extend render_ast_context to list top-level public classes/functions with their list_symbols signatures (capped to a few lines).
    • Keep the existing complexity/branch/untraced/call-graph signals.

  3. Add usage telemetry to context_assembler.py

    • After assembly, log per-layer token counts at DEBUG (or INFO when a layer exceeds 50% of its budget).
    • Include total spent vs total budget.

  4. Cap memory recall by tokens

    • Pass max_tokens to recall_sync (add the parameter if missing) and trim results so memory cannot exceed its budget layer.

  5. Future (Phase 1 of roadmap)

    • Inject semantic-graph context by default (already implemented; verify it populates when Memgraph is available).
    • Prolog relevance boost for DEBUG tasks.
    • Project-scoped queries and incremental KG sync.

Scope for this wave

Implement steps 1–4. Each is small, testable, and low-risk; none changes the public assemble() contract.