@skein-code/cli 0.3.18 → 0.3.19

package/README.md

@@ -441,10 +441,24 @@ npm run benchmark:context -- \
 ```
 
 It reports Recall@5/10/20, MRR, useful-token ratio, stale-hit rate, and cold,
-incremental, and warm-query latency. The included fixture only validates the
-metric pipeline; it is not evidence for performance on a production repository.
-`--fresh-index` deletes and rebuilds that workspace's local index, so use it only
-where rebuilding the index is intended.
+incremental, and warm-query latency. `context-benchmark-v2` covers TypeScript,
+Python, SQL, CJK, Markdown, mixed-language queries, and a TypeScript import
+neighbor that has no direct lexical match. Its checked-in thresholds fail the
+command instead of allowing a retrieval change to lower the quality bar.
+
+The persisted local index now stores content-addressed TypeScript compiler AST
+facts for definitions, calls, and relative imports. Matching definitions can
+expand a query and import/call neighbors may receive a bounded graph score;
+Python and SQL continue to use explicit syntax-aware fallbacks. Search and
+context JSON expose the index generation, file hash, matched/expanded terms,
+and bm25/path/symbol/phrase/graph breakdown without persisting the query or an
+additional copy of source. Index schema v2 artifacts rebuild as v3 rather than
+being trusted after the parser contract changes.
+
+The included fixture is a deterministic regression gate, not evidence for
+performance on every production repository. `--fresh-index` deletes and
+rebuilds that workspace's local index, so use it only where rebuilding the
+index is intended.
 
 ## Safety model
 

package/dist/cli.js

@@ -220,7 +220,7 @@ function isSqliteBusy(error) {
 // package.json
 var package_default = {
   name: "@skein-code/cli",
-  version: "0.3.18",
+  version: "0.3.19",
   description: "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   type: "module",
   license: "MIT",
@@ -236,6 +236,9 @@ var package_default = {
   },
   skein: {
     releaseNotes: [
+      "Local index v3 records TypeScript AST definitions, calls, and relative import adjacency for graph-assisted retrieval",
+      "Context hits expose generation, content hash, matched terms, and bm25/path/symbol/phrase/graph score provenance",
+      "Context benchmark v2 locks multilingual recall, MRR, useful-token, stale-hit, incremental-index, and warm-latency gates",
       "Large MCP catalogs now disclose at most eight request-relevant schemas per run while preserving network permissions",
       "Token Ledger receipts report deferred progressive schemas and selected definitions remain stable across tool turns",
       "A deterministic Token Economy replay benchmark guards evidence, output-firewall, and no-progress invariants",
@@ -301,6 +304,7 @@ var package_default = {
     react: "^19.2.3",
     "string-width": "^8.2.2",
     "strip-ansi": "^7.2.0",
+    typescript: "^5.9.3",
     yaml: "^2.8.2",
     zod: "^4.4.3"
   },
@@ -310,7 +314,6 @@ var package_default = {
     "@types/react": "^19.2.7",
     tsup: "^8.5.1",
     tsx: "^4.21.0",
-    typescript: "^5.9.3",
     vitest: "^4.0.18"
   },
   overrides: {
@@ -2610,8 +2613,9 @@ function countExplicitPaths(value) {
 // src/context/local-index.ts
 import { createHash as createHash6 } from "node:crypto";
 import { lstat as lstat8, readFile as readFile3, stat as stat3 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname7, extname as extname2, isAbsolute as isAbsolute3, join as join7, relative as relative5, resolve as resolve8, sep as sep4 } from "node:path";
+import { basename as basename5, dirname as dirname7, extname as extname2, isAbsolute as isAbsolute3, join as join7, posix, relative as relative5, resolve as resolve8, sep as sep4 } from "node:path";
 import fg from "fast-glob";
+import ts from "typescript";
 import { z as z3 } from "zod";
 
 // src/tools/workspace.ts
@@ -3063,10 +3067,13 @@ var indexedFileSchema = z3.object({
   ctimeMs: z3.number().optional(),
   size: z3.number().nonnegative(),
   contentHash: contentHashSchema,
-  chunks: z3.array(indexedChunkSchema)
+  chunks: z3.array(indexedChunkSchema),
+  definitions: z3.array(z3.string()),
+  references: z3.array(z3.string()),
+  imports: z3.array(z3.string())
 }).strict();
 var localIndexSchema = z3.object({
-  version: z3.literal(2),
+  version: z3.literal(3),
   createdAt: z3.string(),
   generation: z3.string().min(1),
   roots: z3.array(z3.string()),
@@ -3112,6 +3119,8 @@ var LocalContextIndex = class {
   index;
   workspace;
   queryCache = /* @__PURE__ */ new Map();
+  queryCacheHits = 0;
+  queryCacheMisses = 0;
   fingerprintCache;
   dirtyPaths = /* @__PURE__ */ new Set();
   refreshState = "current";
@@ -3257,7 +3266,7 @@ var LocalContextIndex = class {
         const nextFiles = [...files.values()].sort((left, right) => left.absolutePath.localeCompare(right.absolutePath));
         const generation = createGeneration(nextFiles);
         this.index = {
-          version: 2,
+          version: 3,
           createdAt: (/* @__PURE__ */ new Date()).toISOString(),
           generation,
           roots: this.roots,
@@ -3309,6 +3318,8 @@ var LocalContextIndex = class {
       files: this.index?.files.length ?? 0,
       chunks: this.index?.files.reduce((total, file) => total + file.chunks.length, 0) ?? 0,
       queryCacheEntries: this.queryCache.size,
+      queryCacheHits: this.queryCacheHits,
+      queryCacheMisses: this.queryCacheMisses,
       refreshState: this.refreshState,
       dirtyPaths: this.dirtyPaths.size,
       ...this.refreshError ? { refreshError: this.refreshError } : {},
@@ -3391,12 +3402,13 @@ var LocalContextIndex = class {
         ctimeMs: info.ctimeMs,
         size: info.size,
         contentHash,
-        chunks: chunkFile(safeItem, content)
+        chunks: chunkFile(safeItem, content),
+        ...extractSourceFacts(safeItem.path, content)
       });
     }
     const generation = createGeneration(files);
     this.index = {
-      version: 2,
+      version: 3,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       generation,
       roots: this.roots,
@@ -3461,7 +3473,8 @@ var LocalContextIndex = class {
         ctimeMs: info.ctimeMs,
         size: info.size,
         contentHash: hashContent(content),
-        chunks: chunkFile(safeItem, content)
+        chunks: chunkFile(safeItem, content),
+        ...extractSourceFacts(safeItem.path, content)
       };
     } catch {
       return void 0;
@@ -3484,7 +3497,8 @@ var LocalContextIndex = class {
           path: file.path,
           absolutePath: file.absolutePath
         }, content);
-        if (!chunksMatch(expectedChunks, file.chunks)) return false;
+        const expectedFacts = extractSourceFacts(file.path, content);
+        if (!chunksMatch(expectedChunks, file.chunks) || !sameStrings(expectedFacts.definitions, file.definitions) || !sameStrings(expectedFacts.references, file.references) || !sameStrings(expectedFacts.imports, file.imports)) return false;
       } catch {
         return false;
       }
@@ -3524,10 +3538,14 @@ var LocalContextIndex = class {
     return matches.length === 1 ? { root, path, absolutePath } : void 0;
   }
   rank(query, topK) {
-    const chunks = (this.index?.files ?? []).flatMap((file) => file.chunks);
+    const index = this.index;
+    const files = index?.files ?? [];
+    const chunks = files.flatMap((file) => file.chunks);
     if (!chunks.length) return [];
-    const terms = [...new Set(tokenize(query))];
-    if (!terms.length) return [];
+    const directTerms = [...new Set(tokenize(query))];
+    if (!directTerms.length || !index) return [];
+    const expandedTerms = expandQueryTerms(files, directTerms);
+    const terms = [.../* @__PURE__ */ new Set([...directTerms, ...expandedTerms])];
     const queryTerms = new Set(terms);
     const documentFrequency = new Map([...queryTerms].map((term) => [term, 0]));
     for (const chunk of chunks) {
@@ -3536,22 +3554,51 @@ var LocalContextIndex = class {
       }
     }
     const averageLength = chunks.reduce((sum, chunk) => sum + chunk.tokens.length, 0) / Math.max(chunks.length, 1);
-    return chunks.map((chunk) => ({ chunk, score: scoreChunk(
-      chunk,
-      terms,
-      query,
-      documentFrequency,
-      chunks.length,
-      averageLength
-    ) })).filter(({ score }) => score > 0).sort((left, right) => right.score - left.score || left.chunk.absolutePath.localeCompare(right.chunk.absolutePath)).slice(0, topK).map(({ chunk, score }) => ({
-      path: chunk.absolutePath,
-      startLine: chunk.startLine,
-      endLine: chunk.endLine,
-      content: chunk.content,
-      score,
-      source: "local-bm25+path+symbol",
-      ...chunk.symbol ? { symbol: chunk.symbol } : {}
-    }));
+    const filesByPath = new Map(files.map((file) => [file.absolutePath, file]));
+    const graphBoosts = buildGraphBoosts(files, directTerms);
+    const coverageTerms = directTerms.filter((term) => !retrievalStopWords.has(term));
+    const scored = chunks.map((chunk) => {
+      const lexical = scoreChunk(
+        chunk,
+        terms,
+        query,
+        documentFrequency,
+        chunks.length,
+        averageLength
+      );
+      const graph = graphBoosts.get(chunk.absolutePath)?.score ?? 0;
+      const score = lexical.bm25 + lexical.path + lexical.symbol + lexical.phrase + graph;
+      return { chunk, lexical, graph, score };
+    }).filter(({ score }) => score > 0).sort((left, right) => right.score - left.score || left.chunk.absolutePath.localeCompare(right.chunk.absolutePath));
+    const covered = scored.filter(({ lexical, graph }) => graph > 0 || hasSufficientQueryCoverage(lexical.matchedTerms, coverageTerms));
+    return (covered.length ? covered : scored).slice(0, topK).map(({ chunk, lexical, graph, score }) => {
+      const file = filesByPath.get(chunk.absolutePath);
+      const breakdown = {
+        bm25: roundScore(lexical.bm25),
+        path: roundScore(lexical.path),
+        symbol: roundScore(lexical.symbol),
+        phrase: roundScore(lexical.phrase),
+        graph: roundScore(graph),
+        total: roundScore(score)
+      };
+      const provenance = {
+        generation: index.generation,
+        contentHash: file?.contentHash ?? hashContent(chunk.content),
+        matchedTerms: lexical.matchedTerms.slice(0, 16),
+        expandedTerms: expandedTerms.slice(0, 16),
+        score: breakdown
+      };
+      return {
+        path: chunk.absolutePath,
+        startLine: chunk.startLine,
+        endLine: chunk.endLine,
+        content: chunk.content,
+        score,
+        source: "local-bm25+path+symbol+graph",
+        ...chunk.symbol ? { symbol: chunk.symbol } : {},
+        provenance
+      };
+    });
   }
   async hitsAreCurrent(hits) {
     const files = new Map((this.index?.files ?? []).map((file) => [file.absolutePath, file]));
@@ -3575,10 +3622,17 @@ var LocalContextIndex = class {
   }
   getCachedHits(query, topK) {
     const generation = this.index?.generation;
-    if (!generation) return void 0;
+    if (!generation) {
+      this.queryCacheMisses += 1;
+      return void 0;
+    }
     const key = `${generation}\0${topK}\0${query}`;
     const cached = this.queryCache.get(key);
-    if (!cached) return void 0;
+    if (!cached) {
+      this.queryCacheMisses += 1;
+      return void 0;
+    }
+    this.queryCacheHits += 1;
     this.queryCache.delete(key);
     this.queryCache.set(key, cached);
     return cloneHits(cached);
@@ -3674,6 +3728,9 @@ function chunksMatch(expected, actual) {
     return Boolean(candidate) && chunk.id === candidate?.id && chunk.root === candidate.root && chunk.path === candidate.path && chunk.absolutePath === candidate.absolutePath && chunk.startLine === candidate.startLine && chunk.endLine === candidate.endLine && chunk.content === candidate.content && chunk.symbol === candidate.symbol && chunk.tokens.length === candidate.tokens.length && chunk.tokens.every((token, tokenIndex) => token === candidate.tokens[tokenIndex]);
   });
 }
+function sameStrings(expected, actual) {
+  return expected.length === actual.length && expected.every((value, index) => value === actual[index]);
+}
 function existingBuildResult(status, started) {
   if (!status.available || !status.generation) {
     throw new Error("The existing local context index is unavailable.");
@@ -3728,7 +3785,8 @@ function packContextHits(hits, roots, maxTokens, engine) {
   const text = selected.map((hit) => {
     const shownPath = workspaceAliasPath(hit.path, roots);
     const symbol = hit.symbol ? ` symbol="${escapeAttribute(hit.symbol)}"` : "";
-    return `<code path="${escapeAttribute(shownPath)}" lines="${hit.startLine}-${hit.endLine}" score="${hit.score.toFixed(3)}"${symbol}>
+    const provenance = hit.provenance ? ` source="${escapeAttribute(hit.source)}" hash="${hit.provenance.contentHash.slice(0, 12)}" graph-score="${hit.provenance.score.graph.toFixed(3)}"` : "";
+    return `<code path="${escapeAttribute(shownPath)}" lines="${hit.startLine}-${hit.endLine}" score="${hit.score.toFixed(3)}"${symbol}${provenance}>
 ${hit.content}
 </code>`;
   }).join("\n\n");
