Orchestrata Ultimate / Specs / 107-context-injection-improvements

107-context-injection-improvements: Context-Injection Improvements

The existing context assembler (src/orchestrata_ultimate/context/assembler.py) has the right layered shape, but several layers are either empty in production or under-used:

At a glance

Reading this spec

This spec improves how context reaches agents through the existing layered context assembler. The assembler has the right shape, but several layers are empty or under-used in production: session and goal context is implemented but never fed because production callers pass no context data, the plan layer is budgeted but never populated, memory recall loads an unbounded number of entries and scores them in Python, the semantic graph and the serialized AST are rich sources that are not injected automatically, context use per layer is not logged so tuning is blind, and the artifact store is in-memory only with no digest pagination.

Four ruling constraints apply. Selection is never LLM-driven; ranking and filtering stay deterministic, matching SPEC-106 FR-003. The UnifiedContextAssembler.assemble() signature is unchanged, and new layers are optional parts. Every new source has a no-op fallback when its backend (Neo4j, Memgraph, Redis or Prolog) is unavailable. Tests use real backends, without mocks, on production context paths.

The fourteen functional requirements (FR-001 to FR-014) are: session and plan context, bounded memory recall (for example a max_age_seconds pre-filter before similarity scoring), a semantic-graph context layer, an AST-derived context layer (a budgeted summary of the most relevant complex or called symbols), context telemetry, an artifact store refactor (digests ranked by recency and relevance, top-N within budget), on-demand context tools, context pack caching, expanded graph-context sections (requirements and decisions found through TRACES_TO and APPLIES_TO), runtime signal ingestion, a validator feedback loop, and snapshot and knowledge-base freshness (the ast-sync step runs incrementally, cutting a no-change run from 60.7 s to 8.3 s). The last two requirements concern delivery: claude/ in the repository is the source of truth and ~/.claude is a deployment of it, the deployed virtual environment is verified free-threaded with no reference to the source checkout, and shipping is mechanical. The 73 requirement IDs are numbered REQ-107-NNN.

The code touches many places, so each module holds only a few citations: context tools (6 requirements), the AST context, plan context and semantic context providers, the usage log, the artifact store and the context injector. The requirements traceability matrix lists each ID. The spec states no status line and tracks 2 files. Measured coverage is 13 of 73 requirements cited by at least one @traces in src/ (17.8%), spread over 9 modules; the module citing the most of them is orchestrata_ultimate/tools/context_tools (6 requirements). In tests/, 1 requirement is cited by a test-side @traces. 60 requirements have no citing symbol; the behaviour may still exist in code that was never annotated.

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

Checklists

checklists/requirements.md

The requirement list above comes from this file; 73 of 73 checkbox items are ticked.

Full spec text

Verbatim from specs/107-context-injection-improvements/spec.md; headings are pushed down two levels.

SPEC-107: Context-Injection Improvements

Version: 0.4.0 (draft)
Date: 2026-07-14
Status: Draft — Phase 2 context layers landed (semantic, AST, recent changes, similar patterns, requirement closure, runtime signals, validator loop); FR-012 snapshot/KB freshness added 2026-08-13; FR-013 (the machinery is a deployed artifact) and FR-014 (shipping is mechanical) added 2026-08-14
Depends on: SPEC-008 (knowledge graph), SPEC-009 (volk context injection), SPEC-106 (context semantic layer)

Problem

The existing context assembler (src/orchestrata_ultimate/context/assembler.py) has the right layered shape, but several layers are either empty in production or under-used:

• Session/goal context is implemented (mission_context.render_mission_context) but never fed because production callers pass context_data=None.
• The plan layer is budgeted but never populated.
• Memory recall loads an unbounded number of entries and scores them in Python.
• The semantic graph (src/orchestrata_ultimate/semantic_graph/) and the serialized AST (plans/ast-ultimate.json) are rich data sources that are not automatically injected.
• Context usage per layer is not logged, so optimization is blind.
• The artifact store is in-memory only and does not paginate digests.

Ruling constraints

1. No LLM-driven selection. All context ranking and filtering remains deterministic, matching SPEC-106 FR-003.
2. Backward-compatible assembler contract. UnifiedContextAssembler.assemble() keeps the same signature; new layers are optional parts.
3. Degrade, don't crash. Every new source must have a no-op fallback when its backend (Neo4j, Memgraph, Redis, Prolog) is unavailable.
4. Observed tests only. No mocks for production context paths; tests use real MemoryEngine/Neo4j/Memgraph where applicable.

FR-001: Session and plan context

• PipelineRunner and gateway paths must load ContextData from the active SessionController and pass it to the assembler.
• mission_context.render_mission_context becomes the mission layer.
• A new plan_context provider renders recent pipeline outcomes and next planned stages into the existing plan budget.
• A PlanParser reads the active plan markdown (e.g. plans/execution-plan.md) into structured steps.
• Goal persists a current_step index; the session controller exposes advance_goal_step and set_goal_step.
• plan_context renders the current step in full, the next two step titles, and summaries of the last three completed steps.

