Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate / Specs / 009-volk-context-injection

009-volk-context-injection: Volk Context Injection

The Volk Context Injection system queries the knowledge graph to inject relevant nodes into Volk (AI agent) context at runtime, enabling context-aware task execution without disk reads.

At a glance

Item Value
Spec directory specs/009-volk-context-injection/
Status line in the spec Complete — superseded by SPEC-106/107 context-injection consolidation
Requirement IDs defined 34
With a @traces citation in src/ 0 (0.0%)
With a @traces citation in tests/ 0 (0.0%)
Tracked files 9
RTM page 009-volk-context-injection

Reading this spec

Volk Context Injection queries the knowledge graph at runtime and injects the relevant nodes into a Volk's context, so that an agent receives specs and requirements for its task without reading from disk. The aims are to remove disk reads, give agents awareness of specifications and requirements, connect code to the specs that govern it, and reduce context window usage through targeted injection.

The scope is six user stories, one per task type: BUILD, REFACTOR and DEBUG injection (priority 1), and DOCUMENT, TEST and REVIEW injection (priority 2). Each story describes the context a Volk needs for that kind of task. Requirement IDs use the REQ-009-US-nnn form.

The design decisions are knowledge graph queries chosen by task type, a VolkContextInjector class that assembles the context, task-specific query patterns, and two output formats: a dict (JSON) and markdown.

No code module cites this spec's requirement IDs, so there is no list of tracing modules to link; the context-injection code is traced under the consolidating specs instead, because this spec's status line reads Complete and states that it is superseded by the SPEC-106 and SPEC-107 context-injection consolidation. The per-requirement view is on the RTM page. It tracks 9 files and defines 34 requirement IDs. The full text follows below.

No src/ symbol cites any of the 34 requirements, so measured trace coverage is 0.0%. In tests/, 0 requirements are cited by a test-side @traces.

Coverage gaps: 34 requirements have no citing symbol. The largest untraced groups are REQ-009-US-001 (10), REQ-009-US-002 (7), REQ-009-US-006 (5). Untraced means no @traces names the ID; 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.

ID Done Requirement Traced by
REQ-009-US-001-001 no For BUILD tasks, context SHALL include all Spec nodes matching the requested spec IDs none
REQ-009-US-001-002 no For BUILD tasks, context SHALL include all Requirement nodes traced to those specs via the :TRACES relationship none
REQ-009-US-001-003 no For BUILD tasks, context SHALL include all Document nodes of type "standard" none
REQ-009-US-001-004 no BUILD context injection SHALL complete in under 100ms none
REQ-009-US-002-001 no For REFACTOR tasks, context SHALL include the File node for the target file none
REQ-009-US-002-002 no For REFACTOR tasks, context SHALL include all Class nodes defined in the file via the :DEFINES relationship none
REQ-009-US-002-003 no For REFACTOR tasks, context SHALL include all Function nodes defined in the file none
REQ-009-US-002-004 no For REFACTOR tasks, context SHALL include all Method nodes defined in those classes none
REQ-009-US-002-005 no For REFACTOR tasks, context SHALL include all Import nodes from the file via the :IMPORTS relationship none
REQ-009-US-002-006 no For REFACTOR tasks, context SHALL include all CALLS relationships from functions in the file none
REQ-009-US-002-007 no REFACTOR context injection SHALL complete in under 100ms none
REQ-009-US-003-001 no For DEBUG tasks, context SHALL include the File node for the target file none
REQ-009-US-003-002 no For DEBUG tasks, context SHALL include all Test nodes linked to the file via the :TESTS relationship none
REQ-009-US-003-003 no For DEBUG tasks, context SHALL include the error message from task_params none
REQ-009-US-003-004 no DEBUG context injection SHALL complete in under 100ms none
REQ-009-US-004-001 no For DOCUMENT tasks, context SHALL include File or Package nodes none
REQ-009-US-004-002 no For DOCUMENT tasks, context SHALL include Class nodes with their existing docstrings none
REQ-009-US-004-003 no For DOCUMENT tasks, context SHALL include Function nodes with their existing docstrings none
REQ-009-US-004-004 no DOCUMENT context injection SHALL complete in under 100ms none
REQ-009-US-005-001 no For TEST tasks, context SHALL include the File node to be tested none
REQ-009-US-005-002 no For TEST tasks, context SHALL include all Class and Function nodes in that file none
REQ-009-US-005-003 no For TEST tasks, context SHALL include all Requirement nodes traced to that code via the :TRACES_TO relationship none
REQ-009-US-005-004 no TEST context injection SHALL complete in under 100ms none
REQ-009-US-006-001 no For REVIEW tasks, context SHALL include the File node with metrics (line_count, complexity) none
REQ-009-US-006-002 no For REVIEW tasks, context SHALL include Class nodes with method counts none
REQ-009-US-006-003 no For REVIEW tasks, context SHALL include Function nodes with complexity scores none
REQ-009-US-006-004 no For REVIEW tasks, context SHALL include a StyleGuide node (Google Python Style rules) none
REQ-009-US-006-005 no REVIEW context injection SHALL complete in under 100ms none
REQ-009-US-001-005 - DEBUG Context none
REQ-009-US-001-006 - DOCUMENT Context none
REQ-009-US-001-007 - TEST Context none
REQ-009-US-001-008 - REVIEW Context none
REQ-009-US-001-009 - Context Output Formats none
REQ-009-US-001-010 - Performance none

