agentic-qe 3.15.5 → 3.15.6

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

@@ -30,6 +30,18 @@ import * as os from 'os';
 import * as path from 'path';
 import { safeJsonParse } from '../../shared/safe-json.js';
 import { loadCoverageReportFile } from './coverage-target.js';
+/**
+ * Outcome of a coverage run's tests (#1027 NB2): 'failed' when the runner's
+ * own result reports a failed test or test suite, 'passed' when it reports
+ * none — whatever the exit code (a coverage-threshold failure exits 1 with
+ * every test passing). Without counts (nyc), the exit code decides.
+ */
+export function testRunStatus(run) {
+    if (typeof run.numFailedTests === 'number' || typeof run.numFailedTestSuites === 'number') {
+        return (run.numFailedTests ?? 0) > 0 || (run.numFailedTestSuites ?? 0) > 0 ? 'failed' : 'passed';
+    }
+    return run.exitedCleanly ? 'passed' : 'failed';
+}
 const RESULTS_FILE = 'test-results.json';
 const STDERR_TAIL_BYTES = 2048;
 const STDERR_HEAD_BYTES = 4096;
@@ -92,13 +104,79 @@ function readDeps(projectRoot) {
         return {};
     }
 }
+const RUNNER_DEPS = ['jest', '@jest/core', 'mocha', 'nyc', 'vitest'];
+/**
+ * The project and its ancestors up to the repository / workspace root: the
+ * project itself, then each parent, stopping after the directory holding
+ * `.git` (or a `workspaces` manifest), at $HOME, or after `maxDepth` levels.
+ */
+function projectAndAncestors(projectRoot, maxDepth = 10) {
+    const dirs = [];
+    let home = null;
+    try {
+        home = fs.realpathSync(os.homedir());
+    }
+    catch {
+        home = null;
+    }
+    let dir = path.resolve(projectRoot);
+    for (let i = 0; i <= maxDepth; i++) {
+        if (i > 0 && home !== null && dir === home)
+            break;
+        dirs.push(dir);
+        if (fs.existsSync(path.join(dir, '.git')) || isWorkspaceRoot(dir))
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return dirs;
+}
+function isWorkspaceRoot(dir) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+        return pkg.workspaces !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Dependencies that decide the runner (#1012): the package's own when it
+ * declares a test runner, otherwise those of the nearest ancestor (workspace
+ * root) that does. A package of a monorepo whose jest is declared only at the
+ * root runs jest, not the vitest default.
+ */
+function readRunnerDeps(projectRoot) {
+    for (const dir of projectAndAncestors(projectRoot)) {
+        const deps = readDeps(dir);
+        if (RUNNER_DEPS.some(d => deps[d]))
+            return deps;
+    }
+    return {};
+}
+/**
+ * Every `node_modules/.bin` from the project up to the workspace root,
+ * nearest first. Runners that shell out to sibling tools (nyc → mocha) need
+ * the hoisted ones too (#1012).
+ */
+export function runnerBinDirs(projectRoot) {
+    return projectAndAncestors(projectRoot)
+        .map(dir => path.join(dir, 'node_modules', '.bin'))
+        .filter(dir => fs.existsSync(dir));
+}
+/** Is the project installed with Yarn Plug'n'Play (no node_modules to resolve from)? */
+function usesPlugNPlay(projectRoot) {
+    return projectAndAncestors(projectRoot).some(dir => fs.existsSync(path.join(dir, '.pnp.cjs')) || fs.existsSync(path.join(dir, '.pnp.js')));
+}
 /**
  * Pick the runner and its argv. No shell is involved: `command` is the Node
  * binary and `args[0]` the runner's JS entry, so paths are passed verbatim.
  */
 export function buildJsCoverageInvocation(projectRoot, reportDir) {
     const resultsFile = path.join(reportDir, RESULTS_FILE);
-    const deps = readDeps(projectRoot);
+    const deps = readRunnerDeps(projectRoot);
     let runner = 'vitest';
     let runnerArgs;
     let results = resultsFile;
@@ -117,8 +195,10 @@ export function buildJsCoverageInvocation(projectRoot, reportDir) {
         // vitest is the default — covers vitest, @vitest/coverage-v8, etc.
         // Plain `--outputFile=` (not `.json=`): it overrides a string, object, or
         // absent `outputFile` in the user's config alike.
+        // #1027 N4: vitest writes no coverage when a test fails unless asked;
+        // coverage from a failing suite is still a measurement (runStatus 'failed').
         runnerArgs = ['run', '--coverage', `--coverage.reportsDirectory=${reportDir}`,
-            '--coverage.reporter=json', '--reporter=json', `--outputFile=${resultsFile}`];
+            '--coverage.reporter=json', '--coverage.reportOnFailure=true', '--reporter=json', `--outputFile=${resultsFile}`];
     }
     const bin = findPackageBin(projectRoot, runner === 'jest' ? 'jest' : runner);
     return {
@@ -128,15 +208,23 @@ export function buildJsCoverageInvocation(projectRoot, reportDir) {
         resultsFile: results,
     };
 }
-function readNumTotalTests(resultsFile) {
+const NO_COUNTS = {
+    numTotalTests: null, numPassedTests: null, numFailedTests: null, numPendingTests: null, numFailedTestSuites: null,
+};
+/** Test counts from the runner's own JSON result (vitest/jest share the shape). */
+function readRunCounts(resultsFile) {
     if (!resultsFile)
-        return null;
+        return NO_COUNTS;
     try {
         const parsed = JSON.parse(fs.readFileSync(resultsFile, 'utf-8'));
-        return typeof parsed.numTotalTests === 'number' ? parsed.numTotalTests : null;
+        const n = (k) => (typeof parsed[k] === 'number' ? parsed[k] : null);
+        return {
+            numTotalTests: n('numTotalTests'), numPassedTests: n('numPassedTests'), numFailedTests: n('numFailedTests'),
+            numPendingTests: n('numPendingTests'), numFailedTestSuites: n('numFailedTestSuites'),
+        };
     }
     catch {
-        return null;
+        return NO_COUNTS;
     }
 }
 /**
@@ -311,15 +399,16 @@ export async function runJsCoverage(projectRoot, options = {}) {
                 timeoutMs, data: null, numTotalTests: null, stderrTail: '',
             };
         }
-        // Runners that shell out to sibling tools (nyc → mocha) find them here.
-        const binDir = path.join(projectRoot, 'node_modules', '.bin');
+        // Runners that shell out to sibling tools (nyc → mocha) find them here,
+        // including hoisted workspace-root installs (#1012).
+        const binDirs = runnerBinDirs(projectRoot);
         // The runner's own temp files (vite's SSR cache, etc.) go inside reportDir
         // too, so a killed run leaves nothing behind in the system temp dir.
         const runnerTmp = path.join(reportDir, 'tmp');
         fs.mkdirSync(runnerTmp);
         const env = {
             ...process.env,
-            PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ''}`,
+            PATH: [...binDirs, process.env.PATH ?? ''].join(path.delimiter),
             TMPDIR: runnerTmp, TMP: runnerTmp, TEMP: runnerTmp,
         };
         const run = await runProcessTree(inv.command, inv.args, {
@@ -334,7 +423,7 @@ export async function runJsCoverage(projectRoot, options = {}) {
             timedOut: run.timedOut,
             timeoutMs,
             data,
-            numTotalTests: run.timedOut ? null : readNumTotalTests(inv.resultsFile),
+            ...(run.timedOut ? NO_COUNTS : readRunCounts(inv.resultsFile)),
             stderrTail: run.stderrTail,
         };
     }
@@ -350,6 +439,12 @@ export async function runJsCoverage(projectRoot, options = {}) {
  * Never "No instrumentation ran" when the runner did run and failed.
  */
 export function describeRunFailure(run, projectRoot) {
+    if (run.missing && usesPlugNPlay(projectRoot)) {
+        return `${run.runner} could not be resolved for ${projectRoot}: this project uses Yarn Plug'n'Play, ` +
+            'and agentic-qe resolves test runners only from node_modules. Nothing was run and nothing was downloaded. ' +
+            `Generate a coverage report (e.g. \`yarn ${run.runner} --coverage\`) and pass it as the target, ` +
+            'or use the node-modules linker.';
+    }
     if (run.missing) {
         return `${run.runner} is not installed in ${projectRoot} (no node_modules/${run.runner} found); ` +
             'nothing was run and nothing was downloaded. Install it, or generate a coverage report and pass it as the target.';

package/dist/coordination/handlers/coverage-target.d.ts

@@ -118,6 +118,7 @@ export declare function thresholdVerdict(summary: {
 }, threshold: number, collected: {
     branch: boolean;
     function: boolean;
+    statement?: boolean;
 }): {
     overall: number;
     meetsThreshold: boolean;

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

@@ -254,7 +254,10 @@ export async function resolveExistingCoverage(targetPath) {
  * 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];
+    // #1027 N7: lcov / Cobertura carry no statement data; it is left out too.
+    const metrics = [summary.line];
+    if (collected.statement !== false)
+        metrics.push(summary.statement);
     if (collected.branch)
         metrics.push(summary.branch);
     if (collected.function)

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

@@ -11,7 +11,10 @@ import type { CoverageAnalyzerService } from '../../domains/coverage-analysis';
 import type { SecurityScannerService } from '../../domains/security-compliance';
 import type { TestGeneratorService } from '../../domains/test-generation';
 import type { KnowledgeGraphService } from '../../domains/code-intelligence';
+import type { ICodeIntelligenceCoordinator } from '../../domains/code-intelligence/coordinator';
 import type { QualityAnalyzerService } from '../../domains/quality-assessment';
+/** The coordinator surface the MCP index-code handler needs (#999). */
+export type ProjectMetricsCollector = Pick<ICodeIntelligenceCoordinator, 'collectProjectMetrics'>;
 /** Signature of a single task handler */
 export type InstanceTaskHandler = (task: QueenTask) => Promise<Result<unknown, Error>>;
 /**
@@ -33,6 +36,12 @@ export interface TaskHandlerContext {
      */
     getTestGenerator(useLLM?: boolean): Promise<TestGeneratorService>;
     getKnowledgeGraph(): KnowledgeGraphService;
+    /**
+     * #999 MCP-CLI parity: the code-intelligence coordinator, whose
+     * collectProjectMetrics step `aqe code index` runs. Resolves to undefined when
+     * the domain is unavailable. Optional so lightweight contexts can omit it.
+     */
+    getCodeIntelligenceCoordinator?(): Promise<ProjectMetricsCollector | undefined>;
     getQualityAnalyzer(): QualityAnalyzerService;
     /** Executor configuration */
     readonly config: {

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

@@ -75,7 +75,20 @@ export interface IstanbulFileCoverage {
  */
 export declare function loadCoverageData(targetPath: string): Promise<CoverageData | null>;
 /**
- * Parse Istanbul/nyc coverage-final.json format
+ * Per-line hit counts of one istanbul file entry, computed the way istanbul's
+ * own `FileCoverage#getLineCoverage` (and therefore coverage-summary.json
+ * `lines` and lcov.info `DA:` records) does: each statement counts on its
+ * START line, and a line's count is the highest count of the statements that
+ * start on it. A line is covered when any statement on it ran (#1012).
+ */
+export declare function istanbulLineHits(fd: Pick<IstanbulFileCoverage, 'statementMap' | 's'>): Map<number, number>;
+/**
+ * Parse Istanbul/nyc coverage-final.json format.
+ *
+ * #1012: `lines` are SOURCE LINES (derived from `statementMap` start lines,
+ * as istanbul's own summary does), not statements. Before, statement counts
+ * were reported as "line", so one project had two different line figures
+ * depending on whether coverage-final.json or lcov.info was read.
  */
 export declare function parseCoverageJson(content: string): CoverageData;
 /**

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

@@ -6,6 +6,7 @@
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
+import { isAqeManagedDir } from '../../shared/aqe-managed-dirs.js';
 import { safeJsonParse } from '../../shared/safe-json.js';
 // ============================================================================
 // Coverage Data Loaders
@@ -52,7 +53,32 @@ export async function loadCoverageData(targetPath) {
     return null;
 }
 /**
- * Parse Istanbul/nyc coverage-final.json format
+ * Per-line hit counts of one istanbul file entry, computed the way istanbul's
+ * own `FileCoverage#getLineCoverage` (and therefore coverage-summary.json
+ * `lines` and lcov.info `DA:` records) does: each statement counts on its
+ * START line, and a line's count is the highest count of the statements that
+ * start on it. A line is covered when any statement on it ran (#1012).
+ */
+export function istanbulLineHits(fd) {
+    const lineHits = new Map();
+    const statementMap = fd.statementMap || {};
+    for (const [id, count] of Object.entries(fd.s || {})) {
+        const line = statementMap[id]?.start?.line;
+        if (typeof line !== 'number')
+            continue;
+        const prev = lineHits.get(line);
+        if (prev === undefined || prev < count)
+            lineHits.set(line, count);
+    }
+    return lineHits;
+}
+/**
+ * Parse Istanbul/nyc coverage-final.json format.
+ *
+ * #1012: `lines` are SOURCE LINES (derived from `statementMap` start lines,
+ * as istanbul's own summary does), not statements. Before, statement counts
+ * were reported as "line", so one project had two different line figures
+ * depending on whether coverage-final.json or lcov.info was read.
  */
 export function parseCoverageJson(content) {
     const data = safeJsonParse(content);
@@ -63,30 +89,21 @@ export function parseCoverageJson(content) {
     let totalStatements = 0, coveredStatements = 0;
     for (const [filePath, fileData] of Object.entries(data)) {
         const fd = fileData;
-        // Calculate file-level metrics
-        const lineMap = fd.statementMap || {};
-        const lineCounts = fd.s || {};
+        const statementCounts = fd.s || {};
         const branchMap = fd.branchMap || {};
         const branchCounts = fd.b || {};
         const fnCounts = fd.f || {};
-        const fileLines = Object.keys(lineCounts).length;
-        const fileCoveredLines = Object.values(lineCounts).filter((v) => v > 0).length;
+        const lineHits = istanbulLineHits(fd);
+        const fileLines = lineHits.size;
+        const fileCoveredLines = [...lineHits.values()].filter(v => v > 0).length;
         const fileBranches = Object.values(branchCounts).flat().length;
         const fileCoveredBranches = Object.values(branchCounts).flat().filter((v) => v > 0).length;
         const fileFunctions = Object.keys(fnCounts).length;
         const fileCoveredFunctions = Object.values(fnCounts).filter((v) => v > 0).length;
-        const fileStatements = Object.keys(lineMap).length;
-        const fileCoveredStatements = Object.values(lineCounts).filter((v) => v > 0).length;
-        // Find uncovered lines
-        const uncoveredLines = [];
-        for (const [key, count] of Object.entries(lineCounts)) {
-            if (count === 0) {
-                const stmtInfo = lineMap[key];
-                if (stmtInfo?.start?.line) {
-                    uncoveredLines.push(stmtInfo.start.line);
-                }
-            }
-        }
+        const fileStatements = Object.keys(statementCounts).length;
+        const fileCoveredStatements = Object.values(statementCounts).filter((v) => v > 0).length;
+        // Uncovered lines: lines no statement on which ran.
+        const uncoveredLines = [...lineHits.entries()].filter(([, hits]) => hits === 0).map(([line]) => line);
         // Find uncovered branches
         const uncoveredBranches = [];
         for (const [branchId, counts] of Object.entries(branchCounts)) {
@@ -103,7 +120,7 @@ export function parseCoverageJson(content) {
             branches: { covered: fileCoveredBranches, total: fileBranches },
             functions: { covered: fileCoveredFunctions, total: fileFunctions },
             statements: { covered: fileCoveredStatements, total: fileStatements },
-            uncoveredLines: Array.from(new Set(uncoveredLines)).sort((a, b) => a - b),
+            uncoveredLines: uncoveredLines.sort((a, b) => a - b),
             uncoveredBranches: Array.from(new Set(uncoveredBranches)).sort((a, b) => a - b),
         });
         totalLines += fileLines;
@@ -218,7 +235,8 @@ export function parseLcovInfo(content) {
                 lines: { covered: linesCovered, total: linesTotal },
                 branches: { covered: branchesCovered, total: branchesTotal },
                 functions: { covered: functionsCovered, total: functionsTotal },
-                statements: { covered: linesCovered, total: linesTotal },
+                // #1027 N7: lcov has no statement detail — not collected, not a copy of lines.
+                statements: { covered: 0, total: 0 },
                 uncoveredLines: Array.from(new Set(uncoveredLines)),
                 uncoveredBranches: Array.from(new Set(uncoveredBranches)),
             });
@@ -355,7 +373,8 @@ export function parseCoberturaXml(content) {
             lines: { covered: linesCovered, total: linesTotal },
             branches: { covered: branchesCovered, total: branchesTotal },
             functions: { covered: functionsCovered, total: functionsTotal },
-            statements: { covered: linesCovered, total: linesTotal },
+            // #1027 N7: Cobertura has no statement detail — not collected.
+            statements: { covered: 0, total: 0 },
             uncoveredLines,
             uncoveredBranches,
         });
@@ -449,11 +468,16 @@ export async function discoverSourceFiles(targetPath, options = {}) {
                     if (['node_modules', '.git', 'dist', 'build', 'coverage', '.nyc_output',
                         '__pycache__', '.venv', 'venv', '.tox', '.mypy_cache', 'target',
                         '.gradle', 'vendor', '.bundle',
-                        '.agentic-qe', '.claude', '.cache', '.npm', '.yarn',
+                        '.cache', '.npm', '.yarn',
                         '.next', '.nuxt', '.svelte-kit', 'out', '.turbo',
                         'tmp', 'temp', '.tmp'].includes(entry.name)) {
                         continue;
                     }
+                    // #999: AQE state/assets are not source: .agentic-qe anywhere; .claude at
+                    // the root or next to a nested .agentic-qe. A plugin's own .claude/hooks
+                    // source (no AQE install beside it) is kept.
+                    if (isAqeManagedDir(dir, entry.name, dir === targetPath))
+                        continue;
                     if (files.length >= maxFiles)
                         return; // Cap reached
                     await walkDir(fullPath);

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

@@ -4,9 +4,12 @@
  * Extracted from task-executor.ts registerHandlers().
  * Covers: assess-quality
  */
+import * as nodePath from 'node:path';
+import { existsSync, promises as fsp } from 'node:fs';
 import { ok, err } from '../../shared/types/index.js';
 import { CallerInputError, toError } from '../../shared/error-utils.js';
 import { discoverSourceFiles } from './handler-utils.js';
+import { findProjectRoot } from '../../kernel/project-root.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'];
@@ -17,6 +20,91 @@ const STATIC_ONLY_NOTE = 'Static analysis only; no quality gate was evaluated. '
 function sentinel(value) {
     return isMeasuredMetricValue(value) ? value : UNMEASURED;
 }
+/**
+ * #1011: why each unmeasured metric has no value — the analyzer's reason
+ * (unreadable or unparseable file, failed detection, no stored coverage).
+ */
+function unmeasuredReasons(unmeasured, reported) {
+    const byMetric = new Map((reported ?? []).map((u) => [u.metric, u.reason]));
+    return Object.fromEntries(unmeasured.map((metric) => [
+        metric,
+        byMetric.get(metric) ?? (metric === 'security'
+            ? 'static analysis never measures security'
+            : 'the static analyzer produced no measured value'),
+    ]));
+}
+/** Cap on excluded files echoed back in the result (the count is always exact). */
+const MAX_EXCLUDED_LISTED = 50;
+/** True when `candidate` is `root` or lies beneath it. */
+function isWithin(root, candidate) {
+    const relative = nodePath.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${nodePath.sep}`) && !nodePath.isAbsolute(relative));
+}
+/**
+ * #1021 (B2): resolve a caller path against the project root and require it to
+ * stay inside — lexically, and by realpath when it exists (so a symlink cannot
+ * lead outside). A path that does not exist is returned as resolved; the
+ * analyzer reports it as unreadable.
+ */
+async function resolveContained(input, root, label) {
+    const resolved = nodePath.resolve(root, input);
+    if (input.includes('\0') || !isWithin(root, resolved)) {
+        throw new CallerInputError(`${label} ${JSON.stringify(input)} is outside the project root (${root}).`);
+    }
+    let real;
+    try {
+        real = await fsp.realpath(resolved);
+    }
+    catch {
+        return resolved;
+    }
+    const rootReal = await fsp.realpath(root).catch(() => root);
+    if (!isWithin(rootReal, real)) {
+        throw new CallerInputError(`${label} ${JSON.stringify(input)} resolves outside the project root (${root}).`);
+    }
+    return resolved;
+}
+/**
+ * #1021 (B2): the files to analyse and which of them the caller named. Explicit
+ * sourceFiles win over target; with neither, src/ (else the root) is analysed.
+ */
+async function resolveAnalysisScope(payload) {
+    // #1021 round 2b: the AQE project root (AQE_PROJECT_ROOT, else detected),
+    // not the process cwd — an MCP server may run from another directory.
+    const root = findProjectRoot();
+    if (Array.isArray(payload.sourceFiles) && payload.sourceFiles.length > 0) {
+        const files = [];
+        for (const file of payload.sourceFiles) {
+            if (typeof file !== 'string' || file.trim() === '') {
+                throw new CallerInputError('sourceFiles must be a non-empty array of file paths.');
+            }
+            files.push(await resolveContained(file, root, 'sourceFile'));
+        }
+        return { sourceFiles: files, explicitFiles: files, scope: 'sourceFiles' };
+    }
+    if (typeof payload.target === 'string' && payload.target.trim() !== '') {
+        const target = await resolveContained(payload.target, root, 'target');
+        const stat = await fsp.stat(target).catch(() => null);
+        if (!stat)
+            throw new CallerInputError(`target ${JSON.stringify(payload.target)} does not exist.`);
+        if (stat.isFile())
+            return { sourceFiles: [target], explicitFiles: [target], scope: target };
+        return { sourceFiles: await discoverSourceFiles(target, { includeTests: false }), explicitFiles: [], scope: target };
+    }
+    // Default to src/ — scanning the entire project root is too slow
+    // (node_modules, dist, .git, etc. make it hang on large projects)
+    const srcDir = nodePath.join(root, 'src');
+    const targetDir = existsSync(srcDir) ? srcDir : root;
+    return { sourceFiles: await discoverSourceFiles(targetDir, { includeTests: false }), explicitFiles: [], scope: targetDir };
+}
+/** #1021: one line per partially measured metric, naming the gap. */
+function describePartialMetrics(partial) {
+    return (partial ?? []).map((p) => `Partial evidence: ${p.metric} measured over ${p.analysedFiles} of ${p.totalFiles} `
+        // coverageOfScope is already rounded down to 3 decimals; round only float noise here.
+        + `file(s) (${Math.round(p.coverageOfScope * 1000) / 10}%); not analysed: `
+        + p.failed.slice(0, 3).map((f) => f.reason).join('; ')
+        + (p.failed.length > 3 ? `; and ${p.failed.length - 3} more` : '') + '.');
+}
 /** #996 (N3): reject a malformed `metrics` list instead of spreading a string into characters. */
 function requestedMetricsFrom(metrics) {
     if (metrics === undefined)
@@ -81,27 +169,13 @@ export function registerQualityHandlers(ctx) {
             const coverageOverride = await coverageOverrideFor(payload);
             const analyzer = ctx.getQualityAnalyzer();
             const threshold = payload.threshold || 80;
-            // Determine source files to analyze
-            let sourceFiles = [];
-            if (payload.sourceFiles && payload.sourceFiles.length > 0) {
-                sourceFiles = payload.sourceFiles;
-            }
-            else if (payload.target) {
-                sourceFiles = await discoverSourceFiles(payload.target, { includeTests: false });
-            }
-            else {
-                // Default to src/ — scanning the entire project root is too slow
-                // (node_modules, dist, .git, etc. make it hang on large projects)
-                const path = await import('path');
-                const fs = await import('fs');
-                const srcDir = path.join(process.cwd(), 'src');
-                const targetDir = fs.existsSync(srcDir) ? srcDir : process.cwd();
-                sourceFiles = await discoverSourceFiles(targetDir, { includeTests: false });
-            }
+            // #1021 (B2): analyse what the caller scoped, contained in the project root.
+            const { sourceFiles, explicitFiles, scope } = await resolveAnalysisScope(payload);
             if (sourceFiles.length === 0) {
                 // Nothing was analyzed: every requested metric is unmeasured (#996).
                 return ok({
-                    qualityScore: 0,
+                    // #1011: nothing was analysed, so there is no score (-1), not a score of 0.
+                    qualityScore: UNMEASURED,
                     passed: false,
                     threshold,
                     metrics: {
@@ -117,6 +191,7 @@ export function registerQualityHandlers(ctx) {
                     warning: 'No source files found',
                     evidenceStatus: INSUFFICIENT_EVIDENCE,
                     unmeasured: requestedMetrics,
+                    unmeasuredReasons: Object.fromEntries(requestedMetrics.map((m) => [m, 'no source files found to analyse'])),
                     measuredFailures: [],
                     gateEvaluated: false,
                     confidence: 0,
@@ -127,6 +202,7 @@ export function registerQualityHandlers(ctx) {
             const result = await analyzer.analyzeQuality({
                 sourceFiles,
                 includeMetrics: requestedMetrics,
+                explicitFiles,
             });
             if (!result.success) {
                 return result;
@@ -156,13 +232,27 @@ export function registerQualityHandlers(ctx) {
                     maintainability: sentinel(metrics.maintainability),
                     // The analyzer has no security measurement; never report a placeholder.
                     security: sentinel(metrics.security),
+                    // #1011: every requested metric appears, -1 when unmeasured.
+                    ...Object.fromEntries(requestedMetrics.map((name) => [name, sentinel(metrics[name])])),
                     ...metrics,
                 },
+                unmeasuredReasons: unmeasuredReasons(sufficiency.unmeasured, report.unmeasured),
+                // #1021 round 2b: a score over a subset of the requested metrics (or over
+                // part of the files) names what it is based on — it is not a verdict.
+                ...(insufficient || (report.partial?.length ?? 0) > 0
+                    ? { scoreBasis: report.metrics.map((m) => m.name) }
+                    : {}),
                 recommendations: [
                     ...measuredFailures.map(describeMeasuredFailure),
                     ...describeMissingMetrics(sufficiency.unmeasured),
+                    ...describePartialMetrics(report.partial),
                     ...recommendations,
                 ],
+                ...(report.partial && report.partial.length > 0 ? { partialMetrics: report.partial } : {}),
+                ...(report.excluded && report.excluded.length > 0
+                    ? { excludedFiles: report.excluded.slice(0, MAX_EXCLUDED_LISTED), excludedCount: report.excluded.length }
+                    : {}),
+                scope,
                 evidenceStatus: sufficiency.evidenceStatus,
                 unmeasured: sufficiency.unmeasured,
                 measuredFailures,

package/dist/coordination/handlers/test-execution-handlers.js

@@ -222,7 +222,10 @@ export function registerTestExecutionHandlers(ctx) {
                         const executionError = getTestRunnerExecutionError(runner, testFiles.join(', '), execution.status, { passed, failed, skipped }, diagnostics, json);
                         if (executionError)
                             return err(executionError);
-                        return ok({ total, passed, failed, skipped, duration: 0, coverage: 0, failedTests: [] });
+                        // #1027 N5/NB5: this handler runs the tests without --coverage, so it has no
+                        // coverage figure to return (null, never 0%). For test_execute_parallel the
+                        // measured coverage + testsPassing are recorded by TestExecutorService.
+                        return ok({ total, passed, failed, skipped, duration: 0, coverage: null, failedTests: [] });
                     }
                 }
             }

package/dist/coordination/protocols/defect-investigation.d.ts

@@ -64,7 +64,8 @@ export interface RelatedFailure {
 export interface CoverageContext {
     file: string;
     lineCoverage: number;
-    branchCoverage: number;
+    /** `null` = no branch data was collected (#1027 NB4) — never a borrowed figure. */
+    branchCoverage: number | null;
     uncoveredLines: number[];
     riskScore: number;
 }

package/dist/coordination/protocols/defect-investigation.js

@@ -12,6 +12,7 @@ import { createEvent } from '../../shared/events/domain-events.js';
 import { toError } from '../../shared/error-utils.js';
 import { LoggerFactory } from '../../logging/index.js';
 import { addToCount } from '../../shared/utils/safe-record.js';
+import { measuredFileCoverage } from '../../domains/quality-assessment/coverage-report-event.js';
 const logger = LoggerFactory.create('defect-investigation');
 export const DefectInvestigationEvents = {
     DefectInvestigationStarted: 'coordination.DefectInvestigationStarted',
@@ -605,12 +606,14 @@ export class DefectInvestigationProtocol {
     async getCoverageContext(file) {
         try {
             // Try per-file coverage (written by coverage-analyzer and test-executor)
-            const coverage = await this.memory.get(`coverage:file:${file}`);
+            // #1014: only measured records; legacy unstamped estimates are ignored.
+            const coverage = measuredFileCoverage(await this.memory.get(`coverage:file:${file}`));
             if (!coverage) {
                 return null;
             }
-            // Calculate risk based on coverage
-            const avgCoverage = (coverage.line + coverage.branch) / 2;
+            // Calculate risk based on coverage (an uncollected branch metric is
+            // left out, not counted as 0%).
+            const avgCoverage = coverage.branch === null ? coverage.line : (coverage.line + coverage.branch) / 2;
             const riskScore = 1 - avgCoverage / 100;
             return {
                 file,

package/dist/coordination/protocols/quality-gate.js

@@ -10,6 +10,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { ok, err, } from '../../shared/types/index.js';
 import { createEvent } from '../../shared/events/domain-events.js';
 import { toErrorMessage, toError } from '../../shared/error-utils.js';
+import { measuredCoverageSummary } from '../../domains/quality-assessment/coverage-report-event.js';
 // ============================================================================
 // Protocol Events
 // ============================================================================
@@ -402,12 +403,14 @@ export class QualityGateProtocol {
     async getCoverageMetrics(_releaseCandidate) {
         try {
             // Try to get latest coverage data from memory
-            const latestCoverage = await this.memory.get('coverage:latest');
+            // #1014: only a measured record is coverage evidence; a legacy
+            // unstamped or estimated record is "no data" (the gate fails closed).
+            const latestCoverage = measuredCoverageSummary(await this.memory.get('coverage:latest'));
             if (!latestCoverage) {
                 return null;
             }
-            // Get previous coverage for trend
-            const previousCoverage = await this.memory.get('coverage:previous');
+            // Get previous coverage for trend (measured baselines only, #1015)
+            const previousCoverage = measuredCoverageSummary(await this.memory.get('coverage:previous'));
             let trend = 'stable';
             if (previousCoverage) {
                 const delta = latestCoverage.line - previousCoverage.line;
@@ -418,9 +421,10 @@ export class QualityGateProtocol {
             }
             return {
                 line: latestCoverage.line,
-                branch: latestCoverage.branch,
-                function: latestCoverage.function,
-                statement: latestCoverage.statement,
+                // An uncollected metric has no evidence: 0 fails its check closed.
+                branch: latestCoverage.branch ?? 0,
+                function: latestCoverage.function ?? 0,
+                statement: latestCoverage.statement ?? 0,
                 trend,
             };
         }