agentic-qe 3.15.4 → 3.15.5

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

@@ -0,0 +1,311 @@
+/**
+ * Coverage target resolution (issue #995).
+ *
+ * A coverage target can be the project root, a subfolder of it, a single source
+ * file, or an existing coverage report. Before #995 every target was treated as
+ * if it were the project root: `target: "src/"` ran vitest FROM `src/` (which
+ * found no tests, reported 0%, and wrote `src/coverage/` into the source tree),
+ * and `target: "coverage/lcov.info"` was searched for a `coverage/` folder
+ * inside a file and came back empty.
+ *
+ * This module answers the three questions every collector needs first:
+ *   1. Which project does the target belong to?  (`findCoverageProjectRoot`)
+ *   2. Is the target itself a coverage report?   (`isCoverageReportFile` /
+ *      `loadCoverageReportFile`)
+ *   3. Which entries of a project-wide report belong to the target?
+ *      (`scopeCoverageToTarget`)
+ *
+ * Kept free of task-executor and child-process imports so both the MCP handler
+ * and the CLI `coverage` command can share it.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { loadCoverageData, parseCoberturaXml, parseCoverageJson, parseCoverageSummaryJson, parseLcovInfo, } from './handler-utils.js';
+import { isTestPath } from './coverage-collection.js';
+// ============================================================================
+// Project root
+// ============================================================================
+/**
+ * Files whose presence marks a directory as a project root, i.e. the directory
+ * a test/coverage tool must be run from. `.git` bounds the walk for projects
+ * without a manifest.
+ */
+const PROJECT_ROOT_MARKERS = [
+    'package.json',
+    'pyproject.toml', 'setup.py', 'setup.cfg',
+    'go.mod', 'Cargo.toml',
+    'pom.xml', 'build.gradle', 'build.gradle.kts',
+    '.git',
+];
+/**
+ * Walk up from a target to the nearest directory that holds a project marker.
+ *
+ * NEAREST rather than topmost: in a monorepo, `packages/core/src` belongs to
+ * `packages/core` (its own package.json and test config), not the workspace
+ * root. This intentionally differs from `kernel/findProjectRoot`, which locates
+ * the AQE data root (honouring AQE_PROJECT_ROOT and `.agentic-qe`).
+ *
+ * Returns `null` when the target does not exist (a typo must not silently
+ * resolve to — and run tests for — an ancestor project) or when no marker is
+ * found below the home directory / filesystem root within `maxDepth` levels.
+ */
+export function findCoverageProjectRoot(target, maxDepth = 12) {
+    let dir;
+    try {
+        const resolved = path.resolve(target);
+        if (!fs.existsSync(resolved))
+            return null;
+        const real = fs.realpathSync(resolved);
+        dir = fs.statSync(real).isDirectory() ? real : path.dirname(real);
+    }
+    catch {
+        return null;
+    }
+    let home = null;
+    try {
+        home = fs.realpathSync(os.homedir());
+    }
+    catch {
+        home = null;
+    }
+    const start = dir;
+    for (let depth = 0; depth <= maxDepth; depth++) {
+        // A stray manifest in $HOME must not claim every directory beneath it.
+        // $HOME is still a valid root when it is the target itself.
+        if (home !== null && dir === home && dir !== start)
+            return null;
+        if (PROJECT_ROOT_MARKERS.some(m => fs.existsSync(path.join(dir, m))))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+// ============================================================================
+// Coverage report files as targets
+// ============================================================================
+const REPORT_BASENAMES = new Set([
+    'lcov.info',
+    'coverage-final.json',
+    'coverage-summary.json',
+    'coverage.xml',
+    'cobertura-coverage.xml',
+    'cobertura.xml',
+]);
+/** Is this path (by name) a coverage report rather than source code? */
+export function isCoverageReportFile(filePath) {
+    const base = path.basename(filePath).toLowerCase();
+    return REPORT_BASENAMES.has(base) || base.endsWith('.lcov') || base.endsWith('.lcov.info');
+}
+/**
+ * Parse a coverage report file of any supported format.
+ *
+ * Returns `null` — never an empty "0%" report — when the file can't be read,
+ * can't be parsed, or lists no files.
+ */
+export async function loadCoverageReportFile(filePath) {
+    let content;
+    try {
+        content = await fs.promises.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    if (content.trim().length === 0)
+        return null;
+    try {
+        const base = path.basename(filePath).toLowerCase();
+        let data;
+        if (base.endsWith('.json')) {
+            const parsed = JSON.parse(content);
+            // coverage-summary.json carries a `total` entry with per-metric totals.
+            if (isSummaryShape(parsed))
+                data = parseCoverageSummaryJson(content);
+            // Anything else must be istanbul's per-file map. Raw V8 output
+            // (`{ result: [...] }`) and arbitrary JSON are rejected, not parsed into
+            // a phantom file called "result" with 0/0 coverage.
+            else if (isIstanbulShape(parsed))
+                data = parseCoverageJson(content);
+            else
+                return null;
+        }
+        else if (base.endsWith('.xml')) {
+            data = parseCoberturaXml(content);
+        }
+        else {
+            data = parseLcovInfo(content);
+        }
+        return data.files.length > 0 ? data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isIstanbulShape(parsed) {
+    const entries = Object.values(parsed);
+    return entries.length > 0 && entries.every(e => typeof e === 'object' && e !== null && !Array.isArray(e) &&
+        typeof e.s === 'object' &&
+        typeof e.statementMap === 'object');
+}
+function isSummaryShape(parsed) {
+    const total = parsed.total;
+    return typeof total === 'object' && total !== null && typeof total.lines === 'object';
+}
+// ============================================================================
+// Scoping
+// ============================================================================
+/** True when `child` is `parent` or inside it (path-segment aware). */
+function isWithin(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/** Canonicalise a path without requiring it to exist (macOS /tmp → /private/tmp). */
+function canonical(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * Keep only the report entries that lie under `target`.
+ *
+ * Report paths come in two shapes: absolute (istanbul `coverage-final.json`)
+ * and project-root-relative (vitest/jest `lcov.info` writes `SF:src/math.ts`).
+ * Relative entries are resolved against `root` before comparing. Entry paths are
+ * returned unchanged.
+ */
+export function scopeCoverageToTarget(data, root, target) {
+    const rootAbs = canonical(root);
+    const targetAbs = canonical(target);
+    if (targetAbs === rootAbs)
+        return [...data.files];
+    return data.files.filter(f => {
+        const abs = path.isAbsolute(f.path) ? canonical(f.path) : path.resolve(rootAbs, f.path);
+        return isWithin(abs, targetAbs);
+    });
+}
+/**
+ * Decide what a report says about `target`. Shared by the MCP handler and the
+ * CLI so the two cannot disagree (#995 review B2).
+ *
+ * "Unmeasured" is decided ONLY from evidence that nothing was measured:
+ *   - the runner's own result says it ran 0 tests (`numTotalTests === 0`), or
+ *   - the report has no entry under the target.
+ * Hit counts are never used: a file listed with 0 hits is a measured 0%,
+ * whether the report came from our run or from the user (#995 review B3).
+ */
+export function evaluateCoverageForTarget(report, projectRoot, target, options = {}) {
+    if (options.numTotalTests === 0)
+        return { status: 'no-data', reason: 'no-tests-ran' };
+    const scoped = scopeCoverageToTarget(report, projectRoot, target);
+    if (scoped.length === 0)
+        return { status: 'no-data', reason: 'target-not-covered' };
+    // Coverage OF a test file is not production coverage (#569). A report with
+    // only test entries yields no production figure — never the unfiltered set.
+    const production = scoped.filter(f => !isTestPath(f.path, projectRoot));
+    if (production.length === 0)
+        return { status: 'no-data', reason: 'test-only-report' };
+    return { status: 'measured', files: production };
+}
+/**
+ * Resolve a target to coverage that already exists on disk, without running
+ * anything:
+ *   - a coverage report passed as the target is parsed and analysed whole;
+ *   - otherwise the PROJECT ROOT's report (not the cwd's, not the subfolder's)
+ *     is scoped to the target;
+ *   - `no-report` tells the caller it may run tooling from `projectRoot`.
+ */
+export async function resolveExistingCoverage(targetPath) {
+    const target = path.resolve(targetPath);
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch {
+        return { status: 'target-missing', target };
+    }
+    if (stat.isFile() && isCoverageReportFile(target)) {
+        const reportDir = path.dirname(target);
+        const projectRoot = findCoverageProjectRoot(reportDir)
+            ?? (path.basename(reportDir) === 'coverage' ? path.dirname(reportDir) : reportDir);
+        const report = await loadCoverageReportFile(target);
+        const evaluation = report
+            ? evaluateCoverageForTarget(report, projectRoot, projectRoot)
+            : { status: 'no-data', reason: 'unreadable-report' };
+        return { status: 'evaluated', target, projectRoot, source: 'report-file', evaluation };
+    }
+    const projectRoot = findCoverageProjectRoot(target) ?? (stat.isDirectory() ? target : path.dirname(target));
+    const existing = await loadCoverageData(projectRoot);
+    if (!existing)
+        return { status: 'no-report', target, projectRoot };
+    return {
+        status: 'evaluated', target, projectRoot, source: 'project-report',
+        evaluation: evaluateCoverageForTarget(existing, projectRoot, target),
+    };
+}
+/**
+ * Threshold verdict over the metrics that were actually collected. Shared by
+ * MCP and CLI (#995 review NB5): an uncollected metric (no branch data in the
+ * report) is null, and a null must not drag the average down as a fake 0.
+ */
+export function thresholdVerdict(summary, threshold, collected) {
+    const metrics = [summary.line, summary.statement];
+    if (collected.branch)
+        metrics.push(summary.branch);
+    if (collected.function)
+        metrics.push(summary.function);
+    const overall = metrics.reduce((a, b) => a + b, 0) / metrics.length;
+    return { overall, meetsThreshold: overall >= threshold };
+}
+const SHORTFALL_RE = /^Coverage is [\d.]+% below threshold/i;
+/**
+ * Make the analyzer's recommendations agree with `thresholdVerdict`
+ * (#995 review NB-A). The analyzer computes its "Coverage is X% below
+ * threshold" line from a 4-metric average that counts an uncollected metric as
+ * 0 — so a line-only report at 90% got "Met" next to "35.0% below threshold".
+ * Here the shortfall line is recomputed from the collected-metrics verdict,
+ * and advice about a metric that was never collected is dropped.
+ */
+export function reconcileRecommendations(recommendations, verdict, threshold, collected) {
+    const kept = recommendations.filter(rec => !SHORTFALL_RE.test(rec) &&
+        (collected.branch || !/branch coverage/i.test(rec)) &&
+        (collected.function || !/function coverage/i.test(rec)));
+    if (verdict.meetsThreshold)
+        return kept;
+    return [
+        `Coverage is ${(threshold - verdict.overall).toFixed(1)}% below threshold. Focus on high-risk files first.`,
+        ...kept,
+    ];
+}
+/** Is this verdict "no measurement exists" (as opposed to an error or test-only report)? */
+export function isUnmeasured(reason) {
+    return reason === 'target-not-covered' || reason === 'no-tests-ran';
+}
+/** Caller-facing explanation of a no-data verdict. Shared by MCP and CLI. */
+export function describeNoData(reason, target, projectRoot) {
+    switch (reason) {
+        case 'target-missing':
+            return `Target does not exist: ${target}`;
+        case 'unreadable-report':
+            return `Unreadable coverage report: ${target}. It could not be parsed or lists no files. ` +
+                'Supported: lcov.info, istanbul coverage-final.json / coverage-summary.json, Cobertura XML. ' +
+                "Raw V8 output is not supported — convert it with c8 or your runner's istanbul reporter.";
+        case 'test-only-report':
+            return '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.';
+        case 'target-not-covered':
+            return `Target is UNMEASURED: the coverage data for project ${projectRoot ?? '?'} has no entry ` +
+                `for any production file under ${target}. This is not 0% coverage — no measurement exists ` +
+                "for it. Check your coverage tool's include/exclude settings, or regenerate the report.";
+        case 'no-tests-ran':
+            return `Target is UNMEASURED: the test runner reported running 0 tests from ${projectRoot ?? '?'}. ` +
+                'This is not 0% coverage.';
+    }
+}
+//# sourceMappingURL=coverage-target.js.map

package/dist/coordination/handlers/handler-utils.d.ts

@@ -78,6 +78,15 @@ export declare function loadCoverageData(targetPath: string): Promise<CoverageDa
  * Parse Istanbul/nyc coverage-final.json format
  */
 export declare function parseCoverageJson(content: string): CoverageData;
+/**
+ * Parse istanbul `coverage-summary.json` (the `json-summary` reporter).
+ *
+ * Shape: `{ total: {...}, "<file>": { lines, statements, functions, branches } }`
+ * where each metric is `{ total, covered, skipped, pct }`. There is no
+ * per-line detail, so `uncoveredLines` is empty — a summary can report a
+ * figure but cannot locate a gap (#995).
+ */
+export declare function parseCoverageSummaryJson(content: string): CoverageData;
 /**
  * Parse LCOV info format
  */

package/dist/coordination/handlers/handler-utils.js

@@ -21,6 +21,8 @@ export async function loadCoverageData(targetPath) {
         path.join(targetPath, 'coverage', 'lcov.info'),
         path.join(targetPath, '.nyc_output', 'coverage-final.json'),
         path.join(targetPath, 'coverage-final.json'),
+        // Summary-only (per-file totals, no line detail) — last JS resort (#995)
+        path.join(targetPath, 'coverage', 'coverage-summary.json'),
         // Python (pytest-cov, coverage.py)
         path.join(targetPath, 'coverage.xml'),
         path.join(targetPath, 'htmlcov', 'status.json'),
@@ -30,7 +32,10 @@ export async function loadCoverageData(targetPath) {
     for (const coveragePath of coverageLocations) {
         try {
             const content = await fs.readFile(coveragePath, 'utf-8');
-            if (coveragePath.endsWith('.json')) {
+            if (coveragePath.endsWith('coverage-summary.json')) {
+                return parseCoverageSummaryJson(content);
+            }
+            else if (coveragePath.endsWith('.json')) {
                 return parseCoverageJson(content);
             }
             else if (coveragePath.endsWith('.info')) {
@@ -121,6 +126,44 @@ export function parseCoverageJson(content) {
         },
     };
 }
+/**
+ * Parse istanbul `coverage-summary.json` (the `json-summary` reporter).
+ *
+ * Shape: `{ total: {...}, "<file>": { lines, statements, functions, branches } }`
+ * where each metric is `{ total, covered, skipped, pct }`. There is no
+ * per-line detail, so `uncoveredLines` is empty — a summary can report a
+ * figure but cannot locate a gap (#995).
+ */
+export function parseCoverageSummaryJson(content) {
+    const data = safeJsonParse(content);
+    const pick = (m) => ({ covered: Number(m?.covered) || 0, total: Number(m?.total) || 0 });
+    const files = [];
+    for (const [filePath, entry] of Object.entries(data)) {
+        if (filePath === 'total' || typeof entry !== 'object' || entry === null || !entry.lines)
+            continue;
+        files.push({
+            path: filePath,
+            lines: pick(entry.lines),
+            branches: pick(entry.branches),
+            functions: pick(entry.functions),
+            statements: pick(entry.statements ?? entry.lines),
+            uncoveredLines: [],
+            uncoveredBranches: [],
+        });
+    }
+    const sum = (get) => files.reduce((acc, f) => ({ covered: acc.covered + get(f).covered, total: acc.total + get(f).total }), { covered: 0, total: 0 });
+    const pct = (m) => (m.total > 0 ? (m.covered / m.total) * 100 : 0);
+    return {
+        files,
+        summary: {
+            line: pct(sum(f => f.lines)),
+            branch: pct(sum(f => f.branches)),
+            function: pct(sum(f => f.functions)),
+            statement: pct(sum(f => f.statements)),
+            files: files.length,
+        },
+    };
+}
 /**
  * Parse LCOV info format
  */

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

@@ -5,9 +5,59 @@
  * Covers: assess-quality
  */
 import { ok, err } from '../../shared/types/index.js';
-import { toError } from '../../shared/error-utils.js';
+import { CallerInputError, toError } from '../../shared/error-utils.js';
 import { discoverSourceFiles } from './handler-utils.js';
-import { evaluateQualityEvidence, loadQualityEvidence, } from '../../domains/quality-assessment/quality-evidence.js';
+import { INSUFFICIENT_EVIDENCE, describeMissingMetrics, evaluateQualityEvidence, loadQualityEvidence, } from '../../domains/quality-assessment/quality-evidence.js';
+import { assessEvidenceSufficiency, describeMeasuredFailure, findMeasuredFailures, isMeasuredMetricValue, resolveCoverageOverride, validateRequestedMetrics, } from '../../domains/quality-assessment/evidence-sufficiency.js';
+const DEFAULT_STATIC_METRICS = ['coverage', 'complexity', 'maintainability', 'testability'];
+const UNMEASURED = -1;
+const STATIC_ONLY_NOTE = 'Static analysis only; no quality gate was evaluated. '
+    + 'Call quality_assess with runGate: true (or `aqe quality --gate`) for a pass/fail gate on measured evidence.';
+/** #996: report the -1 sentinel instead of a fabricated number for unmeasured values. */
+function sentinel(value) {
+    return isMeasuredMetricValue(value) ? value : UNMEASURED;
+}
+/** #996 (N3): reject a malformed `metrics` list instead of spreading a string into characters. */
+function requestedMetricsFrom(metrics) {
+    if (metrics === undefined)
+        return DEFAULT_STATIC_METRICS;
+    try {
+        return validateRequestedMetrics(metrics);
+    }
+    catch (error) {
+        throw new CallerInputError(toError(error).message);
+    }
+}
+/**
+ * #996: the user-configured gate coverage threshold (`quality_gate.thresholds.coverage`
+ * in .aqe-ci.yml), found the same way `aqe ci` finds its config. Undefined when
+ * there is no readable config.
+ */
+async function configuredCoverageThreshold(startDir) {
+    try {
+        const { findCIConfigFile, parseCIConfigFile } = await import('../../cli/utils/ci-config.js');
+        const configPath = findCIConfigFile(startDir);
+        if (!configPath)
+            return undefined;
+        const parsed = parseCIConfigFile(configPath);
+        return parsed.success ? parsed.config?.qualityGate.thresholds.coverage : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * #996: coverage limit for measured failures — the request's threshold, else
+ * the configured gate threshold, else the canonical default (undefined).
+ */
+async function coverageOverrideFor(payload) {
+    const requested = payload.thresholdSource === 'default' ? undefined : payload.threshold;
+    if (requested !== undefined && (typeof requested !== 'number' || !Number.isFinite(requested)
+        || requested < 0 || requested > 100)) {
+        throw new CallerInputError('threshold must be a finite number between 0 and 100.');
+    }
+    return resolveCoverageOverride(requested, requested === undefined ? await configuredCoverageThreshold(process.cwd()) : undefined);
+}
 export function registerQualityHandlers(ctx) {
     // Register quality assessment handler - REAL IMPLEMENTATION
     ctx.registerHandler('assess-quality', async (task) => {
@@ -15,13 +65,20 @@ export function registerQualityHandlers(ctx) {
         try {
             // An explicit gate evaluates the same measured, timestamped evidence as
             // `aqe quality --gate`. Static source scores cannot substitute for it.
+            // Missing/stale/malformed evidence throws InsufficientQualityEvidenceError,
+            // whose details (status, unmeasured) travel with the failure.
             if (payload.runGate === true) {
                 const measured = await loadQualityEvidence(ctx.memory);
                 return ok({
                     ...evaluateQualityEvidence(measured),
                     metrics: measured,
+                    evidenceStatus: 'measured',
+                    unmeasured: [],
+                    gateEvaluated: true,
                 });
             }
+            const requestedMetrics = requestedMetricsFrom(payload.metrics);
+            const coverageOverride = await coverageOverrideFor(payload);
             const analyzer = ctx.getQualityAnalyzer();
             const threshold = payload.threshold || 80;
             // Determine source files to analyze
@@ -42,47 +99,76 @@ export function registerQualityHandlers(ctx) {
                 sourceFiles = await discoverSourceFiles(targetDir, { includeTests: false });
             }
             if (sourceFiles.length === 0) {
+                // Nothing was analyzed: every requested metric is unmeasured (#996).
                 return ok({
                     qualityScore: 0,
                     passed: false,
                     threshold,
                     metrics: {
-                        coverage: 0,
-                        complexity: 0,
-                        maintainability: 0,
-                        testability: 0,
+                        coverage: UNMEASURED,
+                        complexity: UNMEASURED,
+                        maintainability: UNMEASURED,
+                        testability: UNMEASURED,
                     },
-                    recommendations: ['No source files found for quality assessment'],
+                    recommendations: [
+                        ...describeMissingMetrics(requestedMetrics),
+                        'No source files found for quality assessment',
+                    ],
                     warning: 'No source files found',
+                    evidenceStatus: INSUFFICIENT_EVIDENCE,
+                    unmeasured: requestedMetrics,
+                    measuredFailures: [],
+                    gateEvaluated: false,
+                    confidence: 0,
+                    note: STATIC_ONLY_NOTE,
                 });
             }
             // Use the real QualityAnalyzerService
             const result = await analyzer.analyzeQuality({
                 sourceFiles,
-                includeMetrics: payload.metrics || ['coverage', 'complexity', 'maintainability', 'testability'],
+                includeMetrics: requestedMetrics,
             });
             if (!result.success) {
                 return result;
             }
             const report = result.value;
-            const passed = report.score.overall >= threshold;
-            // Convert metrics to the expected format
+            // Only metrics the analyzer actually computed count as measured; score
+            // fields carry the -1 sentinel for the rest.
             const metrics = {};
             for (const metric of report.metrics) {
                 metrics[metric.name] = metric.value;
             }
+            // #996: never pass on missing data. A static score computed without a
+            // requested metric (e.g. coverage = -1) is not evidence of quality, and
+            // a measured metric that fails its own limit blocks regardless (N2).
+            const sufficiency = assessEvidenceSufficiency(requestedMetrics, metrics);
+            const measuredFailures = findMeasuredFailures(sufficiency.measured, metrics, { coverage: coverageOverride });
+            const insufficient = sufficiency.evidenceStatus !== 'measured';
+            const passed = !insufficient && measuredFailures.length === 0 && report.score.overall >= threshold;
+            const recommendations = report.recommendations.map(r => `[${r.type}] ${r.title}: ${r.description}`);
             return ok({
                 qualityScore: report.score.overall,
                 passed,
                 threshold,
                 metrics: {
-                    coverage: report.score.coverage,
-                    complexity: report.score.complexity,
-                    maintainability: report.score.maintainability,
-                    security: report.score.security,
+                    coverage: sentinel(metrics.coverage),
+                    complexity: sentinel(metrics.complexity),
+                    maintainability: sentinel(metrics.maintainability),
+                    // The analyzer has no security measurement; never report a placeholder.
+                    security: sentinel(metrics.security),
                     ...metrics,
                 },
-                recommendations: report.recommendations.map(r => `[${r.type}] ${r.title}: ${r.description}`),
+                recommendations: [
+                    ...measuredFailures.map(describeMeasuredFailure),
+                    ...describeMissingMetrics(sufficiency.unmeasured),
+                    ...recommendations,
+                ],
+                evidenceStatus: sufficiency.evidenceStatus,
+                unmeasured: sufficiency.unmeasured,
+                measuredFailures,
+                gateEvaluated: false,
+                confidence: sufficiency.confidence,
+                note: STATIC_ONLY_NOTE,
                 trends: report.trends.map(t => ({
                     metric: t.metric,
                     direction: t.direction,

package/dist/coordination/result-saver.js

@@ -466,10 +466,23 @@ ${data.recommendations.map((r, i) => `${i + 1}. ${r}`).join('\n')}
 `;
     }
     generateQualityReport(data) {
+        // #996: unmeasured metrics (-1 sentinel) are not scores, and a static
+        // analysis run is not a gate — say both plainly.
+        const insufficient = (data.unmeasured?.length ?? 0) > 0 || data.evidenceStatus === 'insufficient-evidence';
+        const status = insufficient ? 'INSUFFICIENT EVIDENCE (not passed)' : data.passed ? 'PASSED' : 'FAILED';
+        const gateLine = data.gateEvaluated === false
+            ? '\n**Quality gate:** Not evaluated (static analysis only)'
+            : '';
+        const unmeasuredLine = insufficient && data.unmeasured?.length
+            ? `\n**Unmeasured:** ${data.unmeasured.join(', ')}`
+            : '';
+        const noRecommendations = data.gateEvaluated === false
+            ? 'No recommendations.'
+            : 'No recommendations - all quality gates passed.';
         return `# Quality Assessment Report
 
 **Generated:** ${new Date().toISOString()}
-**Status:** ${data.passed ? 'PASSED' : 'FAILED'}
+**Status:** ${status}${gateLine}${unmeasuredLine}
 
 ## Quality Score
 
@@ -479,11 +492,11 @@ ${typeof data.qualityScore === 'number' ? `**${data.qualityScore.toFixed(1)}** /
 
 | Metric | Score |
 |--------|-------|
-${Object.entries(data.metrics).map(([k, v]) => `| ${k} | ${v.toFixed(1)} |`).join('\n')}
+${Object.entries(data.metrics).map(([k, v]) => `| ${k} | ${Number.isFinite(v) && v >= 0 ? v.toFixed(1) : 'not measured'} |`).join('\n')}
 
 ## Recommendations
 
-${data.recommendations.length === 0 ? 'No recommendations - all quality gates passed.' : data.recommendations.map((r, i) => `${i + 1}. ${r}`).join('\n')}
+${data.recommendations.length === 0 ? noRecommendations : data.recommendations.map((r, i) => `${i + 1}. ${r}`).join('\n')}
 `;
     }
     // ==========================================================================
@@ -544,6 +557,7 @@ ${data.recommendations.length === 0 ? 'No recommendations - all quality gates pa
                 return {
                     qualityScore: data.qualityScore,
                     passed: data.passed,
+                    ...(data.evidenceStatus !== undefined ? { evidenceStatus: data.evidenceStatus } : {}),
                 };
             case 'generate-tests':
                 return {

package/dist/coordination/task-executor.d.ts

@@ -44,6 +44,11 @@ export interface TaskResult {
     domain: DomainName;
     /** Files saved by result saver */
     savedFiles?: string[];
+    /**
+     * #996: structured context for a failure (which quality metrics were
+     * unmeasured). Only set for InsufficientQualityEvidenceError; absent otherwise.
+     */
+    errorDetails?: Record<string, unknown>;
 }
 export declare class DomainTaskExecutor implements TaskHandlerContext {
     private readonly kernel;

package/dist/coordination/task-executor.js

@@ -14,6 +14,7 @@
  */
 import { v4 as uuidv4 } from 'uuid';
 import { isCallerInputError, toErrorMessage } from '../shared/error-utils.js';
+import { InsufficientQualityEvidenceError } from '../domains/quality-assessment/quality-evidence.js';
 import { createResultSaver } from './result-saver.js';
 import { createLogger } from '../logging/logger-factory.js';
 import { getClaudeModelForTier } from '../shared/llm/model-registry.js';
@@ -53,6 +54,10 @@ function resolveQualityAnalyzerService(memory) {
     const factory = DomainServiceRegistry.resolve(ServiceKeys.QualityAnalyzerService);
     return factory(memory);
 }
+/** #996: structured details, only from the one error type that is known to carry them. */
+function errorDetailsOf(error) {
+    return error instanceof InsufficientQualityEvidenceError ? { ...error.toDetails() } : undefined;
+}
 // ============================================================================
 // ADR-051: Model Routing Support
 // ============================================================================
@@ -439,12 +444,14 @@ export class DomainTaskExecutor {
                 await this.publishTaskFailed(task.id, errorMsg, domain, 'error' in result && isCallerInputError(result.error));
                 // ADR-051: Record failed outcome
                 this.recordOutcome(task, routingTier, false, Date.now() - startTime).catch((e) => { logger.warn('recordOutcome failed', { error: e instanceof Error ? e.message : String(e), taskId: task.id }); });
+                const errorDetails = 'error' in result ? errorDetailsOf(result.error) : undefined;
                 return {
                     taskId: task.id,
                     success: false,
                     error: errorMsg,
                     duration: Date.now() - startTime,
                     domain,
+                    ...(errorDetails ? { errorDetails } : {}),
                 };
             }
             await this.publishTaskCompleted(task.id, result.value, domain);

package/dist/domains/code-intelligence/coordinator.d.ts

@@ -261,7 +261,8 @@ export declare class CodeIntelligenceCoordinator extends BaseDomainCoordinator<C
      */
     getMetricCollector(): IMetricCollectorService | undefined;
     /**
-     * Determine project root from indexed paths
+     * Determine project root from indexed paths (nearest marker, bottom-up; #994).
+     * Relative paths resolve against the process cwd, matching the CLI/MCP callers.
      */
     private getProjectRootFromPaths;
     /**