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

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

@@ -0,0 +1,243 @@
+// 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";
+import { isV2ReportSection } from "./buildIncrementalChangeStalenessReportV2.js";
+import { renderIncrementalChangeStalenessHtmlV2 } from "./renderIncrementalChangeStalenessHtmlV2.js";
+const MAX_DISPLAY_ITEMS = 20;
+export function renderIncrementalChangeStalenessHtml(section) {
+    if (section !== null && isV2ReportSection(section))
+        return renderIncrementalChangeStalenessHtmlV2(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/renderIncrementalChangeStalenessHtmlV2.js

@@ -0,0 +1,111 @@
+// v0.6.3 -- V2 HTML section for the incremental-change-staleness plugin report. Renders the same persisted
+// facts as the text renderer through the shared row builders; every persisted string is HTML-escaped.
+import { COMPARISON_PRESENTATION_ORDER, EVIDENCE_FAMILY_NOTE, SCENARIO_SUMMARY_ROWS, TREATMENT_PRESENTATION_ORDER, affectedNeighborhoodSummary, comparisonBlock, treatmentBlock } from "./incrementalChangeStalenessReportRowsV2.js";
+const MAX_DISPLAY_ITEMS = 20;
+export function renderIncrementalChangeStalenessHtmlV2(section) {
+    return `<section>
+    <h2>Incremental-Change And Staleness Evidence</h2>
+    <p class="muted">Scoped experimental evidence: results are limited to the executed scenarios below. Full refresh is a comparison reference, not a declared best treatment.</p>
+    ${table(["Field", "Value"], SCENARIO_SUMMARY_ROWS(section.summary))}
+    ${section.scenarios.map(renderScenario).join("\n")}
+    <h3>Limitations</h3>
+    ${list(section.limitations)}
+  </section>`;
+}
+function renderScenario(scenario) {
+    const lifecycle = scenario.lifecycle;
+    const affected = affectedNeighborhoodSummary(scenario);
+    return `<h3>Scenario: ${escapeHtml(scenario.scenarioId)}</h3>
+    <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)}
+    <h4>Lifecycle Integrity</h4>
+    ${lifecycle
+        ? `${table(["Field", "Value"], [
+            ["my-dev-kit version", lifecycle.myDevKitVersion ?? "unavailable"],
+            ["Index invocations (total)", String(lifecycle.totalIndexInvocationCount)],
+            ["Freshness assessments (total)", String(lifecycle.totalFreshnessAssessmentCount)],
+            ...Object.entries(lifecycle.preMutationEquivalence).map(([id, result]) => [`Pre-mutation equivalence (${id} vs stale-index reference)`, result]),
+            ...Object.entries(lifecycle.postMutationEquivalence).map(([id, result]) => [`Post-mutation equivalence (${id} vs stale-index reference)`, result])
+        ])}<p>Controlled file paths:</p>${boundedList(lifecycle.controlledFilePaths)}<p>Source roots:</p>${boundedList(lifecycle.sourceRoots)}`
+        : "<p>Not available for this scenario.</p>"}
+    <h4>Affected-Neighborhood Evidence (Changed Baseline Neighborhood Relative To The Task)</h4>
+    ${affected.state === "none"
+        ? "<p>Not available.</p>"
+        : affected.state === "inconsistent"
+            ? "<p>inconsistent persisted evidence</p>"
+            : `${table(["Field", "Value"], affected.rows)}<p>${escapeHtml(affected.explanation)}</p>`}
+    <p class="muted">${escapeHtml(EVIDENCE_FAMILY_NOTE)}</p>
+    ${scenario.treatments.length === 0
+        ? "<h4>Treatments</h4><p>Not produced: the scenario failed before any treatment evidence existed.</p>"
+        : TREATMENT_PRESENTATION_ORDER.map((entry) => renderTreatment(scenario, entry)).join("\n")}
+    <h4>Reference Comparisons (Against The Full-Refresh Reference)</h4>
+    ${COMPARISON_PRESENTATION_ORDER.map((entry) => renderComparison(scenario, entry)).join("\n")}`;
+}
+function renderTreatment(scenario, entry) {
+    const block = treatmentBlock(scenario, entry.id, entry.label);
+    const title = `${block.label} Treatment (${entry.id})`;
+    if (!block.available)
+        return `<h4>${escapeHtml(title)}</h4><p>Not available.</p>`;
+    return `<h4>${escapeHtml(title)}</h4>
+    ${table(["Field", "Value"], block.rows)}
+    <p><strong>Refresh Execution</strong> (upstream evidence of what my-dev-kit actually did)</p>
+    ${table(["Field", "Value"], block.refreshRows)}
+    ${block.fallbackStatement ? `<p class="fallback"><strong>${escapeHtml(block.fallbackStatement)}</strong></p>` : ""}
+    ${block.forcedNeighborSample ? `<p>Forced-neighbor sample:</p>${boundedList(block.forcedNeighborSample)}` : ""}
+    <p>Files read:</p>
+    ${boundedList(block.filesRead)}
+    <p>Required files:</p>
+    ${boundedList(block.requiredFiles)}
+    <p>Observed files:</p>
+    ${boundedList(block.observedFiles)}
+    <p>Missing files:</p>
+    ${boundedList(block.missingFiles)}`;
+}
+function renderComparison(scenario, entry) {
+    const block = comparisonBlock(scenario, entry);
+    if (!block.available)
+        return `<h5>${escapeHtml(block.label)}</h5><p>Not available.</p>`;
+    return `<h5>${escapeHtml(block.label)}</h5>
+    ${table(["Field", "Value"], block.rows)}
+    <p>Reason codes:</p>
+    ${list(block.reasonCodes)}
+    <p>${escapeHtml(block.explanation)}</p>`;
+}
+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/renderIncrementalChangeStalenessTextV2.js

@@ -0,0 +1,96 @@
+// v0.6.3 -- V2 text section for the incremental-change-staleness plugin report. Renders only persisted
+// V2 report-model fields (via the shared row builders); no recomputation. Lists are bounded.
+import { COMPARISON_PRESENTATION_ORDER, EVIDENCE_FAMILY_NOTE, SCENARIO_SUMMARY_ROWS, TREATMENT_PRESENTATION_ORDER, affectedNeighborhoodSummary, comparisonBlock, treatmentBlock } from "./incrementalChangeStalenessReportRowsV2.js";
+function renderScenario(lines, scenario, h) {
+    h.pushSection(lines, `Scenario: ${scenario.scenarioId}`);
+    lines.push(h.fieldLine("Category", scenario.category));
+    lines.push(h.fieldLine("Status", scenario.status));
+    lines.push(h.fieldLine("Failure Reason", scenario.failureReason));
+    lines.push(h.fieldLine("Benchmark Project", scenario.benchmarkProjectId));
+    lines.push(h.fieldLine("Base Case", scenario.baseCaseId));
+    lines.push(h.fieldLine("Answer Policy", scenario.answerPolicy));
+    lines.push(h.fieldLine("Query", scenario.query));
+    h.pushBoundedStringList(lines, "Expected Files", scenario.expectedFiles);
+    h.pushBoundedStringList(lines, "Expected Symbols", scenario.expectedSymbols);
+    h.pushSection(lines, "Lifecycle");
+    const lifecycle = scenario.lifecycle;
+    if (!lifecycle) {
+        lines.push("Not available.");
+    }
+    else {
+        lines.push(h.fieldLine("my-dev-kit Version", lifecycle.myDevKitVersion));
+        lines.push(h.fieldLine("Index Invocations (total)", lifecycle.totalIndexInvocationCount));
+        lines.push(h.fieldLine("Freshness Assessments (total)", lifecycle.totalFreshnessAssessmentCount));
+        for (const [treatmentId, result] of Object.entries(lifecycle.preMutationEquivalence)) {
+            lines.push(h.fieldLine(`Pre-Mutation Equivalence (${treatmentId} vs stale-index reference)`, result));
+        }
+        for (const [treatmentId, result] of Object.entries(lifecycle.postMutationEquivalence)) {
+            lines.push(h.fieldLine(`Post-Mutation Equivalence (${treatmentId} vs stale-index reference)`, result));
+        }
+        h.pushBoundedStringList(lines, "Controlled File Paths", lifecycle.controlledFilePaths);
+        h.pushBoundedStringList(lines, "Source Roots", lifecycle.sourceRoots);
+    }
+    h.pushSection(lines, "Affected-Neighborhood Evidence (changed baseline neighborhood relative to the task)");
+    const affected = affectedNeighborhoodSummary(scenario);
+    if (affected.state === "none") {
+        lines.push("Not available.");
+    }
+    else if (affected.state === "inconsistent") {
+        lines.push("inconsistent persisted evidence");
+    }
+    else {
+        for (const [label, value] of affected.rows)
+            lines.push(h.fieldLine(label, value));
+        lines.push(h.fieldLine("Reindex Recommendation Explanation", affected.explanation));
+    }
+    lines.push(EVIDENCE_FAMILY_NOTE);
+    if (scenario.treatments.length === 0) {
+        h.pushSection(lines, "Treatments");
+        lines.push("Not produced: the scenario failed before any treatment evidence existed.");
+    }
+    else {
+        for (const entry of TREATMENT_PRESENTATION_ORDER) {
+            const block = treatmentBlock(scenario, entry.id, entry.label);
+            h.pushSection(lines, `${block.label} Treatment (${entry.id})`);
+            if (!block.available) {
+                lines.push("Not available.");
+                continue;
+            }
+            for (const [label, value] of block.rows)
+                lines.push(h.fieldLine(label, value));
+            lines.push("Refresh Execution (upstream evidence of what my-dev-kit actually did):");
+            for (const [label, value] of block.refreshRows)
+                lines.push(h.fieldLine(label, value));
+            if (block.fallbackStatement)
+                lines.push(block.fallbackStatement);
+            if (block.forcedNeighborSample)
+                h.pushBoundedStringList(lines, "Forced-Neighbor Sample", block.forcedNeighborSample);
+            h.pushBoundedStringList(lines, "Files Read", block.filesRead);
+            h.pushBoundedStringList(lines, "Required Files", block.requiredFiles);
+            h.pushBoundedStringList(lines, "Observed Files", block.observedFiles);
+            h.pushBoundedStringList(lines, "Missing Files", block.missingFiles);
+        }
+    }
+    h.pushSection(lines, "Reference Comparisons (against the full-refresh reference)");
+    for (const entry of COMPARISON_PRESENTATION_ORDER) {
+        const block = comparisonBlock(scenario, entry);
+        lines.push(block.label);
+        if (!block.available) {
+            lines.push("Not available.");
+            continue;
+        }
+        for (const [label, value] of block.rows)
+            lines.push(h.fieldLine(label, value));
+        h.pushDashList(lines, block.reasonCodes);
+        lines.push(block.explanation);
+    }
+}
+export function renderIncrementalChangeStalenessSectionV2(lines, section, h) {
+    h.pushSection(lines, "Summary");
+    for (const [label, value] of SCENARIO_SUMMARY_ROWS(section.summary))
+        lines.push(h.fieldLine(label, value));
+    for (const scenario of section.scenarios)
+        renderScenario(lines, scenario, h);
+    h.pushSection(lines, "Limitations");
+    h.pushDashList(lines, section.limitations);
+}

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,7 @@
+import { STALE_RISK_CLASSIFICATION_EXPLANATIONS } from "./buildIncrementalChangeStalenessReport.js";
+import { isV2ReportSection } from "./buildIncrementalChangeStalenessReportV2.js";
+import { renderIncrementalChangeStalenessSectionV2 } from "./renderIncrementalChangeStalenessTextV2.js";
+import { REINDEX_RECOMMENDATION_EXPLANATIONS } from "./buildWarmIndexReuseReport.js";
 function sanitizeScalar(value) {
     const text = String(value);
     let result = "";
@@ -489,6 +493,144 @@ 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;
+    }
+    if (isV2ReportSection(section)) {
+        renderIncrementalChangeStalenessSectionV2(lines, section, { pushSection, fieldLine, pushDashList, pushBoundedStringList });
+        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 +661,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");