@@ -3744,7 +3802,17 @@ ${hit.content}
   };
 }
 function cloneHits(hits) {
-  return hits.map((hit) => ({ ...hit }));
+  return hits.map((hit) => ({
+    ...hit,
+    ...hit.provenance ? {
+      provenance: {
+        ...hit.provenance,
+        matchedTerms: [...hit.provenance.matchedTerms],
+        expandedTerms: [...hit.provenance.expandedTerms],
+        score: { ...hit.provenance.score }
+      }
+    } : {}
+  }));
 }
 function cloneDuplicationBaseline(baseline) {
   return {
@@ -3846,6 +3914,109 @@ function detectSymbol(lines) {
   }
   return void 0;
 }
+function extractSourceFacts(path, content) {
+  const extension = extname2(path).toLocaleLowerCase();
+  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(extension)) {
+    return extractTypeScriptFacts(path, content);
+  }
+  if (extension === ".py") return extractPythonFacts(content);
+  if (extension === ".sql") return extractSqlFacts(content);
+  return { definitions: [], references: [], imports: [] };
+}
+function extractTypeScriptFacts(path, content) {
+  const definitions = /* @__PURE__ */ new Set();
+  const references = /* @__PURE__ */ new Set();
+  const imports = /* @__PURE__ */ new Set();
+  const source = ts.createSourceFile(path, content, ts.ScriptTarget.Latest, false, scriptKind(path));
+  const addName = (name) => {
+    if (!name) return;
+    if (ts.isIdentifier(name)) definitions.add(name.text);
+    else if (ts.isStringLiteralLike(name) || ts.isNumericLiteral(name)) definitions.add(name.text);
+    else if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+      for (const element of name.elements) if (ts.isBindingElement(element)) addName(element.name);
+    }
+  };
+  const addCallReference = (expression) => {
+    if (ts.isIdentifier(expression)) references.add(expression.text);
+    else if (ts.isPropertyAccessExpression(expression)) references.add(expression.name.text);
+    else if (ts.isElementAccessExpression(expression) && ts.isIdentifier(expression.expression)) {
+      references.add(expression.expression.text);
+    }
+  };
+  const visit = (node) => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+      if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) imports.add(node.moduleSpecifier.text);
+    } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && node.moduleReference.expression && ts.isStringLiteral(node.moduleReference.expression)) {
+      imports.add(node.moduleReference.expression.text);
+    } else if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node) || ts.isModuleDeclaration(node)) {
+      addName(node.name);
+    } else if (ts.isVariableDeclaration(node) || ts.isBindingElement(node) || ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node)) {
+      addName(node.name);
+    } else if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+      addCallReference(node.expression);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return {
+    definitions: sortedValues(definitions),
+    references: sortedValues(references),
+    imports: sortedValues(imports)
+  };
+}
+function scriptKind(path) {
+  switch (extname2(path).toLocaleLowerCase()) {
+    case ".tsx":
+      return ts.ScriptKind.TSX;
+    case ".jsx":
+      return ts.ScriptKind.JSX;
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return ts.ScriptKind.JS;
+    default:
+      return ts.ScriptKind.TS;
+  }
+}
+function extractPythonFacts(content) {
+  const definitions = /* @__PURE__ */ new Set();
+  const references = /* @__PURE__ */ new Set();
+  const imports = /* @__PURE__ */ new Set();
+  for (const line of content.split("\n")) {
+    const definition = line.match(/^\s*(?:async\s+)?(?:def|class)\s+([\p{L}_][\p{L}\p{N}_]*)/u);
+    if (definition?.[1]) definitions.add(definition[1]);
+    const imported = line.match(/^\s*(?:from\s+([\w.]+)\s+import|import\s+([\w.]+))/u);
+    if (imported?.[1] || imported?.[2]) imports.add(imported[1] ?? imported[2] ?? "");
+    for (const call of line.matchAll(/([\p{L}_][\p{L}\p{N}_]*)\s*\(/gu)) {
+      if (call[1] && !["def", "class", "if", "for", "while"].includes(call[1])) references.add(call[1]);
+    }
+  }
+  for (const definition of definitions) references.delete(definition);
+  return {
+    definitions: sortedValues(definitions),
+    references: sortedValues(references),
+    imports: sortedValues(imports)
+  };
+}
+function extractSqlFacts(content) {
+  const definitions = /* @__PURE__ */ new Set();
+  const references = /* @__PURE__ */ new Set();
+  const imports = /* @__PURE__ */ new Set();
+  for (const definition of content.matchAll(/\bcreate\s+(?:table|view|function|procedure)\s+(?:if\s+not\s+exists\s+)?([\w.]+)/giu)) {
+    if (definition[1]) definitions.add(definition[1]);
+  }
+  for (const reference2 of content.matchAll(/\b(?:from|join|update|into)\s+([\w.]+)/giu)) {
+    if (reference2[1]) references.add(reference2[1]);
+  }
+  return {
+    definitions: sortedValues(definitions),
+    references: sortedValues(references),
+    imports: sortedValues(imports)
+  };
+}
+function sortedValues(values) {
+  return [...values].filter(Boolean).sort((left, right) => left.localeCompare(right));
+}
 function tokenize(input2) {
   const normalized = input2.replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([\p{Ll}])([\p{Lu}])/gu, "$1 $2").toLocaleLowerCase();
   const base = normalized.match(/[\p{L}\p{N}_-]+/gu) ?? [];
@@ -3861,24 +4032,123 @@ function tokenize(input2) {
   }
   return output2;
 }
