@polycode-projects/the-mechanical-code-talker 1.8.11 → 1.8.14

package/src/chat.mjs

@@ -43,10 +43,10 @@ import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { createInterface } from "node:readline/promises";
 import { spawnSync } from "node:child_process";
-import { dispatchTool } from "./server.mjs";
+import { dispatchTool, loadGraph } from "./server.mjs";
 import { loadConfig, DEFAULT_GRAPH_REL } from "./config.mjs";
 import { resolveRuntimeConfig } from "./cli-args.mjs";
-import { parseEntities, edgesOfKind, renderAuthorCard, renderAuthorTouches, renderCommitAuthor } from "./codegraph.mjs";
+import { parseEntities, edgesOfKind, renderAuthorCard, renderAuthorTouches, renderCommitAuthor, resolveSymbol, renderCompare } from "./codegraph.mjs";
 import { SESSIONS_DIR_REL, appendSessionToGraph } from "./sessions.mjs";
 import { uuidv7 } from "./uuid.mjs";
 import { createTelemetry } from "./telemetry.mjs";
@@ -57,9 +57,9 @@ import { rankByBiasThenTrust } from "./memory/bias.mjs";
 import { finish, beginsWithVowelSound, grammarRules } from "./finish.mjs";
 import {
   VERB_TO_KIND, WHERE_MARKERS, MENTION_MARKERS, ENTITY_TO_TYPE, PASSIVE_PARTICIPLE_TO_KIND,
-  stripTrailingScopeFiller, stripTrailingDiscourseTag,
+  stripTrailingScopeFiller, stripTrailingDiscourseTag, EDGE_NOUN_TO_METRIC, RELATIONS,
 } from "./ask-vocab.mjs";
-import { COUNTERFACTUAL_RE, correctMisspellings, applyPreambleFrames, normalizeQuery, escapeRegex, kindNounAnaphoraHint } from "./interpret/normalize.mjs";
+import { COUNTERFACTUAL_RE, correctMisspellings, applyPreambleFrames, normalizeQuery, stripFillerWords, escapeRegex, kindNounAnaphoraHint } from "./interpret/normalize.mjs";
 import { fuzzyMatchInSet, fuzzyBound } from "./interpret/fuzzy.mjs";
 import { pickPhrase } from "./answer-variants.mjs";
 
@@ -564,6 +564,113 @@ export function answerCount(graph, query) {
   return `${n} ${classNoun(cls, n)}.`;
 }
 
