@dailephd/my-dev-kit-lab 0.7.2 → 0.8.1

package/dist/src/evaluation/retrievalQuality/factContextTargets.js

@@ -0,0 +1,44 @@
+import { normalizeRetrievedRepositoryPath } from "./buildRetrievalEvidence.js";
+/** True when the target participates in fact mapping, i.e. it carries a `factIds` field. */
+export function hasFactMapping(target) {
+    return typeof target === "object" && target !== null && !Array.isArray(target) && target.factIds !== undefined;
+}
+/**
+ * Single owner of the `ExpectedContextTarget.factIds` contract. Pure. Problems are fixed bounded strings and
+ * never echo the offending value. Unsafe file identities are rejected, never repaired.
+ */
+export function interpretFactContextTarget(target, knownFactIds) {
+    if (typeof target !== "object" || target === null || Array.isArray(target)) {
+        return { ok: false, problem: "target must be an object" };
+    }
+    const record = target;
+    const file = normalizeRetrievedRepositoryPath(record.file);
+    if (file === null) {
+        return { ok: false, problem: "file must be a safe repository-relative path" };
+    }
+    const rawFactIds = record.factIds;
+    if (!Array.isArray(rawFactIds) || rawFactIds.length === 0 || rawFactIds.some((id) => typeof id !== "string" || id.length === 0)) {
+        return { ok: false, problem: "factIds must be a nonempty array of nonempty strings" };
+    }
+    const factIds = rawFactIds;
+    if (new Set(factIds).size !== factIds.length) {
+        return { ok: false, problem: "factIds must not contain duplicates" };
+    }
+    if (factIds.some((id) => !knownFactIds.has(id))) {
+        return { ok: false, problem: "factIds must reference existing expectedFacts ids" };
+    }
+    let symbols = [];
+    if (record.symbols !== undefined) {
+        if (!Array.isArray(record.symbols) || record.symbols.some((symbol) => typeof symbol !== "string" || symbol.length === 0)) {
+            return { ok: false, problem: "symbols must be an array of nonempty strings" };
+        }
+        symbols = record.symbols;
+        if (new Set(symbols).size !== symbols.length) {
+            return { ok: false, problem: "symbols must not contain duplicates" };
+        }
+    }
+    if (record.required !== undefined && typeof record.required !== "boolean") {
+        return { ok: false, problem: "required must be a boolean when present" };
+    }
+    return { ok: true, target: { file, symbols: [...symbols], required: record.required !== false, factIds: [...factIds] } };
+}

package/dist/src/evaluation/retrievalQuality/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./buildRetrievalEvidence.js";
+export * from "./factContextTargets.js";
+export * from "./metrics.js";
+export * from "./corpusCompleteness.js";

package/dist/src/evaluation/retrievalQuality/metrics.js

