ADR-154: Context Graph Query DSL and Agent Workflow Context Management

Status

ACCEPTED (2026-02-03)

Executive Summary

This ADR defines the architecture for querying the context graph (ADR-151) and managing workflow context for long-running agentic systems. It builds on the Query Language Evolution Strategy (ADR-149) to provide:

1. Query Templates - YAML-defined reusable queries for common agentic patterns
2. Agent Context Injection - Automatic context graph hydration per agent turn
3. Workflow State Management - Cross-session context continuity for long-running tasks
4. Decision Surface Queries - "What CAN I do?" not just "What do I know?"

Key Question Answered: Do we need a full DSL?

Answer: Not yet. Phase 2 Query Templates (ADR-149) with agent-specific extensions provide sufficient capability for current agentic workflows. A full DSL (Phase 3) should be deferred until template usage patterns reveal actual gaps.

Context

Problem Statement

With ADR-151's knowledge graph (16,932 nodes, 7,118 edges) and context graph builder in place, agents need a way to:

Need	Current Gap
Find relevant prior decisions	Must manually call /cxq --decisions
Discover similar past errors	No automatic error pattern matching
Load workflow state	No cross-session state persistence
Query decision surfaces	No "what actions are allowed?" queries
Chain context queries	Each query is isolated

Current Capabilities (ADR-149 Phase 1 - DONE)

The /cxq command now supports context graph flags and enhanced query syntax:

Context Graph Flags (J.4.6):

/cxq --graph "task description"      # Build context subgraph
/cxq --graph-stats                   # Knowledge graph statistics
/cxq --graph-strategy semantic       # Seed strategy: semantic, policy_first, anchor
/cxq --graph-budget 8000             # Token budget for context
/cxq --graph-depth 3                 # BFS expansion depth
/cxq --graph-format json             # Output format
/cxq --graph-entities decision,error # Filter entity types

Query Enhancement Flags (J.4.7.1-J.4.7.2):

# WHERE expressions (J.4.7.1)
/cxq --decisions --where "confidence > 0.8 AND decision_type = 'architecture'"
/cxq --tokens --where "cost_total_usd > 0.01 AND model_name LIKE 'claude%'"

# GROUP BY with time functions (J.4.7.2)
/cxq --tokens --group-by model_name,week     # Group by model and week
/cxq --tools --group-by tool_name            # Group by tool name

# ORDER BY with direction (J.4.7.2)
/cxq --tokens --sort cost_total_usd_desc     # Sort by cost descending
/cxq --tokens --group-by model_name --sort total_cost_desc  # Combined

Why NOT Build Full DSL Now

Argument	Counter
"DSL is more powerful"	Query templates provide 80% of value with 20% complexity
"Agents need SQL-like queries"	Agents work better with semantic queries + predefined templates
"Future-proofs the system"	YAGNI - build when usage patterns emerge
"Other systems have DSLs"	Those systems serve different use cases (data analysts vs agents)

Recommendation: Implement Phase 2 Query Templates with agent-specific extensions. Measure usage. Build DSL only if templates prove insufficient.

Decision

1. Query Template Architecture

Extend ADR-149's query template system with agent-aware capabilities:

# ~/.coditect-data/queries/agent-context-templates/
# security-audit-context.yaml

name: security-audit-context
version: 1.0.0
description: Load security-relevant context for audit workflows
author: coditect-team

# Template category for agent routing
category: agent-context
agent_types:
  - security-specialist
  - penetration-testing-agent
  - compliance-auditor

# Query definition
query:
  anchors:
    - type: track
      id: "D"  # Security track
    - type: recent_decisions
      filter: "decision_type IN ('security', 'auth', 'compliance')"
      limit: 20

  expansion:
    strategy: policy_first
    depth: 2
    edge_types:
      - GOVERNED_BY
      - REFERENCES
      - SIMILAR_TO

  filters:
    - "confidence > 0.7"
    - "created_at > datetime('now', '-30 days')"

  budget:
    max_nodes: 100
    max_tokens: 6000

# Output configuration
output:
  format: markdown
  sections:
    - name: Active Policies
      node_types: [Policy]
    - name: Recent Security Decisions
      node_types: [Decision]
    - name: Related ADRs
      node_types: [ADR]
    - name: Known Vulnerabilities
      node_types: [ErrorSolution]
      filter: "properties->>'category' = 'security'"

# Governance
governance:
  require_policies: [security-data-access]
  audit_usage: true

2. Agent Context Injection Protocol

Automatic context loading at agent turn boundaries:

