agentic-qe 3.15.4 → 3.15.6

package/dist/mcp/handlers/domain-handler-configs.d.ts

@@ -10,8 +10,10 @@ import { DomainHandlerConfig } from './handler-factory';
 import { TestGenerateParams, TestGenerateResult, TestExecuteParams, CoverageAnalyzeParams, CoverageAnalyzeResult, QualityAssessParams, SecurityScanParams, ContractValidateParams, AccessibilityTestParams, ChaosTestParams } from '../types';
 import type { SecurityScanEvidence } from '../../domains/security-compliance/scan-evidence.js';
 import type { SecurityCoverage } from '../../domains/security-compliance/interfaces.js';
+import type { ExcludedQualityFile, PartialQualityMetric } from '../../domains/quality-assessment/interfaces.js';
 import { type RiskDecision } from '../../contracts/verdicts.js';
-import type { EvaluatedQualityCheck } from '../../domains/quality-assessment/quality-evidence.js';
+import { type EvaluatedQualityCheck } from '../../domains/quality-assessment/quality-evidence.js';
+import { type MeasuredFailure } from '../../domains/quality-assessment/evidence-sufficiency.js';
 export interface TestExecuteResult {
     taskId: string;
     status: string;
@@ -19,7 +21,8 @@ export interface TestExecuteResult {
     passed: number;
     failed: number;
     duration: number;
-    coverage?: number;
+    /** Measured line coverage of the run, or null when none was collected (#1027 N5). */
+    coverage?: number | null;
     workerStats?: Record<string, unknown>;
     retryStats?: Record<string, unknown>;
     results?: unknown[];
@@ -49,6 +52,38 @@ export interface QualityAssessResult {
     resultsNote?: string;
     /** ADR-103: versioned, schema-validated gate verdict (additive) */
     riskDecision?: RiskDecision;
+    /**
+     * #996 (additive): 'measured' when every requested metric had data;
+     * 'insufficient-evidence' when any did not — `passed` is then false and
+     * `status` is 'insufficient-evidence'.
+     */
+    evidenceStatus?: 'measured' | 'insufficient-evidence';
+    /** #996: requested metrics with no measured data (reported as -1 in `metrics`). */
+    unmeasured?: string[];
+    /** #1011: why each unmeasured metric has no value (e.g. a file could not be parsed). */
+    unmeasuredReasons?: Record<string, string>;
+    /** #1021: metrics measured over part of the scope (files that failed to read or parse are listed). */
+    partialMetrics?: PartialQualityMetric[];
+    /** #1021: files left out of the analysis (binary, generated, minified, .d.ts, reader policy); first 50. */
+    excludedFiles?: ExcludedQualityFile[];
+    /** #1021: total number of excluded files. */
+    excludedCount?: number;
+    /** #1021: the directory, file, or 'sourceFiles' that was analysed. */
+    scope?: string;
+    /**
+     * #1021 round 2b: the metrics `qualityScore` was computed from, present when
+     * the score covers only part of the request (insufficient evidence) or of the
+     * files (partial metrics). Such a score is not a verdict.
+     */
+    scoreBasis?: string[];
+    /** #996: measured metrics that fail their own limit; any entry blocks. */
+    measuredFailures?: MeasuredFailure[];
+    /** #996: false for static analysis (runGate omitted/false) — no quality gate ran. */
+    gateEvaluated?: boolean;
+    /** #996: share of requested metrics that were measured, in [0, 1]. */
+    confidence?: number;
+    /** #996: plain statement of what was (and was not) evaluated. */
+    note?: string;
 }
 export interface SecurityScanResult {
     taskId: string;
@@ -184,6 +219,18 @@ export interface CodeIndexResult {
     symbolsExtracted: number;
     relationsFound: number;
     duration: number;
+    /**
+     * #999 MCP-CLI parity: project metrics collected by the code-intelligence
+     * coordinator, rooted at the target (as `aqe code index` does). Absent when
+     * no project root resolves or the metric step is unavailable.
+     */
+    projectMetrics?: {
+        root: string;
+        loc: number;
+        locByLanguage: Record<string, number>;
+        tests: number;
+        toolsUsed: string[];
+    };
     savedFiles?: string[];
     /** #933: true when result files were written; see savedFiles for their paths. */
     resultsSaved?: boolean;

package/dist/mcp/handlers/domain-handler-configs.js

@@ -9,8 +9,11 @@
 import { generateV2LearningFeedback, analyzeComplexity, generateV2AIInsights, generateV2Tests, detectAntiPatterns, generateTestId, } from './handler-factory.js';
 import { describeSavedResults } from './save-results-option.js';
 import { MetricsCollector } from '../metrics/index.js';
+import { CallerInputError } from '../../shared/error-utils.js';
 import { DEFAULT_FRAMEWORKS, FRAMEWORK_TO_LANGUAGE, } from '../../shared/types/test-frameworks.js';
 import { buildRiskDecisionFromQualityGate, validateRiskDecision, } from '../../contracts/verdicts.js';
+import { INSUFFICIENT_EVIDENCE, } from '../../domains/quality-assessment/quality-evidence.js';
+import { validateRequestedMetrics, } from '../../domains/quality-assessment/evidence-sufficiency.js';
 import { validateBehaviorExamples } from '../../domains/test-generation/services/behavior-example-validation.js';
 const SUPPORTED_LANGUAGES = Object.keys(DEFAULT_FRAMEWORKS);
 /**
@@ -200,7 +203,8 @@ export const testExecuteConfig = {
         const total = data.total || 0;
         const passed = data.passed || 0;
         const failed = data.failed || 0;
-        const coverage = data.coverage;
+        // #1027 N5: no measured coverage → null, never a hardcoded 0.
+        const coverage = typeof data.coverage === 'number' && Number.isFinite(data.coverage) ? data.coverage : null;
         const parallelism = params?.parallelism || 4;
         const realRetryStats = MetricsCollector.getRetryStats();
         const workersUsed = MetricsCollector.getWorkersUsed();
@@ -305,7 +309,8 @@ export const coverageAnalyzeConfig = {
         const rawLine = summary?.line ?? data.lineCoverage;
         const lineCoverage = rawLine ?? null;
         const rawStatement = summary?.statement ?? data.statementCoverage;
-        const statementCoverage = rawStatement ?? lineCoverage;
+        // #1027 N7: an explicit null (no statement data, e.g. lcov) stays null.
+        const statementCoverage = rawStatement === undefined ? lineCoverage : rawStatement;
         const learning = generateV2LearningFeedback('coverage-analyzer');
         // Map gap analysis from real data — never fabricate file paths
         const detailedGaps = gaps.map((gap, i) => {
@@ -403,6 +408,9 @@ export const coverageAnalyzeConfig = {
             coverageMethod: data.coverageMethod ?? 'unknown',
             branchDataCollected,
             functionDataCollected,
+            ...(data.runStatus === 'passed' || data.runStatus === 'failed' ? { runStatus: data.runStatus } : {}),
+            // #995: the target has no measurement at all — distinct from a measured 0%.
+            ...(data.unmeasured === true ? { unmeasured: true } : {}),
             ...(data.warning ? { warning: data.warning } : {}),
         };
     },
@@ -420,32 +428,95 @@ export const qualityAssessConfig = {
         if (params.runGate !== undefined && typeof params.runGate !== 'boolean') {
             throw new Error('runGate must be a boolean.');
         }
+        // #996 (N3): a string or unknown name is a caller error, not a metric list.
+        const metrics = params.metrics === undefined
+            ? ['coverage', 'complexity', 'maintainability']
+            : validateRequestedMetrics(params.metrics);
+        // #1021: scope the analysis instead of silently analysing <cwd>/src.
+        // Containment in the project root is enforced by the handler.
+        // CallerInputError: a caller mistake, never a component failure (round 2b).
+        if (params.target !== undefined && (typeof params.target !== 'string' || params.target.trim() === '')) {
+            throw new CallerInputError('target must be a non-empty string path.');
+        }
+        if (params.sourceFiles !== undefined && (!Array.isArray(params.sourceFiles) || params.sourceFiles.length === 0
+            || params.sourceFiles.some((f) => typeof f !== 'string' || f.trim() === ''))) {
+            throw new CallerInputError('sourceFiles must be a non-empty array of file paths.');
+        }
         return {
             runGate: params.runGate ?? false,
+            ...(params.target !== undefined ? { target: params.target } : {}),
+            ...(params.sourceFiles !== undefined ? { sourceFiles: params.sourceFiles } : {}),
             threshold: params.threshold || 80,
-            metrics: params.metrics || ['coverage', 'complexity', 'maintainability'],
+            // #996: only a caller-supplied threshold overrides the configured/default
+            // per-metric limits; the 80 fallback above must not.
+            thresholdSource: params.threshold === undefined ? 'default' : 'request',
+            metrics,
             routingTier: routingResult?.decision.tier,
             useAgentBooster: routingResult?.useAgentBooster,
             compiledContext: routingResult?.compiledContext,
         };
     },
     mapToResult: (taskId, data, duration, savedFiles) => {
+        // #996: never approve on missing data. Any unmeasured requested metric
+        // forces passed=false and an explicit insufficient-evidence status.
+        const unmeasured = Array.isArray(data.unmeasured)
+            ? data.unmeasured.filter((m) => typeof m === 'string')
+            : undefined;
+        const insufficient = (unmeasured?.length ?? 0) > 0 || data.evidenceStatus === INSUFFICIENT_EVIDENCE;
+        const gateEvaluated = typeof data.gateEvaluated === 'boolean' ? data.gateEvaluated : undefined;
+        const confidence = typeof data.confidence === 'number' ? data.confidence : undefined;
+        const measuredFailures = Array.isArray(data.measuredFailures)
+            ? data.measuredFailures
+            : undefined;
+        const failedMetrics = (measuredFailures ?? []).map((f) => f.metric);
+        // #1011: reasons travel only as a string-to-string map.
+        const unmeasuredReasons = data.unmeasuredReasons && typeof data.unmeasuredReasons === 'object'
+            && Object.values(data.unmeasuredReasons).every((r) => typeof r === 'string')
+            ? data.unmeasuredReasons
+            : undefined;
+        // -1 = no measured score; never quote it as a score.
+        const measuredScore = typeof data.qualityScore === 'number' && data.qualityScore >= 0
+            ? data.qualityScore
+            : undefined;
+        const passed = !insufficient && failedMetrics.length === 0 && data.passed === true;
         // ADR-103: attach a schema-validated RiskDecision envelope at the MCP
         // boundary (additive — existing fields unchanged). Omit rather than
         // emit an invalid envelope.
         const riskDecision = buildRiskDecisionFromQualityGate({
-            passed: typeof data.passed === 'boolean' ? data.passed : undefined,
-            qualityScore: data.qualityScore,
+            passed: insufficient || failedMetrics.length > 0
+                ? false
+                : typeof data.passed === 'boolean' ? data.passed : undefined,
+            qualityScore: measuredScore,
             recommendations: data.recommendations || [],
+            unmeasured: insufficient ? (unmeasured?.length ? unmeasured : ['unknown']) : [],
+            failedMetrics,
+            evidenceConfidence: confidence,
+            gateEvaluated,
         });
         return {
             taskId,
-            status: 'completed',
+            status: insufficient ? INSUFFICIENT_EVIDENCE : 'completed',
             ...(typeof data.qualityScore === 'number' ? { qualityScore: data.qualityScore } : {}),
             ...(Array.isArray(data.checks) ? { checks: data.checks } : {}),
-            passed: data.passed || false,
+            passed,
             metrics: data.metrics || {},
             recommendations: data.recommendations || [],
+            ...(data.evidenceStatus === 'measured' || insufficient
+                ? { evidenceStatus: insufficient ? INSUFFICIENT_EVIDENCE : 'measured' }
+                : {}),
+            ...(unmeasured ? { unmeasured } : {}),
+            ...(unmeasuredReasons ? { unmeasuredReasons } : {}),
+            // #1021: partial evidence, exclusions and the analysed scope travel with the verdict.
+            ...(Array.isArray(data.partialMetrics) ? { partialMetrics: data.partialMetrics } : {}),
+            ...(Array.isArray(data.excludedFiles) ? { excludedFiles: data.excludedFiles } : {}),
+            ...(typeof data.excludedCount === 'number' ? { excludedCount: data.excludedCount } : {}),
+            ...(typeof data.scope === 'string' ? { scope: data.scope } : {}),
+            ...(Array.isArray(data.scoreBasis) && data.scoreBasis.every((m) => typeof m === 'string')
+                ? { scoreBasis: data.scoreBasis } : {}),
+            ...(measuredFailures ? { measuredFailures } : {}),
+            ...(gateEvaluated !== undefined ? { gateEvaluated } : {}),
+            ...(confidence !== undefined ? { confidence } : {}),
+            ...(typeof data.note === 'string' ? { note: data.note } : {}),
             duration,
             savedFiles,
             ...(validateRiskDecision(riskDecision).valid ? { riskDecision } : {}),
@@ -683,6 +754,7 @@ export const codeIndexConfig = {
         filesIndexed: data.filesIndexed || 0,
         symbolsExtracted: data.symbolsExtracted || 0,
         relationsFound: data.relationsFound || 0,
+        ...(data.projectMetrics ? { projectMetrics: data.projectMetrics } : {}),
         duration,
         savedFiles,
     }),

package/dist/mcp/handlers/handler-factory.js

@@ -14,9 +14,10 @@ import { randomUUID } from 'crypto';
 import { getFleetState, isFleetInitialized } from './core-handlers.js';
 import { createTaskExecutor } from '../../coordination/task-executor.js';
 import { getTaskRouter } from '../services/task-router.js';
-import { toErrorMessage } from '../../shared/error-utils.js';
+import { isCallerInputError, toErrorMessage } from '../../shared/error-utils.js';
 import { describeSavedResults, readSaveResultsOption } from './save-results-option.js';
 import { createInitializedFeedbackLoop, getQualityFeedbackLoop } from '../../feedback/feedback-loop.js';
+import { isLearnableResult } from '../../learning/learnable-result.js';
 // ============================================================================
 // Shared Utilities (exported for response mappers)
 // ============================================================================
@@ -171,7 +172,10 @@ async function recordDomainFeedback(domain, data, durationMs, params) {
             await loop.recordTestOutcome(outcome);
         }
     }
-    if (domain === 'coverage-analysis' && data) {
+    // #1014: only MEASURED coverage becomes a coverage_sessions row. An
+    // estimate or an UNMEASURED target wrote after_lines = the estimate / 0.0,
+    // which gate-check, threshold-check and the coverage-learner then read.
+    if (domain === 'coverage-analysis' && data && isLearnableResult(domain, data)) {
         // Extract coverage session data and record for learning
         const session = {
             id: randomUUID(),
@@ -203,6 +207,14 @@ async function recordDomainFeedback(domain, data, durationMs, params) {
             durationMs,
             startedAt: new Date(Date.now() - durationMs),
             completedAt: new Date(),
+            // #1014: provenance stamp — readers ignore legacy rows of this agent
+            // without it (see feedback/coverage-session-provenance.ts).
+            context: {
+                measured: true,
+                coverageMethod: data.coverageMethod ?? 'instrumented-report',
+                branchDataCollected: data.branchCoverage !== null && data.branchCoverage !== undefined,
+                functionDataCollected: data.functionCoverage !== null && data.functionCoverage !== undefined,
+            },
         };
         await loop.recordCoverageSession(session);
     }
@@ -636,6 +648,9 @@ export function createDomainHandler(config) {
                 return {
                     success: false,
                     error: result.error || 'Task execution failed',
+                    // #996: structured failure context (e.g. status + unmeasured metrics),
+                    // only when the failing handler provided it. success stays false.
+                    ...(result.errorDetails ? { data: result.errorDetails } : {}),
                 };
             }
             // Step 5: Map result
@@ -643,16 +658,22 @@ export function createDomainHandler(config) {
             const mappedResult = mapToResult(submitResult.value, data, result.duration, result.savedFiles, params);
             // #933: every result-saving tool reports what it wrote, the same way.
             Object.assign(mappedResult, describeSavedResults(saveResults, result.savedFiles));
-            // Step 5b: Record pattern usage on success (Phase 5.3 — fire-and-forget)
-            recordPatternUsageAsync(routingResult?.patternHints, true, domain, result.duration);
-            // Step 5c: Capture real execution learning (fire-and-forget)
-            captureExecutionLearning(`qe-${domain}`, taskType, params, data, result.duration).catch(() => { }); // Swallow errors — learning is non-critical
-            // Step 5d: Record feedback for test_outcomes / coverage_sessions
-            try {
-                await recordDomainFeedback(domain, data, result.duration, params);
-            }
-            catch {
-                // Non-critical — don't fail handler if feedback recording fails
+            // #1014: a run without evidence (a coverage estimate, an UNMEASURED
+            // target, an insufficient-evidence gate) still succeeds as a tool call,
+            // but is not recorded as successful learning anywhere below.
+            const learnable = isLearnableResult(domain, data) && isLearnableResult('', mappedResult);
+            if (learnable) {
+                // Step 5b: Record pattern usage on success (Phase 5.3 — fire-and-forget)
+                recordPatternUsageAsync(routingResult?.patternHints, true, domain, result.duration);
+                // Step 5c: Capture real execution learning (fire-and-forget)
+                captureExecutionLearning(`qe-${domain}`, taskType, params, data, result.duration).catch(() => { }); // Swallow errors — learning is non-critical
+                // Step 5d: Record feedback for test_outcomes / coverage_sessions
+                try {
+                    await recordDomainFeedback(domain, data, result.duration, params);
+                }
+                catch {
+                    // Non-critical — don't fail handler if feedback recording fails
+                }
             }
             return {
                 success: true,
@@ -662,11 +683,19 @@ export function createDomainHandler(config) {
         catch (error) {
             // Step 6: Error handling
             const errorMessage = toErrorMessage(error);
-            // Record pattern usage on failure (Phase 5.3 — fire-and-forget)
-            recordPatternUsageAsync(routingResult?.patternHints, false, domain, 0);
+            // A caller-input error thrown before the task runs (e.g. by
+            // mapToPayload's shape checks) is the caller's mistake, not a domain
+            // failure: it is marked for the experience middleware and not recorded
+            // as a pattern-usage failure.
+            const callerError = isCallerInputError(error);
+            if (!callerError) {
+                // Record pattern usage on failure (Phase 5.3 — fire-and-forget)
+                recordPatternUsageAsync(routingResult?.patternHints, false, domain, 0);
+            }
             return {
                 success: false,
                 error: `Failed to ${taskType.replace(/-/g, ' ')}: ${errorMessage}`,
+                ...(callerError ? { data: { callerError: true } } : {}),
             };
         }
     };

package/dist/mcp/handlers/wrapped-domain-handlers.js

@@ -53,7 +53,13 @@ function createWrappedHandler(handler, domain, agent) {
         if (result.success) {
             return { success: true, data: result.data };
         }
-        return { success: false, error: result.error || 'Unknown error' };
+        // #996: keep structured failure context (e.g. insufficient-evidence details)
+        // when the domain handler provided it; success stays false.
+        return {
+            success: false,
+            error: result.error || 'Unknown error',
+            ...(result.data !== undefined ? { data: result.data } : {}),
+        };
     };
 }
 // ============================================================================

package/dist/mcp/protocol-server.js

@@ -477,9 +477,16 @@ export class MCPProtocolServer {
                     const { getSessionCache } = await import('../optimization/session-cache.js');
                     const cache = getSessionCache();
                     const { domain, action } = parseToolDomainAction(name);
+                    // #998: key on the project root, working directory and a fingerprint
+                    // of every path argument, not on the raw arguments alone. A call that
+                    // reads a directory tree is neither served from nor stored in cache.
+                    const { buildToolCacheScope } = await import('./tool-cache-scope.js');
+                    const { scope, reusable } = buildToolCacheScope(name, processedCtx.params);
                     cacheGeneration = cache.getGeneration();
-                    cacheFingerprint = cache.computeFingerprint(domain, action, processedCtx.params || {});
-                    const hit = cache.get(cacheFingerprint);
+                    cacheFingerprint = reusable
+                        ? cache.computeFingerprint(domain, action, processedCtx.params || {}, scope)
+                        : null;
+                    const hit = cacheFingerprint ? cache.get(cacheFingerprint) : null;
                     if (hit) {
                         // Cache hit — return the stored result without running the handler.
                         const cachedText = JSON.stringify(hit.result, null, 2);
@@ -887,6 +894,10 @@ export class MCPProtocolServer {
                 description: `Analyze code coverage with O(log n) sublinear algorithm and ML-powered gap detection. ${SAVE_RESULTS_HINT} Example: coverage_analyze_sublinear({ target: "src/", detectGaps: true })`,
                 category: 'domain',
                 isConcurrencySafe: true,
+                // #998: never replay from the session cache. The result measures
+                // mutable project state (source tree, test runs, reports on disk), so a
+                // cached answer goes stale as soon as those inputs change.
+                isCacheable: false,
                 parameters: [
                     { name: 'target', type: 'string', description: 'Target path to analyze', required: true },
                     { name: 'detectGaps', type: 'boolean', description: 'Detect coverage gaps', default: true },
@@ -899,11 +910,18 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'quality_assess',
-                description: `Assess code quality metrics and optionally run a pass/fail quality gate. ${SAVE_RESULTS_HINT} Example: quality_assess({ runGate: true })`,
+                description: `Assess code quality metrics and optionally run a pass/fail quality gate. Unmeasured metrics never pass. ${SAVE_RESULTS_HINT} Example: quality_assess({ runGate: true })`,
                 category: 'domain',
                 isConcurrencySafe: true,
+                // #998: never replay from the session cache. The result measures
+                // mutable project state (source tree, test runs, reports on disk), so a
+                // cached answer goes stale as soon as those inputs change.
+                isCacheable: false,
                 parameters: [
-                    { name: 'runGate', type: 'boolean', description: 'Evaluate all seven canonical measured quality checks; requires complete, valid evidence from the last 24 hours. Returns individual checks, not a static aggregate score.', default: false },
+                    { name: 'runGate', type: 'boolean', description: 'Evaluate all seven canonical measured quality checks; requires complete, valid evidence from the last 24 hours. Returns individual checks, not a static aggregate score. Missing, stale or malformed evidence fails with status "insufficient-evidence" and lists the metrics in unmeasured. When false, only static analysis runs (gateEvaluated: false).', default: false },
+                    { name: 'metrics', type: 'array', description: 'Static-analysis metrics to assess (default coverage, complexity, maintainability). Known: coverage, complexity, maintainability, duplication, testability, security. Any requested metric without measured data gives status "insufficient-evidence", passed: false, and lists it in unmeasured; a measured metric failing its threshold blocks.', items: { type: 'string' } },
+                    { name: 'target', type: 'string', description: 'File or directory to analyse, resolved against the project root and required to stay inside it (default: src/, else the root). Binary, generated, minified and .d.ts files are excluded and listed in excludedFiles; files that fail to parse are listed in partialMetrics.' },
+                    { name: 'sourceFiles', type: 'array', description: 'Explicit files to analyse (each inside the project root); takes precedence over target. If a listed file cannot be read or parsed, the affected metrics are unmeasured.', items: { type: 'string' } },
                     saveResultsParameter('quality_assess'),
                 ],
             },
@@ -973,6 +991,10 @@ export class MCPProtocolServer {
                 description: `Predict potential defects using AI analysis of code complexity and change history. ${SAVE_RESULTS_HINT} Example: defect_predict({ target: "src/auth/" })`,
                 category: 'domain',
                 isConcurrencySafe: true,
+                // #998: never replay from the session cache. The result measures
+                // mutable project state (source tree, test runs, reports on disk), so a
+                // cached answer goes stale as soon as those inputs change.
+                isCacheable: false,
                 parameters: [
                     { name: 'target', type: 'string', description: 'Target path', required: true },
                     saveResultsParameter('defect_predict'),
@@ -1001,6 +1023,10 @@ export class MCPProtocolServer {
                 description: `Index source code into the knowledge graph for dependency and impact analysis. ${SAVE_RESULTS_HINT} Example: code_index({ target: "src/" })`,
                 category: 'domain',
                 isConcurrencySafe: true,
+                // #998: never replay from the session cache. The result measures
+                // mutable project state (source tree, test runs, reports on disk), so a
+                // cached answer goes stale as soon as those inputs change.
+                isCacheable: false,
                 parameters: [
                     { name: 'target', type: 'string', description: 'Target path', required: true },
                     saveResultsParameter('code_index'),

package/dist/mcp/tool-cache-scope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Agentic QE v3 - MCP result-cache scope (#998)
+ *
+ * The protocol server reuses results of read-only tools through the session
+ * cache. A result is only reusable for the same project and the same inputs,
+ * so the cache key carries:
+ * - the resolved project root and working directory, and
+ * - for each path argument, its absolute path plus an mtime/size fingerprint,
+ *   so an edited requirements file misses the cache.
+ *
+ * A directory argument cannot be fingerprinted cheaply (editing a file inside
+ * it does not change the directory's mtime), so a call that reads a directory
+ * tree is reported as not reusable and runs every time.
+ *
+ * @module mcp/tool-cache-scope
+ */
+import type { CacheScope } from '../optimization/session-cache.js';
+/** Argument names that tools treat as filesystem paths. */
+export declare const PATH_ARGUMENTS: readonly ["target", "requirementsPath", "contractPath", "testPath", "path", "filePath", "file"];
+export interface ToolCacheScope {
+    scope: CacheScope;
+    /** False when the call reads a directory tree, so no cached result may be reused. */
+    reusable: boolean;
+}
+/**
+ * Build the cache scope for one tool call: project root, working directory
+ * and a fingerprint of every path argument (relative ones resolved to
+ * absolute paths against the working directory).
+ */
+export declare function buildToolCacheScope(toolName: string, params: Record<string, unknown> | undefined): ToolCacheScope;
+//# sourceMappingURL=tool-cache-scope.d.ts.map

package/dist/mcp/tool-cache-scope.js

@@ -0,0 +1,71 @@
+/**
+ * Agentic QE v3 - MCP result-cache scope (#998)
+ *
+ * The protocol server reuses results of read-only tools through the session
+ * cache. A result is only reusable for the same project and the same inputs,
+ * so the cache key carries:
+ * - the resolved project root and working directory, and
+ * - for each path argument, its absolute path plus an mtime/size fingerprint,
+ *   so an edited requirements file misses the cache.
+ *
+ * A directory argument cannot be fingerprinted cheaply (editing a file inside
+ * it does not change the directory's mtime), so a call that reads a directory
+ * tree is reported as not reusable and runs every time.
+ *
+ * @module mcp/tool-cache-scope
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { findProjectRoot } from '../kernel/project-root.js';
+/** Argument names that tools treat as filesystem paths. */
+export const PATH_ARGUMENTS = [
+    'target', 'requirementsPath', 'contractPath', 'testPath', 'path', 'filePath', 'file',
+];
+function fingerprintPath(value, cwd) {
+    const absolute = path.resolve(cwd, value);
+    try {
+        const stat = fs.statSync(absolute);
+        return {
+            path: absolute,
+            exists: true,
+            kind: stat.isFile() ? 'file' : stat.isDirectory() ? 'directory' : 'other',
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+        };
+    }
+    catch {
+        return { path: absolute, exists: false };
+    }
+}
+/**
+ * Tools that scan the working directory tree when their path argument is
+ * omitted. Such a call reads mutable files that no fingerprint here covers.
+ */
+const IMPLICIT_DIRECTORY_ARGUMENT = {
+    requirements_validate: 'requirementsPath',
+};
+/**
+ * Build the cache scope for one tool call: project root, working directory
+ * and a fingerprint of every path argument (relative ones resolved to
+ * absolute paths against the working directory).
+ */
+export function buildToolCacheScope(toolName, params) {
+    const cwd = process.cwd();
+    const projectRoot = path.resolve(findProjectRoot());
+    const inputs = {};
+    let reusable = true;
+    for (const name of PATH_ARGUMENTS) {
+        const value = params?.[name];
+        if (typeof value === 'string' && value.length > 0) {
+            const fingerprint = fingerprintPath(value, cwd);
+            inputs[name] = fingerprint;
+            if (fingerprint.kind === 'directory')
+                reusable = false;
+        }
+    }
+    const implicit = IMPLICIT_DIRECTORY_ARGUMENT[toolName];
+    if (implicit && inputs[implicit] === undefined)
+        reusable = false;
+    return { scope: { projectRoot, cwd, inputs }, reusable };
+}
+//# sourceMappingURL=tool-cache-scope.js.map

package/dist/mcp/tools/code-intelligence/analyze.js

@@ -14,6 +14,7 @@ import { SemanticAnalyzerService } from '../../../domains/code-intelligence/serv
 import { ImpactAnalyzerService } from '../../../domains/code-intelligence/services/impact-analyzer.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import { isAqeManagedDir } from '../../../shared/aqe-managed-dirs.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 // ============================================================================
 // Tool Implementation
@@ -405,7 +406,7 @@ export class CodeAnalyzeTool extends MCPToolBase {
     /**
      * Find source files in a directory
      */
-    async findSourceFiles(dir) {
+    async findSourceFiles(dir, isRoot = true) {
         const files = [];
         const extensions = ['.ts', '.tsx', '.js', '.jsx'];
         const ignoreDirs = ['node_modules', '.git', 'dist', 'build', 'coverage'];
@@ -414,8 +415,9 @@ export class CodeAnalyzeTool extends MCPToolBase {
             for (const entry of entries) {
                 const fullPath = path.join(dir, entry.name);
                 if (entry.isDirectory()) {
-                    if (!ignoreDirs.includes(entry.name)) {
-                        const subFiles = await this.findSourceFiles(fullPath);
+                    // #999: AQE state/assets (.agentic-qe anywhere; .claude at the root or next to .agentic-qe)
+                    if (!ignoreDirs.includes(entry.name) && !isAqeManagedDir(dir, entry.name, isRoot)) {
+                        const subFiles = await this.findSourceFiles(fullPath, false);
                         files.push(...subFiles);
                     }
                 }

package/dist/mcp/tools/coverage-analysis/index.js

@@ -143,6 +143,7 @@ export class CoverageAnalyzeTool extends MCPToolBase {
                 coverageData: { files: domainFiles, summary: calculateSummary(domainFiles) },
                 threshold: thresholds.lines || 80,
                 includeFileDetails: true,
+                measured: true, // parsed from a real report (no estimation fallback here)
             });
             if (!analyzeResult.success) {
                 return {

package/dist/mcp/types.d.ts

@@ -221,6 +221,10 @@ export interface QualityAssessParams {
     runGate?: boolean;
     threshold?: number;
     metrics?: string[];
+    /** #1021: file or directory to analyse, relative to (and contained in) the project root. Default: src/ (or the root). */
+    target?: string;
+    /** #1021: explicit files to analyse, each contained in the project root. Takes precedence over target. */
+    sourceFiles?: string[];
     /** #933: write result files under .agentic-qe/results/ (default true). false skips them. */
     saveResults?: boolean;
 }
@@ -568,6 +572,12 @@ export interface CoverageAnalyzeResult {
     branchDataCollected?: boolean;
     /** Whether function-level data was actually collected. */
     functionDataCollected?: boolean;
+    /**
+     * #995: true when coverage data exists for the project but none of it covers
+     * the requested target (or the run executed no code). The figures are null —
+     * this is "no measurement", never 0%.
+     */
+    unmeasured?: boolean;
     /** Caveats the caller should surface (e.g. "no instrumentation ran"). */
     warning?: string;
 }

package/dist/optimization/session-cache.d.ts

@@ -22,6 +22,19 @@ export interface CachedOperation {
     hitCount: number;
     lastHitAt: number;
 }
+/**
+ * Where a cached operation ran (#998). Arguments alone do not identify a
+ * result: the same relative `target: "."` means a different tree in another
+ * project, and a file argument means different content after an edit.
+ */
+export interface CacheScope {
+    /** Resolved project root. Defaults to `findProjectRoot()`. */
+    projectRoot?: string;
+    /** Working directory relative arguments resolve against. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Fingerprints of the inputs the operation reads (absolute path, mtime, size). */
+    inputs?: Record<string, unknown>;
+}
 export interface SessionCacheConfig {
     /** Enable the cache (default: true) */
     enabled: boolean;
@@ -62,8 +75,13 @@ export declare class SessionOperationCache {
      *
      * Including the version means an upgrade misses cleanly rather than serving
      * stale answers; entries from the old build simply age out.
+     *
+     * The scope (project root, working directory and input fingerprints) is part
+     * of the key too (#998): without it a relative target returned another
+     * project's cached result. When no scope is passed, the current project root
+     * and working directory are used, so every caller is project-scoped.
      */
-    computeFingerprint(domain: string, action: string, input: Record<string, unknown>): string;
+    computeFingerprint(domain: string, action: string, input: Record<string, unknown>, scope?: CacheScope): string;
     /**
      * Look up a cached result by fingerprint.
      * Returns null on miss or expired entry.