agentic-qe 3.15.4 → 3.15.5

package/dist/cli/utils/ci-output.js

@@ -209,10 +209,14 @@ export function coverageToMarkdown(result) {
     let md = `# Coverage Report\n\n`;
     md += `| Metric | Value | Status |\n`;
     md += `|--------|-------|--------|\n`;
-    md += `| Lines | ${result.summary.line}% | ${result.summary.line >= result.threshold ? '\u2705' : '\u274C'} |\n`;
-    md += `| Branches | ${result.summary.branch}% | ${result.summary.branch >= result.threshold ? '\u2705' : '\u274C'} |\n`;
-    md += `| Functions | ${result.summary.function}% | ${result.summary.function >= result.threshold ? '\u2705' : '\u274C'} |\n`;
-    md += `| Statements | ${result.summary.statement}% | ${result.summary.statement >= result.threshold ? '\u2705' : '\u274C'} |\n`;
+    // #995: an uncollected metric is "n/a", with no pass/fail mark — it is not 0%.
+    const row = (label, v) => v === null
+        ? `| ${label} | n/a (not collected) | \u2014 |\n`
+        : `| ${label} | ${v}% | ${v >= result.threshold ? '\u2705' : '\u274C'} |\n`;
+    md += row('Lines', result.summary.line);
+    md += row('Branches', result.summary.branch);
+    md += row('Functions', result.summary.function);
+    md += row('Statements', result.summary.statement);
     md += `\n**Threshold:** ${result.threshold}% \u2014 ${result.meetsThreshold ? '\u2705 Met' : '\u274C Not met'}\n`;
     if (result.gaps && result.gaps.length > 0) {
         md += `\n## Coverage Gaps\n\n`;
@@ -232,6 +236,19 @@ export function coverageToMarkdown(result) {
 }
 export function qualityGateToMarkdown(result) {
     let md = `# Quality Gate Report\n\n`;
+    if (result.evidenceStatus === 'insufficient-evidence') {
+        // #996: a gate that could not run is neither a pass nor a measured failure.
+        md += `**Result:** \u26A0\uFE0F INSUFFICIENT EVIDENCE \u2014 quality gate not evaluated\n`;
+        if (result.unmeasured && result.unmeasured.length > 0) {
+            md += `**Unmeasured:** ${result.unmeasured.join(', ')}\n`;
+        }
+        if (result.error)
+            md += `**Reason:** ${result.error}\n`;
+        if (result.recommendations && result.recommendations.length > 0) {
+            md += `\n## Recommendations\n\n${result.recommendations.map(rec => `- ${rec}`).join('\n')}\n`;
+        }
+        return md;
+    }
     md += `**Result:** ${result.passed ? '\u2705 PASSED' : '\u274C FAILED'}\n`;
     md += `**Score:** ${result.score}\n\n`;
     md += `## Checks\n\n`;

package/dist/cli/utils/coverage-data.d.ts

@@ -41,12 +41,19 @@ export interface CoverageData {
     };
     /** True if data came from real instrumented coverage (V8/istanbul) */
     instrumented: boolean;
+    /**
+     * Source files the instrumented report has no entry for (#995). These are
+     * UNMEASURED — excluded from the figures rather than counted as 0%.
+     */
+    unmeasuredFiles?: string[];
 }
 /**
  * Try to read real coverage data from a coverage-final.json file.
  * Returns null if no instrumented coverage is available.
  */
 export declare function readInstrumentedCoverage(projectRoot: string): Map<string, FileCoverage> | null;
+/** Aggregate per-file coverage into whole-number percentages. */
+export declare function summarizeCoverage(files: FileCoverage[]): CoverageData['summary'];
 /**
  * Build coverage data for the given source files.
  *

package/dist/cli/utils/coverage-data.js

@@ -161,6 +161,20 @@ function estimateFileCoverage(filePath, content) {
 // ============================================================================
 // Public API
 // ============================================================================
+/** Aggregate per-file coverage into whole-number percentages. */
+export function summarizeCoverage(files) {
+    const sum = (pick) => files.reduce((acc, f) => acc + pick(f), 0);
+    const safeDiv = (a, b) => b > 0 ? Math.round((a / b) * 100) : 0;
+    const totalLines = sum(f => f.lines.total);
+    const coveredLines = sum(f => f.lines.covered);
+    return {
+        line: safeDiv(coveredLines, totalLines),
+        branch: safeDiv(sum(f => f.branches.covered), sum(f => f.branches.total)),
+        function: safeDiv(sum(f => f.functions.covered), sum(f => f.functions.total)),
+        statement: safeDiv(coveredLines, totalLines),
+        files: files.length,
+    };
+}
 /**
  * Build coverage data for the given source files.
  *
@@ -174,6 +188,7 @@ export function buildCoverageData(sourceFiles, projectRoot) {
     // Try instrumented coverage first
     const instrumentedData = readInstrumentedCoverage(root);
     const files = [];
+    const unmeasuredFiles = [];
     let isInstrumented = false;
     if (instrumentedData && instrumentedData.size > 0) {
         isInstrumented = true;
@@ -187,18 +202,10 @@ export function buildCoverageData(sourceFiles, projectRoot) {
                 files.push({ ...match, path: filePath });
             }
             else {
-                // File exists in source but has no coverage data — 0% coverage
-                const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : '';
-                const totalLines = content.split('\n').length;
-                files.push({
-                    path: filePath,
-                    lines: { covered: 0, total: totalLines },
-                    branches: { covered: 0, total: 1 },
-                    functions: { covered: 0, total: 1 },
-                    statements: { covered: 0, total: totalLines },
-                    uncoveredLines: Array.from({ length: totalLines }, (_, i) => i + 1),
-                    uncoveredBranches: [],
-                });
+                // #995: the report has no entry for this file — the coverage run did
+                // not measure it. That is "unmeasured", not 0%: counting it as fully
+                // uncovered invented a figure nobody measured.
+                unmeasuredFiles.push(filePath);
             }
         }
     }
@@ -209,24 +216,11 @@ export function buildCoverageData(sourceFiles, projectRoot) {
             files.push(estimateFileCoverage(filePath, content));
         }
     }
-    // Compute summary
-    const totalLines = files.reduce((sum, f) => sum + f.lines.total, 0);
-    const coveredLines = files.reduce((sum, f) => sum + f.lines.covered, 0);
-    const totalBranches = files.reduce((sum, f) => sum + f.branches.total, 0);
-    const coveredBranches = files.reduce((sum, f) => sum + f.branches.covered, 0);
-    const totalFunctions = files.reduce((sum, f) => sum + f.functions.total, 0);
-    const coveredFunctions = files.reduce((sum, f) => sum + f.functions.covered, 0);
-    const safeDiv = (a, b) => b > 0 ? Math.round((a / b) * 100) : 0;
     return {
         files,
-        summary: {
-            line: safeDiv(coveredLines, totalLines),
-            branch: safeDiv(coveredBranches, totalBranches),
-            function: safeDiv(coveredFunctions, totalFunctions),
-            statement: safeDiv(coveredLines, totalLines),
-            files: files.length,
-        },
+        summary: summarizeCoverage(files),
         instrumented: isInstrumented,
+        ...(unmeasuredFiles.length > 0 ? { unmeasuredFiles } : {}),
     };
 }
 //# sourceMappingURL=coverage-data.js.map

package/dist/contracts/verdicts.d.ts

@@ -58,14 +58,28 @@ export interface ValidationResult {
 export declare function validateRiskDecision(value: unknown): ValidationResult;
 export declare function validateFindingVerdict(value: unknown): ValidationResult;
 export declare function validateCoverageGap(value: unknown): ValidationResult;
+/** #996: confidence cap for an approve that rests on static analysis alone (no gate). */
+export declare const STATIC_APPROVAL_CONFIDENCE = 0.7;
 /**
  * Derive a RiskDecision from a quality-gate outcome (quality_assess boundary).
  * Indeterminate gates (passed undefined) escalate rather than guess.
+ *
+ * #996: when key metrics are unmeasured the decision escalates with lowered
+ * confidence, whatever `passed` says — never approve on missing data. When
+ * `gateEvaluated` is false the rationale says plainly that no gate ran.
  */
 export declare function buildRiskDecisionFromQualityGate(input: {
     passed?: boolean;
     qualityScore?: number;
     recommendations?: string[];
+    /** Requested metrics that had no measured data. */
+    unmeasured?: string[];
+    /** Share of requested metrics that were measured, in [0, 1]. */
+    evidenceConfidence?: number;
+    /** False for static analysis: no quality gate was evaluated. */
+    gateEvaluated?: boolean;
+    /** Measured metrics that fail their own limit — conclusive, so the decision blocks. */
+    failedMetrics?: string[];
 }): RiskDecision;
 export declare const RISK_DECISION_SCHEMA: {
     readonly $schema: "http://json-schema.org/draft-07/schema#";

package/dist/contracts/verdicts.js

@@ -176,21 +176,62 @@ export function validateCoverageGap(value) {
 // ============================================================================
 // Builders — derive contract envelopes at MCP boundaries
 // ============================================================================
+/** #996: confidence cap for an approve that rests on static analysis alone (no gate). */
+export const STATIC_APPROVAL_CONFIDENCE = 0.7;
 /**
  * Derive a RiskDecision from a quality-gate outcome (quality_assess boundary).
  * Indeterminate gates (passed undefined) escalate rather than guess.
+ *
+ * #996: when key metrics are unmeasured the decision escalates with lowered
+ * confidence, whatever `passed` says — never approve on missing data. When
+ * `gateEvaluated` is false the rationale says plainly that no gate ran.
  */
 export function buildRiskDecisionFromQualityGate(input) {
-    const { passed, qualityScore, recommendations = [] } = input;
+    const { passed, qualityScore, recommendations = [], unmeasured = [], failedMetrics = [], gateEvaluated, } = input;
+    const noGate = gateEvaluated === false ? ' (no quality gate was evaluated)' : '';
+    const score = typeof qualityScore === 'number' ? ` with score ${qualityScore}` : '';
+    // A measured failure cannot be rescued by metrics that were never measured.
+    if (failedMetrics.length > 0) {
+        const missing = unmeasured.length > 0 ? `; also unmeasured: ${unmeasured.join(', ')}` : '';
+        return {
+            contract: 'risk-decision@1',
+            decision: 'block',
+            riskFactors: [
+                `failed: ${failedMetrics.join(', ')}`,
+                ...(unmeasured.length > 0 ? [`unmeasured: ${unmeasured.join(', ')}`] : []),
+                ...recommendations,
+            ].slice(0, 10),
+            confidence: 0.9,
+            rationale: `Measured ${failedMetrics.join(', ')} failed its threshold${missing}${noGate}`,
+        };
+    }
+    if (unmeasured.length > 0) {
+        const share = typeof input.evidenceConfidence === 'number' && Number.isFinite(input.evidenceConfidence)
+            ? Math.min(1, Math.max(0, input.evidenceConfidence))
+            : 0;
+        return {
+            contract: 'risk-decision@1',
+            decision: 'escalate',
+            riskFactors: [`unmeasured: ${unmeasured.join(', ')}`, ...recommendations].slice(0, 10),
+            confidence: Math.round(0.5 * share * 100) / 100,
+            rationale: `Insufficient evidence: ${unmeasured.join(', ')} not measured${noGate} — `
+                + 'measure the missing metrics or run the measured quality gate before deciding',
+        };
+    }
     const decision = passed === true ? 'approve' : passed === false ? 'block' : 'escalate';
+    const subject = gateEvaluated === false ? 'Static analysis' : 'Quality gate';
+    // #996 (N1): an approval no gate evaluated is weaker evidence than a gate pass.
+    const confidence = decision === 'escalate'
+        ? 0.5
+        : decision === 'approve' && gateEvaluated === false ? STATIC_APPROVAL_CONFIDENCE : 0.9;
     return {
         contract: 'risk-decision@1',
         decision,
         riskFactors: recommendations.slice(0, 10),
-        confidence: decision === 'escalate' ? 0.5 : 0.9,
+        confidence,
         rationale: decision === 'escalate'
             ? 'Quality gate outcome indeterminate — manual review required'
-            : `Quality gate ${passed ? 'passed' : 'failed'}${typeof qualityScore === 'number' ? ` with score ${qualityScore}` : ''}`,
+            : `${subject} ${passed ? 'passed' : 'failed'}${score}${noGate}`,
     };
 }
 // ============================================================================

package/dist/coordination/handlers/coverage-handlers.js

@@ -4,143 +4,141 @@
  * Extracted from task-executor.ts registerHandlers().
  * Covers: analyze-coverage
  */
-import * as fs from 'fs/promises';
-import * as path from 'path';
 import { ok, err } from '../../shared/types/index.js';
 import { toError } from '../../shared/error-utils.js';
-import { safeJsonParse } from '../../shared/safe-json.js';
-import { loadCoverageData } from './handler-utils.js';
-import { buildEstimatedCoverage, collectRustCoverage, isCoverageExecDisabled, isRustProject, isTestPath, } from './coverage-collection.js';
+import { buildEstimatedCoverage, collectRustCoverage, findCargoRoot, isCoverageExecDisabled, isRustProject, } from './coverage-collection.js';
+import { describeNoData, evaluateCoverageForTarget, isUnmeasured, resolveExistingCoverage, scopeCoverageToTarget, reconcileRecommendations, thresholdVerdict, } from './coverage-target.js';
+import { describeRunFailure, runJsCoverage } from './coverage-runner.js';
 /**
- * Try to produce a JS/TS coverage report by running the project's test runner.
- * Returns true if the runner completed (which does not guarantee a report was
- * written — the caller re-checks disk).
+ * How long the project's test runner may take before its process tree is
+ * killed. `AQE_COVERAGE_TIMEOUT_MS` overrides the 120s default.
  */
-async function tryRunJsCoverage(targetPath) {
-    // Running the project's test suite executes code from the analyzed repository
-    // (the tests themselves, plus npm lifecycle scripts via npx). Honor the
-    // opt-out before doing that.
-    if (isCoverageExecDisabled())
-        return false;
-    try {
-        const { execSync } = await import('child_process');
-        let coverageCmd = 'npx vitest run --coverage --reporter=json 2>/dev/null';
-        try {
-            const pkgContent = await fs.readFile(path.join(targetPath, 'package.json'), 'utf-8');
-            const pkg = safeJsonParse(pkgContent);
-            const deps = {
-                ...(pkg.devDependencies || {}),
-                ...(pkg.dependencies || {}),
-            };
-            if (deps['jest'] || deps['@jest/core']) {
-                coverageCmd = 'npx jest --coverage --json 2>/dev/null';
-            }
-            else if (deps['mocha'] || deps['nyc']) {
-                coverageCmd = 'npx nyc mocha 2>/dev/null';
-            }
-            // vitest is the default — covers vitest, @vitest/coverage-v8, etc.
-        }
-        catch {
-            // No package.json — use default vitest
-        }
-        execSync(coverageCmd, {
-            cwd: targetPath,
-            timeout: 120000,
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        return true;
-    }
-    catch {
-        // Test runner failed or not available.
-        return false;
-    }
+function coverageTimeoutMs(env = process.env) {
+    const parsed = Number.parseInt(env.AQE_COVERAGE_TIMEOUT_MS ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 120000;
 }
-/**
- * Narrow an instrumented report to production files only, recomputing the
- * aggregate from what survives.
- *
- * Returns `null` when the report contains no production files at all — the
- * caller must NOT fall back to the unfiltered set, because that reports the test
- * files' own coverage as the project's (#569's third contradiction).
- */
-function productionOnly(report, targetPath) {
-    const files = report.files.filter(f => !isTestPath(f.path, targetPath));
-    if (files.length === 0)
-        return null;
-    // Recompute rather than carrying the original summary: it was computed over
-    // the unfiltered set, so keeping it would blend test-file coverage into the
-    // production headline figure.
+/** Aggregate a file list into whole-number percentages. */
+function recomputeSummary(files) {
     const sum = (pick) => files.reduce((acc, f) => acc + pick(f), 0);
-    const pct = (covered, total) => total > 0 ? Math.round((covered / total) * 100) : 0;
+    const pct = (covered, total) => (total > 0 ? Math.round((covered / total) * 100) : 0);
     const totalLines = sum(f => f.lines.total);
     const coveredLines = sum(f => f.lines.covered);
-    const branchDataCollected = files.some(f => f.branches.total > 0);
-    const functionDataCollected = files.some(f => f.functions.total > 0);
     return {
-        data: {
-            files,
-            summary: {
-                line: pct(coveredLines, totalLines),
-                branch: pct(sum(f => f.branches.covered), sum(f => f.branches.total)),
-                function: pct(sum(f => f.functions.covered), sum(f => f.functions.total)),
-                statement: pct(coveredLines, totalLines),
-                files: files.length,
-            },
-        },
+        line: pct(coveredLines, totalLines),
+        branch: pct(sum(f => f.branches.covered), sum(f => f.branches.total)),
+        function: pct(sum(f => f.functions.covered), sum(f => f.functions.total)),
+        statement: pct(coveredLines, totalLines),
+        files: files.length,
+    };
+}
+/** An instrumented verdict as a collected result with honest provenance. */
+function instrumented(files) {
+    return {
+        data: { files, summary: recomputeSummary(files) },
         provenance: {
             method: 'instrumented-report',
             estimated: false,
-            branchDataCollected,
-            functionDataCollected,
+            branchDataCollected: files.some(f => f.branches.total > 0),
+            functionDataCollected: files.some(f => f.functions.total > 0),
             notes: [],
         },
     };
 }
+function fromEvaluation(evaluation, ranTests, projectRoot) {
+    return evaluation.status === 'measured'
+        ? { collected: instrumented(evaluation.files), ranTests, projectRoot }
+        : { collected: null, ranTests, noData: evaluation.reason, projectRoot };
+}
 /**
  * Collect coverage for a target, preferring real measurement over estimation
  * and always reporting which one happened (#569).
  *
+ * The target may be the project root, a subfolder or file inside it, or an
+ * existing coverage report (#995). Tooling always runs from the project root
+ * and the result is scoped back down to the target. The decision about what
+ * a report says for a target is shared with the CLI (`resolveExistingCoverage`
+ * / `evaluateCoverageForTarget`).
+ *
  * Cascade:
- *   1. an instrumented report already on disk (istanbul/lcov/cobertura)
+ *   0. the target IS a coverage report — parse it, run nothing
+ *   1. an instrumented report already on disk at the project root
  *   2. language-specific instrumentation we can run — `cargo llvm-cov` for Rust,
- *      the project's test runner for JS/TS
+ *      the project's test runner for JS/TS — writing to a temp dir
  *   3. static estimation, explicitly labelled `estimated: true`
  */
 async function collectCoverage(targetPath) {
-    const existing = await loadCoverageData(targetPath);
-    if (existing) {
-        const fromReport = productionOnly(existing, targetPath);
-        // A report whose only entries are test files yields NO production coverage.
-        // Falling back to the unfiltered set here would report the test files'
-        // own coverage as the project's — recreating #569's third contradiction
-        // (`tests/verifier_matrix.rs` analysed at 79.2% as if it were a target).
-        if (!fromReport)
-            return { collected: null, ranTests: false, testOnlyReport: true };
-        return { collected: fromReport, ranTests: false };
+    const existing = await resolveExistingCoverage(targetPath);
+    if (existing.status === 'target-missing') {
+        return { collected: null, ranTests: false, noData: 'target-missing', projectRoot: null };
+    }
+    if (existing.status === 'evaluated') {
+        return fromEvaluation(existing.evaluation, false, existing.projectRoot);
     }
+    const { target, projectRoot } = existing;
     // #569 work item 1: delegate to real instrumentation where available.
-    const rustProject = isRustProject(targetPath);
-    if (rustProject) {
-        const rust = await collectRustCoverage(targetPath);
-        if (rust)
-            return { collected: rust, ranTests: true };
+    if (isRustProject(target)) {
+        const rust = await collectRustCoverage(target);
+        if (rust) {
+            // cargo ran from the crate root; scope its crate-wide output to the target.
+            const crateRoot = findCargoRoot(target) ?? projectRoot;
+            const scoped = scopeCoverageToTarget(rust.data, crateRoot, target);
+            if (scoped.length === 0) {
+                return { collected: null, ranTests: true, noData: 'target-not-covered', projectRoot: crateRoot };
+            }
+            const collected = scoped.length === rust.data.files.length
+                ? rust
+                : { data: { files: scoped, summary: recomputeSummary(scoped) }, provenance: rust.provenance };
+            return { collected, ranTests: true, projectRoot: crateRoot };
+        }
         // This target is a Rust crate. Do not continue into the JS/TS runner:
         // `npx vitest --coverage` can still be available through the parent
         // process PATH and will write an empty report even though the crate has no
         // JavaScript tests. Treating that artifact as coverage hides the intended
         // Rust static-estimation fallback and mislabels the result.
-        return { collected: buildEstimatedCoverage(targetPath), ranTests: false };
+        return { collected: buildEstimatedCoverage(target), ranTests: false, projectRoot };
     }
-    const ranTests = await tryRunJsCoverage(targetPath);
-    const afterRun = await loadCoverageData(targetPath);
-    if (afterRun) {
-        const fromRun = productionOnly(afterRun, targetPath);
-        if (!fromRun)
-            return { collected: null, ranTests, testOnlyReport: true };
-        return { collected: fromRun, ranTests };
+    // Running the project's test suite executes code from the analyzed repository
+    // (the tests themselves, plus npm lifecycle scripts via npx). Honor the
+    // opt-out before doing that.
+    if (isCoverageExecDisabled()) {
+        return { collected: buildEstimatedCoverage(target), ranTests: false, projectRoot };
     }
-    return { collected: buildEstimatedCoverage(targetPath), ranTests };
+    const run = await runJsCoverage(projectRoot, { timeoutMs: coverageTimeoutMs() });
+    // An EMPTY report (`{}`) from a run that reported its tests means "the run
+    // instrumented nothing under the target" → unmeasured, never an estimate
+    // (#995 review BL2). An empty report from a run that crashed before
+    // reporting any tests is a crash, handled below.
+    const crashedEmpty = run.data !== null && run.data.files.length === 0 &&
+        run.numTotalTests === null && !run.exitedCleanly;
+    if ((run.data && !crashedEmpty) || run.numTotalTests === 0) {
+        const evaluation = run.data
+            ? evaluateCoverageForTarget(run.data, projectRoot, target, { numTotalTests: run.numTotalTests })
+            : { status: 'no-data', reason: 'no-tests-ran' };
+        return fromEvaluation(evaluation, run.exitedCleanly || run.data !== null, projectRoot);
+    }
+    // No report at all: say exactly what happened to the run (not installed,
+    // timed out, crashed with stderr), then fall back to a labelled estimate.
+    const estimate = buildEstimatedCoverage(target);
+    const runNote = describeRunFailure(run, projectRoot);
+    if (estimate) {
+        estimate.provenance.notes = [
+            `${runNote} These numbers are a STATIC ESTIMATE derived from source shape — ` +
+                'not measured coverage, and must not be reported as such.',
+            ...estimate.provenance.notes.filter(n => !/^No instrumentation ran/.test(n)),
+        ];
+    }
+    return {
+        collected: estimate, ranTests: run.exitedCleanly, projectRoot,
+        notes: estimate ? [] : [runNote],
+    };
+}
+/** Caller-facing explanation for a result with no coverage figures. */
+function noDataWarning(reason, ranTests, targetPath, projectRoot) {
+    if (reason)
+        return describeNoData(reason, targetPath, projectRoot);
+    return ranTests
+        ? 'Tests ran but no coverage output was generated. Ensure a coverage provider is configured (e.g., @vitest/coverage-v8, istanbul).'
+        : 'No coverage data found and could not run tests automatically. ' + estimationGuidance(targetPath);
 }
 /**
  * Build the guidance string shown when a result is an estimate rather than a
@@ -169,8 +167,13 @@ export function registerCoverageHandlers(ctx) {
             const analyzer = ctx.getCoverageAnalyzer();
             const targetPath = payload.target || process.cwd();
             const threshold = payload.threshold || 80;
-            const { collected, ranTests, testOnlyReport } = await collectCoverage(targetPath);
+            const { collected, ranTests, noData, projectRoot, notes } = await collectCoverage(targetPath);
+            // #995 review N5: say so plainly instead of "no coverage data found".
+            if (noData === 'target-missing') {
+                return err(new Error(describeNoData('target-missing', targetPath, null)));
+            }
             if (!collected) {
+                const unmeasured = noData !== undefined && isUnmeasured(noData);
                 return ok({
                     lineCoverage: null,
                     branchCoverage: null,
@@ -182,22 +185,21 @@ export function registerCoverageHandlers(ctx) {
                     estimated: false,
                     measured: false,
                     coverageMethod: 'none',
+                    // #995(d): "no measurement exists for this target", distinct from 0%.
+                    ...(unmeasured ? { unmeasured: true } : {}),
                     algorithm: 'sublinear-O(log n)',
-                    warning: testOnlyReport
-                        ? 'The coverage report contains only test files, so there is no production ' +
-                            'coverage to report. Coverage OF a test file is not a meaningful metric. ' +
-                            'Check that your coverage tool is instrumenting your source directory.'
-                        : ranTests
-                            ? 'Tests ran but no coverage output was generated. Ensure a coverage provider is configured (e.g., @vitest/coverage-v8, istanbul).'
-                            : 'No coverage data found and could not run tests automatically. ' + estimationGuidance(targetPath),
+                    warning: notes?.length ? notes.join(' ') : noDataWarning(noData, ranTests, targetPath, projectRoot),
                 });
             }
             const { data: coverageData, provenance } = collected;
             // Analyze coverage using the real CoverageAnalyzerService
+            // #1008: the analyzer persists only measured coverage; a static estimate
+            // is returned below, labelled, but never stored as evidence.
             const analysisResult = await analyzer.analyze({
                 coverageData,
                 threshold,
                 includeFileDetails: payload.detectGaps,
+                measured: !provenance.estimated,
             });
             if (!analysisResult.success) {
                 return analysisResult;
@@ -227,7 +229,7 @@ export function registerCoverageHandlers(ctx) {
             }
             const round = (n) => Math.round(n * 10) / 10;
             const pct = (covered, total) => total > 0 ? Math.round((covered / total) * 1000) / 10 : null;
-            const warnings = [...provenance.notes];
+            const warnings = [...provenance.notes, ...(notes ?? [])];
             if (provenance.estimated)
                 warnings.push(estimationGuidance(targetPath));
             // #569: the analyzer generates recommendations from the summary numbers.
@@ -236,13 +238,11 @@ export function registerCoverageHandlers(ctx) {
             // significantly lower than line coverage", "Function coverage is below
             // 70%") is a statement about a metric nobody measured. Drop it rather
             // than send a developer to fix a number that doesn't exist.
-            const recommendations = report.recommendations.filter(rec => {
-                if (!provenance.branchDataCollected && /branch coverage/i.test(rec))
-                    return false;
-                if (!provenance.functionDataCollected && /function coverage/i.test(rec))
-                    return false;
-                return true;
-            });
+            // #995 NB5/NB-A: the verdict and the shortfall advice come from the same
+            // collected-metrics computation (shared with the CLI), so they can't disagree.
+            const metricsCollected = { branch: provenance.branchDataCollected, function: provenance.functionDataCollected };
+            const verdict = thresholdVerdict(report.summary, threshold, metricsCollected);
+            const recommendations = reconcileRecommendations(report.recommendations, verdict, threshold, metricsCollected);
             return ok({
                 lineCoverage: round(report.summary.line),
                 // #569 work item 4: never report a branch percentage — least of all
@@ -258,7 +258,8 @@ export function registerCoverageHandlers(ctx) {
                     functionCoverage: provenance.functionDataCollected ? pct(f.functions.covered, f.functions.total) : null,
                 })),
                 gaps,
-                meetsThreshold: report.meetsThreshold,
+                // NB5: judged only on the metrics that were collected (shared with the CLI).
+                meetsThreshold: verdict.meetsThreshold,
                 delta: report.delta,
                 recommendations,
                 algorithm: 'sublinear-O(log n)',