agentic-qe 1.8.2 → 1.8.4

package/README.md

@@ -9,11 +9,11 @@
 <img alt="NPM Downloads" src="https://img.shields.io/npm/dw/agentic-qe">
 
 
-**Version 1.8.2** (Database Schema Fix) | [Changelog](CHANGELOG.md) | [Issues](https://github.com/proffesor-for-testing/agentic-qe/issues) | [Discussions](https://github.com/proffesor-for-testing/agentic-qe/discussions)
+**Version 1.8.4** (Phase 1 Infrastructure + Critical Fixes) | [Changelog](CHANGELOG.md) | [Issues](https://github.com/proffesor-for-testing/agentic-qe/issues) | [Discussions](https://github.com/proffesor-for-testing/agentic-qe/discussions)
 
-> Enterprise-grade test automation with AI learning, comprehensive skills library (38 QE skills), and intelligent model routing.
+> Enterprise-grade test automation with AI learning, OpenTelemetry observability, persistent event storage, constitutional AI governance, and intelligent model routing.
 
-🧠 **QE Agent Learning System** | 📚 **38 World-Class QE Skills** | 🎯 **Advanced Flaky Detection** | 💰 **Multi-Model Router** | 🔧 **32 Domain-Specific Tools**
+🧠 **QE Agent Learning** | 📊 **OpenTelemetry Integration** | 💾 **Event Sourcing** | 📋 **Constitution System** | 📚 **38 QE Skills** | 🎯 **Flaky Detection** | 💰 **Multi-Model Router**
 
 </div>
 
@@ -54,12 +54,13 @@ claude "Use qe-flaky-test-hunter to analyze the last 100 test runs and identify
 ```
 
 **What gets initialized:**
+- ✅ **Phase 1 Infrastructure**: OpenTelemetry, Event Store, Constitution System (v1.8.4)
 - ✅ Multi-Model Router (70-81% cost savings - opt-in)
 - ✅ Learning System (20% improvement target)
 - ✅ Pattern Bank (cross-project reuse)
 - ✅ ML Flaky Detection (100% accuracy)
 - ✅ 18 Specialized agent definitions (including qe-code-complexity)
-- ✅ 8 TDD subagent definitions (RED/GREEN/REFACTOR phases)
+- ✅ 11 TDD subagent definitions (RED/GREEN/REFACTOR phases + specialized)
 - ✅ 38 World-class QE skills library
 - ✅ 8 AQE slash commands
 - ✅ Configuration directory
@@ -68,9 +69,41 @@ claude "Use qe-flaky-test-hunter to analyze the last 100 test runs and identify
 
 ## ✨ Features
 
+### 🏗️ Phase 1 Infrastructure (v1.8.4)
+
+**Enterprise-Grade Observability & Governance**
+
+#### 📊 OpenTelemetry Integration
+- **Full OTEL SDK**: 12 OpenTelemetry packages for comprehensive observability
+- **Auto-Instrumentation**: HTTP, file system, and custom metrics
+- **Metrics Export**: gRPC and HTTP exporters for Grafana, Prometheus, Jaeger
+- **Agent Metrics**: Task completion, success rate, error tracking
+- **Quality Metrics**: Coverage %, defect density, test effectiveness
+- **System Metrics**: Memory, CPU, latency, throughput
+
+#### 💾 Event Sourcing & Persistence
+- **Event Store**: SQLite-based event sourcing with correlation tracking
+- **Reasoning Capture**: Agent decision tracking and prompt/response analysis
+- **Metrics Aggregation**: Time-window aggregation (hourly, daily, weekly)
+- **Performance Optimization**: Prepared statements, indexes, connection pooling
+- **Query API**: Time-range queries with pagination support
+
+#### 📋 Constitutional AI Governance
+- **JSON Schema Validation**: Type-safe constitution definitions
+- **4 Base Constitutions**: Default, test-generation, code-review, performance
+- **Inheritance & Merge**: Constitution composition with override support
+- **Agent-Specific**: Per-agent constitutional rules and guidelines
+- **Validation Pipeline**: Ensure agents follow constitutional principles
+
+**Benefits:**
+- 🔍 **Full Observability**: Track every agent action, metric, and decision
+- 📈 **Data-Driven**: Historical analysis for continuous improvement
+- 🛡️ **Governance**: Constitutional AI ensures quality and compliance
+- 🚀 **Production Ready**: Enterprise-grade persistence and monitoring
+
 ### 🤖 Autonomous Agent Fleet
 - **18 Specialized Agents**: Expert agents for every QE domain (test generation, coverage analysis, security scanning, performance testing, code complexity analysis)
-- **8 TDD Subagents**: Specialized subagents for Test-Driven Development workflow (RED/GREEN/REFACTOR phases + quality validation)
+- **11 TDD Subagents**: Specialized subagents for Test-Driven Development workflow (RED/GREEN/REFACTOR phases + quality validation + analysis)
 - **AI-Powered Coordination**: Event-driven architecture with intelligent task distribution
 - **Zero External Dependencies**: Native AQE hooks system (100-500x faster than external coordination)
 - **Scalable**: From single developer projects to enterprise-scale testing infrastructure
@@ -436,9 +469,9 @@ Model Usage:
 
 </details>
 
-**Total: 26 Agents** (18 main agents + 8 TDD subagents)
+**Total: 29 Agents** (18 main agents + 11 TDD subagents)
 
-### TDD Subagents (8 specialized)
+### TDD Subagents (11 specialized)
 
 <details>
 <summary><b>Test-Driven Development Subagents</b></summary>
@@ -455,6 +488,12 @@ The test generator orchestrates a complete TDD workflow through specialized suba
 | **qe-data-generator** | GENERATION | Test data creation | Realistic data generation, constraint satisfaction, edge cases |
 | **qe-performance-validator** | VALIDATION | Performance checks | SLA validation, benchmark comparison, threshold enforcement |
 | **qe-security-auditor** | AUDIT | Security validation | Vulnerability detection, compliance checking, threat modeling |
+| **qe-flaky-investigator** | ANALYSIS | Flaky test detection | Pattern detection, timing analysis, stabilization fixes |
+| **qe-coverage-gap-analyzer** | ANALYSIS | Coverage gaps | Risk scoring, gap detection, test recommendations |
+| **qe-test-data-architect-sub** | GENERATION | High-volume data | Schema-aware generation, relationship preservation |
+
+**Coordination Protocol:**
+All subagents use a unified coordination protocol with cycle-based memory namespaces (`aqe/tdd/cycle-{id}/*`) ensuring tests written in RED are the same tests validated in GREEN and refactored in REFACTOR. See [Coordination Guide](docs/subagents/coordination-guide.md).
 
 **Usage Example:**
 ```bash
@@ -539,60 +578,52 @@ The test generator automatically delegates to subagents for a complete RED-GREEN
 
 ---
 
-## 📝 What's New in v1.8.2
+## 📝 What's New in v1.8.3
 
-🔧 **Database Schema Enhancement** (2025-01-18)
+🔄 **Phase 4: TDD Subagent Coordination** (2025-01-19)
 
-This release improves the database initialization to create all required tables for the QE learning system, including ReasoningBank integration for advanced pattern matching.
+This release implements comprehensive TDD subagent coordination, solving the disconnected tests/code/refactor issue where RED-GREEN-REFACTOR cycle agents were producing inconsistent outputs.
 
 ### Key Improvements
-- **Enhanced Database Initialization** - Now creates 10 tables instead of 1 (9x improvement)
-  - ✅ 6 QE learning tables for pattern storage and quality metrics
-  - ✅ 2 ReasoningBank tables for semantic pattern search
-  - ✅ Schema versioning for future migrations
-  - ✅ 150x faster vector search with HNSW indexing
-
-- **ReasoningBank Integration** - Advanced pattern matching capabilities
-  - ✅ Task-type-based pattern storage
-  - ✅ Semantic similarity search (384-dim embeddings)
-  - ✅ Local embedding service (no external API needed)
-  - ✅ Pattern learning from successful executions
-
-- **Migration Support** - Easy upgrade for existing users
-  - ✅ Migration script preserves all existing data
-  - ✅ Automatic backups before migration
-  - ✅ Data integrity verification
-
-### Tables Created
-All fresh installations now get complete database schema:
-1. `patterns` - Base vector embeddings
-2. `test_patterns` - QE test patterns with deduplication
-3. `pattern_usage` - Quality metrics tracking
-4. `cross_project_mappings` - Framework translation rules
-5. `pattern_similarity_index` - Fast similarity lookups
-6. `pattern_fts` - Full-text search
-7. `schema_version` - Migration tracking
-8. `reasoning_patterns` - ReasoningBank patterns
-9. `pattern_embeddings` - Vector embeddings
-10. `sqlite_sequence` - Auto-increment tracking
-
-### Migration Guide
-**Existing users (v1.8.0-1.8.1)**:
-```bash
-npm install agentic-qe@1.8.2
-npx tsx node_modules/agentic-qe/scripts/migrate-add-qe-tables.ts
-```
 
-**Fresh installations**: All tables created automatically during `aqe init`.
+- **TDD Coordination Protocol** - Memory-based coordination for consistent TDD cycles
+  - ✅ Cycle-based memory namespace (`aqe/tdd/cycle-{cycleId}/*`)
+  - ✅ File hash validation ensures test file integrity across phases
+  - ✅ Handoff gates prevent premature phase transitions
+  - ✅ Phase output interfaces for typed contracts
+
+- **Runtime Enforcement** - TDDPhaseValidator class validates memory state
+  - ✅ Validates memory keys exist before phase transitions
+  - ✅ Enforces output schema compliance
+  - ✅ Checks file hash integrity across RED→GREEN→REFACTOR
+  - ✅ Coverage comparison warnings
+
+- **New Subagents (3)** - Specialized quality engineering agents
+  - ✅ `qe-flaky-investigator` - Detects flaky tests, analyzes root causes
+  - ✅ `qe-coverage-gap-analyzer` - Identifies coverage gaps, risk-scores untested code
+  - ✅ `qe-test-data-architect-sub` - High-volume test data generation
+
+### Updated Subagents (8)
+All existing subagents now include coordination protocol:
+- `qe-test-writer`, `qe-test-implementer`, `qe-test-refactorer` (TDD phases)
+- `qe-code-reviewer`, `qe-integration-tester`, `qe-performance-validator`
+- `qe-security-auditor`, `qe-data-generator`
+
+### Testing
+- 22 integration tests for TDD coordination
+- All tests passing
+
+### Documentation
+- Coordination guide at `docs/subagents/coordination-guide.md`
 
 ### Impact
 ✅ **Build Status**: Passing (0 errors)
-✅ **Database Schema**: Complete (10/10 tables)
-✅ **Pattern Storage**: Fully operational
-✅ **Semantic Search**: Enabled (HNSW + SIMD)
+✅ **TDD Coordination**: Fully operational
+✅ **Subagents**: 11 total (3 new, 8 updated)
+✅ **Integration Tests**: 22 passing
 ❌ **Breaking Changes**: None
 
-**Upgrade from v1.8.1**: Fully backward-compatible. Run `npm install agentic-qe@1.8.2` and `aqe init`.
+**Upgrade**: `npm install agentic-qe@1.8.3`
 
 **Previous Releases**: See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 
@@ -700,7 +731,7 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for deta
 - ✅ Pattern Bank with cross-project sharing
 - ✅ ML Flaky Detection (100% accuracy)
 - ✅ Continuous Improvement Loop
-- ✅ 18 specialized agents + 8 TDD subagents
+- ✅ 18 specialized agents + 11 TDD subagents
 - ✅ Complete TDD workflow automation (RED/GREEN/REFACTOR/REVIEW)
 - ✅ Multi-framework test execution
 - ✅ Real-time coverage analysis

package/config/constitution.schema.json

@@ -0,0 +1,423 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://agentic-qe.io/schemas/constitution.schema.json",
+  "title": "Constitution Schema",
+  "description": "Schema for Agentic QE Fleet constitution definitions that govern quality evaluation criteria",
+  "type": "object",
+  "required": ["id", "name", "version", "description", "principles", "rules", "metrics", "thresholds", "metadata"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier for the constitution",
+      "pattern": "^[a-z0-9-]+$",
+      "minLength": 1,
+      "maxLength": 100
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of the constitution's purpose",
+      "minLength": 1,
+      "maxLength": 2000
+    },
+    "principles": {
+      "type": "array",
+      "description": "Core quality principles",
+      "items": { "$ref": "#/definitions/Principle" },
+      "minItems": 1
+    },
+    "rules": {
+      "type": "array",
+      "description": "Evaluation rules",
+      "items": { "$ref": "#/definitions/Rule" }
+    },
+    "metrics": {
+      "type": "array",
+      "description": "Metric definitions",
+      "items": { "$ref": "#/definitions/MetricDefinition" }
+    },
+    "thresholds": {
+      "type": "array",
+      "description": "Quality thresholds",
+      "items": { "$ref": "#/definitions/Threshold" }
+    },
+    "metadata": {
+      "$ref": "#/definitions/ConstitutionMetadata"
+    }
+  },
+  "definitions": {
+    "PriorityLevel": {
+      "type": "string",
+      "enum": ["critical", "high", "medium", "low"],
+      "description": "Priority level for principles and rules"
+    },
+    "SeverityLevel": {
+      "type": "string",
+      "enum": ["error", "warning", "info"],
+      "description": "Severity level for rule violations"
+    },
+    "AggregationType": {
+      "type": "string",
+      "enum": ["sum", "avg", "min", "max", "count", "percentile"],
+      "description": "Aggregation method for metrics"
+    },
+    "ConditionOperator": {
+      "type": "string",
+      "enum": [
+        "equals", "not_equals", "greater_than", "less_than",
+        "greater_than_or_equal", "less_than_or_equal",
+        "contains", "not_contains", "matches",
+        "in", "not_in", "exists", "not_exists"
+      ],
+      "description": "Condition operator for rule evaluation"
+    },
+    "ActionType": {
+      "type": "string",
+      "enum": ["fail", "warn", "notify", "log", "block", "require_review", "auto_fix", "escalate"],
+      "description": "Action type when rules are triggered"
+    },
+    "ThresholdMode": {
+      "type": "string",
+      "enum": ["absolute", "percentage", "relative"],
+      "description": "Threshold comparison mode"
+    },
+    "ConstitutionStatus": {
+      "type": "string",
+      "enum": ["active", "deprecated", "draft", "archived"],
+      "description": "Constitution status"
+    },
+    "Principle": {
+      "type": "object",
+      "required": ["id", "name", "description", "priority", "category"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the principle",
+          "pattern": "^[a-z0-9-]+$"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Detailed description of the principle"
+        },
+        "priority": { "$ref": "#/definitions/PriorityLevel" },
+        "category": {
+          "type": "string",
+          "description": "Category grouping for the principle"
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Optional tags for filtering and search"
+        },
+        "mandatory": {
+          "type": "boolean",
+          "description": "Whether this principle is mandatory",
+          "default": false
+        },
+        "relatedPrinciples": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Related principle IDs"
+        }
+      }
+    },
+    "RuleCondition": {
+      "type": "object",
+      "required": ["field", "operator", "value"],
+      "additionalProperties": false,
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The field or metric to evaluate"
+        },
+        "operator": { "$ref": "#/definitions/ConditionOperator" },
+        "value": {
+          "oneOf": [
+            { "type": "string" },
+            { "type": "number" },
+            { "type": "boolean" },
+            { "type": "array", "items": { "type": "string" } },
+            { "type": "array", "items": { "type": "number" } }
+          ],
+          "description": "Value to compare against"
+        },
+        "unit": {
+          "type": "string",
+          "description": "Optional unit for the value"
+        },
+        "and": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RuleCondition" },
+          "description": "Nested conditions for complex logic"
+        },
+        "or": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RuleCondition" },
+          "description": "Alternative conditions"
+        }
+      }
+    },
+    "RuleAction": {
+      "type": "object",
+      "required": ["type", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "$ref": "#/definitions/ActionType" },
+        "message": {
+          "type": "string",
+          "description": "Message to display or log"
+        },
+        "params": {
+          "type": "object",
+          "description": "Additional parameters for the action"
+        },
+        "stopProcessing": {
+          "type": "boolean",
+          "description": "Whether to halt further processing",
+          "default": false
+        },
+        "notify": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Notification targets"
+        }
+      }
+    },
+    "Rule": {
+      "type": "object",
+      "required": ["id", "principleId", "condition", "action", "severity"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the rule",
+          "pattern": "^[a-z0-9-]+$"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable name"
+        },
+        "principleId": {
+          "type": "string",
+          "description": "Reference to the principle this rule enforces"
+        },
+        "condition": { "$ref": "#/definitions/RuleCondition" },
+        "action": { "$ref": "#/definitions/RuleAction" },
+        "severity": { "$ref": "#/definitions/SeverityLevel" },
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether this rule is enabled",
+          "default": true
+        },
+        "description": {
+          "type": "string",
+          "description": "Description of what this rule checks"
+        },
+        "remediation": {
+          "type": "string",
+          "description": "Remediation guidance when rule is violated"
+        },
+        "examples": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Example of compliant code/configuration"
+        }
+      }
+    },
+    "MetricDefinition": {
+      "type": "object",
+      "required": ["id", "name", "unit", "aggregation"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the metric",
+          "pattern": "^[a-z0-9-]+$"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Description of what this metric measures"
+        },
+        "unit": {
+          "type": "string",
+          "description": "Unit of measurement"
+        },
+        "aggregation": { "$ref": "#/definitions/AggregationType" },
+        "targetValue": {
+          "type": "number",
+          "description": "Target value to achieve"
+        },
+        "warningThreshold": {
+          "type": "number",
+          "description": "Value that triggers a warning"
+        },
+        "criticalThreshold": {
+          "type": "number",
+          "description": "Value that triggers a critical alert"
+        },
+        "dataType": {
+          "type": "string",
+          "enum": ["number", "percentage", "duration", "count", "ratio"],
+          "description": "Data type of the metric value"
+        },
+        "higherIsBetter": {
+          "type": "boolean",
+          "description": "Whether higher values are better",
+          "default": true
+        },
+        "formula": {
+          "type": "string",
+          "description": "Formula for computed metrics"
+        },
+        "dependencies": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Dependencies on other metrics"
+        },
+        "percentile": {
+          "type": "number",
+          "description": "Percentile for percentile-based metrics",
+          "minimum": 0,
+          "maximum": 100
+        }
+      }
+    },
+    "Threshold": {
+      "type": "object",
+      "required": ["id", "metricId", "mode", "warning", "critical"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the threshold",
+          "pattern": "^[a-z0-9-]+$"
+        },
+        "metricId": {
+          "type": "string",
+          "description": "Reference to the metric this threshold applies to"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable name"
+        },
+        "mode": { "$ref": "#/definitions/ThresholdMode" },
+        "warning": {
+          "type": "number",
+          "description": "Warning level value"
+        },
+        "critical": {
+          "type": "number",
+          "description": "Critical level value"
+        },
+        "target": {
+          "type": "number",
+          "description": "Target value to aim for"
+        },
+        "blocking": {
+          "type": "boolean",
+          "description": "Whether to block on threshold violation",
+          "default": false
+        },
+        "period": {
+          "type": "string",
+          "description": "Time period for threshold evaluation"
+        },
+        "environments": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Applicable environments"
+        }
+      }
+    },
+    "ChangelogEntry": {
+      "type": "object",
+      "required": ["version", "date", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "Version number"
+        },
+        "date": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Date of change"
+        },
+        "description": {
+          "type": "string",
+          "description": "Description of changes"
+        },
+        "author": {
+          "type": "string",
+          "description": "Who made the change"
+        }
+      }
+    },
+    "ConstitutionMetadata": {
+      "type": "object",
+      "required": ["createdAt", "updatedAt", "author", "applicableTo", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the constitution was created"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the constitution was last updated"
+        },
+        "author": {
+          "type": "string",
+          "description": "Who created or maintains the constitution"
+        },
+        "applicableTo": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Applicable agent types",
+          "minItems": 1
+        },
+        "inheritsFrom": {
+          "type": "string",
+          "description": "Parent constitution to inherit from"
+        },
+        "status": { "$ref": "#/definitions/ConstitutionStatus" },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Optional expiration date"
+        },
+        "changelog": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/ChangelogEntry" },
+          "description": "Changelog entries"
+        },
+        "customProperties": {
+          "type": "object",
+          "description": "Custom properties"
+        }
+      }
+    }
+  }
+}