@dailephd/my-dev-kit-lab 0.5.2 → 0.6.1

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

@@ -1,5 +1,7 @@
 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";
 import { groupWarmIndexCases, taskOutputSegment } from "./selection.js";
@@ -90,8 +92,16 @@ 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.
+        indexFreshness = await assessIndexFreshness({
+            snapshot: null,
+            targetRoot: evaluationCase.absoluteTargetRoot,
+            sourceRoots: evaluationCase.sourceRoots,
+        });
     }
     else {
         try {
@@ -101,6 +111,30 @@ async function executeTask(args) {
             errors.push({ side: "warm", code: "warm-session-target-mismatch", message: errorMessage(error) });
         }
         if (!errors.some((error) => error.side === "warm")) {
+            // Observational only: measured immediately before reuse, and retrieval below runs regardless.
+            indexFreshness = await assessIndexFreshness({
+                snapshot: args.session.indexSnapshot,
+                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.
@@ -134,6 +168,8 @@ async function executeTask(args) {
         warmStatus,
         rawBaseline,
         warmRetrieval,
+        indexFreshness,
+        affectedNeighborhood,
         warnings,
         errors,
     };

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

@@ -46,6 +46,8 @@ function summarizeTask(task) {
                 commands: warm.commands.map(summarizeCommand),
             }
             : null,
+        indexFreshness: task.indexFreshness ? structuredClone(task.indexFreshness) : null,
+        affectedNeighborhood: task.affectedNeighborhood ? structuredClone(task.affectedNeighborhood) : null,
         warnings: [...task.warnings],
         errors: task.errors.map((error) => ({ ...error })),
     };
@@ -62,6 +64,7 @@ export function summarizeProjectExecution(project) {
         sessionPrepared: project.session !== undefined,
         buildDurationMs: project.build ? project.build.durationMs : null,
         indexCommand: project.build ? summarizeCommand(project.build.command) : null,
+        indexSnapshot: project.session ? structuredClone(project.session.indexSnapshot) : null,
         tasks: project.tasks.map(summarizeTask),
         warnings: [...project.warnings],
         errors: [...project.errors],

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

@@ -147,6 +147,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 +193,35 @@ function warmDirect(task) {
         retrievalDurationMs: availableMetric(warm.durationMs, "ms", "measured"),
     };
 }
+const NO_AFFECTED_NEIGHBORHOOD_REASON = "No affected-neighborhood assessment was recorded for this task.";
+/**
+ * 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 metric layer alone owns these value objects.
+ */
+function affectedNeighborhoodMetrics(task) {
+    const assessment = task.affectedNeighborhood;
+    const one = (field, label) => {
+        const unit = field === "taskOverlapPercent" ? "percent" : "count";
+        if (!assessment)
+            return unavailableMetric(unit, "derived", NO_AFFECTED_NEIGHBORHOOD_REASON);
+        const value = assessment[field];
+        if (typeof value === "number")
+            return availableMetric(value, unit, "derived");
+        const context = `assessment ${assessment.status}; seed mapping ${assessment.seedMappingStatus}; ` +
+            `graph ${assessment.graphEvidenceStatus}; neighborhood ${assessment.neighborhoodStatus}; task mapping ${assessment.taskMapping.status}` +
+            (field === "taskOverlapPercent" ? `; resolvable task nodes ${assessment.taskMapping.resolvableTaskNodeCount}` : "");
+        return unavailableMetric(unit, "derived", `Affected-neighborhood evidence did not establish ${label} (${context}).`);
+    };
+    return {
+        changedFileCount: one("changedFileCount", "the changed indexed file count"),
+        changedSymbolCount: one("changedSymbolCount", "the changed baseline symbol count"),
+        affectedNodeCount: one("affectedNodeCount", "the affected graph node count"),
+        affectedEdgeCount: one("affectedEdgeCount", "the affected graph edge count"),
+        taskOverlapCount: one("taskOverlapCount", "the task-overlap node count"),
+        taskOverlapPercent: one("taskOverlapPercent", "the task-overlap percent"),
+    };
+}
 /** 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 +252,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,8 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { buildMyDevKitIndex } from "../../../evaluation/runMyDevKitRetrieval.js";
+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
  * success but leaves no index directory is not treated as a prepared session.
@@ -17,12 +19,33 @@ export async function prepareWarmIndexSession(options) {
         }
         return { ok: false, warnings: [...build.warnings, message], build };
     }
+    const sourceRoots = Object.freeze([...options.target.sourceRoots]);
+    // One `--version` probe per prepared session, outside the measured index build; it never fails
+    // the session (an unsupported probe becomes explicit `unavailable` tool evidence).
+    const tool = await probeMyDevKitVersion({ kitCommand: options.kitCommand, commandsDir: options.commandsDir });
+    // Reads the just-built index and the files it lists; never invokes my-dev-kit again and never
+    // fails the session (an uninterpretable index becomes an explicit `unavailable` snapshot).
+    const indexSnapshot = await captureIndexSnapshot({
+        indexDir: build.indexDir,
+        targetRoot: options.target.absoluteTargetRoot,
+        sourceRoots,
+        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: Object.freeze([...options.target.sourceRoots]),
-        buildCommand: build.command
+        sourceRoots,
+        buildCommand: build.command,
+        indexSnapshot,
+        affectedNeighborhoodGraph
     });
     return { ok: true, session, build };
 }

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

@@ -97,6 +97,28 @@ function buildFindings(run) {
         ...skipped,
     ];
 }
+/** Neutral, count-only sentence derived from the report's persisted freshness summary. */
+function freshnessSentence(report) {
+    const summary = report.indexFreshnessSummary;
+    if (!summary || summary.assessedTaskCount === 0) {
+        return "No per-task index freshness assessment was available in this report.";
+    }
+    return (`Index freshness was assessed for ${summary.assessedTaskCount} task boundar${summary.assessedTaskCount === 1 ? "y" : "ies"}: ` +
+        `fresh=${summary.freshTaskCount}, stale=${summary.staleTaskCount}, partially-stale=${summary.partiallyStaleTaskCount}, unknown=${summary.unknownTaskCount}. ` +
+        "Freshness is observational evidence over files represented by the index snapshot and does not change retrieval or provider status.");
+}
+/** Neutral, count-only sentence derived from the report's persisted affected-neighborhood summary. */
+function affectedNeighborhoodSentence(report) {
+    const summary = report.affectedNeighborhoodSummary;
+    if (!summary || summary.assessedTaskCount === 0) {
+        return "No per-task affected-neighborhood assessment was available in this report.";
+    }
+    return (`Affected-neighborhood evidence was available for ${summary.assessedTaskCount} task boundar${summary.assessedTaskCount === 1 ? "y" : "ies"}: ` +
+        `complete=${summary.completeAssessmentCount}, partial=${summary.partialAssessmentCount}, unavailable=${summary.unavailableAssessmentCount}; ` +
+        `relationships were related=${summary.relatedTaskCount}, unrelated=${summary.unrelatedTaskCount}, unknown=${summary.unknownRelationshipTaskCount}; ` +
+        `reindex recommendations were recommended=${summary.recommendedReindexCount}, not-indicated=${summary.notIndicatedReindexCount}, unknown=${summary.unknownReindexRecommendationCount}. ` +
+        "Affected-neighborhood evidence uses a one-hop baseline graph around confirmed changed indexed files/symbols. It is observational and does not alter retrieval or execution status.");
+}
 function buildInterpretation(run, contextStrategyComparisonV043, warmIndexReuse) {
     if (run.pluginId === "warm-index-reuse" && warmIndexReuse) {
         const summary = warmIndexReuse.summary;
@@ -107,7 +129,8 @@ function buildInterpretation(run, contextStrategyComparisonV043, warmIndexReuse)
                     "The report separates one-time index-build duration from per-task retrieval duration and shows how the fixed build cost is amortized across repeated tasks. " +
                     `Deterministic fake-agent correctness/token evidence is available for ${summary.agentCorrectnessAvailableCount} of ${summary.agentSideCount} task sides (correctness) and ${summary.agentTotalTokensAvailableCount} (total tokens); ` +
                     "fake-agent totals are simulated harness evidence, not real-model or provider measurements. " +
-                    "Estimated context-token values are context-size estimates, not provider token usage.",
+                    "Estimated context-token values are context-size estimates, not provider token usage. " +
+                    freshnessSentence(warmIndexReuse) + " " + affectedNeighborhoodSentence(warmIndexReuse),
                 recommendedNextStep: run.status === "completed"
                     ? "Review per-task measurements and cumulative component costs for each project; the variants are reported side by side and are not ranked."
                     : "Inspect unavailable metrics, warnings, and failures before drawing conclusions from this run.",
@@ -132,7 +155,8 @@ function buildInterpretation(run, contextStrategyComparisonV043, warmIndexReuse)
                 `Agent evidence status: ${campaign.agentEvidenceStatus} (${campaign.executedSideCount} of ${campaign.scheduledSideCount} scheduled sides executed` +
                 `${nonCompletedCounts ? `; outcome counts: ${nonCompletedCounts}` : ""}). ` +
                 `Token evidence status: ${campaign.tokenEvidenceStatus} (${summary.agentTotalTokensAvailableCount} of ${summary.agentSideCount} task sides have a total-token value). ` +
-                "Context estimated tokens remain a separate character-based context-size estimate and are never substituted for provider telemetry.",
+                "Context estimated tokens remain a separate character-based context-size estimate and are never substituted for provider telemetry. " +
+                freshnessSentence(warmIndexReuse) + " " + affectedNeighborhoodSentence(warmIndexReuse),
             recommendedNextStep: isInfrastructureComplete && isAgentEvidenceComplete
                 ? "Review per-task correctness, token provenance, and cumulative component measurements."
                 : "Review infrastructure gaps (index build, raw/warm retrieval) separately from provider/agent limitations before drawing conclusions from this run.",

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

@@ -1,4 +1,4 @@
-import { WARM_INDEX_REUSE_REPORT_SCHEMA_VERSION, } from "./warmIndexReuseReportModel.js";
+import { MAX_REPORT_AFFECTED_EDGES, MAX_REPORT_AFFECTED_NODES, MAX_REPORT_AFFECTED_TASK_AMBIGUOUS, MAX_REPORT_AFFECTED_TASK_UNRESOLVED, MAX_REPORT_AFFECTED_WARNINGS, MAX_REPORT_FRESHNESS_CHANGES, MAX_REPORT_FRESHNESS_UNRESOLVED, WARM_INDEX_REUSE_REPORT_SCHEMA_VERSION, } from "./warmIndexReuseReportModel.js";
 const WARM_INDEX_REUSE_PLUGIN_ID = "warm-index-reuse";
 const COMMON_LIMITATIONS = [
     "Context estimated-token counts use the character-based estimate and are not provider billing telemetry.",
@@ -23,6 +23,24 @@ const CLAUDE_CAMPAIGN_LIMITATIONS = [
     "Token totals may be unavailable for some CLI/version/run outcomes.",
     "Unavailable token totals remain unavailable and are never replaced by zero or a context estimate.",
 ];
+const FRESHNESS_LIMITATIONS = [
+    "Freshness compares only files proven by the index snapshot to have been indexed. It does not establish that the entire repository is unchanged.",
+    "A new file that was not represented in the snapshot is outside the current freshness comparison and is not automatically evidence that the index is stale.",
+    "File content SHA-256 is the comparison identity. Modified timestamps are diagnostic metadata only.",
+    "Freshness is observational evidence. It does not trigger reindexing, suppress warm retrieval, alter execution status, or alter provider/agent outcome status.",
+    "Freshness statuses: fresh means all represented indexed files were completely compared and their content identities still match; stale means a complete comparison confirmed at least one represented indexed file is modified or missing; partially-stale means at least one represented indexed file is confirmed changed but comparison evidence is incomplete; unknown means no confirmed change established staleness but evidence is insufficient to prove freshness. A task without an assessment is reported as not assessed, which is not the same as unknown.",
+];
+const AFFECTED_NEIGHBORHOOD_LIMITATIONS = [
+    "Affected-neighborhood evidence uses a one-hop baseline graph around confirmed changed indexed files/symbols. It is observational and does not alter retrieval or execution status.",
+    "A changed baseline symbol means the symbol was present in a confirmed changed indexed file; it is not proof that the symbol's own source text changed.",
+    "Reindex recommendation categories describe this bounded analysis only. They do not claim that reindexing is mandatory, that it guarantees correctness, that skipping it is universally safe, or that the whole repository is fresh.",
+];
+/** Fixed neutral wording per recommendation category. */
+export const REINDEX_RECOMMENDATION_EXPLANATIONS = {
+    recommended: "Reindex recommended: the task has confirmed overlap with the affected one-hop baseline graph neighborhood.",
+    "not-indicated": "Reindex not indicated by this bounded analysis: complete evidence found no task-node overlap with the affected neighborhood.",
+    unknown: "Reindex recommendation unknown: evidence is incomplete or unavailable, so absence of observed overlap is not sufficient to conclude that the task is unaffected.",
+};
 const COST_MODEL = [
     "Index construction is a one-time cost per benchmark project; task retrieval is the repeated warm cost.",
     "Cold start: for the first task in a project, the cumulative warm component duration is the one-time index build plus the first retrieval.",
@@ -90,6 +108,8 @@ export function buildWarmIndexReuseReport(run) {
                     warm: task.warm,
                     rawAgent: toReportAgent(rawEvidence),
                     warmAgent: toReportAgent(warmEvidence),
+                    indexFreshness: toReportFreshness(execution.tasks[taskIndex].indexFreshness),
+                    affectedNeighborhood: toReportAffectedNeighborhood(execution.tasks[taskIndex].affectedNeighborhood, task.warm),
                 };
             }),
         };
@@ -121,6 +141,114 @@ export function buildWarmIndexReuseReport(run) {
         projects,
         agent: agentIdentity,
         agentCampaign,
+        indexFreshnessSummary: summarizeFreshness(projects.flatMap((project) => project.tasks)),
+        affectedNeighborhoodSummary: summarizeAffectedNeighborhood(projects.flatMap((project) => project.tasks)),
+    };
+}
+function boundedList(source, limit, map) {
+    const items = source.slice(0, limit).map(map);
+    return { totalCount: source.length, displayedCount: items.length, omittedCount: source.length - items.length, items };
+}
+/**
+ * Presents persisted freshness evidence only: it never recomputes a status, count, or hash and
+ * never touches the filesystem. Absent evidence stays null rather than becoming `unknown`.
+ */
+function toReportFreshness(freshness) {
+    if (!freshness)
+        return null;
+    return {
+        status: freshness.status,
+        assessedAt: freshness.assessedAt,
+        baselineSnapshotStatus: freshness.baselineSnapshotStatus,
+        indexedFileCount: freshness.indexedFileCount,
+        comparableFileCount: freshness.comparableFileCount,
+        unchangedFileCount: freshness.unchangedFileCount,
+        changedFileCount: freshness.changedFileCount,
+        missingFileCount: freshness.missingFileCount,
+        unresolvedFileCount: freshness.unresolvedFileCount,
+        changes: boundedList(freshness.changes, MAX_REPORT_FRESHNESS_CHANGES, (change) => ({ path: change.path, changeType: change.changeType })),
+        unresolved: boundedList(freshness.unresolved, MAX_REPORT_FRESHNESS_UNRESOLVED, (entry) => ({
+            path: entry.path,
+            reasonCode: entry.reasonCode,
+            message: entry.message,
+        })),
+        warnings: [...freshness.warnings],
+    };
+}
+/** Bounded list whose totals come from persisted counts, which can exceed the persisted item list. */
+function boundedListWithTotal(source, totalCount, limit, map) {
+    const items = source.slice(0, limit).map(map);
+    const total = Math.max(totalCount, source.length);
+    return { totalCount: total, displayedCount: items.length, omittedCount: total - items.length, items };
+}
+/**
+ * Presents a persisted affected-neighborhood assessment only: it never traverses, remaps seeds,
+ * recomputes overlap, or reads the graph, index, or filesystem. Numeric fields are the warm-side
+ * metric objects already calculated by the metric owner. Absent evidence stays null.
+ */
+function toReportAffectedNeighborhood(assessment, warm) {
+    if (!assessment)
+        return null;
+    const mapping = assessment.taskMapping;
+    return {
+        status: assessment.status,
+        freshnessStatus: assessment.freshnessStatus,
+        seedMappingStatus: assessment.seedMappingStatus,
+        graphEvidenceStatus: assessment.graphEvidenceStatus,
+        neighborhoodStatus: assessment.neighborhoodStatus,
+        metrics: {
+            changedFileCount: warm.changedFileCount,
+            changedSymbolCount: warm.changedSymbolCount,
+            affectedNodeCount: warm.affectedNodeCount,
+            affectedEdgeCount: warm.affectedEdgeCount,
+            taskOverlapCount: warm.taskOverlapCount,
+            taskOverlapPercent: warm.taskOverlapPercent,
+        },
+        taskMappingStatus: mapping.status,
+        resolvableTaskNodeCount: mapping.resolvableTaskNodeCount,
+        relationship: assessment.relationship,
+        reindexRecommendation: assessment.reindexRecommendation,
+        recommendationExplanation: REINDEX_RECOMMENDATION_EXPLANATIONS[assessment.reindexRecommendation],
+        affectedNodeIds: boundedList(assessment.affectedNodeIds, MAX_REPORT_AFFECTED_NODES, (id) => id),
+        participatingEdgeIds: boundedList(assessment.participatingEdgeIds, MAX_REPORT_AFFECTED_EDGES, (id) => id),
+        unresolvedTaskMappings: boundedListWithTotal(mapping.unresolved, mapping.unresolvedCount, MAX_REPORT_AFFECTED_TASK_UNRESOLVED, (entry) => ({ ...entry })),
+        ambiguousTaskSymbols: boundedListWithTotal(mapping.ambiguousSymbols, mapping.ambiguousCount, MAX_REPORT_AFFECTED_TASK_AMBIGUOUS, (entry) => ({
+            name: entry.name,
+            candidateNodeIds: [...entry.candidateNodeIds],
+        })),
+        warnings: boundedListWithTotal(assessment.warnings, assessment.warningCount, MAX_REPORT_AFFECTED_WARNINGS, (warning) => ({
+            code: warning.code,
+            message: warning.message,
+        })),
+    };
+}
+function summarizeAffectedNeighborhood(tasks) {
+    const assessed = tasks.flatMap((task) => (task.affectedNeighborhood ? [task.affectedNeighborhood] : []));
+    const count = (key, value) => assessed.filter((entry) => entry[key] === value).length;
+    return {
+        assessedTaskCount: assessed.length,
+        unassessedTaskCount: tasks.length - assessed.length,
+        completeAssessmentCount: count("status", "complete"),
+        partialAssessmentCount: count("status", "partial"),
+        unavailableAssessmentCount: count("status", "unavailable"),
+        relatedTaskCount: count("relationship", "related"),
+        unrelatedTaskCount: count("relationship", "unrelated"),
+        unknownRelationshipTaskCount: count("relationship", "unknown"),
+        recommendedReindexCount: count("reindexRecommendation", "recommended"),
+        notIndicatedReindexCount: count("reindexRecommendation", "not-indicated"),
+        unknownReindexRecommendationCount: count("reindexRecommendation", "unknown"),
+    };
+}
+function summarizeFreshness(tasks) {
+    const assessed = tasks.flatMap((task) => (task.indexFreshness ? [task.indexFreshness] : []));
+    const count = (status) => assessed.filter((freshness) => freshness.status === status).length;
+    return {
+        assessedTaskCount: assessed.length,
+        unassessedTaskCount: tasks.length - assessed.length,
+        freshTaskCount: count("fresh"),
+        staleTaskCount: count("stale"),
+        partiallyStaleTaskCount: count("partially-stale"),
+        unknownTaskCount: count("unknown"),
     };
 }
 function deriveAgentIdentity(args) {
@@ -191,10 +319,10 @@ function buildCampaignSummary(args) {
 }
 function buildLimitations(agent) {
     if (agent.mode === "deterministic-fake") {
-        return [...COMMON_LIMITATIONS, ...FAKE_AGENT_LIMITATIONS];
+        return [...COMMON_LIMITATIONS, ...FAKE_AGENT_LIMITATIONS, ...FRESHNESS_LIMITATIONS, ...AFFECTED_NEIGHBORHOOD_LIMITATIONS];
     }
     const providerLimitations = agent.id === "codex" ? CODEX_CAMPAIGN_LIMITATIONS : CLAUDE_CAMPAIGN_LIMITATIONS;
-    return [...COMMON_LIMITATIONS, ...providerLimitations];
+    return [...COMMON_LIMITATIONS, ...providerLimitations, ...FRESHNESS_LIMITATIONS, ...AFFECTED_NEIGHBORHOOD_LIMITATIONS];
 }
 function toReportAgent(agent) {
     if (!agent)

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

@@ -301,6 +301,8 @@ function renderWarmIndexReuseSection(lines, section) {
     lines.push(fieldLine("Agent Mode", section.agent.mode));
     lines.push(fieldLine("Agent Correctness Available (task sides)", `${section.summary.agentCorrectnessAvailableCount} of ${section.summary.agentSideCount}`));
     lines.push(fieldLine("Agent Token Totals Available (task sides)", `${section.summary.agentTotalTokensAvailableCount} of ${section.summary.agentSideCount}`));
+    renderFreshnessSummary(lines, section);
+    renderAffectedNeighborhoodSummary(lines, section);
     if (section.agentCampaign) {
         renderCampaignSection(lines, section.agentCampaign);
     }
@@ -324,6 +326,8 @@ function renderWarmIndexReuseSection(lines, section) {
             const rows = [
                 ["Raw Status", task.rawStatus],
                 ["Warm Status", task.warmStatus],
+                ["Index Freshness Status", task.indexFreshness ? task.indexFreshness.status : "not assessed"],
+                ["Affected Neighborhood Status", task.affectedNeighborhood ? task.affectedNeighborhood.status : "not assessed"],
                 ["Raw Context Characters", formatWarmMetric(task.raw.contextCharacters)],
                 ["Warm Context Characters", formatWarmMetric(task.warm.contextCharacters)],
                 ["Raw Estimated Context Tokens (estimate)", formatWarmMetric(task.raw.contextEstimatedTokens)],
@@ -347,9 +351,144 @@ function renderWarmIndexReuseSection(lines, section) {
             for (const [label, value] of rows) {
                 lines.push(fieldLine(label, value));
             }
+            renderTaskFreshnessDetail(lines, task.indexFreshness);
+            renderTaskAffectedNeighborhoodDetail(lines, task.affectedNeighborhood);
         }
     });
 }
+function renderFreshnessSummary(lines, section) {
+    // Reports serialized before v0.6.0 Batch 3 lack the summary; render them as having no assessment.
+    const summary = section.indexFreshnessSummary ?? {
+        assessedTaskCount: 0,
+        unassessedTaskCount: section.summary.taskCount,
+        freshTaskCount: 0,
+        staleTaskCount: 0,
+        partiallyStaleTaskCount: 0,
+        unknownTaskCount: 0,
+    };
+    pushSection(lines, "Index Freshness Summary");
+    lines.push(fieldLine("Assessed Tasks", summary.assessedTaskCount));
+    lines.push(fieldLine("Unassessed Tasks", summary.unassessedTaskCount));
+    lines.push(fieldLine("Fresh Tasks", summary.freshTaskCount));
+    lines.push(fieldLine("Stale Tasks", summary.staleTaskCount));
+    lines.push(fieldLine("Partially-Stale Tasks", summary.partiallyStaleTaskCount));
+    lines.push(fieldLine("Unknown Tasks", summary.unknownTaskCount));
+}
+function renderAffectedNeighborhoodSummary(lines, section) {
+    // Reports serialized before v0.6.1 lack the summary; render them as having no assessment.
+    const summary = section.affectedNeighborhoodSummary ?? {
+        assessedTaskCount: 0,
+        unassessedTaskCount: section.summary.taskCount,
+        completeAssessmentCount: 0,
+        partialAssessmentCount: 0,
+        unavailableAssessmentCount: 0,
+        relatedTaskCount: 0,
+        unrelatedTaskCount: 0,
+        unknownRelationshipTaskCount: 0,
+        recommendedReindexCount: 0,
+        notIndicatedReindexCount: 0,
+        unknownReindexRecommendationCount: 0,
+    };
+    pushSection(lines, "Affected Neighborhood Summary");
+    lines.push(fieldLine("Assessed Tasks", summary.assessedTaskCount));
+    lines.push(fieldLine("Unassessed Tasks", summary.unassessedTaskCount));
+    lines.push(fieldLine("Complete Assessments", summary.completeAssessmentCount));
+    lines.push(fieldLine("Partial Assessments", summary.partialAssessmentCount));
+    lines.push(fieldLine("Unavailable Assessments", summary.unavailableAssessmentCount));
+    lines.push(fieldLine("Related Tasks", summary.relatedTaskCount));
+    lines.push(fieldLine("Unrelated Tasks", summary.unrelatedTaskCount));
+    lines.push(fieldLine("Unknown-Relationship Tasks", summary.unknownRelationshipTaskCount));
+    lines.push(fieldLine("Reindex Recommended", summary.recommendedReindexCount));
+    lines.push(fieldLine("Reindex Not Indicated", summary.notIndicatedReindexCount));
+    lines.push(fieldLine("Reindex Recommendation Unknown", summary.unknownReindexRecommendationCount));
+}
+/** Renders the persisted affected-neighborhood evidence; numeric lines come from the metric owner. */
+function renderTaskAffectedNeighborhoodDetail(lines, evidence) {
+    if (!evidence)
+        return;
+    lines.push(fieldLine("Affected Neighborhood Relationship", evidence.relationship));
+    lines.push(fieldLine("Reindex Recommendation", evidence.reindexRecommendation));
+    lines.push(fieldLine("Reindex Recommendation Explanation", evidence.recommendationExplanation));
+    lines.push(fieldLine("Affected Neighborhood Freshness Status", evidence.freshnessStatus));
+    lines.push(fieldLine("Seed Mapping Status", evidence.seedMappingStatus));
+    lines.push(fieldLine("Graph Evidence Status", evidence.graphEvidenceStatus));
+    lines.push(fieldLine("Neighborhood Status", evidence.neighborhoodStatus));
+    lines.push(fieldLine("Task Mapping Status", evidence.taskMappingStatus));
+    lines.push(fieldLine("Resolvable Task Nodes", evidence.resolvableTaskNodeCount));
+    lines.push(fieldLine("Changed Indexed Files", formatWarmMetric(evidence.metrics.changedFileCount)));
+    lines.push(fieldLine("Changed Baseline Symbols", formatWarmMetric(evidence.metrics.changedSymbolCount)));
+    lines.push(fieldLine("Affected Graph Nodes", formatWarmMetric(evidence.metrics.affectedNodeCount)));
+    lines.push(fieldLine("Affected Graph Edges", formatWarmMetric(evidence.metrics.affectedEdgeCount)));
+    lines.push(fieldLine("Task-Overlap Nodes", formatWarmMetric(evidence.metrics.taskOverlapCount)));
+    lines.push(fieldLine("Task-Overlap Percent", formatWarmMetric(evidence.metrics.taskOverlapPercent)));
+    lines.push("Affected Node IDs:");
+    pushFreshnessBoundedNote(lines, evidence.affectedNodeIds);
+    if (evidence.affectedNodeIds.items.length === 0)
+        lines.push("- none");
+    for (const id of evidence.affectedNodeIds.items)
+        lines.push(`- ${sanitizeScalar(id)}`);
+    lines.push("Participating Edge IDs:");
+    pushFreshnessBoundedNote(lines, evidence.participatingEdgeIds);
+    if (evidence.participatingEdgeIds.items.length === 0)
+        lines.push("- none");
+    for (const id of evidence.participatingEdgeIds.items)
+        lines.push(`- ${sanitizeScalar(id)}`);
+    lines.push("Unresolved Task Mappings:");
+    pushFreshnessBoundedNote(lines, evidence.unresolvedTaskMappings);
+    if (evidence.unresolvedTaskMappings.items.length === 0)
+        lines.push("- none");
+    for (const entry of evidence.unresolvedTaskMappings.items) {
+        lines.push(`- ${sanitizeScalar(entry.subject)} ${sanitizeScalar(entry.name)} [${sanitizeScalar(entry.reason)}]`);
+    }
+    lines.push("Ambiguous Task Symbols:");
+    pushFreshnessBoundedNote(lines, evidence.ambiguousTaskSymbols);
+    if (evidence.ambiguousTaskSymbols.items.length === 0)
+        lines.push("- none");
+    for (const entry of evidence.ambiguousTaskSymbols.items) {
+        lines.push(`- ${sanitizeScalar(entry.name)}: ${entry.candidateNodeIds.map((id) => sanitizeScalar(id)).join(", ")}`);
+    }
+    lines.push("Affected Neighborhood Warnings:");
+    pushFreshnessBoundedNote(lines, evidence.warnings);
+    if (evidence.warnings.items.length === 0)
+        lines.push("- none");
+    for (const warning of evidence.warnings.items) {
+        lines.push(`- [${sanitizeScalar(warning.code)}] ${sanitizeScalar(warning.message)}`);
+    }
+}
+function pushFreshnessBoundedNote(lines, list) {
+    if (list.omittedCount > 0) {
+        lines.push(`Displayed: ${list.displayedCount} of ${list.totalCount}`);
+        lines.push(`Omitted: ${list.omittedCount}`);
+    }
+}
+/** Renders the persisted freshness counts and bounded evidence; hashes are never printed. */
+function renderTaskFreshnessDetail(lines, freshness) {
+    if (!freshness)
+        return;
+    lines.push(fieldLine("Baseline Snapshot Status", freshness.baselineSnapshotStatus));
+    lines.push(fieldLine("Indexed Files", freshness.indexedFileCount));
+    lines.push(fieldLine("Comparable Files", freshness.comparableFileCount));
+    lines.push(fieldLine("Unchanged Files", freshness.unchangedFileCount));
+    lines.push(fieldLine("Modified Files", freshness.changedFileCount));
+    lines.push(fieldLine("Missing Files", freshness.missingFileCount));
+    lines.push(fieldLine("Unresolved Comparisons", freshness.unresolvedFileCount));
+    lines.push("Freshness Changes:");
+    pushFreshnessBoundedNote(lines, freshness.changes);
+    if (freshness.changes.items.length === 0) {
+        lines.push("- none");
+    }
+    for (const change of freshness.changes.items) {
+        lines.push(`- ${sanitizeScalar(change.changeType)} ${sanitizeScalar(change.path)}`);
+    }
+    lines.push("Freshness Unresolved Evidence:");
+    pushFreshnessBoundedNote(lines, freshness.unresolved);
+    if (freshness.unresolved.items.length === 0) {
+        lines.push("- none");
+    }
+    for (const entry of freshness.unresolved.items) {
+        lines.push(`- ${entry.path === null ? "run-level" : sanitizeScalar(entry.path)} [${sanitizeScalar(entry.reasonCode)}] ${sanitizeScalar(entry.message)}`);
+    }
+}
 export function renderPluginExperimentReportText(report) {
     const lines = [];
     pushSection(lines, "Plugin Experiment Report");