agentic-qe 3.15.5 → 3.15.6

package/dist/domains/quality-assessment/coordinator-rl-integration.d.ts

@@ -11,6 +11,20 @@ import { PersistentSONAEngine } from '../../integrations/ruvector/sona-persisten
 import { QEFlashAttention } from '../../integrations/ruvector/wrappers';
 import type { GateEvaluationRequest, GateResult, QualityAnalysisRequest, QualityReport, QualityMetrics } from './interfaces';
 import type { DreamCycleCompletedPayload } from '../../shared/events/domain-events';
+import type { QualityScore } from '../../shared/types';
+/**
+ * Score features with unmeasured (-1) fields masked to 0, followed by one
+ * presence flag per field (1 = measured, 0 = not), so a learner can tell
+ * "unmeasured" apart from a measured 0.
+ */
+export declare function maskedScoreFeatures(score: QualityScore, scale?: number): number[];
+/**
+ * True when an analysis report has no verdict to learn from: a requested
+ * metric was not measured, or nothing was measured at all.
+ */
+export declare function isInsufficientQualityReport(report: QualityReport): boolean;
+/** True when a gate request carries any unmeasured (negative or non-finite) metric. */
+export declare function hasUnmeasuredGateMetrics(metrics: QualityMetrics): boolean;
 /**
  * RL-trained thresholds result
  */

package/dist/domains/quality-assessment/coordinator-rl-integration.js

@@ -9,6 +9,39 @@ import { toErrorMessage } from '../../shared/error-utils.js';
 import { ActorCriticAlgorithm } from '../../integrations/rl-suite/algorithms/actor-critic.js';
 import { createPersistentSONAEngine } from '../../integrations/ruvector/sona-persistence.js';
 import { createQEFlashAttention, } from '../../integrations/ruvector/wrappers.js';
+import { isMeasuredMetricValue } from './evidence-sufficiency.js';
+// ============================================================================
+// #1002: unmeasured values never reach a learner as numbers
+// ============================================================================
+/** Score fields in the fixed order every quality feature vector uses. */
+const SCORE_FIELDS = ['overall', 'coverage', 'complexity', 'maintainability', 'security'];
+/**
+ * Score features with unmeasured (-1) fields masked to 0, followed by one
+ * presence flag per field (1 = measured, 0 = not), so a learner can tell
+ * "unmeasured" apart from a measured 0.
+ */
+export function maskedScoreFeatures(score, scale = 1) {
+    const values = SCORE_FIELDS.map((field) => score[field]);
+    return [
+        ...values.map((value) => (isMeasuredMetricValue(value) ? value / scale : 0)),
+        ...values.map((value) => (isMeasuredMetricValue(value) ? 1 : 0)),
+    ];
+}
+/** Score fields carrying the unmeasured sentinel. */
+function unmeasuredScoreFields(score) {
+    return SCORE_FIELDS.filter((field) => !isMeasuredMetricValue(score[field]));
+}
+/**
+ * True when an analysis report has no verdict to learn from: a requested
+ * metric was not measured, or nothing was measured at all.
+ */
+export function isInsufficientQualityReport(report) {
+    return (report.unmeasured?.length ?? 0) > 0 || !isMeasuredMetricValue(report.score.overall);
+}
+/** True when a gate request carries any unmeasured (negative or non-finite) metric. */
+export function hasUnmeasuredGateMetrics(metrics) {
+    return Object.values(metrics).some((value) => !isMeasuredMetricValue(value));
+}
 /**
  * Initialize Actor-Critic RL for quality gate threshold tuning
  */