FR-002: Bounded memory recall

• MemoryEngine.search / RedisMemoryStore.retrieve_by_scope must accept and enforce a max_entries and/or max_age_seconds pre-filter before similarity scoring.
• Defaults are chosen to keep recall latency under 100ms and memory layer under its token budget.

FR-003: Semantic-graph context layer

• A SemanticGraphContextProvider queries the Memgraph semantic graph for chunks relevant to the user message.
• It contributes a semantic part to ContextAssembly when the subject is implement, fix_issues, or review_and_test.
• Falls back to empty if Memgraph is unavailable.

FR-004: AST-derived context layer

• AST complexity, branch, and typed call-graph signals from plans/ast-ultimate.json must be queryable from Neo4j or directly from the AST snapshot.
• An ast_context part (<=500 tokens) highlights the most complex or most-called symbols related to the task entities.

FR-005: Context telemetry

• Every assemble() call logs ContextUsage.to_dict() at INFO.
• A new scripts/context_usage_report.py aggregates per-layer spend over a session.

FR-006: Artifact store refactor

• ArtifactStore persists each artifact to a timestamped JSONL file under a configurable output_dir.
• On construction it replays the JSONL into the in-memory index.
• render_artifact_digest ranks artifacts by recency and relevance and renders only the top-N within budget.
• Artifacts carry spec/reqs fields and can be retrieved by requirement id.

FR-007: On-demand context tools

• get_code(entity_id) returns the stored content or signature for a canonical code entity (File/Class/Function/Method) from the knowledge graph.
• get_tests(entity_id) returns the tests that cover a canonical code entity.
• get_requirements(entity_id) returns the RequirementItem/Requirement chain traced by a canonical code entity.
• search_code(query, target_files) returns a semantic-search context block by querying the Memgraph semantic graph and mapping chunk file paths back to Neo4j File root entities.
• All four tools degrade gracefully when Neo4j or Memgraph is unavailable, returning a clear "unavailable" result rather than raising.
• Tools are registered as SPEC-062 native tools and exposed to the volks that need them (Architect, CodeDirector, QA, Documentor).

FR-008: Context pack caching

• UnifiedContextAssembler caches ContextPack.render() output by (snapshot_id, volk_alias, subject) for the lifetime of a pipeline run, avoiding redundant KG queries.
• The cache key includes the graph snapshot/version so that a new sync invalidates prior packs.

FR-009: Expanded graph-context sections

• GraphContext populates recent_changes from explicit Change nodes, NEXT_VERSION chains, or file timestamp properties.
• GraphContext populates similar_patterns with files whose classes share base classes or protocols with target files.
• GraphContext populates semantic_files via the Memgraph semantic-search bridge.
• GraphContext populates requirements and decisions by traversing TRACES_TO and APPLIES_TO relationships, including REQUIRES closure up to a bounded depth.

FR-010: Tier-H runtime signal ingestion

• Runtime signals (Message, ToolCall, Decision, GatewayEvent) are persisted to Neo4j with deterministic ids.
• Signals link to mentioned File/Class/Function nodes via MENTIONS edges.
• Kernel pipeline dispatch, orchestrator runner, and BaseAgent wire the shared RuntimeSignalWriter.

FR-011: Validator feedback loop

• GraphContextValidator validates LLM responses against core entities cited in graph_context.
• ValidatorLoop retries LLM calls with expanded context when validation reports missing citations.
• ContextExpansion controls extra_hops, include_tested_by, include_requirement_closure, and limit_multiplier.

FR-012: Snapshot and KB freshness

The AST snapshot (plans/ast-ultimate.json) is the input every deterministic context layer is derived from: the Prolog code-intelligence KB is rebuilt from it, FR-004's AST layer reads it, and the gate fact base is extracted from it. A stale snapshot therefore does not weaken those layers, it makes them confidently wrong — the consumer has no way to tell an answer about deleted code from a current one.

