agentic-qe 3.7.9 → 3.7.11

package/assets/governance/shards/coverage-analysis.shard.md

@@ -1,146 +1,146 @@
-# Coverage Analysis Domain Shard
-
-**Domain**: coverage-analysis
-**Version**: 1.0.0
-**Last Updated**: 2026-02-03
-**Parent Constitution**: `.claude/guidance/constitution.md`
-
----
-
-## Domain Rules
-
-1. **Sublinear Algorithm Mandate**: Coverage gap detection MUST use the O(log n) HNSW-based SublinearCoverageAnalyzer for codebases > 1000 files. Linear scan is prohibited at scale.
-
-2. **Real Data Only**: Coverage reports MUST be derived from actual test execution results, not estimated or synthesized data.
-
-3. **Risk-Weighted Prioritization**: Coverage gaps MUST be prioritized by risk score (complexity, change frequency, defect history), not just coverage percentage.
-
-4. **Trend Accuracy**: Coverage trend analysis MUST use at least 3 historical data points; single-point trends are invalid.
-
-5. **Embedding Freshness**: Coverage embeddings MUST be regenerated when source code changes exceed the staleness threshold (default: 7 days or 100+ file changes).
-
-6. **Gap Verification**: Identified coverage gaps MUST be verified against the actual codebase before generating test suggestions.
-
----
-
-## Quality Thresholds
-
-| Metric | Minimum | Target | Critical |
-|--------|---------|--------|----------|
-| Coverage Score | 0.6 | 0.8 | < 0.4 |
-| Confidence | 0.7 | 0.9 | < 0.5 |
-| Gap Detection Accuracy | 0.8 | 0.95 | < 0.6 |
-| Risk Scoring Accuracy | 0.7 | 0.85 | < 0.5 |
-| HNSW Query Efficiency | O(log n) | O(log n) | O(n) |
-
----
-
-## Invariants
-
-```
-INVARIANT sublinear_at_scale:
-  FOR ALL analysis IN coverage_analyses:
-    IF analysis.codebase_size > 1000 THEN
-      analysis.algorithm = 'HNSW_SUBLINEAR' AND
-      analysis.complexity <= O(log(analysis.codebase_size))
-```
-
-```
-INVARIANT real_coverage_data:
-  FOR ALL report IN coverage_reports:
-    EXISTS execution_source WHERE
-      execution_source.report_id = report.id AND
-      execution_source.type IN ['jest', 'vitest', 'nyc', 'c8'] AND
-      execution_source.timestamp IS NOT NULL
-```
-
-```
-INVARIANT trend_minimum_points:
-  FOR ALL trend IN coverage_trends:
-    trend.data_points.length >= 3
-```
-
-```
-INVARIANT embedding_freshness:
-  FOR ALL embedding IN coverage_embeddings:
-    (NOW() - embedding.created_at) < STALENESS_THRESHOLD OR
-    embedding.regeneration_scheduled = true
-```
-
----
-
-## Patterns
-
-**Domain Source**: `v3/src/domains/coverage-analysis/`
-
-| Pattern | Location | Description |
-|---------|----------|-------------|
-| Coverage Analyzer Service | `services/coverage-analyzer.ts` | Core coverage analysis |
-| Gap Detector Service | `services/gap-detector.ts` | Coverage gap identification |
-| Risk Scorer Service | `services/risk-scorer.ts` | Multi-factor risk scoring |
-| HNSW Index | `services/hnsw-index.ts` | O(log n) vector indexing |
-| Coverage Embedder | `services/coverage-embedder.ts` | Code-to-vector embedding |
-| Sublinear Analyzer | `services/sublinear-analyzer.ts` | ADR-003 sublinear implementation |
-
-**ADR Reference**: ADR-003 defines sublinear algorithm requirements.
-
----
-
-## Agent Constraints
-
-| Role | Agent ID | Permissions |
-|------|----------|-------------|
-| **Primary** | `qe-coverage-specialist` | Full analysis, gap detection, risk scoring |
-| **Secondary** | `qe-gap-detector` | Gap detection, test suggestions |
-| **Support** | `qe-test-architect` | Receive gaps, generate tests |
-| **Readonly** | `qe-quality-gate` | Coverage validation |
-
-**Forbidden Agents**: Agents without HNSW index access MUST NOT perform gap detection on large codebases.
-
----
-
-## Escalation Triggers
-
-| Trigger | Severity | Action |
-|---------|----------|--------|
-| Coverage < 0.4 | CRITICAL | Escalate to Queen Coordinator, prioritize test generation |
-| O(n) algorithm used at scale | CRITICAL | Escalate, require algorithm fix |
-| Gap detection accuracy < 0.6 | HIGH | Escalate, recalibrate model |
-| Stale embeddings > 14 days | HIGH | Escalate, force regeneration |
-| Trend shows declining coverage | MEDIUM | Notify coordinator, generate report |
-| Risk scoring confidence < 0.5 | MEDIUM | Request additional data points |
-| Synthetic data detected | CRITICAL | Block report, escalate for investigation |
-
----
-
-## Memory Namespace
-
-- **Namespace**: `qe-patterns/coverage-analysis`
-- **Retention**: 30 days with minimum 3 uses
-- **Contradiction Check**: Enabled
-
----
-
-## Integration Points
-
-| Domain | Integration Type | Purpose |
-|--------|-----------------|---------|
-| `test-execution` | Input | Receive execution coverage data |
-| `test-generation` | Output | Provide gaps for test targeting |
-| `quality-assessment` | Output | Report coverage metrics |
-| `code-intelligence` | Input | Receive code structure for risk scoring |
-| `learning-optimization` | Bidirectional | Share coverage patterns |
-
----
-
-## Performance Benchmarks (ADR-003)
-
-| Codebase Size | Traditional O(n) | v3 O(log n) | Improvement |
-|---------------|-----------------|-------------|-------------|
-| 1,000 files | 1,000 ops | 10 ops | 100x |
-| 10,000 files | 10,000 ops | 13 ops | 770x |
-| 100,000 files | 100,000 ops | 17 ops | 5,900x |
-
----
-
-*This shard is enforced by @claude-flow/guidance governance system.*
+# Coverage Analysis Domain Shard
+
+**Domain**: coverage-analysis
+**Version**: 1.0.0
+**Last Updated**: 2026-02-03
+**Parent Constitution**: `.claude/guidance/constitution.md`
+
+---
+
+## Domain Rules
+
+1. **Sublinear Algorithm Mandate**: Coverage gap detection MUST use the O(log n) HNSW-based SublinearCoverageAnalyzer for codebases > 1000 files. Linear scan is prohibited at scale.
+
+2. **Real Data Only**: Coverage reports MUST be derived from actual test execution results, not estimated or synthesized data.
+
+3. **Risk-Weighted Prioritization**: Coverage gaps MUST be prioritized by risk score (complexity, change frequency, defect history), not just coverage percentage.
+
+4. **Trend Accuracy**: Coverage trend analysis MUST use at least 3 historical data points; single-point trends are invalid.
+
+5. **Embedding Freshness**: Coverage embeddings MUST be regenerated when source code changes exceed the staleness threshold (default: 7 days or 100+ file changes).
+
+6. **Gap Verification**: Identified coverage gaps MUST be verified against the actual codebase before generating test suggestions.
+
+---
+
+## Quality Thresholds
+
+| Metric | Minimum | Target | Critical |
+|--------|---------|--------|----------|
+| Coverage Score | 0.6 | 0.8 | < 0.4 |
+| Confidence | 0.7 | 0.9 | < 0.5 |
+| Gap Detection Accuracy | 0.8 | 0.95 | < 0.6 |
+| Risk Scoring Accuracy | 0.7 | 0.85 | < 0.5 |
+| HNSW Query Efficiency | O(log n) | O(log n) | O(n) |
+
+---
+
+## Invariants
+
+```
+INVARIANT sublinear_at_scale:
+  FOR ALL analysis IN coverage_analyses:
+    IF analysis.codebase_size > 1000 THEN
+      analysis.algorithm = 'HNSW_SUBLINEAR' AND
+      analysis.complexity <= O(log(analysis.codebase_size))
+```
+
+```
+INVARIANT real_coverage_data:
+  FOR ALL report IN coverage_reports:
+    EXISTS execution_source WHERE
+      execution_source.report_id = report.id AND
+      execution_source.type IN ['jest', 'vitest', 'nyc', 'c8'] AND
+      execution_source.timestamp IS NOT NULL
+```
+
+```
+INVARIANT trend_minimum_points:
+  FOR ALL trend IN coverage_trends:
+    trend.data_points.length >= 3
+```
+
+```
+INVARIANT embedding_freshness:
+  FOR ALL embedding IN coverage_embeddings:
+    (NOW() - embedding.created_at) < STALENESS_THRESHOLD OR
+    embedding.regeneration_scheduled = true
+```
+
+---
+
+## Patterns
+
+**Domain Source**: `v3/src/domains/coverage-analysis/`
+
+| Pattern | Location | Description |
+|---------|----------|-------------|
+| Coverage Analyzer Service | `services/coverage-analyzer.ts` | Core coverage analysis |
+| Gap Detector Service | `services/gap-detector.ts` | Coverage gap identification |
+| Risk Scorer Service | `services/risk-scorer.ts` | Multi-factor risk scoring |
+| HNSW Index | `services/hnsw-index.ts` | O(log n) vector indexing |
+| Coverage Embedder | `services/coverage-embedder.ts` | Code-to-vector embedding |
+| Sublinear Analyzer | `services/sublinear-analyzer.ts` | ADR-003 sublinear implementation |
+
+**ADR Reference**: ADR-003 defines sublinear algorithm requirements.
+
+---
+
+## Agent Constraints
+
+| Role | Agent ID | Permissions |
+|------|----------|-------------|
+| **Primary** | `qe-coverage-specialist` | Full analysis, gap detection, risk scoring |
+| **Secondary** | `qe-gap-detector` | Gap detection, test suggestions |
+| **Support** | `qe-test-architect` | Receive gaps, generate tests |
+| **Readonly** | `qe-quality-gate` | Coverage validation |
+
+**Forbidden Agents**: Agents without HNSW index access MUST NOT perform gap detection on large codebases.
+
+---
+
+## Escalation Triggers
+
+| Trigger | Severity | Action |
+|---------|----------|--------|
+| Coverage < 0.4 | CRITICAL | Escalate to Queen Coordinator, prioritize test generation |
+| O(n) algorithm used at scale | CRITICAL | Escalate, require algorithm fix |
+| Gap detection accuracy < 0.6 | HIGH | Escalate, recalibrate model |
+| Stale embeddings > 14 days | HIGH | Escalate, force regeneration |
+| Trend shows declining coverage | MEDIUM | Notify coordinator, generate report |
+| Risk scoring confidence < 0.5 | MEDIUM | Request additional data points |
+| Synthetic data detected | CRITICAL | Block report, escalate for investigation |
+
+---
+
+## Memory Namespace
+
+- **Namespace**: `qe-patterns/coverage-analysis`
+- **Retention**: 30 days with minimum 3 uses
+- **Contradiction Check**: Enabled
+
+---
+
+## Integration Points
+
+| Domain | Integration Type | Purpose |
+|--------|-----------------|---------|
+| `test-execution` | Input | Receive execution coverage data |
+| `test-generation` | Output | Provide gaps for test targeting |
+| `quality-assessment` | Output | Report coverage metrics |
+| `code-intelligence` | Input | Receive code structure for risk scoring |
+| `learning-optimization` | Bidirectional | Share coverage patterns |
+
+---
+
+## Performance Benchmarks (ADR-003)
+
+| Codebase Size | Traditional O(n) | v3 O(log n) | Improvement |
+|---------------|-----------------|-------------|-------------|
+| 1,000 files | 1,000 ops | 10 ops | 100x |
+| 10,000 files | 10,000 ops | 13 ops | 770x |
+| 100,000 files | 100,000 ops | 17 ops | 5,900x |
+
+---
+
+*This shard is enforced by @claude-flow/guidance governance system.*

