Context Epic

User Journey

The Context bounded context enables AI systems to maintain and retrieve situational awareness across conversational interactions and project contexts. It serves as the semantic memory layer that combines conversational context (user intents, extracted entities, dialogue history) with project context (technical stack, architectural patterns, dependencies) into unified, queryable context snapshots with vector representations for semantic similarity operations.

Jobs to be Done & EARS Requirements

Job: Execute AnalyzeConversationalContext

User Story: As a conversational AI system, I want to process user input to extract intent and entities, so that I can maintain conversational context for personalized responses.

EARS Requirement:

• While the system is operational, when the AnalyzeConversationalContext command (CMD-CTX-001) is received with UserRequest containing input text, the context system shall:
  1. Extract the primary intent from the user input using IntentResult value object
  2. Identify and extract relevant entities using ExtractedEntity value objects
  3. Build ConversationalContext containing user input, intent, entities, and dialogue history
  4. Create or update a ContextSnapshot aggregate with the conversational data
  5. Enforce ValidSemanticVersion policy (POL-CTX-001) ensuring semantic version > 0
  6. Enforce ValidExpiry policy (POL-CTX-002) ensuring expiry timestamp > creation timestamp

Job: Execute AnalyzeProject

User Story: As a developer or AI system, I want to start background analysis of a codebase to extract technical context, so that I can enable context-aware code generation and architectural understanding.

EARS Requirement:

• While the system is operational, when the AnalyzeProject command (CMD-CTX-002) is received with ProjectRequest containing project location and AnalysisScope, the context system shall:
  1. Create an AnalysisJob aggregate with unique jobId, projectLocation, and scope
  2. Initialize job status to pending with progress at 0%
  3. Support configurable analysis depth via AnalysisScope (shallow, standard, full)
  4. Trigger background processing to analyze:
     • Code structure and patterns (if AST analysis enabled via feature flag)
     • Dependencies and import relationships
     • Technical stack identification
     • Architectural patterns detection
  5. Update job progress (0-100%) during processing
  6. Transition job status to completed with resultId reference, failed with error details, or cancelled
  7. Enforce CompletedJobHasResult policy (POL-CTX-003) for completed jobs

Job: Execute BuildHolisticContext

User Story: As an AI system, I want to aggregate multiple context sources (conversational, project, semantic memory, temporal state, causal history) into a unified snapshot, so that I can provide comprehensive context-aware responses.

EARS Requirement:

• While the system is operational, when the BuildHolisticContext command (CMD-CTX-003) is received with ContextRequest, the context system shall:
  1. Aggregate data from multiple context sources:
     • ConversationalContext: User input, intent, entities, dialogue history
     • ProjectContext: Technical stack, semantic project context, architectural context
     • SemanticMemory: Knowledge base of concepts, relationships, policies
     • TemporalState: Version information and deployment state
     • CausalHistory: Event tracking for provenance and debugging
  2. Generate HolisticContextVector as a semantic representation combining all sources
  3. Create ContextSnapshot aggregate with snapshotId, sessionId, aggregated context, and vector
  4. Set createdAt and expiresAt timestamps for time-based validity
  5. Enforce ValidSemanticVersion policy (POL-CTX-001) on the vector representation
  6. Enforce ValidExpiry policy (POL-CTX-002) ensuring expiry > creation

Job: Retrieve GetAnalysisJobStatus

User Story: As a system monitoring component or UI, I want to check the status of a project analysis job, so that I can display progress or handle completion/error states.

EARS Requirement:

• While the system is operational, when the GetAnalysisJobStatus query (QRY-CTX-003) is received with JobQuery containing jobId, the context system shall:
  1. Retrieve the AnalysisJob aggregate matching the jobId
  2. Return job details including:
     • jobId: Unique job identifier
     • projectLocation: Path to project being analyzed
     • scope: Analysis depth configuration
     • status: Current state (pending, processing, completed, failed, cancelled)
     • progress: Completion percentage (0-100)
     • resultId: Reference to analysis results (if completed)
     • Error details (if failed)
  3. Return null or error if job not found

Job: Retrieve GetCurrentContext

User Story: As an AI system, I want to retrieve the current context snapshot for a session, so that I can provide personalized, contextually relevant responses.

EARS Requirement:

• While the system is operational, when the GetCurrentContext query (QRY-CTX-001) is received with ContextQuery containing sessionId, the context system shall:
  1. Retrieve the active ContextSnapshot aggregate for the sessionId
  2. Validate the snapshot has not expired (expiresAt > current time)
  3. Return the complete ContextSnapshot containing:
     • snapshotId: Unique snapshot identifier
     • sessionId: Session identifier
     • conversational: ConversationalContext with intent, entities, dialogue history
     • project: ProjectContext with technical stack, semantic context, architectural patterns
     • holisticVector: HolisticContextVector for semantic operations
     • createdAt/expiresAt: Validity timestamps
  4. Return null or error if no valid snapshot exists

Job: Retrieve GetHolisticVector

User Story: As a semantic search or recommendation system, I want to retrieve the vector representation of context, so that I can perform semantic similarity matching and context-aware recommendations.

EARS Requirement:

• While the system is operational, when the GetHolisticVector query (QRY-CTX-004) is received with VectorQuery containing snapshotId, the context system shall:
  1. Retrieve the ContextSnapshot aggregate matching the snapshotId
  2. Extract and return the HolisticContextVector value object
  3. Return null or error if snapshot not found or vector not available

Job: Retrieve GetProjectContext

User Story: As a developer or AI system, I want to retrieve project-specific context details, so that I can understand the technical stack, architectural patterns, and dependencies for code generation and analysis.

EARS Requirement:

• While the system is operational, when the GetProjectContext query (QRY-CTX-002) is received with ProjectQuery containing projectId, the context system shall:
  1. Retrieve the ProjectContext for the specified projectId
  2. Return the complete ProjectContext containing:
     • TechnicalStack: Frameworks, languages, libraries identified
     • SemanticProjectContext: Domain concepts and relationships extracted
     • ArchitecturalContext: Patterns, layering, and design decisions
     • Dependencies: Import relationships and module dependencies
  3. Return null or error if project context not found

Domain Entities Summary

Root Aggregates

• ContextSnapshot: Point-in-time capture of conversational and project context with holistic vector
• AnalysisJob: Manages asynchronous project analysis lifecycle with status tracking

Value Objects

• HolisticContextVector: Semantic representation combining all context sources
• ConversationalContext: User input, intent, entities, dialogue history
• ProjectContext: Technical stack, semantic context, architectural patterns, dependencies
• SemanticMemory: Knowledge base of concepts, relationships, policies
• TemporalState: Version information and deployment state
• CausalHistory: Event tracking for provenance and debugging
• AnalysisScope: Configurable depth (shallow, standard, full) and scope of project analysis
• IntentResult: Extracted user intent from conversational input
• ExtractedEntity: Identified entities from user input
• TechnicalStack: Identified frameworks, languages, libraries
• SemanticProjectContext: Domain concepts and relationships
• ArchitecturalContext: Design patterns and architectural decisions

Integration Points

• Semantic Core Context: Provides knowledge base for semantic memory and ontologies
• Cognitive Extension Context: Consumes context for AI behavior personalization
• Shared Services Context: Integrates with messaging for cross-context communication
• Developer Tooling Context: Provides context-aware scaffolding and generation