agentic-qe 3.15.5 → 3.15.6

package/dist/domains/test-execution/services/test-executor.js

@@ -13,7 +13,9 @@ import { TEST_EXECUTION_CONSTANTS, LLM_ANALYSIS_CONSTANTS } from '../../constant
 import { toErrorMessage, toError } from '../../../shared/error-utils.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
 import { secureRandom, secureRandomInt } from '../../../shared/utils/crypto-random.js';
-import { writeQualityEvidence } from '../../quality-assessment/quality-evidence.js';
+import { writeTestRunEvidence } from '../../quality-assessment/quality-evidence.js';
+import { istanbulLineHits } from '../../../coordination/handlers/handler-utils.js';
+import { fileCoverageKey } from '../../coverage-analysis/collected-metrics.js';
 import { getTestRunnerExecutionError, TestRunnerExecutionError } from '../../../shared/test-runner-verdict.js';
 import { createVitestJsonReport } from '../../../shared/vitest-json-report.js';
 import { jestExactPathPattern, runnerFilePath } from '../../../shared/test-runner-args.js';
@@ -78,7 +80,7 @@ export class TestExecutorService {
             };
             // Store results
             this.runResults.set(runId, runResult);
-            await this.storeResults(runId, runResult);
+            await this.storeResults(runId, runResult, request.testFiles);
             // Create and store stats
             const stats = {
                 runId,
@@ -133,7 +135,7 @@ export class TestExecutorService {
             };
             // Store results
             this.runResults.set(runId, runResult);
-            await this.storeResults(runId, runResult);
+            await this.storeResults(runId, runResult, request.testFiles);
             // Create and store stats
             const stats = {
                 runId,
@@ -958,17 +960,22 @@ Provide:
         if (coverages.length === 0) {
             return undefined;
         }
-        const sum = coverages.reduce((acc, cov) => ({
-            line: acc.line + cov.line,
-            branch: acc.branch + cov.branch,
-            function: acc.function + cov.function,
-            statement: acc.statement + cov.statement,
-        }), { line: 0, branch: 0, function: 0, statement: 0 });
+        // #1015: average each metric over the entries that collected it; a
+        // metric nobody collected stays null.
+        const mean = (values) => {
+            const present = values.filter((v) => typeof v === 'number' && Number.isFinite(v));
+            return present.length > 0
+                ? Math.round((present.reduce((a, v) => a + v, 0) / present.length) * 100) / 100
+                : null;
+        };
+        const line = mean(coverages.map(c => c.line));
+        if (line === null)
+            return undefined;
         return {
-            line: Math.round((sum.line / coverages.length) * 100) / 100,
-            branch: Math.round((sum.branch / coverages.length) * 100) / 100,
-            function: Math.round((sum.function / coverages.length) * 100) / 100,
-            statement: Math.round((sum.statement / coverages.length) * 100) / 100,
+            line,
+            branch: mean(coverages.map(c => c.branch)),
+            function: mean(coverages.map(c => c.function)),
+            statement: mean(coverages.map(c => c.statement)),
         };
     }
     /**
@@ -989,59 +996,61 @@ Provide:
             // Jest shape: { coverageSummary: { total: { lines: { pct }, branches: { pct }, ... } } }
             const total = json?.coverageSummary?.total ?? json?.coverageMap?.total;
             if (total?.lines?.pct !== undefined) {
+                const line = summaryPct(total.lines);
                 return {
-                    summary: {
-                        line: typeof total.lines?.pct === 'number' ? total.lines.pct : 0,
-                        branch: typeof total.branches?.pct === 'number' ? total.branches.pct : 0,
-                        function: typeof total.functions?.pct === 'number' ? total.functions.pct : 0,
-                        statement: typeof total.statements?.pct === 'number' ? total.statements.pct : 0,
+                    summary: line === null ? undefined : {
+                        line,
+                        branch: summaryPct(total.branches),
+                        function: summaryPct(total.functions),
+                        statement: summaryPct(total.statements),
                     },
                     perFile,
                 };
             }
-            // Vitest v8 shape: coverageMap is keyed by file path
+            // Vitest v8 shape: coverageMap is keyed by file path (istanbul entries)
             const coverageMap = json?.coverageMap;
             if (coverageMap && typeof coverageMap === 'object') {
                 const files = Object.keys(coverageMap).filter(k => k !== 'total');
-                if (files.length > 0) {
-                    let lines = 0, branches = 0, functions = 0, statements = 0;
-                    let count = 0;
-                    for (const filePath of files) {
-                        const entry = coverageMap[filePath];
-                        const s = entry?.s ?? {};
-                        const f = entry?.f ?? {};
-                        const b = entry?.b ?? {};
-                        const stmtTotal = Object.keys(s).length;
-                        const stmtCovered = Object.values(s).filter((v) => v > 0).length;
-                        const fnTotal = Object.keys(f).length;
-                        const fnCovered = Object.values(f).filter((v) => v > 0).length;
-                        const brTotal = Object.keys(b).length;
-                        const brCovered = Object.values(b).filter((v) => Array.isArray(v) ? v.every(c => c > 0) : v > 0).length;
-                        if (stmtTotal > 0) {
-                            const fileLine = Math.round((stmtCovered / stmtTotal) * 10000) / 100;
-                            const fileFn = fnTotal > 0 ? Math.round((fnCovered / fnTotal) * 10000) / 100 : 100;
-                            const fileBr = brTotal > 0 ? Math.round((brCovered / brTotal) * 10000) / 100 : 100;
-                            const fileStmt = fileLine;
-                            perFile.push({ path: filePath, line: fileLine, branch: fileBr, function: fileFn, statement: fileStmt });
-                            statements += fileStmt;
-                            lines += fileLine;
-                            functions += fileFn;
-                            branches += fileBr;
-                            count++;
-                        }
-                    }
-                    if (count > 0) {
-                        return {
-                            summary: {
-                                line: Math.round((lines / count) * 100) / 100,
-                                branch: Math.round((branches / count) * 100) / 100,
-                                function: Math.round((functions / count) * 100) / 100,
-                                statement: Math.round((statements / count) * 100) / 100,
-                            },
-                            perFile,
-                        };
+                const totals = { line: [0, 0], branch: [0, 0], function: [0, 0], statement: [0, 0] };
+                for (const filePath of files) {
+                    const entry = coverageMap[filePath];
+                    const s = entry?.s ?? {};
+                    const f = entry?.f ?? {};
+                    const b = entry?.b ?? {};
+                    // #1012: line coverage per SOURCE LINE (istanbul's own rule), not per statement.
+                    const lineHits = istanbulLineHits({ statementMap: entry?.statementMap ?? {}, s });
+                    const lines = [[...lineHits.values()].filter(v => v > 0).length, lineHits.size];
+                    const statements = [Object.values(s).filter(v => v > 0).length, Object.keys(s).length];
+                    const fns = [Object.values(f).filter(v => v > 0).length, Object.keys(f).length];
+                    const branchCounts = Object.values(b).flatMap(v => (Array.isArray(v) ? v : [v]));
+                    const branches = [branchCounts.filter(c => c > 0).length, branchCounts.length];
+                    if (lines[1] === 0)
+                        continue;
+                    // #1015: istanbul's 0/0 (no branches / no functions) is "not
+                    // collected" — null — not 100%.
+                    perFile.push({
+                        path: filePath,
+                        line: ratio(lines),
+                        branch: ratio(branches),
+                        function: ratio(fns),
+                        statement: ratio(statements),
+                    });
+                    for (const [key, [covered, count]] of [['line', lines], ['branch', branches], ['function', fns], ['statement', statements]]) {
+                        totals[key][0] += covered;
+                        totals[key][1] += count;
                     }
                 }
+                if (perFile.length > 0) {
+                    return {
+                        summary: {
+                            line: ratio(totals.line),
+                            branch: ratio(totals.branch),
+                            function: ratio(totals.function),
+                            statement: ratio(totals.statement),
+                        },
+                        perFile,
+                    };
+                }
             }
         }
         catch {
@@ -1073,26 +1082,33 @@ Provide:
                         if (key === 'total')
                             continue;
                         // Normalize path: strip cwd prefix, reject traversal sequences
-                        const normalizedPath = key.replace(process.cwd() + '/', '').replace(process.cwd() + '\\', '');
-                        if (normalizedPath.includes('..'))
+                        // Reject traversal; keep the key absolute (#1027 N7: one key form).
+                        const relative = key.replace(process.cwd() + '/', '').replace(process.cwd() + '\\', '');
+                        if (relative.includes('..'))
                             continue;
+                        const normalizedPath = fileCoverageKey(key);
                         const entry = value;
-                        if (entry?.lines?.pct !== undefined) {
+                        const line = summaryPct(entry?.lines);
+                        if (line !== null) {
+                            // #1015: a metric with total 0 is not collected (null), not its 100 pct.
                             perFile.push({
                                 path: normalizedPath,
-                                line: entry.lines.pct,
-                                branch: entry.branches?.pct ?? 0,
-                                function: entry.functions?.pct ?? 0,
-                                statement: entry.statements?.pct ?? 0,
+                                line,
+                                branch: summaryPct(entry.branches),
+                                function: summaryPct(entry.functions),
+                                statement: summaryPct(entry.statements),
                             });
                         }
                     }
+                    const line = summaryPct(json.total.lines);
+                    if (line === null)
+                        continue;
                     return {
                         summary: {
-                            line: json.total.lines.pct,
-                            branch: json.total.branches?.pct ?? 0,
-                            function: json.total.functions?.pct ?? 0,
-                            statement: json.total.statements?.pct ?? 0,
+                            line,
+                            branch: summaryPct(json.total.branches),
+                            function: summaryPct(json.total.functions),
+                            statement: summaryPct(json.total.statements),
                         },
                         perFile,
                     };
@@ -1111,50 +1127,69 @@ Provide:
         }
         return undefined;
     }
-    async storeResults(runId, result) {
-        await this.memory.set(`test-run:${runId}`, result, {
+    async storeResults(runId, result, testFiles) {
+        // #1028 N1: the record names the test files it ran, so per-test duration
+        // is compared only between runs of the same test set.
+        const files = testFiles && testFiles.length > 0 ? [...new Set(testFiles)].sort() : undefined;
+        await this.memory.set(`test-run:${runId}`, files ? { ...result, testFiles: files } : result, {
             namespace: 'test-execution',
             persist: true,
         });
+        // A runner ERROR has no trustworthy result: it persists no evidence.
+        if (result.status === 'error')
+            return;
+        const runStatus = result.failed > 0 || result.status !== 'passed' ? 'failed' : 'passed';
+        const coverage = result.coverage && Number.isFinite(result.coverage.line) ? result.coverage : undefined;
+        try {
+            // #1027 NB1: this run's testsPassing and (when measured) its coverage,
+            // written together under this runId — the same writer as
+            // `aqe test execute`. Coverage from a run whose tests FAILED (N4) is
+            // then never read next to a stale testsPassing from an earlier run.
+            await writeTestRunEvidence(this.memory, {
+                runId, passed: result.passed, failed: result.failed, skipped: result.skipped,
+            }, { source: 'test-execution', ...(coverage ? { coverage: coverage.line } : {}) });
+        }
+        catch {
+            // Non-critical — don't break test storage if evidence storage fails
+        }
         // Store coverage data so quality-assess and quality-gate can read it.
         // Note: coverage:previous rotation is owned by coverage-analyzer (the
         // canonical coverage service) to avoid double-rotation race conditions.
-        if (result.coverage) {
-            try {
-                // Write project-level summary using the same CoverageSummary shape
-                // as coverage-analyzer to avoid type mismatches
-                await this.memory.set('coverage:latest', {
-                    line: result.coverage.line ?? 0,
-                    branch: result.coverage.branch ?? 0,
-                    function: result.coverage.function ?? 0,
-                    statement: result.coverage.statement ?? 0,
-                    files: result.fileCoverages?.length ?? 0,
+        if (!coverage)
+            return;
+        try {
+            // Same CoverageSummary shape as coverage-analyzer, stamped with its
+            // provenance (#1008/#1015) so readers can trust it. An uncollected
+            // metric stays null — never 0, never istanbul's 0/0 = 100%.
+            await this.memory.set('coverage:latest', {
+                line: coverage.line,
+                branch: coverage.branch ?? null,
+                function: coverage.function ?? null,
+                statement: coverage.statement ?? null,
+                files: result.fileCoverages?.length ?? 0,
+                measured: true,
+                runStatus,
+                runId,
+            }, { persist: true });
+            // Store per-file coverage via memory.set() (not storeVector) so that
+            // quality-analyzer's getStoredCoverage() can read it with memory.get()
+            for (const fc of result.fileCoverages ?? []) {
+                if (!Number.isFinite(fc.line))
+                    continue;
+                // #1027 N7: one key form — the absolute path.
+                await this.memory.set(`coverage:file:${fileCoverageKey(fc.path)}`, {
+                    line: fc.line,
+                    branch: fc.branch ?? null,
+                    function: fc.function ?? null,
+                    statement: fc.statement ?? null,
+                    measured: true,
+                    runStatus,
                 }, { persist: true });
-                if (Number.isFinite(result.coverage.line)) {
-                    await writeQualityEvidence(this.memory, {
-                        coverage: result.coverage.line,
-                    }, {
-                        measuredAt: new Date().toISOString(),
-                        source: 'test-execution coverage',
-                    });
-                }
-                // Store per-file coverage via memory.set() (not storeVector) so that
-                // quality-analyzer's getStoredCoverage() can read it with memory.get()
-                if (result.fileCoverages) {
-                    for (const fc of result.fileCoverages) {
-                        await this.memory.set(`coverage:file:${fc.path}`, {
-                            line: fc.line,
-                            branch: fc.branch,
-                            function: fc.function,
-                            statement: fc.statement,
-                        }, { persist: true });
-                    }
-                }
-            }
-            catch {
-                // Non-critical — don't break test storage if coverage store fails
             }
         }
+        catch {
+            // Non-critical — don't break test storage if coverage store fails
+        }
     }
 }
 // ============================================================================
@@ -1166,4 +1201,19 @@ Provide:
 export function createTestExecutorService(dependencies, config) {
     return new TestExecutorService(dependencies, config);
 }
+/** covered/total as a 2-decimal percentage, or null when there is nothing to cover. */
+function ratio([covered, total]) {
+    return total > 0 ? Math.round((covered / total) * 10000) / 100 : null;
+}
+/**
+ * A coverage-summary metric's percentage. istanbul writes `pct: 100` for a
+ * metric with `total: 0`; that is "not collected" — null (#1015).
+ */
+function summaryPct(metric) {
+    if (!metric || typeof metric.pct !== 'number' || !Number.isFinite(metric.pct))
+        return null;
+    if (typeof metric.total === 'number' && metric.total === 0)
+        return null;
+    return metric.pct;
+}
 //# sourceMappingURL=test-executor.js.map

package/dist/domains/test-generation/coordinator.js

@@ -31,6 +31,7 @@ import { DecisionTransformerAlgorithm, } from '../../integrations/rl-suite/algor
 import { isSONAThreeLoopEnabled } from '../../integrations/ruvector/feature-flags.js';
 // Coherence Gate Integration (ADR-052)
 import { createTestGenerationCoherenceGate, } from './services/coherence-gate-service.js';
+import { isMeasuredGapPayload } from '../../shared/events/domain-events.js';
 const DEFAULT_CONFIG = {
     maxConcurrentWorkflows: 5,
     defaultTimeout: 60000, // 60 seconds
@@ -871,6 +872,9 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
         return features.slice(0, 384);
     }
     async handleCoverageGapDetected(event) {
+        // #1014: only a gap found in MEASURED coverage is acted on / learned from.
+        if (!isMeasuredGapPayload(event.payload))
+            return;
         // Auto-generate tests for detected coverage gaps
         const payload = event.payload;
         const result = await this.testGenerator.generateForCoverageGap(payload.file, payload.uncoveredLines, 'jest' // Default framework

package/dist/domains/test-generation/plugin.js

@@ -10,6 +10,7 @@ import { RoutingFeedbackCollector } from '../../routing/routing-feedback.js';
 import { createTestGeneratorServiceWithDependencies, } from './services/test-generator.js';
 import { toError } from '../../shared/error-utils.js';
 import { PatternMatcherService, } from './services/pattern-matcher.js';
+import { isMeasuredGapPayload } from '../../shared/events/domain-events.js';
 /**
  * Test Generation Domain Plugin
  * Provides AI-powered test generation capabilities
@@ -277,6 +278,9 @@ export class TestGenerationPlugin extends BaseDomainPlugin {
     // Event Handlers
     // ============================================================================
     async handleCoverageGap(event) {
+        // #1014: only a gap found in MEASURED coverage is acted on / learned from.
+        if (!isMeasuredGapPayload(event.payload))
+            return;
         // Coverage gap detected - could auto-generate tests
         const payload = event.payload;
         // Only auto-generate for high-risk gaps

package/dist/feedback/coverage-learner.js

@@ -9,6 +9,7 @@ import { DEFAULT_FEEDBACK_CONFIG } from './types.js';
 import { getUnifiedMemory } from '../kernel/unified-memory.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { safeJsonParse } from '../shared/safe-json.js';
+import { MEASURED_COVERAGE_SESSION_SQL } from './coverage-session-provenance.js';
 // ============================================================================
 // Coverage Session Store
 // ============================================================================
@@ -101,8 +102,10 @@ export class CoverageLearner {
         if (!this.db)
             return;
         const database = this.db.getDatabase();
+        // #1014: legacy MCP rows without provenance (estimates, 0.0 for
+        // unmeasured runs) are not loaded as sessions or learned as strategies.
         const rows = database.prepare(`
-      SELECT * FROM coverage_sessions ORDER BY created_at DESC LIMIT ?
+      SELECT * FROM coverage_sessions WHERE ${MEASURED_COVERAGE_SESSION_SQL} ORDER BY created_at DESC LIMIT ?
     `).all(this.config.maxOutcomesInMemory);
         for (const row of rows.reverse()) {
             const session = {

package/dist/feedback/coverage-session-provenance.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Agentic QE v3 - Provenance of coverage_sessions rows (#1014)
+ *
+ * Up to 3.15.5 the MCP handler factory (agent `qe-coverage-analysis`) wrote a
+ * coverage_sessions row for EVERY coverage_analyze_sublinear call: a static
+ * estimate's figure, or 0.0 for an UNMEASURED target. Those rows have no
+ * provenance and never expire. Rows written from now on carry
+ * `context_json.measured = true`.
+ *
+ * Readers ignore legacy rows of that agent instead of deleting them (no data
+ * is destroyed; the coverage-learner's own retention ages them out). Rows of
+ * other writers (e.g. the post-command hook, which records a real istanbul
+ * coverage-summary.json) are unaffected.
+ */
+/** The agent id of the MCP handler factory's coverage sessions. */
+export declare const MCP_COVERAGE_AGENT_ID = "qe-coverage-analysis";
+/**
+ * SQL predicate (no parameters) selecting coverage_sessions rows that are
+ * evidence. `CASE` keeps `json_extract` from running on malformed JSON.
+ */
+export declare const MEASURED_COVERAGE_SESSION_SQL: string;
+/** JS form of {@link MEASURED_COVERAGE_SESSION_SQL} for rows already loaded. */
+export declare function isMeasuredCoverageSession(row: {
+    agent_id?: string;
+    agentId?: string;
+    context?: unknown;
+    context_json?: string | null;
+}): boolean;
+//# sourceMappingURL=coverage-session-provenance.d.ts.map

package/dist/feedback/coverage-session-provenance.js

@@ -0,0 +1,39 @@
+/**
+ * Agentic QE v3 - Provenance of coverage_sessions rows (#1014)
+ *
+ * Up to 3.15.5 the MCP handler factory (agent `qe-coverage-analysis`) wrote a
+ * coverage_sessions row for EVERY coverage_analyze_sublinear call: a static
+ * estimate's figure, or 0.0 for an UNMEASURED target. Those rows have no
+ * provenance and never expire. Rows written from now on carry
+ * `context_json.measured = true`.
+ *
+ * Readers ignore legacy rows of that agent instead of deleting them (no data
+ * is destroyed; the coverage-learner's own retention ages them out). Rows of
+ * other writers (e.g. the post-command hook, which records a real istanbul
+ * coverage-summary.json) are unaffected.
+ */
+/** The agent id of the MCP handler factory's coverage sessions. */
+export const MCP_COVERAGE_AGENT_ID = 'qe-coverage-analysis';
+/**
+ * SQL predicate (no parameters) selecting coverage_sessions rows that are
+ * evidence. `CASE` keeps `json_extract` from running on malformed JSON.
+ */
+export const MEASURED_COVERAGE_SESSION_SQL = `(agent_id != '${MCP_COVERAGE_AGENT_ID}' OR ` +
+    `(CASE WHEN json_valid(context_json) THEN json_extract(context_json, '$.measured') END) = 1)`;
+/** JS form of {@link MEASURED_COVERAGE_SESSION_SQL} for rows already loaded. */
+export function isMeasuredCoverageSession(row) {
+    const agent = row.agent_id ?? row.agentId;
+    if (agent !== MCP_COVERAGE_AGENT_ID)
+        return true;
+    let context = row.context;
+    if (context === undefined && typeof row.context_json === 'string') {
+        try {
+            context = JSON.parse(row.context_json);
+        }
+        catch {
+            return false;
+        }
+    }
+    return !!context && typeof context === 'object' && context.measured === true;
+}
+//# sourceMappingURL=coverage-session-provenance.js.map

package/dist/init/orchestrator.js

@@ -161,6 +161,8 @@ export class ModularInitOrchestrator {
                 workersStarted: workersResult?.data?.workersConfigured ?? 0,
                 codexGuidance: assetsResult?.data?.codexGuidance,
                 codexComponents: assetsResult?.data?.codexComponents,
+                retiredAssetsRemoved: assetsResult?.data?.retiredAssetsRemoved,
+                retiredAssetsKept: assetsResult?.data?.retiredAssetsKept,
             },
             totalDurationMs: Date.now() - startTime,
             timestamp: new Date(),

package/dist/init/phases/09-assets.d.ts

@@ -20,6 +20,10 @@ export interface AssetsResult {
         policy: 'full' | 'compact' | 'none';
         ownedBytes: number;
     };
+    /** #1017: retired shipped files removed from the project (exact path + shipped hash). */
+    retiredAssetsRemoved?: string[];
+    /** #1017: retired files left in place (edited, symlinked, or outside the project). */
+    retiredAssetsKept?: string[];
     codexComponents?: {
         hooks: {
             status: string;

package/dist/init/phases/09-assets.js

@@ -8,6 +8,7 @@ import { BasePhase, } from './phase-interface.js';
 import { createSkillsInstaller } from '../skills-installer.js';
 import { createAgentsInstaller } from '../agents-installer.js';
 import { createN8nInstaller } from '../n8n-installer.js';
+import { retireShippedAssets } from '../retired-assets.js';
 import { installBrowserEngine, detectBrowserEngine, diagnosePlatform, DEFAULT_VIBIUM_SPEC, } from '../browser-engine-installer.js';
 import { initializeOverlays } from '../../routing/qe-agent-registry.js';
 /**
@@ -38,6 +39,8 @@ export class AssetsPhase extends BasePhase {
         let kiroHooks = 0;
         let codexGuidance;
         let codexComponents;
+        let retiredAssetsRemoved = [];
+        let retiredAssetsKept = [];
         if (options.upgrade) {
             context.services.log(`  Upgrade mode: overwriting existing files`);
         }
@@ -58,6 +61,36 @@ export class AssetsPhase extends BasePhase {
                 context.services.warn(`Skills warnings: ${skillsResult.errors.join(', ')}`);
             }
         }
+        // #1017: remove files earlier releases shipped under names the user's test
+        // runner collects. Runs on EVERY init that manages the Claude skills, not
+        // only --upgrade: plain `init --auto` on an existing install skips skills
+        // that are already present, so without this the stale copies would never
+        // leave. It is safe on every run because only an exact path whose content
+        // still equals a shipped version is deleted (edited copies keep their whole
+        // group), and the renamed replacements are installed so the skill keeps
+        // working without --upgrade.
+        if (!options.noClaude) {
+            const retired = retireShippedAssets(projectRoot, {
+                sourceSkillsDir: createSkillsInstaller({ projectRoot }).getSourceSkillsDir(),
+            });
+            retiredAssetsRemoved = retired.removed;
+            retiredAssetsKept = retired.kept.flatMap((k) => k.files);
+            for (const relPath of retired.removed) {
+                context.services.log(`  Removed retired asset: ${relPath}`);
+            }
+            for (const relPath of [...retired.installed, ...retired.refreshed]) {
+                context.services.log(`  Updated skill file: ${relPath}`);
+            }
+            for (const kept of retired.kept) {
+                context.services.warn(`Kept ${kept.files.join(', ')}: ${kept.why}. ${kept.advice}.`);
+            }
+            for (const note of retired.replacementWarnings) {
+                context.services.warn(`Skill file kept: ${note}.`);
+            }
+            if (retired.missingReplacements.length > 0) {
+                context.services.warn(`Could not install ${retired.missingReplacements.join(', ')}; run "aqe init --upgrade" to refresh the skills.`);
+            }
+        }
         // Install agents (Claude Code surface — skipped with --no-claude, #532)
         if (!options.noClaude) {
             try {
@@ -354,6 +387,8 @@ export class AssetsPhase extends BasePhase {
             browserEngine,
             codexGuidance,
             codexComponents,
+            retiredAssetsRemoved,
+            retiredAssetsKept,
         };
     }
     /**

package/dist/init/retired-assets.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Retired shipped assets (#1017).
+ *
+ * Earlier releases copied files into the user's project that 3.15.6 renames.
+ * Re-running `aqe init` skips skills that already exist, so an existing install
+ * would keep the stale copies, and their test-glob names make the user's own
+ * vitest / jest collect AQE's eval fixtures.
+ *
+ * Each group is retired as a unit:
+ *  - A retired file is removable only when its path matches exactly, it is a
+ *    regular file (not a symlink), its resolved parent directory is inside the
+ *    project root (no symlinked ancestor), and its sha256 equals a version AQE
+ *    actually shipped.
+ *  - If ANY present file in a group is not removable (edited, symlink, outside
+ *    the project, unreadable), the whole group is kept. Deleting a pristine
+ *    `budget.ts` next to a kept `budget.test.ts` would break the user's test run
+ *    with "Cannot find module './budget'".
+ *  - After removal, the renamed replacements are installed from the package
+ *    (never overwriting an existing file), and companion files that still name
+ *    the old files (README, eval yaml) are refreshed only when they are AQE's
+ *    unmodified shipped copies. Plain `init --auto` therefore leaves a working
+ *    skill without overwriting user edits.
+ */
+export interface RetiredFile {
+    /** Path relative to the project root, '/'-separated. */
+    readonly relPath: string;
+    /** sha256 (hex) of every distinct content AQE shipped at this path. */
+    readonly shippedSha256: readonly string[];
+}
+export interface ReplacementFile {
+    /** Destination relative to the project root. */
+    readonly relPath: string;
+    /** Source relative to the package skills directory (assets/skills). */
+    readonly source: string;
+}
+export interface RefreshFile extends ReplacementFile {
+    /** sha256 of every earlier shipped version; only those are overwritten. */
+    readonly previousSha256: readonly string[];
+}
+export interface RetiredAssetGroup {
+    readonly id: string;
+    /** Retired together: if one is kept, all are kept. */
+    readonly retired: readonly RetiredFile[];
+    /** Installed (if absent) once the group is retired. */
+    readonly replacements: readonly ReplacementFile[];
+    /** Overwritten once the group is retired, only if still AQE's unmodified copy. */
+    readonly refresh: readonly RefreshFile[];
+    /** Why the group was retired / what to do if it is kept. */
+    readonly advice: string;
+}
+/**
+ * Hashes are of `git show <tag>:assets/skills/<path>` over every v3 release tag.
+ * Retired files: one distinct content each (v3.13.0–v3.15.5 for qe-court,
+ * v3.0.0–v3.15.5 for testability-scoring); the same bytes now ship under the
+ * new names, which a unit test pins. Refreshed files list every earlier shipped
+ * content (qe-court.yaml changed once, at v3.14.0).
+ */
+export declare const RETIRED_ASSET_GROUPS: readonly RetiredAssetGroup[];
+export interface RetireOptions {
+    /** Package skills directory (assets/skills) used for replacements and refreshes. */
+    sourceSkillsDir?: string;
+    groups?: readonly RetiredAssetGroup[];
+}
+export interface RetireResult {
+    /** Retired files removed (exact path + shipped content). */
+    removed: string[];
+    /** Renamed replacements installed. */
+    installed: string[];
+    /** Companion files updated from AQE's unmodified copy. */
+    refreshed: string[];
+    /** Groups left in place, with the files, the cause, and what to do. */
+    kept: Array<{
+        group: string;
+        files: string[];
+        why: string;
+        advice: string;
+    }>;
+    /** Replacements that could not be installed (missing package source or unsafe target). */
+    missingReplacements: string[];
+    /** Why a replacement target was left alone (symlink or other non-file in the way). */
+    replacementWarnings: string[];
+}
+export declare function sha256Hex(content: Buffer): string;
+/** Remove retired assets AQE shipped unmodified, install replacements; keep anything else. */
+export declare function retireShippedAssets(projectRoot: string, options?: RetireOptions): RetireResult;
+//# sourceMappingURL=retired-assets.d.ts.map