agentic-qe 3.15.5 → 3.15.6

package/dist/coordination/result-saver.d.ts

@@ -49,6 +49,11 @@ export interface TrendData {
 export declare class ResultSaver {
     private readonly baseDir;
     private readonly resultsDir;
+    /**
+     * @param baseDir Store directory. Defaults to the resolved project's
+     * `.agentic-qe` (review of #1026 N2: a cwd-relative default wrote
+     * `<tmp>/.agentic-qe/results` when run from a shared dir).
+     */
     constructor(baseDir?: string);
     /**
      * Save task result in appropriate format(s)
@@ -71,12 +76,29 @@ export declare class ResultSaver {
     private generateSecurityReport;
     private generateQualityReport;
     private ensureDirectories;
+    /** `YYYY-MM-DDTHH-MM-SS-mmm` (#1007: milliseconds, not seconds). */
     private formatTimestamp;
+    /** Short task-id fragment plus random hex, unique per save. */
+    private uniqueSuffix;
+    /** Write `filePath` via a temp file and rename, replacing any previous version. */
+    private replaceFile;
+    /**
+     * Create `filePath` exclusively and record it. If the name is taken (a
+     * reused custom prefix), write to
+     * `name-1.ext`, `name-2.ext`, … instead of replacing the earlier file (#1007).
+     */
+    private writeNewFile;
     private sanitizeFilename;
     private getTestExtension;
     private createFileEntry;
     private extractSummary;
+    /**
+     * Append to index.json. Concurrent saves read-modify-write the same file, so
+     * updates are serialized per index path in this process and the file is
+     * replaced atomically, otherwise one save's entry is lost (#1007).
+     */
     private updateIndex;
+    private writeIndexEntry;
 }
 export declare function createResultSaver(baseDir?: string): ResultSaver;
 //# sourceMappingURL=result-saver.d.ts.map

package/dist/coordination/result-saver.js

@@ -4,8 +4,9 @@
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { createHash } from 'crypto';
+import { createHash, randomBytes } from 'crypto';
 import { safeJsonParse } from '../shared/safe-json.js';
+import { getProjectStorePath } from '../kernel/project-root.js';
 function securityReportExecution(data) {
     return data.evidence?.completeness === 'complete' ? 'completed'
         : data.evidence?.completeness === 'partial' ? 'partial'
@@ -77,7 +78,12 @@ const TEST_FILE_PATTERNS = {
 export class ResultSaver {
     baseDir;
     resultsDir;
-    constructor(baseDir = '.agentic-qe') {
+    /**
+     * @param baseDir Store directory. Defaults to the resolved project's
+     * `.agentic-qe` (review of #1026 N2: a cwd-relative default wrote
+     * `<tmp>/.agentic-qe/results` when run from a shared dir).
+     */
+    constructor(baseDir = getProjectStorePath()) {
         this.baseDir = baseDir;
         this.resultsDir = path.join(baseDir, 'results');
     }
@@ -94,8 +100,13 @@ export class ResultSaver {
         // Ensure directories exist
         await this.ensureDirectories(taskType);
         // Get timestamp string for filenames
+        // #1007: millisecond timestamp plus a per-save suffix. Names to the second
+        // let two saves in the same second overwrite each other. Report, manifest
+        // and data files are created exclusively (see writeNewFile), so even a
+        // reused custom prefix never replaces an earlier result. Generated test
+        // files are the exception: one file per test name (see replaceFile).
         const tsStr = this.formatTimestamp(timestamp);
-        const prefix = options.filenamePrefix || tsStr;
+        const prefix = options.filenamePrefix || `${tsStr}_${this.uniqueSuffix(taskId)}`;
         // Save based on task type
         switch (taskType) {
             case 'generate-tests':
@@ -159,8 +170,7 @@ export class ResultSaver {
             framework: options.framework || 'vitest',
             tests: data.tests,
         }, null, 2);
-        await fs.writeFile(manifestPath, manifestContent);
-        files.push(await this.createFileEntry(manifestPath, 'json'));
+        files.push(await this.writeNewFile(manifestPath, manifestContent, 'json'));
         // Save individual test files if code is provided
         if (data.tests) {
             for (const test of data.tests) {
@@ -168,16 +178,17 @@ export class ResultSaver {
                     const ext = this.getTestExtension(options.language || 'typescript', options.framework || 'vitest');
                     const testFilename = this.sanitizeFilename(test.name) + ext;
                     const testPath = path.join(testDir, testFilename);
-                    await fs.writeFile(testPath, test.code);
-                    files.push(await this.createFileEntry(testPath, 'source'));
+                    // Review of #1026 N7: a generated test keeps one file per test name
+                    // (replaced atomically), unlike reports, so numbered copies never
+                    // pile up for a test runner to collect.
+                    files.push(await this.replaceFile(testPath, test.code, 'source'));
                 }
             }
         }
         // Save markdown report
         const reportPath = path.join(this.resultsDir, 'tests', `${prefix}_report.md`);
         const reportContent = this.generateTestReport(data, options);
-        await fs.writeFile(reportPath, reportContent);
-        files.push(await this.createFileEntry(reportPath, 'markdown'));
+        files.push(await this.writeNewFile(reportPath, reportContent, 'markdown'));
         return files;
     }
     async saveCoverage(result, prefix, options) {
@@ -189,8 +200,7 @@ export class ResultSaver {
         const coverageDir = path.join(this.resultsDir, 'coverage');
         // Save JSON
         const jsonPath = path.join(coverageDir, `${prefix}_coverage.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(data, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(data, null, 2), 'json'));
         // Save LCOV format — ONLY for genuinely measured coverage.
         //
         // #569/ADR-126: LCOV has nowhere to record provenance. Emitting it for an
@@ -202,14 +212,12 @@ export class ResultSaver {
         if (options.includeSecondary !== false && data.measured === true) {
             const lcovPath = path.join(coverageDir, `${prefix}_coverage.lcov`);
             const lcovContent = this.generateLcov(data);
-            await fs.writeFile(lcovPath, lcovContent);
-            files.push(await this.createFileEntry(lcovPath, 'lcov'));
+            files.push(await this.writeNewFile(lcovPath, lcovContent, 'lcov'));
         }
         // Save markdown report
         const reportPath = path.join(coverageDir, `${prefix}_report.md`);
         const reportContent = this.generateCoverageReport(data);
-        await fs.writeFile(reportPath, reportContent);
-        files.push(await this.createFileEntry(reportPath, 'markdown'));
+        files.push(await this.writeNewFile(reportPath, reportContent, 'markdown'));
         return files;
     }
     async saveSecurityScan(result, prefix, options) {
@@ -218,20 +226,17 @@ export class ResultSaver {
         const securityDir = path.join(this.resultsDir, 'security');
         // Save JSON
         const jsonPath = path.join(securityDir, `${prefix}_scan.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(data, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(data, null, 2), 'json'));
         // Save SARIF format
         if (options.includeSecondary !== false) {
             const sarifPath = path.join(securityDir, `${prefix}_scan.sarif`);
             const sarifContent = this.generateSarif(data);
-            await fs.writeFile(sarifPath, sarifContent);
-            files.push(await this.createFileEntry(sarifPath, 'sarif'));
+            files.push(await this.writeNewFile(sarifPath, sarifContent, 'sarif'));
         }
         // Save markdown report
         const reportPath = path.join(securityDir, `${prefix}_report.md`);
         const reportContent = this.generateSecurityReport(data);
-        await fs.writeFile(reportPath, reportContent);
-        files.push(await this.createFileEntry(reportPath, 'markdown'));
+        files.push(await this.writeNewFile(reportPath, reportContent, 'markdown'));
         return files;
     }
     async saveQualityAssessment(result, prefix, _options) {
@@ -240,13 +245,11 @@ export class ResultSaver {
         const qualityDir = path.join(this.resultsDir, 'quality');
         // Save JSON
         const jsonPath = path.join(qualityDir, `${prefix}_assessment.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(data, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(data, null, 2), 'json'));
         // Save markdown report
         const reportPath = path.join(qualityDir, `${prefix}_report.md`);
         const reportContent = this.generateQualityReport(data);
-        await fs.writeFile(reportPath, reportContent);
-        files.push(await this.createFileEntry(reportPath, 'markdown'));
+        files.push(await this.writeNewFile(reportPath, reportContent, 'markdown'));
         return files;
     }
     async saveCodeIndex(result, prefix, _options) {
@@ -256,8 +259,7 @@ export class ResultSaver {
         await fs.mkdir(indexDir, { recursive: true });
         // Save JSON
         const jsonPath = path.join(indexDir, `${prefix}_index.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(data, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(data, null, 2), 'json'));
         return files;
     }
     async saveDefectPrediction(result, prefix, _options) {
@@ -266,8 +268,7 @@ export class ResultSaver {
         await fs.mkdir(defectDir, { recursive: true });
         // Save JSON
         const jsonPath = path.join(defectDir, `${prefix}_prediction.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(result, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(result, null, 2), 'json'));
         return files;
     }
     async saveContractValidation(result, prefix, _options) {
@@ -276,8 +277,7 @@ export class ResultSaver {
         await fs.mkdir(contractDir, { recursive: true });
         // Save JSON
         const jsonPath = path.join(contractDir, `${prefix}_validation.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(result, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(result, null, 2), 'json'));
         return files;
     }
     async saveAccessibilityTest(result, prefix, _options) {
@@ -286,8 +286,7 @@ export class ResultSaver {
         await fs.mkdir(a11yDir, { recursive: true });
         // Save JSON
         const jsonPath = path.join(a11yDir, `${prefix}_test.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(result, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(result, null, 2), 'json'));
         return files;
     }
     async saveChaosTest(result, prefix, _options) {
@@ -296,8 +295,7 @@ export class ResultSaver {
         await fs.mkdir(chaosDir, { recursive: true });
         // Save JSON
         const jsonPath = path.join(chaosDir, `${prefix}_chaos.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(result, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(result, null, 2), 'json'));
         return files;
     }
     async saveGeneric(taskType, result, prefix) {
@@ -305,8 +303,7 @@ export class ResultSaver {
         const genericDir = path.join(this.resultsDir, 'other');
         await fs.mkdir(genericDir, { recursive: true });
         const jsonPath = path.join(genericDir, `${prefix}_${taskType}.json`);
-        await fs.writeFile(jsonPath, JSON.stringify(result, null, 2));
-        files.push(await this.createFileEntry(jsonPath, 'json'));
+        files.push(await this.writeNewFile(jsonPath, JSON.stringify(result, null, 2), 'json'));
         return files;
     }
     // ==========================================================================
@@ -486,7 +483,12 @@ ${data.recommendations.map((r, i) => `${i + 1}. ${r}`).join('\n')}
 
 ## Quality Score
 
-${typeof data.qualityScore === 'number' ? `**${data.qualityScore.toFixed(1)}** / 100` : 'N/A — measured gate uses individual checks.'}
+${typeof data.qualityScore !== 'number' ? 'N/A — measured gate uses individual checks.'
+            : data.qualityScore < 0 ? 'Not measured — no requested metric had measured data (#1011).'
+                : data.evidenceStatus === 'insufficient-evidence'
+                    ? `Subset score over measured metrics: ${data.qualityScore.toFixed(1)} (not a verdict)`
+                        + (data.scoreBasis?.length ? `\nBased on: ${data.scoreBasis.join(', ')}` : '')
+                    : `**${data.qualityScore.toFixed(1)}** / 100`}
 
 ## Metrics
 
@@ -515,8 +517,51 @@ ${data.recommendations.length === 0 ? noRecommendations : data.recommendations.m
             await fs.mkdir(dir, { recursive: true });
         }
     }
+    /** `YYYY-MM-DDTHH-MM-SS-mmm` (#1007: milliseconds, not seconds). */
     formatTimestamp(date) {
-        return date.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+        return date.toISOString().replace(/[:.]/g, '-').slice(0, 23);
+    }
+    /** Short task-id fragment plus random hex, unique per save. */
+    uniqueSuffix(taskId) {
+        const idPart = this.sanitizeFilename(taskId).slice(-12) || 'task';
+        return `${idPart}-${randomBytes(3).toString('hex')}`;
+    }
+    /** Write `filePath` via a temp file and rename, replacing any previous version. */
+    async replaceFile(filePath, content, format) {
+        const tmpPath = `${filePath}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+        try {
+            await fs.writeFile(tmpPath, content, { flag: 'wx' });
+            await fs.rename(tmpPath, filePath);
+        }
+        catch (error) {
+            await fs.rm(tmpPath, { force: true });
+            throw error;
+        }
+        return this.createFileEntry(filePath, format);
+    }
+    /**
+     * Create `filePath` exclusively and record it. If the name is taken (a
+     * reused custom prefix), write to
+     * `name-1.ext`, `name-2.ext`, … instead of replacing the earlier file (#1007).
+     */
+    async writeNewFile(filePath, content, format) {
+        const dir = path.dirname(filePath);
+        const base = path.basename(filePath);
+        const dot = base.indexOf('.', 1);
+        const stem = dot > 0 ? base.slice(0, dot) : base;
+        const ext = dot > 0 ? base.slice(dot) : '';
+        for (let attempt = 0; attempt < 1000; attempt++) {
+            const candidate = attempt === 0 ? filePath : path.join(dir, `${stem}-${attempt}${ext}`);
+            try {
+                await fs.writeFile(candidate, content, { flag: 'wx' });
+                return this.createFileEntry(candidate, format);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        throw new Error(`ResultSaver: no free file name for ${filePath}`);
     }
     sanitizeFilename(name) {
         return name.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
@@ -555,7 +600,10 @@ ${data.recommendations.length === 0 ? noRecommendations : data.recommendations.m
                 };
             case 'assess-quality':
                 return {
-                    qualityScore: data.qualityScore,
+                    // #1021: -1 means "not measured", and a subset score under insufficient
+                    // evidence is not a verdict; keep both out of the index and trends.
+                    ...(typeof data.qualityScore === 'number' && data.qualityScore >= 0
+                        && data.evidenceStatus !== 'insufficient-evidence' ? { qualityScore: data.qualityScore } : {}),
                     passed: data.passed,
                     ...(data.evidenceStatus !== undefined ? { evidenceStatus: data.evidenceStatus } : {}),
                 };
@@ -568,8 +616,26 @@ ${data.recommendations.length === 0 ? noRecommendations : data.recommendations.m
                 return {};
         }
     }
-    async updateIndex(taskId, taskType, timestamp, files, summary) {
-        const indexPath = path.join(this.resultsDir, 'index.json');
+    /**
+     * Append to index.json. Concurrent saves read-modify-write the same file, so
+     * updates are serialized per index path in this process and the file is
+     * replaced atomically, otherwise one save's entry is lost (#1007).
+     */
+    updateIndex(taskId, taskType, timestamp, files, summary) {
+        const indexPath = path.resolve(this.resultsDir, 'index.json');
+        const previous = indexUpdateQueues.get(indexPath) ?? Promise.resolve();
+        const next = previous
+            .catch(() => undefined)
+            .then(() => this.writeIndexEntry(indexPath, taskId, taskType, timestamp, files, summary));
+        indexUpdateQueues.set(indexPath, next);
+        const settle = () => {
+            if (indexUpdateQueues.get(indexPath) === next)
+                indexUpdateQueues.delete(indexPath);
+        };
+        next.then(settle, settle);
+        return next;
+    }
+    async writeIndexEntry(indexPath, taskId, taskType, timestamp, files, summary) {
         let index;
         try {
             const content = await fs.readFile(indexPath, 'utf-8');
@@ -598,9 +664,13 @@ ${data.recommendations.length === 0 ? noRecommendations : data.recommendations.m
         if (index.results.length > 100) {
             index.results = index.results.slice(-100);
         }
-        await fs.writeFile(indexPath, JSON.stringify(index, null, 2));
+        const tmpPath = `${indexPath}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(index, null, 2));
+        await fs.rename(tmpPath, indexPath);
     }
 }
+/** Pending index.json updates, keyed by absolute index path (#1007). */
+const indexUpdateQueues = new Map();
 // Factory function
 export function createResultSaver(baseDir) {
     return new ResultSaver(baseDir);

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

@@ -22,6 +22,7 @@ type CoverageAnalyzerService = import('../domains/coverage-analysis').CoverageAn
 type SecurityScannerService = import('../domains/security-compliance').SecurityScannerService;
 type KnowledgeGraphService = import('../domains/code-intelligence').KnowledgeGraphService;
 type QualityAnalyzerService = import('../domains/quality-assessment').QualityAnalyzerService;
+type ProjectMetricsCollector = import('./handlers/handler-types').ProjectMetricsCollector;
 export interface TaskExecutorConfig {
     timeout: number;
     maxRetries: number;
@@ -106,6 +107,12 @@ export declare class DomainTaskExecutor implements TaskHandlerContext {
      */
     private resolveLLMRouter;
     getKnowledgeGraph(): KnowledgeGraphService;
+    /**
+     * #999: the code-intelligence coordinator, so the MCP index-code handler can
+     * run the same project-metric step as `aqe code index`. Loads the domain
+     * lazily; undefined when it is disabled or fails to load.
+     */
+    getCodeIntelligenceCoordinator(): Promise<ProjectMetricsCollector | undefined>;
     getQualityAnalyzer(): QualityAnalyzerService;
     private registerHandlers;
     /**

package/dist/coordination/task-executor.js

@@ -16,6 +16,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { isCallerInputError, toErrorMessage } from '../shared/error-utils.js';
 import { InsufficientQualityEvidenceError } from '../domains/quality-assessment/quality-evidence.js';
 import { createResultSaver } from './result-saver.js';
+import { getProjectStorePath } from '../kernel/project-root.js';
 import { createLogger } from '../logging/logger-factory.js';
 import { getClaudeModelForTier } from '../shared/llm/model-registry.js';
 // ADR-051: Agent Booster integration for Tier 0 tasks
@@ -54,9 +55,15 @@ function resolveQualityAnalyzerService(memory) {
     const factory = DomainServiceRegistry.resolve(ServiceKeys.QualityAnalyzerService);
     return factory(memory);
 }
-/** #996: structured details, only from the one error type that is known to carry them. */
+/**
+ * #996: structured details, only from error types known to carry them.
+ * #1021 round 2b: a caller-input error is marked so learners do not record
+ * the caller's mistake as a component failure.
+ */
 function errorDetailsOf(error) {
-    return error instanceof InsufficientQualityEvidenceError ? { ...error.toDetails() } : undefined;
+    if (error instanceof InsufficientQualityEvidenceError)
+        return { ...error.toDetails() };
+    return isCallerInputError(error) ? { callerError: true } : undefined;
 }
 // ============================================================================
 // ADR-051: Model Routing Support
@@ -141,7 +148,8 @@ export class DomainTaskExecutor {
             maxRetries: config?.maxRetries ?? 3,
             enableCaching: config?.enableCaching ?? true,
             saveResults: config?.saveResults ?? true,
-            resultsDir: config?.resultsDir ?? '.agentic-qe',
+            // Review of #1026 N2: resolve the project store, not a cwd-relative one.
+            resultsDir: config?.resultsDir ?? getProjectStorePath(),
             defaultLanguage: config?.defaultLanguage ?? 'typescript',
             defaultFramework: config?.defaultFramework ?? 'vitest',
         };
@@ -240,6 +248,25 @@ export class DomainTaskExecutor {
         }
         return this.knowledgeGraph;
     }
+    /**
+     * #999: the code-intelligence coordinator, so the MCP index-code handler can
+     * run the same project-metric step as `aqe code index`. Loads the domain
+     * lazily; undefined when it is disabled or fails to load.
+     */
+    async getCodeIntelligenceCoordinator() {
+        try {
+            const api = this.kernel.getDomainAPIAsync
+                ? await this.kernel.getDomainAPIAsync('code-intelligence')
+                : this.kernel.getDomainAPI('code-intelligence');
+            return typeof api?.getCoordinator === 'function' ? api.getCoordinator() : undefined;
+        }
+        catch (error) {
+            logger.debug('code-intelligence coordinator unavailable for project metrics', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    }
     getQualityAnalyzer() {
         if (!this.qualityAnalyzer) {
             this.qualityAnalyzer = resolveQualityAnalyzerService(this.kernel.memory);
@@ -498,12 +525,14 @@ export class DomainTaskExecutor {
             await this.publishTaskFailed(task.id, errorMessage, domain, isCallerInputError(error));
             // ADR-051: Record failed outcome
             this.recordOutcome(task, routingTier, false, Date.now() - startTime).catch((e) => { logger.warn('recordOutcome failed', { error: e instanceof Error ? e.message : String(e), taskId: task.id }); });
+            const errorDetails = errorDetailsOf(error);
             return {
                 taskId: task.id,
                 success: false,
                 error: errorMessage,
                 duration: Date.now() - startTime,
                 domain,
+                ...(errorDetails ? { errorDetails } : {}),
             };
         }
     }

package/dist/domains/code-intelligence/plugin.js

@@ -9,6 +9,7 @@ import { KnowledgeGraphService, } from './services/knowledge-graph.js';
 import { SemanticAnalyzerService, } from './services/semantic-analyzer.js';
 import { toError } from '../../shared/error-utils.js';
 import { ImpactAnalyzerService, } from './services/impact-analyzer.js';
+import { isMeasuredGapPayload } from '../../shared/events/domain-events.js';
 /**
  * Code Intelligence Domain Plugin
  * Provides knowledge graph, semantic search, and impact analysis capabilities
@@ -301,6 +302,9 @@ export class CodeIntelligencePlugin extends BaseDomainPlugin {
         );
     }
     async handleCoverageGap(event) {
+        // #1014: only a gap found in MEASURED coverage is acted on / learned from.
+        if (!isMeasuredGapPayload(event.payload))
+            return;
         // Coverage gap detected - update risk scores in knowledge graph
         const payload = event.payload;
         // Store coverage gap info for impact analysis

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