@dailephd/my-dev-kit-lab 0.4.9 → 0.5.1

package/dist/src/cli/help.js

@@ -142,7 +142,7 @@ export function renderExperimentRunHelp() {
         "Required:",
         "  --experiment <id>   Registered experiment plugin id (see \"my-dev-kit-lab experiment list\")",
         "",
-        "Options:",
+        "Common options (all plugins):",
         "  --target <path>                                    Local target project path (default: self)",
         "  --out <dir>                                         Output directory for experiment artifacts",
         "                                                      (default: beneath the workspace when installed)",
@@ -152,6 +152,15 @@ export function renderExperimentRunHelp() {
         "                                                      (default: the bundled package resource)",
         "  --case <ids>                                       Comma-separated case ids to run",
         "  --benchmark-project <ids>                          Comma-separated benchmark project ids to run",
+        "",
+        "warm-index-reuse only:",
+        "  --kit-command <command>                            my-dev-kit command used to build one index per benchmark",
+        "                                                      project and retrieve per task",
+        "                                                      (default: npx @dailephd/my-dev-kit@latest)",
+        "                                                      Agent evidence uses the deterministic fake agent only;",
+        "                                                      agent options below are not accepted by this plugin.",
+        "",
+        "context-strategy-comparison only:",
         "  --agents <list>                                    Comma-separated agent ids (default: fake-agent)",
         "  --strategies <list>                                Comma-separated strategies: raw-full-file,my-dev-kit-guided",
         "  --complexities <list>                               Comma-separated complexity levels: short,medium,long,multi-step",
@@ -238,19 +247,25 @@ export function renderPlotsHelp() {
         "  my-dev-kit-lab plots --help",
         "",
         "Commands:",
-        "  generate   Generate experiment plot artifacts from controlled-experiment artifacts.",
+        "  generate   Generate experiment plot artifacts from controlled-experiment or supported",
+        "             plugin experiment artifacts (warm-index-reuse).",
         "             Run \"my-dev-kit-lab plots generate --help\" for details."
     ].join("\n");
 }
 export function renderPlotsGenerateHelp() {
     return [
-        "my-dev-kit-lab plots generate - generate chart/plot artifacts from controlled-experiment artifacts",
+        "my-dev-kit-lab plots generate - generate chart/plot artifacts from experiment artifacts",
         "",
         "Usage:",
         "  my-dev-kit-lab plots generate --experiment <dir> --out <dir>",
         "",
+        "Supported inputs:",
+        "  - legacy controlled-experiment output directories",
+        "  - warm-index-reuse plugin output directories (containing its report.json)",
+        "  Other plugin outputs are not plotted by this command.",
+        "",
         "Required:",
-        "  --experiment <dir>   Path to a controlled-experiment output directory",
+        "  --experiment <dir>   Path to a supported experiment output directory",
         "  --out <dir>          Output directory for plot artifacts"
     ].join("\n");
 }

package/dist/src/commands/runExperimentDescribeCommand.js

@@ -106,6 +106,9 @@ function readConfigFields(plugin, required) {
     }));
 }
 function readSupportedVariants(plugin) {
+    if (plugin.supportedVariants) {
+        return [...plugin.supportedVariants];
+    }
     const strategies = readArrayField(plugin.defaultConfig, "strategies");
     return strategies.filter((value) => typeof value === "string");
 }
@@ -139,9 +142,15 @@ function describeExpectedReports(plugin) {
     return `Writes supported outputs: ${plugin.metadata.supportedOutputs.join(", ")}.`;
 }
 function describeExamples(plugin) {
+    // Only advertise agent-matrix options for plugins that declare them.
+    const agentOptions = hasConfigField(plugin, "agents") ? " --agents fake-agent --complexities short" : "";
+    const screenshotOption = hasConfigField(plugin, "agents") ? " --no-screenshot" : "";
     return [
         `my-dev-kit-lab experiment describe --experiment ${plugin.metadata.id}`,
-        `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --agents fake-agent --complexities short`,
-        `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --target "Z:\\Users\\newuser\\Projects\\my-dev-kit-v1" --agents fake-agent --complexities short --no-screenshot`
+        `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id}${agentOptions}`,
+        `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --target "Z:\\Users\\newuser\\Projects\\my-dev-kit-v1"${agentOptions}${screenshotOption}`
     ];
 }
