sdl-mcp 0.11.2 → 0.11.4

package/dist/agent/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/agent/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAoBV,MAAM,EACN,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACT,MAAM,YAAY,CAAC;AAcpB,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACX,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,4BAA4B,CAAC;AAEpC,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,KACnD,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAuBlC,CAAC;AA0CF;;;GAGG;AACH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,GAC3B,CAAC;AAEF,qBAAa,QAAQ;IACnB,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,SAAS,CAAK;IAEtB,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,WAAW,CAAkD;IACrE,OAAO,CAAC,SAAS,CAAqB;gBAE1B,aAAa,CAAC,EAAE,aAAa;IAczC,OAAO,CAAC,OAAO;IAOT,OAAO,CACX,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,EAAE,QAAQ,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IAgGF,OAAO,CAAC,qBAAqB;YAYf,WAAW;IA0CzB;;;OAGG;YACW,kBAAkB;IAyDhC;;;OAGG;YACW,uBAAuB;IAqBrC;;;OAGG;YACW,gBAAgB;YAyBhB,eAAe;YAsNf,mBAAmB;YA+FnB,kBAAkB;YAsElB,cAAc;IAuG5B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAkBlC,OAAO,CAAC,gBAAgB;IAIxB;;;;OAIG;IACH,UAAU,IAAI,gBAAgB;IAI9B,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAgBvC,KAAK,IAAI,IAAI;CAkBd"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/agent/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAoBV,MAAM,EACN,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACR,oBAAoB,EACrB,MAAM,YAAY,CAAC;AASpB,OAAO,KAAK,SAAS,MAAM,0BAA0B,CAAC;AAMtD,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACX,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,4BAA4B,CAAC;AAEpC,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,KACnD,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjC,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,OAAO,SAAS,EACd,mBAAmB,GACnB,oBAAoB,GACpB,kBAAkB,GAClB,kBAAkB,GAClB,mBAAmB,GACnB,sBAAsB,GACtB,iBAAiB,GACjB,eAAe,CAClB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAuBlC,CAAC;AA2CF;;;GAGG;AACH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,GAC3B,CAAC;AAEF,qBAAa,QAAQ;IACnB,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,SAAS,CAAK;IAEtB,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,WAAW,CAAkD;IACrE,OAAO,CAAC,SAAS,CAAoB;IAErC,OAAO,CAAC,SAAS,CAAqB;gBAGpC,aAAa,CAAC,EAAE,aAAa,EAC7B,SAAS,GAAE,iBAA6B;IAgB1C,OAAO,CAAC,OAAO;IAOT,OAAO,CACX,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,EAAE,MAAM,EAAE,EACjB,cAAc,GAAE,oBAAoB,EAAO,GAC1C,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,EAAE,QAAQ,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IAgGF,OAAO,CAAC,qBAAqB;YAYf,WAAW;IA2CzB;;;OAGG;YACW,kBAAkB;IAwDhC;;;;;;OAMG;YACW,uBAAuB;IA0KrC;;;OAGG;YACW,gBAAgB;IA6C9B,OAAO,CAAC,uBAAuB;YAuDjB,yBAAyB;IA0DvC,OAAO,CAAC,sBAAsB;YAmBhB,eAAe;YA+Of,mBAAmB;YAuHnB,kBAAkB;YA2FlB,cAAc;IAuG5B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAkBlC,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,0BAA0B;IAsBlC,OAAO,CAAC,6BAA6B;IAOrC,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,gBAAgB;IAIxB;;;;OAIG;IACH,UAAU,IAAI,gBAAgB;IAI9B,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAgBvC,KAAK,IAAI,IAAI;CAkBd"}

package/dist/agent/executor.js

@@ -60,6 +60,7 @@ const MAX_HOTPATH_SYMBOLS = 5;
 const MAX_RAW_SYMBOLS = 3;
 const MAX_SEARCH_FALLBACK = 10;
 const MAX_ESCALATIONS = 2;
