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

package/src/ask.mjs

@@ -62,13 +62,6 @@ import { pickPhrase } from "./answer-variants.mjs";
 
 // Normalization stays importable from its original site (tests + chat surface).
 export { normalizeQuery, applyNegationFrames };
-// The OPTIONAL Node-only wink-nlp adapter (lemma/POS tier). BOUNDARY: the inlined
-// viewer bundle (viz.mjs askSource) strips this import line and never inlines
-// ask-nlp.mjs, so in the browser `nlpAdapter` is simply an undeclared identifier —
-// defaultNlp() below reads it through `typeof`, the one operator that touches an
-// undeclared name without throwing, and the portable single-file HTML degrades to
-// adapter-less parsing (curated tables + bounded fuzzy still on) instead of
-// shipping a ~1MB language model inside the page.
 import { nlpAdapter } from "./ask-nlp.mjs";
 
 /** Per-graph, per-kind memo for THIS file's own edgesOfKind copy — same WeakMap<graph,
@@ -87,15 +80,7 @@ const askEdgesOfKindCache = new WeakMap();
 
 /** All edges of a classified relation kind, flattened across relation groups —
  *  a local copy of codegraph.mjs's private edgesOfKind (kept local rather than
- *  exported+imported to avoid coupling this file's commit boundary to concurrent
- *  in-flight edits elsewhere in codegraph.mjs; both read the same relationKind
- *  classification, so they cannot drift in meaning). Memoized per (graph, kind) —
- *  perf lever, HANDOVER follow-up #8: this is the query engine's hottest path,
- *  called repeatedly on the same (graph, kind) pair across a single query's
- *  compositional evaluation, and at monorepo scale (tens of thousands of modules)
- *  the repeated O(relations) scan is a real latency/GC cost — not a correctness
- *  fix (the stack-overflow bug this file's twin comment references is already
- *  fixed and unrelated). */
+ *  exported+imported to avoid coupling this file's commit. */
 function edgesOfKind(graph, kind) {
   let byKind = askEdgesOfKindCache.get(graph);
   if (!byKind) { byKind = new Map(); askEdgesOfKindCache.set(graph, byKind); }
@@ -145,6 +130,12 @@ const PLURAL_FORMS = {
   // "Change" is ask-vocab.mjs's pseudo-type (a wildcard over the touch traversal's
   // results, never a node class) — it still needs noun forms for zero-hit templates.
   Change: ["change", "changes"],
+  // Memory-graph classes (memory/core.mjs) — real noun forms for the dynamic
+  // class count/list fallback (PLAN_BREADTH_FIRST_NLU.md (d), see
+  // dynamicClassQuery below) so "2 facts." reads naturally instead of falling
+  // back to the generic "2 results.".
+  Fact: ["fact", "facts"], Utterance: ["utterance", "utterances"],
+  Session: ["session", "sessions"], Source: ["source", "sources"], Rule: ["rule", "rules"],
 };
 function nounFor(entityType, n) {
   const [s, p] = PLURAL_FORMS[entityType] || ["result", "results"];
@@ -200,10 +191,7 @@ const LEADING_RELATION_VERB_RE = new RegExp(
 // keeps the winning parse only, byte-identical to the original two-way merge). ----
 
 /** The default lemma/POS adapter: wink-nlp when this is a Node process with the
- *  optional deps installed, null otherwise. BOUNDARY (see the import comment):
- *  the inlined viewer bundle strips the ask-nlp.mjs import, so `nlpAdapter` is
- *  an UNDECLARED identifier there — `typeof` reads it without throwing and the
- *  browser path degrades to no adapter, same parse pipeline otherwise. */
+ *  optional deps installed, null otherwise.. */
 function defaultNlp() {
   return typeof nlpAdapter === "function" ? nlpAdapter() : null;
 }
@@ -312,7 +300,13 @@ export function parseQueryFull(query, { nlp = undefined } = {}) {
 //   {node:"allOfClass", entityType}              — every individual of a class
 //   {node:"reverseSet"|"forwardSet", kind, entityType, inner}  — nested/relative:
 //        the OBJECT (reverse) / SUBJECT (forward) of the outer edge is the id-set
-//        produced by evaluating `inner` (another AST) — two-stage traversal.
+//        produced by evaluating `inner` (another AST) — two-stage traversal. `inner`
+//        is usually a nested relative clause, but {node:"prevSet"} (below) is a
+//        second, discourse-shaped leaf composing with the same union logic.
+//   {node:"prevSet"}                              — the FULL id set of ask()'s own
+//        `prev` (the immediately-preceding list-shaped answer) — a plural pronoun's
+//        ("those"/"them") antecedent, only ever used as reverseSet/forwardSet's
+//        `inner` (see parsePluralAnaphoraObject).
 //   {node:"membership", entityType, term}        — "<entity> of/in <term>"
 //   {node:"qualifier", filters:[word…], inner}   — adjective post-filters on a set
 //   {node:"boolean", entityType, atoms:[{op,kind,ast|filters}…]}  — set algebra
@@ -391,6 +385,7 @@ function parseComposite(text, nlp) {
     || parseFind(w, lc, nlp, 0)
     || parseList(w, lc, nlp, 0)
     || parseNested(w, lc, nlp, 0)
+    || parsePluralAnaphoraObject(w, lc, nlp)
     || parseRelationalOrQualified(w, lc, nlp, 0);
 }
 
@@ -580,6 +575,43 @@ function parseNested(w, lc, nlp, depth) {
   return null;
 }
 
+// PLURAL ANAPHORA OBJECT (HANDOVER.md 2026-07-12 finding: CONTEXT_WORDS/resolveTermOrContext
+// only ever bound a SINGULAR pronoun to ask()'s contextId — "what tests cover those", after a
+// listing turn, fell to an honest miss with the literal word "those" treated as an unresolvable
+// module name). "those"/"them" standing as a BARE pronoun in an ordinary reverse/forward clause
+// ("what tests cover those" — trailing, the reverse OBJECT; "what do those import" — leading, the
+// forward SUBJECT) refer to the FULL id set of the immediately-preceding list-shaped answer —
+// exactly the id array ask()'s own `prev` already threads for parseAnaphora's "of those"/"count
+// them" shapes. Reuses reverseSet/forwardSet's existing multi-object UNION traversal (parseNested,
+// just above) verbatim: the only new thing is a second kind of `inner` leaf, {node:"prevSet"},
+// that reads `prev` instead of evaluating a nested clause.
+//
+// Two positions are recognized, both requiring the pronoun to stand ALONE (never a determiner —
+// "list those functions" is untouched): the sentence's FINAL word (mirrors parseAnaphora's own
+// "count them"/"list them" terminal pinning — the reverse-clause object trails its verb), or
+// immediately followed by a known relation verb (the forward-clause subject leads its verb: "those
+// IMPORT" is unambiguously a pronoun-then-verb, never "those <noun>"). An "of those"/"of them"
+// tail is parseAnaphora's own territory (checked earlier in parseComposite) and is skipped here.
+// After the substitution, `outer.object` is verified to BE the sentinel itself — guards against a
+// keyword-spot retry silently resolving the object to some other word in the sentence instead.
+const PLURAL_ANAPHORA_OBJECT = new Set(["those", "them"]);
+function parsePluralAnaphoraObject(w, lc, nlp) {
+  for (let i = 0; i < lc.length; i += 1) {
+    if (!PLURAL_ANAPHORA_OBJECT.has(lc[i])) continue;
+    if (lc[i - 1] === "of") continue; // "…of those/them" — parseAnaphora's own shape
+    const isTerminal = i === lc.length - 1;
+    const leadsAVerb = i + 1 < lc.length && !!VERB_TO_KIND[lc[i + 1]];
+    if (!isTerminal && !leadsAVerb) continue; // a determiner use ("those functions") — not a bare pronoun
+    const head = [...w.slice(0, i), NEST_SENTINEL, ...w.slice(i + 1)];
+    const outer = parseSimpleClause(head.join(" "), nlp);
+    if (!outer || (outer.shape !== "reverse" && outer.shape !== "forward")) continue;
+    if (outer.object !== NEST_SENTINEL) continue;
+    if (outer.modifier && outer.modifier !== "direct") continue; // no transitive-over-set closure primitive
+    return { node: outer.shape === "reverse" ? "reverseSet" : "forwardSet", kind: outer.kind, entityType: outer.entityType, inner: { node: "prevSet" } };
+  }
+  return null;
+}
+
 // TEMPORAL-OVER-RELATIVE (Phase 11 Track 1, lever 3) — "when did <relative set> [last]
 // change". The flat when-shape (traverse) dates the commits touching ONE resolved term;
 // this composes that same touches→commit→date-sort machinery as an OUTER operator over a
@@ -1856,6 +1888,15 @@ function evalSet(graph, ast, opts) {
       const ids = new Set(evalSet(graph, ast.inner, opts).map((i) => i.id));
       return forwardOverSet(graph, ast.kind, ids);
     }
+    // the previous list-shaped answer's own id set (parsePluralAnaphoraObject's
+    // "those"/"them" leaf) — evalComposite's reverseSet/forwardSet dispatch already
+    // intercepts the genuinely-empty (no `prev` at all) case as an honest "needs a
+    // previous answer" miss, same as evalAnaphora's own no-prev branch; this is only
+    // reached with a real, non-empty `prev` in hand.
+    case "prevSet": {
+      const prev = opts && opts.prev;
+      return Array.isArray(prev) ? prev.map((id) => graph.byId.get(id)).filter(Boolean) : [];
+    }
     case "membership": {
       // DIRECTORY SCOPE ("modules in src/lib", "files in src/handlers"): a bare
       // path term with no exact node of its own is a DIRECTORY, not a single
@@ -2207,6 +2248,14 @@ export function evalComposite(graph, ast, opts = {}) {
       matches: narrow.length ? narrow : broad, broad: !narrow.length && broad.length > 0,
     };
   }
+  // plural-anaphora object (parsePluralAnaphoraObject): a genuinely EMPTY `prev` means
+  // "those"/"them" has no antecedent at all — the same honest "needs a previous answer"
+  // miss evalAnaphora's own no-prev branch gives "of those"/"count them", rather than
+  // evalSet's ordinary (and here misleading) empty-set "nothing in the index matches".
+  if ((ast.node === "reverseSet" || ast.node === "forwardSet") && ast.inner.node === "prevSet"
+    && !(Array.isArray(opts.prev) && opts.prev.length)) {
+    return { compositeMiss: true, reason: "no-prev", matches: [] };
+  }
   return { compositeKind: "set", matches: evalSet(graph, ast, opts), entityType: ast.entityType || null };
 }
 
@@ -2296,7 +2345,10 @@ function renderComposite(parsed, result) {
     // an unscoped list that overflowed the cap gets a light hint to narrow by module —
     // but only for kinds that live IN a module (a "modules in <module>" or "commits in
     // <module>" scope is meaningless); the scoped forms are already narrow, no hint.
-    const scopeable = !["Module", "Commit"].includes(result.entityType);
+    // Memory-graph classes (Fact/Utterance/Session/Source/Rule, dynamicClassQuery
+    // above) never support a module scope either — there's no such parse for them —
+    // so they're excluded here too rather than hinting at an unsupported shape.
+    const scopeable = !["Module", "Commit", "Fact", "Utterance", "Session", "Source", "Rule"].includes(result.entityType);
     const hint = (!result.scoped && scopeable && result.matches.length > OVERFLOW_CAP)
       ? ` — narrow with "${nounFor(result.entityType, 2)} in <module>"`
       : "";
@@ -4412,6 +4464,72 @@ function substituteLastCommitPhrase(graph, query) {
   return BARE_WHEN_COMMIT_RE.test(bareTrimmed) ? `${bareTrimmed} touched` : out;
 }
 
+// ---- dynamic memory-graph class count/list (PLAN_BREADTH_FIRST_NLU.md (d),
+// ROADMAP.md "What's next" (d)): a real "list/count all X of class Y" shape for
+// MEMORY-graph classes (Fact/Utterance/Session/Source/Rule, or any class a taught
+// individual actually carries), reachable via ask.mjs alone — the gap live-testing
+// during the viz chat panel's build confirmed ("how many facts are there"/"list
+// facts"/"what is a Fact" all missed against a real memory graph, since the only
+// working machinery for this shape lived in chat.mjs's heavier factAnswer cascade,
+// out of the browser bundle's ask.mjs-only scope).
+//
+// ENTITY_TO_TYPE (ask-vocab.mjs) is a CLOSED table of code-graph nouns only
+// (module/function/class/…) — memory-graph classes are open-ended (taught, not a
+// fixed vocabulary), so they can't be added to that table the same way. Instead,
+// this resolves the noun against whatever classes ACTUALLY have at least one
+// individual in THIS graph right now (never guesses a class exists with zero
+// evidence — same zero-fabrication discipline as everything else here) and
+// reuses the exact SAME count/list AST + traverse()+render() path every
+// code-graph count/list query already runs through (evalComposite's
+// "allOfClass"/"count"/"list" nodes, already generic over any `individual.class`
+// string — see `evalSet`'s "allOfClass" case and renderComposite's "count"/"list"
+// branches above) — no new render logic, no new miss/hit wording invented.
+//
+// Fires ONLY as a fallback in ask() after the normal cascade already produced an
+// honest miss, and is skipped entirely for any noun ENTITY_TO_TYPE already owns
+// (so a real code-graph "list modules"/"how many classes" answer, including its
+// own honest empty-graph miss wording, is never intercepted or changed).
+function singularCandidates(word) {
+  const w = String(word || "").toLowerCase();
+  const c = new Set([w]);
+  if (w.endsWith("ies")) c.add(`${w.slice(0, -3)}y`);
+  if (w.endsWith("ses")) c.add(w.slice(0, -2));
+  else if (w.endsWith("es")) c.add(w.slice(0, -2));
+  if (w.endsWith("s") && w.length > 1) c.add(w.slice(0, -1));
+  return [...c];
+}
+function resolveDynamicClass(graph, word) {
+  const cands = singularCandidates(word);
+  for (const ind of graph?.individuals || []) {
+    if (ind?.class && cands.includes(String(ind.class).toLowerCase())) return ind.class;
+  }
+  return null;
+}
+const DYNAMIC_LIST_TRIGGER_RE = /^(?:list|show(?:\s+me)?)\s+(?:all\s+|the\s+)?([a-z][a-z'-]*)\s*(.*)$/i;
+const DYNAMIC_COUNT_TRIGGER_RE = /^(?:how\s+many|number\s+of|count(?:\s+the)?)\s+([a-z][a-z'-]*)\s*(.*)$/i;
+// A closed set of harmless trailing fillers ("are there", "do you know", …) — an
+// empty tail is the plain "list facts"/"how many facts" shape; anything else
+// (a real restrictor like "that mention X") is NOT this shape and is left alone
+// so it stays whatever honest miss the normal cascade already produced.
+const DYNAMIC_TAIL_OK_RE = /^(?:are there(?:\s+in\s+total)?|is there|do you know(?:\s+about)?|do you have|exist(?:s)?|are known|in (?:the |a )?(?:graph|memory)|you know(?:\s+about)?)?[?.!\s]*$/i;
+
+/** Compile "list/how many <memory-class-noun>" into the same count/list AST every
+ *  code-graph count/list query already builds, or null when this isn't that shape
+ *  (wrong trigger, a real restrictor tail, ENTITY_TO_TYPE already owns the noun, or
+ *  no individual in THIS graph actually carries that class). */
+function dynamicClassQuery(graph, query) {
+  const q = String(query || "").trim();
+  const listM = q.match(DYNAMIC_LIST_TRIGGER_RE);
+  const countM = !listM ? q.match(DYNAMIC_COUNT_TRIGGER_RE) : null;
+  const m = listM || countM;
+  if (!m || !DYNAMIC_TAIL_OK_RE.test(m[2] || "")) return null;
+  if (ENTITY_TO_TYPE[m[1].toLowerCase()]) return null;
+  const entityType = resolveDynamicClass(graph, m[1]);
+  if (!entityType) return null;
+  const base = { node: "allOfClass", entityType };
+  return listM ? { node: "list", entityType, base, scoped: false } : { node: "count", entityType, base };
+}
+
 export function ask(graph, query, { contextId = null, nlp = undefined, prev = null } = {}) {
   // Explicit help/orientation request → the rephrase hint directly (the honest bottom
   // of the cascade, reached on demand), never a pretend answer or a relaxation attempt.
@@ -4441,8 +4559,21 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
     const r = relaxParse(graph, query, { nlp, contextId, prev });
     if (r) { parsed = r.parsed; relaxed = { from: r.from, to: r.to, dropped: r.dropped, steps: r.steps }; }
   }
-  const result = traverse(graph, parsed, { contextId, prev });
-  const rendered = render(parsed, result);
+  let result = traverse(graph, parsed, { contextId, prev });
+  let rendered = render(parsed, result);
+  // Dynamic memory-graph class count/list fallback (PLAN_BREADTH_FIRST_NLU.md (d))
+  // — fires ONLY once everything above already produced an honest miss, and only
+  // replaces it when the fallback itself produces a real (non-miss) answer, so a
+  // genuine "no X in this index" miss for an ENTITY_TO_TYPE-owned noun is never
+  // touched (dynamicClassQuery declines those itself — see its own doc above).
+  if (rendered.miss && !rendered.ambiguous) {
+    const dyn = dynamicClassQuery(graph, query);
+    if (dyn) {
+      const dynResult = traverse(graph, dyn, { contextId, prev });
+      const dynRendered = render(dyn, dynResult);
+      if (!dynRendered.miss) { parsed = dyn; result = dynResult; rendered = dynRendered; relaxed = null; }
+    }
+  }
   // If relaxation materially rewrote the query and produced a real answer, note it
   // lightly (terse, honest) so the reader knows how the question was read.
   let content = (relaxed && !rendered.miss && relaxed.to !== relaxed.from)

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";
@@ -59,7 +59,7 @@ import {
   VERB_TO_KIND, WHERE_MARKERS, MENTION_MARKERS, ENTITY_TO_TYPE, PASSIVE_PARTICIPLE_TO_KIND,
   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";
 
@@ -3263,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();
@@ -6713,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
@@ -7729,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
@@ -8163,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

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