+/** singular+plural display forms for the edge-nominalized nouns answerEdgeCount
+ *  (below) actually answers — a small subset of EDGE_NOUN_TO_METRIC's keys, the
+ *  ones that read as a real countable noun ("3 callers.") rather than a
+ *  participle only natural in a superlative ("most USED", not "how many used").
+ *  A key with no entry here echoes the user's own word unchanged (safe default,
+ *  same fallback CLASS_LABELS/classNoun use above). */
+const EDGE_NOUN_LABELS = {
+  test: ["test", "tests"], tests: ["test", "tests"],
+  importers: ["importer", "importers"], dependents: ["dependent", "dependents"],
+  callers: ["caller", "callers"], callees: ["callee", "callees"],
+  calls: ["call", "calls"], imports: ["import", "imports"],
+  dependencies: ["dependency", "dependencies"], members: ["member", "members"],
+  subclasses: ["subclass", "subclasses"], connections: ["connection", "connections"],
+  edges: ["edge", "edges"],
+};
+const edgeCountNoun = (noun, n) => {
+  const [s, p] = EDGE_NOUN_LABELS[noun] || [noun, noun];
+  return n === 1 ? s : p;
+};
+
+/** Pull the named entity out of a per-entity edge-count tail — the text after
+ *  "how many <edge-noun>" — recognising exactly the two closed shapes such a
+ *  tail actually takes:
+ *    - "<verb> <entity>" ("cover src/x.mjs", "import Widget") — verb drawn
+ *      from ask-vocab.mjs's RELATIONS[metric.kind].verbs (the SAME verb list
+ *      the relation clause grammar itself reads), longest-first so a
+ *      multi-word verb ("depends on") matches whole rather than a short
+ *      prefix stealing part of the entity name.
+ *    - "does/do/did <entity> have/has/had/got" ("does X have") — safe to
+ *      treat as unambiguous HERE even though answerCount's own
+ *      AMBIGUOUS_HAVE_VERBS guard deliberately excludes "have" elsewhere:
+ *      that guard exists because "have" maps to either defines/contains
+ *      depending on the SUBJECT's class, but an edge-nominalized noun's
+ *      metric.dir is fixed by the NOUN itself ("importers" is always dir
+ *      "in"), so there is no analogous ambiguity to worry about here.
+ *  Returns the trimmed entity term, or null (no recognizable shape — an
+ *  honest decline, not a guess) — the caller then leaves the existing "I
+ *  can't count" message from answerCount standing. */
+function extractEdgeCountEntity(tail, metric) {
+  const t = String(tail || "").trim().replace(/[?.!]+$/, "").trim();
+  if (!t) return null;
+  const haveM = t.match(/^(?:does|do|did)\s+(.+?)\s+(?:have|has|had|got)$/i);
+  if (haveM && haveM[1].trim()) return haveM[1].trim();
+  if (metric.kind !== "*" && RELATIONS[metric.kind]) {
+    const verbs = [...RELATIONS[metric.kind].verbs].sort((a, b) => b.length - a.length);
+    for (const v of verbs) {
+      const re = new RegExp(`^${v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+(.+)$`, "i");
+      const m = t.match(re);
+      if (m && m[1].trim()) return m[1].trim();
+    }
+  }
+  return null;
+}
+
+/** Bare "how many <edge-noun> <verb> <entity>" / "how many <edge-noun> does
+ *  <entity> have" (HANDOVER "bare 'how many X' fails for edge-nominalized
+ *  nouns", 2026-07-12 fix) — "how many tests cover X", "how many importers
+ *  does X have", "how many callers does X have". answerCount's own COUNT_NOUNS
+ *  table only maps a counted noun to a graph INDIVIDUAL CLASS (Module/Class/…);
+ *  an edge-nominalized noun like "tests"/"importers"/"callers" names an EDGE
+ *  KIND instead — ask-vocab.mjs's EDGE_NOUN_TO_METRIC, the SAME table the
+ *  working superlative lane ("which module has the most tests") already reads
+ *  — so it was never in COUNT_NOUNS and answerCount short-circuited straight
+ *  to "I can't count 'tests'" without ever consulting that table. This reuses
+ *  the SAME per-entity degree computation the superlative lane's own
+ *  evalSuperlative uses to rank every entity of a class (ask.mjs's
+ *  degreeMetric, exported for exactly this) — just read for the ONE named
+ *  entity instead of sorting all of them.
+ *
+ *  Checked BEFORE answerCount in runTurn (same precedence pattern as
+ *  answerMemoryCount/answerQuantifierRecall above) so it gets first look;
+ *  declines (returns null, letting answerCount's existing message stand)
+ *  whenever:
+ *    - the noun isn't edge-nominalized at all (a COUNT_NOUNS class, or truly
+ *      unknown), or
+ *    - no entity term could be extracted from the tail
+ *      (extractEdgeCountEntity), or
+ *    - the extracted term doesn't resolve to exactly one graph entity.
+ *
+ *  SCOPED to the per-entity case only: a bare "how many tests are there" (no
+ *  named entity in the tail) has nothing for extractEdgeCountEntity to pull
+ *  out, so it declines here and keeps answerCount's existing "I can't count
+ *  'tests'" honest miss — what a GLOBAL edge count would even mean (every
+ *  test edge in the graph? distinct test modules? distinct tested modules?)
+ *  is a genuine, undecided design question, out of this fix's scope. */
+async function answerEdgeCount(graph, query) {
+  if (!graph) return null;
+  const q = String(query);
+  if (ANAPHORA_COUNT_RE.test(q) || IMPLICIT_ANAPHORA_COUNT_RE.test(q.trim())) return null;
+  const m = q.match(/\b(?:how many|number of|count(?:\s+the)?)\s+([a-z]+)\b/i);
+  if (!m) return null;
+  const noun = m[1].toLowerCase();
+  if (COUNT_NOUNS[noun]) return null; // a real graph class — answerCount owns it
+  const metric = EDGE_NOUN_TO_METRIC[noun];
+  if (!metric) return null; // not edge-nominalized either — answerCount's "I can't count" stands
+  const term = extractEdgeCountEntity(q.slice(m.index + m[0].length), metric);
+  if (!term) return null; // no per-entity phrasing recognized — scoped out (see docblock)
+  const entity = await resolveEntity(graph, term);
+  if (!entity) return null; // unresolved/ambiguous entity — honest decline, not a guess
+  const ind = graph.byId?.get?.(entity.id);
+  if (!ind) return null;
+  let degreeMetric;
+  try { ({ degreeMetric } = await import("./ask.mjs")); } catch { return null; }
+  const n = degreeMetric(graph, ind, metric);
+  return `${n} ${edgeCountNoun(noun, n)}.`;
+}
+
 /** ASSERTED-VOCABULARY count (CHATBENCH_006 lever 3): once "every class is a type"
  *  is remembered, "how many types are there" counts as many types as there are
  *  classes — the asserted object noun inherits the subject class's cardinality.
@@ -869,6 +976,29 @@ export function isConversational(query) {
   return q.split(/\s+/).filter(Boolean).length <= 3 && !codeish;
 }
 
+/** Scoped exemption for the bare-meta-fact lane (2b/2c, further down this file)
+ *  ONLY — never a change to looksCodeish()/isConversational() themselves, and
+ *  never used for the generic orientation-card fallback. HANDOVER.md 2026-07-12
+ *  finding: a bare "what is TaskController?" (CamelCase COMPOUND class name, no
+ *  article) hits looksCodeish()'s `/[a-z][A-Z]/` branch, so isConversational()
+ *  returns false and the whole isConversationalCandidate gate — including the
+ *  bare-meta-fact lookup that "what is a TaskController" (articled, via its own
+ *  T5 structural parse) already resolves through — never runs. Single-word/
+ *  lowercased names ("Widget", "taskcontroller") have no lowercase-to-uppercase
+ *  transition so they were never affected; only two-word-shaped compounds were.
+ *  This re-tests the SAME non-CamelCase codeish reasons (paths, dotted refs,
+ *  `()` calls, STRUCT_WORDS) looksCodeish already covers, so a genuine near-miss
+ *  structural question ("what is foo.bar()", "what is import") is UNCHANGED —
+ *  still excluded here, still falls through to its existing (better) miss
+ *  handling, never the friendly orientation card. */
+function isBareCamelCaseMetaQuestion(query) {
+  const raw = String(query).trim();
+  const q = raw.toLowerCase().replace(/[.!?]+$/, "").trim();
+  const nonCamelCodeish = /[_./]|\(\)/.test(raw) || q.split(/\s+/).some((w) => STRUCT_WORDS.has(w));
+  if (nonCamelCodeish || q.split(/\s+/).filter(Boolean).length > 3) return false;
+  return BARE_WHATIS_RE.test(raw) || IS_ADJECTIVE_YESNO_RE.test(raw);
+}
+
 // ---- the response-template library (W1: templates → render path) ----
 // The WORDING of the conversational/orientation surfaces lives in
 // data/templates/responses.jsonl (corpus/templates.mjs) — the template library is
