agentic-qe 3.15.4 → 3.15.6

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

@@ -0,0 +1,57 @@
+/**
+ * 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, type QualityThresholdOverrides } from './quality-evidence.js';
+/** `measured`: every requested metric has data. Otherwise no verdict may approve. */
+export type StaticEvidenceStatus = 'measured' | typeof INSUFFICIENT_EVIDENCE;
+/** Metric names the static quality analysis understands. */
+export declare const STATIC_QUALITY_METRICS: readonly ["coverage", "complexity", "maintainability", "duplication", "testability", "security"];
+/**
+ * #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 declare function resolveCoverageOverride(requested: number | undefined, configured: number | undefined): number | undefined;
+export interface MeasuredFailure {
+    metric: string;
+    value: number;
+    threshold: number;
+    direction: 'min' | 'max';
+}
+export interface EvidenceSufficiency {
+    evidenceStatus: StaticEvidenceStatus;
+    /** Requested metrics backed by measured data. */
+    measured: string[];
+    /** Requested metrics with no measured data (missing, `-1`, or non-finite). */
+    unmeasured: string[];
+    /** Share of requested metrics that were measured, in [0, 1], two decimals. */
+    confidence: number;
+}
+/** A metric value is measured only if it is a finite, non-negative number. */
+export declare function isMeasuredMetricValue(value: unknown): value is number;
+/**
+ * #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 declare function validateRequestedMetrics(metrics: unknown): string[];
+/**
+ * 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 declare function assessEvidenceSufficiency(requested: readonly string[], values: Readonly<Record<string, number | undefined>>): EvidenceSufficiency;
+/**
+ * #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 declare function findMeasuredFailures(measured: readonly string[], values: Readonly<Record<string, number | undefined>>, overrides?: QualityThresholdOverrides): MeasuredFailure[];
+/** Plain-language recommendation for one measured failure. */
+export declare function describeMeasuredFailure(failure: MeasuredFailure): string;
+//# sourceMappingURL=evidence-sufficiency.d.ts.map

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,8 +9,8 @@ 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';
+export type { QualityAssessmentAPI, GateEvaluationRequest, QualityAnalysisRequest, DeploymentRequest, ComplexityRequest, GateResult, GateCheck, QualityReport, UnmeasuredQualityMetric, ExcludedQualityFile, PartialQualityMetric, QualityMetricDetail, QualityTrend, Recommendation, DeploymentAdvice, ComplexityReport, FileComplexity, ComplexitySummary, ComplexityHotspot, QualityMetrics, GateThresholds, } from './interfaces';
 //# sourceMappingURL=index.d.ts.map

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/interfaces.d.ts

