@polycode-projects/the-mechanical-code-talker 2.11.0 → 2.11.1

package/data/templates/responses.jsonl

@@ -68,6 +68,7 @@
 {"id":"identity-self","class":"conversational","register":"friendly","template":"I'm tmct — a deterministic, offline chat assistant. No LLM: wink-nlp parsing over a seeded ontology/lexicon, plus a code graph when you point me at a repo with `--repo <path>`. /help for commands, /stats for an overview."}
 {"id":"identity-not-an-llm","class":"conversational","register":"friendly","template":"No — no LLM involved. tmct is deterministic: wink-nlp parsing over a graph/ontology, not a language model. /help for commands."}
 {"id":"identity-no-feelings","class":"conversational","register":"friendly","template":"No — I don't have feelings, opinions, or consciousness. tmct is deterministic: wink-nlp parsing over a graph/ontology, not a mind. /help for commands."}
+{"id":"identity-honest-miss","class":"conversational","register":"friendly","template":"No — I never make up an answer. If a question doesn't ground to a taught fact or a real graph entity, I say so plainly instead of guessing. /help for commands."}
 {"id":"technical-density","class":"count","register":"technical","template":"{subject} carries {count} {noun} across {scope} — a concentration well above what a codebase of this size typically sustains ({provenance})."}
 {"id":"technical-comparison","class":"count","register":"technical","template":"At {count} {noun}, {subject} sits {comparison} the comparable-project baseline, a divergence that reflects deliberate structure rather than measurement noise ({provenance})."}
 {"id":"technical-superlative","class":"count","register":"technical","template":"No {noun} in {scope} is more {metric} than {subject}; it leads the next candidate by a clear margin of {count} ({provenance})."}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.0",
+  "version": "2.11.1",
   "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; no codebase index of its own.",

package/src/domain/ask-vocab.mjs

@@ -246,6 +246,23 @@ export const VERB_TO_KIND = Object.freeze(
   ),
 );
 
+/** The bare possessive "has"/"have"/"holds"/"hold" is bucketed onto `defines`
+ *  (RELATIONS.defines.verbs above) for genuine code shapes ("what modules
+ *  does app.mjs have", "does createTask have tests") — but those reach the
+ *  grammar/keyword-spot strategies pre-rewritten onto a different verb by
+ *  normalize.mjs's PHRASING_FRAMES (has-tests -> "what tests X", members ->
+ *  "what does X contain"), and the possession/property sense of "have" over a
+ *  TAUGHT individual ("does whiskers have fur") is answered entirely by
+ *  chat.mjs's own has-a/hasProperty readers, upstream of both strategies. So
+ *  a bare have-family verb reaching either strategy's TWO-NAMED-ROLE "ask"
+ *  shape ("does X have Y", free-text subject and object, no grain check) has
+ *  no legitimate code question left to mean, and confidently framing it as
+ *  "locate what a module/class defines" is worse than an honest miss — both
+ *  grammar.mjs (T1/T2/T3) and keywords.mjs check this set to decline instead.
+ *  Shared here (rather than declared per-file) so the two strategies' bundled
+ *  builds never collide on the same top-level identifier. */
+export const HAS_FAMILY_VERBS = Object.freeze(new Set(["has", "have", "holds", "hold"]));
+
 /** "what is a kind of X" / "what is a subclass of X" collision fix: some
  *  inherits verbs are themselves phrased "is a <continuation>", which would
  *  otherwise collide with grammar.mjs's literal meta-whatis reading and

package/src/domain/ask.mjs

@@ -1236,6 +1236,29 @@ function reverseOverSet(graph, kind, entityType, objectIds) {
   return [];
 }
 
+const GIT_PROV_REF_RE = /^git:(.+)$/i;
+
+/** How many distinct commits are attested to have touched a SET of entities —
+ *  the same "touched by N commit(s)" convention renderDescribe's attestation
+ *  line already uses (codegraph.mjs's turnRefCount), not the narrower "touches
+ *  edge count" reverseOverSet(kind="touches") returns. A commit can be recorded
+ *  in an entity's own `derived_from` provenance with no full Commit individual
+ *  of its own (the ingester's touches-edge and provenance-ref writes can drift,
+ *  e.g. a truncated commit walk) — reverseOverSet alone then undercounts, or
+ *  misses entirely when NO touches edge survived. Deduped by short sha so a
+ *  provenance ref naming a commit that DOES have a touches-edge individual
+ *  isn't double-counted. */
+function commitTouchCount(graph, objectIds) {
+  const shas = new Set(reverseOverSet(graph, "touches", "Commit", objectIds).map((c) => String(c.label || "").toLowerCase()));
+  for (const id of objectIds) {
+    for (const ref of graph.byId.get(id)?.derived_from || []) {
+      const m = GIT_PROV_REF_RE.exec(String(ref || ""));
+      if (m) shas.add(m[1].toLowerCase());
+    }
+  }
+  return shas.size;
+}
+
 /** Forward traversal over a SET of subject ids (the "things {X…} call/define" step). */
 function forwardOverSet(graph, kind, subjectIds) {
   const edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => subjectIds.has(e.subject));