• ast-sync MUST pass --incremental to the serializer, warm-starting from the snapshot already on disk and re-parsing only files whose content changed. The serializer guarantees byte-identical output either way, so this is a cost change, not a result change. (Measured 2026-08-13, no-change run: 60.7s → 8.3s; 2819 modules before and after, none gained or lost.)
• ast-sync --snapshot-only MUST run steps 1/1b and stop, skipping the frozen monorepo serialization and the deep comparison. This is the only stage a freshness refresh needs. (Measured: worth ~6s of the above, i.e. the smaller saving — step 1 was the cost.)
• main() MUST parse the argv it is given. argv=None reads sys.argv, so an in-process caller inherits the hosting process's command line; under pytest that aborts the pipeline with SystemExit(2).
• Freshness MUST be evaluated at the point of USE and scoped to the files a task touches. A whole-tree check costs more than it is worth, and an unrelated module's edit cannot invalidate an injection about this one.
• A consumer that cannot reach the KB MUST distinguish "queried, and the answer is nothing" from "could not query". Collapsing them sends the reader hunting for a broken tool when the tool answered correctly.
• Blast radius MUST resolve its impact targets from the module's parsed AST, not from module-api. module-api reports __all__, which only 136 of 2816 modules (4.8%) declare, so KB-sourced resolution returned an empty symbol list — reported as "module not in the KB" — for ~95% of the tree.
• Any bound on the answer (impact fan-out, parse caps, project scoping) MUST be stated in the output. An unstated bound reads as a complete answer.
• A bound that exists only to pay for a per-call cost MUST be removed once that cost is amortised, not merely disclosed. Blast radius capped fan-out at six symbols per module because each impact query was a separate 7.4s process start; measured across orchestrata + knowledge-wiki, that cap left 456 of 2485 symbols (18%) unqueried, concentrated in the 87 of 757 modules (11%) with more than six public symbols — the large modules whose blast radius matters most. code_intel.py impact now accepts many qnames in one invocation, so the cost is the process start (7.4s) and not the query (0.02s): a whole module now costs what one symbol used to (3 symbols in 7.15s, against 22.2s before). The cap is gone rather than documented.

FR-013: The injection machinery is a deployed artifact, not a home directory

Every layer above is delivered by hooks, tools and skills that Claude Code loads from ~/.claude. Until 2026-08-14 that directory was the only copy: unversioned, un-reviewed, and un-restorable, which made the injection layer the least governed code in the project while being the code that runs on every prompt.

• The source of truth MUST be claude/ in this repo, and ~/.claude MUST be a deployment of it. The dev folder is where hooks, tools, agents, skills and commands are edited; nothing is authored in the deployed tree.
• The deployment MUST copy. No symlink from ~/.claude into a checkout — that is deploy-in-place wearing a disguise: the running config silently follows an uncommitted edit, a rebase, or a branch switch.
• The deployment MUST own a venv, created with uv on python3.14t, and ~/.claude/.envrc MUST auto-activate it under direnv. The hooks previously ran under /usr/bin/python3 with the GIL enabled — platform convention 1 violated in the one place that executes on every single prompt.
• direnv is NOT what makes the hooks correct, and the spec MUST NOT be read as saying so. Claude Code spawns hooks from the project's cwd, so nothing direnv does reaches them; the installer additionally rewrites settings.json hook commands to the venv's absolute interpreter. Both are required; neither substitutes for the other.
• The installer MUST record the source commit and then REFUSE success unless every deployed file is byte-identical to that commit's blob. Two ways this check silently lied and were fixed: piping git cat-file into head under pipefail killed the comparison with SIGPIPE (exit 141) and reported nothing, which reads as a pass; and $(...) stripping trailing newlines flagged two byte-identical templates as drift.
• The installer MUST NOT infer what to deploy from filename heuristics. An --exclude='test_*.py' rule intended to skip test fixtures deleted eight live files, including the registered hook test_isolation_hook.py. Excludes are enumerated, never pattern-guessed.
• A verification that matches zero files MUST fail. CHECKED -gt 0 is asserted explicitly, because a drift check whose glob matches nothing otherwise passes loudest of all.

FR-014: Shipping is mechanical

Context injection that exists only as a local commit changes nothing: worktrees branch off origin/master, so an unpushed commit leaves the next delegated task building on a base that does not contain it. This is the drift that left the claude/ dev folder 8831 lines behind the live config.

• ship MUST run verify → push → deploy → verify-the-deployment in one sequence, and MUST be reachable by name on PATH. An installer that reports OK for a command command -v cannot find has verified the wrong thing.
• Each project MUST state its own gate in ship. A gate inferred from a file listing is how a green "verification" gets reported for a suite that never ran; an unknown project fails rather than shipping unverified.
• The dirty-tree check MUST exclude paths the tooling itself rewrites, and that exclusion MUST be narrow. a live-data refresher refreshes four wiki live-data pages every 30 minutes with only a date: and _Refreshed_ change, which made ship fail on a 30-minute cycle; the sibling hand-written pages in the same directory still block, because their changes are real.
• A Stop hook MUST refuse to end a turn while a watched repo holds commits that exist only locally, and MUST stay quiet while a ship for that repo is already running. It detects the in-flight ship by whole-argv-element equality against the resolved executable: the first attempt used pgrep -f "bin/ship", which substring-matches the entire command line and therefore matched the wait-loop polling for ship and the debug command inspecting it — returning true unconditionally and silently disabling the guard permanently.
• Detection MUST be by process, not lockfile. A lockfile outlives a SIGKILL and would then suppress the guard forever, failing in the direction that hides unshipped work — the exact failure the hook exists to prevent.
• --no-verify MUST state what it actually skips. It skips this script's gate and is never passed to git, so a repo with a pre-push hook still runs it; announcing "gate skipped" and then sitting in a ten-minute suite reads as a hang.

Related

• RTM page for 107-context-injection-improvements
• All specs
• RTM overview
• Gates