Code that traces this spec

No src/ symbol cites a requirement of this spec.

Checklists

checklists/architecture_review.md

Architecture Review Checklists

This document contains architecture review checklists for evaluating the Orchestrata system design.

Checklist 1: Data Platform Review
Storage Architecture
Knowledge Graph Schema
Performance Targets
Caching Strategy
Checklist 2: System Interaction Review
Component Communication
Component Interactions
Dependency Injection
Multi-Agent Coordination
Session Management
Integration Points
Security & Governance
Review Scoring

Rate each item:

Current Score
Section Score
Data Platform 100% ✅
System Interaction 100% ✅
Architecture Review 100% ✅
Score Interpretation
Score Rating
90-100% Excellent
70-89% Good
50-69% Needs Work
<50% Critical Gaps
Notes

Record findings and action items here:

Data Platform Findings
System Interaction Findings
Action Items
  1. [x] Implement gRPC support for CXP
  2. [x] Implement WebSocket support
  3. [x] Add Kubernetes deployment manifests
  4. [x] Complete SPEC-009 architecture documentation
  5. [x] Research Erwin integration alternatives
Architecture Review Completion

checklists/architecture_review_completed.md

Architecture Review Checklists - SPEC-009 Completed

This document contains the completed architecture review for SPEC-009: Volk Context Injection.

Checklist 1: Data Platform Review
Storage Architecture
Knowledge Graph Schema
Performance Targets
Caching Strategy
Checklist 2: System Interaction Review
Component Communication
Component Interactions
Dependency Injection
Multi-Agent Coordination
Session Management
Integration Points
Security & Governance
SPEC-009 Specific Review
Context Injection Architecture
Data Flow Validation
Review Scoring

Rate each item:

Current Score
Section Score
Data Platform 100% ✅
System Interaction 95% ✅
SPEC-009 Specific 100% ✅
Score Interpretation
Score Rating
90-100% Excellent
70-89% Good
50-69% Needs Work
<50% Critical Gaps
Notes
Data Platform Findings
System Interaction Findings
Action Items
  1. [ ] Implement gRPC support for CXP
  2. [ ] Implement WebSocket support
  3. [ ] Add Kubernetes deployment manifests
  4. [x] Complete SPEC-009 architecture review ✅
  5. [x] Document data flow diagram ✅
  6. [x] Research Erwin integration alternatives ✅
SPEC-009 Architecture Review Status: COMPLETE ✅

checklists/requirements.md

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

Other tracked files

Full spec text

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

SPEC-009: Volk Context Injection

Metadata

Consolidation note (2026-07-13)

The task-type handlers and VolkContext shape originally specified here were merged into knowledge_graph/context_injector.py::ContextInjector.inject_for_task and are now consumed through context/assembler.py::UnifiedContextAssembler in the production runner (kernel/pipeline_kg.py and orchestrator/pipeline_runner.py). The standalone VolkContextInjector implementation is superseded.

Overview

What

The Volk Context Injection system queries the knowledge graph to inject relevant nodes into Volk (AI agent) context at runtime, enabling context-aware task execution without disk reads.

Why
How

User Scenarios & Stories

US-001: BUILD Context Injection (P1)

As a VizInt volk I want to receive specs and requirements for BUILD tasks So that I can implement features correctly

Acceptance Criteria:

US-002: REFACTOR Context Injection (P1)

As a VizInt volk I want to receive AST subtree for REFACTOR tasks So that I understand the code structure

Acceptance Criteria:

US-003: DEBUG Context Injection (P1)

As a QA volk I want to receive test context for DEBUG tasks So that I can diagnose issues

Acceptance Criteria:

US-004: DOCUMENT Context Injection (P2)

As a VizInt volk I want to receive documentation context So that I can generate docs

Acceptance Criteria:

US-005: TEST Context Injection (P2)

As a QA volk I want to receive code and requirements for TEST tasks So that I can write appropriate tests

Acceptance Criteria:

US-006: REVIEW Context Injection (P2)

As a QA volk I want to receive code metrics for REVIEW tasks So that I can assess code quality

Acceptance Criteria:

Functional Requirements

Context Injector Service

FR-001: VolkContextInjector Class (P0)

FR-002: Task Type Support (P0)

Task-Specific Context Requirements

FR-003: BUILD Context Requirements (P0)

FR-004: REFACTOR Context Requirements (P0)

FR-005: DEBUG Context Requirements (P1)

FR-006: DOCUMENT Context Requirements (P1)

FR-007: TEST Context Requirements (P1)

FR-008: REVIEW Context Requirements (P1)

Context Output Formats

FR-009: Dictionary Output (P0)

