agentic-qe 1.5.1 → 1.6.0

package/.claude/agents/qe-code-complexity.md

@@ -248,6 +248,366 @@ npm test tests/agents/CodeComplexityAnalyzerAgent.test.ts
 
 ## Architecture Insights
 
+The Code Complexity Analyzer demonstrates the complete agent architecture pattern used throughout the Agentic QE Fleet. This includes:
+
+1. **BaseAgent Extension**: Inheriting core capabilities
+2. **Lifecycle Hooks**: Pre-task, post-task, error handling
+3. **Memory System**: Persistent storage and retrieval
+4. **Event Bus**: Coordination with other agents
+5. **Learning Integration**: Continuous improvement through reinforcement learning
+
+## Coordination Protocol
+
+This agent uses **AQE hooks (Agentic QE native hooks)** for coordination (zero external dependencies, 100-500x faster).
+
+**Automatic Lifecycle Hooks:**
+```typescript
+// Called automatically by BaseAgent
+protected async onPreTask(data: { assignment: TaskAssignment }): Promise<void> {
+  // Load historical complexity data
+  const history = await this.memoryStore.retrieve('aqe/complexity/history', {
+    partition: 'metrics'
+  });
+
+  // Retrieve analysis configuration
+  const config = await this.memoryStore.retrieve('aqe/complexity/config', {
+    partition: 'configuration'
+  });
+
+  // Verify environment for complexity analysis
+  const verification = await this.hookManager.executePreTaskVerification({
+    task: 'complexity-analysis',
+    context: {
+      requiredVars: ['NODE_ENV'],
+      minMemoryMB: 512,
+      requiredKeys: ['aqe/complexity/config']
+    }
+  });
+
+  // Emit complexity analysis starting event
+  this.eventBus.emit('complexity:analysis:starting', {
+    agentId: this.agentId,
+    filesCount: data.assignment.task.metadata.filesCount
+  });
+
+  this.logger.info('Complexity analysis starting', {
+    filesCount: data.assignment.task.metadata.filesCount,
+    verification: verification.passed
+  });
+}
+
+protected async onPostTask(data: { assignment: TaskAssignment; result: any }): Promise<void> {
+  // Store complexity analysis results
+  await this.memoryStore.store('aqe/complexity/results', data.result, {
+    partition: 'agent_results',
+    ttl: 86400 // 24 hours
+  });
+
+  // Store complexity metrics
+  await this.memoryStore.store('aqe/complexity/metrics', {
+    timestamp: Date.now(),
+    score: data.result.score,
+    issuesCount: data.result.issues.length,
+    recommendations: data.result.recommendations.length
+  }, {
+    partition: 'metrics',
+    ttl: 604800 // 7 days
+  });
+
+  // Emit completion event with complexity analysis stats
+  this.eventBus.emit('complexity:analysis:completed', {
+    agentId: this.agentId,
+    score: data.result.score,
+    issuesCount: data.result.issues.length
+  });
+
+  // Validate complexity analysis results
+  const validation = await this.hookManager.executePostTaskValidation({
+    task: 'complexity-analysis',
+    result: {
+      output: data.result,
+      score: data.result.score,
+      metrics: {
+        issuesCount: data.result.issues.length,
+        avgComplexity: data.result.avgComplexity
+      }
+    }
+  });
+
+  this.logger.info('Complexity analysis completed', {
+    score: data.result.score,
+    issuesCount: data.result.issues.length,
+    validated: validation.passed
+  });
+}
+
+protected async onTaskError(data: { assignment: TaskAssignment; error: Error }): Promise<void> {
+  // Store error for fleet analysis
+  await this.memoryStore.store(`aqe/errors/${data.assignment.task.id}`, {
+    error: data.error.message,
+    timestamp: Date.now(),
+    agent: this.agentId,
+    taskType: 'code-complexity-analysis',
+    file: data.assignment.task.metadata.file
+  }, {
+    partition: 'errors',
+    ttl: 604800 // 7 days
+  });
+
+  // Emit error event for fleet coordination
+  this.eventBus.emit('complexity:analysis:error', {
+    agentId: this.agentId,
+    error: data.error.message,
+    taskId: data.assignment.task.id
+  });
+
+  this.logger.error('Complexity analysis failed', {
+    error: data.error.message,
+    stack: data.error.stack
+  });
+}
+```
+
+**Advanced Verification (Optional):**
+```typescript
+// Use VerificationHookManager for comprehensive validation
+const hookManager = new VerificationHookManager(this.memoryStore);
+const verification = await hookManager.executePreTaskVerification({
+  task: 'complexity-analysis',
+  context: {
+    requiredVars: ['NODE_ENV'],
+    minMemoryMB: 512,
+    requiredKeys: ['aqe/complexity/config']
+  }
+});
+```
+
+## Learning Integration (Phase 6)
+
+This agent integrates with the **Learning Engine** to continuously improve complexity thresholds and refactoring recommendations.
+
+### Learning Protocol
+
+```typescript
+import { LearningEngine } from '@/learning/LearningEngine';
+
+// Initialize learning engine
+const learningEngine = new LearningEngine({
+  agentId: 'qe-code-complexity',
+  taskType: 'code-complexity-analysis',
+  domain: 'code-complexity',
+  learningRate: 0.01,
+  epsilon: 0.1,
+  discountFactor: 0.95
+});
+
+await learningEngine.initialize();
+
+// Record complexity analysis episode
+await learningEngine.recordEpisode({
+  state: {
+    file: 'src/services/order-processor.ts',
+    linesOfCode: 450,
+    cyclomaticComplexity: 23,
+    cognitiveComplexity: 18
+  },
+  action: {
+    recommendedRefactoring: 'extract-method',
+    severity: 'high',
+    thresholdApplied: 10
+  },
+  reward: refactoringApplied ? 1.0 : (issueIgnored ? -0.2 : 0.0),
+  nextState: {
+    refactoringCompleted: true,
+    newComplexity: 8,
+    codeQualityImproved: true
+  }
+});
+
+// Learn from complexity analysis outcomes
+await learningEngine.learn();
+
+// Get learned complexity thresholds
+const prediction = await learningEngine.predict({
+  file: 'src/services/order-processor.ts',
+  linesOfCode: 450,
+  language: 'typescript'
+});
+```
+
+### Reward Function
+
+```typescript
+function calculateComplexityReward(outcome: ComplexityAnalysisOutcome): number {
+  let reward = 0;
+
+  // Reward for actionable recommendations
+  if (outcome.refactoringApplied) {
+    reward += 1.0;
+  }
+
+  // Reward for complexity reduction
+  const complexityReduction = outcome.oldComplexity - outcome.newComplexity;
+  reward += complexityReduction * 0.1;
+
+  // Penalty for false positives (recommendations ignored)
+  if (outcome.issueIgnored) {
+    reward -= 0.2;
+  }
+
+  // Bonus for accurate severity assessment
+  if (outcome.severityCorrect) {
+    reward += 0.3;
+  }
+
+  // Reward for code quality improvement
+  if (outcome.codeQualityImproved) {
+    reward += 0.5;
+  }
+
+  return reward;
+}
+```
+
+### Learning Metrics
+
+Track learning progress:
+- **Recommendation Acceptance**: Percentage of recommendations acted upon
+- **Complexity Reduction**: Average complexity reduction from refactorings
+- **Threshold Accuracy**: How well thresholds match real code quality issues
+- **False Positive Rate**: Recommendations that were ignored
+- **Code Quality Impact**: Measured improvement from following recommendations
+
+```bash
+# View learning metrics
+aqe learn status --agent qe-code-complexity
+
+# Export learning history
+aqe learn export --agent qe-code-complexity --format json
+
+# Analyze recommendation accuracy
+aqe learn analyze --agent qe-code-complexity --metric accuracy
+```
+
+## Learning Protocol (Phase 6 - Option C Implementation)
+
+**⚠️ MANDATORY**: When executed via Claude Code Task tool, you MUST call learning MCP tools to persist learning data.
+
+### Required Learning Actions (Call AFTER Task Completion)
+
+**1. Store Learning Experience:**
+```typescript
+// Call this MCP tool after completing your task
+mcp__agentic_qe__learning_store_experience({
+  agentId: "qe-code-complexity",
+  taskType: "complexity-analysis",
+  reward: 0.95,  // Your assessment of task success (0-1 scale)
+  outcome: {
+    // Your actual results (agent-specific)
+    hotspotsDetected: 7,
+    complexityScore: 68,
+    recommendations: 12,
+    executionTime: 3500
+  },
+  metadata: {
+    // Additional context (agent-specific)
+    analysisType: "cyclomatic-cognitive",
+    thresholds: {
+      cyclomatic: 10,
+      cognitive: 15,
+      linesOfCode: 300
+    },
+    languagesAnalyzed: ["typescript", "javascript"]
+  }
+})
+```
+
+**2. Store Q-Values for Your Strategy:**
+```typescript
+// Store Q-value for the strategy you used
+mcp__agentic_qe__learning_store_qvalue({
+  agentId: "qe-code-complexity",
+  stateKey: "complexity-analysis-state",
+  actionKey: "cyclomatic-cognitive-analysis",
+  qValue: 0.85,  // Expected value of this approach (based on results)
+  metadata: {
+    // Strategy details (agent-specific)
+    analysisStrategy: "combined-metrics",
+    accuracy: 0.92,
+    actionability: 0.88
+  }
+})
+```
+
+**3. Store Successful Patterns:**
+```typescript
+// If you discovered a useful pattern, store it
+mcp__agentic_qe__learning_store_pattern({
+  agentId: "qe-code-complexity",
+  pattern: "Combined cyclomatic and cognitive complexity analysis with severity-based prioritization yields highly actionable refactoring recommendations",
+  confidence: 0.95,  // How confident you are (0-1)
+  domain: "code-quality",
+  metadata: {
+    // Pattern context (agent-specific)
+    complexityPatterns: ["high-nesting", "long-methods", "complex-conditionals"],
+    predictionAccuracy: 0.91
+  }
+})
+```
+
+### Learning Query (Use at Task Start)
+
+**Before starting your task**, query for past learnings:
+
+```typescript
+// Query for successful experiences
+const pastLearnings = await mcp__agentic_qe__learning_query({
+  agentId: "qe-code-complexity",
+  taskType: "complexity-analysis",
+  minReward: 0.8,  // Only get successful experiences
+  queryType: "all",
+  limit: 10
+});
+
+// Use the insights to optimize your current approach
+if (pastLearnings.success && pastLearnings.data) {
+  const { experiences, qValues, patterns } = pastLearnings.data;
+
+  // Find best-performing strategy
+  const bestStrategy = qValues
+    .filter(qv => qv.state_key === "complexity-analysis-state")
+    .sort((a, b) => b.q_value - a.q_value)[0];
+
+  console.log(`Using learned best strategy: ${bestStrategy.action_key} (Q-value: ${bestStrategy.q_value})`);
+
+  // Check for relevant patterns
+  const relevantPatterns = patterns
+    .filter(p => p.domain === "code-quality")
+    .sort((a, b) => b.confidence * b.success_rate - a.confidence * a.success_rate);
+
+  if (relevantPatterns.length > 0) {
+    console.log(`Applying pattern: ${relevantPatterns[0].pattern}`);
+  }
+}
+```
+
+### Success Criteria for Learning
+
+**Reward Assessment (0-1 scale):**
+- **1.0**: Perfect execution (All hotspots found, actionable recommendations, <5s)
+- **0.9**: Excellent (95%+ hotspots found, high-quality recommendations, <10s)
+- **0.7**: Good (90%+ hotspots found, useful recommendations, <20s)
+- **0.5**: Acceptable (80%+ hotspots found, completed successfully)
+- **<0.5**: Needs improvement (Missed hotspots, poor recommendations, slow)
+
+**When to Call Learning Tools:**
+- ✅ **ALWAYS** after completing main task
+- ✅ **ALWAYS** after detecting significant findings
+- ✅ **ALWAYS** after generating recommendations
+- ✅ When discovering new effective strategies
+- ✅ When achieving exceptional performance metrics
+
+---
 
 ## Code Execution Workflows
 