┌─────────────────────────────────────────────────────────────────┐
│                   AGENT TURN LIFECYCLE                           │
└─────────────────────────────────────────────────────────────────┘

  User Message                    Agent Response
       │                               ▲
       ▼                               │
┌──────────────┐              ┌──────────────┐
│ 1. INTENT    │              │ 5. AUDIT     │
│    CLASSIFY  │              │    RECORD    │
└──────┬───────┘              └──────┬───────┘
       │                             │
       ▼                             │
┌──────────────┐              ┌──────────────┐
│ 2. SELECT    │              │ 4. EXECUTE   │
│    TEMPLATE  │              │    WITH      │
│              │              │    CONTEXT   │
└──────┬───────┘              └──────┴───────┘
       │                             ▲
       ▼                             │
┌──────────────────────────────────────────────┐
│ 3. BUILD CONTEXT GRAPH                        │
│                                               │
│    a. Load template anchors                   │
│    b. Query knowledge graph                   │
│    c. Apply governance filters                │
│    d. Prune to token budget                   │
│    e. Serialize to prompt format              │
└──────────────────────────────────────────────┘

Implementation:

# scripts/context_graph/agent_context_injector.py

class AgentContextInjector:
    """
    Injects relevant context into agent prompts based on:
    - Agent type (from agent registry)
    - Task intent (classified from user message)
    - Workflow state (if multi-turn)
    - Governance policies (from policy nodes)
    """

    def inject_context(
        self,
        agent_type: str,
        user_message: str,
        session_id: str,
        workflow_id: Optional[str] = None
    ) -> ContextInjection:
        """
        Build and inject context for an agent turn.

        Returns:
            ContextInjection with:
            - context_graph: KGSubgraph
            - prompt_section: str (formatted for injection)
            - metadata: dict (audit info)
        """
        # 1. Classify intent
        intent = self.classify_intent(user_message)

        # 2. Select template(s)
        templates = self.select_templates(agent_type, intent)

        # 3. Build context graph
        builder = CODITECTContextGraphBuilder()
        graph = builder.build_from_templates(templates)

        # 4. Add workflow state if multi-turn
        if workflow_id:
            workflow_context = self.get_workflow_state(workflow_id)
            graph = self.merge_graphs(graph, workflow_context)

        # 5. Serialize for prompt
        prompt_section = self.serialize_for_prompt(graph)

        return ContextInjection(
            context_graph=graph,
            prompt_section=prompt_section,
            metadata={
                "intent": intent,
                "templates_used": [t.name for t in templates],
                "node_count": len(graph.nodes),
                "token_estimate": self.estimate_tokens(prompt_section)
            }
        )

3. Workflow State Management

For long-running agentic workflows, persist context across sessions:

-- sessions.db: Workflow state tables

-- Workflow definitions
CREATE TABLE workflow_states (
    workflow_id TEXT PRIMARY KEY,
    workflow_type TEXT NOT NULL,        -- 'security-audit', 'refactor', etc.
    status TEXT DEFAULT 'active',       -- active, paused, completed, failed

    -- Context accumulation
    anchor_nodes TEXT,                  -- JSON: nodes to always include
    accumulated_decisions TEXT,         -- JSON: decisions made in this workflow
    accumulated_errors TEXT,            -- JSON: errors encountered

    -- State
    current_step TEXT,                  -- Current task ID (A.1.1 format)
    completed_steps TEXT,               -- JSON: completed task IDs

    -- Metadata
    started_at TEXT DEFAULT CURRENT_TIMESTAMP,
    updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
    session_ids TEXT,                   -- JSON: sessions in this workflow

    INDEX idx_workflow_status (status),
    INDEX idx_workflow_type (workflow_type)
);

-- Workflow context snapshots (for resumption)
CREATE TABLE workflow_context_snapshots (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    workflow_id TEXT NOT NULL,
    session_id TEXT NOT NULL,
    snapshot_type TEXT,                 -- 'checkpoint', 'error', 'decision'

    -- Context at snapshot time
    context_graph_json TEXT,            -- Serialized context graph
    active_policies TEXT,               -- Policies in effect

    created_at TEXT DEFAULT CURRENT_TIMESTAMP,

    FOREIGN KEY (workflow_id) REFERENCES workflow_states(workflow_id)
);

Workflow Context Commands:

# Start a workflow with context tracking
/workflow start security-audit --track D

# Resume workflow with accumulated context
/workflow resume <workflow_id>

# View workflow context
/workflow context <workflow_id>

# Export workflow state for handoff
/workflow export <workflow_id> --format cusf

4. Standard Query Templates for Agents

Pre-built templates for common agent workflows:

