agentic-qe 3.15.4 → 3.15.6

package/dist/domains/code-intelligence/project-root-resolver.js

@@ -0,0 +1,121 @@
+/**
+ * Project root resolution for code-intelligence metric collection (#994).
+ *
+ * `index()` receives an expanded list of files (the CLI walks the target
+ * directory first). When the caller also passes the original `target`, the
+ * walk starts at the target directory (its parent for a file target), so a `.`
+ * at a monorepo root whose source all lives in one package resolves to the
+ * root. Without a target we start from the deepest directory that contains
+ * every indexed path. Either way we walk UP (bottom-up, using `path.dirname`,
+ * so absolute paths and Windows drive roots are handled by the `path` module)
+ * and return the NEAREST directory that holds a project marker.
+ *
+ * Starting from the common directory rather than the first file keeps a stray
+ * marker inside one subtree (for example `.agentic-qe/workers/package.json`)
+ * from capturing an index that spans the whole project.
+ *
+ * When no marker exists anywhere up to the filesystem root, the start
+ * directory itself is returned (the target, the files' common directory, or a
+ * single file's directory). A filesystem or drive root is never returned:
+ * measuring `/` would walk the whole disk, so the result is null instead.
+ *
+ * @module domains/code-intelligence/project-root-resolver
+ */
+import { existsSync, statSync } from 'node:fs';
+import * as path from 'node:path';
+/** Files or directories whose presence marks a project root. */
+export const PROJECT_ROOT_MARKERS = Object.freeze([
+    'package.json',
+    'Cargo.toml',
+    'go.mod',
+    'pyproject.toml',
+    '.git',
+]);
+function defaultIsDirectory(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `child` is `parent` or lies inside it. */
+function isWithin(p, child, parent) {
+    const rel = p.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !p.isAbsolute(rel));
+}
+/**
+ * Deepest directory containing every input directory, or null when the inputs
+ * share no ancestor (for example different Windows drives).
+ */
+function commonAncestor(p, dirs) {
+    let common = dirs[0];
+    for (const dir of dirs.slice(1)) {
+        while (!isWithin(p, dir, common)) {
+            const parent = p.dirname(common);
+            if (parent === common)
+                return null;
+            common = parent;
+        }
+    }
+    return common;
+}
+/** Walk from `startDir` up to the filesystem root; return the nearest marker directory. */
+function findNearestMarkerDir(p, startDir, exists) {
+    let current = startDir;
+    for (;;) {
+        for (const marker of PROJECT_ROOT_MARKERS) {
+            try {
+                if (exists(p.join(current, marker)))
+                    return current;
+            }
+            catch {
+                // Unreadable entry: keep checking the remaining markers.
+            }
+        }
+        const parent = p.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Resolve the project root for a set of indexed paths.
+ *
+ * @param paths - Files and/or directories, absolute or relative to `options.cwd`
+ * @returns Absolute project root, or null when there is nothing to resolve or
+ *   the result would be a filesystem/drive root
+ */
+export function resolveProjectRootFromPaths(paths, options = {}) {
+    const usable = paths.filter((p) => typeof p === 'string' && p.length > 0);
+    const target = typeof options.target === 'string' && options.target.length > 0 ? options.target : undefined;
+    if (usable.length === 0 && !target)
+        return null;
+    const p = options.pathImpl ?? path;
+    const cwd = options.cwd ?? process.cwd();
+    const exists = options.exists ?? existsSync;
+    const isDirectory = options.isDirectory ?? defaultIsDirectory;
+    // A directory contributes itself; a file contributes its parent directory.
+    const dirOf = (input) => {
+        const abs = p.resolve(cwd, input);
+        return isDirectory(abs) ? abs : p.dirname(abs);
+    };
+    let start;
+    if (target) {
+        // The caller's own target wins over the expanded file list: a `.` at a
+        // monorepo root whose source all lives in packages/a is still the root.
+        start = dirOf(target);
+    }
+    else {
+        const dirs = usable.map(dirOf);
+        // Inputs on different roots (Windows drives): use the first path's directory.
+        start = commonAncestor(p, dirs) ?? dirs[0];
+    }
+    const root = findNearestMarkerDir(p, start, exists) ?? start;
+    // Never measure a whole filesystem / drive root (review N1).
+    return isFilesystemRoot(p, root) ? null : root;
+}
+function isFilesystemRoot(p, dir) {
+    return p.parse(dir).root === dir || p.dirname(dir) === dir;
+}
+//# sourceMappingURL=project-root-resolver.js.map

package/dist/domains/code-intelligence/services/metric-collector/index.js

@@ -14,6 +14,7 @@
  */
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join, extname } from 'path';
+import { AQE_STATE_DIR } from '../../../../shared/aqe-managed-dirs.js';
 import { DEFAULT_METRIC_CONFIG, } from './interfaces.js';
 import { countLOC, checkLOCTools } from './loc-counter.js';
 import { countTests, checkTestRunners } from './test-counter.js';
@@ -211,6 +212,10 @@ export class MetricCollectorService {
         let totalTodos = 0;
         let totalConsole = 0;
         const patterns = this.getPatternsForLanguage(language);
+        // #999: same exclusions as LOC/test counting (.agentic-qe anywhere; .claude at
+        // the root or next to a nested .agentic-qe)
+        const excludeDirs = new Set(this.config.excludeDirs);
+        const rootExcludeDirs = new Set(this.config.excludeRootDirs ?? []);
         function walkDirectory(dirPath) {
             if (!existsSync(dirPath))
                 return;
@@ -219,8 +224,10 @@ export class MetricCollectorService {
                 const fullPath = join(dirPath, entry.name);
                 if (entry.isDirectory()) {
                     // Skip excluded directories
-                    const excludeDirs = ['node_modules', 'dist', 'coverage', 'build', '.git', 'vendor', 'target'];
-                    if (excludeDirs.includes(entry.name))
+                    if (excludeDirs.has(entry.name))
+                        continue;
+                    if (rootExcludeDirs.has(entry.name) &&
+                        (dirPath === projectPath || existsSync(join(dirPath, AQE_STATE_DIR))))
                         continue;
                     walkDirectory(fullPath);
                 }

package/dist/domains/code-intelligence/services/metric-collector/interfaces.d.ts

@@ -130,6 +130,15 @@ export interface MetricCollectorConfig {
     timeout: number;
     /** Directories to exclude from LOC counting */
     excludeDirs: string[];
+    /** File names (exact match) to exclude from LOC counting, e.g. lockfiles (#999) */
+    excludeFiles: string[];
+    /**
+     * Directories excluded directly under the project root, and nested only when
+     * they sit next to a `.agentic-qe/` (a nested `aqe init`): the assets init
+     * writes. Any other directory of the same name (e.g. a plugin's own
+     * `.claude/hooks` source) is still counted (#999 review N4 / round 2b).
+     */
+    excludeRootDirs: string[];
     /** File patterns to include for test counting */
     testPatterns: string[];
     /** Enable caching of metrics (default: true) */
@@ -137,6 +146,18 @@ export interface MetricCollectorConfig {
     /** Cache TTL in milliseconds (default: 300000 = 5 minutes) */
     cacheTTL: number;
 }
+/**
+ * Generated dependency lockfiles. They are machine-written, often thousands of
+ * lines, and are not project code, so LOC counting skips them (#999: a 3-line
+ * project reported 1662 LOC from package-lock.json).
+ */
+export declare const LOC_EXCLUDED_FILE_NAMES: readonly string[];
+/**
+ * Init-written assets: excluded at the project root, and nested only next to a
+ * `.agentic-qe/` (a nested `aqe init`). `.agentic-qe` itself is in excludeDirs
+ * (state, never source, at any depth). #999 review N4 / round 2b.
+ */
+export declare const PROJECT_ROOT_EXCLUDED_DIRS: readonly string[];
 /**
  * Default configuration values
  */

package/dist/domains/code-intelligence/services/metric-collector/interfaces.js

@@ -6,6 +6,27 @@
  *
  * @see docs/plans/AQE_V3_IMPROVEMENTS_PLAN.md - Phase 5
  */
+/**
+ * Generated dependency lockfiles. They are machine-written, often thousands of
+ * lines, and are not project code, so LOC counting skips them (#999: a 3-line
+ * project reported 1662 LOC from package-lock.json).
+ */
+export const LOC_EXCLUDED_FILE_NAMES = Object.freeze([
+    // JS/TS
+    'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lockb', 'bun.lock',
+    'deno.lock',
+    // Python
+    'poetry.lock', 'Pipfile.lock', 'uv.lock', 'pdm.lock',
+    // Rust / Go / Ruby / PHP / Elixir / Dart / .NET / Swift / Nix / Gradle
+    'Cargo.lock', 'go.sum', 'Gemfile.lock', 'composer.lock', 'mix.lock', 'pubspec.lock',
+    'packages.lock.json', 'Package.resolved', 'flake.lock', 'gradle.lockfile',
+]);
+/**
+ * Init-written assets: excluded at the project root, and nested only next to a
+ * `.agentic-qe/` (a nested `aqe init`). `.agentic-qe` itself is in excludeDirs
+ * (state, never source, at any depth). #999 review N4 / round 2b.
+ */
+export const PROJECT_ROOT_EXCLUDED_DIRS = Object.freeze(['.claude']);
 /**
  * Default configuration values
  */
@@ -20,7 +41,11 @@ export const DEFAULT_METRIC_CONFIG = {
         'target', '.gradle', 'vendor', '.bundle',
         // General
         '.git', '.svn', '.hg',
+        // AQE runtime state: never source, at any depth (#999)
+        '.agentic-qe',
     ],
+    excludeFiles: [...LOC_EXCLUDED_FILE_NAMES],
+    excludeRootDirs: [...PROJECT_ROOT_EXCLUDED_DIRS],
     testPatterns: ['**/*.test.ts', '**/*.spec.ts', '**/*.test.js', '**/*.spec.js'],
     enableCache: true,
     cacheTTL: 300000,

package/dist/domains/code-intelligence/services/metric-collector/loc-counter.d.ts

@@ -25,4 +25,16 @@ export declare function countLOC(projectPath: string, config?: Partial<MetricCol
  * Check which LOC counting tools are available
  */
 export declare function checkLOCTools(): ToolAvailability[];
+/**
+ * cloc `--not-match-f` regex matching any of `names` exactly (basename), or
+ * null when there is nothing to exclude.
+ */
+export declare function excludedFileNamesRegex(names: readonly string[] | undefined): string | null;
+/**
+ * cloc `--not-match-d` regex (with --fullpath) matching the given
+ * project-relative directories ('/'-separated) and everything below them, but
+ * no other directory of the same name (#999 review N4 / round 2b). Either
+ * path separator matches. Null when there are none.
+ */
+export declare function rootAnchoredDirsRegex(projectPath: string, relDirs: readonly string[] | undefined): string | null;
 //# sourceMappingURL=loc-counter.d.ts.map

package/dist/domains/code-intelligence/services/metric-collector/loc-counter.js

@@ -14,6 +14,7 @@
 import { spawnSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, extname } from 'path';
+import { AQE_CLAUDE_DIR, AQE_STATE_DIR, findAqeClaudeDirs } from '../../../../shared/aqe-managed-dirs.js';
 import { DEFAULT_METRIC_CONFIG, } from './interfaces.js';
 import { safeJsonParse } from '../../../../shared/safe-json.js';
 // ============================================================================
@@ -77,6 +78,43 @@ export function checkLOCTools() {
     }
     return tools;
 }
+/**
+ * cloc `--not-match-f` regex matching any of `names` exactly (basename), or
+ * null when there is nothing to exclude.
+ */
+export function excludedFileNamesRegex(names) {
+    if (!names || names.length === 0)
+        return null;
+    // Matches a bare name and, under cloc --fullpath, a full path ending in it
+    // (either separator, so Windows paths match too).
+    return `(^|[\\\\/])(${names.map(escapeRegex).join('|')})$`;
+}
+/**
+ * cloc `--not-match-d` regex (with --fullpath) matching the given
+ * project-relative directories ('/'-separated) and everything below them, but
+ * no other directory of the same name (#999 review N4 / round 2b). Either
+ * path separator matches. Null when there are none.
+ */
+export function rootAnchoredDirsRegex(projectPath, relDirs) {
+    if (!relDirs || relDirs.length === 0)
+        return null;
+    const SEP = '[\\\\/]';
+    const toPattern = (path) => path.split(/[\\/]+/).filter(Boolean).map(escapeRegex).join(SEP);
+    const root = toPattern(projectPath);
+    const rootPrefix = /^[\\/]/.test(projectPath) ? SEP : '';
+    return `^${rootPrefix}${root}${SEP}(${relDirs.map(toPattern).join('|')})(${SEP}|$)`;
+}
+/** Project-relative AQE-managed `.claude` dirs to exclude, if `.claude` is a root exclude. */
+function aqeClaudeDirsToExclude(projectPath, config) {
+    const rootDirs = config.excludeRootDirs ?? [];
+    if (!rootDirs.includes(AQE_CLAUDE_DIR))
+        return rootDirs.filter((d) => existsSync(join(projectPath, d)));
+    const others = rootDirs.filter((d) => d !== AQE_CLAUDE_DIR && existsSync(join(projectPath, d)));
+    return [...findAqeClaudeDirs(projectPath, config.excludeDirs), ...others];
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 // ============================================================================
 // Tool-Specific Implementations
 // ============================================================================
@@ -85,7 +123,17 @@ export function checkLOCTools() {
  */
 async function tryClocCount(projectPath, config) {
     try {
-        const args = ['--json', `--exclude-dir=${config.excludeDirs.join(',')}`, projectPath];
+        const args = ['--json', `--exclude-dir=${config.excludeDirs.join(',')}`];
+        const notMatchDir = rootAnchoredDirsRegex(projectPath, aqeClaudeDirsToExclude(projectPath, config));
+        // --fullpath makes --not-match-d/-f see full paths, so the AQE-managed
+        // .claude dirs (root, or next to a nested .agentic-qe) are excluded
+        // without dropping other same-named dirs (#999 review N4 / round 2b).
+        if (notMatchDir)
+            args.push('--fullpath', `--not-match-d=${notMatchDir}`);
+        const notMatch = excludedFileNamesRegex(config.excludeFiles);
+        if (notMatch)
+            args.push(`--not-match-f=${notMatch}`);
+        args.push(projectPath);
         const result = spawnSync('cloc', args, {
             encoding: 'utf-8',
             timeout: config.timeout,
@@ -134,8 +182,19 @@ async function tryTokeiCount(projectPath, config) {
         for (const dir of config.excludeDirs) {
             args.push('-e', dir);
         }
-        args.push(projectPath);
+        // #999: lockfiles are generated, not code (tokei -e takes gitignore-style names)
+        for (const file of config.excludeFiles ?? []) {
+            args.push('-e', file);
+        }
+        // A leading '/' anchors a tokei (gitignore-style) exclude at the directory
+        // tokei walks, so run it IN the project on '.' (round 2b: with an absolute
+        // path argument the anchored patterns matched nothing).
+        for (const rel of aqeClaudeDirsToExclude(projectPath, config)) {
+            args.push('-e', `/${rel}`);
+        }
+        args.push('.');
         const result = spawnSync('tokei', args, {
+            cwd: projectPath,
             encoding: 'utf-8',
             timeout: config.timeout,
             maxBuffer: 10 * 1024 * 1024, // 10MB buffer (reduced for memory safety)
@@ -237,6 +296,8 @@ function manualLOCCount(projectPath, config) {
     const byLanguage = {};
     let total = 0;
     const excludeSet = new Set(config.excludeDirs);
+    const excludeFileSet = new Set(config.excludeFiles ?? []);
+    const rootExcludeSet = new Set(config.excludeRootDirs ?? []);
     // Max file size to read (2MB) — skip minified bundles, generated files
     const MAX_FILE_SIZE = 2 * 1024 * 1024;
     function walkDirectory(dirPath, depth) {
@@ -255,12 +316,17 @@ function manualLOCCount(projectPath, config) {
             const fullPath = join(dirPath, entry.name);
             if (entry.isDirectory()) {
                 // Skip excluded directories (exact match or glob-like suffix match)
-                if (excludeSet.has(entry.name) || entry.name.startsWith('.')) {
+                if (excludeSet.has(entry.name) || entry.name.startsWith('.') ||
+                    (rootExcludeSet.has(entry.name) &&
+                        (dirPath === projectPath || existsSync(join(dirPath, AQE_STATE_DIR))))) {
                     continue;
                 }
                 walkDirectory(fullPath, depth + 1);
             }
             else if (entry.isFile()) {
+                // #999: skip lockfiles and other generated files by exact name
+                if (excludeFileSet.has(entry.name))
+                    continue;
                 const ext = extname(entry.name);
                 const language = getLanguageForExtension(ext);
                 if (language) {

package/dist/domains/code-intelligence/services/metric-collector/test-counter.js

@@ -17,6 +17,7 @@ import { createRequire } from 'module';
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'fs';
 import { tmpdir } from 'os';
 import { join, extname, resolve } from 'path';
+import { AQE_STATE_DIR } from '../../../../shared/aqe-managed-dirs.js';
 import { DEFAULT_METRIC_CONFIG, } from './interfaces.js';
 import { safeJsonParse } from '../../../../shared/safe-json.js';
 import { ownListingProcess } from './listing-process-owner.js';
@@ -478,7 +479,9 @@ function countTestsByFilePattern(projectPath, config) {
             const fullPath = join(dirPath, entry.name);
             if (entry.isDirectory()) {
                 // Skip excluded directories
-                if (config.excludeDirs.includes(entry.name)) {
+                if (config.excludeDirs.includes(entry.name) ||
+                    ((config.excludeRootDirs ?? []).includes(entry.name) &&
+                        (dirPath === projectPath || existsSync(join(dirPath, AQE_STATE_DIR))))) {
                     continue;
                 }
                 walkDirectory(fullPath);

package/dist/domains/coverage-analysis/collected-metrics.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Which coverage metrics a report actually collected (#995, #1015, #1027).
+ *
+ * A metric with no data in the report (no branch entries, no functions, no
+ * statement detail — lcov and Cobertura carry none) is "not collected". Its
+ * summary figure is 0 by construction, and must be reported AND persisted as
+ * null — never as 0% (a fake low figure) nor as istanbul's 0/0 = 100%.
+ */
+import type { CoverageSummary, FileCoverage } from './interfaces';
+/**
+ * The ONE key form for per-file coverage records (#1027 N7): the absolute
+ * path. Reports write absolute (istanbul) or project-relative (lcov
+ * `SF:src/a.ts`) paths; a relative one is resolved against the project root
+ * (or the cwd when none is known), so one file never has two records.
+ */
+export declare function fileCoverageKey(filePath: string, projectRoot?: string): string;
+export interface CollectedMetrics {
+    branch: boolean;
+    function: boolean;
+    statement: boolean;
+}
+/** Which optional metrics the files carry. Line coverage is always collected. */
+export declare function collectedMetrics(files: readonly FileCoverage[]): CollectedMetrics;
+/** A summary as it is reported and persisted: uncollected metrics are null. */
+export interface CollectedSummary {
+    line: number;
+    branch: number | null;
+    function: number | null;
+    statement: number | null;
+    files: number;
+}
+export declare function collectedSummary(summary: CoverageSummary, collected: CollectedMetrics): CollectedSummary;
+//# sourceMappingURL=collected-metrics.d.ts.map

package/dist/domains/coverage-analysis/collected-metrics.js

@@ -0,0 +1,36 @@
+/**
+ * Which coverage metrics a report actually collected (#995, #1015, #1027).
+ *
+ * A metric with no data in the report (no branch entries, no functions, no
+ * statement detail — lcov and Cobertura carry none) is "not collected". Its
+ * summary figure is 0 by construction, and must be reported AND persisted as
+ * null — never as 0% (a fake low figure) nor as istanbul's 0/0 = 100%.
+ */
+import * as path from 'path';
+/**
+ * The ONE key form for per-file coverage records (#1027 N7): the absolute
+ * path. Reports write absolute (istanbul) or project-relative (lcov
+ * `SF:src/a.ts`) paths; a relative one is resolved against the project root
+ * (or the cwd when none is known), so one file never has two records.
+ */
+export function fileCoverageKey(filePath, projectRoot) {
+    return path.isAbsolute(filePath) ? path.normalize(filePath) : path.resolve(projectRoot ?? process.cwd(), filePath);
+}
+/** Which optional metrics the files carry. Line coverage is always collected. */
+export function collectedMetrics(files) {
+    return {
+        branch: files.some(f => f.branches.total > 0),
+        function: files.some(f => f.functions.total > 0),
+        statement: files.some(f => f.statements.total > 0),
+    };
+}
+export function collectedSummary(summary, collected) {
+    return {
+        line: summary.line,
+        branch: collected.branch ? summary.branch : null,
+        function: collected.function ? summary.function : null,
+        statement: collected.statement ? summary.statement : null,
+        files: summary.files,
+    };
+}
+//# sourceMappingURL=collected-metrics.js.map

package/dist/domains/coverage-analysis/coordinator.js

@@ -7,6 +7,7 @@ import { LoggerFactory } from '../../logging/index.js';
 import { ok, err } from '../../shared/types/index.js';
 import { toError } from '../../shared/error-utils.js';
 import { createEvent, CoverageAnalysisEvents, } from '../../shared/events/index.js';
+import { isMeasuredGapRequest, } from './interfaces.js';
 import { CoverageAnalyzerService, GapDetectorService, RiskScorerService, } from './services/index.js';
 import { GhostCoverageAnalyzerService } from './services/ghost-coverage-analyzer.js';
 import { createHNSWIndex } from './services/hnsw-index.js';
@@ -361,7 +362,9 @@ export class CoverageAnalysisCoordinator extends BaseDomainCoordinator {
                 return err(new Error('Coverage analysis paused: topology is in critical state'));
             }
             const result = await this.coverageAnalyzer.analyze(request);
-            if (result.success) {
+            // #1008: subscribers (quality-assessment) store the report as
+            // `coverage:latest`. A static estimate must never reach them.
+            if (result.success && result.value.measured !== false) {
                 // Publish coverage report event
                 await this.publishCoverageReport(result.value);
             }
@@ -402,8 +405,12 @@ export class CoverageAnalysisCoordinator extends BaseDomainCoordinator {
                     }
                     verifiedGaps.push(gap);
                 }
-                // Publish gap detection events for verified high-risk gaps
-                await this.publishGapEvents(verifiedGaps);
+                // Publish gap detection events for verified high-risk gaps — only for
+                // MEASURED coverage (#1014). Consumers learn from these events
+                // (learning-optimization experiences, code/defect-intel KV).
+                if (isMeasuredGapRequest(request)) {
+                    await this.publishGapEvents(verifiedGaps);
+                }
                 // Return result with verified gaps
                 return ok({
                     ...result.value,
@@ -477,7 +484,9 @@ export class CoverageAnalysisCoordinator extends BaseDomainCoordinator {
                 const date = new Date(timestamp);
                 if (date >= timeRange.start && date <= timeRange.end) {
                     const summary = await this.memory.get(key);
-                    if (summary) {
+                    // #1014: only measured snapshots are trend points. Unstamped legacy
+                    // snapshots (estimates were written here up to 3.15.4) are skipped.
+                    if (summary && summary.measured === true && Number.isFinite(summary.line)) {
                         dataPoints.push({ date, coverage: summary });
                     }
                 }
@@ -609,10 +618,13 @@ export class CoverageAnalysisCoordinator extends BaseDomainCoordinator {
         const payload = {
             reportId: crypto.randomUUID(),
             line: report.summary.line,
-            branch: report.summary.branch,
-            function: report.summary.function,
-            statement: report.summary.statement,
+            // #1027 B2: an uncollected metric travels as null, never as its 0.
+            branch: report.collected && !report.collected.branch ? null : report.summary.branch,
+            function: report.collected && !report.collected.function ? null : report.summary.function,
+            statement: report.collected && !report.collected.statement ? null : report.summary.statement,
             files: report.summary.files,
+            measured: true,
+            ...(report.runStatus ? { runStatus: report.runStatus } : {}),
         };
         const event = createEvent(CoverageAnalysisEvents.CoverageReportCreated, 'coverage-analysis', payload);
         await this.eventBus.publish(event);
@@ -627,6 +639,9 @@ export class CoverageAnalysisCoordinator extends BaseDomainCoordinator {
                 uncoveredLines: gap.lines,
                 uncoveredBranches: gap.branches,
                 riskScore: gap.riskScore,
+                // #1014: provenance — only measured gaps are ever published.
+                measured: true,
+                coverageMethod: 'instrumented-report',
             };
             const event = createEvent(CoverageAnalysisEvents.CoverageGapDetected, 'coverage-analysis', payload);
             await this.eventBus.publish(event);

package/dist/domains/coverage-analysis/interfaces.d.ts

@@ -19,10 +19,43 @@ export interface AnalyzeCoverageRequest {
     coverageData: CoverageData;
     threshold?: number;
     includeFileDetails?: boolean;
+    /**
+     * Whether `coverageData` came from instrumentation (#1008). `false` marks a
+     * static estimate: it is analyzed and returned, but never persisted as
+     * `coverage:latest`, history, per-file coverage or quality evidence.
+     * Takes precedence over `coverageData.instrumented`. Fail-closed: when both
+     * are absent the data is treated as UNMEASURED and nothing is persisted.
+     */
+    measured?: boolean;
+    /**
+     * Outcome of the test run that produced `coverageData`, when one ran
+     * (#1027 N4). Coverage from a run whose tests failed is still a
+     * measurement: it is persisted, stamped `runStatus: 'failed'`; the failure
+     * itself is carried by testsPassing.
+     */
+    runStatus?: 'passed' | 'failed';
+    /**
+     * Counts of the test run behind `coverageData`, when one ran (#1027 NB1).
+     * Its testsPassing is recorded together with the coverage, under one runId,
+     * so failing-run coverage never pairs with a stale testsPassing.
+     */
+    testRun?: {
+        runId: string;
+        passed: number;
+        failed: number;
+        skipped?: number;
+    };
+    /**
+     * Project root that relative report paths (lcov `SF:src/a.ts`) resolve
+     * against, so per-file records use ONE key form: the absolute path (#1027 N7).
+     */
+    projectRoot?: string;
 }
 export interface CoverageData {
     files: FileCoverage[];
     summary: CoverageSummary;
+    /** Set by producers that know their provenance; `false` = static estimate (#1008). */
+    instrumented?: boolean;
 }
 export interface FileCoverage {
     path: string;
@@ -57,6 +90,23 @@ export interface CoverageReport {
     meetsThreshold: boolean;
     delta?: CoverageDelta;
     recommendations: string[];
+    /**
+     * False when the report was computed from a static estimate (#1008). Such a
+     * report was not persisted and must not be published or stored as evidence.
+     */
+    measured?: boolean;
+    /**
+     * Which optional metrics the report collected (#1027 B2). `summary` holds 0
+     * for an uncollected metric by construction; consumers must report and
+     * persist it as null.
+     */
+    collected?: {
+        branch: boolean;
+        function: boolean;
+        statement: boolean;
+    };
+    /** Outcome of the test run behind the report, when known (#1027 N4). */
+    runStatus?: 'passed' | 'failed';
 }
 export interface CoverageDelta {
     line: number;
@@ -69,7 +119,16 @@ export interface GapDetectionRequest {
     coverageData: CoverageData;
     minCoverage?: number;
     prioritize?: 'risk' | 'size' | 'recent-changes';
+    /**
+     * Provenance of `coverageData` (#1014), as for AnalyzeCoverageRequest.
+     * Takes precedence over `coverageData.instrumented`. Fail-closed: gaps from
+     * data that is not explicitly measured are returned but never learned from
+     * (no gap-pattern vectors) nor published as CoverageGapDetected.
+     */
+    measured?: boolean;
 }
+/** Whether a gap-detection request carries measured coverage (#1014, fail-closed). */
+export declare function isMeasuredGapRequest(request: GapDetectionRequest): boolean;
 export interface CoverageGaps {
     gaps: CoverageGap[];
     totalUncoveredLines: number;

package/dist/domains/coverage-analysis/interfaces.js

@@ -2,5 +2,10 @@
  * Agentic QE v3 - Coverage Analysis Domain Interface
  * O(log n) coverage gap detection with HNSW
  */
-export {};
+/** Whether a gap-detection request carries measured coverage (#1014, fail-closed). */
+export function isMeasuredGapRequest(request) {
+    if (typeof request.measured === 'boolean')
+        return request.measured;
+    return request.coverageData.instrumented === true;
+}
 //# sourceMappingURL=interfaces.js.map

package/dist/domains/coverage-analysis/plugin.js

@@ -60,10 +60,16 @@ export class CoverageAnalysisPlugin extends BaseDomainPlugin {
                     this._activeAnalyses++;
                     this.updateAgentMetrics();
                     try {
+                        // #1008: coverage numbers supplied in a task payload (e.g. MCP
+                        // `task_submit`) are caller claims, not an instrumented run. Never
+                        // trust a caller-supplied `measured`/`instrumented` flag: analyze
+                        // and return the data, but do not persist it as coverage evidence.
+                        const { instrumented: _claimed, ...callerData } = coverageData;
                         return await this.coordinator.analyze({
-                            coverageData,
+                            coverageData: callerData,
                             threshold: payload.threshold,
                             includeFileDetails: payload.includeFileDetails,
+                            measured: false,
                         });
                     }
                     finally {

package/dist/domains/coverage-analysis/services/coverage-analyzer.d.ts

@@ -8,6 +8,13 @@ import { Result } from '../../../shared/types';
 import { MemoryBackend } from '../../../kernel/interfaces';
 import { AnalyzeCoverageRequest, CoverageReport, CoverageData, CoverageSummary, CoverageGaps, CoverageGap } from '../interfaces';
 import type { HybridRouter } from '../../../shared/llm';
+/**
+ * Whether an analyze request carries instrumented (measured) coverage (#1008).
+ * Fail-closed: an explicit `request.measured` wins; otherwise only data a
+ * producer marked `instrumented: true` is measured. Anything without
+ * provenance is analyzed and returned, but never persisted as evidence.
+ */
+export declare function isMeasuredCoverage(request: AnalyzeCoverageRequest): boolean;
 export interface ICoverageAnalysisService {
     /** Analyze coverage from reports */
     analyze(request: AnalyzeCoverageRequest): Promise<Result<CoverageReport, Error>>;