package/assets/governance/shards/defect-intelligence.shard.md

@@ -1,182 +1,182 @@
-# Defect Intelligence Domain Shard
-
-**Domain**: defect-intelligence
-**Version**: 1.0.0
-**Last Updated**: 2026-02-03
-**Parent Constitution**: `.claude/guidance/constitution.md`
-
----
-
-## Domain Rules
-
-1. **ML Model Transparency**: Defect predictions MUST include confidence scores and feature importance explanations; black-box predictions without explainability are prohibited.
-
-2. **Historical Data Requirement**: Defect prediction models MUST be trained on at least 30 days of historical defect data before being used for production predictions.
-
-3. **Root Cause Verification**: Root cause analyses MUST be validated against actual fix data when available, with feedback loops to improve accuracy.
-
-4. **Pattern Learning Discipline**: Defect patterns MUST only be learned from confirmed defects (not suspected or predicted), with FlashAttention optimization where available.
-
-5. **Regression Risk Honesty**: Regression risk assessments MUST clearly distinguish between measured risk (from data) and estimated risk (from heuristics).
-
-6. **Cluster Quality**: Defect clustering MUST achieve minimum silhouette score for valid cluster formation; invalid clusters MUST NOT be reported as patterns.
-
----
-
-## Quality Thresholds
-
-| Metric | Minimum | Target | Critical |
-|--------|---------|--------|----------|
-| Prediction Accuracy | 0.7 | 0.85 | < 0.5 |
-| Confidence | 0.6 | 0.8 | < 0.4 |
-| Root Cause Accuracy | 0.6 | 0.8 | < 0.4 |
-| Pattern Match Rate | 0.5 | 0.7 | < 0.3 |
-| Cluster Silhouette Score | 0.3 | 0.5 | < 0.2 |
-| Model Freshness | < 7 days | < 3 days | > 14 days |
-
----
-
-## Invariants
-
-```
-INVARIANT prediction_explainability:
-  FOR ALL prediction IN defect_predictions:
-    prediction.confidence IS NOT NULL AND
-    prediction.feature_importance IS NOT NULL AND
-    prediction.feature_importance.length >= 3
-```
-
-```
-INVARIANT historical_data_minimum:
-  FOR ALL model IN active_models:
-    model.training_data_days >= 30 AND
-    model.training_samples >= 100
-```
-
-```
-INVARIANT root_cause_feedback:
-  FOR ALL rca IN root_cause_analyses:
-    IF EXISTS actual_fix WHERE actual_fix.defect_id = rca.defect_id THEN
-      rca.validated_against_fix = true
-```
-
-```
-INVARIANT confirmed_defect_learning:
-  FOR ALL pattern IN learned_patterns:
-    pattern.source_defect.status = 'confirmed'
-```
-
-```
-INVARIANT cluster_quality:
-  FOR ALL cluster IN defect_clusters:
-    cluster.silhouette_score >= 0.2 OR
-    cluster.marked_as_invalid = true
-```
-
----
-
-## Patterns
-
-**Domain Source**: `v3/src/domains/defect-intelligence/`
-
-| Pattern | Location | Description |
-|---------|----------|-------------|
-| Defect Predictor Service | `services/defect-predictor.ts` | ML-based prediction |
-| Pattern Learner Service | `services/pattern-learner.ts` | Defect pattern extraction |
-| Root Cause Analyzer Service | `services/root-cause-analyzer.ts` | RCA algorithms |
-| Defect Intelligence Coordinator | `coordinator.ts` | Workflow orchestration |
-
-**Key Interfaces**: `interfaces/index.ts` defines `PredictionResult`, `RootCauseAnalysis`, `DefectCluster`, and related types.
-
----
-
-## Agent Constraints
-
-| Role | Agent ID | Permissions |
-|------|----------|-------------|
-| **Primary** | `qe-defect-predictor` | Full prediction, model training |
-| **Secondary** | `qe-root-cause-analyzer` | RCA execution, pattern extraction |
-| **Support** | `qe-pattern-learner` | Pattern learning from confirmed defects |
-| **Readonly** | `qe-quality-gate` | Query predictions |
-
-**Forbidden Agents**: Agents MUST NOT modify prediction models without retraining validation.
-
----
-
-## Escalation Triggers
-
-| Trigger | Severity | Action |
-|---------|----------|--------|
-| Prediction accuracy < 0.5 | CRITICAL | Escalate to Queen Coordinator, retrain model |
-| Model stale > 14 days | CRITICAL | Force model refresh, escalate |
-| Root cause accuracy < 0.4 | HIGH | Escalate, request manual validation |
-| Cluster silhouette < 0.2 | HIGH | Invalidate clusters, recalibrate |
-| FlashAttention unavailable | MEDIUM | Fall back to standard attention, log |
-| Unconfirmed defect used for learning | HIGH | Revert pattern, escalate |
-| Feature importance missing | MEDIUM | Block prediction, request explanation |
-
----
-
-## Memory Namespace
-
-- **Namespace**: `qe-patterns/defect-intelligence`
-- **Retention**: 90 days (longer for validated patterns)
-- **Contradiction Check**: Enabled
-
----
-
-## Integration Points
-
-| Domain | Integration Type | Purpose |
-|--------|-----------------|---------|
-| `test-execution` | Input | Receive failure data |
-| `code-intelligence` | Input | Receive code structure for prediction |
-| `coverage-analysis` | Input | Receive coverage data for risk |
-| `quality-assessment` | Output | Report defect density |
-| `learning-optimization` | Bidirectional | Share validated patterns |
-
----
-
-## Model Metrics Schema
-
-```typescript
-interface ModelMetrics {
-  modelId: string;
-  version: string;
-  trainedAt: Date;
-  trainingDataDays: number;
-  trainingSamples: number;
-  accuracy: number;
-  precision: number;
-  recall: number;
-  f1Score: number;
-  flashAttentionEnabled: boolean;
-  lastValidation: Date;
-  validationAccuracy: number;
-}
-```
-
----
-
-## Prediction Output Schema
-
-```typescript
-interface DefectPrediction {
-  fileId: string;
-  probability: number;
-  confidence: number;
-  riskLevel: 'low' | 'medium' | 'high' | 'critical';
-  featureImportance: {
-    feature: string;
-    importance: number;
-    direction: 'increases_risk' | 'decreases_risk';
-  }[];
-  similarDefects: string[];
-  recommendedActions: string[];
-  dataSource: 'measured' | 'heuristic';
-}
-```
-
----
-
-*This shard is enforced by @claude-flow/guidance governance system.*
+# Defect Intelligence Domain Shard
+
+**Domain**: defect-intelligence
+**Version**: 1.0.0
+**Last Updated**: 2026-02-03
+**Parent Constitution**: `.claude/guidance/constitution.md`
+
+---
+
+## Domain Rules
+
+1. **ML Model Transparency**: Defect predictions MUST include confidence scores and feature importance explanations; black-box predictions without explainability are prohibited.
+
+2. **Historical Data Requirement**: Defect prediction models MUST be trained on at least 30 days of historical defect data before being used for production predictions.
+
+3. **Root Cause Verification**: Root cause analyses MUST be validated against actual fix data when available, with feedback loops to improve accuracy.
+
+4. **Pattern Learning Discipline**: Defect patterns MUST only be learned from confirmed defects (not suspected or predicted), with FlashAttention optimization where available.
+
+5. **Regression Risk Honesty**: Regression risk assessments MUST clearly distinguish between measured risk (from data) and estimated risk (from heuristics).
+
+6. **Cluster Quality**: Defect clustering MUST achieve minimum silhouette score for valid cluster formation; invalid clusters MUST NOT be reported as patterns.
+
+---
+
+## Quality Thresholds
+
+| Metric | Minimum | Target | Critical |
+|--------|---------|--------|----------|
+| Prediction Accuracy | 0.7 | 0.85 | < 0.5 |
+| Confidence | 0.6 | 0.8 | < 0.4 |
+| Root Cause Accuracy | 0.6 | 0.8 | < 0.4 |
+| Pattern Match Rate | 0.5 | 0.7 | < 0.3 |
+| Cluster Silhouette Score | 0.3 | 0.5 | < 0.2 |
+| Model Freshness | < 7 days | < 3 days | > 14 days |
+
+---
+
+## Invariants
+
+```
+INVARIANT prediction_explainability:
+  FOR ALL prediction IN defect_predictions:
+    prediction.confidence IS NOT NULL AND
+    prediction.feature_importance IS NOT NULL AND
+    prediction.feature_importance.length >= 3
+```
+
+```
+INVARIANT historical_data_minimum:
+  FOR ALL model IN active_models:
+    model.training_data_days >= 30 AND
+    model.training_samples >= 100
+```
+
+```
+INVARIANT root_cause_feedback:
+  FOR ALL rca IN root_cause_analyses:
+    IF EXISTS actual_fix WHERE actual_fix.defect_id = rca.defect_id THEN
+      rca.validated_against_fix = true
+```
+
+```
+INVARIANT confirmed_defect_learning:
+  FOR ALL pattern IN learned_patterns:
+    pattern.source_defect.status = 'confirmed'
+```
+
+```
+INVARIANT cluster_quality:
+  FOR ALL cluster IN defect_clusters:
+    cluster.silhouette_score >= 0.2 OR
+    cluster.marked_as_invalid = true
+```
+
+---
+
+## Patterns
+
+**Domain Source**: `v3/src/domains/defect-intelligence/`
+
+| Pattern | Location | Description |
+|---------|----------|-------------|
+| Defect Predictor Service | `services/defect-predictor.ts` | ML-based prediction |
+| Pattern Learner Service | `services/pattern-learner.ts` | Defect pattern extraction |
+| Root Cause Analyzer Service | `services/root-cause-analyzer.ts` | RCA algorithms |
+| Defect Intelligence Coordinator | `coordinator.ts` | Workflow orchestration |
+
+**Key Interfaces**: `interfaces/index.ts` defines `PredictionResult`, `RootCauseAnalysis`, `DefectCluster`, and related types.
+
+---
+
+## Agent Constraints
+
+| Role | Agent ID | Permissions |
+|------|----------|-------------|
+| **Primary** | `qe-defect-predictor` | Full prediction, model training |
+| **Secondary** | `qe-root-cause-analyzer` | RCA execution, pattern extraction |
+| **Support** | `qe-pattern-learner` | Pattern learning from confirmed defects |
+| **Readonly** | `qe-quality-gate` | Query predictions |
+
+**Forbidden Agents**: Agents MUST NOT modify prediction models without retraining validation.
+
+---
+
+## Escalation Triggers
+
+| Trigger | Severity | Action |
+|---------|----------|--------|
+| Prediction accuracy < 0.5 | CRITICAL | Escalate to Queen Coordinator, retrain model |
+| Model stale > 14 days | CRITICAL | Force model refresh, escalate |
+| Root cause accuracy < 0.4 | HIGH | Escalate, request manual validation |
+| Cluster silhouette < 0.2 | HIGH | Invalidate clusters, recalibrate |
+| FlashAttention unavailable | MEDIUM | Fall back to standard attention, log |
+| Unconfirmed defect used for learning | HIGH | Revert pattern, escalate |
+| Feature importance missing | MEDIUM | Block prediction, request explanation |
+
+---
+
+## Memory Namespace
+
+- **Namespace**: `qe-patterns/defect-intelligence`
+- **Retention**: 90 days (longer for validated patterns)
+- **Contradiction Check**: Enabled
+
+---
+
+## Integration Points
+
+| Domain | Integration Type | Purpose |
+|--------|-----------------|---------|
+| `test-execution` | Input | Receive failure data |
+| `code-intelligence` | Input | Receive code structure for prediction |
+| `coverage-analysis` | Input | Receive coverage data for risk |
+| `quality-assessment` | Output | Report defect density |
+| `learning-optimization` | Bidirectional | Share validated patterns |
+
+---
+
+## Model Metrics Schema
+
+```typescript
+interface ModelMetrics {
+  modelId: string;
+  version: string;
+  trainedAt: Date;
+  trainingDataDays: number;
+  trainingSamples: number;
+  accuracy: number;
+  precision: number;
+  recall: number;
+  f1Score: number;
+  flashAttentionEnabled: boolean;
+  lastValidation: Date;
+  validationAccuracy: number;
+}
+```
+
+---
+
+## Prediction Output Schema
+
+```typescript
+interface DefectPrediction {
+  fileId: string;
+  probability: number;
+  confidence: number;
+  riskLevel: 'low' | 'medium' | 'high' | 'critical';
+  featureImportance: {
+    feature: string;
+    importance: number;
+    direction: 'increases_risk' | 'decreases_risk';
+  }[];
+  similarDefects: string[];
+  recommendedActions: string[];
+  dataSource: 'measured' | 'heuristic';
+}
+```
+
+---
+
+*This shard is enforced by @claude-flow/guidance governance system.*