@@ -68,6 +68,11 @@ export interface QualityAnalysisRequest {
     sourceFiles: string[];
     includeMetrics: string[];
     compareBaseline?: string;
+    /**
+     * #1021: files the caller named explicitly. If one of them fails to read or
+     * parse, the affected metrics are unmeasured regardless of coverage of scope.
+     */
+    explicitFiles?: string[];
 }
 export interface QualityReport {
     score: QualityScore;
@@ -76,6 +81,43 @@ export interface QualityReport {
     recommendations: Recommendation[];
     /** ADR-051: Optional LLM-generated insights (when enableLLMInsights is true) */
     llmInsights?: LLMQualityInsights;
+    /**
+     * #1011: requested metrics that were NOT measured, with the reason. They are
+     * absent from `metrics` and -1 in `score`; never a fixed fallback value.
+     */
+    unmeasured?: UnmeasuredQualityMetric[];
+    /**
+     * #1021: files left out of the scope (binary, generated, minified, type
+     * declarations, refused by the reader's path policy). Metrics stay measured
+     * over the remaining files.
+     */
+    excluded?: ExcludedQualityFile[];
+    /**
+     * #1021: metrics measured over most, but not all, analysable files. Their
+     * value covers `analysedFiles` of `totalFiles`; `failed` lists the gaps.
+     */
+    partial?: PartialQualityMetric[];
+}
+/** #1021: a file excluded from static analysis, with the reason. */
+export interface ExcludedQualityFile {
+    file: string;
+    reason: string;
+}
+/** #1021: a metric measured over part of its scope. */
+export interface PartialQualityMetric {
+    metric: string;
+    analysedFiles: number;
+    totalFiles: number;
+    /** analysedFiles / totalFiles, three decimals, rounded down (never 1 while a file failed). */
+    coverageOfScope: number;
+    failed: ExcludedQualityFile[];
+}
+/** #1011: a requested metric the static analysis could not measure. */
+export interface UnmeasuredQualityMetric {
+    metric: string;
+    reason: string;
+    /** Files that could not be analysed, when the cause is file-specific. */
+    files?: string[];
 }
 /**
  * ADR-051: LLM-generated quality insights
@@ -140,13 +182,17 @@ export interface ComplexityReport {
     summary: ComplexitySummary;
     hotspots: ComplexityHotspot[];
 }
+/** Values are -1 when not measured (not requested, or the file could not be analysed). */
 export interface FileComplexity {
     path: string;
     cyclomatic: number;
     cognitive: number;
     maintainability: number;
     linesOfCode: number;
+    /** #1011: why this file's metrics are unmeasured (unreadable, binary, unparseable). */
+    unmeasuredReason?: string;
 }
+/** Averages over measured files only; -1 when no file was measured for that metric. */
 export interface ComplexitySummary {
     averageCyclomatic: number;
     averageCognitive: number;

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

@@ -10,6 +10,20 @@ export interface QualityEvidenceRecord {
     value: number;
     measuredAt: string;
     source: string;
+    /**
+     * The test run this figure came from, when it came from one (#1027 NB1).
+     * Coverage and testsPassing written from one run share the runId.
+     */
+    runId?: string;
+    /** Whether that run's tests passed (#1027 NB1). */
+    runStatus?: 'passed' | 'failed';
+}
+/** Metadata of an evidence write; `runId`/`runStatus` scope it to one test run. */
+export interface QualityEvidenceMetadata {
+    measuredAt: string;
+    source: string;
+    runId?: string;
+    runStatus?: 'passed' | 'failed';
 }
 export interface QualityThreshold {
     direction: 'min' | 'max';
@@ -25,17 +39,97 @@ export interface EvaluatedQualityCheck {
     direction: 'min' | 'max';
     severity: QualityThreshold['severity'];
 }
-export declare function writeQualityEvidence(memory: MemoryBackend, values: Partial<QualityEvidenceValues>, metadata: {
-    measuredAt: string;
+export declare function writeQualityEvidence(memory: MemoryBackend, values: Partial<QualityEvidenceValues>, metadata: QualityEvidenceMetadata): Promise<void>;
+/** Test counts of one run. */
+export interface TestRunCounts {
+    passed: number;
+    failed: number;
+    skipped?: number;
+}
+/**
+ * testsPassing as `aqe test execute` has always computed it: passed over all
+ * tests, skipped included; a run with no tests is 0 (#1027 NB1: one formula).
+ */
+export declare function testsPassingPercent(run: TestRunCounts): number;
+/**
+ * Record the evidence of ONE test run (#1027 NB1): its testsPassing and, when
+ * it measured coverage, its coverage — both stamped with the same runId and
+ * runStatus. The single writer for `aqe test execute`, test_execute_parallel
+ * (TestExecutorService) and the coverage auto-run, so coverage from a failing
+ * run can never sit next to a stale testsPassing from an earlier run.
+ */
+export declare function writeTestRunEvidence(memory: MemoryBackend, run: TestRunCounts & {
+    runId: string;
+}, options: {
     source: string;
+    coverage?: number;
+    measuredAt?: 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[];
+}>;
+/**
+ * #1028: the latest record of ONE metric when it is usable evidence — the same
+ * validation (schema, metric, finite value, source, fresh measuredAt) the gate
+ * applies — or `null`. Unlike {@link inspectQualityEvidence} it returns the
+ * record, so a reader can follow its `runId` to the run it came from.
+ */
+export declare function readQualityEvidenceRecord(memory: Pick<MemoryBackend, 'get'>, metric: QualityMetricName, options?: {
+    now?: number;
+    maxAgeMs?: number;
+}): Promise<QualityEvidenceRecord | null>;
 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

@@ -71,6 +71,8 @@ export async function writeQualityEvidence(memory, values, metadata) {
             value,
             measuredAt: metadata.measuredAt,
             source: metadata.source,
+            ...(metadata.runId ? { runId: metadata.runId } : {}),
+            ...(metadata.runStatus ? { runStatus: metadata.runStatus } : {}),
         };
         await memory.set(evidenceKey(metric), record, {
             namespace: QUALITY_EVIDENCE_NAMESPACE,
@@ -78,27 +80,169 @@ export async function writeQualityEvidence(memory, values, metadata) {
         });
     }
 }
-export async function loadQualityEvidence(memory, options = {}) {
+/**
+ * testsPassing as `aqe test execute` has always computed it: passed over all
+ * tests, skipped included; a run with no tests is 0 (#1027 NB1: one formula).
+ */
+export function testsPassingPercent(run) {
+    const total = run.passed + run.failed + (run.skipped ?? 0);
+    return total > 0 ? (run.passed / total) * 100 : 0;
+}
+/**
+ * Record the evidence of ONE test run (#1027 NB1): its testsPassing and, when
+ * it measured coverage, its coverage — both stamped with the same runId and
+ * runStatus. The single writer for `aqe test execute`, test_execute_parallel
+ * (TestExecutorService) and the coverage auto-run, so coverage from a failing
+ * run can never sit next to a stale testsPassing from an earlier run.
+ */
+export async function writeTestRunEvidence(memory, run, options) {
+    const runStatus = run.failed > 0 ? 'failed' : 'passed';
+    const metadata = {
+        measuredAt: options.measuredAt ?? new Date().toISOString(),
+        source: options.source,
+        runId: run.runId,
+        runStatus,
+    };
+    await writeQualityEvidence(memory, {
+        testsPassing: testsPassingPercent(run),
+        ...(typeof options.coverage === 'number' && Number.isFinite(options.coverage) ? { coverage: options.coverage } : {}),
+    }, metadata);
+}
+/** #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 = [];
+    const valid = {};
     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;
+            valid[metric] = record;
+        }
+        catch (error) {
+            problems.push({ metric, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    // #1027 NB1: coverage measured in a run whose tests FAILED is evidence only
+    // next to the testsPassing of that same run — never next to a stale figure
+    // from an earlier (passing) run, which would let the gate pass.
+    const coverage = valid.coverage;
+    if (coverage?.runStatus === 'failed' && (!coverage.runId || valid.testsPassing?.runId !== coverage.runId)) {
+        delete values.coverage;
+        problems.push({
+            metric: 'coverage',
+            reason: 'Measured coverage comes from a run with failing tests, but no testsPassing evidence '
+                + 'from that same run was recorded. Re-run the test suite.',
+        });
     }
+    return { values, problems };
+}
+/**
+ * #1028: the latest record of ONE metric when it is usable evidence — the same
+ * validation (schema, metric, finite value, source, fresh measuredAt) the gate
+ * applies — or `null`. Unlike {@link inspectQualityEvidence} it returns the
+ * record, so a reader can follow its `runId` to the run it came from.
+ */
+export async function readQualityEvidenceRecord(memory, metric, options = {}) {
+    const record = await memory.get(evidenceKey(metric), {
+        namespace: QUALITY_EVIDENCE_NAMESPACE,
+    });
+    try {
+        validateRecord(record, metric, options.now ?? Date.now(), options.maxAgeMs ?? DEFAULT_QUALITY_EVIDENCE_MAX_AGE_MS);
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
+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.d.ts

@@ -3,8 +3,9 @@
  * Comprehensive quality metrics analysis with trends and recommendations
  */
 import { Result, QualityScore } from '../../../shared/types';
+import { CodeMetricsAnalyzer } from '../../../shared/metrics';
 import { MemoryBackend } from '../../../kernel/interfaces';
-import { QualityAnalysisRequest, QualityReport, QualityMetricDetail, QualityTrend, ComplexityRequest, ComplexityReport, LLMQualityInsights } from '../interfaces';
+import { QualityAnalysisRequest, QualityReport, QualityMetricDetail, QualityTrend, ComplexityRequest, ComplexityReport, LLMQualityInsights, UnmeasuredQualityMetric } from '../interfaces';
 import type { HybridRouter } from '../../../shared/llm';
 /**
  * Interface for the quality analyzer service
@@ -49,7 +50,17 @@ export interface QualityAnalyzerDependencies {
     memory: MemoryBackend;
     /** ADR-051: Optional LLM router for AI-enhanced quality insights */
     llmRouter?: HybridRouter;
+    /** Code metrics analyzer (defaults to the shared instance). */
+    metricsAnalyzer?: CodeMetricsAnalyzer;
 }
+/**
+ * #1021: a parsed metric with read/parse failures is still evidence when at
+ * least this share of the analysable files (in-scope minus excluded) was
+ * analysed. Below it, the unseen files are too large a blind spot for an
+ * average to describe the target, so the metric is unmeasured. 95% keeps one
+ * failure in a 20-file scope acceptable but not one in 10.
+ */
+export declare const MIN_ANALYSED_SHARE = 0.95;
 export declare class QualityAnalyzerService implements IQualityAnalyzerService {
     private readonly config;
     private readonly metricsAnalyzer;
@@ -75,7 +86,7 @@ export declare class QualityAnalyzerService implements IQualityAnalyzerService {
      * Generate quality insights using LLM
      * Provides AI-powered explanation and prioritized recommendations
      */
-    generateQualityInsightsWithLLM(metrics: QualityMetricDetail[], score: QualityScore, codeContext?: string): Promise<LLMQualityInsights | null>;
+    generateQualityInsightsWithLLM(metrics: QualityMetricDetail[], score: QualityScore, codeContext?: string, unmeasured?: UnmeasuredQualityMetric[]): Promise<LLMQualityInsights | null>;
     /**
      * Build prompt for quality insights generation
      */
@@ -104,6 +115,16 @@ export declare class QualityAnalyzerService implements IQualityAnalyzerService {
      * Get quality trend for a specific metric
      */
     getQualityTrend(metric: string, days: number): Promise<Result<QualityTrend, Error>>;
+    /**
+     * Collect per-file metric values. #1011 / #1021:
+     * - excluded files (binary, generated, minified, declarations, refused by
+     *   reader policy) leave the scope with a reason;
+     * - failed files (unreadable, unparseable) make a parsed metric partial, or
+     *   unmeasured below MIN_ANALYSED_SHARE or when a failed file was named
+     *   explicitly;
+     * - failed duplication detection and missing coverage are unmeasured.
+     * Never a fixed fallback value.
+     */
     private collectFileMetrics;
     private getStoredCoverage;
     private aggregateMetrics;