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

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

@@ -0,0 +1,66 @@
+import { invalidExperimentConfig, isPlainObject, mergeConfig, validExperimentConfig } from "../../config.js";
+import { FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS } from "./scenarioTypes.js";
+/**
+ * The frozen v0.6.2 compatibility baseline for the upstream tool. Every index
+ * of one matched scenario must come from this one configured command.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_DEFAULT_KIT_COMMAND = "npx @dailephd/my-dev-kit@1.12.4";
+export const defaultIncrementalChangeStalenessConfig = {
+    outDir: "lab-output/incremental-change-staleness",
+    kitCommand: INCREMENTAL_CHANGE_STALENESS_DEFAULT_KIT_COMMAND
+};
+const SUPPORTED_FIELDS = ["outDir", "kitCommand", "caseIds"];
+export const incrementalChangeStalenessConfigDefinition = {
+    fields: [
+        { name: "outDir", type: "string", required: true, description: "Experiment output root." },
+        { name: "kitCommand", type: "string", description: "my-dev-kit command used for every treatment index build." },
+        {
+            name: "caseIds",
+            type: "array",
+            description: `Frozen scenario ids to include (${FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS.join(", ")}); defaults to all. Both stale-index and full-refresh always run for each selected scenario.`
+        }
+    ]
+};
+/**
+ * Closed validation: unknown fields (including any attempt to supply variant
+ * filters, catalog paths, or mutation text) are rejected. Scenario ids must be
+ * frozen production ids, non-empty, and free of duplicates, so invalid
+ * selections fail before any target or index work.
+ */
+export function validateIncrementalChangeStalenessConfig(config) {
+    if (config !== undefined && !isPlainObject(config)) {
+        return invalidExperimentConfig(["incremental-change-staleness config must be an object."]);
+    }
+    const errors = [];
+    const unsupported = Object.keys(config ?? {}).filter((key) => !SUPPORTED_FIELDS.includes(key));
+    if (unsupported.length > 0) {
+        errors.push(`Unsupported incremental-change-staleness config field(s): ${unsupported.sort().join(", ")}.`);
+    }
+    const normalized = mergeConfig(defaultIncrementalChangeStalenessConfig, config);
+    for (const field of ["outDir", "kitCommand"]) {
+        const value = normalized[field];
+        if (typeof value !== "string" || !value.trim()) {
+            errors.push(`${field} must be a non-empty string.`);
+        }
+    }
+    const caseIds = normalized.caseIds;
+    if (caseIds !== undefined) {
+        if (!Array.isArray(caseIds) || caseIds.length === 0 || !caseIds.every((item) => typeof item === "string" && item.trim())) {
+            errors.push("caseIds must be a non-empty array of non-empty scenario id strings when provided.");
+        }
+        else {
+            const duplicates = caseIds.filter((id, index) => caseIds.indexOf(id) !== index);
+            if (duplicates.length > 0) {
+                errors.push(`caseIds contains duplicate scenario id(s): ${[...new Set(duplicates)].join(", ")}.`);
+            }
+            const unknown = caseIds.filter((id) => !FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS.includes(id));
+            if (unknown.length > 0) {
+                errors.push(`caseIds contains unknown scenario id(s): ${unknown.join(", ")}. Expected one of ${FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS.join(", ")}.`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return invalidExperimentConfig(errors);
+    }
+    return validExperimentConfig(normalized);
+}

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

@@ -0,0 +1,107 @@
+import { existsSync } from "node:fs";
+import { cp, realpath, rm } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+/**
+ * The two primary v0.6.2 treatment identities, already frozen by the planned
+ * plugin design. Batch 2 uses them only to name independent disposable
+ * target copies; it never builds a treatment index or runs retrieval.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS = ["stale-index", "full-refresh"];
+/**
+ * Default project-relative, gitignored runtime location for disposable
+ * treatment targets. Callers may pass a different `runRoot`, but it must
+ * still resolve inside `repoRoot` (see `createDisposableTreatmentTarget`).
+ */
+export const DEFAULT_INCREMENTAL_CHANGE_STALENESS_RUNTIME_ROOT_RELATIVE = ".my-dev-kit-context/runtime/incremental-change-staleness";
+function assertSafeRuntimeBoundary(repoRoot, runRoot) {
+    // runRoot itself must live inside the repository; this also rejects a
+    // caller-supplied runRoot that points outside the my-dev-kit-lab worktree.
+    return resolveWithinRoot(repoRoot, path.resolve(runRoot));
+}
+function assertDisposableRootDoesNotOverlapCanonical(targetRoot, canonicalProjectRoot) {
+    const relativeFromCanonical = path.relative(canonicalProjectRoot, targetRoot);
+    const targetIsInsideCanonical = relativeFromCanonical !== "" && !relativeFromCanonical.startsWith("..") && !path.isAbsolute(relativeFromCanonical);
+    const relativeFromTarget = path.relative(targetRoot, canonicalProjectRoot);
+    const canonicalIsInsideTarget = relativeFromTarget !== "" && !relativeFromTarget.startsWith("..") && !path.isAbsolute(relativeFromTarget);
+    if (targetRoot === canonicalProjectRoot || targetIsInsideCanonical || canonicalIsInsideTarget) {
+        throw new Error(`Disposable treatment target root ${targetRoot} unsafely overlaps the canonical benchmark project root ${canonicalProjectRoot}.`);
+    }
+}
+/**
+ * Creates one independent disposable copy of a canonical benchmark project
+ * for one scenario/treatment pair. Always copies the whole benchmark
+ * project (not just the changed file), since later index/retrieval
+ * execution requires a coherent project. Never overwrites an existing
+ * destination and never allows the destination to overlap the canonical
+ * project tree.
+ */
+export async function createDisposableTreatmentTarget(options) {
+    const { repoRoot, scenarioId, treatmentId, benchmarkProjectId, canonicalProjectRootRelative } = options;
+    if (!INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS.includes(treatmentId)) {
+        throw new Error(`Unknown treatment id: ${treatmentId}. Expected one of ${INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS.join(", ")}.`);
+    }
+    if (typeof scenarioId !== "string" || scenarioId.length === 0) {
+        throw new Error("scenarioId must be a nonempty string.");
+    }
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    const resolvedRunRoot = assertSafeRuntimeBoundary(resolvedRepoRoot, options.runRoot);
+    const canonicalProjectRoot = resolveWithinRoot(resolvedRepoRoot, canonicalProjectRootRelative);
+    const targetRoot = resolveWithinRoot(resolvedRunRoot, path.join(scenarioId, treatmentId));
+    assertDisposableRootDoesNotOverlapCanonical(targetRoot, canonicalProjectRoot);
+    if (!existsSync(canonicalProjectRoot)) {
+        throw new Error(`Canonical benchmark project root does not exist: ${canonicalProjectRoot}.`);
+    }
+    if (existsSync(targetRoot)) {
+        throw new Error(`Disposable treatment target already exists; refusing to overwrite: ${targetRoot}.`);
+    }
+    await cp(canonicalProjectRoot, targetRoot, { recursive: true, errorOnExist: true, force: false });
+    return {
+        scenarioId,
+        treatmentId,
+        benchmarkProjectId,
+        canonicalProjectRoot,
+        targetRoot
+    };
+}
+/**
+ * Removes one disposable treatment target directory. Only ever deletes a
+ * path that resolves inside the caller-owned `runRoot`; refuses to touch
+ * anything else, including a canonical benchmark project. Idempotent: a
+ * missing target is a successful no-op.
+ */
+export async function removeDisposableTreatmentTarget(target, repoRoot, runRoot) {
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    const resolvedRunRoot = assertSafeRuntimeBoundary(resolvedRepoRoot, runRoot);
+    // Re-derive containment from the caller-owned root rather than trusting the descriptor blindly.
+    const containedTargetRoot = resolveWithinRoot(resolvedRunRoot, path.resolve(target.targetRoot));
+    await rm(containedTargetRoot, { recursive: true, force: true });
+}
+/**
+ * Removes the entire caller-owned runtime root (both treatment copies for
+ * every scenario created under it). Refuses to operate unless `runRoot`
+ * resolves inside `repoRoot`, and never touches anything outside it.
+ */
+export async function removeIncrementalChangeStalenessRuntimeRoot(repoRoot, runRoot) {
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    const resolvedRunRoot = assertSafeRuntimeBoundary(resolvedRepoRoot, runRoot);
+    await rm(resolvedRunRoot, { recursive: true, force: true });
+}
+/**
+ * Resolves a target-relative path inside a disposable treatment target,
+ * rejecting both textual path traversal and symlink escape: the resolved
+ * real path (once the file exists) must still be contained by the real
+ * path of the treatment root.
+ */
+export async function resolveWithinDisposableTarget(target, relativePath) {
+    const resolved = resolveWithinRoot(target.targetRoot, relativePath);
+    if (!existsSync(resolved)) {
+        return resolved;
+    }
+    const [realResolved, realRoot] = await Promise.all([realpath(resolved), realpath(target.targetRoot)]);
+    const relativeFromRoot = path.relative(realRoot, realResolved);
+    if (relativeFromRoot === ".." || relativeFromRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeFromRoot)) {
+        throw new Error(`Resolved path escapes the disposable treatment root via a symbolic link: ${relativePath}`);
+    }
+    return resolved;
+}

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

@@ -0,0 +1,404 @@
+import path from "node:path";
+import { runAgentPrompt } from "../../../agents/index.js";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { assessAffectedNeighborhood, mapAffectedNeighborhoodSeeds } from "../../../evaluation/affectedNeighborhood.js";
+import { classifyAgentRunOutcome } from "../../../evaluation/classifyAgentRunOutcome.js";
+import { parseAgentAnswer } from "../../../evaluation/parseAgentAnswer.js";
+import { readEvaluationCases } from "../../../evaluation/readEvaluationCases.js";
+import { runMyDevKitRetrievalFromIndex } from "../../../evaluation/runMyDevKitRetrieval.js";
+import { scoreCorrectness } from "../../../evaluation/scoreCorrectness.js";
+import { generatePromptVariants } from "../../../prompts/index.js";
+import { buildRequiredFileEvidence, classifyStaleRisk, compareCorrectness, compareRequiredFileEvidence } from "./comparison.js";
+import { WARM_INDEX_BENCHMARK_CASES_PATH } from "./scenarioCatalog.js";
+// ---------------------------------------------------------------------------
+// v0.6.2 Batch 4 -- treatment retrieval, correctness, and required-file
+// evidence. Reuses existing generic owners exactly (mapAffectedNeighborhoodSeeds
+// / assessAffectedNeighborhood, runMyDevKitRetrievalFromIndex, scoreCorrectness,
+// generatePromptVariants + runAgentPrompt("fake-agent") + parseAgentAnswer +
+// classifyAgentRunOutcome). No new correctness/retrieval/fake-agent algorithm
+// is introduced here.
+// ---------------------------------------------------------------------------
+const SCOREABLE_STATUSES = new Set(["completed", "invalid-output"]);
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Resolves one scenario's query/answer key. `inherit` reuses the referenced base case's existing
+ * query/answer key unchanged; `scenario` uses the scenario's own post-mutation query/answer key.
+ * The two are never merged. Reads the same canonical benchmark-case contract the lifecycle already
+ * validated against; never mutates it.
+ */
+export async function resolveIncrementalChangeStalenessQueryAndAnswer(options) {
+    const { scenario, repoRoot } = options;
+    if (scenario.answerPolicy === "scenario") {
+        if (!scenario.scenarioQuery || !scenario.scenarioAnswerKey) {
+            throw new Error(`Scenario ${scenario.id}: answerPolicy is "scenario" but scenarioQuery/scenarioAnswerKey are missing.`);
+        }
+        return {
+            query: scenario.scenarioQuery,
+            answerKey: scenario.scenarioAnswerKey,
+            expectedFiles: [...scenario.scenarioAnswerKey.expectedFiles],
+            expectedSymbols: [...scenario.scenarioAnswerKey.expectedSymbols]
+        };
+    }
+    const cases = await readEvaluationCases(path.resolve(repoRoot, WARM_INDEX_BENCHMARK_CASES_PATH), repoRoot);
+    const baseCase = cases.find((candidate) => candidate.id === scenario.baseCaseId);
+    if (!baseCase) {
+        throw new Error(`Scenario ${scenario.id}: base case ${scenario.baseCaseId} was not found for query/answer resolution.`);
+    }
+    if (!baseCase.answerKey) {
+        throw new Error(`Scenario ${scenario.id}: base case ${scenario.baseCaseId} declares no answerKey for the "inherit" answer policy.`);
+    }
+    return {
+        query: baseCase.query,
+        answerKey: baseCase.answerKey,
+        expectedFiles: [...baseCase.answerKey.expectedFiles],
+        expectedSymbols: [...baseCase.answerKey.expectedSymbols]
+    };
+}
+// ---------------------------------------------------------------------------
+// Derived in-memory task descriptor (section 9). Never written to disk and
+// never replaces the canonical benchmark case/answer-key files.
+// ---------------------------------------------------------------------------
+/**
+ * Builds one in-memory `EvaluationCase`-shaped task descriptor: identity/project/source ownership
+ * comes from the canonical base case; query and expected files/symbols come from the resolved
+ * query/answer. Used for affected-neighborhood task mapping, treatment retrieval, and fake-agent
+ * prompt generation; it is never materialized as a benchmark case file.
+ */
+export function buildIncrementalChangeStalenessDerivedTask(args) {
+    const base = args.baseEvaluationCase;
+    return {
+        ...base,
+        id: `${args.scenario.id}:${base.id}`,
+        title: `${args.scenario.id} (${base.title})`,
+        query: args.resolved.query,
+        expectedFiles: [...args.resolved.expectedFiles],
+        expectedSymbols: [...args.resolved.expectedSymbols],
+        answerKey: args.resolved.answerKey,
+        projectProfileRef: base.projectProfileRef ?? base.benchmarkProject
+    };
+}
+// ---------------------------------------------------------------------------
+// Affected-neighborhood execution (sections 10-14, 56).
+// ---------------------------------------------------------------------------
+/**
+ * Assesses one treatment's affected neighborhood using its BASELINE change authority (never the
+ * refreshed graph, even for full-refresh): the baseline index's snapshot/graph plus the treatment's
+ * already-established post-mutation baseline freshness.
+ */
+export function assessIncrementalChangeStalenessAffectedNeighborhood(treatment, derivedTask) {
+    const changeAuthority = treatment.changeAuthority;
+    const seedMapping = mapAffectedNeighborhoodSeeds({
+        indexSnapshot: changeAuthority.baselineIndex.snapshot,
+        freshness: changeAuthority.postMutationBaselineFreshness,
+        graph: changeAuthority.baselineIndex.graph
+    });
+    return assessAffectedNeighborhood({ graph: changeAuthority.baselineIndex.graph, seedMapping, task: derivedTask });
+}
+const SYMMETRIC_NUMERIC_FIELDS = [
+    "changedFileCount",
+    "changedSymbolCount",
+    "affectedNodeCount",
+    "affectedEdgeCount",
+    "taskOverlapCount",
+    "taskOverlapPercent"
+];
+/**
+ * Section 13: requires equality of assessment status, relationship, reindexRecommendation, and the
+ * availability/value of all six numeric metrics between the two treatment baselines. Does not
+ * require raw graph identity or absolute paths to match.
+ */
+export function checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry(stale, fullRefresh) {
+    const mismatches = [];
+    if (stale.status !== fullRefresh.status)
+        mismatches.push(`status (${stale.status} vs ${fullRefresh.status})`);
+    if (stale.relationship !== fullRefresh.relationship)
+        mismatches.push(`relationship (${stale.relationship} vs ${fullRefresh.relationship})`);
+    if (stale.reindexRecommendation !== fullRefresh.reindexRecommendation) {
+        mismatches.push(`reindexRecommendation (${stale.reindexRecommendation} vs ${fullRefresh.reindexRecommendation})`);
+    }
+    for (const field of SYMMETRIC_NUMERIC_FIELDS) {
+        if (stale[field] !== fullRefresh[field]) {
+            mismatches.push(`${field} (${String(stale[field])} vs ${String(fullRefresh[field])})`);
+        }
+    }
+    if (mismatches.length === 0)
+        return { symmetric: true };
+    return { symmetric: false, reason: `Affected-neighborhood assessments are asymmetric: ${mismatches.join("; ")}.` };
+}
+/** Same classification rule as the existing warm-index-reuse execution owner. */
+export function classifyIncrementalChangeStalenessRetrieval(result) {
+    if (!result.skipped)
+        return "completed";
+    return result.commands.some((command) => !command.ok) ? "failed" : "skipped";
+}
+export async function runIncrementalChangeStalenessTreatmentRetrieval(args) {
+    return runMyDevKitRetrievalFromIndex({
+        evaluationCase: args.derivedTask,
+        kitCommand: args.kitCommand,
+        indexDir: args.indexDir,
+        commandsDir: args.commandsDir,
+        requireKit: false
+    });
+}
+/**
+ * Section 27: a `failed` retrieval status means the actual-files-read set cannot be trusted as
+ * complete (unknown); `completed` and `skipped` (search ran and legitimately found no candidate)
+ * both provide a complete, trustworthy files-read set, possibly empty.
+ */
+export function buildIncrementalChangeStalenessRequiredFileEvidence(args) {
+    if (!args.retrieval) {
+        return buildRequiredFileEvidence({
+            requiredFiles: args.requiredFiles,
+            observedFiles: [],
+            observedFilesComplete: false,
+            unknownReason: "No retrieval was attempted for this treatment."
+        });
+    }
+    const status = classifyIncrementalChangeStalenessRetrieval(args.retrieval);
+    return buildRequiredFileEvidence({
+        requiredFiles: args.requiredFiles,
+        observedFiles: args.retrieval.filesRead,
+        observedFilesComplete: status !== "failed",
+        unknownReason: status === "failed"
+            ? `Retrieval failed (${args.retrieval.warnings.join(" ") || "my-dev-kit retrieval command failed."}); the actual-files-read set is incomplete.`
+            : undefined
+    });
+}
+export async function runIncrementalChangeStalenessFakeAgent(args) {
+    try {
+        const [promptVariant] = generatePromptVariants({
+            cases: [args.derivedTask],
+            projectProfiles: [...args.projectProfiles],
+            strategies: ["my-dev-kit-guided"],
+            complexityLevels: ["short"]
+        });
+        if (!promptVariant) {
+            throw new Error(`Failed to generate a fake-agent prompt for case ${args.derivedTask.id}.`);
+        }
+        const agentRunResult = await runAgentPrompt({
+            runId: args.runId,
+            agentId: "fake-agent",
+            promptVariant,
+            promptText: promptVariant.promptText,
+            cwd: args.cwd,
+            outDir: args.outDir,
+            env: args.env
+        });
+        const parsedAnswer = parseAgentAnswer({
+            text: agentRunResult.finalAnswerText,
+            answerKey: promptVariant.expectedAnswerKey,
+            tokenUsage: agentRunResult.tokenUsage
+        });
+        const classification = classifyAgentRunOutcome({ agentRunResult, parsedAnswer });
+        const correctness = scoreCorrectness({
+            caseId: args.derivedTask.id,
+            answerKey: promptVariant.expectedAnswerKey,
+            parsedAnswer,
+            status: classification.status
+        });
+        const scoreable = SCOREABLE_STATUSES.has(classification.status) && Number.isFinite(correctness.correctnessScore);
+        return {
+            status: classification.status,
+            correctness: {
+                available: scoreable,
+                score: scoreable ? correctness.correctnessScore : null,
+                passed: scoreable ? correctness.passed : null,
+                failureReasons: [...correctness.failureReasons]
+            },
+            correctnessDetail: scoreable ? correctness : null,
+            durationMs: agentRunResult.durationMs,
+            warnings: [...classification.warnings],
+            errors: [...classification.errors]
+        };
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            correctness: { available: false, score: null, passed: null, failureReasons: [] },
+            correctnessDetail: null,
+            durationMs: null,
+            warnings: [],
+            errors: [errorMessage(error)]
+        };
+    }
+}
+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 = {
+    correctnessRelation: "unknown",
+    requiredFileEvidenceRelation: "unknown",
+    staleRiskClassification: "inconclusive",
+    reasonCodes: ["correctness-unavailable", "required-file-evidence-unavailable"]
+};
+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;
+    let retrieval = null;
+    let retrievalStatus = "not-run";
+    let failureReason = null;
+    try {
+        retrieval = await args.deps.runRetrieval({
+            derivedTask: args.derivedTask,
+            kitCommand: args.kitCommand,
+            indexDir: treatment.activeRetrieval.index.indexDir,
+            commandsDir: args.retrievalCommandsDir
+        });
+        retrievalStatus = classifyIncrementalChangeStalenessRetrieval(retrieval);
+    }
+    catch (error) {
+        failureReason = `Treatment retrieval threw: ${errorMessage(error)}`;
+        retrievalStatus = "failed";
+    }
+    let fakeAgent = null;
+    if (retrieval !== null) {
+        fakeAgent = await args.deps.runFakeAgent({
+            derivedTask: args.derivedTask,
+            projectProfiles: args.projectProfiles,
+            outDir: args.agentOutDir,
+            cwd: args.cwd,
+            runId: `${args.derivedTask.id}.${args.treatmentId}`,
+            env: args.env
+        });
+    }
+    const requiredFileEvidence = buildIncrementalChangeStalenessRequiredFileEvidence({
+        requiredFiles: args.requiredFiles,
+        retrieval
+    });
+    const status = retrievalStatus === "failed" || fakeAgent?.status === "failed"
+        ? "partial"
+        : retrievalStatus === "completed" && fakeAgent && fakeAgent.correctness.available
+            ? "completed"
+            : "partial";
+    return {
+        treatmentId: args.treatmentId,
+        status,
+        failureReason,
+        activeIndexPhase,
+        baselineFreshness,
+        affectedNeighborhood: args.affectedNeighborhood,
+        retrieval,
+        retrievalStatus,
+        fakeAgent,
+        requiredFileEvidence
+    };
+}
+/**
+ * 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
+ * change authority, verify symmetry, then run stale retrieval/fake-agent/correctness/required-file
+ * evidence, then full-refresh, then compare and classify. A lifecycle that is not `ready` is
+ * reported as a failed scenario execution with no fabricated treatment evidence (section 39).
+ */
+export async function executeIncrementalChangeStalenessScenario(options) {
+    const deps = { ...defaultIncrementalChangeStalenessExecutionDeps, ...options.deps };
+    const scenario = options.scenario;
+    if (options.lifecycle.status !== "ready") {
+        // Section 39: scenario-level failure; no treatment execution, comparison stays inconclusive.
+        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,
+            stale: null,
+            fullRefresh: null,
+            comparison: INCONCLUSIVE_NO_EXECUTION
+        };
+    }
+    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 staleAffected = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments["stale-index"], derivedTask);
+    const fullAffected = assessIncrementalChangeStalenessAffectedNeighborhood(session.treatments["full-refresh"], derivedTask);
+    const symmetry = checkIncrementalChangeStalenessAffectedNeighborhoodSymmetry(staleAffected, fullAffected);
+    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
+    };
+    if (!symmetry.symmetric) {
+        return {
+            ...scenarioBase,
+            status: "failed",
+            failureReason: `AFFECTED_NEIGHBORHOOD_ASYMMETRY: ${symmetry.reason}`,
+            stale: null,
+            fullRefresh: null,
+            comparison: INCONCLUSIVE_NO_EXECUTION
+        };
+    }
+    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));
+    // Stale-index runs first, deterministically, before full-refresh (section 37).
+    const stale = await executeOneTreatment({
+        session,
+        treatmentId: "stale-index",
+        derivedTask,
+        affectedNeighborhood: staleAffected,
+        requiredFiles: resolved.expectedFiles,
+        kitCommand: session.kitCommand,
+        retrievalCommandsDir: retrievalCommandsDir("stale-index"),
+        agentOutDir: agentOutDir("stale-index"),
+        projectProfiles: options.projectProfiles,
+        cwd: options.cwd,
+        env: options.env,
+        deps
+    });
+    const fullRefresh = await executeOneTreatment({
+        session,
+        treatmentId: "full-refresh",
+        derivedTask,
+        affectedNeighborhood: fullAffected,
+        requiredFiles: resolved.expectedFiles,
+        kitCommand: session.kitCommand,
+        retrievalCommandsDir: retrievalCommandsDir("full-refresh"),
+        agentOutDir: agentOutDir("full-refresh"),
+        projectProfiles: options.projectProfiles,
+        cwd: options.cwd,
+        env: options.env,
+        deps
+    });
+    const correctnessRelation = compareCorrectness(correctnessComparable(stale.fakeAgent), correctnessComparable(fullRefresh.fakeAgent));
+    const requiredFileEvidenceRelation = compareRequiredFileEvidence(stale.requiredFileEvidence, fullRefresh.requiredFileEvidence);
+    const classification = classifyStaleRisk(correctnessRelation, requiredFileEvidenceRelation);
+    return {
+        ...scenarioBase,
+        status: "ready",
+        failureReason: null,
+        stale,
+        fullRefresh,
+        comparison: {
+            correctnessRelation,
+            requiredFileEvidenceRelation,
+            staleRiskClassification: classification.staleRiskClassification,
+            reasonCodes: classification.reasonCodes
+        }
+    };
+}