+function hasConfigField(plugin, name) {
+    return (plugin.configDefinition?.fields ?? []).some((field) => field.name === name);
+}

package/dist/src/commands/runExperimentListCommand.js

@@ -29,6 +29,9 @@ function toListedExperiment(metadata, plugin) {
     };
 }
 function readSupportedVariants(plugin) {
+    if (plugin.supportedVariants) {
+        return [...plugin.supportedVariants];
+    }
     const strategies = readArrayField(plugin.defaultConfig, "strategies");
     return strategies.filter((value) => typeof value === "string");
 }

package/dist/src/commands/runExperimentRunCommand.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { parseAgentCommandTemplate } from "../agents/index.js";
 import { parseAgentId } from "../agents/agentRegistry.js";
 import { readBenchmarkProjectProfiles, readEvaluationCases } from "../evaluation/index.js";
-import { contextStrategyComparisonPlugin, createDefaultExperimentPluginRegistry, resolveExperimentTarget, runExperiment } from "../experiments/index.js";
+import { contextStrategyComparisonPlugin, createDefaultExperimentPluginRegistry, resolveExperimentTarget, runExperiment, warmIndexReusePlugin } from "../experiments/index.js";
 import { buildDefaultExperimentOutputRoot } from "../experiments/outputPaths.js";
 import { parsePromptComplexityLevel, parsePromptStrategy } from "../prompts/index.js";
 import { writePluginExperimentReports } from "../report/index.js";
