agentic-qe 3.15.4 → 3.15.5

package/dist/domains/quality-assessment/evidence-sufficiency.js

@@ -0,0 +1,97 @@
+/**
+ * Evidence sufficiency for static quality analysis (#996).
+ *
+ * The static analyzer marks metrics it could not measure with the `-1`
+ * sentinel (or omits them). Such metrics must never be read as numbers that
+ * support a verdict: a pass computed without them is a pass on missing data.
+ */
+import { INSUFFICIENT_EVIDENCE, resolveQualityThresholds, } from './quality-evidence.js';
+/** Metric names the static quality analysis understands. */
+export const STATIC_QUALITY_METRICS = [
+    'coverage', 'complexity', 'maintainability', 'duplication', 'testability', 'security',
+];
+/**
+ * Static metrics that a measured value can fail on its own, mapped to the
+ * canonical gate metric whose effective threshold applies (by default
+ * coverage >= 80, duplication <= 5; see resolveQualityThresholds).
+ */
+const STATIC_TO_GATE_METRIC = {
+    coverage: 'coverage',
+    duplication: 'duplications',
+};
+/**
+ * #996: the coverage threshold that applies to a static assessment — the
+ * request's threshold, else the user-configured gate threshold, else the
+ * canonical default (undefined = use the default).
+ */
+export function resolveCoverageOverride(requested, configured) {
+    return requested ?? configured;
+}
+/** A metric value is measured only if it is a finite, non-negative number. */
+export function isMeasuredMetricValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+/**
+ * #996 (N3): `metrics` must be a non-empty string[] of known names. A bare
+ * string would otherwise be spread into characters. Returns the de-duplicated
+ * list, or throws a caller-facing validation error.
+ */
+export function validateRequestedMetrics(metrics) {
+    const known = STATIC_QUALITY_METRICS;
+    const message = `metrics must be a non-empty array of metric names (${known.join(', ')}).`;
+    if (!Array.isArray(metrics) || metrics.length === 0)
+        throw new Error(message);
+    const unknown = metrics.filter((m) => typeof m !== 'string' || !known.includes(m));
+    if (unknown.length > 0) {
+        throw new Error(`${message} Unknown: ${unknown.map((m) => JSON.stringify(m)).join(', ')}.`);
+    }
+    return [...new Set(metrics)];
+}
+/**
+ * Decide whether static analysis measured every requested metric.
+ *
+ * @param requested - metric names the caller asked to assess; when empty,
+ *   the measured values themselves define the scope.
+ * @param values - metric values produced by the analyzer (`-1` = unmeasured).
+ */
+export function assessEvidenceSufficiency(requested, values) {
+    const scope = requested.length > 0
+        ? [...new Set(requested)]
+        : Object.keys(values).filter((name) => isMeasuredMetricValue(values[name]));
+    const measured = scope.filter((name) => isMeasuredMetricValue(values[name]));
+    const unmeasured = scope.filter((name) => !isMeasuredMetricValue(values[name]));
+    const confidence = scope.length === 0
+        ? 0
+        : Math.round((measured.length / scope.length) * 100) / 100;
+    return {
+        evidenceStatus: unmeasured.length === 0 && measured.length > 0 ? 'measured' : INSUFFICIENT_EVIDENCE,
+        measured,
+        unmeasured,
+        confidence,
+    };
+}
+/**
+ * #996 (N2): measured metrics that already fail their own limit. Such a
+ * failure is conclusive — no unmeasured metric can turn it into a pass.
+ */
+export function findMeasuredFailures(measured, values, overrides = {}) {
+    const thresholds = resolveQualityThresholds(overrides);
+    const failures = [];
+    for (const metric of measured) {
+        const gateMetric = STATIC_TO_GATE_METRIC[metric];
+        const limit = gateMetric ? thresholds[gateMetric] : undefined;
+        const value = values[metric];
+        if (!limit || !isMeasuredMetricValue(value))
+            continue;
+        const fails = limit.direction === 'min' ? value < limit.value : value > limit.value;
+        if (fails)
+            failures.push({ metric, value, threshold: limit.value, direction: limit.direction });
+    }
+    return failures;
+}
+/** Plain-language recommendation for one measured failure. */
+export function describeMeasuredFailure(failure) {
+    const bound = failure.direction === 'min' ? 'at least' : 'at most';
+    return `${failure.metric} measured at ${failure.value} fails its threshold (${bound} ${failure.threshold}).`;
+}
+//# sourceMappingURL=evidence-sufficiency.js.map

