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

package/dist/src/experiments/plugins/incrementalChangeStaleness/scenarioValidation.js

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { validateAnswerKey } from "../../../evaluation/benchmarkMetadata.js";
+import { validateMutationFile } from "./scenarioMutation.js";
+import { FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS, INCREMENTAL_CHANGE_STALENESS_ANSWER_POLICIES, INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATEGORIES, INCREMENTAL_CHANGE_STALENESS_SCENARIO_SCHEMA_VERSION } from "./scenarioTypes.js";
+/** Category each frozen production scenario id is required to declare. */
+export const FROZEN_SCENARIO_CATEGORY_BY_ID = {
+    U1: "unrelated-file-change",
+    L2: "local-implementation-change",
+    E1: "exported-symbol-change",
+    P1: "public-api-change",
+    I1: "import-graph-change",
+    T1: "test-only-change"
+};
+/** Substrings that must never appear in scenario notes/query text (Section 7/9/22.I). */
+const FORBIDDEN_TEXT_PATTERNS = [/partial-refresh/i, /changed-files-refresh/i, /affected-neighborhood-refresh/i, /graph-diff/i];
+/**
+ * Strictly validates a parsed incremental-change-staleness scenario catalog.
+ * Performs schema/vocabulary checks, benchmark project/case reference checks,
+ * answer-policy completeness checks, forbidden-content checks, and full
+ * in-memory mutation validation (pre-hash, ordered exact-preimage
+ * replacement, post-hash) against the real canonical benchmark files. Never
+ * writes to disk.
+ */
+export async function validateIncrementalChangeStalenessCatalog(catalog, profiles, cases, repoRoot, options = {}) {
+    const errors = [];
+    if (!catalog || typeof catalog !== "object") {
+        return ["Scenario catalog must be an object."];
+    }
+    const candidate = catalog;
+    if (candidate.schemaVersion !== INCREMENTAL_CHANGE_STALENESS_SCENARIO_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be ${INCREMENTAL_CHANGE_STALENESS_SCENARIO_SCHEMA_VERSION}; received ${JSON.stringify(candidate.schemaVersion)}.`);
+    }
+    if (!Array.isArray(candidate.scenarios)) {
+        errors.push("scenarios must be an array.");
+        return errors;
+    }
+    const profilesById = new Map(profiles.map((profile) => [profile.projectId, profile]));
+    const casesById = new Map(cases.map((benchmarkCase) => [benchmarkCase.id, benchmarkCase]));
+    const seenIds = new Set();
+    for (const [index, scenario] of candidate.scenarios.entries()) {
+        errors.push(...(await validateOneScenario(scenario, index, profilesById, casesById, repoRoot, seenIds)));
+    }
+    if (options.requireFrozenProductionScenarios === true) {
+        const actualIds = candidate.scenarios
+            .map((scenario) => (scenario && typeof scenario === "object" ? scenario.id : undefined))
+            .filter((id) => typeof id === "string");
+        const expected = FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS;
+        const actualSet = new Set(actualIds);
+        const missing = expected.filter((id) => !actualSet.has(id));
+        const extra = actualIds.filter((id) => !expected.includes(id));
+        if (missing.length > 0) {
+            errors.push(`Production catalog is missing required frozen scenario(s): ${missing.join(", ")}.`);
+        }
+        if (extra.length > 0) {
+            errors.push(`Production catalog contains unexpected scenario id(s) beyond the six frozen scenarios: ${extra.join(", ")}.`);
+        }
+        if (actualIds.length !== expected.length || missing.length > 0 || extra.length > 0) {
+            errors.push(`Production catalog must contain exactly the six frozen scenarios ${expected.join(", ")}; received ${actualIds.join(", ") || "<none>"}.`);
+        }
+    }
+    return errors;
+}
+async function validateOneScenario(scenario, index, profilesById, casesById, repoRoot, seenIds) {
+    const errors = [];
+    if (!scenario || typeof scenario !== "object") {
+        return [`scenario at index ${index}: must be an object.`];
+    }
+    const candidate = scenario;
+    const id = typeof candidate.id === "string" && candidate.id.length > 0 ? candidate.id : undefined;
+    const label = id === undefined ? `scenario at index ${index}` : `scenario ${id}`;
+    if (id === undefined) {
+        errors.push(`${label}: id must be a nonempty string.`);
+    }
+    else if (seenIds.has(id)) {
+        errors.push(`${label}: duplicate scenario id.`);
+    }
+    else {
+        seenIds.add(id);
+    }
+    if (typeof candidate.category !== "string" || !INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATEGORIES.includes(candidate.category)) {
+        errors.push(`${label}: category must be one of ${INCREMENTAL_CHANGE_STALENESS_SCENARIO_CATEGORIES.join(", ")}; received ${JSON.stringify(candidate.category)}.`);
+    }
+    else if (id !== undefined && id in FROZEN_SCENARIO_CATEGORY_BY_ID) {
+        const expectedCategory = FROZEN_SCENARIO_CATEGORY_BY_ID[id];
+        if (candidate.category !== expectedCategory) {
+            errors.push(`${label}: category must be ${expectedCategory} for frozen scenario ${id}; received ${candidate.category}.`);
+        }
+    }
+    if (typeof candidate.answerPolicy !== "string" || !INCREMENTAL_CHANGE_STALENESS_ANSWER_POLICIES.includes(candidate.answerPolicy)) {
+        errors.push(`${label}: answerPolicy must be one of ${INCREMENTAL_CHANGE_STALENESS_ANSWER_POLICIES.join(", ")}; received ${JSON.stringify(candidate.answerPolicy)}.`);
+    }
+    const projectId = typeof candidate.benchmarkProjectId === "string" && candidate.benchmarkProjectId.length > 0 ? candidate.benchmarkProjectId : undefined;
+    if (projectId === undefined) {
+        errors.push(`${label}: benchmarkProjectId must be a nonempty string.`);
+    }
+    const profile = projectId === undefined ? undefined : profilesById.get(projectId);
+    if (projectId !== undefined && profile === undefined) {
+        errors.push(`${label}: unknown benchmarkProjectId ${projectId}.`);
+    }
+    const caseId = typeof candidate.baseCaseId === "string" && candidate.baseCaseId.length > 0 ? candidate.baseCaseId : undefined;
+    if (caseId === undefined) {
+        errors.push(`${label}: baseCaseId must be a nonempty string.`);
+    }
+    const baseCase = caseId === undefined ? undefined : casesById.get(caseId);
+    if (caseId !== undefined && baseCase === undefined) {
+        errors.push(`${label}: unknown baseCaseId ${caseId}.`);
+    }
+    if (baseCase !== undefined && projectId !== undefined && baseCase.benchmarkProject !== projectId) {
+        errors.push(`${label}: baseCaseId ${caseId} belongs to benchmark project ${baseCase.benchmarkProject}, not the referenced benchmarkProjectId ${projectId}.`);
+    }
+    // Answer-policy completeness (Section 22.H). Reuses the existing answer-key structure/validator.
+    if (candidate.answerPolicy === "inherit") {
+        if (baseCase !== undefined) {
+            if (typeof baseCase.query !== "string" || baseCase.query.length === 0) {
+                errors.push(`${label}: inherit policy requires the base case to have a nonempty query.`);
+            }
+            if (baseCase.answerKey === undefined) {
+                errors.push(`${label}: inherit policy requires the base case to have an answerKey.`);
+            }
+            else {
+                errors.push(...validateAnswerKey(baseCase.answerKey, `${label} (inherited answerKey)`).map((message) => message));
+            }
+        }
+        if (candidate.scenarioQuery !== undefined || candidate.scenarioAnswerKey !== undefined) {
+            errors.push(`${label}: inherit policy must not declare scenarioQuery or scenarioAnswerKey.`);
+        }
+    }
+    else if (candidate.answerPolicy === "scenario") {
+        if (typeof candidate.scenarioQuery !== "string" || candidate.scenarioQuery.trim().length === 0) {
+            errors.push(`${label}: scenario policy requires a nonempty scenarioQuery.`);
+        }
+        if (candidate.scenarioAnswerKey === undefined) {
+            errors.push(`${label}: scenario policy requires a scenarioAnswerKey.`);
+        }
+        else {
+            errors.push(...validateAnswerKey(candidate.scenarioAnswerKey, `${label}.scenarioAnswerKey`));
+        }
+    }
+    if (candidate.expectedRelationship !== undefined && !["related", "unrelated", "unknown"].includes(candidate.expectedRelationship)) {
+        errors.push(`${label}: expectedRelationship must be one of related, unrelated, unknown; received ${JSON.stringify(candidate.expectedRelationship)}.`);
+    }
+    for (const text of [candidate.notes, candidate.scenarioQuery, candidate.id, candidate.category]) {
+        if (typeof text === "string") {
+            for (const pattern of FORBIDDEN_TEXT_PATTERNS) {
+                if (pattern.test(text)) {
+                    errors.push(`${label}: forbidden v0.6.3+/graph-diff reference found in scenario text: matched ${pattern}.`);
+                }
+            }
+        }
+    }
+    if (!candidate.mutation || typeof candidate.mutation !== "object" || !Array.isArray(candidate.mutation.files) || candidate.mutation.files.length === 0) {
+        errors.push(`${label}: mutation.files must be a nonempty array.`);
+        return errors;
+    }
+    if (profile !== undefined && baseCase !== undefined) {
+        const projectAbsoluteRoot = path.resolve(repoRoot, profile.rootPath);
+        const caseSourceRoots = Array.isArray(baseCase.sourceRoots) ? baseCase.sourceRoots : [];
+        for (const [fileIndex, file] of candidate.mutation.files.entries()) {
+            const fileLabel = `${label}.mutation.files[${fileIndex}]`;
+            const result = await validateMutationFile(fileLabel, file, projectAbsoluteRoot, caseSourceRoots);
+            errors.push(...result.errors);
+        }
+    }
+    else {
+        errors.push(`${label}: mutation files cannot be validated because the benchmark project/case reference is invalid.`);
+    }
+    return errors;
+}

package/dist/src/experiments/plugins/incrementalChangeStaleness/sourceState.js

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { sha256Hex } from "./scenarioMutation.js";
+/**
+ * v0.6.2 Batch 2 controlled-source-state schema version. This is a
+ * copy-equivalence guard scoped to a benchmark case's configured indexed
+ * source roots; it is NOT the real `IndexSnapshotV1` captured from an actual
+ * my-dev-kit index build (that remains Batch 3's responsibility).
+ */
+export const INCREMENTAL_CHANGE_STALENESS_SOURCE_STATE_SCHEMA_VERSION = "1.0.0";
+function normalizeSourceRoot(root) {
+    return root.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+/**
+ * Recursively enumerates regular files (symbolic links are skipped, never
+ * followed) underneath one project-relative source root, hashing each with
+ * SHA-256. Deterministic: results are always returned to the caller sorted.
+ */
+async function collectSourceRootFiles(projectRoot, sourceRoot) {
+    const absoluteRoot = resolveWithinRoot(projectRoot, sourceRoot);
+    const results = [];
+    async function walk(currentAbsoluteDir) {
+        const entries = await readdir(currentAbsoluteDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isSymbolicLink()) {
+                // Never follow symlinks when building controlled source-state evidence.
+                continue;
+            }
+            const entryAbsolutePath = path.join(currentAbsoluteDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryAbsolutePath);
+            }
+            else if (entry.isFile()) {
+                const buffer = await readFile(entryAbsolutePath);
+                const relativePath = path.relative(projectRoot, entryAbsolutePath).split(path.sep).join("/");
+                results.push({ relativePath, sha256: sha256Hex(buffer) });
+            }
+        }
+    }
+    await walk(absoluteRoot);
+    return results;
+}
+function computeDigest(files) {
+    const serialized = files.map((file) => `${file.relativePath}\t${file.sha256}\n`).join("");
+    return createHash("sha256").update(Buffer.from(serialized, "utf8")).digest("hex");
+}
+/**
+ * Captures bounded, deterministic controlled source-state evidence for one
+ * disposable treatment copy, scoped to the base case's own configured
+ * `sourceRoots` (never invented separately). Never converts an unreadable or
+ * missing source root into an empty/zero-file "complete" result: any
+ * enumeration failure makes the whole capture "unavailable" with a reason.
+ */
+export async function captureIncrementalChangeStalenessSourceState(projectRoot, sourceRoots, treatmentId, benchmarkProjectId) {
+    const normalizedSourceRoots = sourceRoots.map(normalizeSourceRoot);
+    if (normalizedSourceRoots.length === 0) {
+        return {
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_SOURCE_STATE_SCHEMA_VERSION,
+            treatmentId,
+            benchmarkProjectId,
+            sourceRoots: normalizedSourceRoots,
+            status: "unavailable",
+            files: [],
+            fileCount: 0,
+            digest: null,
+            reason: "No source roots were configured for this benchmark case."
+        };
+    }
+    try {
+        const perRoot = await Promise.all(normalizedSourceRoots.map((root) => collectSourceRootFiles(projectRoot, root)));
+        const files = perRoot.flat().sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+        return {
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_SOURCE_STATE_SCHEMA_VERSION,
+            treatmentId,
+            benchmarkProjectId,
+            sourceRoots: normalizedSourceRoots,
+            status: "complete",
+            files,
+            fileCount: files.length,
+            digest: computeDigest(files)
+        };
+    }
+    catch (error) {
+        return {
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_SOURCE_STATE_SCHEMA_VERSION,
+            treatmentId,
+            benchmarkProjectId,
+            sourceRoots: normalizedSourceRoots,
+            status: "unavailable",
+            files: [],
+            fileCount: 0,
+            digest: null,
+            reason: `Unable to capture controlled source state: ${error.message}`
+        };
+    }
+}
+/**
+ * Deterministically compares two controlled source-state captures.
+ * `equivalent` requires both sides complete, matching normalized source-root
+ * sets, matching path sets, and matching per-file SHA-256 values.
+ * Incomplete/unavailable evidence on either side always yields `unknown`,
+ * never `equivalent` and never a false `different`.
+ */
+export function compareIncrementalChangeStalenessSourceStates(left, right) {
+    const reasons = [];
+    if (left.status !== "complete") {
+        reasons.push(`left source state is unavailable${left.reason ? `: ${left.reason}` : "."}`);
+    }
+    if (right.status !== "complete") {
+        reasons.push(`right source state is unavailable${right.reason ? `: ${right.reason}` : "."}`);
+    }
+    if (reasons.length > 0) {
+        return { result: "unknown", reasons };
+    }
+    const leftRoots = [...left.sourceRoots].sort();
+    const rightRoots = [...right.sourceRoots].sort();
+    if (leftRoots.length !== rightRoots.length || leftRoots.some((root, index) => root !== rightRoots[index])) {
+        return {
+            result: "different",
+            reasons: [`source-root contract differs: left=${JSON.stringify(leftRoots)} right=${JSON.stringify(rightRoots)}`]
+        };
+    }
+    const leftByPath = new Map(left.files.map((file) => [file.relativePath, file.sha256]));
+    const rightByPath = new Map(right.files.map((file) => [file.relativePath, file.sha256]));
+    const differences = [];
+    for (const [relativePath, sha256] of leftByPath) {
+        if (!rightByPath.has(relativePath)) {
+            differences.push(`only on left: ${relativePath}`);
+        }
+        else if (rightByPath.get(relativePath) !== sha256) {
+            differences.push(`content differs: ${relativePath}`);
+        }
+    }
+    for (const relativePath of rightByPath.keys()) {
+        if (!leftByPath.has(relativePath)) {
+            differences.push(`only on right: ${relativePath}`);
+        }
+    }
+    if (differences.length > 0) {
+        return { result: "different", reasons: differences };
+    }
+    return { result: "equivalent", reasons: [] };
+}

package/dist/src/experiments/plugins/incrementalChangeStaleness/treatmentSession.js

@@ -0,0 +1,6 @@
+/**
+ * v0.6.2 Batch 3 in-memory lifecycle session schema version. This is the
+ * runtime handoff contract Batch 4 consumes for treatment execution; it is
+ * NOT a persisted artifact and carries full graph evidence only in memory.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_SCHEMA_VERSION = "1.0.0";

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

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

package/dist/src/experiments/plugins/warmIndexReuse/execution.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { assessAffectedNeighborhood, mapAffectedNeighborhoodSeeds, } from "../../../evaluation/affectedNeighborhood.js";
 import { assessIndexFreshness } from "../../../evaluation/indexFreshness.js";
 import { runMyDevKitRetrievalFromIndex } from "../../../evaluation/runMyDevKitRetrieval.js";
 import { runRawFullFileBaseline } from "../../../evaluation/runRawFullFileBaseline.js";
@@ -92,6 +93,7 @@ async function executeTask(args) {
     let warmRetrieval;
     let warmStatus = "failed";
     let indexFreshness;
+    let affectedNeighborhood = null;
     if (!args.session) {
         errors.push(args.setupFailure ?? { side: "warm", code: "warm-index-setup-failed", message: "No warm index session." });
         // No snapshot exists, so freshness is conservatively unknown rather than assumed.
@@ -115,6 +117,24 @@ async function executeTask(args) {
                 targetRoot: args.session.targetRoot,
                 sourceRoots: args.session.sourceRoots,
             });
+            // Observational and in-memory: this task's freshness against the shared baseline graph. It
+            // reads no files, runs no my-dev-kit command, and cannot stop the retrieval below.
+            try {
+                const seedMapping = mapAffectedNeighborhoodSeeds({
+                    indexSnapshot: args.session.indexSnapshot,
+                    freshness: indexFreshness,
+                    graph: args.session.affectedNeighborhoodGraph,
+                });
+                affectedNeighborhood = assessAffectedNeighborhood({
+                    graph: args.session.affectedNeighborhoodGraph,
+                    seedMapping,
+                    task: evaluationCase,
+                });
+            }
+            catch (error) {
+                affectedNeighborhood = null;
+                warnings.push(`Affected-neighborhood assessment was not recorded: ${errorMessage(error)}`);
+            }
             try {
                 // requireKit: false retains subordinate command evidence; a skipped result caused by a
                 // failed command is classified as failed below rather than as an honest skip.
@@ -149,6 +169,7 @@ async function executeTask(args) {
         rawBaseline,
         warmRetrieval,
         indexFreshness,
+        affectedNeighborhood,
         warnings,
         errors,
     };

package/dist/src/experiments/plugins/warmIndexReuse/executionArtifact.js

@@ -47,6 +47,7 @@ function summarizeTask(task) {
             }
             : null,
         indexFreshness: task.indexFreshness ? structuredClone(task.indexFreshness) : null,
+        affectedNeighborhood: task.affectedNeighborhood ? structuredClone(task.affectedNeighborhood) : null,
         warnings: [...task.warnings],
         errors: task.errors.map((error) => ({ ...error })),
     };

package/dist/src/experiments/plugins/warmIndexReuse/metrics.js

@@ -1,3 +1,4 @@
+import { toAffectedNeighborhoodMetricValues } from "../../../evaluation/affectedNeighborhoodMetrics.js";
 // ---------------------------------------------------------------------------
 // Warm-index metric owner. Every warm-index formula (amortization, cumulative
 // prefix sums, availability) is calculated here exactly once, as a pure
@@ -147,6 +148,7 @@ export function calculateWarmIndexProjectMetrics(project, agentEvidence) {
                 cumulativeComponentDurationMs: warmDuration.add(warm.retrievalDurationMs, label("warm retrieval duration")),
                 cumulativeEstimatedContextTokens: warmTokens.add(warm.contextEstimatedTokens, label("warm estimated context tokens")),
                 ...warmAgent,
+                ...affectedNeighborhoodMetrics(task),
                 cumulativeAgentTotalTokens: warmAgentTokens.add(warmAgent.agentTotalTokens, label("warm agent total tokens")),
             },
         };
@@ -192,6 +194,31 @@ function warmDirect(task) {
         retrievalDurationMs: availableMetric(warm.durationMs, "ms", "measured"),
     };
 }
+const NO_AFFECTED_NEIGHBORHOOD_REASON = "No affected-neighborhood assessment was recorded for this task.";
+function wrapAffectedNeighborhoodMetricValue(value) {
+    return value.availability === "available"
+        ? availableMetric(value.value, value.unit, "derived")
+        : unavailableMetric(value.unit, "derived", value.reason);
+}
+/**
+ * Converts the persisted affected-neighborhood assessment into the six warm-side metrics, once.
+ * A finite value (including zero) is available; an absent assessment or a null field is
+ * unavailable with a reason, never zero. The formula itself is owned by the shared
+ * `toAffectedNeighborhoodMetricValues` (src/evaluation/affectedNeighborhoodMetrics.ts, extracted in
+ * v0.6.2 Batch 4 for reuse by incremental-change-staleness); this function only wraps its bounded
+ * values into the warm-index `WarmIndexNumberMetricV1` envelope.
+ */
+function affectedNeighborhoodMetrics(task) {
+    const values = toAffectedNeighborhoodMetricValues(task.affectedNeighborhood, NO_AFFECTED_NEIGHBORHOOD_REASON);
+    return {
+        changedFileCount: wrapAffectedNeighborhoodMetricValue(values.changedFileCount),
+        changedSymbolCount: wrapAffectedNeighborhoodMetricValue(values.changedSymbolCount),
+        affectedNodeCount: wrapAffectedNeighborhoodMetricValue(values.affectedNodeCount),
+        affectedEdgeCount: wrapAffectedNeighborhoodMetricValue(values.affectedEdgeCount),
+        taskOverlapCount: wrapAffectedNeighborhoodMetricValue(values.taskOverlapCount),
+        taskOverlapPercent: wrapAffectedNeighborhoodMetricValue(values.taskOverlapPercent)
+    };
+}
 /** Pure, order-preserving calculation; ordinals and cumulative state restart for every project. */
 export function calculateWarmIndexMetrics(projects, agentEvidence) {
     if (agentEvidence && agentEvidence.length !== projects.length) {
@@ -222,8 +249,49 @@ export function toWarmOutcomeMetrics(task, variantId) {
         { id: "cumulative-context-estimated-token-count", name: "Cumulative estimated context tokens", description: "Sum of retrieved estimated context tokens for tasks 1..N in this project; not provider token usage.", metric: task.warm.cumulativeEstimatedContextTokens },
         { id: "amortized-index-build-duration-ms", name: "Amortized index build duration", description: "Index build duration divided by this task's ordinal within its project.", metric: task.warm.amortizedIndexBuildDurationMs },
         ...agentSpecs(task.warm),
+        ...affectedNeighborhoodSpecs(task.warm),
     ]);
 }
+function affectedNeighborhoodSpecs(warm) {
+    return [
+        {
+            id: "affected-neighborhood-changed-file-count",
+            name: "Changed indexed files",
+            description: "Unique confirmed modified or missing files that the baseline index snapshot represents; new or non-indexed files are not counted.",
+            metric: warm.changedFileCount,
+        },
+        {
+            id: "affected-neighborhood-changed-symbol-count",
+            name: "Changed baseline symbols",
+            description: "Baseline indexed symbol identities (file path + name) belonging to confirmed changed indexed files; not proof that each symbol's own source text changed.",
+            metric: warm.changedSymbolCount,
+        },
+        {
+            id: "affected-neighborhood-node-count",
+            name: "Affected graph nodes",
+            description: "Unique resolved seed nodes plus their direct one-hop baseline graph neighbors, over edges of any kind and direction.",
+            metric: warm.affectedNodeCount,
+        },
+        {
+            id: "affected-neighborhood-edge-count",
+            name: "Affected graph edges",
+            description: "Unique baseline graph edges incident to at least one resolved seed node; not the induced subgraph of all affected nodes.",
+            metric: warm.affectedEdgeCount,
+        },
+        {
+            id: "affected-neighborhood-task-overlap-count",
+            name: "Task-overlap nodes",
+            description: "Unique baseline graph nodes that are both in the affected neighborhood and resolved from the task's expected files and symbols.",
+            metric: warm.taskOverlapCount,
+        },
+        {
+            id: "affected-neighborhood-task-overlap-percent",
+            name: "Task-overlap percent",
+            description: "Task-overlap nodes as a percentage of resolvable task graph nodes; unresolved or ambiguous expected metadata is not in the denominator.",
+            metric: warm.taskOverlapPercent,
+        },
+    ];
+}
 function agentSpecs(side) {
     return [
         {

package/dist/src/experiments/plugins/warmIndexReuse/warmIndexSession.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { buildMyDevKitIndex, probeMyDevKitVersion } from "../../../evaluation/runMyDevKitRetrieval.js";
+import { loadAffectedNeighborhoodGraphEvidence } from "../../../evaluation/affectedNeighborhood.js";
 import { captureIndexSnapshot } from "../../../evaluation/indexSnapshot.js";
 /**
  * Builds the index once through the shared `buildMyDevKitIndex` owner. A build that reports
@@ -31,13 +32,20 @@ export async function prepareWarmIndexSession(options) {
         command: build.command,
         tool
     });
+    // Loaded once per session from the manifest-referenced artifacts; never fails the session.
+    const affectedNeighborhoodGraph = await loadAffectedNeighborhoodGraphEvidence({
+        indexDir: build.indexDir,
+        sourceRoots,
+        indexSnapshot
+    });
     const session = Object.freeze({
         indexDir: build.indexDir,
         buildDurationMs: build.durationMs,
         targetRoot: options.target.absoluteTargetRoot,
         sourceRoots,
         buildCommand: build.command,
-        indexSnapshot
+        indexSnapshot,
+        affectedNeighborhoodGraph
     });
     return { ok: true, session, build };
 }

package/dist/src/report/experiments/buildIncrementalChangeStalenessReport.js

@@ -0,0 +1,112 @@
+// v0.6.2 Batch 5 -- projects the persisted Batch 4 incremental-change-staleness-execution.json
+// artifact into the plugin report model. This is a deterministic projection only: no retrieval,
+// no fake-agent evaluation, no correctness scoring, no affected-neighborhood assessment, no
+// freshness assessment, no stale-risk classification, and no source/index/benchmark reads happen
+// here. The persisted artifact is the only plugin-specific evidence source (frozen batch plan
+// Section 4); this file's only I/O is reading that one JSON file.
+import { readFileSync } from "node:fs";
+import { INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION } from "../../experiments/plugins/incrementalChangeStaleness/executionArtifact.js";
+import { INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID } from "../../experiments/plugins/incrementalChangeStaleness/plugin.js";
+import { INCREMENTAL_CHANGE_STALENESS_REPORT_SCHEMA_VERSION } from "./incrementalChangeStalenessReportModel.js";
+// Frozen wording (Section 25). Every point must appear in report.txt and report.html.
+const LIMITATIONS = [
+    "Results are scoped to the executed benchmark scenarios, deterministic controlled changes, configured my-dev-kit version, and observed retrieval/evaluation evidence.",
+    "\"no-observed-stale-regression\" means only that the frozen comparison did not observe a stale-specific regression in that matched run. It does not prove stale indexes are generally safe.",
+    "\"reindexRecommendation\" is separate affected-neighborhood observational evidence; it did not select or trigger either experiment treatment.",
+    "Required-file evidence is a bounded answer-key file-presence check, not retrieval precision/recall.",
+    "Correctness is deterministic fake-agent/harness evidence unless a future version explicitly adds real-agent evidence.",
+    "v0.6.2 compares stale full-index reuse with complete full refresh only.",
+    "Partial refresh is not evaluated in v0.6.2.",
+    "The experiment does not use graph-diff.",
+    "\"changedSymbolCount\" does not mean source-level symbol-diff proof; it retains the released v0.6.1 definition."
+];
+/** Fixed neutral wording per stale-risk classification category (Section 21). Presentation only. */
+export const STALE_RISK_CLASSIFICATION_EXPLANATIONS = {
+    "observed-stale-regression": "The persisted matched comparison observed at least one stale-specific regression under the frozen v0.6.2 evidence dimensions: correctness and/or required-file presence.",
+    "no-observed-stale-regression": "This matched scenario/run did not observe a stale-specific regression under the frozen correctness and required-file evidence dimensions. This does not establish general stale-index safety and does not imply that reindexing should be skipped.",
+    inconclusive: "Available persisted evidence was insufficient to determine whether a stale-specific regression occurred under the frozen comparison rules. Inconclusive is not the same as no regression."
+};
+/**
+ * Builds the plugin report section for an incremental-change-staleness run, or `null` for any
+ * other plugin. Every field is a deterministic projection of the persisted Batch 4 execution
+ * artifact; this function performs no scientific recomputation of its own.
+ */
+export function buildIncrementalChangeStalenessReport(run) {
+    if (run.pluginId !== INCREMENTAL_CHANGE_STALENESS_PLUGIN_ID)
+        return null;
+    const artifact = loadExecutionArtifact(run);
+    const scenarios = artifact.scenarios.map(toReportScenario);
+    return {
+        schemaVersion: INCREMENTAL_CHANGE_STALENESS_REPORT_SCHEMA_VERSION,
+        pluginId: artifact.pluginId,
+        scenarioCount: artifact.summary.scenarioCount,
+        readyScenarioCount: artifact.summary.readyScenarioCount,
+        failedScenarioCount: artifact.summary.failedScenarioCount,
+        observedStaleRegressionCount: artifact.summary.observedStaleRegressionCount,
+        noObservedStaleRegressionCount: artifact.summary.noObservedStaleRegressionCount,
+        inconclusiveCount: artifact.summary.inconclusiveCount,
+        scenarios,
+        limitations: [...LIMITATIONS]
+    };
+}
+function toReportScenario(record) {
+    return {
+        scenarioId: record.scenarioId,
+        category: record.category,
+        benchmarkProjectId: record.benchmarkProjectId,
+        baseCaseId: record.baseCaseId,
+        status: record.status,
+        failureReason: record.failureReason,
+        query: record.query,
+        answerPolicy: record.answerPolicy,
+        expectedFiles: [...record.expectedFiles],
+        expectedSymbols: [...record.expectedSymbols],
+        lifecycle: record.lifecycle
+            ? {
+                ...record.lifecycle,
+                controlledFilePaths: [...record.lifecycle.controlledFilePaths],
+                sourceRoots: [...record.lifecycle.sourceRoots]
+            }
+            : null,
+        // Section 12/34: always stale-index then full-refresh, never combined, never resorted.
+        staleTreatment: record.stale ? structuredClone(record.stale) : null,
+        fullRefreshTreatment: record.fullRefresh ? structuredClone(record.fullRefresh) : null,
+        comparison: { ...record.comparison, reasonCodes: [...record.comparison.reasonCodes] }
+    };
+}
+function readArtifactPath(run) {
+    const fromMetadata = run.metadata?.executionArtifactPath;
+    if (typeof fromMetadata === "string" && fromMetadata)
+        return fromMetadata;
+    return run.artifacts.find((artifact) => artifact.id === "incremental-change-staleness-execution")?.path ?? undefined;
+}
+/**
+ * The persisted execution artifact is the sole plugin-specific evidence source for this report
+ * (Section 4/46). A missing, unreadable, malformed, or schema-mismatched artifact is a report
+ * construction error, never silently reconstructed from source/index/retrieval state.
+ */
+function loadExecutionArtifact(run) {
+    const artifactPath = readArtifactPath(run);
+    if (!artifactPath) {
+        throw new Error("Invalid incremental-change-staleness report source: no execution artifact path was found on the run.");
+    }
+    let raw;
+    try {
+        raw = readFileSync(artifactPath, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Invalid incremental-change-staleness report source: execution artifact could not be read at ${artifactPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid incremental-change-staleness report source: execution artifact at ${artifactPath} is not valid JSON.`);
+    }
+    const candidate = parsed;
+    if (candidate.schemaVersion !== INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION) {
+        throw new Error(`Invalid incremental-change-staleness report source: unsupported execution artifact schema version ${String(candidate.schemaVersion)}.`);
+    }
+    return candidate;
+}