@@ -3076,7 +3206,17 @@ async function memorySummary(memoryDir, graph) {
 // both already exist. CASE-PRESERVING: module paths/symbol names are
 // case-sensitive, so this reads the ORIGINAL query text, never metaLane's
 // lowercased `q` (authorLane's same discipline, just above/below).
-const MODULE_ORIENT_RE = /^what\s+does\s+(.+?)\s+do\??$/i;
+/** A trailing intensifier/filler adverb tacked onto "do"/"does" ("what does the
+ *  store module do exactly?", "...do exactly", "what X does really") — fast
+ *  loop round 8 (ESL/filler-phrasing angle): the closed-form anchor below used
+ *  to require "do"/"does" to be the LAST word before the optional "?", so this
+ *  one extra word past it hit the raw grammar wall even though the shared
+ *  FILLER_WORDS/normalizeQuery pass (used elsewhere in the file) never sees
+ *  this lane's case-preserving text at all. Mirrors MODULE_ORIENT_POLITENESS_RE
+ *  just below: closed, optional, single-lane blast radius — a bare "what does
+ *  X do" still matches with this suffix empty. */
+const TRAILING_ADVERB_RE = "(?:\\s+(?:exactly|really|actually|anyway))?";
+const MODULE_ORIENT_RE = new RegExp(`^what\\s+does\\s+(.+?)\\s+do${TRAILING_ADVERB_RE}\\??$`, "i");
 /** The SUBJECT-FIRST word order of the SAME question ("what saveStore does" vs
  *  "what does saveStore do") — Tier 6 playtest, §3b surface-variation axis: a
  *  perfectly natural alternate phrasing of an ALREADY-recognized intent that
@@ -3086,7 +3226,7 @@ const MODULE_ORIENT_RE = /^what\s+does\s+(.+?)\s+do\??$/i;
  *  UNIQUE graph entity or this lane declines) is what keeps this loose an
  *  ending safe — a syntactic match against a term that isn't a real entity
  *  simply falls through unchanged, same as every other lane in this file. */
-const MODULE_ORIENT_SVO_RE = /^what\s+(.+?)\s+does\??$/i;
+const MODULE_ORIENT_SVO_RE = new RegExp(`^what\\s+(.+?)\\s+does${TRAILING_ADVERB_RE}\\??$`, "i");
 // Seonix Batch 3 (3a) — purpose/identity phrasing: "whats X for"/"what's X
 // about"/"what is X for", the sibling of "what does X do" that asks for the
 // SAME module-grain overview. Deliberately does NOT claim the literal noun
@@ -3123,10 +3263,22 @@ async function moduleOrientLane(query, { graph }) {
   // do") — plus a lane-local politeness strip for "please explain X" (applyPreambleFrames's
   // own EXPLAIN_WRAPPER_RE requires the string to literally START with "explain",
   // so a LEADING "please"/"kindly" ahead of it defeats that frame; see
-  // MODULE_ORIENT_POLITENESS_RE's own docblock). All three are additive,
+  // MODULE_ORIENT_POLITENESS_RE's own docblock). All four are additive,
   // closed-set, and idempotent on an already-clean query, so applying them here
   // only ever WIDENS what resolves, never narrows it.
-  q = applyPreambleFrames(correctMisspellings(q)).replace(MODULE_ORIENT_POLITENESS_RE, "");
+  //
+  // stripFillerWords (normalize.mjs) joins the set here (deferred fast-loop
+  // finding, closed out for real): a leading discourse filler that applyPreambleFrames'
+  // own LEADING_CONNECTIVE_RE doesn't catch ("so um, like, what does the store
+  // module do exactly?" — the gate right after "so" requires an ALREADY-interrogative
+  // remainder, which "um, like, what does…" isn't) left MODULE_ORIENT_RE's own
+  // "^what does …" anchor unmatched, so this lane silently declined and the
+  // query fell all the way to the tailored-miss wall. Run AFTER applyPreambleFrames
+  // (same order normalizeQuery's own pipeline uses — preamble frames need their
+  // anchor words, like "so"/"please", intact) and BEFORE the politeness regex
+  // (stripFillerWords already eats "please"/"could you" as filler; the politeness
+  // regex only adds the "explain [to me]" wrapper on top).
+  q = stripFillerWords(applyPreambleFrames(correctMisspellings(q))).replace(MODULE_ORIENT_POLITENESS_RE, "");
   const m = q.match(MODULE_ORIENT_RE) || q.match(MODULE_PURPOSE_RE) || q.match(MODULE_ORIENT_SVO_RE);
   if (!m) return null;
   const term = m[1].trim();
@@ -6573,6 +6725,84 @@ async function describeWrapperAnswer(query, { config, source, focus, graph, tel
   }
 }
 
+/** COMPARE (HANDOVER.md 2026-07-12 "no comparison capability" item) — a scoped
+ *  v1: "how is X different from Y", "how does X differ from Y", "compare X and
+ *  Y"/"compare X with/to Y", "what's the difference between X and Y". Five
+ *  closed patterns, same discipline as DESCRIBE_WRAPPER_RE/DETAILED_HOW_WORKS_RE
+ *  above — curated anchors, never a general "any two nouns" catch-all. Named
+ *  capture groups (a/b) so compareAnswer doesn't need to know which pattern
+ *  fired. Tried as a LAST-RESORT rescue (same call-site discipline as (4d)/(4e)
+ *  below) since neither ask.mjs's compositional grammar nor any existing lane
+ *  recognizes a two-entity comparison at all — there is nothing for this to
+ *  shadow. */
+const COMPARE_PATTERNS = [
+  /^how\s+(?:is|are)\s+(?<a>.+?)\s+different\s+from\s+(?<b>.+?)$/i,
+  /^how\s+do(?:es)?\s+(?<a>.+?)\s+differ\s+from\s+(?<b>.+?)$/i,
+  /^how\s+are\s+(?<a>.+?)\s+and\s+(?<b>.+?)\s+different$/i,
+  /^compare\s+(?<a>.+?)\s+(?:and|with|to)\s+(?<b>.+?)$/i,
+  /^(?:what(?:'s|\s+is)\s+the\s+difference\s+between|difference\s+between)\s+(?<a>.+?)\s+and\s+(?<b>.+?)$/i,
+];
+
+/** Strip a leading article — resolveSymbol (codegraph.mjs) has no article
+ *  tolerance of its own (same reasoning as describeGrainRescue's own strip,
+ *  above): "the TaskController" never resolves where "TaskController" does. */
+function stripCompareArticle(term) {
+  return String(term || "").trim().replace(/^(?:the|a|an)\s+/i, "").trim();
+}
+
+/** Resolves both named entities via resolveSymbol (the SAME resolver
+ *  dispatchTool("tmct_describe") uses — no new resolution machinery) and
+ *  renders their comparison via renderCompare (codegraph.mjs), which itself
+ *  reuses describe's own edgesFor/relLabel/capJoin. Returns null when the
+ *  query text doesn't match any COMPARE_PATTERNS shape at all (not this
+ *  lane's turn); otherwise always returns a real, honest answer — either the
+ *  comparison text or a stated reason it couldn't be done (a term didn't
+ *  resolve, or the two resolved to different kinds), never a guess. */
+// Loads its own graph via loadGraph (server.mjs) when runAsk's own `graph`
+// param is null (the common case — see runAsk's own `if (graph && …) … else
+// dispatchTool("tmct_ask", …)` split, above this lane's call site: most
+// turns never get a preloaded graph threaded in; only dispatchTool's OWN
+// tools load one, per call, from config). Declines (returns null) on load
+// failure — a genuinely graph-less repo — the same honest-decline-on-throw
+// pattern describeGrainRescue/describeWrapperAnswer already use.
+async function compareAnswer(query, { graph, config, source }) {
+  const q = String(query || "").trim().replace(/\?+$/, "").trim();
+  let m = null;
+  for (const re of COMPARE_PATTERNS) {
+    m = q.match(re);
+    if (m) break;
+  }
+  if (!m) return null;
+  const termA = stripCompareArticle(m.groups?.a);
+  const termB = stripCompareArticle(m.groups?.b);
+  if (!termA || !termB) return null;
+  let g = graph;
+  if (!g) {
+    try {
+      g = await loadGraph(config, source);
+    } catch {
+      return null; // no graph yet — decline, the ordinary wall stands unchanged
+    }
+  }
+  const { match: indA } = resolveSymbol(g, termA);
+  const { match: indB } = resolveSymbol(g, termB);
+  if (!indA || !indB) {
+    const missing = !indA && !indB ? `"${termA}" and "${termB}" don't` : (!indA ? `"${termA}" doesn't` : `"${termB}" doesn't`);
+    return { text: `I can't compare these — ${missing} resolve to anything in the current artifact.`, ents: [] };
+  }
+  if (indA.id === indB.id) {
+    return { text: `"${indA.label}" and "${indB.label}" resolve to the same entity — nothing to compare.`, ents: [indA] };
+  }
+  const cmp = renderCompare(g, indA, indB);
+  if (!cmp) {
+    return {
+      text: `I can only compare two entities of the SAME kind right now — "${indA.label}" is a ${indA.class || "Entity"} and "${indB.label}" is a ${indB.class || "Entity"}.`,
+      ents: [indA, indB],
+    };
+  }
+  return { text: cmp, ents: [indA, indB] };
+}
+
 /** DETAILED-SUMMARY / EXPLAIN-IN-DETAIL closed phrasings (HANDOVER.md 2026-07-10 item
  *  7) — "give me a detailed summary of how the task system works" / "explain in detail
  *  how X works" / "give me a detailed overview of X". PLAYTESTBENCH_1.4.1.md round 3
@@ -7209,7 +7439,8 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       } catch { /* leave false — the ordinary path decides */ }
     }
   }
-  const isConversationalCandidate = !handled && miss && !envelope?.parsed && isConversational(query) && !isWhatAboutContinuation && !isDescribePronounContinuation && !isExplainTouch && !isStaccatoNegation && !isVagueRelationTouch && !isStaccatoComparative && !isStaccatoPronounNoFocus;
+  const conversationalCandidateBaseGate = !handled && miss && !envelope?.parsed && !isWhatAboutContinuation && !isDescribePronounContinuation && !isExplainTouch && !isStaccatoNegation && !isVagueRelationTouch && !isStaccatoComparative && !isStaccatoPronounNoFocus;
+  const isConversationalCandidate = conversationalCandidateBaseGate && isConversational(query);
   // BUG 2 fix (2026-07-09): "what is X" with NO article ("what is john") is BOTH
   // conversational-shaped (≤3 words, no code-ish token — isConversational() would
   // claim it) AND a legitimate bare meta/fact-lookup form (BARE_WHATIS_RE —
@@ -7240,8 +7471,20 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // chance to run before the orientation card claims the turn.
   const bareWhatisShape = BARE_WHATIS_RE.test(String(query).trim());
   const isAdjectiveShape = IS_ADJECTIVE_YESNO_RE.test(String(query).trim());
+  // HANDOVER.md 2026-07-12 CamelCase finding: `isBareCamelCaseMetaQuestion` (see
+  // its own docblock, above isConversational) OR's in alongside
+  // isConversationalCandidate for THIS lane only — a bare "what is TaskController"
+  // (CamelCase compound, no article) is otherwise excluded solely because
+  // isConversational()'s codeish check fires on the CamelCase transition, even
+  // though every other precondition (miss, no structural parse, no continuation
+  // in flight) already holds. Shares the SAME base gate as isConversationalCandidate
+  // (conversationalCandidateBaseGate) so it's never looser. Scoped to this `if`
+  // alone: the `else if (isConversationalCandidate)` orientation-card fallback
+  // further down is UNCHANGED, so a CamelCase term with no real hit still falls
+  // through to its existing miss handling, never the generic orientation card.
+  const isBareCamelCaseWhatisCandidate = conversationalCandidateBaseGate && isBareCamelCaseMetaQuestion(query);
   let bareMetaHit = null;
-  if (isConversationalCandidate && (bareWhatisShape || isAdjectiveShape)) {
+  if ((isConversationalCandidate || isBareCamelCaseWhatisCandidate) && (bareWhatisShape || isAdjectiveShape)) {
     if (memoryDir) {
       bareMetaHit = (await factAnswer(memoryDir, query, envelope, miss, biasByBundle))
         ?? (await factReadBack(memoryDir, query, envelope, miss, graph, newFocus?.label, biasByBundle));
@@ -7576,6 +7819,32 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       note(trace, "goal: produce a grounded, cited, multi-sentence account of the subject (not a single fact/definition)");
     }
   }
+  // (4f) COMPARE RESCUE (HANDOVER.md 2026-07-12 "no comparison capability" item) —
+  // "how is X different from Y" / "compare X and Y" / "what's the difference
+  // between X and Y": resolves BOTH named entities (resolveSymbol, the same
+  // resolver /describe uses) and renders their comparison (renderCompare,
+  // codegraph.mjs — reuses describe's own edgesFor/relLabel/capJoin, no new
+  // graph traversal). Tried ONLY here, after every other lane declined — same
+  // last-resort discipline as (4d)/(4e) above — since no earlier lane (nor
+  // ask.mjs's compositional grammar) recognizes a two-entity comparison at all,
+  // so there is nothing this could shadow. Always a real answer once its
+  // pattern matches: either the comparison, or an honest stated reason it
+  // couldn't be done (a term didn't resolve, or the two are different kinds) —
+  // never a guess, never a forced comparison across mismatched kinds.
+  if (miss && recordMiss && via === "composed") {
+    const compared = await compareAnswer(query, { graph, config, source });
+    if (compared) {
+      answer = compared.text; via = "compare"; recordMiss = false;
+      note(trace, "lane: (4f) COMPARE RESCUE — a \"how is X different from Y\"/\"compare X and Y\" shape matched, answered via renderCompare (codegraph.mjs)");
+      note(trace, "goal: surface the genuine differences between two named entities' facts/edges");
+      if (compared.ents.length) {
+        const last = compared.ents[compared.ents.length - 1];
+        resolvedIds = compared.ents.map((e) => e.id);
+        newFocus = nextFocus(graph, newFocus, last);
+        note(trace, `result: compare resolved "${query}" -> ${compared.ents.map((e) => e.label).join(" vs ")} — the last-named entity becomes the new focus`);
+      }
+    }
+  }
   // (5) #1 SHORT TAILORED MISS — replace ONLY the engine's full grammar cheat-sheet
   // wall (WALL_MISS_RE). Receipt-bearing misses keep their specific wording.
   // WALL KINDNESS (0.8.2 WS4 (a)): when the PREVIOUS turn's answer was already a
@@ -8010,7 +8279,34 @@ async function assertTurn(line, { memoryDir, sessionId, focus, lexicon = null })
       .map((t) => `${normFactTerm(t.subject)} ${t.predicate} ${normFactTerm(t.object)}`)
       .join("; ");
     const n = res.ids.length;
-    const answer = `noted — remembered ${n} fact${n === 1 ? "" : "s"}: ${shown}`;
+    // PLAN_BREADTH_FIRST_NLU.md (c) / ROADMAP.md "Ambition": a paraphrase of
+    // the confirmation sits NEXT TO the literal one, never instead of it, and
+    // only when its accuracy is checked via syllogise.mjs's own transitive-
+    // closure machinery (paraphrase.mjs's verifySubClassParaphrase) against
+    // the SAME pre-existing taught edges — never an unverified paraphrase.
+    // Scoped to the single-triple rdfs:subClassOf shape (the one predicate
+    // family syllogise.mjs's deriveSubClassClosure reasons over); any other
+    // shape (multi-triple sentences, other predicate families) shows only the
+    // original confirmation, unchanged.
+    let paraphraseSuffix = "";
+    if (res.triples.length === 1 && res.triples[0].predicate === SUBCLASS_PREDICATE) {
+      try {
+        const { paraphraseVerifiedSubClass } = await import("./paraphrase.mjs");
+        // Normalized (same normFactTerm cleanup `shown` above already applies)
+        // so the generated paraphrase text reads like "cache is a kind of
+        // component", never a raw lexicon-prefixed form like "tmct:cache".
+        const newSubj = normFactTerm(res.triples[0].subject);
+        const newObj = normFactTerm(res.triples[0].object);
+        const isTaughtRow = (f) => !f.sourceTypes?.includes("corpus") && !f.sourceTypes?.includes("web");
+        const priorEdges = (await factRows(memoryDir))
+          .filter((f) => f.predicate === SUBCLASS_PREDICATE && isTaughtRow(f)
+            && !(normFactTerm(f.subject) === newSubj && normFactTerm(f.object) === newObj))
+          .map((f) => [normFactTerm(f.subject), normFactTerm(f.object)]);
+        const para = paraphraseVerifiedSubClass(newSubj, newObj, priorEdges);
+        if (para) paraphraseSuffix = ` (${para})`;
+      } catch { /* best-effort — the literal confirmation above is already correct either way */ }
+    }
+    const answer = `noted — remembered ${n} fact${n === 1 ? "" : "s"}: ${shown}${paraphraseSuffix}`;
     // PLAN_BREADTH_FIRST_NLU.md §Track 6 (operator directive): the canonical
     // restatement of what was committed — `english` reuses the SAME confirmation
     // text just shown (already tmct's own preferred subject-predicate-object
@@ -8282,6 +8578,19 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
       return withLast(plainTurn(workingLine, quantifierRecall, { via: "fact", focus }), "recall a taught quantifier");
     }
   }
