agentic-qe 3.15.4 → 3.15.5

package/dist/cli/commands/coverage.js

@@ -8,7 +8,52 @@ import chalk from 'chalk';
 import { runCoverageAnalysisWizard } from '../wizards/coverage-wizard.js';
 import { walkSourceFiles } from '../utils/file-discovery.js';
 import { writeOutput, toJSON, coverageToMarkdown } from '../utils/ci-output.js';
-import { buildCoverageData } from '../utils/coverage-data.js';
+import * as path from 'path';
+import { buildCoverageData, summarizeCoverage } from '../utils/coverage-data.js';
+import { describeNoData, isUnmeasured, resolveExistingCoverage, reconcileRecommendations, thresholdVerdict, } from '../../coordination/handlers/coverage-target.js';
+/** Which optional metrics an instrumented report actually carries. */
+function metricsCollected(data) {
+    if (!data.instrumented)
+        return { branch: true, function: true }; // labelled heuristic estimate
+    return {
+        branch: data.files.some(f => f.branches.total > 0),
+        function: data.files.some(f => f.functions.total > 0),
+    };
+}
+/** `aqe coverage` exit code when the target has no coverage measurement (#995). */
+export const EXIT_UNMEASURED = 3;
+/**
+ * Resolve the coverage data for a CLI target (#995).
+ *
+ * Uses the SAME resolution and verdict as the MCP `coverage_analyze_sublinear`
+ * handler (`resolveExistingCoverage`), so CLI and MCP cannot disagree about
+ * what a report says for a target:
+ *   - a coverage report file (lcov.info, coverage-final.json, ...) is parsed
+ *     directly;
+ *   - a directory or source file is scoped against the instrumented report of
+ *     its PROJECT ROOT (nearest package.json/.git above it), not the cwd;
+ *   - with no report at the project root, the CLI falls back to its labelled
+ *     heuristic estimate (the CLI never runs the test suite).
+ */
+export async function resolveCliCoverageData(targetPath) {
+    const existing = await resolveExistingCoverage(targetPath);
+    if (existing.status === 'target-missing') {
+        return { kind: 'no-data', reason: 'target-missing', message: describeNoData('target-missing', targetPath, null) };
+    }
+    if (existing.status === 'evaluated') {
+        const { evaluation, projectRoot } = existing;
+        if (evaluation.status === 'measured') {
+            const files = evaluation.files;
+            return { kind: 'data', data: { files, summary: summarizeCoverage(files), instrumented: true } };
+        }
+        return { kind: 'no-data', reason: evaluation.reason, message: describeNoData(evaluation.reason, targetPath, projectRoot) };
+    }
+    const sourceFiles = walkSourceFiles(existing.target, { includeTests: false });
+    if (sourceFiles.length === 0)
+        return { kind: 'no-sources' };
+    console.log(chalk.gray(`  Analyzing ${sourceFiles.length} files...\n`));
+    return { kind: 'data', data: buildCoverageData(sourceFiles, existing.projectRoot) };
+}
 function getColorForPercent(percent) {
     if (percent >= 80)
         return chalk.green;
@@ -28,6 +73,21 @@ export function createCoverageCommand(context, cleanupAndExit, ensureInitialized
         .option('--ghost', 'Include ghost intent coverage analysis (detect untested behavioral intents)')
         .option('-F, --format <format>', 'Output format (text|json|markdown)', 'text')
         .option('-o, --output <path>', 'Write output to file')
+        .addHelpText('after', `
+Target: a directory, a source file, or an existing coverage report
+(lcov.info, coverage-final.json, coverage-summary.json, Cobertura XML).
+Reports are read from the target's project root (nearest package.json / .git).
+
+Threshold: judged on the metrics the report actually collected. A metric with
+no data (e.g. a report without branch data) is shown as n/a and is excluded
+from the threshold, not counted as 0%.
+
+Exit codes:
+  0  coverage meets the threshold (by more than 5%)
+  1  coverage below the threshold, or an error (missing target, unreadable report)
+  2  coverage within 5% above the threshold
+  ${EXIT_UNMEASURED}  UNMEASURED: no coverage measurement exists for the target
+     (not in the report, the runner ran 0 tests, or only test files were reported)`)
         .action(async (target, options) => {
         let analyzeTarget = target;
         let includeRisk = options.risk;
@@ -57,169 +117,224 @@ export function createCoverageCommand(context, cleanupAndExit, ensureInitialized
                 await cleanupAndExit(1);
             }
         }
-        if (!await ensureInitialized())
-            return;
+        // #995 review NB3: with a machine-readable format, stdout carries ONLY the
+        // document. Progress lines (ours, and anything printed while the fleet
+        // initializes) go to stderr; the real console.log is restored to emit.
+        const machineFormat = options.format !== 'text';
+        const stdoutLog = console.log;
+        if (machineFormat)
+            console.log = (...args) => console.error(...args);
+        const emit = (content) => {
+            console.log = stdoutLog;
+            writeOutput(content, options.output);
+        };
         try {
-            console.log(chalk.blue(`\n  Analyzing coverage for ${analyzeTarget}...\n`));
-            const coverageAPI = await context.kernel.getDomainAPIAsync('coverage-analysis');
-            if (!coverageAPI) {
-                console.log(chalk.red('Coverage analysis domain not available'));
+            if (!await ensureInitialized())
                 return;
-            }
-            const path = await import('path');
-            const targetPath = path.resolve(analyzeTarget);
-            // Fix #280: Use shared file discovery supporting all languages
-            const sourceFiles = walkSourceFiles(targetPath, { includeTests: false });
-            if (sourceFiles.length === 0) {
-                console.log(chalk.yellow('No source files found'));
-                return;
-            }
-            console.log(chalk.gray(`  Analyzing ${sourceFiles.length} files...\n`));
-            // Build coverage data from real V8/istanbul output or deterministic estimation
-            const coverageData = buildCoverageData(sourceFiles);
-            if (coverageData.instrumented) {
-                console.log(chalk.green('  Using instrumented coverage data (V8/istanbul)\n'));
-            }
-            else {
-                console.log(chalk.yellow('  No instrumented coverage found — using heuristic estimation'));
-                console.log(chalk.gray('  Run tests with coverage first: npm test -- --coverage\n'));
-            }
-            const result = await coverageAPI.analyze({
-                coverageData,
-                threshold,
-                includeFileDetails: true,
-            });
-            const format = options.format;
-            let coverageResult;
-            if (result.success && result.value) {
-                const report = result.value;
-                // For non-text formats, collect all data and output at end
-                coverageResult = {
-                    summary: report.summary,
-                    meetsThreshold: report.meetsThreshold,
-                    threshold,
-                    recommendations: report.recommendations,
-                };
-                if (format === 'text') {
-                    const fmt = (v) => typeof v === 'number' ? v.toFixed(1) : v;
-                    console.log(chalk.cyan('  Coverage Summary:'));
-                    console.log(`    Lines:      ${getColorForPercent(report.summary.line)(fmt(report.summary.line) + '%')}`);
-                    console.log(`    Branches:   ${getColorForPercent(report.summary.branch)(fmt(report.summary.branch) + '%')}`);
-                    console.log(`    Functions:  ${getColorForPercent(report.summary.function)(fmt(report.summary.function) + '%')}`);
-                    console.log(`    Statements: ${getColorForPercent(report.summary.statement)(fmt(report.summary.statement) + '%')}`);
-                    console.log(`\n    Threshold: ${report.meetsThreshold ? chalk.green(`Met (${threshold}%)`) : chalk.red(`Not met (${threshold}%)`)}`);
-                    if (report.recommendations.length > 0) {
-                        console.log(chalk.cyan('\n  Recommendations:'));
-                        for (const rec of report.recommendations) {
-                            console.log(chalk.gray(`    - ${rec}`));
-                        }
+            try {
+                console.log(chalk.blue(`\n  Analyzing coverage for ${analyzeTarget}...\n`));
+                const coverageAPI = await context.kernel.getDomainAPIAsync('coverage-analysis');
+                if (!coverageAPI) {
+                    console.log(chalk.red('Coverage analysis domain not available'));
+                    return;
+                }
+                const targetPath = path.resolve(analyzeTarget);
+                // Fix #280: shared file discovery supporting all languages.
+                // #995: coverage files as targets; reports resolved from the project root.
+                const resolved = await resolveCliCoverageData(targetPath);
+                if (resolved.kind === 'no-sources') {
+                    console.log(chalk.yellow('No source files found'));
+                    return;
+                }
+                if (resolved.kind === 'no-data') {
+                    // Errors (missing target, unreadable report) exit 1. Everything else
+                    // means "no measurement exists" — distinct exit code, never "0%".
+                    const isError = resolved.reason === 'target-missing' || resolved.reason === 'unreadable-report';
+                    if (options.format === 'json') {
+                        // Same shape as a normal result, with nulls (#995 review N4).
+                        emit(toJSON({
+                            summary: { line: null, branch: null, function: null, statement: null },
+                            meetsThreshold: null,
+                            threshold,
+                            measured: false,
+                            unmeasured: isUnmeasured(resolved.reason),
+                            reason: resolved.reason,
+                            target: targetPath,
+                            warning: resolved.message,
+                        }));
+                    }
+                    else {
+                        console.log((isError ? chalk.red : chalk.yellow)(`  ${resolved.message}\n`));
                     }
+                    await cleanupAndExit(isError ? 1 : EXIT_UNMEASURED);
+                    return;
                 }
-            }
-            // Detect gaps if requested
-            if (detectGaps) {
-                console.log(chalk.cyan('\n  Coverage Gaps:'));
-                const gapResult = await coverageAPI.detectGaps({
+                const coverageData = resolved.data;
+                if (coverageData.instrumented) {
+                    console.log(chalk.green('  Using instrumented coverage data (V8/istanbul)\n'));
+                    if (coverageData.unmeasuredFiles?.length) {
+                        console.log(chalk.yellow(`  ${coverageData.unmeasuredFiles.length} file(s) not in the coverage report — UNMEASURED, excluded from the figures\n`));
+                    }
+                }
+                else {
+                    console.log(chalk.yellow('  No instrumented coverage found — using heuristic estimation'));
+                    console.log(chalk.gray('  Run tests with coverage first: npm test -- --coverage\n'));
+                }
+                // #1008: a heuristic estimate is shown, never persisted as coverage evidence.
+                const result = await coverageAPI.analyze({
                     coverageData,
-                    minCoverage: threshold,
-                    prioritize: includeRisk ? 'risk' : 'size',
+                    threshold,
+                    includeFileDetails: true,
+                    measured: coverageData.instrumented,
                 });
-                if (gapResult.success && gapResult.value) {
-                    const gaps = gapResult.value;
-                    if (coverageResult)
-                        coverageResult.gaps = gaps.gaps.map(g => ({
-                            file: g.file.replace(process.cwd() + '/', ''),
-                            lines: g.lines,
-                            riskScore: g.riskScore,
-                            severity: g.severity,
-                        }));
-                    console.log(chalk.gray(`    Total uncovered lines: ${gaps.totalUncoveredLines}`));
-                    console.log(chalk.gray(`    Estimated effort: ${gaps.estimatedEffort} hours\n`));
-                    for (const gap of gaps.gaps.slice(0, 8)) {
-                        const severityColor = gap.severity === 'high' ? chalk.red : gap.severity === 'medium' ? chalk.yellow : chalk.gray;
-                        const filePath = gap.file.replace(process.cwd() + '/', '');
-                        console.log(`    ${severityColor(`[${gap.severity}]`)} ${chalk.white(filePath)}`);
-                        console.log(chalk.gray(`        ${gap.lines.length} uncovered lines, Risk: ${(gap.riskScore * 100).toFixed(0)}%`));
+                const format = options.format;
+                let coverageResult;
+                let overallCoverage = 0;
+                if (result.success && result.value) {
+                    const report = result.value;
+                    // #995 review NB5: a metric the report never collected is null — not
+                    // 0 — and is left out of the threshold verdict (same rule as MCP).
+                    const collected = metricsCollected(coverageData);
+                    const verdict = thresholdVerdict(report.summary, threshold, collected);
+                    const summary = {
+                        ...report.summary,
+                        branch: collected.branch ? report.summary.branch : null,
+                        function: collected.function ? report.summary.function : null,
+                    };
+                    // NB-A: the shortfall advice comes from the same verdict (shared with MCP).
+                    const recommendations = reconcileRecommendations(report.recommendations, verdict, threshold, collected);
+                    overallCoverage = verdict.overall;
+                    // For non-text formats, collect all data and output at end
+                    coverageResult = {
+                        summary: summary,
+                        meetsThreshold: verdict.meetsThreshold,
+                        threshold,
+                        recommendations,
+                    };
+                    if (format === 'text') {
+                        const fmt = (v) => v === null ? 'n/a (not collected)' : v.toFixed(1) + '%';
+                        const color = (v) => v === null ? chalk.gray : getColorForPercent(v);
+                        console.log(chalk.cyan('  Coverage Summary:'));
+                        console.log(`    Lines:      ${color(summary.line)(fmt(summary.line))}`);
+                        console.log(`    Branches:   ${color(summary.branch)(fmt(summary.branch))}`);
+                        console.log(`    Functions:  ${color(summary.function)(fmt(summary.function))}`);
+                        console.log(`    Statements: ${color(summary.statement)(fmt(summary.statement))}`);
+                        console.log(`\n    Threshold: ${verdict.meetsThreshold ? chalk.green(`Met (${threshold}%)`) : chalk.red(`Not met (${threshold}%)`)}`);
+                        if (recommendations.length > 0) {
+                            console.log(chalk.cyan('\n  Recommendations:'));
+                            for (const rec of recommendations) {
+                                console.log(chalk.gray(`    - ${rec}`));
+                            }
+                        }
                     }
-                    if (gaps.gaps.length > 8) {
-                        console.log(chalk.gray(`    ... and ${gaps.gaps.length - 8} more gaps`));
+                }
+                // Detect gaps if requested
+                if (detectGaps) {
+                    console.log(chalk.cyan('\n  Coverage Gaps:'));
+                    const gapResult = await coverageAPI.detectGaps({
+                        coverageData,
+                        minCoverage: threshold,
+                        prioritize: includeRisk ? 'risk' : 'size',
+                    });
+                    if (gapResult.success && gapResult.value) {
+                        const gaps = gapResult.value;
+                        if (coverageResult)
+                            coverageResult.gaps = gaps.gaps.map(g => ({
+                                file: g.file.replace(process.cwd() + '/', ''),
+                                lines: g.lines,
+                                riskScore: g.riskScore,
+                                severity: g.severity,
+                            }));
+                        console.log(chalk.gray(`    Total uncovered lines: ${gaps.totalUncoveredLines}`));
+                        console.log(chalk.gray(`    Estimated effort: ${gaps.estimatedEffort} hours\n`));
+                        for (const gap of gaps.gaps.slice(0, 8)) {
+                            const severityColor = gap.severity === 'high' ? chalk.red : gap.severity === 'medium' ? chalk.yellow : chalk.gray;
+                            const filePath = gap.file.replace(process.cwd() + '/', '');
+                            console.log(`    ${severityColor(`[${gap.severity}]`)} ${chalk.white(filePath)}`);
+                            console.log(chalk.gray(`        ${gap.lines.length} uncovered lines, Risk: ${(gap.riskScore * 100).toFixed(0)}%`));
+                        }
+                        if (gaps.gaps.length > 8) {
+                            console.log(chalk.gray(`    ... and ${gaps.gaps.length - 8} more gaps`));
+                        }
                     }
                 }
-            }
-            // Ghost intent coverage analysis (ADR-059)
-            if (options.ghost || detectGaps) {
-                console.log(chalk.cyan('\n  Ghost Intent Coverage (ADR-059):'));
-                try {
-                    const testPaths = coverageData.files.map(f => f.path);
-                    const ghostResult = await coverageAPI.analyzeGhostCoverage(testPaths, analyzeTarget);
-                    if (ghostResult.success && ghostResult.value) {
-                        const ghost = ghostResult.value;
-                        console.log(chalk.gray(`    Phantom gaps detected: ${ghost.gaps.length}`));
-                        console.log(chalk.gray(`    Ghost score: ${(ghost.totalGhostScore * 100).toFixed(1)}%`));
-                        console.log(chalk.gray(`    Coverage completeness: ${(ghost.coverageCompleteness * 100).toFixed(1)}%\n`));
-                        for (const gap of ghost.gaps.slice(0, 8)) {
-                            const severityColor = gap.severity === 'critical' ? chalk.red : gap.severity === 'high' ? chalk.red : gap.severity === 'medium' ? chalk.yellow : chalk.gray;
-                            console.log(`    ${severityColor(`[${gap.severity}]`)} ${chalk.white(gap.category)}`);
-                            console.log(chalk.gray(`        ${gap.description}`));
+                // Ghost intent coverage analysis (ADR-059)
+                if (options.ghost || detectGaps) {
+                    console.log(chalk.cyan('\n  Ghost Intent Coverage (ADR-059):'));
+                    try {
+                        const testPaths = coverageData.files.map(f => f.path);
+                        const ghostResult = await coverageAPI.analyzeGhostCoverage(testPaths, analyzeTarget);
+                        if (ghostResult.success && ghostResult.value) {
+                            const ghost = ghostResult.value;
+                            console.log(chalk.gray(`    Phantom gaps detected: ${ghost.gaps.length}`));
+                            console.log(chalk.gray(`    Ghost score: ${(ghost.totalGhostScore * 100).toFixed(1)}%`));
+                            console.log(chalk.gray(`    Coverage completeness: ${(ghost.coverageCompleteness * 100).toFixed(1)}%\n`));
+                            for (const gap of ghost.gaps.slice(0, 8)) {
+                                const severityColor = gap.severity === 'critical' ? chalk.red : gap.severity === 'high' ? chalk.red : gap.severity === 'medium' ? chalk.yellow : chalk.gray;
+                                console.log(`    ${severityColor(`[${gap.severity}]`)} ${chalk.white(gap.category)}`);
+                                console.log(chalk.gray(`        ${gap.description}`));
+                            }
+                            if (ghost.gaps.length > 8) {
+                                console.log(chalk.gray(`    ... and ${ghost.gaps.length - 8} more phantom gaps`));
+                            }
                         }
-                        if (ghost.gaps.length > 8) {
-                            console.log(chalk.gray(`    ... and ${ghost.gaps.length - 8} more phantom gaps`));
+                        else {
+                            console.log(chalk.dim('    Ghost analysis not available (requires HNSW index)'));
                         }
                     }
-                    else {
-                        console.log(chalk.dim('    Ghost analysis not available (requires HNSW index)'));
+                    catch {
+                        console.log(chalk.dim('    Ghost analysis skipped (analyzer not initialized)'));
                     }
                 }
-                catch {
-                    console.log(chalk.dim('    Ghost analysis skipped (analyzer not initialized)'));
+                // Calculate risk if requested
+                if (includeRisk) {
+                    console.log(chalk.cyan('\n  Risk Analysis:'));
+                    const lowCoverageFiles = [...coverageData.files]
+                        .sort((a, b) => (a.lines.covered / a.lines.total) - (b.lines.covered / b.lines.total))
+                        .slice(0, 5);
+                    for (const file of lowCoverageFiles) {
+                        const riskResult = await coverageAPI.calculateRisk({
+                            file: file.path,
+                            uncoveredLines: file.uncoveredLines,
+                        });
+                        if (riskResult.success && riskResult.value) {
+                            const risk = riskResult.value;
+                            const riskColor = risk.riskLevel === 'high' ? chalk.red : risk.riskLevel === 'medium' ? chalk.yellow : chalk.green;
+                            const filePath = file.path.replace(process.cwd() + '/', '');
+                            console.log(`    ${riskColor(`[${risk.riskLevel}]`)} ${chalk.white(filePath)}`);
+                            console.log(chalk.gray(`        Risk: ${(risk.overallRisk * 100).toFixed(0)}%, Coverage: ${Math.round((file.lines.covered / file.lines.total) * 100)}%`));
+                        }
+                    }
                 }
-            }
-            // Calculate risk if requested
-            if (includeRisk) {
-                console.log(chalk.cyan('\n  Risk Analysis:'));
-                const lowCoverageFiles = [...coverageData.files]
-                    .sort((a, b) => (a.lines.covered / a.lines.total) - (b.lines.covered / b.lines.total))
-                    .slice(0, 5);
-                for (const file of lowCoverageFiles) {
-                    const riskResult = await coverageAPI.calculateRisk({
-                        file: file.path,
-                        uncoveredLines: file.uncoveredLines,
-                    });
-                    if (riskResult.success && riskResult.value) {
-                        const risk = riskResult.value;
-                        const riskColor = risk.riskLevel === 'high' ? chalk.red : risk.riskLevel === 'medium' ? chalk.yellow : chalk.green;
-                        const filePath = file.path.replace(process.cwd() + '/', '');
-                        console.log(`    ${riskColor(`[${risk.riskLevel}]`)} ${chalk.white(filePath)}`);
-                        console.log(chalk.gray(`        Risk: ${(risk.overallRisk * 100).toFixed(0)}%, Coverage: ${Math.round((file.lines.covered / file.lines.total) * 100)}%`));
+                // Non-text format output (collected all data)
+                if (coverageResult && format === 'json') {
+                    emit(toJSON(coverageResult));
+                }
+                else if (coverageResult && format === 'markdown') {
+                    emit(coverageToMarkdown(coverageResult));
+                }
+                else if (format === 'text') {
+                    console.log(chalk.green('\n Coverage analysis complete\n'));
+                }
+                // Exit codes: 1 = below threshold, 2 = within 5% of threshold, 0 = above threshold
+                if (coverageResult && !coverageResult.meetsThreshold) {
+                    await cleanupAndExit(1);
+                }
+                if (coverageResult) {
+                    const avg = overallCoverage;
+                    if (avg < threshold + 5 && avg >= threshold) {
+                        await cleanupAndExit(2);
                     }
                 }
+                await cleanupAndExit(0);
             }
-            // Non-text format output (collected all data)
-            if (coverageResult && format === 'json') {
-                writeOutput(toJSON(coverageResult), options.output);
-            }
-            else if (coverageResult && format === 'markdown') {
-                writeOutput(coverageToMarkdown(coverageResult), options.output);
-            }
-            else if (format === 'text') {
-                console.log(chalk.green('\n Coverage analysis complete\n'));
-            }
-            // Exit codes: 1 = below threshold, 2 = within 5% of threshold, 0 = above threshold
-            if (coverageResult && !coverageResult.meetsThreshold) {
+            catch (error) {
+                console.error(chalk.red('\nFailed:'), error);
                 await cleanupAndExit(1);
             }
-            if (coverageResult) {
-                const avg = (coverageResult.summary.line + coverageResult.summary.branch +
-                    coverageResult.summary.function + coverageResult.summary.statement) / 4;
-                if (avg < threshold + 5 && avg >= threshold) {
-                    await cleanupAndExit(2);
-                }
-            }
-            await cleanupAndExit(0);
         }
-        catch (error) {
-            console.error(chalk.red('\nFailed:'), error);
-            await cleanupAndExit(1);
+        finally {
+            console.log = stdoutLog;
         }
     });
     // Subcommand: coverage gaps — enumerate unhandled branches via static analysis

package/dist/cli/commands/quality.d.ts

@@ -11,12 +11,23 @@ import { type QualityGateResult } from '../utils/ci-output.js';
 import { type QualityEvidenceValues } from '../../domains/quality-assessment/quality-evidence.js';
 export declare function loadQualityEvidence(memory: MemoryBackend): Promise<QualityEvidenceValues>;
 export declare function evaluateMeasuredQualityEvidence(measured: QualityEvidenceValues): QualityGateResult;
+/**
+ * #996: when measured evidence is missing, stale or malformed the gate cannot
+ * be evaluated. Report it as a structured, non-passing result with the same
+ * `status: 'insufficient-evidence'` and `unmeasured` list that MCP
+ * `quality_assess({ runGate: true })` returns alongside its error. Errors that
+ * are not about evidence (e.g. the store itself failing) are rethrown.
+ */
+export declare function describeUnavailableQualityEvidence(memory: MemoryBackend, error: unknown): Promise<QualityGateResult>;
 /**
  * Published quality command exit contract:
  * 0 = passed with more than five percentage points of headroom
  * 1 = one or more measured checks failed
  * 2 = passed, but at least one measured check has less than five points of headroom
+ * 3 = insufficient evidence (#996): a metric is absent, stale or malformed, so
+ *     the gate was not evaluated (UNMEASURED — neither a pass nor a measured failure)
  */
-export declare function getMeasuredQualityExitCode(result: QualityGateResult): 0 | 1 | 2;
+export declare const INSUFFICIENT_EVIDENCE_EXIT_CODE = 3;
+export declare function getMeasuredQualityExitCode(result: QualityGateResult): 0 | 1 | 2 | 3;
 export declare function createQualityCommand(context: CLIContext, cleanupAndExit: (code: number) => Promise<never>, ensureInitialized: () => Promise<boolean>): Command;
 //# sourceMappingURL=quality.d.ts.map

package/dist/cli/commands/quality.js

@@ -7,7 +7,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { writeOutput, toJSON, qualityGateToMarkdown } from '../utils/ci-output.js';
-import { evaluateQualityEvidence, loadQualityEvidence as loadCanonicalQualityEvidence, } from '../../domains/quality-assessment/quality-evidence.js';
+import { InsufficientQualityEvidenceError, evaluateQualityEvidence, inspectQualityEvidence, loadQualityEvidence as loadCanonicalQualityEvidence, } from '../../domains/quality-assessment/quality-evidence.js';
 export async function loadQualityEvidence(memory) {
     return loadCanonicalQualityEvidence(memory);
 }
@@ -20,13 +20,48 @@ export function evaluateMeasuredQualityEvidence(measured) {
         recommendations: evaluation.recommendations,
     };
 }
+/**
+ * #996: when measured evidence is missing, stale or malformed the gate cannot
+ * be evaluated. Report it as a structured, non-passing result with the same
+ * `status: 'insufficient-evidence'` and `unmeasured` list that MCP
+ * `quality_assess({ runGate: true })` returns alongside its error. Errors that
+ * are not about evidence (e.g. the store itself failing) are rethrown.
+ */
+export async function describeUnavailableQualityEvidence(memory, error) {
+    const insufficient = error instanceof InsufficientQualityEvidenceError
+        ? error
+        : await inspectQualityEvidence(memory).then(({ problems }) => problems.length > 0 ? new InsufficientQualityEvidenceError(problems) : undefined);
+    if (!insufficient)
+        throw error;
+    const reason = error instanceof Error ? error.message : String(error);
+    const details = insufficient.toDetails();
+    return {
+        passed: false,
+        score: 'N/A',
+        checks: [],
+        status: details.status,
+        evidenceStatus: details.evidenceStatus,
+        unmeasured: details.unmeasured,
+        gateEvaluated: false,
+        error: reason,
+        recommendations: [
+            `Quality gate not evaluated: ${reason}`,
+            ...details.recommendations,
+        ],
+    };
+}
 /**
  * Published quality command exit contract:
  * 0 = passed with more than five percentage points of headroom
  * 1 = one or more measured checks failed
  * 2 = passed, but at least one measured check has less than five points of headroom
+ * 3 = insufficient evidence (#996): a metric is absent, stale or malformed, so
+ *     the gate was not evaluated (UNMEASURED — neither a pass nor a measured failure)
  */
+export const INSUFFICIENT_EVIDENCE_EXIT_CODE = 3;
 export function getMeasuredQualityExitCode(result) {
+    if (result.evidenceStatus === 'insufficient-evidence')
+        return INSUFFICIENT_EVIDENCE_EXIT_CODE;
     if (!result.passed)
         return 1;
     return result.checks.some(check => (check.direction !== 'max'
@@ -53,14 +88,27 @@ export function createQualityCommand(context, cleanupAndExit, ensureInitialized)
                 if (format === 'text') {
                     console.log(chalk.blue(`\n Running quality gate evaluation...\n`));
                 }
-                const measured = await loadQualityEvidence(context.kernel.memory);
-                const gateResult = evaluateMeasuredQualityEvidence(measured);
+                const memory = context.kernel.memory;
+                let gateResult;
+                try {
+                    gateResult = evaluateMeasuredQualityEvidence(await loadQualityEvidence(memory));
+                }
+                catch (error) {
+                    gateResult = await describeUnavailableQualityEvidence(memory, error);
+                }
                 if (format === 'json') {
                     writeOutput(toJSON(gateResult), options.output);
                 }
                 else if (format === 'markdown') {
                     writeOutput(qualityGateToMarkdown(gateResult), options.output);
                 }
+                else if (gateResult.evidenceStatus === 'insufficient-evidence') {
+                    console.log(`  Quality Gate: ${chalk.yellow('⚠ INSUFFICIENT EVIDENCE (not evaluated)')}`);
+                    if (gateResult.unmeasured?.length) {
+                        console.log(`  Unmeasured: ${gateResult.unmeasured.join(', ')}`);
+                    }
+                    console.log(chalk.gray(`  ${gateResult.error ?? ''}\n`));
+                }
                 else {
                     const statusIcon = gateResult.passed ? chalk.green('✓ PASSED') : chalk.red('✗ FAILED');
                     console.log(`  Quality Gate: ${statusIcon}`);

package/dist/cli/utils/ci-output.d.ts

@@ -64,11 +64,12 @@ export interface TestRunSummary {
     tests?: TestResult[];
 }
 export interface CoverageResult {
+    /** `null` = the report never collected that metric (#995); not 0%. */
     summary: {
-        line: number;
-        branch: number;
-        function: number;
-        statement: number;
+        line: number | null;
+        branch: number | null;
+        function: number | null;
+        statement: number | null;
     };
     meetsThreshold: boolean;
     threshold: number;
@@ -96,6 +97,15 @@ export interface QualityGateResult {
         threshold: number | string;
     }>;
     recommendations?: string[];
+    /** #996 (additive): 'insufficient-evidence' when the gate could not be evaluated. */
+    status?: 'insufficient-evidence';
+    evidenceStatus?: 'measured' | 'insufficient-evidence';
+    /** #996: canonical metrics with no measured evidence. */
+    unmeasured?: string[];
+    /** #996: false when missing evidence prevented the gate from running. */
+    gateEvaluated?: boolean;
+    /** #996: why the gate could not be evaluated. */
+    error?: string;
 }
 /**
  * Standard --format and --output options to add to any Command.