Template	Agent Types	Purpose
security-audit-context	security-specialist	Security decisions, policies, vulnerabilities
code-review-context	code-reviewer, orchestrator	Recent changes, patterns, related decisions
error-investigation-context	debug-specialist	Similar errors, solutions, affected components
architecture-context	senior-architect	ADRs, design decisions, component relationships
refactor-context	code-reviewer	Call graph, dependencies, test coverage
deployment-context	devops-engineer	Infrastructure decisions, deployment history
documentation-context	codi-documentation-writer	Related docs, component descriptions
test-context	testing-specialist	Test patterns, coverage gaps, flaky tests
compliance-context	compliance-auditor	Policies, audit events, regulatory decisions
workflow-resume-context	orchestrator	Workflow state, completed steps, pending tasks

5. Query Template Schema

# CODITECT Query Template Schema v1.0

$schema: "https://coditect.ai/schemas/query-template-v1.yaml"

# Required fields
name: string                    # Unique template identifier
version: string                 # Semantic version
description: string             # Human-readable description

# Optional metadata
author: string
category: enum[agent-context, analytics, audit, search]
agent_types: string[]           # Agent types this template serves

# Query definition
query:
  # Anchor nodes to start expansion from
  anchors:
    - type: enum[track, decision, error, component, session, file, policy]
      id: string                # Optional: specific ID
      filter: string            # Optional: WHERE clause
      limit: integer            # Optional: max anchors

  # Graph expansion configuration
  expansion:
    strategy: enum[anchor, semantic, policy_first, hybrid]
    depth: integer              # BFS depth (1-5)
    edge_types: string[]        # Edge types to traverse
    exclude_types: string[]     # Edge types to skip

  # Node filtering
  filters: string[]             # WHERE clauses for nodes

  # Budget constraints
  budget:
    max_nodes: integer          # Hard limit on nodes
    max_edges: integer          # Hard limit on edges
    max_tokens: integer         # Target token budget

# Output formatting
output:
  format: enum[markdown, json, text, prompt]
  sections:                     # Grouped output sections
    - name: string
      node_types: string[]
      filter: string            # Optional filter
      sort_by: string           # Optional sort
      limit: integer            # Optional limit

# Governance
governance:
  require_policies: string[]    # Policies that must be satisfied
  exclude_phi: boolean          # Filter PHI nodes
  audit_usage: boolean          # Log template usage

6. Integration with /cxq

Extend /cxq with template support (ADR-149 Phase 2):

# Execute a named template
/cxq --query security-audit-context

# List available templates
/cxq --queries
/cxq --queries --category agent-context

# Execute template with overrides
/cxq --query architecture-context --budget 8000 --depth 3

# Create template from current query
/cxq --graph "security decisions" --save-as my-security-query

# View template definition
/cxq --query-info security-audit-context

# Validate template against schema
/cxq --validate-query path/to/template.yaml

7. Agent Workflow Context API

MCP tools for agent context management:

# New MCP tools for coditect-context-graph server

@server.tool()
def get_agent_context(
    agent_type: str,
    task_description: str,
    workflow_id: Optional[str] = None,
    budget_tokens: int = 4000
) -> Dict[str, Any]:
    """
    Get context graph tailored for an agent type and task.

    Returns:
        - context_markdown: str (formatted for prompt injection)
        - nodes_included: int
        - tokens_estimated: int
        - templates_used: List[str]
    """
    ...

@server.tool()
def search_prior_decisions(
    query: str,
    decision_types: Optional[List[str]] = None,
    min_confidence: float = 0.7,
    since_days: int = 30,
    limit: int = 10
) -> Dict[str, Any]:
    """
    Search for relevant prior decisions to inform current work.

    Returns:
        - decisions: List[Decision]
        - related_adrs: List[ADR]
        - similar_patterns: List[Pattern]
    """
    ...

@server.tool()
def get_workflow_context(
    workflow_id: str,
    include_history: bool = True
) -> Dict[str, Any]:
    """
    Get accumulated context for a long-running workflow.

    Returns:
        - current_step: str
        - completed_steps: List[str]
        - accumulated_decisions: List[Decision]
        - context_graph: KGSubgraph
    """
    ...

@server.tool()
def record_workflow_decision(
    workflow_id: str,
    decision_type: str,
    decision: str,
    rationale: str,
    affected_nodes: List[str]
) -> Dict[str, Any]:
    """
    Record a decision made during a workflow for context accumulation.
    """
    ...

