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

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

@@ -1,3 +1,5 @@
+import { STALE_RISK_CLASSIFICATION_EXPLANATIONS } from "./buildIncrementalChangeStalenessReport.js";
+import { REINDEX_RECOMMENDATION_EXPLANATIONS } from "./buildWarmIndexReuseReport.js";
 function sanitizeScalar(value) {
     const text = String(value);
     let result = "";
@@ -302,6 +304,7 @@ function renderWarmIndexReuseSection(lines, section) {
     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);
     }
@@ -326,6 +329,7 @@ function renderWarmIndexReuseSection(lines, section) {
                 ["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)],
@@ -350,6 +354,7 @@ function renderWarmIndexReuseSection(lines, section) {
                 lines.push(fieldLine(label, value));
             }
             renderTaskFreshnessDetail(lines, task.indexFreshness);
+            renderTaskAffectedNeighborhoodDetail(lines, task.affectedNeighborhood);
         }
     });
 }
@@ -371,6 +376,87 @@ function renderFreshnessSummary(lines, section) {
     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}`);
@@ -405,6 +491,140 @@ function renderTaskFreshnessDetail(lines, freshness) {
         lines.push(`- ${entry.path === null ? "run-level" : sanitizeScalar(entry.path)} [${sanitizeScalar(entry.reasonCode)}] ${sanitizeScalar(entry.message)}`);
     }
 }
+const INCREMENTAL_CHANGE_STALENESS_MAX_DISPLAY_ITEMS = 20;
+function pushBoundedStringList(lines, label, items) {
+    lines.push(`${label}:`);
+    if (items.length === 0) {
+        lines.push("- none");
+        return;
+    }
+    const shown = items.slice(0, INCREMENTAL_CHANGE_STALENESS_MAX_DISPLAY_ITEMS);
+    for (const item of shown)
+        lines.push(`- ${sanitizeScalar(item)}`);
+    const omitted = items.length - shown.length;
+    if (omitted > 0)
+        lines.push(`... ${omitted} more`);
+}
+function symmetricIncrementalAffectedNeighborhood(scenario) {
+    const stale = scenario.staleTreatment?.affectedNeighborhood ?? null;
+    const fullRefresh = scenario.fullRefreshTreatment?.affectedNeighborhood ?? null;
+    if (!stale || !fullRefresh)
+        return null;
+    if (stale.relationship !== fullRefresh.relationship || stale.reindexRecommendation !== fullRefresh.reindexRecommendation) {
+        return null;
+    }
+    return stale;
+}
+function renderIncrementalChangeStalenessTreatment(lines, label, treatment) {
+    pushSection(lines, label);
+    if (!treatment) {
+        lines.push("Not available.");
+        return;
+    }
+    lines.push(fieldLine("Treatment Status", treatment.status));
+    lines.push(fieldLine("Failure Reason", treatment.failureReason));
+    lines.push(fieldLine("Active Index Phase", treatment.activeIndexPhase));
+    lines.push(fieldLine("Baseline Freshness Status", treatment.baselineFreshness.status));
+    lines.push("Retrieval (deterministic fake-agent / simulated harness evidence label applies to fakeAgent below):");
+    lines.push(fieldLine("Retrieval Status", treatment.retrieval.status));
+    lines.push(fieldLine("Selected Node ID", treatment.retrieval.selectedNodeId));
+    lines.push(fieldLine("Selected File", treatment.retrieval.selectedFile));
+    lines.push(fieldLine("Selected Symbol", treatment.retrieval.selectedSymbol));
+    lines.push(fieldLine("Context Characters", treatment.retrieval.totalChars));
+    lines.push(fieldLine("Estimated Context Tokens", treatment.retrieval.totalEstimatedTokens));
+    lines.push(fieldLine("Retrieval Duration (ms)", treatment.retrieval.durationMs));
+    pushBoundedStringList(lines, "Files Read", treatment.retrieval.filesRead);
+    pushBoundedStringList(lines, "Retrieval Warnings", treatment.retrieval.warnings);
+    lines.push("Fake-Agent Evidence (deterministic fake-agent / simulated harness evidence):");
+    if (treatment.fakeAgent) {
+        lines.push(fieldLine("Fake-Agent Status", treatment.fakeAgent.status));
+        lines.push(fieldLine("Correctness Score", treatment.fakeAgent.correctness.available ? treatment.fakeAgent.correctness.score : null));
+        lines.push(fieldLine("Passed", treatment.fakeAgent.correctness.passed));
+        lines.push(fieldLine("Fake-Agent Duration (ms)", treatment.fakeAgent.durationMs));
+    }
+    else {
+        lines.push("Not run for this treatment.");
+    }
+    lines.push("Required-File Evidence (bounded answer-key file-presence check, not retrieval precision/recall):");
+    lines.push(fieldLine("Required-File Status", treatment.requiredFileEvidence.status));
+    lines.push(fieldLine("Required-File Reason", treatment.requiredFileEvidence.reason));
+    pushBoundedStringList(lines, "Required Files", treatment.requiredFileEvidence.requiredFiles);
+    pushBoundedStringList(lines, "Observed Files", treatment.requiredFileEvidence.observedFiles);
+    pushBoundedStringList(lines, "Missing Files", treatment.requiredFileEvidence.missingFiles);
+}
+function renderIncrementalChangeStalenessScenario(lines, scenario) {
+    pushSection(lines, `Scenario: ${scenario.scenarioId}`);
+    lines.push(fieldLine("Category", scenario.category));
+    lines.push(fieldLine("Status", scenario.status));
+    lines.push(fieldLine("Failure Reason", scenario.failureReason));
+    lines.push(fieldLine("Benchmark Project", scenario.benchmarkProjectId));
+    lines.push(fieldLine("Base Case", scenario.baseCaseId));
+    lines.push(fieldLine("Answer Policy", scenario.answerPolicy));
+    lines.push(fieldLine("Query", scenario.query));
+    pushBoundedStringList(lines, "Expected Files", scenario.expectedFiles);
+    pushBoundedStringList(lines, "Expected Symbols", scenario.expectedSymbols);
+    pushSection(lines, "Lifecycle");
+    const lifecycle = scenario.lifecycle;
+    if (!lifecycle) {
+        lines.push("Not available.");
+    }
+    else {
+        lines.push(fieldLine("Pre-Mutation Equivalence", lifecycle.preMutationEquivalence));
+        lines.push(fieldLine("Post-Mutation Equivalence", lifecycle.postMutationEquivalence));
+        lines.push(fieldLine("my-dev-kit Version", lifecycle.myDevKitVersion));
+        lines.push(fieldLine("Stale Baseline Freshness Status", lifecycle.staleBaselineFreshnessStatus));
+        lines.push(fieldLine("Full-Refresh Baseline Freshness Status", lifecycle.fullRefreshBaselineFreshnessStatus));
+        lines.push(fieldLine("Full-Refresh Refreshed Freshness Status", lifecycle.fullRefreshRefreshedFreshnessStatus));
+        pushBoundedStringList(lines, "Controlled File Paths", lifecycle.controlledFilePaths);
+        pushBoundedStringList(lines, "Source Roots", lifecycle.sourceRoots);
+    }
+    pushSection(lines, "Affected-Neighborhood Evidence (changed baseline neighborhood relative to the task)");
+    const symmetric = symmetricIncrementalAffectedNeighborhood(scenario);
+    const bothPresent = scenario.staleTreatment?.affectedNeighborhood && scenario.fullRefreshTreatment?.affectedNeighborhood;
+    if (!scenario.staleTreatment?.affectedNeighborhood && !scenario.fullRefreshTreatment?.affectedNeighborhood) {
+        lines.push("Not available.");
+    }
+    else if (bothPresent && !symmetric) {
+        lines.push("inconsistent persisted evidence");
+    }
+    else if (symmetric) {
+        lines.push(fieldLine("Relationship", symmetric.relationship));
+        lines.push(fieldLine("Reindex Recommendation", symmetric.reindexRecommendation));
+        lines.push(fieldLine("Reindex Recommendation Explanation", REINDEX_RECOMMENDATION_EXPLANATIONS[symmetric.reindexRecommendation]));
+        lines.push(fieldLine("Changed Indexed Files", symmetric.changedFileCount));
+        lines.push(fieldLine("Changed Baseline Symbols", symmetric.changedSymbolCount));
+        lines.push(fieldLine("Affected Graph Nodes", symmetric.affectedNodeCount));
+        lines.push(fieldLine("Affected Graph Edges", symmetric.affectedEdgeCount));
+        lines.push(fieldLine("Task-Overlap Nodes", symmetric.taskOverlapCount));
+        lines.push(fieldLine("Task-Overlap Percent", symmetric.taskOverlapPercent));
+    }
+    renderIncrementalChangeStalenessTreatment(lines, "Stale-Index Treatment", scenario.staleTreatment);
+    renderIncrementalChangeStalenessTreatment(lines, "Full-Refresh Treatment", scenario.fullRefreshTreatment);
+    pushSection(lines, "Matched Comparison");
+    lines.push(fieldLine("Correctness Relation", scenario.comparison.correctnessRelation));
+    lines.push(fieldLine("Required-File Evidence Relation", scenario.comparison.requiredFileEvidenceRelation));
+    lines.push(fieldLine("Stale-Risk Classification", scenario.comparison.staleRiskClassification));
+    pushDashList(lines, scenario.comparison.reasonCodes);
+    lines.push(STALE_RISK_CLASSIFICATION_EXPLANATIONS[scenario.comparison.staleRiskClassification]);
+}
+function renderIncrementalChangeStalenessSection(lines, section) {
+    if (section === null) {
+        lines.push("Not applicable to this plugin.");
+        return;
+    }
+    pushSection(lines, "Summary");
+    lines.push(fieldLine("Scenarios", section.scenarioCount));
+    lines.push(fieldLine("Ready", section.readyScenarioCount));
+    lines.push(fieldLine("Failed", section.failedScenarioCount));
+    lines.push(fieldLine("Observed Stale Regression", section.observedStaleRegressionCount));
+    lines.push(fieldLine("No Observed Stale Regression", section.noObservedStaleRegressionCount));
+    lines.push(fieldLine("Inconclusive", section.inconclusiveCount));
+    for (const scenario of section.scenarios) {
+        renderIncrementalChangeStalenessScenario(lines, scenario);
+    }
+    pushSection(lines, "Limitations");
+    pushDashList(lines, section.limitations);
+}
 export function renderPluginExperimentReportText(report) {
     const lines = [];
     pushSection(lines, "Plugin Experiment Report");
@@ -435,6 +655,8 @@ export function renderPluginExperimentReportText(report) {
     renderV043Section(lines, report.contextStrategyComparisonV043);
     pushSection(lines, "Warm Index Reuse Evidence");
     renderWarmIndexReuseSection(lines, report.warmIndexReuse);
+    pushSection(lines, "Incremental-Change And Staleness Evidence");
+    renderIncrementalChangeStalenessSection(lines, report.incrementalChangeStaleness);
     pushSection(lines, "Warnings, Skips, And Failures");
     pushDashList(lines, report.findings.map((finding) => `${finding.severity} ${finding.code} ${finding.message} variant=${finding.variantId ?? ""} case=${finding.caseId ?? ""}`));
     pushSection(lines, "Artifacts");

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

@@ -5,6 +5,8 @@ const UNIT_LABELS = {
     "estimated-tokens": "est. tokens",
     tokens: "tokens",
     score: "score",
+    count: "",
+    percent: "%",
 };
 export function renderWarmIndexReuseHtml(section) {
     if (section === null) {
@@ -26,6 +28,7 @@ export function renderWarmIndexReuseHtml(section) {
         ["Agent token totals available", `${section.summary.agentTotalTokensAvailableCount} of ${section.summary.agentSideCount}`],
     ])}
     ${renderFreshnessSummary(section.indexFreshnessSummary ?? legacyFreshnessSummary(section.summary.taskCount))}
+    ${renderAffectedNeighborhoodSummary(section.affectedNeighborhoodSummary ?? legacyAffectedNeighborhoodSummary(section.summary.taskCount))}
     ${section.agentCampaign ? renderCampaignSection(section.agentCampaign) : ""}
     <h3>Cold Start And Warm Reuse</h3>
     ${list(section.costModel)}
@@ -45,6 +48,100 @@ function legacyFreshnessSummary(taskCount) {
         unknownTaskCount: 0,
     };
 }
+// Reports serialized before v0.6.1 lack the summary; they are rendered as having no assessment.
+function legacyAffectedNeighborhoodSummary(taskCount) {
+    return {
+        assessedTaskCount: 0,
+        unassessedTaskCount: taskCount,
+        completeAssessmentCount: 0,
+        partialAssessmentCount: 0,
+        unavailableAssessmentCount: 0,
+        relatedTaskCount: 0,
+        unrelatedTaskCount: 0,
+        unknownRelationshipTaskCount: 0,
+        recommendedReindexCount: 0,
+        notIndicatedReindexCount: 0,
+        unknownReindexRecommendationCount: 0,
+    };
+}
+function renderAffectedNeighborhoodSummary(summary) {
+    return `<h3>Affected Neighborhood</h3>
+    ${table(["Field", "Value"], [
+        ["Assessed tasks", String(summary.assessedTaskCount)],
+        ["Unassessed tasks", String(summary.unassessedTaskCount)],
+        ["Complete assessments", String(summary.completeAssessmentCount)],
+        ["Partial assessments", String(summary.partialAssessmentCount)],
+        ["Unavailable assessments", String(summary.unavailableAssessmentCount)],
+        ["Related tasks", String(summary.relatedTaskCount)],
+        ["Unrelated tasks", String(summary.unrelatedTaskCount)],
+        ["Unknown-relationship tasks", String(summary.unknownRelationshipTaskCount)],
+        ["Reindex recommended", String(summary.recommendedReindexCount)],
+        ["Reindex not indicated", String(summary.notIndicatedReindexCount)],
+        ["Reindex recommendation unknown", String(summary.unknownReindexRecommendationCount)],
+    ])}`;
+}
+function boundedNote(label, taskOrdinal, bounded) {
+    return bounded.omittedCount > 0 ? [`Task ${taskOrdinal}: ${bounded.omittedCount} of ${bounded.totalCount} ${label} omitted.`] : [];
+}
+/** Persisted affected-neighborhood evidence per task; numeric cells are the metric owner's objects. */
+function renderProjectAffectedNeighborhood(tasks) {
+    const overview = table(["Task", "Assessment", "Relationship", "Reindex recommendation", "Freshness", "Seeds", "Neighborhood", "Task mapping", "Resolvable task nodes"], tasks.map((task) => {
+        const label = `${task.taskOrdinal}. ${task.caseId}`;
+        const evidence = task.affectedNeighborhood;
+        return evidence
+            ? [
+                label,
+                evidence.status,
+                evidence.relationship,
+                evidence.reindexRecommendation,
+                evidence.freshnessStatus,
+                evidence.seedMappingStatus,
+                evidence.neighborhoodStatus,
+                evidence.taskMappingStatus,
+                String(evidence.resolvableTaskNodeCount),
+            ]
+            : [label, "not assessed", "", "", "", "", "", "", ""];
+    }));
+    const assessed = tasks.filter((task) => task.affectedNeighborhood !== null);
+    const metricRows = assessed.map((task) => {
+        const metrics = task.affectedNeighborhood.metrics;
+        return [
+            `${task.taskOrdinal}. ${task.caseId}`,
+            withReason(metrics.changedFileCount),
+            withReason(metrics.changedSymbolCount),
+            withReason(metrics.affectedNodeCount),
+            withReason(metrics.affectedEdgeCount),
+            withReason(metrics.taskOverlapCount),
+            withReason(metrics.taskOverlapPercent),
+        ];
+    });
+    const explanations = assessed.map((task) => `Task ${task.taskOrdinal}: ${task.affectedNeighborhood.recommendationExplanation}`);
+    const detailRows = assessed.flatMap((task) => {
+        const evidence = task.affectedNeighborhood;
+        const label = `${task.taskOrdinal}. ${task.caseId}`;
+        return [
+            ...evidence.unresolvedTaskMappings.items.map((entry) => [label, `unresolved ${entry.subject}`, entry.name, entry.reason]),
+            ...evidence.ambiguousTaskSymbols.items.map((entry) => [label, "ambiguous expected-symbol", entry.name, entry.candidateNodeIds.join(", ")]),
+            ...evidence.warnings.items.map((warning) => [label, "warning", warning.code, warning.message]),
+        ];
+    });
+    const omitted = assessed.flatMap((task) => {
+        const evidence = task.affectedNeighborhood;
+        return [
+            ...boundedNote("affected node IDs", task.taskOrdinal, evidence.affectedNodeIds),
+            ...boundedNote("participating edge IDs", task.taskOrdinal, evidence.participatingEdgeIds),
+            ...boundedNote("unresolved task mappings", task.taskOrdinal, evidence.unresolvedTaskMappings),
+            ...boundedNote("ambiguous task symbols", task.taskOrdinal, evidence.ambiguousTaskSymbols),
+            ...boundedNote("warnings", task.taskOrdinal, evidence.warnings),
+        ];
+    });
+    return `<h4>Affected Neighborhood</h4>
+    ${overview}
+    ${metricRows.length === 0 ? "" : table(["Task", "Changed files", "Changed symbols", "Affected nodes", "Affected edges", "Task-overlap nodes", "Task-overlap percent"], metricRows)}
+    ${explanations.length === 0 ? "" : list(explanations)}
+    ${detailRows.length === 0 ? "" : table(["Task", "Evidence type", "Name", "Detail"], detailRows)}
+    ${omitted.length === 0 ? "" : list(omitted)}`;
+}
 function renderFreshnessSummary(summary) {
     return `<h3>Index Freshness</h3>
     ${table(["Field", "Value"], [
@@ -184,6 +281,7 @@ function renderProject(project, index, agentId) {
         formatMetric(task.warm.cumulativeEstimatedContextTokens),
     ]))}
     ${renderProjectFreshness(project.tasks)}