@@ -100,6 +100,7 @@ export function parseRunExperimentArgs(argv) {
     let continueOnFailure;
     let requireAgents;
     let includeRealAgents;
+    let kitCommand;
     const commandTemplates = {};
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -157,6 +158,9 @@ export function parseRunExperimentArgs(argv) {
         else if (arg === "--command-template-claude") {
             commandTemplates.claude = parseAgentCommandTemplate(readRequiredValue(argv, ++index, "--command-template-claude"));
         }
+        else if (arg === "--kit-command") {
+            kitCommand = readRequiredValue(argv, ++index, "--kit-command");
+        }
         else if (arg === "--no-screenshot") {
             // The plugin-aware report path does not capture screenshots yet; accept this
             // flag so smoke commands can share the legacy demo option set.
@@ -168,6 +172,9 @@ export function parseRunExperimentArgs(argv) {
     if (!experimentId) {
         throw new Error("Usage: --experiment <id> [--target <path>] [--out <directory>]");
     }
+    if (kitCommand !== undefined && experimentId !== warmIndexReusePlugin.metadata.id) {
+        throw new Error(`--kit-command is only supported for --experiment ${warmIndexReusePlugin.metadata.id}.`);
+    }
     return {
         experimentId,
         targetPath,
@@ -185,7 +192,8 @@ export function parseRunExperimentArgs(argv) {
             continueOnFailure,
             requireAgents,
             includeRealAgents,
-            commandTemplates: Object.keys(commandTemplates).length > 0 ? commandTemplates : undefined
+            commandTemplates: Object.keys(commandTemplates).length > 0 ? commandTemplates : undefined,
+            kitCommand
         })
     };
 }
@@ -212,13 +220,25 @@ function generateExperimentRunId(pluginId) {
     return `${pluginId}-${timestamp}`;
 }
 async function loadPluginInputs(args, toolRoot, context) {
-    if (args.experimentId !== contextStrategyComparisonPlugin.metadata.id) {
-        return undefined;
+    if (args.experimentId === contextStrategyComparisonPlugin.metadata.id) {
+        const validation = contextStrategyComparisonPlugin.validateConfig(args.config);
+        if (!validation.valid || !validation.config) {
+            throw new Error(`Invalid context strategy comparison config: ${validation.errors.join("; ")}`);
+        }
+        return loadCasesAndProjectProfiles(args, toolRoot, context);
     }
-    const validation = contextStrategyComparisonPlugin.validateConfig(args.config);
-    if (!validation.valid || !validation.config) {
-        throw new Error(`Invalid context strategy comparison config: ${validation.errors.join("; ")}`);
+    if (args.experimentId === warmIndexReusePlugin.metadata.id) {
+        const validation = warmIndexReusePlugin.validateConfig(args.config);
+        if (!validation.valid || !validation.config) {
+            throw new Error(`Invalid warm index reuse config: ${validation.errors.join("; ")}`);
+        }
+        return loadCasesAndProjectProfiles(args, toolRoot, context);
     }
+    return undefined;
+}
+// Shared by both registered plugins: explicit paths resolve against toolRoot, defaults come from
+// bundled package resources so they do not depend on the invocation cwd.
+async function loadCasesAndProjectProfiles(args, toolRoot, context) {
     const projectProfilesPath = args.config.projectProfilesPath
         ? path.resolve(toolRoot, args.config.projectProfilesPath)
         : resolvePackageResource(context, DEFAULT_PROJECT_PROFILES_RESOURCE);

package/dist/src/evaluation/benchmarkMetadata.js

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { PROJECT_COMPLEXITY_FORMULA, calculateProjectComplexityScore } from "./projectComplexity.js";
+import { PROJECT_COMPLEXITY_FORMULA, calculateProjectComplexityScore, roundToTwo } from "./projectComplexity.js";
+import { TASK_LOCALITIES } from "./types.js";
 export const REQUIRED_BENCHMARK_PROJECT_IDS = [
     "todo-ts",
     "todo-python",
@@ -11,6 +12,8 @@ export const REQUIRED_BENCHMARK_PROJECT_IDS = [
     "task-analytics-large-mixed"
 ];
 export const VALID_COMPLEXITY_LEVELS = new Set(["small", "medium", "large", "mixed-language"]);
+export const REQUIRED_WARM_INDEX_BENCHMARK_PROJECT_IDS = ["task-workflow-medium-ts", "task-analytics-large-mixed"];
+export const MIN_WARM_INDEX_TASKS_PER_PROJECT = 5;
 export async function readBenchmarkProjectProfiles(profilesPath, repoRoot = process.cwd()) {
     let parsed;
     try {
@@ -95,6 +98,193 @@ export function validateAnswerKey(answerKey, label) {
     }
     return errors;
 }
+export function validateTaskLocality(value, label) {
+    if (typeof value === "string" && TASK_LOCALITIES.includes(value)) {
+        return [];
+    }
+    return [`${label}: taskLocality must be one of ${TASK_LOCALITIES.join(", ")} (received ${JSON.stringify(value)}).`];
+}
+export function deriveWarmIndexTaskStats(cases, projectId) {
+    const projectCases = cases.filter((benchmarkCase) => benchmarkCase?.benchmarkProject === projectId);
+    if (projectCases.length === 0) {
+        return { taskCount: 0, expectedRelevantFilesAverage: 0, expectedRelevantSymbolsAverage: 0 };
+    }
+    const fileCounts = projectCases.map((benchmarkCase) => (Array.isArray(benchmarkCase.expectedFiles) ? benchmarkCase.expectedFiles.length : 0));
+    const symbolCounts = projectCases.map((benchmarkCase) => Array.isArray(benchmarkCase.expectedSymbols) ? benchmarkCase.expectedSymbols.length : 0);
+    return {
+        taskCount: projectCases.length,
+        expectedRelevantFilesAverage: roundToTwo(fileCounts.reduce((total, count) => total + count, 0) / projectCases.length),
+        expectedRelevantSymbolsAverage: roundToTwo(symbolCounts.reduce((total, count) => total + count, 0) / projectCases.length)
+    };
+}
+export function validateWarmIndexBenchmarkCases(cases, profiles, repoRoot = process.cwd()) {
+    const errors = [];
+    const profilesById = new Map(profiles.map((profile) => [profile.projectId, profile]));
+    const ids = new Set();
+    const sourceRootsByProject = new Map();
+    cases.forEach((benchmarkCase, index) => {
+        if (!benchmarkCase || typeof benchmarkCase !== "object") {
+            errors.push(`warm-index case at index ${index}: must be an object.`);
+            return;
+        }
+        const id = typeof benchmarkCase.id === "string" && benchmarkCase.id.length > 0 ? benchmarkCase.id : undefined;
+        const label = id === undefined ? `warm-index case at index ${index}` : `warm-index case ${id}`;
+        if (id === undefined) {
+            errors.push(`${label}: id must be a nonempty string.`);
+        }
+        else if (ids.has(id)) {
+            errors.push(`${label}: duplicate case id.`);
+        }
+        else {
+            ids.add(id);
+        }
+        const projectId = typeof benchmarkCase.benchmarkProject === "string" && benchmarkCase.benchmarkProject.length > 0
+            ? benchmarkCase.benchmarkProject
+            : undefined;
+        if (projectId === undefined) {
+            errors.push(`${label}: benchmarkProject must be a nonempty string.`);
+        }
+        if (typeof benchmarkCase.projectProfileRef !== "string" || benchmarkCase.projectProfileRef.length === 0) {
+            errors.push(`${label}: missing projectProfileRef.`);
+        }
+        else if (benchmarkCase.projectProfileRef !== projectId) {
+            errors.push(`${label}: projectProfileRef ${benchmarkCase.projectProfileRef} must equal benchmarkProject ${projectId ?? "<missing>"}.`);
+        }
+        const profile = projectId === undefined ? undefined : profilesById.get(projectId);
+        if (projectId !== undefined && profile === undefined) {
+            errors.push(`${label}: unknown benchmark project profile ${projectId}.`);
+        }
+        if (benchmarkCase.taskLocality === undefined) {
+            errors.push(`${label}: missing taskLocality; expected one of ${TASK_LOCALITIES.join(", ")}.`);
+        }
+        else {
+            errors.push(...validateTaskLocality(benchmarkCase.taskLocality, label));
+        }
+        const targetRoot = typeof benchmarkCase.targetRoot === "string" && benchmarkCase.targetRoot.length > 0 ? benchmarkCase.targetRoot : undefined;
+        if (targetRoot === undefined) {
+            errors.push(`${label}: targetRoot must be a nonempty string.`);
+        }
+        else if (profile !== undefined && normalizeRelativeRoot(targetRoot) !== normalizeRelativeRoot(profile.rootPath ?? "")) {
+            errors.push(`${label}: targetRoot ${targetRoot} does not match profile ${profile.projectId} rootPath ${profile.rootPath}.`);
+        }
+        if (!Array.isArray(benchmarkCase.sourceRoots) || benchmarkCase.sourceRoots.length === 0) {
+            errors.push(`${label}: sourceRoots must be a nonempty array.`);
+        }
+        else {
+            if (profile !== undefined) {
+                errors.push(...validateWarmIndexSourceRoots(benchmarkCase.sourceRoots, profile, label));
+            }
+            if (projectId !== undefined) {
+                const reference = sourceRootsByProject.get(projectId);
+                if (reference === undefined) {
+                    sourceRootsByProject.set(projectId, { caseLabel: label, sourceRoots: benchmarkCase.sourceRoots });
+                }
+                else if (!sameOrderedValues(reference.sourceRoots, benchmarkCase.sourceRoots)) {
+                    errors.push(`${label}: sourceRoots ${JSON.stringify(benchmarkCase.sourceRoots)} must match the ordered sourceRoots ${JSON.stringify(reference.sourceRoots)} of ${reference.caseLabel} for project ${projectId}.`);
+                }
+            }
+        }
+        const expectedFiles = Array.isArray(benchmarkCase.expectedFiles) ? benchmarkCase.expectedFiles : undefined;
+        const expectedSymbols = Array.isArray(benchmarkCase.expectedSymbols) ? benchmarkCase.expectedSymbols : undefined;
+        if (expectedFiles === undefined || expectedFiles.length === 0) {
+            errors.push(`${label}: expectedFiles must be a nonempty array.`);
+        }
+        if (expectedSymbols === undefined || expectedSymbols.length === 0) {
+            errors.push(`${label}: expectedSymbols must be a nonempty array.`);
+        }
+        if (benchmarkCase.answerKey === undefined) {
+            errors.push(`${label}: missing answerKey.`);
+        }
+        else {
+            errors.push(...validateAnswerKey(benchmarkCase.answerKey, label));
+            const answerKey = benchmarkCase.answerKey;
+            if (answerKey && typeof answerKey === "object") {
+                if (expectedFiles !== undefined && Array.isArray(answerKey.expectedFiles) && !sameOrderedValues(expectedFiles, answerKey.expectedFiles)) {
+                    errors.push(`${label}: expectedFiles must exactly match answerKey.expectedFiles (same values in the same order).`);
+                }
+                if (expectedSymbols !== undefined &&
+                    Array.isArray(answerKey.expectedSymbols) &&
+                    !sameOrderedValues(expectedSymbols, answerKey.expectedSymbols)) {
+                    errors.push(`${label}: expectedSymbols must exactly match answerKey.expectedSymbols (same values in the same order).`);
+                }
+            }
+        }
+        if (expectedFiles !== undefined && targetRoot !== undefined) {
+            for (const expectedFile of expectedFiles) {
+                if (typeof expectedFile !== "string" || expectedFile.length === 0 || path.isAbsolute(expectedFile) || expectedFile.includes("..")) {
+                    errors.push(`${label}: expected file must be a safe relative path: ${String(expectedFile)}.`);
+                }
+                else if (!existsSync(path.resolve(repoRoot, targetRoot, expectedFile))) {
+                    errors.push(`${label}: expected file does not exist in ${projectId ?? targetRoot}: ${expectedFile}.`);
+                }
+            }
+        }
+    });
+    const representedProjectIds = [
+        ...new Set(cases
+            .map((benchmarkCase) => benchmarkCase?.benchmarkProject)
+            .filter((projectId) => typeof projectId === "string" && projectId.length > 0))
+    ].sort();
+    for (const projectId of representedProjectIds) {
+        const profile = profilesById.get(projectId);
+        if (profile === undefined || !profile.complexityMetrics || typeof profile.complexityMetrics !== "object") {
+            continue;
+        }
+        const derived = deriveWarmIndexTaskStats(cases, projectId);
+        for (const field of ["taskCount", "expectedRelevantFilesAverage", "expectedRelevantSymbolsAverage"]) {
+            if (profile.complexityMetrics[field] !== derived[field]) {
+                errors.push(`profile ${projectId}: complexityMetrics.${field} ${profile.complexityMetrics[field]} does not match warm-index corpus value ${derived[field]}.`);
+            }
+        }
+    }
+    return errors;
+}
+export function validateWarmIndexBenchmarkSuiteCoverage(cases) {
+    const errors = [];
+    for (const projectId of REQUIRED_WARM_INDEX_BENCHMARK_PROJECT_IDS) {
+        const projectCases = cases.filter((benchmarkCase) => benchmarkCase?.benchmarkProject === projectId);
+        if (projectCases.length === 0) {
+            errors.push(`warm-index suite: missing required benchmark project ${projectId}.`);
+            continue;
+        }
+        if (projectCases.length < MIN_WARM_INDEX_TASKS_PER_PROJECT) {
+            errors.push(`warm-index suite: project ${projectId} has ${projectCases.length} cases; at least ${MIN_WARM_INDEX_TASKS_PER_PROJECT} are required.`);
+        }
+        for (const locality of TASK_LOCALITIES) {
+            if (!projectCases.some((benchmarkCase) => benchmarkCase.taskLocality === locality)) {
+                errors.push(`warm-index suite: project ${projectId} has no ${locality} case.`);
+            }
+        }
+    }
+    return errors;
+}
+function validateWarmIndexSourceRoots(sourceRoots, profile, label) {
+    const errors = [];
+    const allowedRoots = [...(profile.sourceRoots ?? []), ...(profile.testRoots ?? [])];
+    const seen = new Set();
+    for (const sourceRoot of sourceRoots) {
+        if (seen.has(sourceRoot)) {
+            errors.push(`${label}: duplicate source root ${JSON.stringify(sourceRoot)}.`);
+            continue;
+        }
+        seen.add(sourceRoot);
+        if (typeof sourceRoot !== "string" || !allowedRoots.includes(sourceRoot)) {
+            errors.push(`${label}: unknown source root ${JSON.stringify(sourceRoot)} for profile ${profile.projectId}; allowed roots: ${allowedRoots.join(", ")}.`);
+        }
+    }
+    for (const allowedRoot of allowedRoots) {
+        if (!seen.has(allowedRoot)) {
+            errors.push(`${label}: missing profile source/test root ${allowedRoot} for profile ${profile.projectId}.`);
+        }
+    }
+    return errors;
+}
+function normalizeRelativeRoot(value) {
+    return path.posix.normalize(value.replace(/\\/g, "/")).replace(/\/+$/, "");
+}
+function sameOrderedValues(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
 export function validateBenchmarkProjectProfiles(profiles, repoRoot = process.cwd()) {
     const errors = [];
     const ids = new Set(profiles.map((profile) => profile.projectId));

package/dist/src/evaluation/projectComplexity.js

@@ -73,7 +73,7 @@ export function computeProjectComplexityMetrics(projectRoot, fileTree, taskStats
 function normalize(value, cap) {
     return Math.min(value / cap, 1);
 }
-function roundToTwo(value) {
+export function roundToTwo(value) {
     return Math.round(value * 100) / 100;
 }
 function sum(values) {

package/dist/src/evaluation/readEvaluationCases.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { resolveWithinRoot } from "../core/pathSafety.js";
-import { validateAnswerKey } from "./benchmarkMetadata.js";
+import { validateAnswerKey, validateTaskLocality } from "./benchmarkMetadata.js";
 export async function readEvaluationCases(casesPath, repoRoot = process.cwd(), options = {}) {
     let parsed;
     try {
@@ -36,6 +36,12 @@ export async function readEvaluationCases(casesPath, repoRoot = process.cwd(), o
             throw new Error(`Duplicate evaluation case id: ${input.id}`);
         }
         ids.add(input.id);
+        if (candidate.taskLocality !== undefined) {
+            const localityErrors = validateTaskLocality(candidate.taskLocality, `evaluation case ${input.id}`);
+            if (localityErrors.length > 0) {
+                throw new Error(localityErrors.join("\n"));
+            }
+        }
         if (candidate.answerKey !== undefined) {
             const answerKeyErrors = validateAnswerKey(candidate.answerKey, `evaluation case ${input.id}`);
             if (answerKeyErrors.length > 0) {

package/dist/src/evaluation/runMyDevKitRetrieval.js

@@ -39,52 +39,71 @@ function pickCandidateFields(candidate) {
         symbol: readString("symbol", "name", "label")
     };
 }
-export async function runMyDevKitRetrieval(options) {
-    const started = Date.now();
+function skippedRetrieval(caseId, warnings, commands, durationMs) {
+    return {
+        caseId,
+        skipped: true,
+        warnings,
+        totalChars: 0,
+        totalEstimatedTokens: 0,
+        tokenCountMethod,
+        contextText: "",
+        filesRead: [],
+        commands,
+        durationMs
+    };
+}
+/**
+ * Runs exactly one my-dev-kit `index` command for the target and writes the index only to
+ * `indexDir`. Performs no search/lookup/slice/source work. With `requireKit` a failed index
+ * throws; otherwise the failure is returned as `ok: false` with a warning.
+ */
+export async function buildMyDevKitIndex(options) {
     const warnings = [];
-    const commandsDir = path.join(options.outputDir, "commands", options.evaluationCase.id);
-    const indexesDir = path.join(options.outputDir, "indexes", options.evaluationCase.id);
-    const commands = [];
-    const indexCommand = await runMeasuredCommand({
+    const command = await runMeasuredCommand({
         commandId: "index",
         commandString: options.kitCommand,
         cwd: process.cwd(),
-        outDir: commandsDir,
+        outDir: options.commandsDir,
         extraArgs: [
             "index",
             "--root",
-            options.evaluationCase.absoluteTargetRoot,
-            ...options.evaluationCase.sourceRoots.flatMap((sourceRoot) => ["--src", sourceRoot]),
+            options.target.absoluteTargetRoot,
+            ...options.target.sourceRoots.flatMap((sourceRoot) => ["--src", sourceRoot]),
             "--out",
-            indexesDir,
+            options.indexDir,
             "--json"
         ]
     });
-    commands.push(indexCommand);
-    if (!indexCommand.ok) {
+    if (!command.ok) {
         if (options.requireKit) {
-            throw new Error(indexCommand.error || `my-dev-kit index failed with exit code ${indexCommand.exitCode}`);
+            throw new Error(command.error || `my-dev-kit index failed with exit code ${command.exitCode}`);
         }
         warnings.push("my-dev-kit index command was unavailable or failed.");
-        return {
-            caseId: options.evaluationCase.id,
-            skipped: true,
-            warnings,
-            totalChars: 0,
-            totalEstimatedTokens: 0,
-            tokenCountMethod,
-            contextText: "",
-            filesRead: [],
-            commands,
-            durationMs: Date.now() - started
-        };
     }
+    return {
+        ok: command.ok,
+        indexDir: options.indexDir,
+        durationMs: command.durationMs,
+        warnings,
+        command
+    };
+}
+/**
+ * Runs search -> lookup -> slice -> source against an already prepared index. Never invokes
+ * `index`; `durationMs` covers retrieval only.
+ */
+export async function runMyDevKitRetrievalFromIndex(options) {
+    const started = Date.now();
+    const warnings = [];
+    const commands = [];
+    const { commandsDir, indexDir } = options;
     const searchCommand = await runMeasuredCommand({
         commandId: "search",
         commandString: options.kitCommand,
         cwd: process.cwd(),
         outDir: commandsDir,
-        extraArgs: ["search", "--index", indexesDir, "--query", options.evaluationCase.query, "--json"]
+        extraArgs: ["search", "--index", indexDir, "--query", options.evaluationCase.query, "--json"]
     });
     commands.push(searchCommand);
     if (!searchCommand.ok) {
@@ -92,36 +111,14 @@ export async function runMyDevKitRetrieval(options) {
             throw new Error(searchCommand.error || `my-dev-kit search failed with exit code ${searchCommand.exitCode}`);
         }
         warnings.push("my-dev-kit search command failed.");
-        return {
-            caseId: options.evaluationCase.id,
-            skipped: true,
-            warnings,
-            totalChars: 0,
-            totalEstimatedTokens: 0,
-            tokenCountMethod,
-            contextText: "",
-            filesRead: [],
-            commands,
-            durationMs: Date.now() - started
-        };
+        return skippedRetrieval(options.evaluationCase.id, warnings, commands, Date.now() - started);
     }
     const searchPayload = parseJsonIfPossible(searchCommand.stdout);
     const candidates = readSearchResults(searchPayload);
     const selected = candidates[0];
     if (!selected) {
         warnings.push("No my-dev-kit search candidate was found.");
-        return {
-            caseId: options.evaluationCase.id,
-            skipped: true,
-            warnings,
-            totalChars: 0,
-            totalEstimatedTokens: 0,
-            tokenCountMethod,
-            contextText: "",
-            filesRead: [],
-            commands,
-            durationMs: Date.now() - started
-        };
+        return skippedRetrieval(options.evaluationCase.id, warnings, commands, Date.now() - started);
     }
     const candidate = pickCandidateFields(selected);
     const selectedNodeId = candidate.nodeId;
@@ -136,7 +133,7 @@ export async function runMyDevKitRetrieval(options) {
             commandString: options.kitCommand,
             cwd: process.cwd(),
             outDir: commandsDir,
-            extraArgs: ["lookup", "--index", indexesDir, "--node", selectedNodeId, "--json"]
+            extraArgs: ["lookup", "--index", indexDir, "--node", selectedNodeId, "--json"]
         });
         commands.push(lookupCommand);
         if (lookupCommand.ok) {
@@ -150,7 +147,7 @@ export async function runMyDevKitRetrieval(options) {
             commandString: options.kitCommand,
             cwd: process.cwd(),
             outDir: commandsDir,
-            extraArgs: ["slice", "--index", indexesDir, "--node", selectedNodeId, "--json"]
+            extraArgs: ["slice", "--index", indexDir, "--node", selectedNodeId, "--json"]
         });
         commands.push(sliceCommand);
         if (sliceCommand.ok) {
@@ -164,7 +161,7 @@ export async function runMyDevKitRetrieval(options) {
             commandString: options.kitCommand,
             cwd: process.cwd(),
             outDir: commandsDir,
-            extraArgs: ["source", "--index", indexesDir, "--node", selectedNodeId, "--max-lines", "160", "--format", "numbered"]
+            extraArgs: ["source", "--index", indexDir, "--node", selectedNodeId, "--max-lines", "160", "--format", "numbered"]
         });
         commands.push(sourceCommand);
         if (sourceCommand.ok) {
@@ -195,3 +192,35 @@ export async function runMyDevKitRetrieval(options) {
         durationMs: Date.now() - started
     };
 }
+/**
+ * Legacy per-case lifecycle: builds a case-specific index and retrieves from it. `commands`
+ * starts with the index command and `durationMs` covers the whole lifecycle including indexing.
+ */
+export async function runMyDevKitRetrieval(options) {
+    const started = Date.now();
+    const commandsDir = path.join(options.outputDir, "commands", options.evaluationCase.id);
+    const indexDir = path.join(options.outputDir, "indexes", options.evaluationCase.id);
+    const index = await buildMyDevKitIndex({
+        target: options.evaluationCase,
+        kitCommand: options.kitCommand,
+        indexDir,
+        commandsDir,
+        requireKit: options.requireKit
+    });
+    if (!index.ok) {
+        return skippedRetrieval(options.evaluationCase.id, [...index.warnings], [index.command], Date.now() - started);
+    }
+    const retrieval = await runMyDevKitRetrievalFromIndex({
+        evaluationCase: options.evaluationCase,
+        kitCommand: options.kitCommand,
+        indexDir,
+        commandsDir,
+        requireKit: options.requireKit
+    });
+    return {
+        ...retrieval,
+        warnings: [...index.warnings, ...retrieval.warnings],
+        commands: [index.command, ...retrieval.commands],
+        durationMs: Date.now() - started
+    };
+}

package/dist/src/evaluation/types.js

@@ -1 +1 @@
-export {};
+export const TASK_LOCALITIES = ["localized", "cross-module", "broad-change"];

package/dist/src/experiments/defaultRegistry.js

@@ -1,7 +1,9 @@
 import { ExperimentPluginRegistry } from "./registry.js";
 import { contextStrategyComparisonPlugin } from "./plugins/contextStrategyComparison/index.js";
+import { warmIndexReusePlugin } from "./plugins/warmIndexReuse/index.js";
 export function createDefaultExperimentPluginRegistry() {
     const registry = new ExperimentPluginRegistry();
     registry.register(contextStrategyComparisonPlugin);
+    registry.register(warmIndexReusePlugin);
     return registry;
 }

package/dist/src/experiments/plugins/index.js

@@ -1 +1,2 @@
 export * from "./contextStrategyComparison/index.js";
+export * from "./warmIndexReuse/index.js";