@@ -1934,6 +1957,24 @@ function evalUniversal(graph, ast, opts) {
   };
 }
 
+/** The object-id set a "how many commits touched <X>" count restricts to,
+ *  covering both AST shapes that phrasing compiles to: a flat single-object
+ *  reverse clause ("how many commits touched app/lib/a.mjs") or a composed
+ *  reverseSet over a nested inner set ("… touched the module that defines
+ *  fnAlpha"). Null for every other count shape (including an unresolved or
+ *  ambiguous object), so the caller falls back to its plain evalSet(base)
+ *  count unchanged. */
+function commitTouchObjectIds(graph, base, opts) {
+  if (base.node === "reverseSet" && base.kind === "touches" && base.entityType === "Commit") {
+    return new Set(evalSet(graph, base.inner, opts).map((i) => i.id));
+  }
+  if (base.node === "clause" && base.clause?.shape === "reverse" && base.clause.kind === "touches" && base.clause.entityType === "Commit") {
+    const { objMatch, ambiguous } = traverse(graph, base.clause, opts);
+    return objMatch && !ambiguous ? new Set([objMatch.id]) : null;
+  }
+  return null;
+}
+
 /** Compile any compositional AST to a result object traverse() returns for the
  *  simple path — {matches, …} plus compositeKind/compositeMiss flags render() reads. */
 function evalComposite(graph, ast, opts = {}) {
@@ -1941,7 +1982,16 @@ function evalComposite(graph, ast, opts = {}) {
   if (ast.node === "exists") return evalExists(graph, ast);
   if (ast.node === "qualCheck") return evalQualCheck(graph, ast, opts);
   if (ast.node === "universal") return evalUniversal(graph, ast, opts);
-  if (ast.node === "count") return { compositeKind: "count", count: evalSet(graph, ast.base, opts).length, entityType: ast.entityType, matches: [] };
+  if (ast.node === "count") {
+    // "how many commits touched <X>" — count against provenance attestation
+    // (commitTouchCount), not the bare touches-edge set evalSet(base) would
+    // give: see commitTouchCount's own doc for why the two can disagree.
+    const commitTouchIds = commitTouchObjectIds(graph, ast.base, opts);
+    if (commitTouchIds) {
+      return { compositeKind: "count", count: commitTouchCount(graph, commitTouchIds), entityType: ast.entityType, matches: [] };
+    }
+    return { compositeKind: "count", count: evalSet(graph, ast.base, opts).length, entityType: ast.entityType, matches: [] };
+  }
   if (ast.node === "list") return { compositeKind: "list", matches: evalSet(graph, ast.base, opts), entityType: ast.entityType, scoped: ast.scoped };
   if (ast.node === "superlative") return evalSuperlative(graph, ast);
   if (ast.node === "temporal") return evalTemporal(graph, ast, opts);

package/src/domain/grammar/ace.mjs

@@ -106,7 +106,12 @@ function resolveNP(lexicon, tokensIn, { allowCompound = false } = {}) {
     if (proper) return { term: `${ns}${proper}`, individual: true, extras: [], unknown: [] };
     if (CODE_REF.test(t)) return { term: `${ns}${t}`, individual: true, extras: [], unknown: [] };
     const noun = lookupNoun(lexicon, t, { singularOnly });
-    if (noun) return { term: `${ns}${noun.lemma}`, individual: false, noun, extras: [], unknown: [] };
+    // `folded` marks a match that only exists because lookupNoun's own
+    // trailing-"-s" strip or irregular-plural table rewrote the surface word
+    // — never an exact lexicon hit. parseCopula (below) uses this to keep a
+    // proper name that happens to fold to an unrelated dictionary word
+    // ("whiskers" -> "whisker") from silently losing its spelling.
+    if (noun) return { term: `${ns}${noun.lemma}`, individual: false, noun, folded: noun.lemma.toLowerCase() !== t.toLowerCase(), extras: [], unknown: [] };
     return { term: null, individual: false, extras: [], unknown: [t] };
   }
   if (tokens.length === 2) {
@@ -161,6 +166,26 @@ function resolveNP(lexicon, tokensIn, { allowCompound = false } = {}) {
   return { term: null, individual: false, extras: [], unknown: tokens.filter((t) => !classify(t, lexicon)) };
 }
 
+/** A bare single-token subject (no determiner of its own) that resolveNP only
+ *  resolved via a fold, immediately followed by an indefinite-article object
+ *  ("whiskers is A CAT", "every whiskers is A CAT"), is the canonical
+ *  individual-naming shape ("john is a man") wearing a proper name that
+ *  happens to fold to an unrelated dictionary word ("whiskers" ->
+ *  "whisker"). Trusting the fold here silently rewrites the taught subject's
+ *  spelling; declining it and reporting the token as unknown lets the
+ *  caller's own novel-individual fallback store the literal typed word
+ *  instead — the same honest-miss-over-guess call this file's
+ *  exact/irregular-only folds already make everywhere else. Shared by
+ *  parseCopula and parseEvery, the two patterns whose subject slot can hold
+ *  a bare single token immediately followed by "a"/"an". */
+function declineFoldedBareSubject(np, subjectToks, objectHead) {
+  if (np.term != null && !np.individual && np.folded
+    && subjectToks.length === 1 && /^an?$/i.test(objectHead)) {
+    return { term: null, individual: false, extras: [], unknown: [subjectToks[0]] };
+  }
+  return np;
+}
+
 /** The shared miss result: a structural fit with undeclared words returns the
  *  pattern + residue (triples empty); a fit with only declared-but-unusable
  *  phrasing returns null — the honest fall-through either way. */
@@ -349,7 +374,16 @@ function parseEvery(lexicon, toks, lower) {
   if (isIdx <= 1 || isIdx === toks.length - 1) return null;
   const rest = toks.slice(isIdx + 1);
   const everyAdjOnly = rest.length === 1 ? lookupAdjective(lexicon, rest[0]) : null;
-  const np1 = resolveNP(lexicon, toks.slice(1, isIdx), { allowCompound: !everyAdjOnly });
+  const subjectToks = toks.slice(1, isIdx);
+  // Same fold-vs-individual ambiguity parseCopula guards against — a
+  // determiner-less "every whiskers is a cat" reaches the identical
+  // single-token resolveNP fold ("whiskers" -> "whisker") assertCandidates
+  // manufactures as a candidate phrasing whenever the bare payload has no
+  // determiner of its own, so this needs the same declineFoldedBareSubject
+  // guard or that candidate alone re-opens the bug parseCopula just closed.
+  const np1 = declineFoldedBareSubject(
+    resolveNP(lexicon, subjectToks, { allowCompound: !everyAdjOnly }), subjectToks, rest[0],
+  );
   if (everyAdjOnly) return adjectiveCopula(lexicon, PATTERN_ADJECTIVE, np1, everyAdjOnly);
   const np2 = resolveNP(lexicon, rest, { allowCompound: true });
   if (np1.term == null || np2.term == null) return missOrNull(PATTERN_SUB_CLASS_OF, [np1, np2]);
@@ -414,7 +448,13 @@ function parseOfForm(lexicon, toks, lower) {
 function parseCopula(lexicon, toks, lower, isIdx) {
   const rest = toks.slice(isIdx + 1);
   if (!rest.length) return null;
-  const np1 = resolveNP(lexicon, toks.slice(0, isIdx), { allowCompound: rest.length > 1 });
+  const subjectToks = toks.slice(0, isIdx);
+  // parseAce never reaches here for "are", only singular "is" — see
+  // declineFoldedBareSubject's own docblock for why a bare single-token
+  // subject that only resolves by folding needs this guard.
+  const np1 = declineFoldedBareSubject(
+    resolveNP(lexicon, subjectToks, { allowCompound: rest.length > 1 }), subjectToks, rest[0],
+  );
   if (rest.length === 1) {
     const adj = lookupAdjective(lexicon, rest[0]);
     if (adj) return adjectiveCopula(lexicon, PATTERN_ADJECTIVE, np1, adj);

package/src/domain/interpret/normalize.mjs

@@ -128,8 +128,12 @@ const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy|g'?day|yeah\s+nah|g
  *  the "thanks" word family: "thanks so much, <Q>" -> "<Q>". */
 const THANKS_PREAMBLE_RE = /^(?:thanks|thank\s+you|many\s+thanks|thx|ty|cheers)(?:\s+(?:so\s+much|a\s+lot|very\s+much|a\s+bunch))?\s*[,—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
 /** Acknowledgement lead-in with a delimiter ("ok cool, <Q>"), repeating (`+`)
- *  so a stack of ack-words peels in one pass. */
-const ACK_PREAMBLE_RE = /^(?:(?:ok(?:ay)?|aight|cool|alright|sure|right|fine|great|nice|got it|gotcha|sounds good|no worries|no problem)[\s,]+)+(.+)$/i;
+ *  so a stack of ack-words peels in one pass. "one more"/"another one"/"just
+ *  one more" join the ack-word alternation as the same discourse move under a
+ *  different wording — a throwaway counting aside before the real content,
+ *  never part of the content itself ("ok, one more, teach me: no server is a
+ *  client" must peel exactly as "ok cool, <Q>" already does). */
+const ACK_PREAMBLE_RE = /^(?:(?:ok(?:ay)?|aight|cool|alright|sure|right|fine|great|nice|got it|gotcha|sounds good|no worries|no problem|(?:just\s+)?(?:one|another)\s+more|another\s+one)[\s,]+)+(.+)$/i;
 /** Self-orientation lead-in with a delimiter — "just poking around, <Q>",
  *  "first time using this, <Q>". */
 const BROWSING_PREAMBLE_RE = /^(?:just\s+(?:poking\s+around|looking\s+around|browsing|exploring|checking\s+(?:this|it)\s+out)|first\s+time\s+(?:trying\s+this\s+out|using\s+this|here)|i'?m\s+new\s+(?:here|around\s+here|to\s+(?:this|all\s+this)(?:\s+(?:repo|codebase|project|app|tool|thing))?))\s*[,.—–-]\s*(.+)$/i;

package/src/domain/interpret/strategies/grammar.mjs

@@ -8,7 +8,7 @@ import {
   VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
   META_MEANING_VERBS, WHERE_MARKERS, MENTION_MARKERS,
   INHERITS_REVERSE_VERBS, stripTrailingScopeFiller, stripTrailingDiscourseTag,
-  ARTICLE_RELATION_CONTINUATIONS,
+  ARTICLE_RELATION_CONTINUATIONS, HAS_FAMILY_VERBS,
 } from "../../ask-vocab.mjs";
 import { escapeRegex } from "../normalize.mjs";
 
@@ -17,6 +17,11 @@ const ENTITY_ALT = Object.keys(ENTITY_TO_TYPE).sort((a, b) => b.length - a.lengt
 const MODIFIER_ALT = Object.keys(MODIFIER_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
 const META_ALT = META_MEANING_VERBS.slice().sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
 
+// See ask-vocab.mjs's own HAS_FAMILY_VERBS for why a bare have-family verb
+// never resolves to `defines` in this template's "ask"/"reverse"/"forward"
+// shapes below.
+const isHasFamilyDefines = (kind, verb) => kind === "defines" && HAS_FAMILY_VERBS.has(verb);
+
 const TEMPLATES = [
   // T1 ASK: "does X import Y" -> Yes/No. REVERSE VERB SWAP: a semantically-reverse
   // verb ("superclass of") means the opposite of its forward counterpart, so
@@ -27,6 +32,7 @@ const TEMPLATES = [
     build: (m) => {
       const verb = m[2].toLowerCase();
       const kind = VERB_TO_KIND[verb];
+      if (isHasFamilyDefines(kind, verb)) return null;
       let subject = m[1].trim();
       let object = m[3].trim();
       if (INHERITS_REVERSE_VERBS.includes(verb)) [subject, object] = [object, subject];
@@ -37,23 +43,30 @@ const TEMPLATES = [
   {
     name: "reverse",
     re: new RegExp(`^which\\s+(${ENTITY_ALT})\\s+(?:(${MODIFIER_ALT})\\s+)?(${VERB_ALT})\\s+(.+?)\\??$`, "i"),
-    build: (m) => ({
-      shape: "reverse",
-      entityType: ENTITY_TO_TYPE[m[1].toLowerCase()],
-      modifier: m[2] ? MODIFIER_TO_KIND[m[2].toLowerCase()] : "direct",
-      kind: VERB_TO_KIND[m[3].toLowerCase()],
-      object: m[4].trim(),
-    }),
+    build: (m) => {
+      const verb = m[3].toLowerCase();
+      const kind = VERB_TO_KIND[verb];
+      if (isHasFamilyDefines(kind, verb)) return null;
+      return {
+        shape: "reverse",
+        entityType: ENTITY_TO_TYPE[m[1].toLowerCase()],
+        modifier: m[2] ? MODIFIER_TO_KIND[m[2].toLowerCase()] : "direct",
+        kind,
+        object: m[4].trim(),
+      };
+    },
   },
   // T3 forward: "what does <object> <verb>" — X is given, list its R-related things.
   // "did" joins does/do for the past-tense commit forms ("what did commit <sha> touch").
   {
     name: "forward",
     re: new RegExp(`^what\\s+(?:does|do|did)\\s+(.+?)\\s+(${VERB_ALT})\\??$`, "i"),
-    build: (m) => ({
-      shape: "forward", entityType: null, modifier: "direct",
-      kind: VERB_TO_KIND[m[2].toLowerCase()], object: m[1].trim(),
-    }),
+    build: (m) => {
+      const verb = m[2].toLowerCase();
+      const kind = VERB_TO_KIND[verb];
+      if (isHasFamilyDefines(kind, verb)) return null;
+      return { shape: "forward", entityType: null, modifier: "direct", kind, object: m[1].trim() };
+    },
   },
   // T4 meta: "what does <term> mean" — a question about the graph's own vocabulary,
   // not a graph traversal. VERB_ALT and META_ALT are disjoint tables, so this never
@@ -65,16 +78,33 @@ const TEMPLATES = [
   },
   // T5 meta: "what is a/an <term>" — the bare (no-article) form is restricted to
   // the closed ENTITY_TO_TYPE vocabulary (build() -> null otherwise, falling
-  // through); the WITH-article form is unrestricted.
+  // through); the WITH-article form is unrestricted. A "the"-article form is
+  // ALSO accepted, but only for a single-token term ("the Task") — the same
+  // schema-then-code-entity lookup a bare "Task" would reach (traverse()'s
+  // shape:"meta" handling, via metaFallbackEntityAnswer). Multi-word "the …"
+  // phrases stay excluded on purpose: "what is the meaning of this codebase"/
+  // "the purpose of X" are existential framings with their own decline
+  // elsewhere, never a literal term to look up (see the out-of-grammar test
+  // this guards).
   {
     name: "meta-whatis",
-    re: new RegExp(`^what\\s+(?:is|are)\\s+(?:(an?)\\s+)?(.+?)\\??$`, "i"),
+    re: new RegExp(`^what\\s+(?:is|are)\\s+(?:(an?|the)\\s+)?(.+?)\\??$`, "i"),
     build: (m) => {
+      const article = m[1] ? m[1].toLowerCase() : null;
       const object = stripTrailingDiscourseTag(m[2].trim());
-      if (!m[1] && !ENTITY_TO_TYPE[object.toLowerCase()]) return null; // bare form: closed-set only
-      // "what is a kind/subclass of X" is an inherits phrasing, not a term to define.
+      const isSingleToken = !/\s/.test(object);
+      if (article === "the" && !isSingleToken) return null;
+      if (!article && !ENTITY_TO_TYPE[object.toLowerCase()]) return null; // bare form: closed-set only
       const objLower = object.toLowerCase();
-      if (m[1] && ARTICLE_RELATION_CONTINUATIONS.some(
+      // "what is a kind/subclass of X" is an inherits phrasing, not a term to
+      // define — ARTICLE_RELATION_CONTINUATIONS only ever derives from the
+      // "is a/an <continuation>" verb forms, so it's checked only for those;
+      // "the"-definite reverse-inherits forms ("is the superclass of") are a
+      // separate, deliberately unfolded set (ask-vocab.mjs's own comment on
+      // INHERITS_REVERSE_VERB_LIST) — moot here since those are always
+      // multi-word and already excluded by the single-token check above, but
+      // named for the same reason ARTICLE_RELATION_CONTINUATIONS is.
+      if (article && article !== "the" && ARTICLE_RELATION_CONTINUATIONS.some(
         (c) => objLower === c || objLower.startsWith(`${c} `),
       )) return null;
       return { shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: stripTrailingScopeFiller(object) };

package/src/domain/interpret/strategies/keywords.mjs

@@ -8,7 +8,7 @@
 import {
   VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
   WHERE_MARKERS, MENTION_MARKERS, PLACEHOLDER_NOUNS, PASSIVE_PARTICIPLE_TO_KIND,
-  INHERITS_REVERSE_VERBS,
+  INHERITS_REVERSE_VERBS, HAS_FAMILY_VERBS,
 } from "../../ask-vocab.mjs";
 import { STOPWORDS } from "../normalize.mjs";
 import { VOCAB_WORDS, eligibleForCanon, fuzzyVocabWord } from "../fuzzy.mjs";
@@ -19,6 +19,10 @@ import { VOCAB_WORDS, eligibleForCanon, fuzzyVocabWord } from "../fuzzy.mjs";
 const PASSIVE_AUX = new Set(["is", "are", "was", "were", "be", "been", "being", "get", "gets", "got"]);
 const WH_WORDS = new Set(["which", "what", "who", "whom", "whose"]);
 const PLACEHOLDER_SET = new Set(PLACEHOLDER_NOUNS.map((w) => w.toLowerCase()));
+// See ask-vocab.mjs's own HAS_FAMILY_VERBS for why a bare have-family verb
+// never resolves to `defines` in this strategy's two-named-role "ask" shape
+// below (the forward/reverse branches keep their own tested grain-check
+// decline, per that constant's own docblock).
 
 /** Find the longest phrase from `table`'s keys that appears as a contiguous
  *  run of `words` (case already lowercased by the caller). Longest-match-first
@@ -107,6 +111,13 @@ export function parseKeywordSpot(text, nlp = null) {
       fuzzyVerb = { from: lcWords[at], to: fuzzyWords[at] };
     }
   }
+  // Tracks whether verbHit came from PASSIVE_PARTICIPLE_TO_KIND's fallback
+  // rather than an active VERB_TO_KIND entry — that table's own header says
+  // it's only meant to fire once a passive auxiliary AND an agent-marking
+  // "by" are confirmed. A direct complement with no "by" ("my cat is called
+  // whiskers") is the naming sense of "call", not the invoke-relation passive,
+  // so this flag gates the ask-shape SVO fallback below from misreading it.
+  let verbFromParticiple = false;
   if (!verbHit) {
     // A participle with no active verb entry still marks a passive when a passive
     // auxiliary precedes it — with or without an agent "by" phrase. "is http.mjs
@@ -125,10 +136,28 @@ export function parseKeywordSpot(text, nlp = null) {
     for (let i = 0; i < lcWords.length; i += 1) {
       const k = PASSIVE_PARTICIPLE_TO_KIND[lcWords[i]];
       if (k && lcWords[i] === "used" && lcWords[i + 1] === "for") continue;
-      if (k && lcWords.slice(0, i).some((w) => PASSIVE_AUX.has(w))) { verbHit = { kind: k, start: i, end: i + 1 }; break; }
+      if (k && lcWords.slice(0, i).some((w) => PASSIVE_AUX.has(w))) {
+        verbHit = { kind: k, start: i, end: i + 1 };
+        verbFromParticiple = true;
+        break;
+      }
     }
   }
   if (!verbHit) return null;
+  // A single-word verbHit whose LITERAL surface text (not the lemma the tier-2
+  // pass may have rewritten it to) is itself a PASSIVE_PARTICIPLE_TO_KIND entry,
+  // preceded by a passive auxiliary, is the same "needs a confirmed 'by' agent"
+  // case the fallback loop above already flags — checked here too because the
+  // lemma tier reaches it independently: lemma("called") is "call", an ACTIVE
+  // verb-table entry in its own right, so tier 2 resolves verbHit before the
+  // fallback loop ever runs, silently losing the participle reading. "my cat is
+  // called whiskers" (the naming sense of "call") must not be read as though
+  // "cat" were the active subject invoking "whiskers".
+  if (!verbFromParticiple && verbHit.end - verbHit.start === 1
+    && PASSIVE_PARTICIPLE_TO_KIND[lcWords[verbHit.start]]
+    && lcWords.slice(0, verbHit.start).some((w) => PASSIVE_AUX.has(w))) {
+    verbFromParticiple = true;
+  }
   // A tier-3 verb is a REPAIR, not a reading — downstream consumers (the teach
   // lane's canonical receipt, and the chat surface's fuzzy-verb decline) need
   // to know the difference AND which word was rewritten, so {from, to} rides
@@ -221,15 +250,35 @@ export function parseKeywordSpot(text, nlp = null) {
     const [patient, agent] = agentIsFronted
       ? [roleText(passiveAuxIdx + 1, words.length), roleText(byIdx + 1, passiveAuxIdx)]
       : [roleText(0, byIdx), roleText(byIdx + 1, words.length)];
-    if (patient && agent) return stamp({ shape: "ask", entityType: null, modifier: "direct", kind, subject: agent, object: patient });
+    if (patient && agent) {
+      if (kind === "defines" && HAS_FAMILY_VERBS.has(canonWords.slice(verbHit.start, verbHit.end).join(" "))) return null;
+      return stamp({ shape: "ask", entityType: null, modifier: "direct", kind, subject: agent, object: patient });
+    }
     if (agent) return stamp({ shape: "forward", entityType, modifier, kind, object: agent });
     if (patient) return stamp({ shape: "reverse", entityType, modifier, kind, object: patient });
   }
 
+  // "called" specifically (never the rest of the participle family — "was it
+  // touched recently"/"is X used anywhere" are genuine bare-passive code
+  // queries with a trailing adverb, not a competing sense, and must keep
+  // reaching their existing reading) carries a whole separate NAMING sense
+  // ("my cat is called whiskers") distinct from the invoke-relation passive
+  // this table exists for. A following complement with no "by" agent is that
+  // naming sense, not "whiskers calls cat" — falling through to the
+  // active-SVO/reverse branches below would read the participle as if it
+  // were an active verb and answer a code-graph question nobody asked, so
+  // this misses honestly instead.
+  if (verbFromParticiple && byIdx < 0 && afterText && lcWords[verbHit.start] === "called") return null;
+
   if (beforeText && afterText) {
+    const verbPhrase = canonWords.slice(verbHit.start, verbHit.end).join(" ");
+    // The bare have-family "ask" shape ("does X have Y") declines here, same
+    // reasoning as grammar.mjs's T1 (see HAS_FAMILY_VERBS above) — never for
+    // the entityType-driven forward/reverse branches below, which keep their
+    // own tested grain-check decline.
+    if (kind === "defines" && HAS_FAMILY_VERBS.has(verbPhrase)) return null;
     // A semantically-reverse verb ("superclass of") swaps subject/object, same as
     // grammar.mjs's T1.
-    const verbPhrase = canonWords.slice(verbHit.start, verbHit.end).join(" ");
     let subject = beforeText;
     let object = afterText;
     if (INHERITS_REVERSE_VERBS.includes(verbPhrase)) [subject, object] = [object, subject];

package/src/domain/router/registry.mjs

@@ -242,11 +242,18 @@ export function registerCapability(cap) {
 }
 
 // ---- unregistered dispatch tools ---------------------------------------------
-// Dispatch tools not yet registered; each names the precondition work it needs first.
+// Dispatch tools not yet registered; each names the work it needs first — a
+// precondition/effect design, or resolver wiring, before it can join the registry.
 export const EXCLUDED_FROM_REGISTRY = Object.freeze({
   tmct_context: "unbounded edit-context bundle (multi-file); needs a size/budget precondition",
   tmct_context_more: "unbounded context continuation; same as tmct_context",
   tmct_snippet: "raw source-file read (reads the filesystem); needs a file-read + span precondition",
+  tmct_ask: "the plain-English question entry point itself — calls ask.mjs directly and bypasses the capability planner; not one of the planner's operators",
+  tmct_export: "reads the memory store's whole fact set with no discriminating param and no resolver goal frame; needs NL-reachability wiring before it can join",
+  tmct_ingest: "writes into the memory store (grounds facts); capability() only models read-only operators, so a write path needs its own precondition/effect design first",
+  tmct_file_history: "a module-grain cut of the same history edge tmct_history already models; no NL frame distinguishes the granularities yet",
+  tmct_method_history: "a method-grain cut of the same history edge tmct_history already models; no NL frame distinguishes the granularities yet",
+  tmct_class_history: "a class-grain cut of the same history edge tmct_history already models; no NL frame distinguishes the granularities yet",
 });
 
 /** The full registry as a plain frozen object (facts + index), for callers that