@dailephd/my-dev-kit-lab 0.6.2 → 0.7.0

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, getWarmIndexCampaignPreset, incrementalChangeStalenessPlugin, parseWarmIndexCampaignPresetId, resolveExperimentTarget, runExperiment, warmIndexReusePlugin } from "../experiments/index.js";
+import { contextStrategyComparisonPlugin, contextWindowScalingPlugin, createDefaultExperimentPluginRegistry, getWarmIndexCampaignPreset, incrementalChangeStalenessPlugin, parseContextBudgetsCliValue, parseWarmIndexCampaignPresetId, 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";
@@ -32,6 +32,11 @@ import { runWarmIndexCampaignPresentation } from "./runWarmIndexCampaignPresenta
 // ---------------------------------------------------------------------------
 const DEFAULT_CASES_RESOURCE = "examples/token-savings-cases.json";
 const DEFAULT_PROJECT_PROFILES_RESOURCE = "benchmarks/contracts/benchmark-project-profiles.json";
+// context-window-scaling owns one frozen bundled case catalog; its fixed project is referenced by the
+// catalog's package-relative targetRoot, so both resolve from the package root, never the cwd.
+const CONTEXT_WINDOW_SCALING_CASES_RESOURCE = "benchmarks/contracts/context-window-scaling-cases.json";
+// Options the context-window-scaling plugin accepts; every other flag is rejected, not ignored.
+const CONTEXT_WINDOW_SCALING_ALLOWED_FLAGS = ["--experiment", "--out", "--case", "--context-budgets", "--kit-command"];
 export async function runExperimentRunCommandFromArgs(argv, options = {}) {
     try {
         const args = parseRunExperimentArgs(argv);
@@ -52,7 +57,7 @@ export async function runExperimentRunCommandFromArgs(argv, options = {}) {
             registry,
             targetPath: args.targetPath,
             outputRoot,
-            config: args.config,
+            config: pluginConfigFor(args),
             inputs,
             toolRoot,
             runId
@@ -76,7 +81,6 @@ export async function runExperimentRunCommandFromArgs(argv, options = {}) {
         // Automatic presentation (report already produced above) applies only to warm-index-reuse
         // campaign runs; legacy fake-agent warm-index runs and context-strategy-comparison stay
         // report-only, unchanged.
-        let screenshotFailed = false;
         if (args.experimentId === warmIndexReusePlugin.metadata.id && args.config.campaignPreset) {
             const executionArtifactPath = readMetadataString(result.metadata?.executionArtifactPath);
             const campaignAgentId = readMetadataString(result.metadata?.campaignAgentId);
@@ -106,7 +110,6 @@ export async function runExperimentRunCommandFromArgs(argv, options = {}) {
             else {
                 outputLines.push("Screenshot: failed");
                 outputLines.push(presentation.screenshot.error ?? "Screenshot capture failed.");
-                screenshotFailed = true;
             }
             outputLines.push(`Gallery manifest: ${presentation.gallery.manifestPath}`);
             outputLines.push(`Gallery index: ${presentation.gallery.indexPath}`);
@@ -114,8 +117,6 @@ export async function runExperimentRunCommandFromArgs(argv, options = {}) {
         console.log(outputLines.join("\n"));
         if (result.status === "failed")
             return 1;
-        if (screenshotFailed)
-            return 1;
         return 0;
     }
     catch (error) {
@@ -146,9 +147,13 @@ export function parseRunExperimentArgs(argv) {
     let includeRealAgents;
     let kitCommand;
     let campaignPreset;
+    let contextBudgets;
+    const seenFlags = [];
     const commandTemplates = {};
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
+        if (arg !== undefined && arg.startsWith("--"))
+            seenFlags.push(arg);
         if (arg === "--experiment") {
             experimentId = readRequiredValue(argv, ++index, "--experiment");
         }
@@ -206,6 +211,9 @@ export function parseRunExperimentArgs(argv) {
         else if (arg === "--kit-command") {
             kitCommand = readRequiredValue(argv, ++index, "--kit-command");
         }
+        else if (arg === "--context-budgets") {
+            contextBudgets = parseContextBudgetsCliValue(readRequiredValue(argv, ++index, "--context-budgets"));
+        }
         else if (arg === "--campaign") {
             campaignPreset = parseWarmIndexCampaignPresetId(readRequiredValue(argv, ++index, "--campaign"));
         }
@@ -220,7 +228,23 @@ export function parseRunExperimentArgs(argv) {
     if (!experimentId) {
         throw new Error("Usage: --experiment <id> [--target <path>] [--out <directory>]");
     }
-    const KIT_COMMAND_PLUGIN_IDS = [warmIndexReusePlugin.metadata.id, incrementalChangeStalenessPlugin.metadata.id];
+    const KIT_COMMAND_PLUGIN_IDS = [
+        warmIndexReusePlugin.metadata.id,
+        incrementalChangeStalenessPlugin.metadata.id,
+        contextWindowScalingPlugin.metadata.id
+    ];
+    if (contextBudgets !== undefined && experimentId !== contextWindowScalingPlugin.metadata.id) {
+        throw new Error(`--context-budgets is only supported for --experiment ${contextWindowScalingPlugin.metadata.id}.`);
+    }
+    if (experimentId === contextWindowScalingPlugin.metadata.id) {
+        const unsupported = [...new Set(seenFlags.filter((flag) => !CONTEXT_WINDOW_SCALING_ALLOWED_FLAGS.includes(flag)))];
+        if (unsupported.length > 0) {
+            throw new Error(`${unsupported.join(", ")} ${unsupported.length === 1 ? "is" : "are"} not supported for --experiment ${experimentId}; supported options: ${CONTEXT_WINDOW_SCALING_ALLOWED_FLAGS.join(", ")}.`);
+        }
+        if (seenFlags.includes("--case") && caseIds.length === 0) {
+            throw new Error("--case must list at least one case id.");
+        }
+    }
     if (kitCommand !== undefined && !KIT_COMMAND_PLUGIN_IDS.includes(experimentId)) {
         throw new Error(`--kit-command is only supported for --experiment ${KIT_COMMAND_PLUGIN_IDS.join(" or ")}.`);
     }
@@ -257,7 +281,8 @@ export function parseRunExperimentArgs(argv) {
             includeRealAgents,
             commandTemplates: Object.keys(commandTemplates).length > 0 ? commandTemplates : undefined,
             kitCommand,
-            campaignPreset
+            campaignPreset,
+            contextBudgets
         })
     };
 }
@@ -301,8 +326,39 @@ async function loadPluginInputs(args, toolRoot, context) {
         }
         return loadCasesAndProjectProfiles(args, toolRoot, context);
     }
+    if (args.experimentId === contextWindowScalingPlugin.metadata.id) {
+        return loadContextWindowScalingInputs(args, toolRoot, context);
+    }
     return undefined;
 }
+// --case is a selection over the frozen bundled catalog (catalog order, not argument order);
+// the rest of the CLI config is the plugin's own ContextWindowScalingConfig.
+function pluginConfigFor(args) {
+    if (args.experimentId !== contextWindowScalingPlugin.metadata.id)
+        return args.config;
+    const { caseIds: _caseIds, ...config } = args.config;
+    return config;
+}
+async function loadContextWindowScalingInputs(args, toolRoot, context) {
+    const validation = contextWindowScalingPlugin.validateConfig(pluginConfigFor(args));
+    if (!validation.valid || !validation.config) {
+        throw new Error(`Invalid context window scaling config: ${validation.errors.join("; ")}`);
+    }
+    const catalog = await readEvaluationCases(resolvePackageResource(context, CONTEXT_WINDOW_SCALING_CASES_RESOURCE), toolRoot);
+    const requested = args.config.caseIds;
+    if (requested === undefined)
+        return { cases: catalog, env: process.env };
+    const duplicates = [...new Set(requested.filter((id, position) => requested.indexOf(id) !== position))];
+    if (duplicates.length > 0) {
+        throw new Error(`--case contains duplicate case id(s): ${duplicates.join(", ")}.`);
+    }
+    const known = new Set(catalog.map((evaluationCase) => evaluationCase.id));
+    const unknown = requested.filter((id) => !known.has(id));
+    if (unknown.length > 0) {
+        throw new Error(`--case contains unknown case id(s): ${unknown.join(", ")}. Expected one of ${catalog.map((evaluationCase) => evaluationCase.id).join(", ")}.`);
+    }
+    return { cases: catalog.filter((evaluationCase) => requested.includes(evaluationCase.id)), env: process.env };
+}
 // 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) {

package/dist/src/evaluation/benchmarkMetadata.js

@@ -280,7 +280,11 @@ function validateWarmIndexSourceRoots(sourceRoots, profile, label) {
     return errors;
 }
 function normalizeRelativeRoot(value) {
-    return path.posix.normalize(value.replace(/\\/g, "/")).replace(/\/+$/, "");
+    const normalized = path.posix.normalize(value.replaceAll("\\", "/"));
+    let end = normalized.length;
+    while (end > 0 && normalized[end - 1] === "/")
+        end -= 1;
+    return normalized.slice(0, end);
 }
 function sameOrderedValues(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);

package/dist/src/evaluation/parseAgentAnswer.js

@@ -77,11 +77,24 @@ function collectJsonCandidates(text) {
     if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
         candidates.push(trimmed);
     }
-    for (const match of text.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi)) {
-        const body = match[1]?.trim();
+    let cursor = 0;
+    while (cursor < text.length) {
+        const opening = text.indexOf("```", cursor);
+        if (opening < 0)
+            break;
+        let bodyStart = opening + 3;
+        if (text.slice(bodyStart, bodyStart + 4).toLowerCase() === "json")
+            bodyStart += 4;
+        while (bodyStart < text.length && isWhitespace(text[bodyStart]))
+            bodyStart += 1;
+        const closing = text.indexOf("```", bodyStart);
+        if (closing < 0)
+            break;
+        const body = text.slice(bodyStart, closing).trim();
         if (body?.startsWith("{")) {
             candidates.push(body);
         }
+        cursor = closing + 3;
     }
     return candidates;
 }
@@ -89,39 +102,103 @@ function collectFieldValues(text) {
     const fields = new Map();
     let currentKey;
     for (const line of text.split(/\r?\n/)) {
-        const fieldMatch = line.match(/^\s*(?:[-*]\s*)?(?:[*_`]{0,2})([A-Za-z][A-Za-z0-9 _-]{1,40})(?:[*_`]{0,2})\s*:\s*(.*)$/);
-        if (fieldMatch) {
-            currentKey = normalizeKey(fieldMatch[1]);
+        const field = parseStructuredFieldLine(line);
+        if (field) {
+            currentKey = normalizeKey(field.label);
             const current = fields.get(currentKey) ?? [];
-            current.push(stripMarkupOnlyValue(fieldMatch[2] ?? ""));
+            current.push(stripMarkupOnlyValue(field.value));
             fields.set(currentKey, current);
             continue;
         }
-        if (currentKey && (/^\s+[-*]?\s*\S/.test(line) || /^\s*[-*]\s+\S/.test(line))) {
-            fields.get(currentKey)?.push(line.trim().replace(/^[-*]\s*/, ""));
+        if (currentKey) {
+            const continuation = parseFieldContinuation(line);
+            if (continuation !== undefined)
+                fields.get(currentKey)?.push(continuation);
         }
     }
     return fields;
 }
+function isWhitespace(character) {
+    return character.trim().length === 0;
+}
+function parseStructuredFieldLine(line) {
+    let start = 0;
+    while (start < line.length && isWhitespace(line[start]))
+        start += 1;
+    if (line[start] === "-" || line[start] === "*") {
+        start += 1;
+        while (start < line.length && isWhitespace(line[start]))
+            start += 1;
+    }
+    let leadingMarkup = 0;
+    while (start < line.length && leadingMarkup < 2 && "*_`".includes(line[start])) {
+        start += 1;
+        leadingMarkup += 1;
+    }
+    const colon = line.indexOf(":", start);
+    if (colon < 0)
+        return undefined;
+    let labelEnd = colon;
+    let trailingMarkup = 0;
+    while (labelEnd > start && trailingMarkup < 2 && "*_`".includes(line[labelEnd - 1])) {
+        labelEnd -= 1;
+        trailingMarkup += 1;
+    }
+    const label = line.slice(start, labelEnd);
+    if (label.length < 2 || label.length > 41 || !isAsciiLetter(label[0]))
+        return undefined;
+    for (let index = 1; index < label.length; index += 1) {
+        const character = label[index];
+        if (!isAsciiLetter(character) && !(character >= "0" && character <= "9") && character !== " " && character !== "_" && character !== "-")
+            return undefined;
+    }
+    let valueStart = colon + 1;
+    while (valueStart < line.length && isWhitespace(line[valueStart]))
+        valueStart += 1;
+    return { label, value: line.slice(valueStart) };
+}
+function isAsciiLetter(character) {
+    return (character >= "a" && character <= "z") || (character >= "A" && character <= "Z");
+}
+function parseFieldContinuation(line) {
+    let index = 0;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    const indented = index > 0;
+    if (index === line.length)
+        return undefined;
+    if (line[index] === "-" || line[index] === "*") {
+        index += 1;
+        const whitespaceStart = index;
+        while (index < line.length && isWhitespace(line[index]))
+            index += 1;
+        if ((!indented && index === whitespaceStart) || index === line.length)
+            return undefined;
+        return line.slice(index).trim();
+    }
+    if (!indented)
+        return undefined;
+    return line.slice(index).trim();
+}
 function parseMarkdownSection(text, headings) {
     const lines = text.split(/\r?\n/);
     const values = [];
     let inSection = false;
     for (const line of lines) {
-        const heading = line.match(/^\s*#{1,6}\s*(.+?)\s*$/);
-        if (heading) {
-            inSection = headings.some((candidate) => normalizeKey(candidate) === normalizeKey(heading[1]));
+        const heading = parseMarkdownHeading(line);
+        if (heading !== undefined) {
+            inSection = headings.some((candidate) => normalizeKey(candidate) === normalizeKey(heading));
             continue;
         }
         if (!inSection) {
             continue;
         }
-        if (/^\s*#{1,6}\s+/.test(line)) {
+        if (isMarkdownHeading(line)) {
             break;
         }
-        const bullet = line.match(/^\s*[-*]\s+(.+)$/);
-        if (bullet) {
-            values.push(bullet[1].trim());
+        const bullet = parseMarkdownBullet(line);
+        if (bullet !== undefined) {
+            values.push(bullet);
         }
         else if (line.includes(",")) {
             values.push(...splitListValues([line]));
@@ -129,6 +206,41 @@ function parseMarkdownSection(text, headings) {
     }
     return unique(values);
 }
+function parseMarkdownHeading(line) {
+    let index = 0;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    const hashStart = index;
+    while (index < line.length && line[index] === "#" && index - hashStart < 6)
+        index += 1;
+    if (index === hashStart || (index < line.length && line[index] === "#"))
+        return undefined;
+    const heading = line.slice(index).trim();
+    return heading.length > 0 ? heading : undefined;
+}
+function isMarkdownHeading(line) {
+    let index = 0;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    const start = index;
+    while (index < line.length && line[index] === "#" && index - start < 6)
+        index += 1;
+    return index > start && index < line.length && isWhitespace(line[index]);
+}
+function parseMarkdownBullet(line) {
+    let index = 0;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    if (line[index] !== "-" && line[index] !== "*")
+        return undefined;
+    index += 1;
+    if (index >= line.length || !isWhitespace(line[index]))
+        return undefined;
+    while (index < line.length && isWhitespace(line[index]))
+        index += 1;
+    const content = line.slice(index).trim();
+    return content.length > 0 ? content : undefined;
+}
 function enrichFacts(parsed, text, answerKey) {
     parsed.expectedFactsFound = normalizeFactMatches(parsed.expectedFactsFound, text, answerKey);
     if (parsed.answerText.length === 0) {
@@ -168,15 +280,51 @@ function splitListValues(values) {
         .filter(Boolean));
 }
 function cleanListItem(value) {
-    const codeSpan = value.match(/`([^`]+)`/);
-    const cleaned = (codeSpan?.[1] ?? value)
-        .trim()
-        .replace(/^[-*]\s*/, "")
-        .replace(/^["'`]+|["'`.]+$/g, "")
-        .replace(/\s+[--]\s+.*$/g, "")
-        .replace(/\s+[-–—]\s+.*$/g, "")
-        .trim();
-    return cleaned;
+    let source = value;
+    let searchFrom = 0;
+    while (searchFrom < value.length) {
+        const open = value.indexOf("`", searchFrom);
+        if (open < 0)
+            break;
+        const close = value.indexOf("`", open + 1);
+        if (close < 0)
+            break;
+        if (close > open + 1) {
+            source = value.slice(open + 1, close);
+            break;
+        }
+        searchFrom = close + 1;
+    }
+    let start = 0;
+    let end = source.length;
+    while (start < end && isWhitespace(source[start]))
+        start += 1;
+    while (end > start && isWhitespace(source[end - 1]))
+        end -= 1;
+    if (source[start] === "-" || source[start] === "*") {
+        start += 1;
+        while (start < end && isWhitespace(source[start]))
+            start += 1;
+    }
+    while (start < end && (source[start] === '"' || source[start] === "'" || source[start] === "`"))
+        start += 1;
+    while (end > start && (source[end - 1] === '"' || source[end - 1] === "'" || source[end - 1] === "`" || source[end - 1] === "."))
+        end -= 1;
+    let whitespaceStart = -1;
+    for (let index = start; index < end; index += 1) {
+        const character = source[index];
+        if (isWhitespace(character)) {
+            if (whitespaceStart < 0)
+                whitespaceStart = index;
+            continue;
+        }
+        if ((character === "-" || character === "–" || character === "—") && whitespaceStart >= start && index + 1 < end && isWhitespace(source[index + 1])) {
+            end = whitespaceStart;
+            break;
+        }
+        whitespaceStart = -1;
+    }
+    return source.slice(start, end).trim();
 }
 function stripMarkupOnlyValue(value) {
     return /^[*_`\s]+$/.test(value) ? "" : value;

package/dist/src/evaluation/runMyDevKitRetrieval.js

@@ -55,13 +55,118 @@ function skippedRetrieval(caseId, warnings, commands, durationMs) {
         durationMs
     };
 }
+const APPLIED_SCOPES = ["none", "changed-files", "affected-neighborhood", "full"];
+const SELECTION_STATUSES = ["not-needed", "applied", "fallback-full"];
+const NEIGHBORHOOD_COUNT_KEYS = ["seedFileCount", "seedSymbolCount", "affectedNodeCount", "affectedEdgeCount"];
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+/**
+ * Validates the per-invocation `incrementalRefresh` object from `my-dev-kit index --incremental --json`
+ * stdout against the scope Lab requested. Returns validated evidence or an explicit error; never coerces.
+ * The fallback reason is intentionally an open string: upstream reason codes may evolve additively.
+ */
+export function parseIncrementalRefreshEvidence(stdout, requestedScope) {
+    const payload = parseJsonIfPossible(stdout);
+    if (payload === undefined)
+        return { ok: false, error: "index stdout is not valid JSON" };
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return { ok: false, error: "index JSON result is not an object" };
+    }
+    const raw = payload.incrementalRefresh;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, error: "index JSON result has no incrementalRefresh object" };
+    }
+    const r = raw;
+    if (r.requestedScope !== requestedScope) {
+        return {
+            ok: false,
+            error: `incrementalRefresh.requestedScope ${JSON.stringify(r.requestedScope)} does not match requested scope ${requestedScope}`
+        };
+    }
+    if (!APPLIED_SCOPES.includes(r.appliedScope)) {
+        return { ok: false, error: `incrementalRefresh.appliedScope ${JSON.stringify(r.appliedScope)} is not a known value` };
+    }
+    if (!SELECTION_STATUSES.includes(r.selectionStatus)) {
+        return { ok: false, error: `incrementalRefresh.selectionStatus ${JSON.stringify(r.selectionStatus)} is not a known value` };
+    }
+    if (r.fallbackReason !== null && typeof r.fallbackReason !== "string") {
+        return { ok: false, error: "incrementalRefresh.fallbackReason must be a string or null" };
+    }
+    for (const key of NEIGHBORHOOD_COUNT_KEYS) {
+        if (r[key] !== null && !isNonNegativeInteger(r[key])) {
+            return { ok: false, error: `incrementalRefresh.${key} must be a non-negative integer or null` };
+        }
+    }
+    for (const key of ["forcedNeighborReanalysisFileCount", "freshExtractionFileCount", "reusedFileCount"]) {
+        if (!isNonNegativeInteger(r[key])) {
+            return { ok: false, error: `incrementalRefresh.${key} must be a non-negative integer` };
+        }
+    }
+    if (!Array.isArray(r.forcedNeighborSample) || r.forcedNeighborSample.some((item) => typeof item !== "string")) {
+        return { ok: false, error: "incrementalRefresh.forcedNeighborSample must be an array of strings" };
+    }
+    const appliedScope = r.appliedScope;
+    const selectionStatus = r.selectionStatus;
+    const fallbackReason = r.fallbackReason;
+    if (selectionStatus === "applied") {
+        if (appliedScope !== requestedScope) {
+            return { ok: false, error: "incrementalRefresh applied status requires appliedScope equal to requestedScope" };
+        }
+        if (fallbackReason !== null)
+            return { ok: false, error: "incrementalRefresh applied status requires a null fallbackReason" };
+    }
+    else if (selectionStatus === "fallback-full") {
+        if (appliedScope !== "full")
+            return { ok: false, error: "incrementalRefresh fallback-full status requires appliedScope full" };
+        if (fallbackReason === null || fallbackReason.length === 0) {
+            return { ok: false, error: "incrementalRefresh fallback-full status requires a nonempty fallbackReason" };
+        }
+    }
+    else {
+        if (appliedScope !== "none")
+            return { ok: false, error: "incrementalRefresh not-needed status requires appliedScope none" };
+        if (fallbackReason !== null)
+            return { ok: false, error: "incrementalRefresh not-needed status requires a null fallbackReason" };
+    }
+    if (requestedScope === "affected-neighborhood" && selectionStatus === "applied") {
+        for (const key of NEIGHBORHOOD_COUNT_KEYS) {
+            if (r[key] === null) {
+                return { ok: false, error: `incrementalRefresh.${key} must be numeric for an applied affected-neighborhood refresh` };
+            }
+        }
+    }
+    return {
+        ok: true,
+        evidence: {
+            requestedScope,
+            appliedScope,
+            selectionStatus,
+            fallbackReason,
+            seedFileCount: r.seedFileCount,
+            seedSymbolCount: r.seedSymbolCount,
+            affectedNodeCount: r.affectedNodeCount,
+            affectedEdgeCount: r.affectedEdgeCount,
+            forcedNeighborReanalysisFileCount: r.forcedNeighborReanalysisFileCount,
+            forcedNeighborSample: [...r.forcedNeighborSample],
+            freshExtractionFileCount: r.freshExtractionFileCount,
+            reusedFileCount: r.reusedFileCount
+        }
+    };
+}
 /**
  * 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.
+ *
+ * `mode` defaults to a full index. An incremental mode adds `--incremental --refresh-scope <scope>`
+ * and requires valid per-invocation `incrementalRefresh` JSON evidence on stdout; a successful
+ * process without that evidence is not a usable incremental build. Upstream full-fallback and
+ * no-change outcomes are valid evidence and are returned as-is.
  */
 export async function buildMyDevKitIndex(options) {
     const warnings = [];
+    const mode = options.mode ?? { kind: "full" };
     const command = await runMeasuredCommand({
         commandId: "index",
         commandString: options.kitCommand,
@@ -74,22 +179,30 @@ export async function buildMyDevKitIndex(options) {
             ...options.target.sourceRoots.flatMap((sourceRoot) => ["--src", sourceRoot]),
             "--out",
             options.indexDir,
+            ...(mode.kind === "incremental" ? ["--incremental", "--refresh-scope", mode.refreshScope] : []),
             "--json"
         ]
     });
+    const result = { indexDir: options.indexDir, durationMs: command.durationMs, command, mode };
     if (!command.ok) {
         if (options.requireKit) {
             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 { ...result, ok: false, warnings, incrementalRefresh: null };
     }
-    return {
-        ok: command.ok,
-        indexDir: options.indexDir,
-        durationMs: command.durationMs,
-        warnings,
-        command
-    };
+    if (mode.kind === "full") {
+        return { ...result, ok: true, warnings, incrementalRefresh: null };
+    }
+    const parsed = parseIncrementalRefreshEvidence(command.stdout, mode.refreshScope);
+    if (!parsed.ok) {
+        const message = `my-dev-kit incremental index (${mode.refreshScope}) returned no valid incrementalRefresh evidence: ${parsed.error}`;
+        if (options.requireKit)
+            throw new Error(message);
+        warnings.push(message);
+        return { ...result, ok: false, warnings, incrementalRefresh: null };
+    }
+    return { ...result, ok: true, warnings, incrementalRefresh: parsed.evidence };
 }
 /**
  * Runs `<kit-command> --version` once through the shared measured-command runner and returns

package/dist/src/experiments/defaultRegistry.js

@@ -1,5 +1,6 @@
 import { ExperimentPluginRegistry } from "./registry.js";
 import { contextStrategyComparisonPlugin } from "./plugins/contextStrategyComparison/index.js";
+import { contextWindowScalingPlugin } from "./plugins/contextWindowScaling/index.js";
 import { incrementalChangeStalenessPlugin } from "./plugins/incrementalChangeStaleness/index.js";
 import { warmIndexReusePlugin } from "./plugins/warmIndexReuse/index.js";
 export function createDefaultExperimentPluginRegistry() {
@@ -7,5 +8,6 @@ export function createDefaultExperimentPluginRegistry() {
     registry.register(contextStrategyComparisonPlugin);
     registry.register(warmIndexReusePlugin);
     registry.register(incrementalChangeStalenessPlugin);
+    registry.register(contextWindowScalingPlugin);
     return registry;
 }

package/dist/src/experiments/plugins/contextWindowScaling/cliBudgets.js

@@ -0,0 +1,31 @@
+import { validateContextBudgets } from "./config.js";
+import { CONTEXT_BUDGET_16K, CONTEXT_BUDGET_32K, CONTEXT_BUDGET_64K, CONTEXT_BUDGET_8K } from "./contextBudget.js";
+/** Closed, lowercase CLI vocabulary. "8k" is 8192 (binary), never 8000. */
+const SYMBOLIC_CONTEXT_BUDGETS = Object.freeze({
+    "8k": CONTEXT_BUDGET_8K,
+    "16k": CONTEXT_BUDGET_16K,
+    "32k": CONTEXT_BUDGET_32K,
+    "64k": CONTEXT_BUDGET_64K,
+});
+const CANONICAL_POSITIVE_INTEGER = /^[1-9][0-9]*$/;
+/**
+ * Converts the comma-separated --context-budgets value to numbers (symbolic or canonical base-10
+ * integers only), then delegates all domain rules (positive safe integer, no duplicates, ascending
+ * order) to validateContextBudgets. Throws with the CLI flag name on any invalid input.
+ */
+export function parseContextBudgetsCliValue(value) {
+    const tokens = value.split(",").map((token) => token.trim());
+    const numbers = tokens.map((token) => {
+        const symbolic = Object.hasOwn(SYMBOLIC_CONTEXT_BUDGETS, token) ? SYMBOLIC_CONTEXT_BUDGETS[token] : undefined;
+        if (symbolic !== undefined)
+            return symbolic;
+        if (CANONICAL_POSITIVE_INTEGER.test(token))
+            return Number(token);
+        throw new Error(`--context-budgets value ${JSON.stringify(token.length > 20 ? `${token.slice(0, 20)}...` : token)} is invalid; use 8k, 16k, 32k, 64k, or a positive base-10 integer.`);
+    });
+    const validated = validateContextBudgets(numbers);
+    if (validated.errors.length > 0) {
+        throw new Error(`--context-budgets is invalid: ${validated.errors.join(" ")}`);
+    }
+    return validated.budgets;
+}