FR-010: Markdown Output (P0)

Non-Functional Requirements

Performance

NFR-001: Context Injection Performance

Reliability

NFR-002: Error Handling

Extensibility

NFR-003: Task Type Extensibility

Technical Design

Architecture
┌─────────────┐     ┌──────────────────────┐     ┌─────────────┐
│  Volk Spawn │────▶│  Context Injector    │────▶│  Injected   │
│  Task       │     │  (VolkContextInjector)│    │  Context    │
└─────────────┘     └──────────────────────┘     └─────────────┘
                           │
                           ▼
                    ┌───────────────┐
                    │  Neo4j KG    │
                    │  - Specs     │
                    │  - Reqs      │
                    │  - AST       │
                    │  - Tests     │
                    └───────────────┘
Class Design
class VolkContextInjector:
    def __init__(self, neo4j_client: Neo4jClient):
        self.neo4j = neo4j_client
    
    async def inject_for_task(
        self,
        volk_alias: str,
        task_type: TaskType,
        task_params: Dict[str, Any]
    ) -> VolkContext:
        """Inject context based on task type."""
        query = self._get_query_for_task(task_type)
        nodes = await self.neo4j.query(query, task_params)
        return VolkContext(nodes=nodes, task_type=task_type)

class VolkContext:
    def __init__(self, nodes: List[Node], task_type: TaskType):
        self.nodes = nodes
        self.task_type = task_type
        self.files = self._extract_files()
        self.specs = self._extract_specs()
        self.requirements = self._extract_requirements()
    
    def to_dict(self) -> Dict[str, Any]:
        """Return JSON-serializable dict."""
        return {
            "task_type": self.task_type.value,
            "files": self.files,
            "specs": self.specs,
            "requirements": self.requirements,
            "nodes": [node.to_dict() for node in self.nodes],
            "metadata": {
                "node_count": len(self.nodes),
                "timestamp": datetime.now().isoformat()
            }
        }
    
    def to_markdown(self) -> str:
        """Return human-readable markdown."""
        ...

class TaskType(Enum):
    BUILD = "build"
    REFACTOR = "refactor"
    DEBUG = "debug"
    DOCUMENT = "document"
    TEST = "test"
    REVIEW = "review"
Query Patterns

BUILD Query:

MATCH (s:Spec) WHERE s.id IN $spec_ids
MATCH (s)-[:TRACES]->(r:Requirement)
MATCH (d:Document {type: "standard"})
RETURN s, r, d

REFACTOR Query:

MATCH (f:File {path: $file_path})
OPTIONAL MATCH (f)-[:DEFINES]->(c:Class)
OPTIONAL MATCH (f)-[:DEFINES]->(fn:Function)
OPTIONAL MATCH (c)-[:DEFINES]->(m:Method)
OPTIONAL MATCH (f)-[:IMPORTS]->(i:Import)
OPTIONAL MATCH (fn)-[:CALLS]->(called:Function)
RETURN f, c, fn, m, i, called
Graph Relationships
(Spec)-[:TRACES]->(Requirement)
(Requirement)-[:VALIDATES]->(Spec)
(File)-[:DEFINES]->(Class)
(File)-[:DEFINES]->(Function)
(Class)-[:DEFINES]->(Method)
(File)-[:IMPORTS]->(Import)
(Function)-[:CALLS]->(Function)
(File)-[:TESTS]->(Test)
(Requirement)-[:TRACES_TO]->(File)
(Class)-[:HAS_DOCS]->(Document)
(File)-[:BELONGS_TO]->(Package)

Integration Points

Component Integration
orchestrata-agents Called during IVolkRuntime.spawn() or task assignment
orchestrata-knowledge Uses existing Neo4jClient and schema from Spec-008
orchestrata-cxp Context passed to Volk's execute method via CXP packets

Success Criteria

  1. ✅ Functional: VolkContextInjector class exists and is importable
  2. ✅ Coverage: All 6 task types return appropriate nodes
  3. ✅ Format: to_dict() produces valid JSON
  4. ✅ Format: to_markdown() produces readable output
  5. ✅ Performance: Context injection completes in <100ms
  6. ✅ Compatibility: Works with existing Neo4j schema from Spec-008
  7. ✅ Integration: Integration with orchestrata-agents documented
  8. ✅ Architecture Review: Completed using checklist in checklists/architecture_review.md
  9. ✅ Data Flow Diagram: Created in draw.io format documenting component flows
  10. ✅ Alternative Research: Erwin integration researched and documented

Dependencies

Open Questions

  1. Should context be cached in Redis for repeated tasks?
  2. Should we support custom graph queries per Volk type?
  3. How to handle very large files in REFACTOR context?
  4. Should we include git history in context?

Alternative Knowledge Graph Storage Research

Erwin (erwin.easydb.de) Evaluation

Research Findings:

Conclusion:

Recommendation:

Revision History

Date Version Author Changes
2026-03-05 1.0 Mohamed Initial specification
2026-03-07 1.1 Mohamed Standardized format, added numbered requirements