+var retrievalStopWords = /* @__PURE__ */ new Set([
+  "add",
+  "audit",
+  "change",
+  "code",
+  "create",
+  "explain",
+  "find",
+  "fix",
+  "implement",
+  "inspect",
+  "review",
+  "show",
+  "test",
+  "the",
+  "update",
+  "where",
+  "with",
+  "\u4FEE\u6539",
+  "\u4FEE\u590D",
+  "\u5B9E\u73B0",
+  "\u5BA1\u67E5",
+  "\u67E5\u627E",
+  "\u89E3\u91CA",
+  "\u6D4B\u8BD5",
+  "\u66F4\u65B0"
+]);
+function hasSufficientQueryCoverage(matchedTerms, coverageTerms) {
+  if (!coverageTerms.length) return matchedTerms.length > 0;
+  const matched = new Set(matchedTerms);
+  const covered = [...new Set(coverageTerms)].filter((term) => matched.has(term)).length;
+  return covered >= Math.min(2, new Set(coverageTerms).size);
+}
+function expandQueryTerms(files, directTerms) {
+  const expanded = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    for (const definition of file.definitions) {
+      const definitionTerms = [...new Set(tokenize(definition))];
+      if (!definitionMatchesQuery(definitionTerms, directTerms)) continue;
+      for (const term of definitionTerms) if (!directTerms.includes(term)) expanded.add(term);
+    }
+  }
+  return [...expanded].sort((left, right) => left.localeCompare(right)).slice(0, 24);
+}
+function buildGraphBoosts(files, directTerms) {
+  const anchors = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    for (const definition of file.definitions) {
+      if (!definitionMatchesQuery(tokenize(definition), directTerms)) continue;
+      const values = anchors.get(file.absolutePath) ?? /* @__PURE__ */ new Set();
+      values.add(definition.toLocaleLowerCase());
+      anchors.set(file.absolutePath, values);
+    }
+  }
+  if (!anchors.size) return /* @__PURE__ */ new Map();
+  const boosts = /* @__PURE__ */ new Map();
+  const addBoost = (path, score) => {
+    boosts.set(path, { score: (boosts.get(path)?.score ?? 0) + score });
+  };
+  const anchorSymbols = new Set([...anchors.values()].flatMap((symbols) => [...symbols]));
+  for (const file of files) {
+    if (file.references.some((reference2) => anchorSymbols.has(reference2.toLocaleLowerCase()))) {
+      addBoost(file.absolutePath, 1.5);
+    }
+    for (const specifier of file.imports) {
+      for (const target of resolveImportTargets(file, specifier, files)) {
+        if (anchors.has(target)) addBoost(file.absolutePath, 1.25);
+        if (anchors.has(file.absolutePath)) addBoost(target, 0.75);
+      }
+    }
+  }
+  return boosts;
+}
+function definitionMatchesQuery(definitionTerms, queryTerms) {
+  const definitions = new Set(definitionTerms);
+  const shared = [...new Set(queryTerms)].filter((term) => definitions.has(term));
+  const required = Math.min(2, Math.max(1, Math.min(definitions.size, queryTerms.length)));
+  return shared.length >= required;
+}
+function resolveImportTargets(importer, specifier, files) {
+  if (!specifier.startsWith(".")) return [];
+  const base = posix.normalize(posix.join(posix.dirname(importer.path), specifier));
+  const extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+  const importedExtension = posix.extname(base);
+  const extensionless = extensions.includes(importedExtension) ? base.slice(0, -importedExtension.length) : base;
+  const candidates = /* @__PURE__ */ new Set([
+    base,
+    ...extensions.map((extension) => `${extensionless}${extension}`),
+    ...extensions.map((extension) => posix.join(extensionless, `index${extension}`))
+  ]);
+  return files.filter((file) => file.root === importer.root && candidates.has(file.path)).map((file) => file.absolutePath);
+}
 function scoreChunk(chunk, terms, rawQuery, documentFrequency, documentCount, averageLength) {
   const frequencies = /* @__PURE__ */ new Map();
   for (const token of chunk.tokens) frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
   const k1 = 1.2;
   const b = 0.75;
-  let score = 0;
+  let bm25 = 0;
+  let path = 0;
+  let symbol = 0;
+  const matchedTerms = [];
   for (const term of terms) {
     const frequency = frequencies.get(term) ?? 0;
     if (!frequency) continue;
+    matchedTerms.push(term);
     const df = documentFrequency.get(term) ?? 0;
     const idf = Math.log(1 + (documentCount - df + 0.5) / (df + 0.5));
-    score += idf * (frequency * (k1 + 1) / (frequency + k1 * (1 - b + b * chunk.tokens.length / averageLength)));
-    if (chunk.path.toLocaleLowerCase().includes(term)) score += 1.5;
-    if (chunk.symbol?.toLocaleLowerCase().includes(term)) score += 2.5;
+    bm25 += idf * (frequency * (k1 + 1) / (frequency + k1 * (1 - b + b * chunk.tokens.length / averageLength)));
+    if (chunk.path.toLocaleLowerCase().includes(term)) path += 1.5;
+    if (chunk.symbol?.toLocaleLowerCase().includes(term)) symbol += 2.5;
   }
   const phrase = rawQuery.trim().toLocaleLowerCase();
-  if (phrase.length > 3 && chunk.content.toLocaleLowerCase().includes(phrase)) score += 3;
-  return score;
+  const phraseScore = phrase.length > 3 && chunk.content.toLocaleLowerCase().includes(phrase) ? 3 : 0;
+  return { bm25, path, symbol, phrase: phraseScore, matchedTerms };
+}
+function roundScore(value) {
+  return Number(value.toFixed(6));
 }
 
 // src/context/context-engine.ts