+    ${renderProjectAffectedNeighborhood(project.tasks)}
     <p class="muted">Estimated tokens are character-based context-size estimates, not provider token usage.</p>
     <p class="muted">${agentColumnsNote(agentId)}</p>
     ${table([

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

@@ -2,3 +2,8 @@ export const WARM_INDEX_REUSE_REPORT_SCHEMA_VERSION = "my-dev-kit-lab-warm-index
 /** Report presentation limits; the full persisted lists stay in warm-index-execution.json. */
 export const MAX_REPORT_FRESHNESS_CHANGES = 20;
 export const MAX_REPORT_FRESHNESS_UNRESOLVED = 10;
+export const MAX_REPORT_AFFECTED_NODES = 20;
+export const MAX_REPORT_AFFECTED_EDGES = 20;
+export const MAX_REPORT_AFFECTED_TASK_UNRESOLVED = 10;
+export const MAX_REPORT_AFFECTED_TASK_AMBIGUOUS = 10;
+export const MAX_REPORT_AFFECTED_WARNINGS = 10;

package/docs/METRICS.md

@@ -1,6 +1,6 @@
 # Metrics
 
-This document is the canonical metric glossary for my-dev-kit-lab. It defines every metric that appears in benchmark profiles, prompt variants, controlled experiment artifacts, and rendered reports.
+This document is the canonical metric glossary for my-dev-kit-lab. It defines every metric that appears in benchmark profiles, prompt variants, controlled experiment artifacts, and rendered reports across the registered experiment plugins (`context-strategy-comparison`, `warm-index-reuse`, and `incremental-change-staleness`).
 
 Related documentation:
 - [ARCHITECTURE.md](ARCHITECTURE.md) — how metrics flow through the pipeline
@@ -463,7 +463,7 @@ The released v0.5.1 expanded benchmark suite adds no warm-index metric and chang
 - `unavailable`: `value` is `null` and `reason` explains the missing or invalid evidence. Missing evidence is never reported as zero, and a non-finite upstream number becomes `unavailable` with an invalid-input reason.
 - `not-applicable`: `value` is `null` and `reason` explains why the metric does not apply. The contract supports it; the current warm-index metrics do not emit it.
 
-Units are `ms`, `characters`, `estimated-tokens`, `tokens`, and `score`. Sources are `measured`, `derived`, `estimated-chars-div-4`, and `agent`. `tokenCountMethod` is set only for estimated-token metrics (currently `estimated_chars_div_4`).
+Units are `ms`, `characters`, `estimated-tokens`, `tokens`, and `score`; the affected-neighborhood metrics below add `count` and `percent` in v0.6.1. Sources are `measured`, `derived`, `estimated-chars-div-4`, and `agent`. `tokenCountMethod` is set only for estimated-token metrics (currently `estimated_chars_div_4`).
 
 **Task ordinal.** Tasks keep their filtered source order inside each benchmark project and are numbered `1, 2, 3, …` per project. Ordinals, amortization, and every cumulative sum restart for each benchmark project.
 
@@ -513,7 +513,7 @@ The plugin evaluates each task side that has context evidence once with the dete
 - Cumulative fake-agent total tokens (`tokens`, `agent`)
   Formula: sum of fake-agent total tokens for tasks `1..N` on that side, under the strict-prefix rule.
 
-**Generic outcome metrics.** Available values also appear as `ExperimentMetric` entries on each outcome, with `variantId`, `caseId`, `unit`, and `description`. Both the `raw-full-file` and `warm-index-reuse` outcomes can carry `context-character-count`, `context-estimated-token-count`, `operation-duration-ms` (raw context construction or warm retrieval), `cumulative-component-duration-ms`, `cumulative-context-estimated-token-count`, `agent-correctness-score`, `agent-total-tokens`, and `cumulative-agent-total-tokens`. The warm outcome also carries `amortized-index-build-duration-ms`. Unavailable metrics are omitted rather than emitted as zero. Run-level metrics are limited to `warm-index-project-count`, `warm-index-task-count`, and `warm-index-session-prepared-project-count`.
+**Generic outcome metrics.** Available values also appear as `ExperimentMetric` entries on each outcome, with `variantId`, `caseId`, `unit`, and `description`. Both the `raw-full-file` and `warm-index-reuse` outcomes can carry `context-character-count`, `context-estimated-token-count`, `operation-duration-ms` (raw context construction or warm retrieval), `cumulative-component-duration-ms`, `cumulative-context-estimated-token-count`, `agent-correctness-score`, `agent-total-tokens`, and `cumulative-agent-total-tokens`. The warm outcome also carries `amortized-index-build-duration-ms` and the six released v0.6.1 affected-neighborhood metrics listed below. Unavailable metrics are omitted rather than emitted as zero. Run-level metrics are limited to `warm-index-project-count`, `warm-index-task-count`, and `warm-index-session-prepared-project-count`.
 
 **Interpretation.** The report separates the one-time index cost from per-task retrieval cost and shows the fixed cost falling per task as more tasks reuse the index. It calculates no token-savings percentage, duration-reduction percentage, break-even task, composite score, winner, or ranking. Warm-index plots map the same precomputed values: amortized index build duration, raw versus retrieved estimated context tokens, fake-agent correctness (or campaign agent correctness for a `--campaign` run), and cumulative fake-agent total tokens. Unavailable values become skipped plot points with their reason.
 
@@ -553,3 +553,79 @@ Before each task's warm retrieval, the warm-index run compares the files the ind
 - **`unknown` versus not assessed.** `unknown` means an assessment ran and could not prove freshness. A task with no assessment (for example a report from before v0.6.0) is shown as `not assessed` and counted as unassessed, never as `unknown`.
 - **Report-level counts.** `report.warmIndexReuse.indexFreshnessSummary` holds direct presentation counts of assessed, unassessed, `fresh`, `stale`, `partially-stale`, and `unknown` tasks (assessed equals the sum of the four statuses). They are counts, not `ExperimentMetric` formulas: no percentage, score, or ranking is calculated. Each task's `indexFreshness` lists at most 20 changed files and 10 unresolved comparisons, with the persisted totals and the omitted count; hashes stay in `warm-index-execution.json`.
 - **Observational only.** Freshness does not trigger reindexing, suppress or alter warm retrieval, or change execution status, correctness, provider or agent outcome status, or token evidence. v0.6.0 makes no reindex recommendation.
+
+### Affected-neighborhood metrics (v0.6.1)
+
+Status: released in v0.6.1. This evidence extends the warm-index evidence above without a new command, flag, plugin, plot, or gallery item.
+
+For each task, after that task's freshness assessment and before its warm retrieval, the run maps the confirmed changed indexed files, and the baseline symbols they contain, onto the baseline my-dev-kit graph of the prepared warm index, takes the exactly one-hop neighborhood, maps the task's `expectedFiles` and `expectedSymbols` onto the same graph, and compares them. The assessment is persisted as the per-task `affectedNeighborhood` in `warm-index-execution.json`. The metric owner (`metrics.ts`) converts that persisted assessment into the six warm-side metrics below exactly once; the report renders the metric owner's objects and never recomputes them.
+
+All six metrics are warm-side only (they are not on the raw-full-file side, because raw context construction does not own baseline index graph evidence), have source `derived`, and carry the standard availability contract: `available` with a finite value (zero is a valid available value) or `unavailable` with a reason. An absent or `null` assessment makes all six unavailable with the reason "No affected-neighborhood assessment was recorded for this task."; a `null` field in a performed assessment is unavailable with a reason naming the assessment, seed-mapping, graph, neighborhood, and task-mapping statuses. Missing evidence is never reported as zero.
+
+- `changedFileCount` (`count`)
+  Meaning: the number of unique confirmed modified or missing files that the index snapshot represents.
+  Availability: available (including 0 for a fresh index) when freshness gave a basis for a changed-file list; unavailable when freshness is `unknown`.
+  Limitations: files the snapshot does not represent, including new files, are not counted.
+- `changedSymbolCount` (`count`)
+  Meaning: the number of unique baseline symbol identities (file path plus symbol name) that belong to confirmed changed indexed files, read from the baseline symbol index.
+  Limitations: it does not prove that any individual counted symbol's own source text changed; it means the symbol was present in a changed indexed file. A symbol counts even when its graph node cannot be resolved, so mapping completeness is separate from this count. Duplicate same-file, same-name records count once. It is unavailable when the baseline symbol index is unavailable.
+- `affectedNodeCount` (`count`)
+  Meaning: the number of unique graph node IDs among the resolved seed nodes plus their direct one-hop neighbors.
+  Formula: exactly one hop, bidirectional (either endpoint of an edge may be the seed), over every structurally valid retained edge kind, with no weighting by kind. Unresolved seed identities are not counted as affected nodes.
+  Availability: 0 for a complete empty seed set (for example a fresh index); unavailable when the seed mapping or graph evidence is unavailable.
+- `affectedEdgeCount` (`count`)
+  Meaning: the number of unique baseline graph edges incident to at least one resolved seed node (the edges actually followed by the one-hop expansion).
+  Limitations: it is not the number of edges among all affected nodes; an edge between two non-seed neighbors is not counted.
+- `taskOverlapCount` (`count`)
+  Meaning: the number of unique graph nodes that are both in the affected neighborhood and among the task's resolved task nodes.
+  Availability: evaluable only when both the neighborhood and the task mapping are usable.
+- `taskOverlapPercent` (`percent`)
+  Formula: `taskOverlapCount / resolvableTaskNodeCount * 100`, unrounded.
+  Denominator: `resolvableTaskNodeCount` is the number of unique graph nodes resolved from the task's `expectedFiles` (exact `file:<path>` nodes) and its unambiguous `expectedSymbols`. An expected symbol resolves only within the task's own expected files, only when exactly one candidate exists (zero is unresolved, several is ambiguous), and never by a global lookup. Unresolved and ambiguous metadata are excluded from the denominator.
+  Availability: unavailable, never zero, when there are no resolvable task nodes or overlap cannot be evaluated. When task mapping is partial, the percentage covers only the resolvable subset.
+
+**Generic outcome metrics.** Available values appear as `ExperimentMetric` entries on the warm outcome only: `affected-neighborhood-changed-file-count`, `affected-neighborhood-changed-symbol-count`, `affected-neighborhood-node-count`, `affected-neighborhood-edge-count`, `affected-neighborhood-task-overlap-count`, and `affected-neighborhood-task-overlap-percent`. Unavailable metrics stay explicit in the structured metrics and the report but are omitted from these entries rather than emitted as zero. There is no run-level aggregate, average, ranking, or score for this evidence.
+
+**Categorical evidence (not metrics).** The assessment also records, and the report presents, two categories that are deliberately not numeric `ExperimentMetric` entries:
+
+- `relationship`: `related` when the confirmed overlap is greater than zero (even when other evidence is partial); `unrelated` only when the seed mapping, neighborhood, and task mapping are all complete and the overlap is zero; `unknown` for zero observed overlap under incomplete or unavailable evidence (for example partially-stale freshness, an unresolved changed file or symbol, a partial graph, an unresolved or ambiguous expected file or symbol, or no resolvable task nodes).
+- `reindexRecommendation`: `recommended` for `related`, `not-indicated` for `unrelated`, and `unknown` for `unknown`. There is no freshness-only shortcut: a fresh index with an empty affected neighborhood and incomplete task mapping is `unknown` / `unknown`. `not-indicated` means only that this bounded analysis found no evidence supporting reindexing for that task; it does not mean skipping a reindex is universally safe, that the whole repository is fresh, that no new non-indexed file exists, or that reindexing could never help.
+- The assessment `status` (`complete`, `partial`, or `unavailable`) says how complete the evidence was. A `partial` assessment can still be `related` and `recommended`. A `null` per-task value means no assessment was performed, an absent value means a pre-v0.6.1 artifact, and an assessment whose status is `unavailable` means it was performed but the evidence could not establish a usable result; these are reported separately.
+
+**Report presentation.** `report.warmIndexReuse.affectedNeighborhoodSummary` holds presentation counts (assessed and unassessed tasks; complete, partial, and unavailable assessments; related, unrelated, and unknown relationships; recommended, not-indicated, and unknown recommendations). They are counts, not metric formulas. Each task's `affectedNeighborhood` block shows the statuses, the six metric objects, the relationship, the recommendation with a fixed explanation, and bounded lists (at most 20 affected node IDs, 20 edge IDs, 10 unresolved and 10 ambiguous task mappings, and 10 warnings, each with its total and omitted count). The full identity arrays stay in `warm-index-execution.json`.
+
+**Observational only.** The evidence never triggers reindexing, suppresses or alters warm retrieval, or changes execution, provider, agent, correctness, or token-evidence status. It uses only the baseline graph of the prepared index: there is no graph-diff, refreshed-index, or stale-versus-refreshed comparison.
+
+## Incremental-change and staleness evidence (v0.6.2)
+
+The `incremental-change-staleness` plugin reuses the six existing v0.6.1 affected-neighborhood numeric metrics unchanged (`changedFileCount`, `changedSymbolCount`, `affectedNodeCount`, `affectedEdgeCount`, `taskOverlapCount`, `taskOverlapPercent`; see "Affected-neighborhood metrics (v0.6.1)" above) and adds no new numeric formula.
+
+**Correctness relation** (per scenario, comparing the `stale-index` and `full-refresh` treatments' deterministic fake-agent correctness):
+
+- `stale-worse`: `stale-index` correctness is lower than `full-refresh` correctness.
+- `same`: both treatments have available, equal correctness.
+- `stale-better`: `stale-index` correctness is higher than `full-refresh` correctness.
+- `unknown`: either treatment's correctness is unavailable.
+
+**Required-file status** (per treatment, an answer-key file-presence check against that treatment's actual retrieved-files evidence — not retrieval precision, recall, F1, MRR, NDCG, or symbol recall):
+
+- `present`: every required file was observed.
+- `missing`: at least one required file was not observed, and the observed-files evidence was complete.
+- `unknown`: the actual-files-read evidence was not complete enough to establish presence or absence.
+
+**Required-file relation** (per scenario, comparing the two treatments' required-file status):
+
+- `stale-worse`: `stale-index` is `missing` while `full-refresh` is `present`.
+- `same`: both treatments have the same status (including `missing`/`missing`).
+- `stale-better`: `stale-index` is `present` while `full-refresh` is `missing`.
+- `unknown`: either treatment's status is `unknown`.
+
+**Stale-risk classification** (per scenario, the frozen precedence over the two relations above):
+
+1. `observed-stale-regression` — the correctness relation or the required-file relation is `stale-worse`.
+2. `inconclusive` — otherwise, if the correctness relation or the required-file relation is `unknown`.
+3. `no-observed-stale-regression` — otherwise.
+
+`staleRiskClassification` is not a numeric risk score, not a winner, not a ranking, and not an automatic reindex decision. `no-observed-stale-regression` means only that this matched scenario did not observe a stale-specific regression under these two frozen evidence dimensions; it does not establish that stale indexes are generally safe. `reindexRecommendation` (the released v0.6.1 categorical evidence) remains separate observational evidence about the affected-neighborhood analysis; it does not select or trigger either treatment and is not an input to the stale-risk classification above.
+
+**Report presentation.** `report.incrementalChangeStaleness` holds `scenarioCount`, `readyScenarioCount`, `failedScenarioCount`, `observedStaleRegressionCount`, `noObservedStaleRegressionCount`, `inconclusiveCount`, per-scenario evidence (lifecycle, both treatments in order, and the comparison), and fixed limitations text. There is no overall score, grade, winner, best-treatment, or safe-to-skip-reindex field anywhere in the report or the persisted execution artifact.

package/examples/tutorial-browser/prepare.mjs

@@ -1,14 +1,14 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const sourceRoot = path.dirname(fileURLToPath(import.meta.url));
-const targetRoot = process.argv[2];
-if (!targetRoot) {
-  console.error("prepare requires a target root argument");
-  process.exit(2);
-}
-fs.mkdirSync(path.join(targetRoot, "app"), { recursive: true });
-fs.mkdirSync(path.join(targetRoot, "out"), { recursive: true });
-for (const file of ["index.html", "server.mjs"]) fs.copyFileSync(path.join(sourceRoot, file), path.join(targetRoot, "app", file));
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const sourceRoot = path.dirname(fileURLToPath(import.meta.url));
+const targetRoot = process.argv[2];
+if (!targetRoot) {
+  console.error("prepare requires a target root argument");
+  process.exit(2);
+}
+fs.mkdirSync(path.join(targetRoot, "app"), { recursive: true });
+fs.mkdirSync(path.join(targetRoot, "out"), { recursive: true });
+for (const file of ["index.html", "server.mjs"]) fs.copyFileSync(path.join(sourceRoot, file), path.join(targetRoot, "app", file));
 fs.writeFileSync(path.join(targetRoot, "out", "report.json"), JSON.stringify({ prepared: true, counts: { widgets: 3 } }, null, 2), "utf8");

package/examples/tutorial-browser/server.mjs

@@ -1,14 +1,14 @@
-import http from "node:http";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const root = path.dirname(fileURLToPath(import.meta.url));
-const port = Number(process.env.TUTORIAL_FIXTURE_PORT || 0);
-const server = http.createServer((req, res) => {
-  const url = new URL(req.url ?? "/", "http://127.0.0.1");
-  if (url.pathname === "/api/status") { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, widgets: 3 })); return; }
-  const filePath = url.pathname === "/" ? path.join(root, "index.html") : path.join(root, url.pathname);
-  fs.readFile(filePath, (error, contents) => { if (error) { res.writeHead(404); res.end("not found"); return; } res.writeHead(200, { "content-type": filePath.endsWith(".html") ? "text/html" : "application/octet-stream" }); res.end(contents); });
-});
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const port = Number(process.env.TUTORIAL_FIXTURE_PORT || 0);
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  if (url.pathname === "/api/status") { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, widgets: 3 })); return; }
+  const filePath = url.pathname === "/" ? path.join(root, "index.html") : path.join(root, url.pathname);
+  fs.readFile(filePath, (error, contents) => { if (error) { res.writeHead(404); res.end("not found"); return; } res.writeHead(200, { "content-type": filePath.endsWith(".html") ? "text/html" : "application/octet-stream" }); res.end(contents); });
+});
 server.listen(port, "127.0.0.1", () => console.log("tutorial fixture listening on " + server.address().port));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dailephd/my-dev-kit-lab",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "type": "module",
   "description": "Evidence, benchmark, and evaluation companion for my-dev-kit.",
   "bin": {