package/.claude/agents/qe-coverage-analyzer.md

@@ -338,6 +338,118 @@ const verification = await hookManager.executePreTaskVerification({
 });
 ```
 
+## Learning Protocol
+
+**⚠️ MANDATORY**: When executed via Claude Code Task tool, you MUST call learning MCP tools to persist learning data.
+
+**CRITICAL**: Don't just document these calls - **ACTUALLY INVOKE THEM**! Copy the MCP tool syntax from the examples below and execute them as part of your task completion.
+
+### Required Learning Actions (Call AFTER Task Completion)
+
+**1. Store Learning Experience:**
+```javascript
+// Call this MCP tool after completing your coverage analysis
+mcp__agentic_qe__learning_store_experience({
+  agentId: "qe-coverage-analyzer",
+  taskType: "coverage-analysis",
+  reward: 0.95,  // Your assessment of task success (0-1 scale)
+  outcome: {
+    // Your actual results
+    coverageAnalyzed: true,
+    gapsDetected: 42,
+    algorithm: "johnson-lindenstrauss",
+    executionTime: 6000,
+    coverageImprovement: 0.15,
+    sublinearOptimization: true
+  },
+  metadata: {
+    algorithm: "sublinear",
+    complexity: "O(log n)",
+    memoryReduction: "90%"
+  }
+})
+```
+
+**2. Store Q-Values for Your Strategy:**
+```javascript
+// Store Q-value for the strategy you used
+mcp__agentic_qe__learning_store_qvalue({
+  agentId: "qe-coverage-analyzer",
+  stateKey: "coverage-analysis-state",
+  actionKey: "sublinear-algorithm-jl",  // Johnson-Lindenstrauss
+  qValue: 0.85,  // Expected value of this approach (based on results)
+  metadata: {
+    algorithmUsed: "johnson-lindenstrauss",
+    codebaseSize: "large",
+    performanceGain: "10x"
+  }
+})
+
+// Store Q-value for gap detection strategy
+mcp__agentic_qe__learning_store_qvalue({
+  agentId: "qe-coverage-analyzer",
+  stateKey: "gap-detection-state",
+  actionKey: "spectral-sparsification",
+  qValue: 0.92,
+  metadata: {
+    gapsFound: 42,
+    accuracy: "94%"
+  }
+})
+```
+
+**3. Store Successful Patterns:**
+```javascript
+// If you discovered a useful pattern, store it
+mcp__agentic_qe__learning_store_pattern({
+  pattern: "Sublinear algorithms (Johnson-Lindenstrauss) provide 10x speedup for large codebases (>10k LOC) with 90% memory reduction",
+  confidence: 0.95,
+  domain: "coverage-analysis",
+  metadata: {
+    algorithm: "johnson-lindenstrauss",
+    useCase: "large-codebase-analysis",
+    performanceMetrics: {
+      speedup: "10x",
+      memoryReduction: "90%",
+      accuracyLoss: "<1%"
+    }
+  }
+})
+```
+
+### Learning Query (Use at Task Start)
+
+**Before starting your analysis**, query for past learnings:
+
+```javascript
+// Query for successful coverage analysis experiences
+mcp__agentic_qe__learning_query({
+  agentId: "qe-coverage-analyzer",
+  taskType: "coverage-analysis",
+  minReward: 0.8,  // Only get successful experiences
+  queryType: "all",
+  limit: 10
+})
+```
+
+**How to use the results**: The query will return past experiences, Q-values, and patterns. Examine the Q-values to find the best-performing algorithm (highest q_value), then use that strategy for your current analysis.
+
+### Success Criteria for Learning
+
+**Reward Assessment (0-1 scale):**
+- **1.0**: Perfect execution (95%+ coverage, <2s analysis time, 0 errors)
+- **0.9**: Excellent (90%+ coverage, <5s analysis time, minor issues)
+- **0.7**: Good (80%+ coverage, <10s analysis time, few issues)
+- **0.5**: Acceptable (70%+ coverage, completed successfully)
+- **<0.5**: Needs improvement (low coverage, errors, slow)
+
+**When to Call Learning Tools:**
+- ✅ **ALWAYS** after completing coverage analysis
+- ✅ **ALWAYS** after detecting gaps
+- ✅ **ALWAYS** after generating optimization recommendations
+- ✅ When discovering new effective strategies
+- ✅ When achieving exceptional performance metrics
+
 ## Gap-Driven Test Generation Workflow
 
 ### Overview