feat: route surface-enrichment for retrieval — opt-in, measured +0, default off

AGENTS.md

@@ -176,6 +176,11 @@ code-fence ---
 
 ## src
 
+### src/config/defaults.js
+```
+module.exports = { DEFAULTS }  :165-165
+```
+
 ### src/extractors/csharp.js
 ```
 module.exports = { extract }  :71-71
@@ -272,6 +277,12 @@ function dispatch(msg, cwd)  :41-108
 function start(cwd)  :113-139
 ```
 
+### src/retrieval/enrich-from-maps.js
+```
+module.exports = { enrichWithSurfaces }  :55-55
+function enrichWithSurfaces(index, cwd) → number  :25-53
+```
+
 ### src/analysis/coverage-score.js
 ```
 module.exports = { coverageScore, CODE_EXTS }  :105-105
@@ -309,11 +320,6 @@ function getChangedFiles(files, cache) → { changed: string[], unch  :71-88
 function updateCacheEntries(cache, extracted)  :96-103
 ```
 
-### src/config/defaults.js
-```
-module.exports = { DEFAULTS }  :163-163
-```
-
 ### src/config/loader.js
 ```
 module.exports = { loadConfig, loadBaseConfig }  :313-313
@@ -1090,41 +1096,6 @@ function walk(dir, cwd, depth, out)  :31-62
 function analyze(files, cwd)  :64-82
 ```
 
-### src/map/route-table.js
-```
-module.exports = { analyze }  :127-127
-function shouldSkipFile(rel)  :18-21
-function analyze(files, cwd)  :23-125
-```
-
-### src/mcp/handlers.js
-```
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput }  :975-975
-function _readContextFiles(cwd)  :10-17
-function readContext(args, cwd)  :36-66
-function searchSignatures(args, cwd)  :74-100
-function getMap(args, cwd)  :108-131
-function createCheckpoint(args, cwd)  :143-215
-function getRouting(args, cwd)  :224-261
-function explainFile(args, cwd)  :269-356
-function listModules(args, cwd)  :364-403
-function queryContext(args, cwd)  :411-438
-function getMethodImpact(args, cwd)  :446-460
-function getImpact(args, cwd)  :468-480
-function getLines(args, cwd)  :489-537
-function readMemory(args, cwd)  :545-580
-function getCalleeSignatures(args, cwd)  :589-634
-function _pkgVersion(cwd)  :641-644
-function notifyFileCreated(args, cwd)  :648-670
-function notifySymbolAdded(args, cwd)  :673-693
-function notifyFileDeleted(args, cwd)  :696-710
-function _changedFiles(cwd, args)  :716-728
-function getDiffContext(args, cwd)  :737-808
-function getArchitectureOverview(args, cwd)  :817-885
-function verifySuggestion(args, cwd)  :895-930
-function squeezeOutput(args, cwd)  :940-973
-```
-
 ### src/mcp/install.js
 ```
 module.exports = { CLIENTS, listClients, installClient, resolveTarget }  :142-142

benchmarks/reports/surface-enrichment.json

@@ -0,0 +1,164 @@
+{
+  "benchmark": "surface-enrichment-ab",
+  "arms": {
+    "A": "rank + plain index",
+    "B": "rank + route-enriched index"
+  },
+  "tasks": 90,
+  "hitAt5A": 80,
+  "hitAt5B": 80,
+  "deltaTasks": 0,
+  "routeSigsTotal": 280,
+  "perRepo": [
+    {
+      "repo": "abseil-cpp",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "akka",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "axios",
+      "tasks": 5,
+      "routeSigs": 1,
+      "hitA": 4,
+      "hitB": 4,
+      "delta": 0
+    },
+    {
+      "repo": "express",
+      "tasks": 5,
+      "routeSigs": 66,
+      "hitA": 4,
+      "hitB": 4,
+      "delta": 0
+    },
+    {
+      "repo": "fastapi",
+      "tasks": 5,
+      "routeSigs": 18,
+      "hitA": 4,
+      "hitB": 4,
+      "delta": 0
+    },
+    {
+      "repo": "fastify",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 4,
+      "hitB": 4,
+      "delta": 0
+    },
+    {
+      "repo": "flask",
+      "tasks": 5,
+      "routeSigs": 162,
+      "hitA": 0,
+      "hitB": 0,
+      "delta": 0
+    },
+    {
+      "repo": "gin",
+      "tasks": 5,
+      "routeSigs": 28,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "laravel",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "okhttp",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "rails",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "riverpod",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "rust-analyzer",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "serilog",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 0,
+      "hitB": 0,
+      "delta": 0
+    },
+    {
+      "repo": "spring-petclinic",
+      "tasks": 5,
+      "routeSigs": 5,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "svelte",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    },
+    {
+      "repo": "vapor",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 1,
+      "hitB": 1,
+      "delta": 0
+    },
+    {
+      "repo": "vue-core",
+      "tasks": 5,
+      "routeSigs": 0,
+      "hitA": 5,
+      "hitB": 5,
+      "delta": 0
+    }
+  ],
+  "skipped": [
+    {
+      "repo": "retrieval",
+      "reason": "repo not cloned"
+    }
+  ]
+}

docs-vp/public/llms-full.txt

@@ -343,7 +343,7 @@ testCoverage = false
 testDirs = ["tests","test","__tests__","spec"]
 sigCache = false
 impactRadius = false
-retrieval = {"topK":10,"recencyBoost":1.5,"callGraphBoost":false}
+retrieval = {"topK":10,"recencyBoost":1.5,"callGraphBoost":false,"surfaceEnrichment":false}
 impact = {"depth":3,"includeSigs":true}
 ```