package/dist/domains/quality-assessment/index.d.ts

@@ -9,7 +9,7 @@ export { QualityAssessmentCoordinator, type IQualityAssessmentCoordinator, type
 export { QualityGateService, type IQualityGateService, type QualityGateConfig, } from './services/quality-gate';
 export { QualityAnalyzerService, type IQualityAnalyzerService, type QualityAnalyzerConfig, } from './services/quality-analyzer';
 export { DeploymentAdvisorService, type IDeploymentAdvisorService, type DeploymentAdvisorConfig, type DeploymentAccuracy, } from './services/deployment-advisor';
-export { DEFAULT_QUALITY_EVIDENCE_MAX_AGE_MS, DEFAULT_QUALITY_THRESHOLDS, QUALITY_EVIDENCE_NAMESPACE, QUALITY_METRICS, evaluateQualityEvidence, loadQualityEvidence, writeQualityEvidence, type EvaluatedQualityCheck, type QualityEvidenceRecord, type QualityEvidenceValues, type QualityMetricName, type QualityThreshold, } from './quality-evidence.js';
+export { DEFAULT_QUALITY_EVIDENCE_MAX_AGE_MS, DEFAULT_QUALITY_THRESHOLDS, QUALITY_EVIDENCE_NAMESPACE, QUALITY_METRICS, INSUFFICIENT_EVIDENCE, InsufficientQualityEvidenceError, evaluateQualityEvidence, inspectQualityEvidence, loadQualityEvidence, writeQualityEvidence, type EvaluatedQualityCheck, type QualityEvidenceRecord, type QualityEvidenceValues, type QualityMetricName, type QualityThreshold, } from './quality-evidence.js';
 export { CoherenceGateService, createCoherenceGateService, type CoherenceGateResult, type CoherenceGateServiceConfig, } from './services/coherence-gate';
 export * from './coherence';
 export type { QualityAssessmentAPI, GateEvaluationRequest, QualityAnalysisRequest, DeploymentRequest, ComplexityRequest, GateResult, GateCheck, QualityReport, QualityMetricDetail, QualityTrend, Recommendation, DeploymentAdvice, ComplexityReport, FileComplexity, ComplexitySummary, ComplexityHotspot, QualityMetrics, GateThresholds, } from './interfaces';

package/dist/domains/quality-assessment/index.js

@@ -18,7 +18,7 @@ export { QualityAssessmentCoordinator, } from './coordinator.js';
 export { QualityGateService, } from './services/quality-gate.js';
 export { QualityAnalyzerService, } from './services/quality-analyzer.js';
 export { DeploymentAdvisorService, } from './services/deployment-advisor.js';
-export { DEFAULT_QUALITY_EVIDENCE_MAX_AGE_MS, DEFAULT_QUALITY_THRESHOLDS, QUALITY_EVIDENCE_NAMESPACE, QUALITY_METRICS, evaluateQualityEvidence, loadQualityEvidence, writeQualityEvidence, } from './quality-evidence.js';
+export { DEFAULT_QUALITY_EVIDENCE_MAX_AGE_MS, DEFAULT_QUALITY_THRESHOLDS, QUALITY_EVIDENCE_NAMESPACE, QUALITY_METRICS, INSUFFICIENT_EVIDENCE, InsufficientQualityEvidenceError, evaluateQualityEvidence, inspectQualityEvidence, loadQualityEvidence, writeQualityEvidence, } from './quality-evidence.js';
 // ============================================================================
 // Coherence-Gated Quality Gates (ADR-030)
 // ============================================================================

package/dist/domains/quality-assessment/plugin.js

@@ -8,6 +8,7 @@ import { QualityAssessmentCoordinator, } from './coordinator.js';
 import { QualityGateService, } from './services/quality-gate.js';
 import { QualityAnalyzerService, } from './services/quality-analyzer.js';
 import { toError } from '../../shared/error-utils.js';
+import { measuredCoverageSummary } from './coverage-report-event.js';
 import { DeploymentAdvisorService, } from './services/deployment-advisor.js';
 /**
  * Quality Assessment Domain Plugin
@@ -285,15 +286,14 @@ export class QualityAssessmentPlugin extends BaseDomainPlugin {
         }
     }
     async handleCoverageReport(event) {
-        const payload = event.payload;
+        // #1008: only a report explicitly marked measured is coverage evidence.
+        // Estimates and look-alike events with no coverage figures (e.g. bridged
+        // captured experiences) must never touch `coverage:latest`.
+        const summary = measuredCoverageSummary(event.payload);
+        if (!summary)
+            return;
         // Store under the canonical coverage key so quality-analyzer can read it
-        await this.memory.set('coverage:latest', {
-            line: payload.line,
-            branch: payload.branch,
-            function: payload.function,
-            statement: payload.statement,
-            files: 0,
-        }, { persist: true });
+        await this.memory.set('coverage:latest', summary, { persist: true });
     }
     async handleDefectPrediction(event) {
         const payload = event.payload;

package/dist/domains/quality-assessment/quality-evidence.d.ts

@@ -29,13 +29,61 @@ export declare function writeQualityEvidence(memory: MemoryBackend, values: Part
     measuredAt: string;
     source: string;
 }): Promise<void>;
+/** #996: the single status word for "a verdict cannot be reached on this evidence". */
+export declare const INSUFFICIENT_EVIDENCE: "insufficient-evidence";
+/** #996: one recommendation per unmeasured metric, naming what to run. */
+export declare function describeMissingMetrics(unmeasured: readonly string[]): string[];
+/** Why a canonical metric has no usable evidence. */
+export interface UnusableQualityEvidence {
+    metric: QualityMetricName;
+    reason: string;
+}
+/**
+ * #996: thrown when the measured gate cannot be evaluated. The message is the
+ * first problem found (unchanged wording); `unmeasured` names every metric
+ * whose record is absent, stale, future-dated or malformed.
+ */
+export declare class InsufficientQualityEvidenceError extends Error {
+    readonly status: "insufficient-evidence";
+    readonly unmeasured: QualityMetricName[];
+    readonly problems: UnusableQualityEvidence[];
+    constructor(problems: UnusableQualityEvidence[]);
+    /** Structured, non-passing description of the gate that could not run. */
+    toDetails(): {
+        passed: false;
+        status: typeof INSUFFICIENT_EVIDENCE;
+        evidenceStatus: typeof INSUFFICIENT_EVIDENCE;
+        unmeasured: QualityMetricName[];
+        gateEvaluated: false;
+        recommendations: string[];
+    };
+}
+/**
+ * Inspect every canonical metric with the same validation, collecting each
+ * absent, stale, future-dated or malformed record instead of stopping at the first.
+ */
+export declare function inspectQualityEvidence(memory: MemoryBackend, options?: {
+    now?: number;
+    maxAgeMs?: number;
+}): Promise<{
+    values: Partial<QualityEvidenceValues>;
+    problems: UnusableQualityEvidence[];
+}>;
 export declare function loadQualityEvidence(memory: MemoryBackend, options?: {
     now?: number;
     maxAgeMs?: number;
 }): Promise<QualityEvidenceValues>;
-export declare function evaluateQualityEvidence(values: QualityEvidenceValues, thresholds?: {
+/** Threshold overrides a caller or user configuration may apply to the canonical defaults. */
+export interface QualityThresholdOverrides {
     coverage?: number;
-}): {
+}
+/**
+ * The single source of effective quality thresholds: canonical defaults with
+ * any override applied. Used by the measured gate and by static analysis
+ * (#996) so the two never disagree.
+ */
+export declare function resolveQualityThresholds(overrides?: QualityThresholdOverrides): Record<QualityMetricName, QualityThreshold>;
+export declare function evaluateQualityEvidence(values: QualityEvidenceValues, thresholds?: QualityThresholdOverrides): {
     passed: boolean;
     checks: EvaluatedQualityCheck[];
     recommendations: string[];

package/dist/domains/quality-assessment/quality-evidence.js

@@ -78,27 +78,109 @@ export async function writeQualityEvidence(memory, values, metadata) {
         });
     }
 }