@@ -74,6 +107,9 @@ export async function initializeFlashAttention() {
  * Use Actor-Critic RL to predict optimal quality gate thresholds
  */
 export async function tuneThresholdsWithRL(actorCritic, metrics) {
+    // #1002: never predict from unmeasured inputs; keep the canonical thresholds.
+    if (hasUnmeasuredGateMetrics(metrics))
+        return null;
     try {
         const state = {
             id: `quality-state-${Date.now()}`,
@@ -129,6 +165,9 @@ export function applyActionToThresholds(thresholds, action) {
  * Train Actor-Critic with quality gate evaluation results
  */
 export async function trainActorCritic(actorCritic, request, result) {
+    // #1002: an experience built from unmeasured inputs teaches the critic fake data.
+    if (hasUnmeasuredGateMetrics(request.metrics))
+        return;
     try {
         const state = {
             id: `quality-state-${Date.now()}`,
@@ -177,6 +216,9 @@ export async function trainActorCritic(actorCritic, request, result) {
  * Store quality gate pattern in SONA for learning
  */
 export async function storeQualityPattern(qesona, request, result, domainName) {
+    // #1002: no gate pattern from unmeasured inputs.
+    if (hasUnmeasuredGateMetrics(request.metrics))
+        return;
     try {
         const state = {
             id: `quality-state-${Date.now()}`,
@@ -212,14 +254,15 @@ export async function storeQualityPattern(qesona, request, result, domainName) {
  * Store quality analysis pattern in SONA
  */
 export async function storeQualityAnalysisPattern(qesona, request, report, domainName) {
+    // #1002: an insufficient-evidence run has no verdict — neither a success
+    // nor a failure pattern may be recorded from it.
+    if (isInsufficientQualityReport(report))
+        return;
     try {
         const state = {
             id: `quality-analysis-${Date.now()}`,
             features: [
-                report.score.overall,
-                report.score.coverage,
-                report.score.complexity,
-                report.score.maintainability,
+                ...maskedScoreFeatures(report.score),
                 report.metrics.length,
                 request.sourceFiles.length,
             ],
@@ -235,6 +278,8 @@ export async function storeQualityAnalysisPattern(qesona, request, report, domai
         }, 'quality-assessment', domainName, {
             sourceFileCount: request.sourceFiles.length,
             recommendationCount: report.recommendations.length,
+            // Score fields outside the requested scope, masked to 0 in features.
+            unmeasuredScoreFields: unmeasuredScoreFields(report.score),
         });
     }
     catch (error) {
@@ -248,12 +293,8 @@ export async function enhanceWithSimilarityPatterns(report, flashAttention, qeso
     try {
         const state = {
             id: `similarity-search-${Date.now()}`,
-            features: [
-                report.score.overall,
-                report.score.coverage,
-                report.score.complexity,
-                report.score.maintainability,
-            ],
+            // #1002: -1 (unmeasured) is masked, never matched as a value.
+            features: maskedScoreFeatures(report.score),
         };
         const adaptation = await qesona.adaptPattern(state, 'quality-assessment', domainName);
         if (!adaptation.success || !adaptation.pattern) {
@@ -286,13 +327,10 @@ export async function enhanceWithSimilarityPatterns(report, flashAttention, qeso
  * Create embedding from quality metrics for similarity search
  */
 export function createMetricsEmbedding(report) {
+    // #1002: unmeasured score fields are masked (was security -1 / 100 = -0.01).
     const features = [
-        report.score.overall / 100,
-        report.score.coverage / 100,
-        report.score.complexity / 100,
-        report.score.maintainability / 100,
-        report.score.security / 100,
-        ...report.metrics.map(m => m.value / 100),
+        ...maskedScoreFeatures(report.score, 100),
+        ...report.metrics.map(m => (isMeasuredMetricValue(m.value) ? m.value / 100 : 0)),
     ];
     while (features.length < 384) {
         features.push(0);

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

@@ -244,8 +244,10 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
             }
             // Success path
             this.completeWorkflow(workflowId);
-            // Three-loop protocol: instantAdapt must precede recordOutcome
-            if (isSONAThreeLoopEnabled() && this.qesona?.isThreeLoopEnabled()) {
+            // Three-loop protocol: instantAdapt must precede recordOutcome.
+            // #1002: unmeasured (-1) gate inputs are never fed to the learner.
+            if (isSONAThreeLoopEnabled() && this.qesona?.isThreeLoopEnabled()
+                && !RLIntegration.hasUnmeasuredGateMetrics(effectiveRequest.metrics)) {
                 const m = effectiveRequest.metrics;
                 this.qesona.instantAdapt([
                     m.coverage / 100,
@@ -384,8 +386,10 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
                     result.value = enhanced;
                 }
             }
+            // #1002: an insufficient-evidence run has no verdict to learn from.
+            const learnable = !RLIntegration.isInsufficientQualityReport(result.value);
             // Three-loop protocol: instantAdapt must precede recordOutcome
-            if (isSONAThreeLoopEnabled() && this.qesona?.isThreeLoopEnabled()) {
+            if (learnable && isSONAThreeLoopEnabled() && this.qesona?.isThreeLoopEnabled()) {
                 const score = result.value.score;
                 this.qesona.instantAdapt([
                     score.overall / 100,
@@ -405,12 +409,12 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
                 }
                 catch { /* must not break main flow */ }
             }
-            // Store quality pattern in SONA
+            // Store quality pattern in SONA (skipped inside for insufficient evidence)
             if (this.config.enableSONAPatternLearning && this.qesona) {
                 await this.storeQualityAnalysisPattern(request, result.value);
             }
-            // Auto-trigger gate evaluation if enabled
-            if (this.config.enableAutoGating && result.value.score.overall < 70) {
+            // Auto-trigger gate evaluation if enabled (-1 = not measured, not a low score)
+            if (this.config.enableAutoGating && result.value.score.overall >= 0 && result.value.score.overall < 70) {
                 // Store for downstream consumption
                 await this.memory.set(`quality-assessment:auto-gate:${workflowId}`, { score: result.value.score, recommendations: result.value.recommendations }, { namespace: 'quality-assessment', ttl: 3600 });
             }

package/dist/domains/quality-assessment/coverage-report-event.d.ts

@@ -1,25 +1,49 @@
 /**
- * Validation of `coverage-analysis.CoverageReportCreated` payloads before the
- * quality-assessment domain stores them as `coverage:latest` (#1008).
+ * Validation of measured coverage records (#1008, #1014, #1015).
  *
- * Only a report its producer explicitly marked `measured: true`, carrying
+ * Used for `coverage-analysis.CoverageReportCreated` payloads before the
+ * quality-assessment domain stores them as `coverage:latest`, and by every
+ * reader of the stored records (`coverage:latest`, `coverage:previous`,
+ * `coverage:file:*`).
+ *
+ * Only a record its producer explicitly marked `measured: true`, carrying
  * finite coverage figures, is coverage evidence. Anything else — a static
- * estimate, a legacy event without provenance, or a look-alike event with no
- * coverage figures at all — is ignored rather than written as zeros.
+ * estimate, a legacy record without provenance (written by <= 3.15.4, or the
+ * `{"files":0}` bridge echo removed in #1013), or a look-alike with no coverage
+ * figures at all — is ignored rather than read as a measurement or as zeros.
  */
 /** The `coverage:latest` record written from a measured coverage report. */
 export interface MeasuredCoverageSummary {
     line: number;
-    branch: number;
-    function: number;
-    statement: number;
+    /** `null` = the report collected no branch data (not 0%, #1015). */
+    branch: number | null;
+    /** `null` = the report collected no function data (not 0%, #1015). */
+    function: number | null;
+    /** `null` = the report collected no statement data (lcov, Cobertura; #1027). */
+    statement: number | null;
     files: number;
     /** Provenance stamp: this record came from instrumented coverage. */
     measured: true;
+    /** Outcome of the test run behind the record, when known (#1027 N4). */
+    runStatus?: 'passed' | 'failed';
+}
+/** A per-file `coverage:file:<path>` record written from measured coverage. */
+export interface MeasuredFileCoverage {
+    line: number;
+    branch: number | null;
+    function: number | null;
+    statement: number | null;
+    measured: true;
 }
 /**
  * Return the measured summary to store, or `null` when the payload is not
  * measured coverage evidence.
  */
 export declare function measuredCoverageSummary(payload: unknown): MeasuredCoverageSummary | null;
+/**
+ * Return a stored per-file coverage record when it is measured evidence, or
+ * `null` (#1014): legacy unstamped `coverage:file:*` records — static
+ * estimates written by <= 3.15.4 never expire — must not be read as coverage.
+ */
+export declare function measuredFileCoverage(record: unknown): MeasuredFileCoverage | null;
 //# sourceMappingURL=coverage-report-event.d.ts.map

package/dist/domains/quality-assessment/coverage-report-event.js

@@ -1,13 +1,20 @@
 /**
- * Validation of `coverage-analysis.CoverageReportCreated` payloads before the
- * quality-assessment domain stores them as `coverage:latest` (#1008).
+ * Validation of measured coverage records (#1008, #1014, #1015).
  *
- * Only a report its producer explicitly marked `measured: true`, carrying
+ * Used for `coverage-analysis.CoverageReportCreated` payloads before the
+ * quality-assessment domain stores them as `coverage:latest`, and by every
+ * reader of the stored records (`coverage:latest`, `coverage:previous`,
+ * `coverage:file:*`).
+ *
+ * Only a record its producer explicitly marked `measured: true`, carrying
  * finite coverage figures, is coverage evidence. Anything else — a static
- * estimate, a legacy event without provenance, or a look-alike event with no
- * coverage figures at all — is ignored rather than written as zeros.
+ * estimate, a legacy record without provenance (written by <= 3.15.4, or the
+ * `{"files":0}` bridge echo removed in #1013), or a look-alike with no coverage
+ * figures at all — is ignored rather than read as a measurement or as zeros.
  */
 const isPercent = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 100;
+/** A percentage, or `null` for a metric that was not collected. */
+const isPercentOrNull = (v) => v === null || isPercent(v);
 /**
  * Return the measured summary to store, or `null` when the payload is not
  * measured coverage evidence.
@@ -18,7 +25,7 @@ export function measuredCoverageSummary(payload) {
     const p = payload;
     if (p.measured !== true)
         return null;
-    if (!isPercent(p.line) || !isPercent(p.branch) || !isPercent(p.function) || !isPercent(p.statement)) {
+    if (!isPercent(p.line) || !isPercentOrNull(p.statement) || !isPercentOrNull(p.branch) || !isPercentOrNull(p.function)) {
         return null;
     }
     const files = typeof p.files === 'number' && Number.isInteger(p.files) && p.files >= 0 ? p.files : null;
@@ -31,6 +38,21 @@ export function measuredCoverageSummary(payload) {
         statement: p.statement,
         files,
         measured: true,
+        ...(p.runStatus === 'passed' || p.runStatus === 'failed' ? { runStatus: p.runStatus } : {}),
     };
 }
+/**
+ * Return a stored per-file coverage record when it is measured evidence, or
+ * `null` (#1014): legacy unstamped `coverage:file:*` records — static
+ * estimates written by <= 3.15.4 never expire — must not be read as coverage.
+ */
+export function measuredFileCoverage(record) {
+    if (!record || typeof record !== 'object')
+        return null;
+    const r = record;
+    if (r.measured !== true || !isPercent(r.line))
+        return null;
+    const opt = (v) => (isPercent(v) ? v : null);
+    return { line: r.line, branch: opt(r.branch), function: opt(r.function), statement: opt(r.statement), measured: true };
+}
 //# sourceMappingURL=coverage-report-event.js.map

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

@@ -12,5 +12,5 @@ export { DeploymentAdvisorService, type IDeploymentAdvisorService, type Deployme
 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/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/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,9 +39,31 @@ 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";
@@ -69,6 +105,16 @@ export declare function inspectQualityEvidence(memory: MemoryBackend, options?:
     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;

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,6 +80,34 @@ export async function writeQualityEvidence(memory, values, metadata) {
         });
     }
 }
+/**
+ * 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. */
@@ -141,6 +171,7 @@ export async function inspectQualityEvidence(memory, options = {}) {
     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,
@@ -148,13 +179,44 @@ export async function inspectQualityEvidence(memory, options = {}) {
         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)

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;