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

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

@@ -224,13 +224,13 @@ export async function runIncrementalChangeStalenessFakeAgent(args) {
         };
     }
 }
-function correctnessComparable(fakeAgent) {
+export function correctnessComparable(fakeAgent) {
     if (!fakeAgent || !fakeAgent.correctness.available || fakeAgent.correctness.score === null) {
         return { available: false };
     }
     return { available: true, score: fakeAgent.correctness.score };
 }
-const INCONCLUSIVE_NO_EXECUTION = {
+export const INCONCLUSIVE_NO_EXECUTION = {
     correctnessRelation: "unknown",
     requiredFileEvidenceRelation: "unknown",
     staleRiskClassification: "inconclusive",
@@ -240,10 +240,12 @@ export const defaultIncrementalChangeStalenessExecutionDeps = {
     runRetrieval: runIncrementalChangeStalenessTreatmentRetrieval,
     runFakeAgent: runIncrementalChangeStalenessFakeAgent
 };
-async function executeOneTreatment(args) {
-    const treatment = args.session.treatments[args.treatmentId];
-    const baselineFreshness = treatment.changeAuthority.postMutationBaselineFreshness;
-    const activeIndexPhase = treatment.activeRetrieval.role;
+/**
+ * Retrieval + deterministic fake-agent + required-file evidence for ONE treatment against its own active
+ * index. Shared by the v0.6.2 two-treatment path and the v0.6.3 four-treatment path; takes only the
+ * lifecycle-provided facts it needs so it never reaches into another treatment's state.
+ */
+export async function executeTreatmentEvaluation(args) {
     let retrieval = null;
     let retrievalStatus = "not-run";
     let failureReason = null;
@@ -251,7 +253,7 @@ async function executeOneTreatment(args) {
         retrieval = await args.deps.runRetrieval({
             derivedTask: args.derivedTask,
             kitCommand: args.kitCommand,
-            indexDir: treatment.activeRetrieval.index.indexDir,
+            indexDir: args.activeIndexDir,
             commandsDir: args.retrievalCommandsDir
         });
         retrievalStatus = classifyIncrementalChangeStalenessRetrieval(retrieval);
@@ -284,8 +286,8 @@ async function executeOneTreatment(args) {
         treatmentId: args.treatmentId,
         status,
         failureReason,
-        activeIndexPhase,
-        baselineFreshness,
+        activeIndexPhase: args.activeIndexPhase,
+        baselineFreshness: args.baselineFreshness,
         affectedNeighborhood: args.affectedNeighborhood,
         retrieval,
         retrievalStatus,
@@ -293,6 +295,36 @@ async function executeOneTreatment(args) {
         requiredFileEvidence
     };
 }
+async function executeOneTreatment(args) {
+    const treatment = args.session.treatments[args.treatmentId];
+    return executeTreatmentEvaluation({
+        treatmentId: args.treatmentId,
+        baselineFreshness: treatment.changeAuthority.postMutationBaselineFreshness,
+        activeIndexPhase: treatment.activeRetrieval.role,
+        activeIndexDir: treatment.activeRetrieval.index.indexDir,
+        derivedTask: args.derivedTask,
+        affectedNeighborhood: args.affectedNeighborhood,
+        requiredFiles: args.requiredFiles,
+        kitCommand: args.kitCommand,
+        retrievalCommandsDir: args.retrievalCommandsDir,
+        agentOutDir: args.agentOutDir,
+        projectProfiles: args.projectProfiles,
+        cwd: args.cwd,
+        env: args.env,
+        deps: args.deps
+    });
+}
+/** Resolves the scenario's query/answer and derives the one in-memory task shared by every matched treatment. */
+export async function resolveIncrementalChangeStalenessScenarioTask(options) {
+    const { scenario } = options;
+    const resolved = await resolveIncrementalChangeStalenessQueryAndAnswer({ scenario, repoRoot: options.repoRoot });
+    const cases = await readEvaluationCases(path.resolve(options.repoRoot, WARM_INDEX_BENCHMARK_CASES_PATH), options.repoRoot);
+    const baseEvaluationCase = cases.find((candidate) => candidate.id === scenario.baseCaseId);
+    if (!baseEvaluationCase) {
+        throw new Error(`Scenario ${scenario.id}: base case ${scenario.baseCaseId} was not found for task-descriptor construction.`);
+    }
+    return { resolved, derivedTask: buildIncrementalChangeStalenessDerivedTask({ scenario, baseEvaluationCase, resolved }) };
+}
 /**
  * Executes the frozen Batch 4 order (section 36) for one ready lifecycle session: resolve query and
  * answer, derive the task descriptor, assess both treatments' affected neighborhoods from BASELINE
@@ -323,13 +355,7 @@ export async function executeIncrementalChangeStalenessScenario(options) {
         };
     }
     const session = options.lifecycle.session;
-    const resolved = await resolveIncrementalChangeStalenessQueryAndAnswer({ scenario, repoRoot: options.repoRoot });
-    const cases = await readEvaluationCases(path.resolve(options.repoRoot, WARM_INDEX_BENCHMARK_CASES_PATH), options.repoRoot);
-    const baseEvaluationCase = cases.find((candidate) => candidate.id === scenario.baseCaseId);
-    if (!baseEvaluationCase) {
-        throw new Error(`Scenario ${scenario.id}: base case ${scenario.baseCaseId} was not found for task-descriptor construction.`);
-    }
-    const derivedTask = buildIncrementalChangeStalenessDerivedTask({ scenario, baseEvaluationCase, resolved });
+    const { resolved, derivedTask } = await resolveIncrementalChangeStalenessScenarioTask({ repoRoot: options.repoRoot, scenario });
     const staleAffected = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments["stale-index"], derivedTask);
     const fullAffected = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments["full-refresh"], derivedTask);
     const symmetry = checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry(staleAffected, fullAffected);

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

@@ -9,7 +9,7 @@ import { resolveWithinRoot } from "../../../core/pathSafety.js";
 // ---------------------------------------------------------------------------
 export const INCREMENTAL_CHANGE_STALENESS_EXECUTION_ARTIFACT_FILE = "incremental-change-staleness-execution.json";
 export const INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION = "my-dev-kit-lab-incremental-change-staleness-execution-v1";
-function sortedUnique(values) {
+export function sortedUnique(values) {
     return [...new Set(values)].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
 }
 function summarizeCommand(command) {
@@ -24,7 +24,7 @@ function summarizeCommand(command) {
         error: command.error ?? null
     };
 }
-function summarizeRetrieval(treatment) {
+export function summarizeRetrieval(treatment) {
     const retrieval = treatment.retrieval;
     if (!retrieval) {
         return {
@@ -56,7 +56,7 @@ function summarizeRetrieval(treatment) {
         commands: retrieval.commands.map(summarizeCommand)
     };
 }
-function summarizeFakeAgent(treatment) {
+export function summarizeFakeAgent(treatment) {
     if (!treatment.fakeAgent)
         return null;
     const agent = treatment.fakeAgent;
@@ -69,7 +69,7 @@ function summarizeFakeAgent(treatment) {
         errors: [...agent.errors]
     };
 }
-function summarizeRequiredFileEvidence(evidence) {
+export function summarizeRequiredFileEvidence(evidence) {
     return {
         status: evidence.status,
         requiredFiles: sortedUnique(evidence.requiredFiles),

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

@@ -0,0 +1,289 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { classifyStaleRisk } from "./comparison.js";
+import { classifyPartialRefreshAgainstFull } from "./comparisonV2.js";
+import { INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS } from "./disposableTarget.js";
+import { INCREMENTAL_CHANGE_STALENESS_EXECUTION_ARTIFACT_FILE, INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION, sortedUnique, summarizeFakeAgent, summarizeRequiredFileEvidence, summarizeRetrieval } from "./executionArtifact.js";
+// ---------------------------------------------------------------------------
+// v0.6.3 Batch 3 -- persisted four-treatment execution artifact. A distinct schema from V1 written to the
+// same canonical filename; the schemaVersion is the discriminator. Bounded structured evidence only:
+// never raw retrieved context bodies, graph artifacts, or file contents. Descriptive counts, no ranking.
+// ---------------------------------------------------------------------------
+export const INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION_V2 = "my-dev-kit-lab-incremental-change-staleness-execution-v2";
+const PARTIAL_IDS = ["changed-files-refresh", "affected-neighborhood-refresh"];
+const REQUESTED_SCOPE = {
+    "changed-files-refresh": "changed-files",
+    "affected-neighborhood-refresh": "affected-neighborhood"
+};
+const COMPARISON_CANDIDATE_ORDER = ["stale-index", "changed-files-refresh", "affected-neighborhood-refresh"];
+function record(build) {
+    return Object.fromEntries(INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS.map((id) => [id, build(id)]));
+}
+function summarizeTreatmentV2(treatment) {
+    return {
+        treatmentId: treatment.treatmentId,
+        treatmentIntent: treatment.treatmentIntent,
+        status: treatment.status,
+        failureReason: treatment.failureReason,
+        activeIndexPhase: treatment.activeIndexPhase,
+        baselineFreshness: structuredClone(treatment.baselineFreshness),
+        refreshedFreshness: treatment.refreshedFreshness ? structuredClone(treatment.refreshedFreshness) : null,
+        refreshExecution: structuredClone(treatment.refreshExecution),
+        affectedNeighborhood: structuredClone(treatment.affectedNeighborhood),
+        // Bounded status/telemetry only; never embeds retrieval.contextText.
+        retrieval: summarizeRetrieval(treatment),
+        fakeAgent: summarizeFakeAgent(treatment),
+        requiredFileEvidence: summarizeRequiredFileEvidence(treatment.requiredFileEvidence)
+    };
+}
+function summarizeLifecycleV2(execution) {
+    const session = execution.session;
+    if (!session)
+        return null;
+    const refreshedStatus = {};
+    for (const id of INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS) {
+        const freshness = session.treatments[id].refreshedFreshness;
+        if (freshness)
+            refreshedStatus[id] = freshness.status;
+    }
+    return {
+        controlledFilePaths: [...session.controlledChangedPaths],
+        treatmentIntents: record((id) => INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[id]),
+        preMutationEquivalence: {
+            "changed-files-refresh": session.preMutationEquivalence["changed-files-refresh"].result,
+            "affected-neighborhood-refresh": session.preMutationEquivalence["affected-neighborhood-refresh"].result,
+            "full-refresh": session.preMutationEquivalence["full-refresh"].result
+        },
+        postMutationEquivalence: {
+            "changed-files-refresh": session.postMutationEquivalence["changed-files-refresh"].result,
+            "affected-neighborhood-refresh": session.postMutationEquivalence["affected-neighborhood-refresh"].result,
+            "full-refresh": session.postMutationEquivalence["full-refresh"].result
+        },
+        baselineFreshnessStatus: record((id) => session.treatments[id].changeAuthority.postMutationBaselineFreshness.status),
+        refreshedFreshnessStatus: refreshedStatus,
+        partialRealization: {
+            "changed-files-refresh": session.treatments["changed-files-refresh"].refreshRealization,
+            "affected-neighborhood-refresh": session.treatments["affected-neighborhood-refresh"].refreshRealization
+        },
+        indexInvocationCounts: record((id) => session.treatments[id].indexInvocationCount),
+        freshnessAssessmentCounts: record((id) => session.treatments[id].freshnessAssessmentCount),
+        totalIndexInvocationCount: session.totalIndexInvocationCount,
+        totalFreshnessAssessmentCount: session.totalFreshnessAssessmentCount,
+        myDevKitVersion: session.toolIdentity.version ?? null,
+        sourceRoots: [...session.baseCase.sourceRoots]
+    };
+}
+function summarizeScenarioV2(execution) {
+    return {
+        scenarioId: execution.scenarioId,
+        category: execution.category,
+        benchmarkProjectId: execution.benchmarkProjectId,
+        baseCaseId: execution.baseCaseId,
+        answerPolicy: execution.answerPolicy,
+        query: execution.query,
+        expectedFiles: sortedUnique(execution.expectedFiles),
+        expectedSymbols: sortedUnique(execution.expectedSymbols),
+        status: execution.status,
+        failureReason: execution.failureReason,
+        lifecycle: summarizeLifecycleV2(execution),
+        treatments: execution.treatments.map(summarizeTreatmentV2),
+        referenceComparisons: structuredClone(execution.referenceComparisons)
+    };
+}
+function partialComparison(scenario, candidate) {
+    const found = scenario.referenceComparisons.find((comparison) => comparison.candidateTreatmentId === candidate);
+    return found && found.kind === "partial-refresh" ? found : null;
+}
+function countPartial(scenarios, candidate, classification) {
+    return scenarios.filter((scenario) => partialComparison(scenario, candidate)?.classification === classification).length;
+}
+function countRealization(scenarios, candidate, realization) {
+    return scenarios.filter((scenario) => scenario.treatments.find((treatment) => treatment.treatmentId === candidate)?.refreshExecution.realization === realization).length;
+}
+function summarizeV2(scenarios) {
+    const staleClass = (scenario) => {
+        const stale = scenario.referenceComparisons.find((comparison) => comparison.candidateTreatmentId === "stale-index");
+        return stale && stale.kind === "stale-risk" ? stale.comparison.staleRiskClassification : null;
+    };
+    return {
+        scenarioCount: scenarios.length,
+        readyScenarioCount: scenarios.filter((scenario) => scenario.status === "ready").length,
+        failedScenarioCount: scenarios.filter((scenario) => scenario.status === "failed").length,
+        staleObservedRegressionCount: scenarios.filter((scenario) => staleClass(scenario) === "observed-stale-regression").length,
+        staleNoObservedRegressionCount: scenarios.filter((scenario) => staleClass(scenario) === "no-observed-stale-regression").length,
+        staleInconclusiveCount: scenarios.filter((scenario) => staleClass(scenario) === "inconclusive").length,
+        changedFilesAppliedPartialCount: countRealization(scenarios, "changed-files-refresh", "APPLIED_PARTIAL"),
+        changedFilesFallbackFullCount: countRealization(scenarios, "changed-files-refresh", "FALLBACK_FULL"),
+        affectedNeighborhoodAppliedPartialCount: countRealization(scenarios, "affected-neighborhood-refresh", "APPLIED_PARTIAL"),
+        affectedNeighborhoodFallbackFullCount: countRealization(scenarios, "affected-neighborhood-refresh", "FALLBACK_FULL"),
+        changedFilesObservedRegressionRelativeToFullCount: countPartial(scenarios, "changed-files-refresh", "observed-regression-relative-to-full"),
+        changedFilesNoObservedRegressionRelativeToFullCount: countPartial(scenarios, "changed-files-refresh", "no-observed-regression-relative-to-full"),
+        changedFilesInconclusiveCount: countPartial(scenarios, "changed-files-refresh", "inconclusive"),
+        changedFilesNotComparableCount: countPartial(scenarios, "changed-files-refresh", "not-comparable-as-partial-refresh"),
+        affectedNeighborhoodObservedRegressionRelativeToFullCount: countPartial(scenarios, "affected-neighborhood-refresh", "observed-regression-relative-to-full"),
+        affectedNeighborhoodNoObservedRegressionRelativeToFullCount: countPartial(scenarios, "affected-neighborhood-refresh", "no-observed-regression-relative-to-full"),
+        affectedNeighborhoodInconclusiveCount: countPartial(scenarios, "affected-neighborhood-refresh", "inconclusive"),
+        affectedNeighborhoodNotComparableCount: countPartial(scenarios, "affected-neighborhood-refresh", "not-comparable-as-partial-refresh")
+    };
+}
+function contradiction(scenarioId, message) {
+    throw new Error(`Contradictory v2 execution evidence for scenario ${scenarioId}: ${message}`);
+}
+function sameList(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+/**
+ * Rejects internally contradictory evidence; called before anything is built or written. Unavailable/null
+ * evidence is preserved, never coerced.
+ */
+export function validateIncrementalChangeStalenessScenarioRecordV2(scenario) {
+    const id = scenario.scenarioId;
+    // Comparisons: exactly three, fixed order, explicit identities, reference is full-refresh, never full vs full.
+    if (!sameList(scenario.referenceComparisons.map((comparison) => comparison.candidateTreatmentId), COMPARISON_CANDIDATE_ORDER)) {
+        contradiction(id, "reference comparisons must be exactly stale-index, changed-files-refresh, affected-neighborhood-refresh in order.");
+    }
+    for (const comparison of scenario.referenceComparisons) {
+        if (comparison.referenceTreatmentId !== "full-refresh")
+            contradiction(id, `${comparison.candidateTreatmentId} comparison references ${comparison.referenceTreatmentId}, not full-refresh.`);
+        if ((comparison.candidateTreatmentId === "stale-index") !== (comparison.kind === "stale-risk")) {
+            contradiction(id, `${comparison.candidateTreatmentId} comparison uses the wrong comparison kind (${comparison.kind}).`);
+        }
+    }
+    // Stale comparison must use the unchanged stale-risk semantics.
+    const stale = scenario.referenceComparisons[0];
+    if (stale.kind === "stale-risk") {
+        const expected = classifyStaleRisk(stale.comparison.correctnessRelation, stale.comparison.requiredFileEvidenceRelation);
+        if (expected.staleRiskClassification !== stale.comparison.staleRiskClassification || !sameList(expected.reasonCodes, stale.comparison.reasonCodes)) {
+            contradiction(id, "stale-index comparison does not follow the stale-risk classification rules.");
+        }
+    }
+    // Treatment collection.
+    if (scenario.treatments.length === 0) {
+        if (scenario.status === "ready")
+            contradiction(id, "a ready scenario must carry four treatment records.");
+        for (const comparison of scenario.referenceComparisons) {
+            if (comparison.kind === "partial-refresh" && comparison.refreshRealization !== null) {
+                contradiction(id, `${comparison.candidateTreatmentId} carries a refresh realization although no treatment executed.`);
+            }
+        }
+        return;
+    }
+    if (scenario.status !== "ready")
+        contradiction(id, "a failed scenario must not carry treatment records.");
+    if (!sameList(scenario.treatments.map((treatment) => treatment.treatmentId), INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS)) {
+        contradiction(id, "treatments must be exactly stale-index, changed-files-refresh, affected-neighborhood-refresh, full-refresh, each once, in order.");
+    }
+    for (const treatment of scenario.treatments) {
+        if (treatment.treatmentIntent !== INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[treatment.treatmentId]) {
+            contradiction(id, `${treatment.treatmentId} carries treatment intent ${treatment.treatmentIntent}.`);
+        }
+        const refresh = treatment.refreshExecution;
+        if (treatment.treatmentId === "stale-index") {
+            if (refresh.kind !== "no-refresh" || refresh.realization !== "NO_REFRESH" || refresh.incrementalRefresh !== null)
+                contradiction(id, "stale-index must be no-refresh without incrementalRefresh evidence.");
+            if (treatment.activeIndexPhase !== "baseline")
+                contradiction(id, "stale-index active index must be the baseline.");
+            if (treatment.refreshedFreshness !== null)
+                contradiction(id, "stale-index has no refreshed freshness.");
+        }
+        else {
+            if (treatment.activeIndexPhase !== "refreshed")
+                contradiction(id, `${treatment.treatmentId} active index must be the refreshed index.`);
+            if (treatment.refreshedFreshness === null)
+                contradiction(id, `${treatment.treatmentId} is missing refreshed freshness.`);
+        }
+        if (treatment.treatmentId === "full-refresh") {
+            if (refresh.kind !== "full" || refresh.realization !== "FULL_REFRESH" || refresh.incrementalRefresh !== null)
+                contradiction(id, "full-refresh must be a full refresh without incrementalRefresh evidence.");
+        }
+        if (treatment.treatmentId === "changed-files-refresh" || treatment.treatmentId === "affected-neighborhood-refresh") {
+            if (refresh.kind !== "incremental")
+                contradiction(id, `${treatment.treatmentId} must be an incremental refresh.`);
+            if (refresh.kind === "incremental") {
+                const upstream = refresh.incrementalRefresh;
+                if (upstream.requestedScope !== REQUESTED_SCOPE[treatment.treatmentId])
+                    contradiction(id, `${treatment.treatmentId} requested scope ${upstream.requestedScope} does not match the treatment.`);
+                if (refresh.realization === "APPLIED_PARTIAL" && (upstream.selectionStatus !== "applied" || upstream.appliedScope !== upstream.requestedScope)) {
+                    contradiction(id, `${treatment.treatmentId} is APPLIED_PARTIAL but upstream reported status=${upstream.selectionStatus} applied=${upstream.appliedScope}.`);
+                }
+                if (refresh.realization === "FALLBACK_FULL" && (upstream.selectionStatus !== "fallback-full" || upstream.appliedScope !== "full")) {
+                    contradiction(id, `${treatment.treatmentId} is FALLBACK_FULL but upstream reported status=${upstream.selectionStatus} applied=${upstream.appliedScope}.`);
+                }
+            }
+        }
+    }
+    // Partial comparisons must agree with their treatment's realization and the frozen precedence.
+    for (const candidate of PARTIAL_IDS) {
+        const comparison = partialComparison(scenario, candidate);
+        const treatment = scenario.treatments.find((entry) => entry.treatmentId === candidate);
+        if (!comparison || !treatment || treatment.refreshExecution.kind !== "incremental")
+            contradiction(id, `${candidate} comparison or treatment is missing.`);
+        else {
+            if (comparison.refreshRealization !== treatment.refreshExecution.realization) {
+                contradiction(id, `${candidate} comparison realization ${comparison.refreshRealization} differs from the treatment realization ${treatment.refreshExecution.realization}.`);
+            }
+            const expected = classifyPartialRefreshAgainstFull({
+                realization: treatment.refreshExecution.realization,
+                correctnessRelation: comparison.correctnessRelation,
+                requiredFileEvidenceRelation: comparison.requiredFileEvidenceRelation
+            });
+            if (expected.classification !== comparison.classification || !sameList(expected.reasonCodes, comparison.reasonCodes)) {
+                contradiction(id, `${candidate} comparison does not follow the partial-refresh reference rules.`);
+            }
+        }
+    }
+    if (scenario.lifecycle) {
+        for (const count of [...Object.values(scenario.lifecycle.indexInvocationCounts), ...Object.values(scenario.lifecycle.freshnessAssessmentCounts)]) {
+            if (!Number.isInteger(count) || count < 0)
+                contradiction(id, "lifecycle counts must be non-negative integers.");
+        }
+    }
+    else {
+        contradiction(id, "a ready scenario must carry a lifecycle summary.");
+    }
+}
+export function validateIncrementalChangeStalenessExecutionArtifactV2(artifact) {
+    if (artifact.schemaVersion !== INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION_V2) {
+        throw new Error(`Unexpected execution artifact schema ${String(artifact.schemaVersion)}.`);
+    }
+    for (const scenario of artifact.scenarios)
+        validateIncrementalChangeStalenessScenarioRecordV2(scenario);
+}
+/**
+ * Builds and validates the v2 artifact from already-executed scenario evidence, in the caller's canonical
+ * scenario order. Throws on internal contradiction instead of serializing it.
+ */
+export function buildIncrementalChangeStalenessExecutionArtifactV2(args) {
+    const scenarios = args.executions.map(summarizeScenarioV2);
+    const artifact = {
+        schemaVersion: INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION_V2,
+        runId: args.runId,
+        pluginId: args.pluginId,
+        scenarios,
+        summary: summarizeV2(scenarios)
+    };
+    validateIncrementalChangeStalenessExecutionArtifactV2(artifact);
+    return artifact;
+}
+/** Writes to the canonical filename shared with v1; validates first so contradictory evidence is never serialized. */
+export async function writeIncrementalChangeStalenessExecutionArtifactV2(outDir, artifact) {
+    validateIncrementalChangeStalenessExecutionArtifactV2(artifact);
+    await mkdir(outDir, { recursive: true });
+    const artifactPath = resolveWithinRoot(outDir, INCREMENTAL_CHANGE_STALENESS_EXECUTION_ARTIFACT_FILE);
+    await writeFile(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+    return artifactPath;
+}
+/** Discriminates V1 from V2 by schemaVersion only; historical V1 evidence is never converted to V2. */
+export function parseIncrementalChangeStalenessExecutionArtifact(json) {
+    const schemaVersion = json && typeof json === "object" ? json.schemaVersion : undefined;
+    if (schemaVersion === INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION) {
+        return { version: "v1", artifact: json };
+    }
+    if (schemaVersion === INCREMENTAL_CHANGE_STALENESS_EXECUTION_SCHEMA_VERSION_V2) {
+        return { version: "v2", artifact: json };
+    }
+    throw new Error(`Unrecognized incremental-change-staleness execution artifact schema: ${String(schemaVersion)}.`);
+}
+export async function readIncrementalChangeStalenessExecutionArtifact(artifactPath) {
+    return parseIncrementalChangeStalenessExecutionArtifact(JSON.parse(await readFile(artifactPath, "utf8")));
+}

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

@@ -0,0 +1,195 @@
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { classifyStaleRisk, compareCorrectness, compareRequiredFileEvidence } from "./comparison.js";
+import { compareCandidateCorrectness, compareCandidateRequiredFileEvidence, classifyPartialRefreshAgainstFull } from "./comparisonV2.js";
+import { INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS } from "./disposableTarget.js";
+import { assessIncrementalChangeStalenessAffectedNeighborhood, checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry, correctnessComparable, defaultIncrementalChangeStalenessExecutionDeps, executeTreatmentEvaluation, INCONCLUSIVE_NO_EXECUTION, resolveIncrementalChangeStalenessScenarioTask } from "./execution.js";
+/**
+ * Four-way check with stale-index only as the deterministic reference. Reuses the v0.6.2 pairwise check
+ * (status, relationship, reindexRecommendation, and the six numeric metrics) and additionally requires
+ * equal seedNodeCount. Conflicting evidence is never averaged or merged.
+ */
+export function checkAffectedNeighborhoodFourWaySymmetry(assessments) {
+    const reference = assessments["stale-index"];
+    const reasons = [];
+    for (const treatmentId of INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS) {
+        if (treatmentId === "stale-index")
+            continue;
+        const other = assessments[treatmentId];
+        const pairwise = checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry(reference, other);
+        if (!pairwise.symmetric)
+            reasons.push(`${treatmentId}: ${pairwise.reason}`);
+        if (reference.seedNodeCount !== other.seedNodeCount) {
+            reasons.push(`${treatmentId}: seedNodeCount (${reference.seedNodeCount} vs ${other.seedNodeCount})`);
+        }
+    }
+    return reasons.length === 0 ? { symmetric: true } : { symmetric: false, reason: `Affected-neighborhood assessments are asymmetric across treatments: ${reasons.join(" | ")}` };
+}
+const PARTIAL_TREATMENT_IDS = ["changed-files-refresh", "affected-neighborhood-refresh"];
+function placeholderComparisons() {
+    return [
+        { kind: "stale-risk", candidateTreatmentId: "stale-index", referenceTreatmentId: "full-refresh", comparison: { ...INCONCLUSIVE_NO_EXECUTION, reasonCodes: [...INCONCLUSIVE_NO_EXECUTION.reasonCodes] } },
+        ...PARTIAL_TREATMENT_IDS.map((candidateTreatmentId) => ({
+            kind: "partial-refresh",
+            candidateTreatmentId,
+            referenceTreatmentId: "full-refresh",
+            refreshRealization: null,
+            correctnessRelation: "unknown",
+            requiredFileEvidenceRelation: "unknown",
+            classification: "inconclusive",
+            reasonCodes: ["correctness-unavailable", "required-file-evidence-unavailable"]
+        }))
+    ];
+}
+function refreshExecutionOf(session, treatmentId) {
+    const treatment = session.treatments[treatmentId];
+    if (treatment.refreshRealization !== null) {
+        const incrementalRefresh = treatment.refreshedIndex.incrementalRefresh;
+        if (!incrementalRefresh) {
+            throw new Error(`${treatmentId} lifecycle reported ${treatment.refreshRealization} without upstream incrementalRefresh evidence.`);
+        }
+        return { kind: "incremental", realization: treatment.refreshRealization, incrementalRefresh: structuredClone(incrementalRefresh) };
+    }
+    return treatment.postMutationIndexBuilt
+        ? { kind: "full", realization: "FULL_REFRESH", incrementalRefresh: null }
+        : { kind: "no-refresh", realization: "NO_REFRESH", incrementalRefresh: null };
+}
+/**
+ * Executes the four matched treatments in fixed order for one lifecycle-ready V2 session, then builds
+ * exactly three comparisons against full-refresh. A lifecycle that is not ready, or an affected-neighborhood
+ * asymmetry, is a failed scenario with no fabricated treatment evidence.
+ */
+export async function executeIncrementalChangeStalenessScenarioV2(options) {
+    const deps = { ...defaultIncrementalChangeStalenessExecutionDeps, ...options.deps };
+    const scenario = options.scenario;
+    if (options.lifecycle.status !== "ready") {
+        return {
+            scenarioId: scenario.id,
+            category: scenario.category,
+            benchmarkProjectId: options.baseCase.benchmarkProjectId,
+            baseCaseId: options.baseCase.caseId,
+            answerPolicy: scenario.answerPolicy,
+            query: null,
+            expectedFiles: [],
+            expectedSymbols: [],
+            status: "failed",
+            failureReason: `${options.lifecycle.failure.code}: ${options.lifecycle.failure.message}`,
+            session: null,
+            treatments: [],
+            referenceComparisons: placeholderComparisons()
+        };
+    }
+    const session = options.lifecycle.session;
+    const { resolved, derivedTask } = await resolveIncrementalChangeStalenessScenarioTask({ repoRoot: options.repoRoot, scenario });
+    const scenarioBase = {
+        scenarioId: scenario.id,
+        category: scenario.category,
+        benchmarkProjectId: scenario.benchmarkProjectId,
+        baseCaseId: scenario.baseCaseId,
+        answerPolicy: scenario.answerPolicy,
+        query: resolved.query,
+        expectedFiles: resolved.expectedFiles,
+        expectedSymbols: resolved.expectedSymbols,
+        session
+    };
+    // Affected-neighborhood evidence is derived from each treatment's ORIGINAL BASELINE change authority.
+    const affected = {};
+    for (const treatmentId of INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS) {
+        affected[treatmentId] = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments[treatmentId], derivedTask);
+    }
+    const symmetry = checkAffectedNeighborhoodFourWaySymmetry(affected);
+    if (!symmetry.symmetric) {
+        return {
+            ...scenarioBase,
+            status: "failed",
+            failureReason: `AFFECTED_NEIGHBORHOOD_ASYMMETRY: ${symmetry.reason}`,
+            treatments: [],
+            referenceComparisons: placeholderComparisons()
+        };
+    }
+    const retrievalCommandsDir = (treatmentId) => resolveWithinRoot(options.runOwnedRoot, path.join("commands", scenario.id, treatmentId, "retrieval"));
+    const agentOutDir = (treatmentId) => resolveWithinRoot(options.runOwnedRoot, path.join("agents", scenario.id, treatmentId));
+    // Fixed deterministic order, sequential; each treatment retrieves only from its own active index.
+    const treatments = [];
+    for (const treatmentId of INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS) {
+        const lifecycleTreatment = session.treatments[treatmentId];
+        const evaluation = await executeTreatmentEvaluation({
+            treatmentId,
+            baselineFreshness: lifecycleTreatment.changeAuthority.postMutationBaselineFreshness,
+            activeIndexPhase: lifecycleTreatment.activeRetrieval.role,
+            activeIndexDir: lifecycleTreatment.activeRetrieval.index.indexDir,
+            derivedTask,
+            affectedNeighborhood: affected[treatmentId],
+            requiredFiles: resolved.expectedFiles,
+            kitCommand: session.kitCommand,
+            retrievalCommandsDir: retrievalCommandsDir(treatmentId),
+            agentOutDir: agentOutDir(treatmentId),
+            projectProfiles: options.projectProfiles,
+            cwd: options.cwd,
+            env: options.env,
+            deps
+        });
+        treatments.push({
+            ...evaluation,
+            treatmentIntent: INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[treatmentId],
+            refreshedFreshness: lifecycleTreatment.refreshedFreshness,
+            refreshExecution: refreshExecutionOf(session, treatmentId)
+        });
+    }
+    return {
+        ...scenarioBase,
+        status: "ready",
+        failureReason: null,
+        treatments,
+        referenceComparisons: buildReferenceComparisons(treatments)
+    };
+}
+/** Exactly three comparisons against full-refresh: stale-index, changed-files-refresh, affected-neighborhood-refresh. */
+export function buildReferenceComparisons(treatments) {
+    const byId = new Map(treatments.map((treatment) => [treatment.treatmentId, treatment]));
+    const reference = byId.get("full-refresh");
+    const stale = byId.get("stale-index");
+    if (!reference || !stale)
+        throw new Error("Reference comparisons require the stale-index and full-refresh treatment executions.");
+    // Historical v0.6.2 semantics, unchanged.
+    const staleCorrectness = compareCorrectness(correctnessComparable(stale.fakeAgent), correctnessComparable(reference.fakeAgent));
+    const staleRequired = compareRequiredFileEvidence(stale.requiredFileEvidence, reference.requiredFileEvidence);
+    const staleRisk = classifyStaleRisk(staleCorrectness, staleRequired);
+    const comparisons = [
+        {
+            kind: "stale-risk",
+            candidateTreatmentId: "stale-index",
+            referenceTreatmentId: "full-refresh",
+            comparison: {
+                correctnessRelation: staleCorrectness,
+                requiredFileEvidenceRelation: staleRequired,
+                staleRiskClassification: staleRisk.staleRiskClassification,
+                reasonCodes: staleRisk.reasonCodes
+            }
+        }
+    ];
+    for (const candidateTreatmentId of PARTIAL_TREATMENT_IDS) {
+        const candidate = byId.get(candidateTreatmentId);
+        if (!candidate || candidate.refreshExecution.kind !== "incremental") {
+            throw new Error(`${candidateTreatmentId} has no incremental refresh execution to compare.`);
+        }
+        const correctnessRelation = compareCandidateCorrectness(correctnessComparable(candidate.fakeAgent), correctnessComparable(reference.fakeAgent));
+        const requiredFileEvidenceRelation = compareCandidateRequiredFileEvidence(candidate.requiredFileEvidence, reference.requiredFileEvidence);
+        const classified = classifyPartialRefreshAgainstFull({
+            realization: candidate.refreshExecution.realization,
+            correctnessRelation,
+            requiredFileEvidenceRelation
+        });
+        comparisons.push({
+            kind: "partial-refresh",
+            candidateTreatmentId,
+            referenceTreatmentId: "full-refresh",
+            refreshRealization: candidate.refreshExecution.realization,
+            correctnessRelation,
+            requiredFileEvidenceRelation,
+            classification: classified.classification,
+            reasonCodes: classified.reasonCodes
+        });
+    }
+    return comparisons;
+}