+const GENERIC_FILE_BASENAMES = new Set(["engine", "index", "types"]);
 /** Map rung types to action type strings for error reporting. */
 const RUNG_TO_ACTION_TYPE = {
     card: "getCard",
@@ -90,10 +91,12 @@ export class Executor {
     policyDecisions = new Map();
     gateEvaluator;
     connPromise = null;
+    dbQueries;
     cardCache = new Set();
-    constructor(gateEvaluator) {
+    constructor(gateEvaluator, dbQueries = ladybugDb) {
         this.evidenceCapture = new EvidenceCapture();
         this.gateEvaluator = gateEvaluator ?? defaultGateEvaluator;
+        this.dbQueries = dbQueries;
         this.metrics = {
             totalDurationMs: 0,
             totalTokens: 0,
@@ -109,14 +112,14 @@ export class Executor {
         }
         return this.connPromise;
     }
-    async execute(task, rungs, context) {
+    async execute(task, rungs, context, seedCandidates = []) {
         this.startTime = Date.now();
         const mutableRungs = [...rungs];
         let escalationCount = 0;
         for (let i = 0; i < mutableRungs.length; i++) {
             const rung = mutableRungs[i];
             const evidenceBefore = this.evidenceCapture.getAllEvidence().length;
-            await this.executeRung(task, rung, context);
+            await this.executeRung(task, rung, context, seedCandidates);
             // Track tokens: use actual evidence-based count when available,
             // fall back to static estimates otherwise
             const rungEvidence = this.evidenceCapture.getAllEvidence();
@@ -191,17 +194,17 @@ export class Executor {
         const next = RUNG_ESCALATION_ORDER[currentIndex + 1];
         return existingRungs.includes(next) ? undefined : next;
     }
-    async executeRung(task, rung, context) {
+    async executeRung(task, rung, context, seedCandidates) {
         try {
             switch (rung) {
                 case "card":
-                    await this.executeCardRung(task, context);
+                    await this.executeCardRung(task, context, seedCandidates);
                     break;
                 case "skeleton":
-                    await this.executeSkeletonRung(task, context);
+                    await this.executeSkeletonRung(task, context, seedCandidates);
                     break;
                 case "hotPath":
-                    await this.executeHotPathRung(task, context);
+                    await this.executeHotPathRung(task, context, seedCandidates);
                     break;
                 case "raw":
                     await this.executeRawRung(task, context);
@@ -239,12 +242,10 @@ export class Executor {
         for (const relPath of filePaths) {
             try {
                 // Try exact file match first
-                const file = await ladybugDb.getFileByRepoPath(conn, repoId, relPath);
+                const file = await this.dbQueries.getFileByRepoPath(conn, repoId, relPath);
                 if (file) {
-                    const symbols = await ladybugDb.getSymbolsByFile(conn, file.fileId);
-                    const behavioral = symbols.filter((s) => BEHAVIORAL_KINDS.has(s.kind));
-                    const preferred = behavioral.length > 0 ? behavioral : symbols;
-                    results.push(preferred.slice(0, 50).map((sym) => sym.symbolId));
+                    const symbolIds = await this.dbQueries.getSymbolIdsByFile(conn, file.fileId);
+                    results.push(symbolIds.slice(0, 5));
                     continue;
                 }
                 // If exact match fails, treat as directory prefix and find files under it.
@@ -252,11 +253,11 @@ export class Executor {
                 const normalizedPrefix = relPath.endsWith("/")
                     ? relPath
                     : relPath + "/";
-                const filesUnderDir = await ladybugDb.getFilesByPrefix(conn, repoId, normalizedPrefix);
+                const filesUnderDir = await this.dbQueries.getFilesByPrefix(conn, repoId, normalizedPrefix);
                 if (filesUnderDir.length > 0) {
                     const symbolResults = [];
                     for (const f of filesUnderDir.slice(0, 10)) {
-                        const symbols = await ladybugDb.getSymbolsByFile(conn, f.fileId);
+                        const symbols = await this.dbQueries.getSymbolsByFile(conn, f.fileId);
                         const beh = symbols.filter((s) => BEHAVIORAL_KINDS.has(s.kind));
                         symbolResults.push((beh.length > 0 ? beh : symbols)
                             .slice(0, 5)
@@ -277,48 +278,270 @@ export class Executor {
         return results.flat();
     }
     /**
-     * Extract symbol IDs and file paths from context entries,
-     * resolving file: entries to their constituent symbol IDs.
+     * Extract symbol IDs and file paths from context entries.
+     *
+     * Non-symbol retrieval entities are expanded into representative symbols and
+     * carry their original seed score forward so final ranking can still use the
+     * retrieval prior that found the entity.
      */
-    async resolveContextToSymbols(context, repoId) {
+    async resolveContextToSymbols(context, task, seedCandidates = []) {
+        const repoId = task.repoId;
         const directSymbols = context
             .filter((c) => c.startsWith("symbol:"))
             .map((s) => s.slice("symbol:".length));
         const filePaths = context
             .filter((c) => c.startsWith("file:"))
             .map((f) => f.slice("file:".length));
+        const fileSummaryIds = context
+            .filter((c) => c.startsWith("fileSummary:"))
+            .map((f) => f.slice("fileSummary:".length));
+        const clusterIds = context
+            .filter((c) => c.startsWith("cluster:"))
+            .map((c) => c.slice("cluster:".length));
+        const processIds = context
+            .filter((c) => c.startsWith("process:"))
+            .map((p) => p.slice("process:".length));
         let resolvedSymbols = [];
         if (filePaths.length > 0) {
             resolvedSymbols = await this.resolveFileSymbols(filePaths, repoId);
         }
+        const seedByRef = new Map(seedCandidates.map((c) => [c.contextRef, c]));
+        const expandedSeedCandidates = seedCandidates.filter((c) => c.contextRef.startsWith("symbol:"));
+        const expandedRefs = new Set(expandedSeedCandidates.map((c) => c.contextRef));
+        for (const [index, symbolId] of directSymbols.entries()) {
+            const symbolRef = `symbol:${symbolId}`;
+            if (expandedRefs.has(symbolRef))
+                continue;
+            expandedRefs.add(symbolRef);
+            expandedSeedCandidates.push({
+                contextRef: symbolRef,
+                source: "lexical",
+                score: 1,
+                sourceRank: -1000 + index,
+                entityType: "symbol",
+                expansionReason: "directContext",
+            });
+        }
+        const addExpandedSeed = (symbolId, sourceRef, index, scoreScale, expansionReason) => {
+            const source = seedByRef.get(sourceRef);
+            if (!source)
+                return;
+            const symbolRef = `symbol:${symbolId}`;
+            if (expandedRefs.has(symbolRef))
+                return;
+            expandedRefs.add(symbolRef);
+            expandedSeedCandidates.push({
+                ...source,
+                contextRef: symbolRef,
+                entityType: "symbol",
+                expandedFrom: sourceRef,
+                expansionReason,
+                score: Math.max(0, Math.min(1, source.score * scoreScale)),
+                sourceRank: source.sourceRank + index + 1,
+            });
+        };
+        if (fileSummaryIds.length > 0 || clusterIds.length > 0 || processIds.length > 0) {
+            const conn = await this.getConn();
+            const identifiers = this.extractIdentifiersFromTask(task);
+            const rankExpandedFileSymbols = (fileId, symbols) => {
+                if (symbols.length === 0)
+                    return [];
+                const source = seedByRef.get(`fileSummary:${fileId}`);
+                const symbolIds = symbols.map((symbol) => symbol.symbolId);
+                if (identifiers.length === 0 || !source) {
+                    return symbolIds.slice(0, 8);
+                }
+                const symbolMap = new Map(symbols.map((symbol) => [symbol.symbolId, symbol]));
+                const fileSeedCandidates = symbols.map((symbol, index) => ({
+                    ...source,
+                    contextRef: `symbol:${symbol.symbolId}`,
+                    entityType: "symbol",
+                    expandedFrom: `fileSummary:${fileId}`,
+                    expansionReason: "fileSummary",
+                    score: Math.max(0, Math.min(1, source.score * 0.92)),
+                    sourceRank: source.sourceRank + index + 1,
+                }));
+                return rankSymbols(symbolIds, symbolMap, identifiers, task, {
+                    seedCandidates: fileSeedCandidates,
+                    anchorSymbolIds: directSymbols,
+                })
+                    .ranked.slice(0, 8)
+                    .map((ranked) => ranked.symbolId);
+            };
+            for (const fileId of fileSummaryIds.slice(0, 8)) {
+                const symbols = await this.dbQueries.getSymbolsByFile(conn, fileId);
+                const symbolIds = rankExpandedFileSymbols(fileId, symbols);
+                resolvedSymbols.push(...symbolIds);
+                symbolIds.forEach((symbolId, index) => addExpandedSeed(symbolId, `fileSummary:${fileId}`, index, 0.92, "fileSummary"));
+            }
+            for (const clusterId of clusterIds.slice(0, 8)) {
+                const members = (await this.dbQueries.getClusterMembers(conn, clusterId))
+                    .sort((a, b) => b.membershipScore - a.membershipScore)
+                    .slice(0, 8);
+                resolvedSymbols.push(...members.map((m) => m.symbolId));
+                members.forEach((member, index) => addExpandedSeed(member.symbolId, `cluster:${clusterId}`, index, 0.86, "clusterMember"));
+            }
+            if (processIds.length > 0) {
+                const wantedProcesses = new Set(processIds.slice(0, 8));
+                const steps = (await this.dbQueries.getProcessStepsByIds(conn, repoId, [...wantedProcesses]))
+                    .filter((step) => wantedProcesses.has(step.processId))
+                    .sort((a, b) => a.stepOrder - b.stepOrder);
+                const countByProcess = new Map();
+                for (const step of steps) {
+                    const count = countByProcess.get(step.processId) ?? 0;
+                    if (count >= 8)
+                        continue;
+                    countByProcess.set(step.processId, count + 1);
+                    resolvedSymbols.push(step.symbolId);
+                    addExpandedSeed(step.symbolId, `process:${step.processId}`, count, 0.88, "processStep");
+                }
+            }
+        }
         const symbolIds = [...new Set([...directSymbols, ...resolvedSymbols])];
-        return { symbolIds, filePaths };
+        return { symbolIds, filePaths, seedCandidates: expandedSeedCandidates };
     }
     /**
      * Select the top symbols based on multi-factor ranking with adaptive cutoff.
      * Delegates scoring to context-ranking.ts for evidence-aware symbol selection.
      */
-    async selectTopSymbols(symbolIds, task, maxCount) {
+    async selectTopSymbols(symbolIds, task, maxCount, seedCandidates = []) {
         if (!task.taskText || symbolIds.length === 0) {
             return symbolIds.slice(0, maxCount);
         }
         const identifiers = this.extractIdentifiersFromTask(task);
-        if (identifiers.length === 0)
+        if (identifiers.length === 0 && seedCandidates.length === 0) {
             return symbolIds.slice(0, maxCount);
+        }
         const conn = await this.getConn();
-        const symbolMap = await ladybugDb.getSymbolsByIds(conn, symbolIds);
-        const ranking = rankSymbols(symbolIds, symbolMap, identifiers, task);
+        const symbolMap = await this.dbQueries.getSymbolsByIds(conn, symbolIds);
+        const anchorSymbolIds = seedCandidates
+            .map((candidate) => candidate.contextRef.startsWith("symbol:")
+            ? candidate.contextRef.slice("symbol:".length)
+            : undefined)
+            .filter((symbolId) => !!symbolId);
+        const ranking = rankSymbols(symbolIds, symbolMap, identifiers, task, {
+            seedCandidates,
+            anchorSymbolIds,
+        });
         const isPrecise = task.options?.contextMode === "precise";
         const hasScope = !!(task.options?.focusPaths?.length || task.options?.focusSymbols?.length);
-        return applyAdaptiveCutoff(ranking, maxCount, isPrecise, hasScope);
+        const selected = applyAdaptiveCutoff(ranking, maxCount, isPrecise, hasScope);
+        return this.ensureFocusPathCoverage(selected, ranking.ranked.map((ranked) => ranked.symbolId), symbolMap, task.options?.inferredFocusPaths ?? [], maxCount);
     }
-    async executeCardRung(task, context) {
+    ensureFocusPathCoverage(selected, rankedSymbolIds, symbolMap, focusPaths, maxCount) {
+        if (focusPaths.length === 0 || selected.length === 0)
+            return selected;
+        const selectedSet = new Set(selected);
+        const additions = [];
+        const perPathLimit = focusPaths.some((path) => path.split("/").pop()?.includes("."))
+            ? 4
+            : 2;
+        for (const focusPath of focusPaths) {
+            let addedForPath = 0;
+            for (const symbolId of rankedSymbolIds) {
+                if (selectedSet.has(symbolId))
+                    continue;
+                const symbol = symbolMap.get(symbolId);
+                if (!this.symbolMatchesFocusPath(symbol, focusPath))
+                    continue;
+                selectedSet.add(symbolId);
+                additions.push(symbolId);
+                addedForPath++;
+                if (addedForPath >= perPathLimit)
+                    break;
+            }
+        }
+        if (additions.length === 0)
+            return selected;
+        const focusSet = new Set();
+        for (const symbolId of rankedSymbolIds) {
+            const symbol = symbolMap.get(symbolId);
+            if (focusPaths.some((focusPath) => this.symbolMatchesFocusPath(symbol, focusPath))) {
+                focusSet.add(symbolId);
+            }
+        }
+        const merged = [...selected];
+        for (const symbolId of additions) {
+            if (merged.length < maxCount) {
+                merged.push(symbolId);
+                continue;
+            }
+            const replaceIndex = merged.findLastIndex((existing) => !focusSet.has(existing));
+            if (replaceIndex < 0)
+                break;
+            merged[replaceIndex] = symbolId;
+        }
+        return merged;
+    }
+    async buildRelatedSymbolNameMap(conn, selectedSymbols, task) {
+        const shouldSurfaceRelated = task.options?.semantic === true ||
+            (task.options?.inferredFocusPaths?.length ?? 0) > 0;
+        if (!shouldSurfaceRelated || selectedSymbols.length === 0) {
+            return new Map();
+        }
+        const inferredFocusPaths = task.options?.inferredFocusPaths ?? [];
+        const identifiers = this.extractIdentifiersFromTask(task);
+        const selectedByFile = new Map();
+        for (const symbol of selectedSymbols) {
+            if (!symbol.fileId)
+                continue;
+            if (inferredFocusPaths.length > 0 &&
+                !inferredFocusPaths.some((focusPath) => this.symbolMatchesFocusPath(symbol, focusPath))) {
+                continue;
+            }
+            if (!selectedByFile.has(symbol.fileId)) {
+                selectedByFile.set(symbol.fileId, new Set());
+            }
+            selectedByFile.get(symbol.fileId).add(symbol.symbolId);
+            if (selectedByFile.size >= 6)
+                break;
+        }
+        const relatedByFile = new Map();
+        for (const [fileId, selectedIds] of selectedByFile) {
+            const fileSymbols = await this.dbQueries.getSymbolsByFile(conn, fileId);
+            if (fileSymbols.length === 0)
+                continue;
+            const symbolIds = fileSymbols.map((symbol) => symbol.symbolId);
+            const fileSymbolMap = new Map(fileSymbols.map((symbol) => [symbol.symbolId, symbol]));
+            const ranking = rankSymbols(symbolIds, fileSymbolMap, identifiers, task);
+            const names = [];
+            const seenNames = new Set();
+            for (const ranked of ranking.ranked) {
+                if (selectedIds.has(ranked.symbolId))
+                    continue;
+                const symbol = fileSymbolMap.get(ranked.symbolId);
+                if (!symbol || seenNames.has(symbol.name))
+                    continue;
+                seenNames.add(symbol.name);
+                names.push(symbol.name);
+                if (names.length >= 14)
+                    break;
+            }
+            if (names.length > 0) {
+                relatedByFile.set(fileId, names);
+            }
+        }
+        return relatedByFile;
+    }
+    symbolMatchesFocusPath(symbol, focusPath) {
+        const fileId = symbol?.fileId;
+        if (!fileId)
+            return false;
+        const relPath = fileId.includes(":")
+            ? fileId.slice(fileId.indexOf(":") + 1)
+            : fileId;
+        const normalizedRelPath = relPath.replace(/\\/g, "/").toLowerCase();
+        const normalizedFocus = focusPath.replace(/\\/g, "/").toLowerCase();
+        return (normalizedRelPath === normalizedFocus ||
+            normalizedRelPath.startsWith(normalizedFocus.endsWith("/") ? normalizedFocus : `${normalizedFocus}/`));
+    }
+    async executeCardRung(task, context, seedCandidates) {
         const actionId = this.generateActionId();
         const startTime = Date.now();
         try {
-            const { symbolIds: rawSymbols } = await this.resolveContextToSymbols(context, task.repoId);
+            const { symbolIds: rawSymbols, seedCandidates: expandedSeedCandidates } = await this.resolveContextToSymbols(context, task, seedCandidates);
             let allSymbols = rawSymbols.length > 0 && task.taskText
-                ? await this.selectTopSymbols(rawSymbols, task, MAX_CARD_SYMBOLS)
+                ? await this.selectTopSymbols(rawSymbols, task, MAX_CARD_SYMBOLS, expandedSeedCandidates)
                 : rawSymbols.slice(0, MAX_CARD_SYMBOLS);
             // Fallback: identifier-based search with per-term resolution
             if (allSymbols.length === 0 && task.taskText) {
@@ -331,7 +554,8 @@ export class Executor {
                     ? task.options.searchTerms.slice(0, maxTerms)
                     : this.extractIdentifiersFromTask(task).slice(0, maxTerms);
                 const seen = new Set();
-                const useHybrid = await isHybridRetrievalAvailable();
+                const useHybrid = task.options?.semantic !== false &&
+                    (await isHybridRetrievalAvailable());
                 // 2. Search for each identifier individually and combine results
                 for (const term of searchTerms) {
                     if (useHybrid) {
@@ -350,7 +574,7 @@ export class Executor {
                     }
                     else {
                         const conn = await this.getConn();
-                        const searchResults = await ladybugDb.searchSymbols(conn, task.repoId, term, Math.ceil(searchFallbackLimit / Math.max(searchTerms.length, 1)));
+                        const searchResults = await this.dbQueries.searchSymbols(conn, task.repoId, term, Math.ceil(searchFallbackLimit / Math.max(searchTerms.length, 1)));
                         for (const result of searchResults) {
                             if (!seen.has(result.symbolId)) {
                                 seen.add(result.symbolId);
@@ -374,7 +598,7 @@ export class Executor {
                     }
                     else {
                         const conn = await this.getConn();
-                        const searchResults = await ladybugDb.searchSymbols(conn, task.repoId, task.taskText, searchFallbackLimit);
+                        const searchResults = await this.dbQueries.searchSymbols(conn, task.repoId, task.taskText, searchFallbackLimit);
                         for (const result of searchResults) {
                             allSymbols.push(result.symbolId);
                         }
@@ -432,7 +656,8 @@ export class Executor {
             else {
                 // Fetch real symbol data from DB
                 const conn = await this.getConn();
-                const symbolMap = await ladybugDb.getSymbolsByIds(conn, allSymbols);
+                const symbolMap = await this.dbQueries.getSymbolsByIds(conn, allSymbols);
+                const relatedSymbolsByFile = await this.buildRelatedSymbolNameMap(conn, [...symbolMap.values()], task);
                 // Iterate in ranked order to preserve relevance in evidence
                 for (const symbolId of allSymbols) {
                     const sym = symbolMap.get(symbolId);
@@ -452,6 +677,16 @@ export class Executor {
                     const parts = [`${sym.kind} ${sym.name}`];
                     if (relPath)
                         parts.push(relPath);
+                    const fileAlias = this.fileAliasForPath(relPath);
+                    if (fileAlias && fileAlias !== sym.name) {
+                        parts.push(`fileAlias: ${fileAlias}`);
+                    }
+                    const relatedSymbols = sym.fileId
+                        ? relatedSymbolsByFile.get(sym.fileId)
+                        : undefined;
+                    if (relatedSymbols && relatedSymbols.length > 0) {
+                        parts.push(`relatedSymbols: ${relatedSymbols.join(", ")}`);
+                    }
                     if (sym.signatureJson) {
                         try {
                             const sig = JSON.parse(sym.signatureJson);
@@ -494,21 +729,30 @@ export class Executor {
             throw new IndexError(`Card rung execution failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    async executeSkeletonRung(task, context) {
+    async executeSkeletonRung(task, context, seedCandidates) {
         const actionId = this.generateActionId();
         const startTime = Date.now();
         try {
-            const { symbolIds: rawSkeletonSymbols, filePaths } = await this.resolveContextToSymbols(context, task.repoId);
+            const { symbolIds: rawSkeletonSymbols, filePaths, seedCandidates: expandedSeedCandidates, } = await this.resolveContextToSymbols(context, task, seedCandidates);
+            const skeletonSymbolLimit = this.rungSymbolLimit(task, MAX_SKELETON_SYMBOLS);
             const symbolIds = rawSkeletonSymbols.length > 0 && task.taskText
-                ? await this.selectTopSymbols(rawSkeletonSymbols, task, MAX_SKELETON_SYMBOLS)
-                : rawSkeletonSymbols.slice(0, MAX_SKELETON_SYMBOLS);
+                ? await this.selectTopSymbols(rawSkeletonSymbols, task, skeletonSymbolLimit, expandedSeedCandidates)
+                : rawSkeletonSymbols.slice(0, skeletonSymbolLimit);
             let processedCount = 0;
+            const hydrateEvidencePrefixes = this.shouldHydrateEvidencePrefixes(task);
+            const conn = hydrateEvidencePrefixes && symbolIds.length > 0
+                ? await this.getConn()
+                : undefined;
+            const symbolMap = conn
+                ? await this.dbQueries.getSymbolsByIds(conn, symbolIds)
+                : new Map();
             // Generate skeletons for symbol IDs (skip degenerate < 10 tokens)
             for (const symbolId of symbolIds) {
                 try {
                     const result = await generateSkeletonIR(task.repoId, symbolId, {});
                     if (result && result.estimatedTokens >= 10) {
-                        this.evidenceCapture.captureSkeleton(symbolId, `Skeleton (${result.originalLines} lines, ~${result.estimatedTokens} tokens): ${result.skeletonText.slice(0, 200)}`);
+                        const prefix = this.formatSymbolEvidencePrefix(symbolMap.get(symbolId));
+                        this.evidenceCapture.captureSkeleton(symbolId, `${prefix} | Skeleton (${result.originalLines} lines, ~${result.estimatedTokens} tokens): ${result.skeletonText.slice(0, 200)}`);
                         processedCount++;
                     }
                 }
@@ -526,7 +770,7 @@ export class Executor {
                 ? 0
                 : processedCount > 0
                     ? 1
-                    : MAX_SKELETON_SYMBOLS;
+                    : skeletonSymbolLimit;
             for (const filePath of filePaths.slice(0, maxFileSks)) {
                 try {
                     const result = await generateFileSkeleton(task.repoId, filePath, false, {});
@@ -564,21 +808,30 @@ export class Executor {
             throw new IndexError(`Skeleton rung execution failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    async executeHotPathRung(task, context) {
+    async executeHotPathRung(task, context, seedCandidates) {
         const actionId = this.generateActionId();
         const startTime = Date.now();
         try {
-            const { symbolIds: rawHotpathSymbols } = await this.resolveContextToSymbols(context, task.repoId);
+            const { symbolIds: rawHotpathSymbols, seedCandidates: expandedSeedCandidates } = await this.resolveContextToSymbols(context, task, seedCandidates);
+            const hotPathSymbolLimit = this.rungSymbolLimit(task, MAX_HOTPATH_SYMBOLS);
             const symbols = rawHotpathSymbols.length > 0 && task.taskText
-                ? await this.selectTopSymbols(rawHotpathSymbols, task, MAX_HOTPATH_SYMBOLS)
-                : rawHotpathSymbols.slice(0, MAX_HOTPATH_SYMBOLS);
+                ? await this.selectTopSymbols(rawHotpathSymbols, task, hotPathSymbolLimit, expandedSeedCandidates)
+                : rawHotpathSymbols.slice(0, hotPathSymbolLimit);
             const identifiers = this.extractIdentifiersFromTask(task);
             let processedCount = 0;
+            const hydrateEvidencePrefixes = this.shouldHydrateEvidencePrefixes(task);
+            const conn = hydrateEvidencePrefixes && symbols.length > 0
+                ? await this.getConn()
+                : undefined;
+            const symbolMap = conn
+                ? await this.dbQueries.getSymbolsByIds(conn, symbols)
+                : new Map();
             for (const symbolId of symbols) {
                 try {
                     const result = await extractHotPath(task.repoId, symbolId, identifiers, {});
                     if (result) {
-                        this.evidenceCapture.captureHotPath(symbolId, `Hot path (${result.matchedIdentifiers.length} matches, ~${result.estimatedTokens} tokens): ${result.excerpt.slice(0, 200)}`);
+                        const prefix = this.formatSymbolEvidencePrefix(symbolMap.get(symbolId));
+                        this.evidenceCapture.captureHotPath(symbolId, `${prefix} | Hot path (${result.matchedIdentifiers.length} matches, ~${result.estimatedTokens} tokens): ${result.excerpt.slice(0, 200)}`);
                         processedCount++;
                     }
                 }
@@ -615,7 +868,7 @@ export class Executor {
         const actionId = this.generateActionId();
         const startTime = Date.now();
         try {
-            const { symbolIds: symbols } = await this.resolveContextToSymbols(context, task.repoId);
+            const { symbolIds: symbols } = await this.resolveContextToSymbols(context, task);
             const identifiers = this.extractIdentifiersFromTask(task);
             let processedCount = 0;
             for (const symbolId of symbols.slice(0, MAX_RAW_SYMBOLS)) {
@@ -702,6 +955,58 @@ export class Executor {
         }
         return [...new Set(identifiers)].slice(0, MAX_IDENTIFIERS);
     }
+    fileAliasForPath(relPath) {
+        if (!relPath)
+            return undefined;
+        const parts = relPath.split(/[\\/]+/).filter(Boolean);
+        const fileName = parts.at(-1);
+        if (!fileName)
+            return undefined;
+        const base = fileName.replace(/\.[^.]+$/, "");
+        const parent = parts.length >= 2 ? parts.at(-2) : undefined;
+        const aliasBase = parent && GENERIC_FILE_BASENAMES.has(base.toLowerCase())
+            ? `${parent}-${base}`
+            : base;
+        const words = aliasBase
+            .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+            .split(/[^A-Za-z0-9]+/)
+            .filter(Boolean);
+        if (words.length === 0)
+            return undefined;
+        return words
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join("");
+    }
+    formatSymbolEvidencePrefix(sym) {
+        if (!sym)
+            return "symbol";
+        const relPath = sym.fileId?.includes(":")
+            ? sym.fileId.slice(sym.fileId.indexOf(":") + 1)
+            : sym.fileId;
+        const parts = [`${sym.kind} ${sym.name}`];
+        if (relPath)
+            parts.push(relPath);
+        const fileAlias = this.fileAliasForPath(relPath);
+        if (fileAlias && fileAlias !== sym.name) {
+            parts.push(`fileAlias: ${fileAlias}`);
+        }
+        return parts.join(" | ");
+    }
+    shouldHydrateEvidencePrefixes(task) {
+        const hasExplicitScope = !!(task.options?.focusPaths?.length || task.options?.focusSymbols?.length);
+        return task.options?.semantic === true || !hasExplicitScope;
+    }
+    rungSymbolLimit(task, defaultMax) {
+        const hasExplicitScope = !!(task.options?.focusPaths?.length || task.options?.focusSymbols?.length);
+        const hasInferredScope = (task.options?.inferredFocusPaths?.length ?? 0) > 0;
+        if (task.options?.contextMode === "precise" &&
+            hasExplicitScope &&
+            !hasInferredScope &&
+            task.options?.semantic !== true) {
+            return Math.min(2, defaultMax);
+        }
+        return defaultMax;
+    }
     generateActionId() {
         return `action-${this.actions.length}-${Date.now()}-${randomUUID().slice(0, 8)}`;
     }