agentic-qe 3.15.5 → 3.15.6

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

@@ -10,6 +10,7 @@ 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 MeasuredFailure } from '../../domains/quality-assessment/evidence-sufficiency.js';
@@ -20,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[];
@@ -58,6 +60,22 @@ export interface QualityAssessResult {
     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. */
@@ -201,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,6 +9,7 @@
 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';
@@ -202,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();
@@ -307,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) => {
@@ -405,6 +408,7 @@ 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 } : {}),
@@ -428,8 +432,20 @@ export const qualityAssessConfig = {
         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,
             // #996: only a caller-supplied threshold overrides the configured/default
             // per-metric limits; the 80 fallback above must not.
@@ -453,6 +469,15 @@ export const qualityAssessConfig = {
             ? 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
@@ -461,7 +486,7 @@ export const qualityAssessConfig = {
             passed: insufficient || failedMetrics.length > 0
                 ? false
                 : typeof data.passed === 'boolean' ? data.passed : undefined,
-            qualityScore: data.qualityScore,
+            qualityScore: measuredScore,
             recommendations: data.recommendations || [],
             unmeasured: insufficient ? (unmeasured?.length ? unmeasured : ['unknown']) : [],
             failedMetrics,
@@ -480,6 +505,14 @@ export const qualityAssessConfig = {
                 ? { 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 } : {}),
@@ -721,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);
     }
@@ -646,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,
@@ -665,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/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 },
@@ -902,9 +913,15 @@ export class MCPProtocolServer {
                 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. 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'),
                 ],
             },
@@ -974,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'),
@@ -1002,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/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;
 }

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.

package/dist/optimization/session-cache.js

@@ -13,6 +13,8 @@
  * - TTL-based expiry, LRU-ish eviction at capacity
  */
 import { createHash } from 'crypto';
+import * as path from 'path';
+import { findProjectRoot } from '../kernel/project-root.js';
 /**
  * Build identity mixed into every cache fingerprint so persisted entries never
  * outlive the code that produced them. `__CLI_VERSION__` is substituted at bundle
@@ -54,6 +56,31 @@ function canonicalStringify(value) {
     }
     return encode(normalized);
 }
+function resolveScope(scope) {
+    let projectRoot = scope?.projectRoot;
+    if (!projectRoot) {
+        try {
+            projectRoot = findProjectRoot();
+        }
+        catch {
+            projectRoot = '';
+        }
+    }
+    let cwd = scope?.cwd;
+    if (!cwd) {
+        try {
+            cwd = process.cwd();
+        }
+        catch {
+            cwd = '';
+        }
+    }
+    return {
+        projectRoot: projectRoot ? path.resolve(projectRoot) : '',
+        cwd: cwd ? path.resolve(cwd) : '',
+        inputs: scope?.inputs ?? {},
+    };
+}
 // ============================================================================
 // Implementation
 // ============================================================================
@@ -81,9 +108,16 @@ export 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, action, input) {
-        const canonical = canonicalStringify({ action, build: getBuildIdentity(), domain, input });
+    computeFingerprint(domain, action, input, scope) {
+        const canonical = canonicalStringify({
+            action, build: getBuildIdentity(), domain, input, scope: resolveScope(scope),
+        });
         return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
     }
     /**

package/dist/plugins/cache.js

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { validVersion, newestVersionFirst } from './version-policy.js';
+import { getProjectStorePath } from '../kernel/project-root.js';
 // ============================================================================
 // PluginCache
 // ============================================================================
@@ -16,7 +17,7 @@ export class PluginCache {
     keepVersions;
     constructor(options = {}) {
         this.cacheDir = options.cacheDir
-            ?? path.join(process.cwd(), '.agentic-qe', 'plugins');
+            ?? getProjectStorePath('plugins');
         this.keepVersions = options.keepVersions ?? 2;
     }
     /** Check if a specific version is cached. */

package/dist/plugins/sources/github.js

@@ -7,6 +7,7 @@
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 import { parseManifest } from '../manifest.js';
+import { getProjectStorePath } from '../../kernel/project-root.js';
 // ============================================================================
 // Input Validation
 // ============================================================================
@@ -28,7 +29,7 @@ export class GitHubPluginSource {
     type = 'github';
     cacheDir;
     constructor(cacheDir) {
-        this.cacheDir = cacheDir ?? path.join(process.cwd(), '.agentic-qe', 'plugins-cache');
+        this.cacheDir = cacheDir ?? getProjectStorePath('plugins-cache');
     }
     async resolve(location) {
         const pluginPath = await this.getPluginPath(location);

package/dist/plugins/sources/npm.js

@@ -9,6 +9,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { execFileSync } from 'child_process';
 import { parseManifest } from '../manifest.js';
+import { getProjectStorePath } from '../../kernel/project-root.js';
 // ============================================================================
 // Input Validation
 // ============================================================================
@@ -30,7 +31,7 @@ export class NpmPluginSource {
     type = 'npm';
     cacheDir;
     constructor(cacheDir) {
-        this.cacheDir = cacheDir ?? path.join(process.cwd(), '.agentic-qe', 'plugins-cache', 'npm');
+        this.cacheDir = cacheDir ?? getProjectStorePath('plugins-cache', 'npm');
     }
     async resolve(location) {
         const pluginPath = await this.getPluginPath(location);

package/dist/shared/aqe-managed-dirs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AQE-managed directories that source walkers must not treat as project code
+ * (#999, review N4 / round 2b).
+ *
+ *  - `.agentic-qe/` is AQE runtime state (workers, results, DBs) at ANY depth;
+ *    it is never source.
+ *  - `.claude/` holds the assets `aqe init` writes (helpers, skills, agents).
+ *    It is AQE-managed at the walk root, and nested only when it sits next to
+ *    a `.agentic-qe/` (a nested `aqe init` in a monorepo package). A nested
+ *    `.claude/` with no AQE install beside it (e.g. a Claude Code plugin's own
+ *    `.claude/hooks/*.ts`) is the package's source and is walked.
+ */
+export declare const AQE_STATE_DIR = ".agentic-qe";
+export declare const AQE_CLAUDE_DIR = ".claude";
+/** True when directory `name` inside `parentDir` is AQE-managed (never project source). */
+export declare function isAqeManagedDir(parentDir: string, name: string, isWalkRoot: boolean): boolean;
+/**
+ * Root-relative ('/'-separated) paths of the AQE-managed `.claude` directories
+ * under `projectRoot`: the root one (if present) and every `.claude` that has a
+ * sibling `.agentic-qe`. Used to anchor cloc/tokei excludes. Bounded walk that
+ * skips `skipDirs` and dot-directories.
+ */
+export declare function findAqeClaudeDirs(projectRoot: string, skipDirs?: readonly string[], maxDepth?: number): string[];
+//# sourceMappingURL=aqe-managed-dirs.d.ts.map