@@ -3989,7 +4259,10 @@ function formatContextHits(hits, roots) {
   return hits.map((hit) => {
     const path = workspaceAliasPath(hit.path, roots);
     const symbol = hit.symbol ? ` ${hit.symbol}` : "";
-    return `[${hit.source} ${hit.score.toFixed(3)}]${symbol} ${path}:${hit.startLine}-${hit.endLine}`;
+    const score = hit.provenance?.score;
+    const breakdown = score ? ` bm25=${score.bm25.toFixed(2)} path=${score.path.toFixed(2)} symbol=${score.symbol.toFixed(2)} graph=${score.graph.toFixed(2)}` : "";
+    const hash4 = hit.provenance?.contentHash.slice(0, 12);
+    return `[${hit.source} ${hit.score.toFixed(3)}${breakdown}${hash4 ? ` hash=${hash4}` : ""}]${symbol} ${path}:${hit.startLine}-${hit.endLine}`;
   }).join("\n");
 }
 
@@ -9719,7 +9992,7 @@ async function evaluateReuseGate(input2) {
     candidates.push({
       path: hit.path,
       ...hit.symbol ? { symbol: hit.symbol.slice(0, 160) } : {},
-      score: roundScore(hit.score),
+      score: roundScore2(hit.score),
       read
     });
   }
@@ -9827,7 +10100,7 @@ function unresolvedReceipt(input2, queryHash, targetPaths, trigger, detail) {
 function hash3(value) {
   return createHash13("sha256").update(value).digest("hex");
 }
-function roundScore(value) {
+function roundScore2(value) {
   return Number.isFinite(value) ? Math.round(value * 1e3) / 1e3 : 0;
 }