+  // Edge-nominalized "how many X" counts ("how many tests cover Y", "how many
+  // callers does Y have") — checked BEFORE answerCount (same precedence
+  // pattern as answerQuantifierRecall/answerMemoryCount above): answerCount's
+  // own COUNT_NOUNS table doesn't know these nouns at all and would otherwise
+  // short-circuit straight to "I can't count 'tests'" before this lane ever
+  // got a turn. Declines (null) for anything answerCount should own, or a bare
+  // global count with no named entity — see answerEdgeCount's own docblock.
+  const edgeCount = await answerEdgeCount(graph, workingLine);
+  if (edgeCount != null) {
+    note(trace, 'goal: get a per-entity count of an edge-nominalized kind ("how many tests cover X", "how many callers does X have")');
+    note(trace, "lane: answerEdgeCount — matched an EDGE_NOUN_TO_METRIC noun with a resolvable named entity, answered via the same degreeMetric the superlative lane uses");
+    return withLast(plainTurn(workingLine, edgeCount, { via: "count", focus }), "get a per-entity edge count");
+  }
   // Aggregate/count questions are answered mechanically off the loaded graph header,
   // BEFORE falling through to the ask engine (focus unchanged — a count names no entity).
   const count = answerCount(graph, workingLine);

package/src/codegraph.mjs

