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

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

@@ -0,0 +1,239 @@
+// v0.6.2 Batch 5 -- plugin-specific HTML section rendering only. Renders exactly the persisted
+// report-model fields; performs no classification, no metric arithmetic, and no percent
+// calculation beyond formatting an already-persisted number.
+import { STALE_RISK_CLASSIFICATION_EXPLANATIONS } from "./buildIncrementalChangeStalenessReport.js";
+import { REINDEX_RECOMMENDATION_EXPLANATIONS } from "./buildWarmIndexReuseReport.js";
+const MAX_DISPLAY_ITEMS = 20;
+export function renderIncrementalChangeStalenessHtml(section) {
+    if (section === null) {
+        return `<section>
+    <h2>Incremental-Change And Staleness Evidence</h2>
+    <p>Not applicable to this plugin.</p>
+  </section>`;
+    }
+    return `<section>
+    <h2>Incremental-Change And Staleness Evidence</h2>
+    <p class="muted">Scoped experimental evidence: results are limited to the executed scenarios below, not a general safety verdict.</p>
+    ${table(["Field", "Value"], [
+        ["Scenarios", String(section.scenarioCount)],
+        ["Ready", String(section.readyScenarioCount)],
+        ["Failed", String(section.failedScenarioCount)],
+        ["Observed stale regression", String(section.observedStaleRegressionCount)],
+        ["No observed stale regression", String(section.noObservedStaleRegressionCount)],
+        ["Inconclusive", String(section.inconclusiveCount)]
+    ])}
+    <h3>Scenario Comparison</h3>
+    ${table([
+        "Scenario",
+        "Category",
+        "Status",
+        "Relationship",
+        "Reindex recommendation",
+        "Stale correctness",
+        "Full-refresh correctness",
+        "Correctness relation",
+        "Stale required files",
+        "Full-refresh required files",
+        "Required-file relation",
+        "Stale-risk classification"
+    ], section.scenarios.map(comparisonRow))}
+    ${section.scenarios.map(renderScenarioDetail).join("\n")}
+    <h3>Limitations</h3>
+    ${list(section.limitations)}
+  </section>`;
+}
+function symmetricAffectedNeighborhood(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 comparisonRow(scenario) {
+    const stale = scenario.staleTreatment?.affectedNeighborhood ?? null;
+    const fullRefresh = scenario.fullRefreshTreatment?.affectedNeighborhood ?? null;
+    const symmetric = symmetricAffectedNeighborhood(scenario);
+    const inconsistent = stale !== null && fullRefresh !== null && symmetric === null;
+    return [
+        `${scenario.scenarioId}`,
+        scenario.category,
+        scenario.status,
+        inconsistent ? "inconsistent persisted evidence" : symmetric?.relationship ?? "not available",
+        inconsistent ? "inconsistent persisted evidence" : symmetric?.reindexRecommendation ?? "not available",
+        formatCorrectness(scenario.staleTreatment),
+        formatCorrectness(scenario.fullRefreshTreatment),
+        scenario.comparison.correctnessRelation,
+        scenario.staleTreatment?.requiredFileEvidence.status ?? "not available",
+        scenario.fullRefreshTreatment?.requiredFileEvidence.status ?? "not available",
+        scenario.comparison.requiredFileEvidenceRelation,
+        scenario.comparison.staleRiskClassification
+    ];
+}
+function formatCorrectness(treatment) {
+    if (!treatment || !treatment.fakeAgent)
+        return "unavailable";
+    const correctness = treatment.fakeAgent.correctness;
+    return correctness.available && correctness.score !== null ? String(correctness.score) : "unavailable";
+}
+function renderScenarioDetail(scenario) {
+    return `<h3>Scenario: ${escapeHtml(scenario.scenarioId)}</h3>
+    ${renderDefinition(scenario)}
+    ${renderLifecycle(scenario)}
+    ${renderAffectedNeighborhoodSection(scenario)}
+    ${renderTreatment("Stale-Index Treatment", scenario.staleTreatment)}
+    ${renderTreatment("Full-Refresh Treatment", scenario.fullRefreshTreatment)}
+    ${renderComparison(scenario)}`;
+}
+function renderDefinition(scenario) {
+    return `<h4>Scenario Definition</h4>
+    ${table(["Field", "Value"], [
+        ["Scenario ID", scenario.scenarioId],
+        ["Category", scenario.category],
+        ["Benchmark project", scenario.benchmarkProjectId],
+        ["Base case", scenario.baseCaseId],
+        ["Answer policy", scenario.answerPolicy],
+        ["Query", scenario.query ?? "unavailable"],
+        ["Status", scenario.status],
+        ["Failure reason", scenario.failureReason ?? "not applicable"]
+    ])}
+    <p>Expected files:</p>
+    ${boundedList(scenario.expectedFiles)}
+    <p>Expected symbols:</p>
+    ${boundedList(scenario.expectedSymbols)}`;
+}
+function renderLifecycle(scenario) {
+    const lifecycle = scenario.lifecycle;
+    if (!lifecycle) {
+        return `<h4>Lifecycle Integrity</h4><p>Not available for this scenario.</p>`;
+    }
+    return `<h4>Lifecycle Integrity</h4>
+    ${table(["Field", "Value"], [
+        ["Pre-mutation equivalence", lifecycle.preMutationEquivalence],
+        ["Post-mutation equivalence", lifecycle.postMutationEquivalence],
+        ["my-dev-kit version", lifecycle.myDevKitVersion ?? "unavailable"],
+        ["Stale baseline freshness", lifecycle.staleBaselineFreshnessStatus],
+        ["Full-refresh baseline freshness", lifecycle.fullRefreshBaselineFreshnessStatus],
+        ["Full-refresh refreshed freshness", lifecycle.fullRefreshRefreshedFreshnessStatus ?? "unavailable"]
+    ])}
+    <p>Controlled file paths:</p>
+    ${boundedList(lifecycle.controlledFilePaths)}
+    <p>Source roots:</p>
+    ${boundedList(lifecycle.sourceRoots)}`;
+}
+function renderAffectedNeighborhoodSection(scenario) {
+    const stale = scenario.staleTreatment?.affectedNeighborhood ?? null;
+    const fullRefresh = scenario.fullRefreshTreatment?.affectedNeighborhood ?? null;
+    if (!stale && !fullRefresh) {
+        return `<h4>Affected-Neighborhood Evidence (Changed Baseline Neighborhood Relative To The Task)</h4><p>Not available.</p>`;
+    }
+    const symmetric = symmetricAffectedNeighborhood(scenario);
+    if (!symmetric) {
+        return `<h4>Affected-Neighborhood Evidence (Changed Baseline Neighborhood Relative To The Task)</h4><p>inconsistent persisted evidence</p>`;
+    }
+    const explanation = REINDEX_RECOMMENDATION_EXPLANATIONS[symmetric.reindexRecommendation];
+    return `<h4>Affected-Neighborhood Evidence (Changed Baseline Neighborhood Relative To The Task)</h4>
+    ${table(["Field", "Value"], [
+        ["Relationship", symmetric.relationship],
+        ["Reindex recommendation", symmetric.reindexRecommendation],
+        ["Changed indexed files", formatAffectedNumber(symmetric.changedFileCount)],
+        ["Changed baseline symbols", formatAffectedNumber(symmetric.changedSymbolCount)],
+        ["Affected graph nodes", formatAffectedNumber(symmetric.affectedNodeCount)],
+        ["Affected graph edges", formatAffectedNumber(symmetric.affectedEdgeCount)],
+        ["Task-overlap nodes", formatAffectedNumber(symmetric.taskOverlapCount)],
+        ["Task-overlap percent", formatAffectedNumber(symmetric.taskOverlapPercent)]
+    ])}
+    <p>${escapeHtml(explanation)}</p>`;
+}
+function renderTreatment(title, treatment) {
+    if (!treatment) {
+        return `<h4>${escapeHtml(title)}</h4><p>Not available.</p>`;
+    }
+    const retrieval = treatment.retrieval;
+    const fakeAgent = treatment.fakeAgent;
+    const requiredFileEvidence = treatment.requiredFileEvidence;
+    return `<h4>${escapeHtml(title)}</h4>
+    ${table(["Field", "Value"], [
+        ["Treatment status", treatment.status],
+        ["Failure reason", treatment.failureReason ?? "not applicable"],
+        ["Active index phase", treatment.activeIndexPhase],
+        ["Baseline freshness status", treatment.baselineFreshness.status]
+    ])}
+    <p><strong>Retrieval</strong> (bounded evidence; full retrieved context body is never rendered here)</p>
+    ${table(["Field", "Value"], [
+        ["Status", retrieval.status],
+        ["Selected node ID", retrieval.selectedNodeId ?? "unavailable"],
+        ["Selected file", retrieval.selectedFile ?? "unavailable"],
+        ["Selected symbol", retrieval.selectedSymbol ?? "unavailable"],
+        ["Context characters", String(retrieval.totalChars)],
+        ["Estimated context tokens", String(retrieval.totalEstimatedTokens)],
+        ["Duration (ms)", String(retrieval.durationMs)]
+    ])}
+    <p>Files read:</p>
+    ${boundedList(retrieval.filesRead)}
+    <p>Retrieval warnings:</p>
+    ${boundedList(retrieval.warnings)}
+    <p><strong>Fake-Agent Evidence</strong> (deterministic fake-agent / simulated harness evidence, not a provider or real-model measurement)</p>
+    ${fakeAgent
+        ? table(["Field", "Value"], [
+            ["Status", fakeAgent.status],
+            ["Correctness score", fakeAgent.correctness.available && fakeAgent.correctness.score !== null ? String(fakeAgent.correctness.score) : "unavailable"],
+            ["Passed", fakeAgent.correctness.passed === null ? "unavailable" : String(fakeAgent.correctness.passed)],
+            ["Duration (ms)", fakeAgent.durationMs === null ? "unavailable" : String(fakeAgent.durationMs)]
+        ])
+        : "<p>Not run for this treatment.</p>"}
+    <p><strong>Required-File Evidence</strong> (bounded answer-key file-presence check, not retrieval precision/recall)</p>
+    ${table(["Field", "Value"], [
+        ["Status", requiredFileEvidence.status],
+        ["Reason", requiredFileEvidence.reason ?? "not applicable"]
+    ])}
+    <p>Required files:</p>
+    ${boundedList(requiredFileEvidence.requiredFiles)}
+    <p>Observed files:</p>
+    ${boundedList(requiredFileEvidence.observedFiles)}
+    <p>Missing files:</p>
+    ${boundedList(requiredFileEvidence.missingFiles)}`;
+}
+function renderComparison(scenario) {
+    const comparison = scenario.comparison;
+    const explanation = STALE_RISK_CLASSIFICATION_EXPLANATIONS[comparison.staleRiskClassification];
+    return `<h4>Matched Comparison</h4>
+    ${table(["Field", "Value"], [
+        ["Correctness relation", comparison.correctnessRelation],
+        ["Required-file evidence relation", comparison.requiredFileEvidenceRelation],
+        ["Stale-risk classification", comparison.staleRiskClassification]
+    ])}
+    <p>Reason codes:</p>
+    ${list(comparison.reasonCodes)}
+    <p>${escapeHtml(explanation)}</p>`;
+}
+function formatAffectedNumber(value) {
+    return value === null ? "unavailable" : String(value);
+}
+function boundedList(items) {
+    if (items.length === 0)
+        return "<p>none</p>";
+    const shown = items.slice(0, MAX_DISPLAY_ITEMS);
+    const omitted = items.length - shown.length;
+    return `${list(shown)}${omitted > 0 ? `<p class="muted">... ${omitted} more</p>` : ""}`;
+}
+function list(items) {
+    if (items.length === 0)
+        return "<ul><li>none</li></ul>";
+    return `<ul>${items.map((item) => `<li>${escapeHtml(item)}</li>`).join("")}</ul>`;
+}
+function table(headers, rows) {
+    return `<table><thead><tr>${headers.map((header) => `<th>${escapeHtml(header)}</th>`).join("")}</tr></thead><tbody>${rows
+        .map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(cell)}</td>`).join("")}</tr>`)
+        .join("")}</tbody></table>`;
+}
+function escapeHtml(value) {
+    return String(value ?? "")
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}

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

@@ -1,5 +1,6 @@
 import { renderContextStrategyComparisonV043Html } from "./renderContextStrategyComparisonV043Html.js";
 import { renderWarmIndexReuseHtml } from "./renderWarmIndexReuseHtml.js";
+import { renderIncrementalChangeStalenessHtml } from "./renderIncrementalChangeStalenessHtml.js";
 export function renderPluginExperimentReportHtml(report) {
     return `<!DOCTYPE html>
 <html lang="en">
@@ -99,6 +100,8 @@ export function renderPluginExperimentReportHtml(report) {
 
   ${renderWarmIndexReuseHtml(report.warmIndexReuse)}
 
+  ${renderIncrementalChangeStalenessHtml(report.incrementalChangeStaleness)}
+
   <section>
     <h2>Warnings, Skips, And Failures</h2>
     ${report.findings.length ? table(["Severity", "Code", "Message", "Variant", "Case"], report.findings.map((finding) => [

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 = "";
@@ -489,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");
@@ -519,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/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
@@ -595,3 +595,37 @@ All six metrics are warm-side only (they are not on the raw-full-file side, beca
 **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/package.json

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