@server.tool()
def query_decision_surface(
    context: str,
    constraints: Optional[List[str]] = None
) -> Dict[str, Any]:
    """
    Query what actions are ALLOWED given current context and policies.

    Returns:
        - allowed_actions: List[Action]
        - blocked_actions: List[BlockedAction] with reasons
        - active_policies: List[Policy]
    """
    ...

Implementation

Phase 1: Query Template Infrastructure (J.4.8.1-J.4.8.3)

Task	Description	Estimate
J.4.8.1	Create query template YAML schema	4h
J.4.8.2	Implement query template registry in org.db	8h
J.4.8.3	Add --query, --queries flags to /cxq	4h

Phase 2: Standard Templates (J.4.8.4)

Task	Description	Estimate
J.4.8.4.1	Create 10 standard agent context templates	8h
J.4.8.4.2	Create 5 analytics templates	4h
J.4.8.4.3	Create 5 audit/compliance templates	4h

Phase 3: Agent Context Injection (J.4.9)

Task	Description	Estimate
J.4.9.1	Implement AgentContextInjector service	12h
J.4.9.2	Add intent classification for template selection	8h
J.4.9.3	Integrate with agent orchestrator	8h
J.4.9.4	Add context injection MCP tools	4h

Phase 4: Workflow State Management (J.4.10)

Task	Description	Estimate
J.4.10.1	Add workflow_states table to sessions.db	4h
J.4.10.2	Implement workflow context accumulation	8h
J.4.10.3	Add /workflow commands	8h
J.4.10.4	Implement workflow resume with context	8h

Total Estimated Effort

• Phase 1: 16h
• Phase 2: 16h
• Phase 3: 32h
• Phase 4: 28h
• Total: 92h (~12 days)

Decision Criteria for Full DSL (Phase 3 of ADR-149)

Trigger a full DSL implementation if ANY of these occur:

Metric	Threshold
Unique query templates	> 50 templates created
Template customization rate	> 40% of executions use overrides
Cross-table join requests	> 20% of queries need 3+ table joins
Graph traversal depth	> 30% need depth > 3
Natural language query failures	> 25% can't be mapped to templates

Measurement: Add telemetry to track template usage patterns.

Consequences

Positive

1. Immediate value - Templates provide structured queries without DSL learning curve
2. Agent-aware - Templates optimized for specific agent types
3. Workflow continuity - Long-running tasks maintain context across sessions
4. Governance-ready - Policies integrated into query execution
5. Measurable - Usage patterns inform future DSL decisions

Negative

1. Template proliferation - May end up with many similar templates
2. Indirect customization - Users must edit YAML vs writing queries
3. Two-step learning - Users learn templates then (maybe) DSL

Mitigations

• Template inheritance to reduce duplication
• Template composition (include other templates)
• Good defaults reduce need for customization
• Clear documentation on when to use what

Related

• ADR-149: Query Language Evolution Strategy (parent strategy)
• ADR-151: Context Graph Evolution Architecture (graph foundation)
• ADR-118: Four-Tier Database Architecture (storage layer)
• ADR-053: Cloud Context Sync (workflow state sync)
• ADR-136: CODITECT Experience Framework (agent context)

Appendix: Example Agent Context Flow

User: "Review the authentication code for security issues"

1. INTENT CLASSIFICATION
   → Intent: security-review
   → Agent: security-specialist
   → Track: D (Security)

2. TEMPLATE SELECTION
   → Primary: security-audit-context
   → Secondary: code-review-context

3. CONTEXT GRAPH BUILD
   Anchors:
   - track:D (Security track)
   - component:security-specialist
   - recent decisions (security, auth)

   Expansion (depth=2, policy_first):
   - 23 Policy nodes
   - 45 Decision nodes
   - 12 ADR nodes
   - 8 ErrorSolution nodes

   Pruned to 6000 tokens

4. PROMPT INJECTION

   ## Context: Security Audit

   ### Active Policies
   - no-hardcoded-secrets: Never commit secrets to code
   - auth-patterns: Use established auth patterns
   ...

   ### Recent Security Decisions
   - [2026-02-01] Adopted OAuth 2.0 for all API auth (ADR-089)
   - [2026-01-28] JWT validation must check expiry (Decision #234)
   ...

   ### Known Vulnerabilities
   - SQL injection in user input (solved: parameterized queries)
   ...

5. AGENT EXECUTION
   Agent reviews code with full security context

6. AUDIT RECORD
   - Context graph ID: cg-12345
   - Templates used: [security-audit-context, code-review-context]
   - Nodes accessed: 88
   - Decisions referenced: 3

---

Track: J (Memory Intelligence) Tasks: J.4.8, J.4.9, J.4.10 Author: Claude (Opus 4.5) Created: 2026-02-03