@@ -277,6 +277,81 @@ function truncationNote(graph) {
   return `note: partial edge lists for: ${list}. Counts are complete; the lists are not.`;
 }
 
+// ---- compare (scoped v1, HANDOVER.md 2026-07-12 "no comparison capability" item) ----
+
+/** One side-by-side row for a single classified relation (predicate/prop pair),
+ *  in the given direction — reuses edgesFor/relLabel/capJoin verbatim (the SAME
+ *  classified relation groups and edge-cap discipline renderDescribe reads), just
+ *  paired up instead of listed independently per entity. `field` picks the
+ *  correct edge endpoint for the direction (`out` reads the OBJECT end,
+ *  `incoming` reads the SUBJECT end) — edgesFor's own out/incoming split. */
+function compareRow(prefix, key, aEdges, bEdges, labelA, labelB, field) {
+  const fmt = (edges) => (edges.length ? capJoin(edges.map((e) => e[`${field}Label`] || e[field]), DESCRIBE_EDGE_CAP) : "none");
+  return `  ${prefix}${key}: ${labelA} (${aEdges.length}) -> ${fmt(aEdges)}; ${labelB} (${bEdges.length}) -> ${fmt(bEdges)}`;
+}
+
+/** predicate-label -> {group, aEdges, bEdges}, built from BOTH sides' edge
+ *  groups for one direction (out or incoming) — a plain union-by-key merge, no
+ *  new graph query: every group/edges pair here is exactly what edgesFor already
+ *  returned for each individual separately. */
+function pairByPredicate(aGroups, bGroups) {
+  const byPred = new Map();
+  for (const { group, edges } of aGroups) byPred.set(relLabel(group), { group, aEdges: edges, bEdges: [] });
+  for (const { group, edges } of bGroups) {
+    const key = relLabel(group);
+    if (!byPred.has(key)) byPred.set(key, { group, aEdges: [], bEdges: [] });
+    byPred.get(key).bEdges = edges;
+  }
+  return byPred;
+}
+
+/** Compact, honest side-by-side comparison of two SAME-KIND individuals —
+ *  the scoped-down v1 comparison capability (HANDOVER.md 2026-07-12): reuses
+ *  the exact edgesFor/relLabel/capJoin machinery renderDescribe already reads
+ *  (same classified relation groups, same DESCRIBE_EDGE_CAP discipline), just
+ *  rendered as a paired diff instead of two independent one-entity reports —
+ *  no new graph traversal, only a new presentation over data describe already
+ *  surfaces. Deliberately refuses (returns null) rather than forcing a
+ *  comparison across mismatched kinds or the same individual twice — the
+ *  caller (chat.mjs's compare lane) renders its own honest message for those
+ *  cases instead of an empty/degenerate report. */
+export function renderCompare(graph, indA, indB) {
+  if (!indA || !indB || indA.id === indB.id) return null;
+  const klass = indA.class || "Entity";
+  if ((indB.class || "Entity") !== klass) return null;
+
+  const lines = [`Comparing ${indA.label} and ${indB.label} (both ${klass}):`];
+  const a = edgesFor(graph, indA.id);
+  const b = edgesFor(graph, indB.id);
+  const outByPred = pairByPredicate(a.out, b.out);
+  const inByPred = pairByPredicate(a.incoming, b.incoming);
+
+  if (!outByPred.size && !inByPred.size) {
+    lines.push("  edges: none recorded for either in the current artifact.");
+  } else {
+    for (const [key, { aEdges, bEdges }] of outByPred) {
+      lines.push(compareRow("", key, aEdges, bEdges, indA.label, indB.label, "object"));
+    }
+    for (const [key, { aEdges, bEdges }] of inByPred) {
+      lines.push(compareRow("<- ", key, aEdges, bEdges, indA.label, indB.label, "subject"));
+    }
+  }
+
+  // Attribute diff — same key-union approach, but only MISMATCHES are worth
+  // surfacing (a shared attribute value isn't a "difference").
+  const attrsA = new Map((indA.attributes || []).map((x) => [x.key, x.value]));
+  const attrsB = new Map((indB.attributes || []).map((x) => [x.key, x.value]));
+  const attrKeys = new Set([...attrsA.keys(), ...attrsB.keys()]);
+  for (const k of attrKeys) {
+    const va = attrsA.has(k) ? attrsA.get(k) : "(none)";
+    const vb = attrsB.has(k) ? attrsB.get(k) : "(none)";
+    if (va !== vb) lines.push(`  attribute ${k}: ${indA.label} = ${va}; ${indB.label} = ${vb}`);
+  }
+
+  if (graph.truncated.length) lines.push(truncationNote(graph));
+  return lines.join("\n");
+}
+
 // ---- impact (transitive reverse closure over imports/calls) ---------------------
 
 /**

package/src/interpret/normalize.mjs

@@ -152,6 +152,50 @@ export function correctMisspellings(text) {
   return String(text || "").replace(MISSPELLING_RE, (m) => MISSPELLINGS[m.toLowerCase()]);
 }
 
+/** FILLER_WORDS (ask-vocab.mjs), pre-built into one alternation once at module
+ *  load — same "build the regex from the table once, reuse it" discipline as
+ *  every other closed-vocabulary regex in this file (CONTRACTION_RE,
+ *  MISSPELLING_RE, …), rather than rebuilding it inside stripFillerWords on
+ *  every call. */
+const FILLER_RE = FILLER_WORDS.length
+  ? new RegExp(
+      "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b\\s*,?",
+      "gi",
+    )
+  : null;
+
+/** Just the filler/politeness-word strip (ask-vocab.mjs's FILLER_WORDS),
+ *  standalone — the same "one piece of the pipeline, not the whole thing"
+ *  need correctMisspellings above exists for: a caller with its own
+ *  closed anchor regex (chat.mjs's moduleOrientLane matches "^what does …
+ *  do$" itself) wants leading/embedded filler cleared WITHOUT running
+ *  normalizeQuery's other, more invasive rewrites (contraction expansion,
+ *  preamble/subordination/conditional frame rewrites) that can restructure
+ *  the sentence in ways its own shape-matcher never expects — the exact
+ *  risk correctMisspellings' own docblock describes for the same reason.
+ *
+ *  A comma trailing the filler word/phrase itself (across any whitespace,
+ *  e.g. "um, like," or "quickly,") is swallowed WITH it — leading
+ *  conversational filler is routinely comma-spliced onto the real question
+ *  ("so um, like, what does X do exactly?"), and stripping only the word
+ *  leaves the comma stranded as parse-corrupting punctuation debris (a
+ *  leading "," defeats every `^`-anchored template downstream, both parse
+ *  strategies and lane-local regexes alike) — the same species of
+ *  leftover-debris bug the preamble frames elsewhere in this file
+ *  (GREETING_PREAMBLE_RE et al.) already avoid by consuming their own
+ *  delimiter. The trailing `,?` is safe to make unconditional (unlike the
+ *  preamble frames, no delimiter-required gate is needed): it only ever
+ *  fires immediately after a MATCHED filler word, so it can only ever eat a
+ *  comma that was already glued to filler, never a comma separating real
+ *  content ("the modules, and the classes" — that comma sits after the
+ *  content word "modules", not after any filler word). Pure, idempotent;
+ *  unmatched text passes through byte-unchanged. */
+export function stripFillerWords(text) {
+  let q = String(text || "");
+  if (FILLER_RE) q = q.replace(FILLER_RE, " ");
+  return q.replace(/\s+/g, " ").trim();
+}
+
 // ---- closed PREAMBLE frames (0.8.2 feel wave, PLAN_CHAT_FEEL item 2) — the
 // conversational wrapping a developer puts AROUND a real question: a greeting
 // lead-in with a delimiter ("hey there, quick question - …"), a thanks lead-in
@@ -634,13 +678,7 @@ export function normalizeQuery(text) {
   // leaving punctuation/clause debris that poisons the parse.
   q = applySubordinationFrames(q);
   q = applyConditionalFrames(q);
-  if (FILLER_WORDS.length) {
-    const fillerRe = new RegExp(
-      "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
-      "gi",
-    );
-    q = q.replace(fillerRe, " ");
-  }
+  q = stripFillerWords(q);
   // emphatic trailing punctuation (item 10): a run of terminal "?" collapses to
   // one — the anchored templates consume exactly one optional trailing "?", so
   // "…walk.mjs??" otherwise leaks a stray "?" into the captured object term (the