@@ -0,0 +1,258 @@
+import { compareCodeUnits } from "../indexSnapshot.js";
+import { normalizeRetrievedRepositoryPath } from "./buildRetrievalEvidence.js";
+import { hasFactMapping, interpretFactContextTarget } from "./factContextTargets.js";
+const sortedUnique = (values) => [...new Set(values)].sort(compareCodeUnits);
+function ratio(numerator, denominator, notApplicableReason) {
+    if (denominator === 0) {
+        return { availability: "not-applicable", numerator: null, denominator: null, value: null, reason: notApplicableReason };
+    }
+    return { availability: "available", numerator, denominator, value: numerator / denominator, reason: null };
+}
+function unavailableRatio(reason) {
+    return { availability: "unavailable", numerator: null, denominator: null, value: null, reason };
+}
+function normalizeExpectedFiles(values) {
+    if (!Array.isArray(values))
+        return { ok: false, reason: "expected-files-missing" };
+    const normalized = [];
+    for (const value of values) {
+        const path = normalizeRetrievedRepositoryPath(value);
+        if (path === null)
+            return { ok: false, reason: "unsafe-expected-file-identity" };
+        normalized.push(path);
+    }
+    return { ok: true, values: sortedUnique(normalized) };
+}
+function normalizeExpectedSymbols(values) {
+    if (!Array.isArray(values))
+        return { ok: false, reason: "expected-symbols-missing" };
+    if (values.some((value) => typeof value !== "string" || value.length === 0))
+        return { ok: false, reason: "invalid-expected-symbol" };
+    return { ok: true, values: sortedUnique(values) };
+}
+function sameSet(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+/**
+ * The answer key is the semantic source of relevance. A top-level expectation that is also present must agree
+ * with it after normalization; disagreement is never silently reconciled.
+ */
+function resolveExpectation(topLevel, answerKeyValues, hasAnswerKey, normalize, mismatchReason) {
+    if (!hasAnswerKey)
+        return normalize(topLevel);
+    const fromKey = normalize(answerKeyValues);
+    if (!fromKey.ok)
+        return fromKey;
+    if (Array.isArray(topLevel)) {
+        const fromTop = normalize(topLevel);
+        if (!fromTop.ok)
+            return fromTop;
+        if (!sameSet(fromTop.values, fromKey.values))
+            return { ok: false, reason: mismatchReason };
+    }
+    return fromKey;
+}
+const expectationStatus = (resolved) => resolved.ok ? { availability: "available", reason: null } : { availability: "unavailable", reason: resolved.reason };
+/** Symbol name -> normalized files it was retrieved from. Symbols without file identity cannot satisfy a file-specific target. */
+function symbolFilesByName(evidence) {
+    const byName = new Map();
+    for (const symbol of evidence.symbols) {
+        if (symbol.file === undefined)
+            continue;
+        const files = byName.get(symbol.name) ?? new Set();
+        files.add(symbol.file);
+        byName.set(symbol.name, files);
+    }
+    return byName;
+}
+function calculateFactCoverage(answerKey, evidence, retrievedFiles) {
+    if (!answerKey || typeof answerKey !== "object")
+        return { kind: "unavailable", reason: "answer-key-missing" };
+    const facts = answerKey.expectedFacts;
+    if (!Array.isArray(facts))
+        return { kind: "unavailable", reason: "expected-facts-invalid" };
+    const factIds = [];
+    for (const fact of facts) {
+        const id = typeof fact === "object" && fact !== null ? fact.id : undefined;
+        if (typeof id !== "string" || id.length === 0 || factIds.includes(id)) {
+            return { kind: "unavailable", reason: "expected-facts-invalid" };
+        }
+        factIds.push(id);
+    }
+    if (factIds.length === 0)
+        return { kind: "not-applicable", reason: "no-expected-facts" };
+    const targets = answerKey.expectedContextTargets;
+    if (!Array.isArray(targets))
+        return { kind: "unavailable", reason: "fact-context-mapping-unavailable" };
+    const known = new Set(factIds);
+    const targetsByFact = new Map(factIds.map((id) => [id, []]));
+    for (const target of targets) {
+        if (!hasFactMapping(target))
+            continue;
+        const required = target.required !== false;
+        const interpretation = interpretFactContextTarget(target, known);
+        if (!interpretation.ok) {
+            // An invalid optional target cannot gate coverage; an invalid required one makes the mapping untrustworthy.
+            if (required)
+                return { kind: "unavailable", reason: "fact-context-mapping-invalid" };
+            continue;
+        }
+        if (!interpretation.target.required)
+            continue;
+        for (const id of interpretation.target.factIds)
+            targetsByFact.get(id)?.push(interpretation.target);
+    }
+    if (factIds.some((id) => (targetsByFact.get(id) ?? []).length === 0)) {
+        return { kind: "unavailable", reason: "fact-context-mapping-unavailable" };
+    }
+    const symbolFiles = symbolFilesByName(evidence);
+    const isCovered = (target) => retrievedFiles.has(target.file) && target.symbols.every((symbol) => symbolFiles.get(symbol)?.has(target.file) === true);
+    const covered = factIds.filter((id) => (targetsByFact.get(id) ?? []).every(isCovered));
+    const coveredSet = new Set(covered);
+    return {
+        kind: "computed",
+        covered: sortedUnique(covered),
+        uncovered: sortedUnique(factIds.filter((id) => !coveredSet.has(id))),
+        total: factIds.length
+    };
+}
+function evidenceReason(evidence) {
+    if (evidence === undefined)
+        return "retrieval-evidence-missing";
+    if (evidence.availability === "partial")
+        return "retrieval-evidence-partial";
+    if (evidence.availability === "unavailable")
+        return "retrieval-evidence-unavailable";
+    return null;
+}
+/**
+ * Pure per-case retrieval-quality calculation. Formulas are planner-frozen:
+ * file precision = |R_file ∩ E_file| / |R_file|; file recall = |R_file ∩ E_file| / |E_file|;
+ * irrelevant context ratio = |R_file - E_file| / |R_file|; symbol precision/recall use the same set formulas
+ * over exact unique symbol names; fact coverage = covered facts / expected facts, unweighted and derived only
+ * from explicit `factIds` target mappings. No input is mutated and nothing is read from disk or text.
+ * Unavailable or not-applicable results are never converted to zero.
+ */
+export function calculateRetrievalQualityMetrics(input) {
+    const evidence = input.retrieval.retrievalEvidence;
+    return calculateRetrievalQualityMetricsFromIdentityEvidence({
+        evaluationCase: input.evaluationCase,
+        retrieval: {
+            identityEvidence: evidence === undefined
+                ? undefined
+                : {
+                    availability: evidence.availability,
+                    ...(evidence.availabilityReason !== undefined ? { availabilityReason: evidence.availabilityReason } : {}),
+                    files: evidence.files.map((file) => file.path),
+                    symbols: evidence.symbols.map((symbol) => ({
+                        name: symbol.name,
+                        ...(symbol.file !== undefined ? { file: symbol.file } : {})
+                    }))
+                },
+            totalEstimatedTokens: input.retrieval.totalEstimatedTokens,
+            tokenCountMethod: input.retrieval.tokenCountMethod
+        }
+    });
+}
+/**
+ * Single mathematical owner for retrieval-quality calculation. Applies the v0.8.0 formulas and availability
+ * semantics to already-normalized identity evidence, so any evidence contract can be scored identically.
+ */
+export function calculateRetrievalQualityMetricsFromIdentityEvidence(input) {
+    const { evaluationCase, retrieval } = input;
+    const evidence = retrieval.identityEvidence;
+    const evidenceBlocked = evidenceReason(evidence);
+    const answerKey = evaluationCase.answerKey;
+    const hasAnswerKey = answerKey !== undefined && answerKey !== null && typeof answerKey === "object";
+    const expectedFiles = resolveExpectation(evaluationCase.expectedFiles, hasAnswerKey ? answerKey.expectedFiles : undefined, hasAnswerKey, normalizeExpectedFiles, "expected-files-answer-key-mismatch");
+    const expectedSymbols = resolveExpectation(evaluationCase.expectedSymbols, hasAnswerKey ? answerKey.expectedSymbols : undefined, hasAnswerKey, normalizeExpectedSymbols, "expected-symbols-answer-key-mismatch");
+    const usable = evidenceBlocked === null && evidence !== undefined ? evidence : undefined;
+    const retrievedFiles = usable ? sortedUnique(usable.files) : undefined;
+    const retrievedSymbols = usable ? sortedUnique(usable.symbols.map((symbol) => symbol.name)) : undefined;
+    // ---- files
+    let file = {
+        relevantRetrievedFiles: null,
+        irrelevantRetrievedFiles: null,
+        missedFiles: null,
+        missedFileCount: null,
+        precision: unavailableRatio(evidenceBlocked ?? (expectedFiles.ok ? "unavailable" : expectedFiles.reason)),
+        recall: unavailableRatio(evidenceBlocked ?? (expectedFiles.ok ? "unavailable" : expectedFiles.reason))
+    };
+    let irrelevantContextRatio = unavailableRatio(evidenceBlocked ?? (expectedFiles.ok ? "unavailable" : expectedFiles.reason));
+    if (retrievedFiles !== undefined && expectedFiles.ok) {
+        const expected = new Set(expectedFiles.values);
+        const retrieved = new Set(retrievedFiles);
+        const relevant = retrievedFiles.filter((path) => expected.has(path));
+        const irrelevant = retrievedFiles.filter((path) => !expected.has(path));
+        const missed = expectedFiles.values.filter((path) => !retrieved.has(path));
+        file = {
+            relevantRetrievedFiles: relevant,
+            irrelevantRetrievedFiles: irrelevant,
+            missedFiles: missed,
+            missedFileCount: missed.length,
+            precision: ratio(relevant.length, retrievedFiles.length, "no-retrieved-files"),
+            recall: ratio(relevant.length, expectedFiles.values.length, "no-expected-files")
+        };
+        irrelevantContextRatio = ratio(irrelevant.length, retrievedFiles.length, "no-retrieved-files");
+    }
+    // ---- symbols (exact unique names)
+    let symbol = {
+        relevantRetrievedSymbols: null,
+        irrelevantRetrievedSymbols: null,
+        missedSymbols: null,
+        missedSymbolCount: null,
+        precision: unavailableRatio(evidenceBlocked ?? (expectedSymbols.ok ? "unavailable" : expectedSymbols.reason)),
+        recall: unavailableRatio(evidenceBlocked ?? (expectedSymbols.ok ? "unavailable" : expectedSymbols.reason))
+    };
+    if (retrievedSymbols !== undefined && expectedSymbols.ok) {
+        const expected = new Set(expectedSymbols.values);
+        const retrieved = new Set(retrievedSymbols);
+        const relevant = retrievedSymbols.filter((name) => expected.has(name));
+        const missed = expectedSymbols.values.filter((name) => !retrieved.has(name));
+        symbol = {
+            relevantRetrievedSymbols: relevant,
+            irrelevantRetrievedSymbols: retrievedSymbols.filter((name) => !expected.has(name)),
+            missedSymbols: missed,
+            missedSymbolCount: missed.length,
+            precision: ratio(relevant.length, retrievedSymbols.length, "no-retrieved-symbols"),
+            recall: ratio(relevant.length, expectedSymbols.values.length, "no-expected-symbols")
+        };
+    }
+    // ---- facts
+    let fact = {
+        coveredFactIds: null,
+        uncoveredFactIds: null,
+        uncoveredFactCount: null,
+        coverage: unavailableRatio(evidenceBlocked ?? "unavailable")
+    };
+    if (usable !== undefined && retrievedFiles !== undefined) {
+        const outcome = calculateFactCoverage(answerKey, usable, new Set(retrievedFiles));
+        if (outcome.kind === "computed") {
+            fact = {
+                coveredFactIds: outcome.covered,
+                uncoveredFactIds: outcome.uncovered,
+                uncoveredFactCount: outcome.uncovered.length,
+                coverage: ratio(outcome.covered.length, outcome.total, "no-expected-facts")
+            };
+        }
+        else {
+            fact = { ...fact, coverage: outcome.kind === "unavailable" ? unavailableRatio(outcome.reason) : { availability: "not-applicable", numerator: null, denominator: null, value: null, reason: outcome.reason } };
+        }
+    }
+    const tokensValid = typeof retrieval.totalEstimatedTokens === "number" && Number.isFinite(retrieval.totalEstimatedTokens) && retrieval.totalEstimatedTokens >= 0;
+    return {
+        schemaVersion: "retrieval-quality-metrics-v1",
+        caseId: evaluationCase.id,
+        evidence: {
+            availability: evidence === undefined ? "missing" : evidence.availability,
+            reason: evidence === undefined ? "retrieval-evidence-missing" : (evidence.availabilityReason ?? null)
+        },
+        expectations: { files: expectationStatus(expectedFiles), symbols: expectationStatus(expectedSymbols) },
+        file,
+        symbol,
+        fact,
+        irrelevantContextRatio,
+        retrievedTokenCount: tokensValid ? retrieval.totalEstimatedTokens : null,
+        tokenCountMethod: tokensValid && typeof retrieval.tokenCountMethod === "string" ? retrieval.tokenCountMethod : null
+    };
+}

package/dist/src/evaluation/retrievalQuality/types.js

@@ -0,0 +1,9 @@
+/**
+ * Normalized retrieval-evidence contract (V1).
+ *
+ * Describes which files and symbols the existing my-dev-kit search -> lookup -> slice -> source
+ * lifecycle actually surfaced. It is observation only: it carries no relevance judgement and no
+ * score. It deliberately contains no source text, stdout/stderr bodies, or machine-local paths.
+ */
+/** Retrieval command families in fixed lifecycle order. */
+export const RETRIEVAL_COMMAND_FAMILIES = ["search", "lookup", "slice", "source"];

package/dist/src/evaluation/retrievalQueryStrategies.js

@@ -0,0 +1,26 @@
+export const RETRIEVAL_QUERY_STRATEGY_IDS = [
+    "keyword-search",
+    "symbol-lookup",
+    "graph-neighborhood",
+    "source-slice",
+    "data-model-graph",
+    "model-view-lineage",
+    "combined-graph-guided"
+];
+export const CORE_GRAPH_RETRIEVAL_QUERY_STRATEGY_IDS = [
+    "keyword-search",
+    "symbol-lookup",
+    "graph-neighborhood",
+    "source-slice",
+    "combined-graph-guided"
+];
+export function isCoreGraphRetrievalQueryStrategyId(value) {
+    return CORE_GRAPH_RETRIEVAL_QUERY_STRATEGY_IDS.includes(value);
+}
+export const SEMANTIC_RETRIEVAL_QUERY_STRATEGY_IDS = [
+    "data-model-graph",
+    "model-view-lineage"
+];
+export function isSemanticRetrievalQueryStrategyId(value) {
+    return SEMANTIC_RETRIEVAL_QUERY_STRATEGY_IDS.includes(value);
+}

package/dist/src/evaluation/retrievalQueryStrategyEvidence.js

@@ -0,0 +1,58 @@
+/**
+ * Strategy-neutral retrieval identity evidence (V1).
+ *
+ * Additive to `retrieval-evidence-v1`, which is frozen to the search/lookup/slice/source command
+ * families. This contract records only which file and symbol identities a query strategy exposed and
+ * which steps ran. It carries no relevance judgement, score, answer-key data, source text,
+ * stdout/stderr, or machine-local paths.
+ */
+import { compareCodeUnits } from "./indexSnapshot.js";
+/**
+ * Deduplicates and canonically orders identities. Files are keyed by path; symbols by `nodeId` when
+ * present, otherwise by `file + NUL + name`. Ordering is code-unit order, never locale-sensitive.
+ */
+export function canonicalizeQueryStrategyIdentities(files, symbols) {
+    const fileByPath = new Map();
+    for (const file of files) {
+        if (!fileByPath.has(file.path))
+            fileByPath.set(file.path, { path: file.path });
+    }
+    const symbolByKey = new Map();
+    for (const symbol of symbols) {
+        const key = symbol.nodeId !== null ? symbol.nodeId : `${symbol.file ?? ""}\0${symbol.name}`;
+        if (!symbolByKey.has(key)) {
+            symbolByKey.set(key, { name: symbol.name, nodeId: symbol.nodeId, file: symbol.file });
+        }
+    }
+    return {
+        files: [...fileByPath.values()].sort((a, b) => compareCodeUnits(a.path, b.path)),
+        symbols: [...symbolByKey.values()].sort((a, b) => compareCodeUnits(a.file ?? "", b.file ?? "") ||
+            compareCodeUnits(a.name, b.name) ||
+            compareCodeUnits(a.nodeId ?? "", b.nodeId ?? ""))
+    };
+}
+/**
+ * Converts an already-normalized `retrieval-evidence-v1` observation into the strategy-neutral
+ * contract. It recalculates no identity, parses no stdout, and does not reinterpret availability.
+ */
+export function buildQueryStrategyEvidenceFromRetrievalEvidence(strategyId, evidence) {
+    return {
+        schemaVersion: "retrieval-query-strategy-evidence-v1",
+        strategyId,
+        availability: evidence.availability,
+        availabilityReason: evidence.availabilityReason ?? null,
+        files: evidence.files.map(({ path }) => ({ path })),
+        symbols: evidence.symbols.map((symbol) => ({
+            name: symbol.name,
+            nodeId: symbol.nodeId ?? null,
+            file: symbol.file ?? null
+        })),
+        steps: evidence.commands.map((command) => ({
+            kind: command.family,
+            succeeded: command.succeeded,
+            evidenceAvailable: (command.parseState === "parsed" || command.parseState === "selection-attributed") &&
+                command.rejectedIdentityCount === 0,
+            reason: command.reason ?? null
+        }))
+    };
+}

package/dist/src/evaluation/runMyDevKitRetrieval.js

@@ -2,6 +2,8 @@ import path from "node:path";
 import { countEstimatedTokens, countTextChars, tokenCountMethod } from "../core/countTokens.js";
 import { runMeasuredCommand } from "../core/runMeasuredCommand.js";
 import { interpretToolVersionOutput } from "./indexSnapshot.js";
+import { buildRetrievalEvidenceFromCommands } from "./retrievalQuality/buildRetrievalEvidence.js";
+import { buildQueryStrategyEvidenceFromRetrievalEvidence } from "./retrievalQueryStrategyEvidence.js";
 const VERSION_PROBE_TIMEOUT_MS = 30_000;
 function parseJsonIfPossible(text) {
     try {
@@ -52,6 +54,7 @@ function skippedRetrieval(caseId, warnings, commands, durationMs) {
         contextText: "",
         filesRead: [],
         commands,
+        retrievalEvidence: buildRetrievalEvidenceFromCommands(commands),
         durationMs
     };
 }
@@ -237,11 +240,31 @@ export async function probeMyDevKitVersion(options) {
         });
     }
 }
