@polycode-projects/the-mechanical-code-talker 3.1.0 → 3.1.3

package/README.md

@@ -1135,6 +1135,8 @@ The `<where-marker>` slot takes any of *defined*, *declared*, *located*, *implem
 - **touches** — *touched*, *touches*, *changed*, *change*, and more
 - **cochange** — *changed with*, *co-changes with*, *co-change with*, *changes alongside*, and more
 - **reexports** — *exports*, *export*, *re-exports*, *re-export*, and more
+- **serves** — *serves*, *serve*, *serving*, and more
+- **denotes** — *denotes*, *denote*, *denoting*, and more
 
 Every question in that table runs against the example graph:
 

package/corpus/seon/relations.jsonl

@@ -7,3 +7,5 @@
 {"relation":"touches","definition":"A touch is a commit changing a file or a symbol in the codebase.","sense":"software"}
 {"relation":"cochange","definition":"Change-coupling is two files that tend to be changed together in the same commits.","sense":"software"}
 {"relation":"reexports","definition":"A re-export is a module passing another module's definition through as part of its own public API.","sense":"software"}
+{"relation":"serves","definition":"A service edge is one part of the codebase providing or backing another, such as a handler serving a route.","sense":"software"}
+{"relation":"denotes","definition":"A denotation is a vocabulary term naming a code entity, linking the word to the thing it refers to.","sense":"software"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "3.1.0",
+  "version": "3.1.3",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; indexes a repo on request (tmct index) or reads any producer's graph.",
@@ -46,6 +46,8 @@
     "./generateCompletion": "./src/services/completions.mjs",
     "./createCompletionsGraphAdapter": "./src/services/completions.mjs",
     "./ingest": "./src/services/extract-facts.mjs",
+    "./digest": "./src/adapters/corpus/digest-bank.mjs",
+    "./memory": "./src/adapters/memory/core.mjs",
     "./repository-interface": "./src/adapters/repository-interface.mjs",
     "./conformance": "./src/tools/conformance.mjs",
     "./ask-browser": "./src/surfaces/web/graph-ask-browser-entry.mjs"

package/src/adapters/repository-interface.mjs

@@ -46,6 +46,7 @@ export const MISS_REASONS = Object.freeze({
 export const EDGE_KINDS = Object.freeze([
   "imports", "calls", "callsSymbol", "defines", "tests",
   "touches", "touchesSymbol", "contains", "inherits", "cochange", "reexports",
+  "serves", "denotes",
 ]);
 
 /** edge-kind → the `tmct:` object property it realizes (the OWL grounding). */
@@ -61,6 +62,8 @@ export const EDGE_KIND_TO_TMCT = Object.freeze({
   inherits: "tmct:extends",
   cochange: "tmct:dependsOn",
   reexports: "tmct:exports",
+  serves: "tmct:serves",
+  denotes: "tmct:denotes",
 });
 
 /** The named services, grouped as in the plan's six-group inventory. Names are

package/src/domain/ask-vocab.mjs

@@ -164,6 +164,29 @@ export const RELATIONS = {
       "exporting",
     ],
   },
+  // serves/denotes classify edges a PROVIDER declares (mgx:serves / mgx:denotes).
+  // tmct's own indexer emits neither, so they are absent from a graph it built
+  // and answer honestly empty there; a provider graph that carries them gets the
+  // same one-hop traversal every other kind gets, instead of only /describe's
+  // kind-agnostic edge walk.
+  serves: {
+    bare: "serve",
+    comment: "subject provides or backs the object — a handler serving a route, a module serving a surface (mgx:serves).",
+    verbs: [
+      "serves", "serve",
+      // gerund (g-drop normalization)
+      "serving",
+    ],
+  },
+  denotes: {
+    bare: "denote",
+    comment: "subject names the object — a glossary/lexicon term denoting a code entity (mgx:denotes).",
+    verbs: [
+      "denotes", "denote",
+      // gerund (g-drop normalization)
+      "denoting",
+    ],
+  },
 };
 
 /** The closed set of reverse `inherits` verb phrasings a strategy checks to

package/src/domain/ask.mjs

@@ -35,6 +35,7 @@ import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mj
 import { runStrategiesSync } from "./interpret/pipeline.mjs";
 import { mergeStrategyResults, alternateLines } from "./interpret/merge.mjs";
 import { lookupByProseTokens, splitIdentifierWords } from "./prose.mjs";
+import { articleFor } from "./digest/words.mjs";
 import { pickPhrase } from "./answer-variants.mjs";
 
 // Normalization stays importable from its original site (tests + chat surface).
@@ -137,7 +138,7 @@ function verbFor(kind) {
 const PLURAL_SUBJECT_VERB = {
   imports: "import", calls: "call", callsSymbol: "call", inherits: "inherit from",
   contains: "contain", tests: "test", touches: "touch", cochange: "cochange",
-  reexports: "export", uses: "use",
+  reexports: "export", uses: "use", serves: "serve", denotes: "denote",
 };
 const pluralVerbFor = (kind) => PLURAL_SUBJECT_VERB[kind] || verbFor(kind);
 
@@ -2187,7 +2188,28 @@ function describeFindHit(ind) {
   const label = ["Function", "Method"].includes(ind.class) ? `${ind.label}()` : ind.label;
   if (ind.class === "Module") return label;
   const mod = moduleLabelOf(ind);
-  return mod && mod !== "(unknown module)" ? `${label} in ${mod}` : label;
+  return mod ? `${label} in ${mod}` : label;
+}
+
+/** Does any branch of a compositional AST filter on test coverage? Keyed off
+ *  QUALIFIERS' own `via` field, so a new coverage adjective in the vocabulary
+ *  is picked up here without a second list to keep in step. */
+function filtersOnCoverage(node) {
+  if (!node || typeof node !== "object") return false;
+  if (Array.isArray(node)) return node.some(filtersOnCoverage);
+  if (Array.isArray(node.filters)
+    && node.filters.some((f) => QUALIFIERS[String(f).toLowerCase()]?.via === "tested")) return true;
+  return Object.values(node).some(filtersOnCoverage);
+}
+
+/** An empty coverage-filtered set over symbols is a grain mismatch, not an
+ *  absent answer: `tests` edges are recorded module to module, so no
+ *  function-grain coverage exists to filter on. Say that instead of the
+ *  generic rephrase nudge, which would send the reader somewhere unrelated. */
+function coverageGrainNote(parsed, entityType) {
+  if (!["Function", "Method"].includes(entityType)) return null;
+  if (!filtersOnCoverage(parsed)) return null;
+  return "This index records tests edges module to module, so it holds no function-grain coverage to filter on — ask whether the module a function lives in is tested instead.";
 }
 
 function renderComposite(parsed, result, graph) {
@@ -2210,7 +2232,7 @@ function renderComposite(parsed, result, graph) {
       }
       const hit = result.matches[0];
       const modLabel = moduleLabelOf(hit);
-      const definedIn = hit.class === "Module" ? "" : (modLabel && modLabel !== "(unknown module)" ? `, ${pickPhrase("defined-in", hit.id, "defined in")} ${modLabel}` : "");
+      const definedIn = hit.class === "Module" ? "" : (modLabel ? `, ${pickPhrase("defined-in", hit.id, "defined in")} ${modLabel}` : "");
       return { content: `Yes — ${hit.label} is a ${kindSingular}${definedIn}.`, miss: false, ambiguous: false, matches: result.matches };
     }
     if (!result.matches.length) {
@@ -2386,7 +2408,8 @@ function renderComposite(parsed, result, graph) {
   }
   // set-producing
   if (!result.matches.length) {
-    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${touchesRephraseHint(graph)}`, miss: true, ambiguous: false, matches: [] };
+    const hint = coverageGrainNote(parsed, result.entityType) || touchesRephraseHint(graph);
+    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${hint}`, miss: true, ambiguous: false, matches: [] };
   }
   return { content: `${compositeList(result.matches)}.`, miss: false, ambiguous: false, matches: result.matches };
 }
@@ -2963,6 +2986,25 @@ function modifierIsWired(shape, kind, entityType) {
 }
 const TRANSITIVE_MAX_DEPTH = 8; // matches renderImpact's own default (codegraph.mjs)
 
+/** A graph's own vocabulary nodes carry their definition text under this
+ *  property. A code entity's docstring rides `seon:hasDoc` and shares the
+ *  plain `doc` key, so the PROP is what separates the two. */
+const SCHEMA_DOC_PROP = "mgx:schemaDoc";
+
+/** The definition text an individual publishes about itself, or null. Reading
+ *  the meta lane off this attribute rather than a fixed class-name list lets a
+ *  graph declare its own documented individual class (a glossary term, say)
+ *  and have "what is X" answer for it like any other vocabulary node. */
+function schemaDefinitionOf(ind) {
+  return (ind?.attributes || []).find((a) => a.prop === SCHEMA_DOC_PROP)?.value || null;
+}
+
+function schemaKindWordFor(cls) {
+  if (cls === "SchemaClass") return "a class in the graph's schema";
+  if (cls === "SchemaPredicate") return "a predicate (relation) in the graph's schema";
+  return `${articleFor(cls)} ${cls} in this graph's vocabulary`;
+}
+
 /** Compile a parsed query into a graph lookup. Pure given (graph, parsed, opts).
  *  `opts.contextId` resolves a context pronoun ("this"/"it"/…) when the parse
  *  needed one. Returns {matches, objMatch, candidates, traversal, ambiguous,
@@ -2992,7 +3034,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
     const term = String(parsed.object || "").trim();
     const termLc = term.toLowerCase();
     const match = (graph.individuals || []).find((i) => {
-      if (i.class !== "SchemaClass" && i.class !== "SchemaPredicate") return false;
+      if (!schemaDefinitionOf(i)) return false;
       if (String(i.label).toLowerCase() === termLc) return true;
       const token = (i.attributes || []).find((a) => a.key === "token")?.value;
       return token && String(token).toLowerCase() === termLc;
@@ -3435,12 +3477,15 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
 // ---- templated renderer: string interpolation + grouping/pluralization/
 // overflow rules, never generation. ----
 
+/** The module an individual lives in, or null when the index places it in
+ *  none — a graph can carry individuals that are not code (a glossary term,
+ *  a schema node), and naming a module for those would be a fabrication. */
 function moduleLabelOf(ind) {
   if (ind.class === "Module") return ind.label;
   const site = (ind.attributes || []).find((a) => a.key === "site")?.value;
   if (site) return String(site).split(":")[0];
   const m = String(ind.id || "").match(/^fn:(.+)#/);
-  return m ? m[1] : "(unknown module)";
+  return m ? m[1] : null;
 }
 
 function symbolLabelOf(ind) {
@@ -3653,9 +3698,8 @@ function renderCore(parsed, result, graph) {
     if (result.metaCodeClass) {
       return { content: result.metaFallbackText, miss: false, ambiguous: false, matches: result.matches };
     }
-    const doc = (result.objMatch.attributes || []).find((a) => a.key === "doc")?.value || "";
-    const kindWord = result.objMatch.class === "SchemaClass" ? "a class in the graph's schema" : "a predicate (relation) in the graph's schema";
-    return { content: `${result.objMatch.label} is ${kindWord}: ${doc}`, miss: false, ambiguous: false, matches: result.matches };
+    const doc = schemaDefinitionOf(result.objMatch) || "";
+    return { content: `${result.objMatch.label} is ${schemaKindWordFor(result.objMatch.class)}: ${doc}`, miss: false, ambiguous: false, matches: result.matches };
   }
   // mentions: the prose surface — checked before the generic objMatch-null miss
   // below, because a mentions result deliberately carries no resolved object
@@ -3810,8 +3854,15 @@ function renderCore(parsed, result, graph) {
       const lines = m[3] && m[3] !== m[2] ? `lines ${m[2]}-${m[3]}` : `line ${m[2]}`;
       return { content: `${symbolLabelOf(ind)} is defined in ${m[1]} at ${lines}.`, miss: false, ambiguous: false, matches: result.matches };
     }
+    const mod = moduleLabelOf(ind);
+    if (!mod) {
+      return {
+        content: `${ind.label} has no recorded code location in this index — it carries no source site, and nothing places it in a module.`,
+        miss: true, ambiguous: false,
+      };
+    }
     return {
-      content: `${symbolLabelOf(ind)} is defined in ${moduleLabelOf(ind)} (no line span recorded in this index).`,
+      content: `${symbolLabelOf(ind)} is defined in ${mod} (no line span recorded in this index).`,
       miss: false, ambiguous: false, matches: result.matches,
     };
   }
@@ -3974,7 +4025,7 @@ function renderCore(parsed, result, graph) {
   // "there is … in {module}" (module trails, not leads).
   const byModule = new Map();
   for (const m of result.matches.slice(0, OVERFLOW_CAP)) {
-    const mod = moduleLabelOf(m);
+    const mod = moduleLabelOf(m) || "no recorded module";
     if (!byModule.has(mod)) byModule.set(mod, []);
     byModule.get(mod).push(symbolLabelOf(m));
   }
@@ -4066,8 +4117,7 @@ function fuzzyCascadeWord(w) {
  *  question. Exact/substring/prose matches are untouched. */
 function schemaTypoTrap(resolution, term) {
   if (!resolution?.match || resolution.matchedVia !== "fuzzy" || resolution.ambiguous) return false;
-  const cls = resolution.match.class;
-  if (cls !== "SchemaClass" && cls !== "SchemaPredicate") return false;
+  if (!schemaDefinitionOf(resolution.match)) return false;
   const lc = String(term || "").trim().toLowerCase();
   const kindNoun = fuzzyCascadeWord(lc);
   return !!kindNoun && kindNoun !== lc && !!ENTITY_TO_TYPE[kindNoun];

package/src/domain/code-explorer-hints.mjs

@@ -42,6 +42,8 @@ const FORWARD_TEMPLATE = Object.freeze({
   contains: (f) => `what is in ${f}`,
   defines: (f) => `what does ${f} define`,
   inherits: (f) => `what does ${f} inherit from`,
+  serves: (f) => `what does ${f} serve`,
+  denotes: (f) => `what does ${f} denote`,
 });
 
 // Reverse reading (focus is the object): "what <kind> <focus>".
@@ -51,6 +53,8 @@ const REVERSE_TEMPLATE = Object.freeze({
   tests: (f) => `what tests ${f}`,
   inherits: (f) => `what inherits from ${f}`,
   contains: (f) => `what contains ${f}`,
+  serves: (f) => `what serves ${f}`,
+  denotes: (f) => `what denotes ${f}`,
 });
 
 /** Index a payload into the counts and adjacency the hints read: class →

package/src/domain/codegraph.mjs

@@ -75,6 +75,10 @@ const PROP_KIND = {
   "seon:hassupertype": "inherits",
   "mgx:changecoupledwith": "cochange",
   "mgx:reexports": "reexports",
+  // provider-declared edges: tmct's own indexer emits neither, so these classify
+  // only in a graph supplied through the provider seam
+  "mgx:serves": "serves",
+  "mgx:denotes": "denotes",
   // symbol-level edges stay separate kinds so the module-coarse impact closure is unchanged
   "mgx:touchessymbol": "touchesSymbol",
   "mgx:callssymbol": "callsSymbol",
@@ -152,6 +156,11 @@ export function resolveSymbol(graph, symbol) {
   const s = normPath(symbol);
   if (!s) return { match: null, candidates: [] };
   const sBase = basename(s);
+  // A bare filename (no "/") legitimately fuzzy-matches on basename alone. A
+  // multi-segment input reads as a repo-relative path the caller believes exists;
+  // matching it against an unrelated file that merely shares a basename would
+  // fabricate a hit, so those only match via an exact path suffix, never basename alone.
+  const isBareFilename = !s.includes("/");
   const scored = [];
   for (const ind of graph.individuals) {
     const label = normPath(ind.label);
@@ -160,8 +169,7 @@ export function resolveSymbol(graph, symbol) {
     if (label === s || id === s) score = 100;
     else if (
       label.endsWith(`/${s}`) ||
-      basename(label) === sBase ||
-      basename(label).replace(/\.[a-z]+$/, "") === sBase
+      (isBareFilename && (basename(label) === sBase || basename(label).replace(/\.[a-z]+$/, "") === sBase))
     )
       score = 80;
     else if (label.includes(s)) score = Math.max(10, 50 - (label.length - s.length));
@@ -1090,7 +1098,7 @@ export function compileNameFilter(name, { now = Date.now } = {}) {
   };
 }
 
-export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "" } = {}) {
+export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "", toolNamePrefix = "tmct_" } = {}) {
   const tokens = String(query || "").toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
   const wantKind = String(kind || "").trim().toLowerCase();
   const decFilter = String(decorator || "").trim().toLowerCase();
@@ -1104,7 +1112,7 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
   // default (no kind) keeps the module "where does this live" search unchanged.
   if (wantKind && wantKind !== "module") {
     try {
-      return searchSymbols(graph, tokens, { limit, kind: wantKind, decFilter, nameRe });
+      return searchSymbols(graph, tokens, { limit, kind: wantKind, decFilter, nameRe, toolNamePrefix });
     } catch (e) {
       if (e instanceof NameFilterBudgetExceeded) return e.message;
       throw e;
@@ -1113,7 +1121,7 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
   if (!tokens.length && !nameRe && !decFilter) return "empty query";
   const scored = scoreModules(graph, tokens);
   if (!scored.length) {
-    return `no module matches "${query}". Try broader keywords, or tmct_describe <path> if you know where it lives.`;
+    return `no module matches "${query}". Try broader keywords, or ${toolNamePrefix}describe <path> if you know where it lives.`;
   }
   const hits = scored.slice(0, limit);
   const lines = [`${scored.length} module(s) match "${query}" (top ${hits.length}):`];
@@ -1121,7 +1129,7 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
     const m = matching.length ? ` — matching: ${capJoin([...new Set(matching)], SEARCH_SYMBOLS_SHOWN)}` : "";
     lines.push(`- ${ind.label} (defines ${defineCount} symbol(s))${m}`);
   }
-  lines.push("Then tmct_describe <path> for the full sibling list + typed edges, or tmct_impact <path> for dependents.");
+  lines.push(`Then ${toolNamePrefix}describe <path> for the full sibling list + typed edges, or ${toolNamePrefix}impact <path> for dependents.`);
   return lines.join("\n");
 }
 
@@ -1187,11 +1195,11 @@ const CALL_CAP = 30;
 
 /** A class's methods + attributes (with sites/decorators) in one slice — replaces
  *  reading the class body. Uses the `contains` (seon:containsCodeEntity) relation. */
-export function renderMembers(graph, ind) {
+export function renderMembers(graph, ind, { toolNamePrefix = "tmct_" } = {}) {
   const lines = [`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`];
   const contains = edgesOfKind(graph, "contains").filter((e) => e.subject === ind.id);
   if (!contains.length) {
-    lines.push("members: none recorded (empty class, or members not in the extracted graph). Use tmct_describe for its edges.");
+    lines.push(`members: none recorded (empty class, or members not in the extracted graph). Use ${toolNamePrefix}describe for its edges.`);
     return lines.join("\n");
   }
   const methods = [];
@@ -1205,7 +1213,7 @@ export function renderMembers(graph, ind) {
   }
   if (methods.length) lines.push(`methods (${methods.length}): ${capJoin(methods, MEMBERS_CAP)}`);
   if (attrs.length) lines.push(`attributes (${attrs.length}): ${capJoin(attrs, MEMBERS_CAP)}`);
-  lines.push("Use tmct_snippet <Class.member> for an exact body.");
+  lines.push(`Use ${toolNamePrefix}snippet <Class.member> for an exact body.`);
   return lines.join("\n");
 }
 
@@ -1215,7 +1223,7 @@ const attrVal = (ind, key) => (ind?.attributes || []).find((a) => a.key === key)
  *  return annotation, raises/catches, self-fields, flags, decorators, one-line doc —
  *  so the agent gets the API surface without reading the body. Deterministic ast facts
  *  (kept OUT of tmct_context's lean bundle; this is the targeted tool for them). */
-export function renderSignature(graph, ind) {
+export function renderSignature(graph, ind, { toolNamePrefix = "tmct_" } = {}) {
   const site = siteOf(ind);
   const lines = [`${ind.label} — ${classHeading(ind.class)}${spanTag(site)}`];
   const params = attrVal(ind, "params");
@@ -1242,8 +1250,8 @@ export function renderSignature(graph, ind) {
   if (value) lines.push(`value: ${value}`);
   const doc = attrVal(ind, "doc");
   if (doc) lines.push(`doc: ${doc}`);
-  if (lines.length === 1) lines.push("(no signature detail recorded for this symbol — likely a module or attribute; use tmct_snippet for its source.)");
-  lines.push("Use tmct_snippet for the exact body.");
+  if (lines.length === 1) lines.push(`(no signature detail recorded for this symbol — likely a module or attribute; use ${toolNamePrefix}snippet for its source.)`);
+  lines.push(`Use ${toolNamePrefix}snippet for the exact body.`);
   return lines.join("\n");
 }
 
@@ -1391,18 +1399,18 @@ export function renderHistory(graph, ind) {
 // classes whose call graph lives on the fn/method-precise callsSymbol edge, not module-coarse calls
 const CALL_SYMBOL_CLASSES = new Set(["Function", "Method"]);
 
-export function renderCallers(graph, ind) {
+export function renderCallers(graph, ind, { toolNamePrefix = "tmct_" } = {}) {
   // symbol grain: a fine symbol's callers are the SUBJECTS of callsSymbol edges into it.
   if (CALL_SYMBOL_CLASSES.has(ind.class)) {
     const callers = [...new Set(edgesOfKind(graph, "callsSymbol").filter((e) => e.object === ind.id).map((e) => e.subjectLabel || e.subject))];
-    if (!callers.length) return `${ind.label}: no recorded callers (fine-grained call edges are conservative — absence is not proof). Try tmct_impact for the full reverse closure.`;
+    if (!callers.length) return `${ind.label}: no recorded callers (fine-grained call edges are conservative — absence is not proof). Try ${toolNamePrefix}impact for the full reverse closure.`;
     return `${ind.label} — called by ${callers.length} symbol(s):\n  ${capJoin(callers, CALL_CAP, "\n  ")}`;
   }
   const modId = moduleIdOf(graph, ind);
   if (!modId) return `cannot map ${ind.label} to a module.`;
   const modLabel = graph.byId.get(modId)?.label || modId;
   const callers = [...new Set(edgesOfKind(graph, "calls").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject))];
-  if (!callers.length) return `${modLabel}: no recorded callers (calls are coarse/import-backed — absence is not proof). Try tmct_impact for the full reverse closure.`;
+  if (!callers.length) return `${modLabel}: no recorded callers (calls are coarse/import-backed — absence is not proof). Try ${toolNamePrefix}impact for the full reverse closure.`;
   return `${modLabel} — called by ${callers.length} module(s):\n  ${capJoin(callers, CALL_CAP, "\n  ")}`;
 }
 
@@ -1632,7 +1640,7 @@ export function scoreSymbolsRanked(graph, tokens, { kind, decFilter = "", nameRe
   return hits;
 }
 
-function searchSymbols(graph, tokens, { limit = SEARCH_LIMIT, kind, decFilter, nameRe }) {
+function searchSymbols(graph, tokens, { limit = SEARCH_LIMIT, kind, decFilter, nameRe, toolNamePrefix = "tmct_" }) {
   const targetClass = SYMBOL_CLASSES[kind];
   if (!targetClass) return `unknown kind "${kind}" (use function, class, method, attribute, or module).`;
   const hits = scoreSymbolsRanked(graph, tokens, { kind, decFilter, nameRe });
@@ -1640,7 +1648,7 @@ function searchSymbols(graph, tokens, { limit = SEARCH_LIMIT, kind, decFilter, n
   const top = hits.slice(0, limit);
   const lines = [`${hits.length} ${kind}(s) match (top ${top.length}):`];
   for (const { ind } of top) lines.push(`- ${ind.label}${spanTag(siteOf(ind))}`);
-  lines.push("Then tmct_snippet <name> for the exact body, or tmct_describe for its edges.");
+  lines.push(`Then ${toolNamePrefix}snippet <name> for the exact body, or ${toolNamePrefix}describe for its edges.`);
   return lines.join("\n");
 }
 

package/src/domain/codeplan/graph-delta.mjs

@@ -30,6 +30,7 @@ export const ENTITY_CLASSES = Object.freeze([
 export const EDGE_PREDICATES = Object.freeze([
   "imports", "calls", "callsSymbol", "defines", "tests",
   "touches", "touchesSymbol", "contains", "inherits", "cochange", "reexports",
+  "serves", "denotes",
 ]);
 
 /** The closed effect vocabulary — every way an operator's declared delta can

package/src/domain/concept.mjs

@@ -219,6 +219,10 @@ export const RELATION_TERM = Object.freeze({
   export: "reexports", exports: "reexports", exporting: "reexports", exported: "reexports",
   reexport: "reexports", reexports: "reexports", reexporting: "reexports",
   "re-export": "reexports", "re-exports": "reexports", "re-exporting": "reexports",
+  // provider-declared kinds: tmct's own indexer emits neither, so a graph it
+  // built degrades to the honest two-band "no edges" answer rather than a miss.
+  serve: "serves", serves: "serves", serving: "serves", served: "serves",
+  denote: "denotes", denotes: "denotes", denoting: "denotes", denoted: "denotes",
 });
 
 /** concept key → the relationKind()s whose edges it enumerates. A concept can span
@@ -234,6 +238,8 @@ const RELATION_KINDS = Object.freeze({
   touches: ["touches", "touchesSymbol"],
   cochange: ["cochange"],
   reexports: ["reexports"],
+  serves: ["serves"],
+  denotes: ["denotes"],
 });
 
 /** concept key → the verb phrase that renders an edge as an English sentence
@@ -248,6 +254,8 @@ const RELATION_RENDER = Object.freeze({
   touches: { verb: "touches", edgeNoun: "touch" },
   cochange: { verb: "changes together with", edgeNoun: "change-coupling" },
   reexports: { verb: "re-exports", edgeNoun: "re-export" },
+  serves: { verb: "serves", edgeNoun: "service" },
+  denotes: { verb: "denotes", edgeNoun: "denotation" },
 });
 
 /** Per concept key, the candidate follow-up shapes in priority order — each
@@ -290,6 +298,14 @@ const RELATION_FOLLOWUP_SHAPES = Object.freeze({
     { side: "subj", make: (x) => `what does ${x} export` },
     { side: "obj", make: (x) => `where is ${x} defined` },
   ],
+  serves: [
+    { side: "subj", make: (x) => `what does ${x} serve` },
+    { side: "obj", make: (x) => `what serves ${x}` },
+  ],
+  denotes: [
+    { side: "subj", make: (x) => `what does ${x} denote` },
+    { side: "obj", make: (x) => `what denotes ${x}` },
+  ],
 });
 
 /** How many example edges the relation force shows before the remainder is held for

package/src/domain/interpret/normalize.mjs

@@ -186,6 +186,12 @@ const EMBEDDED_MEANS_RE = /^what\s+((?:an?\s+|the\s+)?[\w'-]+(?:\s+[\w'-]+){0,2}
  *  untouched, a relation/interrogative remainder unwraps to itself, anything
  *  else bridges to "describe <thing>". */
 const SHOW_GIVE_ME_RE = /^(?:show|give)\s+me\s+(?:the\s+)?(.+?)\??$/i;
+/** An "everything I need [to <verb>|for X]" remainder always bridges to
+ *  "describe <thing>", even when its purpose clause happens to contain a
+ *  relation verb ("everything I need to change X") — RELATION_VERB_RE's
+ *  bag-of-words probe would otherwise misread that verb as making the
+ *  remainder itself an already-relational clause. */
+const EVERYTHING_I_NEED_RE = /^everything\s+i(?:'d|\s+would)?\s+need\b/i;
 
 /** Leading STACCATO connective before an ALREADY well-formed question ("and
  *  what imports it") -> the question alone. Gated on the remainder starting
@@ -196,6 +202,12 @@ const SHOW_GIVE_ME_RE = /^(?:show|give)\s+me\s+(?:the\s+)?(.+?)\??$/i;
  *  noise-strip layer never drops. */
 const LEADING_CONNECTIVE_RE = /^(?:and|also|so|then|now|but)\s+(.+)$/i;
 const QUESTION_AUX_LEAD_RE = /^(?:does|do|did|is|are|was|were|has|have|had|can|could|will|would|should)\b/i;
+/** A bare relative-clause remainder ("the tests that cover it"), the shape an
+ *  anaphoric follow-up takes when it names a thing instead of asking outright.
+ *  Anchored on a determiner and a short head noun so a mid-clause boolean
+ *  branch ("and are tested", "and call Y") never reaches it. */
+const RELATIVE_CLAUSE_LEAD_RE =
+  /^(?:the|its|their|his|her|our|my)\s+[\w'-]+(?:\s+[\w'-]+){0,2}\s+(?:that|which|who)\s+\S/i;
 
 /** A topic-switch/self-interruption preamble ("actually never mind, <Q>"),
  *  repeating so a stack of markers peels in one pass. Distinct from
@@ -248,7 +260,9 @@ export function applyPreambleFrames(text) {
     if (m) {
       const rest = m[1].trim();
       if (!isListingRemainder(rest)) {
-        q = (RELATION_VERB_RE.test(rest) || INTERROGATIVE_LEAD_RE.test(rest)) ? rest : `describe ${rest}`;
+        const isRelationClause = !EVERYTHING_I_NEED_RE.test(rest)
+          && (RELATION_VERB_RE.test(rest) || INTERROGATIVE_LEAD_RE.test(rest));
+        q = isRelationClause ? rest : `describe ${rest}`;
       }
     }
     m = q.match(LEADING_CONNECTIVE_RE);
@@ -261,6 +275,7 @@ export function applyPreambleFrames(text) {
         INTERROGATIVE_LEAD_RE.test(rest) || QUESTION_AUX_LEAD_RE.test(rest)
         || TOPIC_SWITCH_PREAMBLE_RE.test(rest) || ACK_PREAMBLE_RE.test(rest)
         || HEDGE_ADVERB_PREAMBLE_RE.test(rest) || BROWSING_PREAMBLE_RE.test(rest)
+        || RELATIVE_CLAUSE_LEAD_RE.test(rest)
       ) q = rest;
     }
     if (q === before) break;

package/src/domain/module-paths.mjs

@@ -2,8 +2,10 @@
 // the rankers that read what they build.
 
 /** Does this module path (or a lowercased path-shaped label) belong to test code?
- *  Covers `test/` and `tests/` segments, Python's `test_*.py` convention, and
- *  .NET's `*.Tests` assembly suffix. Case-sensitive: callers holding mixed-case
- *  paths lowercase first. */
+ *  Covers `test/` and `tests/` segments, a hyphen/underscore-prefixed test directory
+ *  (`behaviour-tests/`, `unit_test/`), Python's `test_*.py` convention, .NET's
+ *  `*.Tests` assembly suffix, and a `.test`/`.spec` file anywhere in the tree.
+ *  Case-sensitive: callers holding mixed-case paths lowercase first. */
 export const isTestPath = (p) =>
-  /(^|\/)tests?\//.test(p) || /(^|\/)test_[^/]*\.py$/.test(p) || /\.tests(\.|$)/.test(p);
+  /(^|\/)tests?\//.test(p) || /(^|\/)test_[^/]*\.py$/.test(p) || /\.tests(\.|$)/.test(p)
+  || /(^|\/)[^/]*[-_]tests?\//.test(p) || /\.(test|spec)\.[cm]?[jt]sx?$/.test(p);