-export async function loadQualityEvidence(memory, options = {}) {
+/** #996: the single status word for "a verdict cannot be reached on this evidence". */
+export const INSUFFICIENT_EVIDENCE = 'insufficient-evidence';
+/** #996: what to run to measure a metric that has no usable evidence. */
+// Advice names only producers a user can actually run. Metrics with no
+// exposed producer say so instead of pointing at an unreachable tool.
+const NO_EXPOSED_PRODUCER = 'no MCP tool or CLI command records it yet, so supply it from your own measurement';
+const MISSING_METRIC_ADVICE = {
+    coverage: 'run the tests with coverage instrumentation enabled so measured line coverage is recorded '
+        + '(a static estimate is not measured coverage)',
+    testsPassing: 'run the test suite (test_execute_parallel, or `aqe test execute`)',
+    // The static analyzer has no security measurement; a scan reports findings separately.
+    security: 'static analysis never measures security; drop it from metrics and use '
+        + 'security_scan_comprehensive (or `aqe security`) for findings',
+    securityVulnerabilities: `a measured vulnerability count is required; ${NO_EXPOSED_PRODUCER}`,
+    criticalBugs: `a measured critical-bug count is required; ${NO_EXPOSED_PRODUCER}`,
+    codeSmells: `a measured code-smell count is required; ${NO_EXPOSED_PRODUCER}`,
+    technicalDebt: `a measured technical-debt ratio is required; ${NO_EXPOSED_PRODUCER}`,
+    duplications: `a measured duplication percentage is required; ${NO_EXPOSED_PRODUCER}`,
+    complexity: 'make sure the target contains readable TypeScript/JavaScript source the analyzer can parse',
+    maintainability: 'make sure the target contains readable TypeScript/JavaScript source the analyzer can parse',
+    testability: 'make sure the target contains readable TypeScript/JavaScript source the analyzer can parse',
+    duplication: 'make sure the target contains readable TypeScript/JavaScript source the analyzer can parse',
+};
+/** #996: one recommendation per unmeasured metric, naming what to run. */
+export function describeMissingMetrics(unmeasured) {
+    return unmeasured.map((metric) => `Insufficient evidence: ${metric} not measured — ${MISSING_METRIC_ADVICE[metric] ?? 'measure it'}.`);
+}
+/**
+ * #996: thrown when the measured gate cannot be evaluated. The message is the
+ * first problem found (unchanged wording); `unmeasured` names every metric
+ * whose record is absent, stale, future-dated or malformed.
+ */
+export class InsufficientQualityEvidenceError extends Error {
+    status = INSUFFICIENT_EVIDENCE;
+    unmeasured;
+    problems;
+    constructor(problems) {
+        super(problems[0]?.reason ?? 'Measured quality evidence is unavailable.');
+        this.name = 'InsufficientQualityEvidenceError';
+        this.problems = problems;
+        this.unmeasured = problems.map((p) => p.metric);
+    }
+    /** Structured, non-passing description of the gate that could not run. */
+    toDetails() {
+        return {
+            passed: false,
+            status: INSUFFICIENT_EVIDENCE,
+            evidenceStatus: INSUFFICIENT_EVIDENCE,
+            unmeasured: this.unmeasured,
+            gateEvaluated: false,
+            recommendations: describeMissingMetrics(this.unmeasured),
+        };
+    }
+}
+/**
+ * Inspect every canonical metric with the same validation, collecting each
+ * absent, stale, future-dated or malformed record instead of stopping at the first.
+ */
+export async function inspectQualityEvidence(memory, options = {}) {
     const now = options.now ?? Date.now();
     const maxAgeMs = options.maxAgeMs ?? DEFAULT_QUALITY_EVIDENCE_MAX_AGE_MS;
     const values = {};
+    const problems = [];
     for (const metric of QUALITY_METRICS) {
         const record = await memory.get(evidenceKey(metric), {
             namespace: QUALITY_EVIDENCE_NAMESPACE,
         });
-        validateRecord(record, metric, now, maxAgeMs);
-        values[metric] = record.value;
+        try {
+            validateRecord(record, metric, now, maxAgeMs);
+            values[metric] = record.value;
+        }
+        catch (error) {
+            problems.push({ metric, reason: error instanceof Error ? error.message : String(error) });
+        }
     }
+    return { values, problems };
+}
+export async function loadQualityEvidence(memory, options = {}) {
+    const { values, problems } = await inspectQualityEvidence(memory, options);
+    if (problems.length > 0)
+        throw new InsufficientQualityEvidenceError(problems);
     return values;
 }
-export function evaluateQualityEvidence(values, thresholds = {}) {
-    if (thresholds.coverage !== undefined && (!Number.isFinite(thresholds.coverage) || thresholds.coverage < 0 || thresholds.coverage > 100)) {
+/**
+ * The single source of effective quality thresholds: canonical defaults with
+ * any override applied. Used by the measured gate and by static analysis
+ * (#996) so the two never disagree.
+ */
+export function resolveQualityThresholds(overrides = {}) {
+    if (overrides.coverage !== undefined && (!Number.isFinite(overrides.coverage) || overrides.coverage < 0 || overrides.coverage > 100)) {
         throw new Error('Coverage quality threshold must be a finite number between 0 and 100.');
     }
+    return {
+        ...DEFAULT_QUALITY_THRESHOLDS,
+        ...(overrides.coverage !== undefined
+            ? { coverage: { ...DEFAULT_QUALITY_THRESHOLDS.coverage, value: overrides.coverage } }
+            : {}),
+    };
+}
+export function evaluateQualityEvidence(values, thresholds = {}) {
+    const effective = resolveQualityThresholds(thresholds);
     const checks = QUALITY_METRICS.map((name) => {
-        const threshold = name === 'coverage' && thresholds.coverage !== undefined
-            ? { ...DEFAULT_QUALITY_THRESHOLDS[name], value: thresholds.coverage }
-            : DEFAULT_QUALITY_THRESHOLDS[name];
+        const threshold = effective[name];
         const value = values[name];
         return {
             name,

package/dist/domains/quality-assessment/services/quality-analyzer.js

@@ -152,11 +152,13 @@ Focus on:
             prompt += `- **${metric.name}**: ${metric.value} (Rating: ${metric.rating}, Trend: ${metric.trend})\n`;
         }
         prompt += `\n`;
+        // #996: -1 means "not measured"; never present it to the model as a value.
+        const show = (value, unit = '') => (value >= 0 ? `${value}${unit}` : 'not measured');
         prompt += `### Score Breakdown:\n`;
-        prompt += `- Coverage: ${score.coverage}%\n`;
-        prompt += `- Complexity: ${score.complexity}\n`;
-        prompt += `- Maintainability: ${score.maintainability}\n`;
-        prompt += `- Security: ${score.security}\n\n`;
+        prompt += `- Coverage: ${show(score.coverage, '%')}\n`;
+        prompt += `- Complexity: ${show(score.complexity)}\n`;
+        prompt += `- Maintainability: ${show(score.maintainability)}\n`;
+        prompt += `- Security: ${show(score.security)}\n\n`;
         if (codeContext) {
             prompt += `### Code Context:\n\`\`\`\n${codeContext.slice(0, 2000)}\n\`\`\`\n\n`;
         }
@@ -480,13 +482,15 @@ Focus on:
         }
         const overall = totalWeight > 0 ? Math.round(weightedSum / totalWeight) : 0;
         // Use -1 to signal "no data available" rather than 0 which implies "0% coverage"
-        const coverageMetric = metrics.find((m) => m.name === 'coverage');
+        // (#996: the same holds for every score field — never fabricate a value).
+        const valueOf = (name) => metrics.find((m) => m.name === name)?.value ?? -1;
         return {
             overall,
-            coverage: coverageMetric ? coverageMetric.value : -1,
-            complexity: metrics.find((m) => m.name === 'complexity')?.value || 0,
-            maintainability: metrics.find((m) => m.name === 'maintainability')?.value || 0,
-            security: 85, // Placeholder - would come from security analysis
+            coverage: valueOf('coverage'),
+            complexity: valueOf('complexity'),
+            maintainability: valueOf('maintainability'),
+            // No security analysis runs here; -1 = not measured (was a fixed 85 placeholder).
+            security: -1,
         };
     }
     async generateTrends(currentMetrics, _compareBaseline) {