@agentic-qe/v3 3.0.0-alpha.10

package/README.md

@@ -0,0 +1,429 @@
+# Agentic QE v3
+
+[![npm version](https://img.shields.io/npm/v/@agentic-qe/v3.svg)](https://www.npmjs.com/package/@agentic-qe/v3)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+> Domain-Driven Quality Engineering with 12 Bounded Contexts, ReasoningBank Learning, and HNSW Vector Search
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @agentic-qe/v3
+
+# Initialize your project
+cd your-project
+aqe-v3 init --wizard
+
+# Or with auto-configuration
+aqe-v3 init --auto
+
+# Add MCP server to Claude Code
+claude mcp add agentic-qe-v3 npx @agentic-qe/v3 mcp
+```
+
+## Architecture Overview
+
+Agentic QE v3 uses a **Domain-Driven Design (DDD)** architecture with a microkernel pattern:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Queen Coordinator                                  │
+│                    (Task Orchestration & Work Stealing)                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                        Cross-Domain Event Router                             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                              QE Kernel                                       │
+│  ┌──────────┐  ┌──────────────┐  ┌─────────────┐  ┌──────────────────────┐  │
+│  │ EventBus │  │ AgentCoord.  │  │ PluginLoader│  │ Memory (HNSW+SQLite) │  │
+│  └──────────┘  └──────────────┘  └─────────────┘  └──────────────────────┘  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                          12 Bounded Contexts                                 │
+│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐   │
+│  │ Test          │ │ Test          │ │ Coverage      │ │ Quality       │   │
+│  │ Generation    │ │ Execution     │ │ Analysis      │ │ Assessment    │   │
+│  └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘   │
+│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐   │
+│  │ Defect        │ │ Requirements  │ │ Code          │ │ Security      │   │
+│  │ Intelligence  │ │ Validation    │ │ Intelligence  │ │ Compliance    │   │
+│  └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘   │
+│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐   │
+│  │ Contract      │ │ Visual        │ │ Chaos         │ │ Learning      │   │
+│  │ Testing       │ │ Accessibility │ │ Resilience    │ │ Optimization  │   │
+│  └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## 12 DDD Bounded Contexts
+
+| Domain | Description | Key Features |
+|--------|-------------|--------------|
+| **test-generation** | AI-powered test creation | Pattern learning, multi-framework support, coverage targeting |
+| **test-execution** | Parallel test running | Retry logic, flaky detection, parallel orchestration |
+| **coverage-analysis** | O(log n) gap detection | HNSW indexing, risk scoring, sublinear analysis |
+| **quality-assessment** | Quality gates | Deployment decisions, metric aggregation, trend analysis |
+| **defect-intelligence** | Defect prediction | Root cause analysis, pattern learning, regression detection |
+| **requirements-validation** | BDD scenarios | Testability scoring, acceptance criteria, Gherkin generation |
+| **code-intelligence** | Knowledge graph | Semantic search, impact analysis, dependency mapping |
+| **security-compliance** | SAST/DAST scanning | OWASP checks, CVE detection, compliance validation |
+| **contract-testing** | API contracts | Schema validation, breaking change detection, GraphQL support |
+| **visual-accessibility** | Visual regression | WCAG compliance, responsive testing, screenshot comparison |
+| **chaos-resilience** | Chaos engineering | Fault injection, load testing, resilience validation |
+| **learning-optimization** | Cross-domain learning | Pattern transfer, metric optimization, SONA integration |
+
+## Core Components
+
+### QE Kernel
+
+The microkernel provides core infrastructure:
+
+```typescript
+import { QEKernelImpl } from '@agentic-qe/v3';
+
+const kernel = new QEKernelImpl({
+  maxConcurrentAgents: 15,
+  memoryBackend: 'hybrid',      // 'sqlite' | 'hybrid' | 'agentdb'
+  hnswEnabled: true,            // 150x faster vector search
+  lazyLoading: true,            // Load domains on demand
+  enabledDomains: [
+    'test-generation',
+    'coverage-analysis',
+    // ... other domains
+  ],
+});
+
+await kernel.initialize();
+```
+
+### Queen Coordinator
+
+Orchestrates tasks across all domains:
+
+```typescript
+import { createQueenCoordinator } from '@agentic-qe/v3';
+
+const queen = createQueenCoordinator(kernel, router, executor);
+await queen.initialize();
+
+// Submit a task
+const result = await queen.submitTask({
+  type: 'generate-tests',
+  priority: 'p1',
+  targetDomains: ['test-generation'],
+  payload: { sourceFile: 'src/user-service.ts' },
+  timeout: 300000,
+});
+
+// Check health
+const health = queen.getHealth();
+console.log(`Status: ${health.status}, Agents: ${health.totalAgents}`);
+```
+
+### Event Bus
+
+Cross-domain communication:
+
+```typescript
+// Publish events
+kernel.eventBus.publish('test-generation.tests-generated', {
+  testCount: 15,
+  coverage: 85,
+});
+
+// Subscribe to events
+kernel.eventBus.subscribe('coverage-analysis.gap-detected', (event) => {
+  console.log('Coverage gap:', event.payload);
+});
+```
+
+### Memory Backend
+
+HNSW-indexed vector storage:
+
+```typescript
+// Store with vector embedding
+await kernel.memory.store('pattern:auth-test', {
+  pattern: 'JWT authentication test pattern',
+  confidence: 0.95,
+}, { namespace: 'patterns', ttl: 86400 });
+
+// Semantic search (150x faster with HNSW)
+const results = await kernel.memory.search('authentication patterns', {
+  limit: 10,
+  threshold: 0.7,
+});
+```
+
+## CLI Commands
+
+### Initialization
+
+```bash
+# Interactive wizard
+aqe-v3 init --wizard
+
+# Auto-configure based on project
+aqe-v3 init --auto
+
+# Manual configuration
+aqe-v3 init -d test-generation,coverage-analysis -m hybrid --max-agents 20
+```
+
+### Status & Health
+
+```bash
+# System status
+aqe-v3 status
+aqe-v3 status --verbose
+
+# Domain health
+aqe-v3 health
+aqe-v3 health -d test-generation
+```
+
+### Test Generation
+
+```bash
+# Generate tests for a file
+aqe-v3 test generate src/services/user.ts
+
+# Generate with options
+aqe-v3 test generate src/ -t unit -f vitest
+```
+
+### Coverage Analysis
+
+```bash
+# Analyze coverage
+aqe-v3 coverage ./src
+
+# With gap detection and risk scoring
+aqe-v3 coverage ./src --gaps --risk
+```
+
+### Security Scanning
+
+```bash
+# Run SAST scan
+aqe-v3 security --sast -t ./src
+
+# Check compliance
+aqe-v3 security --compliance gdpr,hipaa
+```
+
+### Code Intelligence
+
+```bash
+# Index codebase
+aqe-v3 code index ./src
+
+# Semantic search
+aqe-v3 code search "authentication middleware"
+
+# Impact analysis
+aqe-v3 code impact ./src/auth.ts
+
+# Dependency mapping
+aqe-v3 code deps ./src
+```
+
+### Migration from v2
+
+```bash
+# Preview migration
+aqe-v3 migrate --dry-run
+
+# Run migration with backup
+aqe-v3 migrate --backup
+
+# Full migration
+aqe-v3 migrate
+```
+
+### Task Management
+
+```bash
+# Submit a task
+aqe-v3 task submit generate-tests -p p1 --payload '{"source":"src/"}'
+
+# List tasks
+aqe-v3 task list
+aqe-v3 task list -s running
+
+# Task status
+aqe-v3 task status <task-id>
+
+# Cancel task
+aqe-v3 task cancel <task-id>
+```
+
+### Agent Management
+
+```bash
+# List agents
+aqe-v3 agent list
+aqe-v3 agent list -d test-generation
+
+# Spawn agent
+aqe-v3 agent spawn test-generation -t worker -c unit-test,integration-test
+```
+
+## MCP Integration
+
+Add the v3 MCP server to Claude Code:
+
+```bash
+claude mcp add agentic-qe-v3 npx @agentic-qe/v3 mcp
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `fleet_init` | Initialize the QE fleet |
+| `fleet_status` | Get fleet and agent status |
+| `fleet_health` | Check fleet health |
+| `task_submit` | Submit a task |
+| `task_list` | List all tasks |
+| `task_status` | Get task status |
+| `task_cancel` | Cancel a task |
+| `task_orchestrate` | Orchestrate complex QE workflows |
+| `agent_list` | List active agents |
+| `agent_spawn` | Spawn a new agent |
+| `agent_metrics` | Get agent performance metrics |
+| `test_generate_enhanced` | AI-powered test generation |
+| `test_execute_parallel` | Parallel test execution |
+| `coverage_analyze_sublinear` | O(log n) coverage analysis |
+| `quality_assess` | Quality gate assessment |
+| `security_scan_comprehensive` | SAST/DAST security scanning |
+| `contract_validate` | API contract validation |
+| `accessibility_test` | WCAG accessibility testing |
+| `chaos_test` | Chaos engineering tests |
+| `defect_predict` | AI defect prediction |
+| `requirements_validate` | Requirements validation |
+| `code_index` | Code intelligence indexing |
+| `memory_store` | Store data in memory |
+| `memory_retrieve` | Retrieve from memory |
+| `memory_query` | Query memory with patterns |
+| `memory_share` | Share knowledge between agents |
+
+## Programmatic API
+
+### Test Generation
+
+```typescript
+import { QEKernelImpl } from '@agentic-qe/v3';
+
+const kernel = new QEKernelImpl();
+await kernel.initialize();
+
+const testGenAPI = kernel.getDomainAPI('test-generation');
+const result = await testGenAPI.generateTests({
+  sourceFiles: ['src/user-service.ts'],
+  testType: 'unit',
+  framework: 'vitest',
+  coverageTarget: 90,
+});
+
+console.log(`Generated ${result.value.tests.length} tests`);
+```
+
+### Coverage Analysis
+
+```typescript
+const coverageAPI = kernel.getDomainAPI('coverage-analysis');
+const gaps = await coverageAPI.detectGaps({
+  coverageData: existingCoverage,
+  minCoverage: 80,
+  prioritize: 'risk',
+});
+
+console.log(`Found ${gaps.value.gaps.length} coverage gaps`);
+```
+
+### Quality Assessment
+
+```typescript
+const qualityAPI = kernel.getDomainAPI('quality-assessment');
+const gate = await qualityAPI.evaluateQualityGate({
+  metrics: {
+    coverage: 85,
+    testsPassing: 100,
+    securityVulnerabilities: 0,
+  },
+  thresholds: {
+    minCoverage: 80,
+    maxVulnerabilities: 0,
+  },
+});
+
+console.log(`Quality gate: ${gate.value.passed ? 'PASSED' : 'FAILED'}`);
+```
+
+## Performance Characteristics
+
+| Metric | v2 | v3 | Improvement |
+|--------|----|----|-------------|
+| Coverage Analysis | O(n) | O(log n) | Sublinear |
+| Pattern Search | Linear scan | HNSW index | 150x faster |
+| Memory Usage | Unbounded | Quantized | 50-75% reduction |
+| Agent Coordination | Sequential | Work stealing | 3-5x throughput |
+| Startup Time | ~2s | ~500ms | 4x faster |
+
+## Key Differences from v2
+
+| Feature | v2 | v3 |
+|---------|----|----|
+| Architecture | Monolithic | 12 DDD Bounded Contexts |
+| Test Framework | Jest | Vitest |
+| Module System | CommonJS | ESM |
+| Memory | SQLite only | HNSW + SQLite hybrid |
+| Learning | Basic patterns | ReasoningBank + SONA |
+| Agents | 31 | 47 QE agents |
+| CLI | `aqe` | `aqe-v3` |
+| Package | `agentic-qe` | `@agentic-qe/v3` |
+
+## Migration from v2
+
+See the [Migration Guide](../docs/MIGRATION-GUIDE.md) for detailed instructions.
+
+```bash
+# Quick migration
+npm install @agentic-qe/v3
+aqe-v3 migrate --backup
+```
+
+## Configuration
+
+### Project Configuration (.aqe-v3/config.json)
+
+```json
+{
+  "version": "3.0.0",
+  "kernel": {
+    "maxConcurrentAgents": 15,
+    "memoryBackend": "hybrid",
+    "hnswEnabled": true,
+    "lazyLoading": true
+  },
+  "domains": {
+    "test-generation": { "enabled": true },
+    "coverage-analysis": { "enabled": true, "algorithm": "hnsw" },
+    "security-compliance": { "enabled": true }
+  },
+  "learning": {
+    "reasoningBank": true,
+    "sona": true,
+    "patternRetention": 180
+  }
+}
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT - see [LICENSE](../LICENSE) for details.