+function selectRetrievalStrategyContextText(strategyId, outputs) {
+    const ordered = strategyId === "keyword-search"
+        ? [outputs.search]
+        : strategyId === "symbol-lookup"
+            ? [outputs.lookup, outputs.search]
+            : strategyId === "graph-neighborhood"
+                ? [outputs.slice, outputs.search]
+                : strategyId === "source-slice"
+                    ? [outputs.source, outputs.search]
+                    : [outputs.source, outputs.slice, outputs.lookup, outputs.search];
+    return ordered.find((text) => text && text.trim().length > 0) ?? "";
+}
+const STRATEGY_DOWNSTREAM_COMMANDS = {
+    "keyword-search": [],
+    "symbol-lookup": ["lookup"],
+    "graph-neighborhood": ["slice"],
+    "source-slice": ["source"],
+    "combined-graph-guided": ["lookup", "slice", "source"]
+};
 /**
- * Runs search -> lookup -> slice -> source against an already prepared index. Never invokes
- * `index`; `durationMs` covers retrieval only.
+ * Executes exactly one core retrieval query strategy against an already prepared index. Every
+ * strategy starts with `search` and expands at most the first candidate. Never invokes `index`;
+ * `durationMs` covers retrieval only.
  */
-export async function runMyDevKitRetrievalFromIndex(options) {
+export async function runMyDevKitRetrievalStrategyFromIndex(options) {
     const started = Date.now();
     const warnings = [];
     const commands = [];
@@ -272,58 +295,37 @@ export async function runMyDevKitRetrievalFromIndex(options) {
     const selectedNodeId = candidate.nodeId;
     const selectedFile = candidate.file;
     const selectedSymbol = candidate.symbol;
-    let lookupOutput = "";
-    let sliceOutput = "";
-    let sourceOutput = "";
-    if (selectedNodeId) {
-        const lookupCommand = await runMeasuredCommand({
-            commandId: "lookup",
-            commandString: options.kitCommand,
-            cwd: process.cwd(),
-            outDir: commandsDir,
-            extraArgs: ["lookup", "--index", indexDir, "--node", selectedNodeId, "--json"]
-        });
-        commands.push(lookupCommand);
-        if (lookupCommand.ok) {
-            lookupOutput = lookupCommand.stdout;
-        }
-        else {
-            warnings.push("my-dev-kit lookup command failed.");
-        }
-        const sliceCommand = await runMeasuredCommand({
-            commandId: "slice",
-            commandString: options.kitCommand,
-            cwd: process.cwd(),
-            outDir: commandsDir,
-            extraArgs: ["slice", "--index", indexDir, "--node", selectedNodeId, "--json"]
-        });
-        commands.push(sliceCommand);
-        if (sliceCommand.ok) {
-            sliceOutput = sliceCommand.stdout;
-        }
-        else {
-            warnings.push("my-dev-kit slice command failed.");
-        }
-        const sourceCommand = await runMeasuredCommand({
-            commandId: "source",
-            commandString: options.kitCommand,
-            cwd: process.cwd(),
-            outDir: commandsDir,
-            extraArgs: ["source", "--index", indexDir, "--node", selectedNodeId, "--max-lines", "160", "--format", "numbered"]
-        });
-        commands.push(sourceCommand);
-        if (sourceCommand.ok) {
-            sourceOutput = sourceCommand.stdout;
+    const outputs = { search: searchCommand.stdout, lookup: "", slice: "", source: "" };
+    const downstream = STRATEGY_DOWNSTREAM_COMMANDS[options.strategyId];
+    if (downstream.length > 0) {
+        if (selectedNodeId) {
+            for (const commandId of downstream) {
+                const extraArgs = commandId === "source"
+                    ? ["source", "--index", indexDir, "--node", selectedNodeId, "--max-lines", "160", "--format", "numbered"]
+                    : [commandId, "--index", indexDir, "--node", selectedNodeId, "--json"];
+                const command = await runMeasuredCommand({
+                    commandId,
+                    commandString: options.kitCommand,
+                    cwd: process.cwd(),
+                    outDir: commandsDir,
+                    extraArgs
+                });
+                commands.push(command);
+                if (command.ok) {
+                    outputs[commandId] = command.stdout;
+                }
+                else {
+                    warnings.push(`my-dev-kit ${commandId} command failed.`);
+                }
+            }
         }
         else {
-            warnings.push("my-dev-kit source command failed.");
+            warnings.push("No my-dev-kit node id was available after search.");
         }
     }
-    else {
-        warnings.push("No my-dev-kit node id was available after search.");
-    }
-    const contextText = [sourceOutput, sliceOutput, lookupOutput, searchCommand.stdout].find((text) => text && text.trim().length > 0) ?? "";
+    const contextText = selectRetrievalStrategyContextText(options.strategyId, outputs);
     const filesRead = selectedFile ? [selectedFile] : [];
+    const retrievalEvidence = buildRetrievalEvidenceFromCommands(commands, { nodeId: selectedNodeId, file: selectedFile });
     return {
         caseId: options.evaluationCase.id,
         skipped: contextText.length === 0,
@@ -337,9 +339,18 @@ export async function runMyDevKitRetrievalFromIndex(options) {
         selectedNodeId,
         selectedFile,
         selectedSymbol,
+        retrievalEvidence,
+        queryStrategyEvidence: buildQueryStrategyEvidenceFromRetrievalEvidence(options.strategyId, retrievalEvidence),
         durationMs: Date.now() - started
     };
 }
+/**
+ * v0.8.0 compatibility entrypoint: the historical search -> lookup -> slice -> source lifecycle,
+ * delegating to the `combined-graph-guided` strategy. Never invokes `index`.
+ */
+export async function runMyDevKitRetrievalFromIndex(options) {
+    return runMyDevKitRetrievalStrategyFromIndex({ ...options, strategyId: "combined-graph-guided" });
+}
 /**
  * Legacy per-case lifecycle: builds a case-specific index and retrieves from it. `commands`
  * starts with the index command and `durationMs` covers the whole lifecycle including indexing.