@polycode-projects/the-mechanical-code-talker 0.8.2 → 0.9.0

package/src/chat.mjs

@@ -52,6 +52,8 @@ import { createTelemetry } from "./telemetry.mjs";
 import * as defaultSource from "./source.mjs";
 import { loadTemplates, render as renderTemplate } from "./corpus/templates.mjs";
 import { finish } from "./finish.mjs";
+import { VERB_TO_KIND, WHERE_MARKERS, MENTION_MARKERS, ENTITY_TO_TYPE } from "./ask-vocab.mjs";
+import { COUNTERFACTUAL_RE } from "./interpret/normalize.mjs";
 
 // uuidv7 lives in ./uuid.mjs (shared with telemetry + the bench stamp); re-exported
 // here because callers/tests still import it from chat.mjs.
@@ -139,6 +141,40 @@ const COMMAND_WORDS = new Set(["stats", "memory", "focus", ...Object.keys(COMMAN
  *  IMPORTING x", "find functions THAT CALL y"). Their presence blocks slash-routing. */
 const QUERY_CONNECTIVES = /\b(that|which|and|or|imports?|importing|calls?|calling|uses?|using|covers?|covering|tests?|testing|touch(?:es|ed|ing)?|inherits?|of|with|from|into|by|most|least)\b/i;
 
+// ---- "find" routing precedence (PLAN_PREDICATE_QUERIES.md) — /find (COMMANDS,
+// tmct_search: a plain lexical search) predates the ask engine's newer
+// predicate-find grammar (parseFind, ask.mjs: "find [me] a/the <term>
+// <entityType>" or "find [me] a/the <entityType> named/called/… <term>",
+// type-filtered ∧ fuzzy property-match — reuses ENTITY_TO_TYPE/LIST_SKIP
+// exactly as parseList does). Both now claim a bare "find …" line, so
+// asBareCommand must pick ONE deterministically — not by incidental word
+// count (a 3-word tail used to fall to the OLD /find while an otherwise
+// identical 4-word tail fell to the NEW grammar: "find the widget class" vs
+// "find me the payment class"). Precedence: when the tail names a real
+// listable entity type in one of parseFind's own two closed shapes, that IS
+// the predicate-find grammar's trigger — defer to it (return null) regardless
+// of length; otherwise (no entity-type noun — a plain name/keyword search)
+// /find keeps its original tmct_search routing. ----
+const FIND_LIST_SKIP = new Set(["the", "a", "an", "all", "me", "us"]);
+const FIND_LINKERS = new Set(["called", "named", "about", "like", "containing", "matching", "with"]);
+
+/** Does a bare "find …" tail look like the ask engine's predicate-find shape
+ *  rather than a plain lexical search? A cheap, read-only proxy for
+ *  parseFind's own trigger (ask.mjs is out of this agent's edit scope this
+ *  pass — ENTITY_TO_TYPE is the SAME table parseFind validates candidates
+ *  against, imported here read-only so both call sites agree on one
+ *  vocabulary). Two closed shapes, mirroring parseFind exactly: trailing-type
+ *  ("<term…> <entityType>", e.g. "the payment class") and
+ *  leading-type-with-linker ("<entityType> <linker> <term…>", e.g. "the class
+ *  named Foo"). */
+function looksLikePredicateFind(restTok) {
+  const toks = restTok.map((w) => w.toLowerCase()).filter((w) => !FIND_LIST_SKIP.has(w));
+  if (!toks.length) return false;
+  if (ENTITY_TO_TYPE[toks[toks.length - 1]]) return true; // trailing-type
+  if (toks.length > 1 && ENTITY_TO_TYPE[toks[0]] && FIND_LINKERS.has(toks[1])) return true; // leading-type-with-linker
+  return false;
+}
+
 /** A bare leading command word → its slash form ("stats" → "/stats", "describe x"
  *  → "/describe x"), so the system commands are slash-optional. Conservative on the
  *  entity/arg commands: it routes a bare word or a SHORT name-like argument, but
@@ -154,6 +190,10 @@ export function asBareCommand(line) {
   const rest = restTok.join(" ");
   // Zero-arg system commands are always the command; a bare command word is too.
   if (!rest || fl === "stats" || fl === "memory") return `/${trimmed}`;
+  // "find" (only — "search", its /find-tool alias, keeps its original behavior
+  // unconditionally): the predicate-find grammar's own shape wins regardless of
+  // word count, see the precedence note above.
+  if (fl === "find" && looksLikePredicateFind(restTok)) return null;
   // A NO-ARGUMENT command word ("untested") with trailing words is NOT a command
   // call — the /untested tool takes no argument and would silently drop the qualifier,
   // listing MODULES for "untested classes". "untested classes" / "untested modules"
@@ -582,6 +622,38 @@ function orientationText(graph) {
     + "/stats for the full overview, /help for commands.";
 }
 
+/** Bug E (0.8.2 follow-up): a friendly, prose-shaped condensation of
+ *  renderDescribe's edge counts (codegraph.mjs) — defines/imports/reexports
+ *  (outgoing from `ind`) + tests (incoming: who covers `ind`) — capped sample,
+ *  matching orientationText's tone rather than reusing /describe's verbose
+ *  block verbatim. A capped sample (not the full renderDescribe dump) because
+ *  this lane answers a casual "what does X do", not a request for the whole
+ *  edge listing (that's what /describe is for — named in the pointer below). */
+const MODULE_OVERVIEW_SAMPLE = 3;
+function moduleOverviewText(graph, ind) {
+  const out = (kind) => edgesOfKind(graph, kind).filter((e) => e.subject === ind.id);
+  const sample = (edges) => {
+    const labels = edges.slice(0, MODULE_OVERVIEW_SAMPLE).map((e) => e.objectLabel || e.object);
+    return edges.length > MODULE_OVERVIEW_SAMPLE
+      ? `${labels.join(", ")}, +${edges.length - MODULE_OVERVIEW_SAMPLE} more`
+      : labels.join(", ");
+  };
+  const defines = out("defines");
+  const imports = out("imports");
+  const reexports = out("reexports");
+  const testedBy = edgesOfKind(graph, "tests").filter((e) => e.object === ind.id);
+  const parts = [];
+  if (defines.length) parts.push(`defines ${defines.length} (${sample(defines)})`);
+  if (imports.length) parts.push(`imports ${imports.length} (${sample(imports)})`);
+  if (reexports.length) parts.push(`exports ${reexports.length} (${sample(reexports)})`);
+  parts.push(testedBy.length
+    ? `covered by ${testedBy.length} test module${testedBy.length === 1 ? "" : "s"}`
+    : "no recorded tests");
+  const cls = (ind.class || "entity").toLowerCase();
+  return `${ind.label} is a ${cls} — ${parts.join("; ")}. `
+    + `/describe ${ind.label} for the full breakdown.`;
+}
+
 // #1 SHORT, TAILORED MISS — the engine's full grammar cheat-sheet (rephraseHint)
 // now lives ONLY behind /help. A genuine parse-miss gets ONE line: an honest miss
 // + at most two example shapes chosen for what the user typed + a /help pointer.
@@ -632,6 +704,14 @@ export function shortMissHint(query) {
  *  (fold.mjs carries its own local copy — the memory layer stays decoupled). */
 export const WALL_MISS_RE = /^couldn't parse this as a graph question\. Try:/;
 
+/** WALL_MISS_RE's non-anchored twin: does the grammar-wall opening appear
+ *  ANYWHERE in the text, not just at its start? A recall-then-wall's own
+ *  `answer` is prefixed with the recall frame ("you asked about this before
+ *  (…):\n  Q: …\n  A: …\n\n"), so the wall-repeat check (Bug A root cause 2,
+ *  0.8.2 follow-up) that inspects the PREVIOUS turn's `last.answer` needs the
+ *  unanchored form to still recognize it as a wall repeat. */
+const WALL_MISS_ANYWHERE_RE = /couldn't parse this as a graph question\. Try:/;
+
 // #2 INTENT LANE — MEMORY/TEACH. "remember that X is a Y", "note that …", or a
 // bare "X is a Y" declarative the graph parser couldn't handle → route to the
 // assert/memory path; when it can't be stored, say what CAN be remembered
@@ -783,12 +863,47 @@ async function memorySummary(memoryDir, graph) {
     + `type${preds.size === 1 ? "" : "s"}. Ask "what do you know about <term>", or /memory to explore.`;
 }
 
+// #2(e) MODULE-GRAIN OVERVIEW (Bug E, 0.8.2 follow-up). META_ORIENT_RE (above)
+// is closed to 5 literal nouns (app/codebase/repo/repository/project) — it
+// cannot match a module path or symbol name by construction, and "do" is
+// deliberately excluded from VERB_TO_KIND everywhere else in the grammar, so
+// "what does app/lib/a.mjs do" hit the grammar wall even though the data
+// (renderDescribe's own edge aggregation) and the resolver (resolveEntity)
+// 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;
+
+/** authorLane's discipline, mirrored: a closed regex + an EXACT, UNIQUE
+ *  resolution via resolveEntity, else null — never a guess. Pronoun/self
+ *  subjects ("what does it/this do") are META_ORIENT_RE's/isConversational's
+ *  territory, not this lane's — declined here so they fall through unchanged. */
+async function moduleOrientLane(query, { graph }) {
+  if (!graph) return null;
+  const q = String(query).trim().replace(/[?.!]+$/, "").replace(/\s+/g, " ");
+  const m = q.match(MODULE_ORIENT_RE);
+  if (!m) return null;
+  const term = m[1].trim();
+  if (/^(?:it|this|that|they|them)$/i.test(term)) return null;
+  const ent = await resolveEntity(graph, term);
+  if (!ent) return null;
+  const ind = graph.byId?.get?.(ent.id);
+  if (!ind) return null;
+  return { text: moduleOverviewText(graph, ind), via: "meta" };
+}
+
 async function metaLane(query, { graph, memoryDir }) {
   const q = String(query).trim().toLowerCase().replace(/[?.!]+$/, "").replace(/\s+/g, " ");
   if (WHAT_KNOW_RE.test(q) || q === "what have you learned" || q === "what have you learnt") {
     return { text: await memorySummary(memoryDir, graph), via: "meta" };
   }
   if (META_ORIENT_RE.test(q)) return { text: orientationText(graph), via: "meta" };
+  // Bug E: an arbitrary "what does <term> do" that META_ORIENT_RE's closed noun
+  // list didn't claim — try the module-grain overview before falling through to
+  // the author-sha check below (disjoint triggers; order doesn't matter, but
+  // this reads MORE of the query shape space, so it goes first).
+  const moduleOrient = await moduleOrientLane(query, { graph });
+  if (moduleOrient) return moduleOrient;
   // 0.8.2 WS4: the sha-authorship form ("who authored a1b2c3d") can be as short as
   // THREE words, which the conversational-orientation branch (step 2) would grab
   // before the author step (4b) is reached — a bare hex sha is not "code-ish" to
@@ -890,11 +1005,113 @@ function nudgeAnswer(query, focus) {
   return null;
 }
 
+// #5(f) PRESUPPOSITION HONEST-NUDGE (ADVANCED_GRAMMAR track f,
+// PLAN_ADVANCED_GRAMMAR.md §2f). "why does a.mjs still import the deprecated
+// store?" presupposes TWO things: (1) a.mjs currently imports store — a real,
+// checkable graph fact; (2) store is "deprecated" — a checkable MEMORY fact
+// (mgx:hasProperty, the teach lane's own "X is <adjective>" shape). We never
+// ACCOMMODATE a presupposition silently (assume it's true and answer around
+// it) — we NAME it, confirmed or refuted, then answer what survives. Same
+// honesty-nudge render precedent as why-untested/opinion above. Closed
+// trigger lexicon (Levinson's classic still/again/anymore family) + the
+// closed VERB_TO_KIND relation-verb table (read-only, ask-vocab.mjs) for the
+// verb split — an unrecognized shape declines (null), never a guess.
+const PRESUPPOSITION_TRIGGER_RE = /^why\s+(?:does|do|is|are)\s+(.+?)\s+(?:still|again|anymore|any\s+more)\s+(.+?)[?.!\s]*$/i;
+
+/** Split a "<verb> <object>" tail on the longest known VERB_TO_KIND phrase
+ *  (2-word phrases tried before 1-word, so "inherits from" wins over a bare
+ *  "inherits"), returning {verb, kind, object} or null when no known relation
+ *  verb opens the tail — the presupposition's relation half is then simply
+ *  not checkable, so the caller declines rather than guessing a kind. */
+function splitVerbObject(tail) {
+  const words = String(tail).trim().split(/\s+/);
+  for (let n = Math.min(2, words.length); n >= 1; n -= 1) {
+    const candidate = words.slice(0, n).join(" ").toLowerCase();
+    if (VERB_TO_KIND[candidate]) {
+      return { verb: candidate, kind: VERB_TO_KIND[candidate], object: words.slice(n).join(" ").trim() };
+    }
+  }
+  return null;
+}
+
+/** The presupposition-nudge answer for a would-miss "why … still/again …"
+ *  query, or null (declines — never a guess — when the subject/object don't
+ *  resolve to real graph entities, or no known relation verb opens the tail).
+ *  Presupposition (1) is checked against the GRAPH (exhaustive, so a "no" is
+ *  a confident, non-miss answer, not a shrug); presupposition (2) — an
+ *  optional embedded 2-word object ("the DEPRECATED store") — is checked
+ *  against MEMORY facts (mgx:hasProperty) and is honestly "no fact saying so"
+ *  when absent, never assumed. Returns {text} or null.
+ *
+ *  WOULD-MISS ONLY, matching every other lane in this file (never hijack a
+ *  real answer): "why does X import Y" already has a real, working grammar
+ *  answer when the relation HOLDS ("Yes — imports edge from X to Y",
+ *  miss:false) — that answer is correct and this lane must not shadow it. The
+ *  relation-holds case an honest "No — no <kind> edge found …" is recorded as
+ *  a MISS by the base engine's own empty-result convention, so THAT is where
+ *  this lane adds real value: naming the presupposition explicitly (subject,
+ *  predicate, object — and the embedded property claim, if any) rather than
+ *  the plainer receipt. */
+async function presuppositionNudge(query, { graph, memoryDir }) {
+  if (!graph) return null;
+  const m = String(query).trim().replace(/[?.!]+$/, "").match(PRESUPPOSITION_TRIGGER_RE);
+  if (!m) return null;
+  const split = splitVerbObject(m[2]);
+  if (!split) return null;
+  const rawObject = split.object.replace(/^(?:the|a|an)\s+/i, "").trim();
+  const objWords = rawObject.split(/\s+/);
+  const hasAdjective = objWords.length === 2;
+  const entityTerm = hasAdjective ? objWords[1] : rawObject;
+  const adjective = hasAdjective ? objWords[0].toLowerCase() : null;
+
+  const subjEnt = await resolveEntity(graph, m[1].trim());
+  const objEnt = await resolveEntity(graph, entityTerm);
+  if (!subjEnt || !objEnt) return null; // can't check the presupposition — decline, never guess
+
+  const holds = edgesOfKind(graph, split.kind).some((e) => e.subject === subjEnt.id && e.object === objEnt.id);
+  const lines = [
+    `checking the presupposition first: ${subjEnt.label} does${holds ? "" : "n't"} ${split.verb} ${objEnt.label} (${holds ? "yes" : "no"})`,
+  ];
+  if (adjective) {
+    let propHit = null;
+    if (memoryDir) {
+      let normFactTerm;
+      try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { normFactTerm = null; }
+      if (normFactTerm) {
+        const facts = await memoryFacts(memoryDir);
+        const subjMatches = (f) => normFactTerm(f.subject) === normFactTerm(entityTerm);
+        // Two shapes a taught "<X> is <adjective>" can land as: the teach
+        // lane's mgx:hasProperty (subject/object) fact, or — when the
+        // adjective is a known ACE-OWL lexicon data-property word (e.g.
+        // "deprecated", grammar/lexicon-core.json) — the ACE grammar's own
+        // tmct:<adjective> "true" data-property triple (assertTurn tries ACE
+        // FIRST, so this is the more common real path for a lexicon word).
+        propHit = facts.find((f) => subjMatches(f)
+          && ((f.predicate === HAS_PROPERTY_PREDICATE && normFactTerm(f.object) === adjective)
+            || (f.predicate === `tmct:${adjective}` && f.object === "true"))) || null;
+      }
+    }
+    lines.push(`${objEnt.label} ${adjective} — ${propHit ? `yes (source: ${propHit.provenance})` : "I have no fact saying so"}`);
+  }
+  const verdict = lines.join("; ");
+  return { text: holds ? `${verdict}. ${subjEnt.label} does ${split.verb} ${objEnt.label}.` : `${verdict} — the premise doesn't hold.` };
+}
+
 /** The wall-repeat one-liner (0.8.2 WS4 wall kindness (a)). MUST NOT match
  *  WALL_MISS_RE: the suppression keys on the PREVIOUS answer matching it, so this
  *  text self-limits — a third consecutive miss re-offers the tailored hint. */
 const WALL_REPEAT_ONELINER = "still couldn't parse that — /help lists every query shape.";
 
+/** The orientation-repeat one-liner (Bug B1, 0.8.2 follow-up). The conversational
+ *  orientation branch sits OUTSIDE the composed-only wall-shortening gate (it
+ *  carries via:"template", never "composed"), so it never shortened on a second
+ *  identical turn the way a plain wall does. MUST be a different string from
+ *  orientationAnswer's own output (checked by identity, not regex, since the
+ *  orientation text is templated/graph-dependent) so this self-limits exactly
+ *  like WALL_REPEAT_ONELINER: a third consecutive orientation-class turn
+ *  re-offers the full orientation instead of droning the one-liner forever. */
+const ORIENTATION_REPEAT_ONELINER = "still the same overview — /help lists every command and query shape.";
+
 // ---- repo-root resolution: default the target to the GIT ROOT, not raw cwd ----
 
 /** The git top-level for `cwd`, or null if not in a repo (or git is unavailable).
@@ -996,15 +1213,50 @@ function uuidv7Day(id) {
  *  earlier recall, never fresh content (nested recall-of-recall hygiene). */
 const RECALL_PREAMBLE_RE = /^you asked about this before/;
 
-/** Pick the recalled block's Q/A pair most relevant to the query (content-word
- *  overlap; ties → first). Null when nothing qualifies — the block matched on
- *  packaging, not substance, so the honest miss must stand. Recall HYGIENE
- *  (0.8.2): only a pair with a SUBSTANTIVE answer is recallable — a Q-only pair,
- *  a grammar-wall answer (WALL_MISS_RE) or a prior recall frame (nested
- *  recall-of-recall) is skipped; and the shared overlap must carry at least one
- *  dotted path/file token or ≥2 plain content words, so "src"/"mjs"-grade noise
- *  never bridges two unrelated questions. */
-function bestQaPair(blockText, query) {
+/** Predicate-class content words bestQaPair requires a SHARED token from (Bug A
+ *  entity∧predicate conjunction fix, 0.8.2 follow-up): every phrase in
+ *  VERB_TO_KIND (ask-vocab.mjs's code-graph relation vocabulary — read-only
+ *  reference here, never edited) split into its content words, PLUS the
+ *  where/mention markers from the same file, PLUS chat.mjs's own ownership
+ *  predicate ("owns"/"maintains", WHO_OWNS_RE/OWNS_TEACH_RE below) — a real,
+ *  distinct predicate class the graph-relation table doesn't carry. Without this
+ *  last pair, a stored "who touched X" and a live "who owns X" share no
+ *  predicate word at all (which already rejects them) but neither could a
+ *  genuine "who owns X" repeat ever recall itself. */
+const PREDICATE_WORDS = new Set(
+  [
+    ...Object.keys(VERB_TO_KIND).flatMap((phrase) => phrase.split(/[\s-]+/)),
+    ...WHERE_MARKERS, ...MENTION_MARKERS,
+    "owns", "maintains",
+  ].filter((w) => w.length >= 3),
+);
+
+/** Does `word` identify a graph ENTITY the two questions share — a dotted/path
+ *  token (the cheap, always-available signal) or a bare term that resolves to a
+ *  real graph individual (so a shared bare name, not just a shared directory
+ *  segment, counts too). Failure-tolerated: no graph / no resolution → false,
+ *  never a throw. */
+async function isSharedEntityToken(word, graph) {
+  if (word.includes(".")) return true;
+  if (!graph) return false;
+  const ent = await resolveEntity(graph, word);
+  return !!ent;
+}
+
+/** Pick the recalled block's Q/A pair most relevant to the query. Null when
+ *  nothing qualifies — the block matched on packaging, not substance, so the
+ *  honest miss must stand. Recall HYGIENE (0.8.2, tightened in the 0.8.2
+ *  follow-up): only a pair with a SUBSTANTIVE answer is recallable — a Q-only
+ *  pair, a grammar-wall answer (WALL_MISS_RE) or a prior recall frame (nested
+ *  recall-of-recall) is skipped. The acceptance test is an explicit CONJUNCTION,
+ *  not the old OR-shaped word-overlap count: at least one shared
+ *  entity-identifying token (isSharedEntityToken) AND at least one shared
+ *  predicate-class word (PREDICATE_WORDS) — so a stored "who touched X" can
+ *  never recall onto a live "who owns X" (predicate mismatch, entity token
+ *  still shared) and a stored "who owns X" can never recall onto "who owns Y"
+ *  (predicate matches, entity token doesn't — a shared directory segment used
+ *  to satisfy the old ≥2-word branch on its own). */
+async function bestQaPair(blockText, query, graph) {
   const qWords = recallWords(query);
   const pairs = [];
   let open = null;
@@ -1017,7 +1269,13 @@ function bestQaPair(blockText, query) {
   for (const p of pairs) {
     if (!p.a || WALL_MISS_RE.test(p.a) || RECALL_PREAMBLE_RE.test(p.a)) continue;
     const shared = [...recallWords(p.q)].filter((w) => qWords.has(w));
-    if (!shared.some((w) => w.includes(".")) && shared.length < 2) continue;
+    if (!shared.length) continue;
+    if (!shared.some((w) => PREDICATE_WORDS.has(w))) continue;
+    let hasEntity = false;
+    for (const w of shared) {
+      if (await isSharedEntityToken(w, graph)) { hasEntity = true; break; }
+    }
+    if (!hasEntity) continue;
     if (shared.length > bestScore) { best = p; bestScore = shared.length; }
   }
   return best;
@@ -1029,13 +1287,13 @@ function bestQaPair(blockText, query) {
  *  recall only ever fires with a substantive recalled A (bestQaPair's hygiene),
  *  so it is never prepended to a reply that is itself a miss going to record.
  *  Lazy + failure-tolerated (chat.mjs ethos): a broken store degrades to null. */
-async function recallFromBlocks(memoryDir, query) {
+async function recallFromBlocks(memoryDir, query, graph) {
   try {
     const { retrieveBlocks } = await import("./memory/blocks.mjs");
     const hits = await retrieveBlocks(memoryDir, query, RECALL_TOP_K);
     const best = hits[0];
     if (!best || best.score < RECALL_MIN_SCORE || !best.text) return null;
-    const pair = bestQaPair(best.text, query);
+    const pair = await bestQaPair(best.text, query, graph);
     if (!pair) return null;
     const day = uuidv7Day(best.id);
     const cite = `session ${String(best.id).slice(0, 8)}${day ? `, ${day}` : ""}`;
@@ -1135,6 +1393,84 @@ function factTermVariants(normFactTerm, term) {
   return v;
 }
 
+// ---- PLAN_ontology-hierarchies.md §3 tracks (a)+(b): synonymsOf(term) —
+// QUERY-TIME term expansion wiring the two already-parsed-but-inert synonym
+// resources. §1's "two vocabulary gates" distinction: this widens what a
+// vocabulary QUESTION can be matched against (the memory fact/corpus term
+// space), never what parseAce can TEACH (the ACE lexicon gate is untouched —
+// src/grammar/lexicon-core.json is out of this agent's scope regardless). A
+// synonym-expansion hit ALWAYS renders its licensing source visibly — never a
+// silent substitution (the confident-wrong discipline every other lane here
+// already follows). ----
+
+/** term (lowercased, unnormalized — the caller normalizes) -> [{variant,
+ *  source}], built once from two committed-but-unconsumed resources:
+ *    (a) the ConceptNet slice's /r/Synonym + /r/SimilarTo rows — deliberately
+ *        gated `ace = "none"` in conceptnet-map.toml (never emitted as a
+ *        memory FACT; that gate is about fact emission, not about whether the
+ *        raw slice data exists — the map's own note names "the grammar
+ *        lexicon / phrasebook synonym families" as this data's real consumer)
+ *    (b) loadPhrasebook()'s already-parsed `synonyms` families
+ *        (corpus/templates.mjs, parsed + tested but never called outside its
+ *        own test until now)
+ *  PRECISION PASS (PLAN_ontology-hierarchies.md §3 track a: "start with a
+ *  precision-reviewed subset ... not a blind bulk activation"): a spot check
+ *  of the raw /r/Synonym slice showed the noise concentrates in multi-word /
+ *  punctuated endpoints (generic-English senses, proper-noun collisions); this
+ *  index admits only SINGLE-WORD, purely-alphabetic ConceptNet endpoints on
+ *  BOTH sides of a row — a first-cut heuristic filter, not a full manual
+ *  review of all 1,228 rows (a natural follow-up, not claimed as done here).
+ *  Lazy + failure-tolerated: a missing/broken corpus file degrades to an
+ *  empty (or phrasebook-only) index, never a throw. */
+let synonymIndexCache = null;
+async function synonymIndex() {
+  if (synonymIndexCache) return synonymIndexCache;
+  const index = new Map();
+  const add = (a, b, source) => {
+    const ta = String(a || "").trim().toLowerCase();
+    const tb = String(b || "").trim().toLowerCase();
+    if (!ta || !tb || ta === tb) return;
+    if (!index.has(ta)) index.set(ta, []);
+    if (!index.get(ta).some((e) => e.variant === tb)) index.get(ta).push({ variant: tb, source });
+    if (!index.has(tb)) index.set(tb, []);
+    if (!index.get(tb).some((e) => e.variant === ta)) index.get(tb).push({ variant: ta, source });
+  };
+  try {
+    const { loadSlice, loadMap, termText } = await import("./corpus/conceptnet.mjs");
+    const [assertions, map] = await Promise.all([loadSlice(), loadMap()]);
+    const SINGLE_WORD_RE = /^[a-z]+$/;
+    for (const a of assertions) {
+      if (a.rel !== "/r/Synonym" && a.rel !== "/r/SimilarTo") continue;
+      if (!map.has(a.rel)) continue; // drift-guarded elsewhere; tolerate here
+      const start = termText(a.start);
+      const end = termText(a.end);
+      if (!start || !end || !SINGLE_WORD_RE.test(start) || !SINGLE_WORD_RE.test(end)) continue;
+      add(start, end, `corpus:conceptnet ${a.rel}`);
+    }
+  } catch { /* corpus unavailable — degrade gracefully */ }
+  try {
+    const { loadPhrasebook } = await import("./corpus/templates.mjs");
+    const { synonyms } = await loadPhrasebook();
+    for (const family of synonyms) {
+      for (let i = 0; i < family.length; i += 1) {
+        for (let j = i + 1; j < family.length; j += 1) add(family[i], family[j], "corpus:phrasebook");
+      }
+    }
+  } catch { /* tolerated */ }
+  synonymIndexCache = index;
+  return index;
+}
+
+/** Known synonyms of `term` (case-insensitive), each `{variant, source}` — []
+ *  when nothing is known. Callers widen a failed factTermVariants lookup with
+ *  these variants ONLY on a direct miss, and MUST cite `source` in the
+ *  rendered answer (synonymFactAnswer, below factAnswer, is the reference
+ *  consumer). */
+async function synonymsOf(term) {
+  const index = await synonymIndex();
+  return index.get(String(term || "").trim().toLowerCase()) || [];
+}
+
 /** "is a module a component" — the yes/no vocabulary form the graph grammar
  *  doesn't parse; checked against the isa-family fact predicates only. */
 const ISA_ASK_RE = /^(?:is|are)\s+(?:an?\s+)?(.+?)\s+(?:a\s+kind\s+of|a\s+type\s+of|an?)\s+(.+?)[?.!\s]*$/i;
@@ -1207,6 +1543,40 @@ async function factAnswer(memoryDir, query, envelope, miss) {
   return null;
 }
 
+/** Ontology plan tracks (a)+(b) (PLAN_ontology-hierarchies.md §3): a LAST-
+ *  RESORT query-time synonym expansion for a "what is a X"-shaped term with NO
+ *  direct facts. Deliberately run where the caller runs it (runAsk, after
+ *  curatedDefinitionAnswer/conceptForceAnswer have ALL had their full chance,
+ *  gated on `via === "composed"` still standing) rather than inside factAnswer
+ *  itself: ask()'s own grammar parses EVERY "what is a X" as shape:"meta" with
+ *  miss:true, even when conceptForceAnswer goes on to answer it for real from
+ *  SEON instance data — gating on miss alone (tried and reverted) is not
+ *  enough to avoid hijacking that real answer with an unrelated synonym's
+ *  taught fact; running LAST, only once nothing else answered, is the actual
+ *  guard. ALWAYS renders a visible prefix naming the synonym term AND the
+ *  corpus row that licensed the match — never a silent substitution. Returns
+ *  { text } or null. Lazy + failure-tolerated throughout. */
+async function synonymFactAnswer(memoryDir, query, envelope) {
+  if (!memoryDir) return null;
+  const term = metaTermOf(query, envelope);
+  if (!term) return null;
+  let normFactTerm;
+  try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
+  const facts = await memoryFacts(memoryDir);
+  for (const { variant, source } of await synonymsOf(term)) {
+    const variants = factTermVariants(normFactTerm, variant);
+    const hits = facts.filter((f) => variants.has(f.subject));
+    if (!hits.length) continue;
+    const lines = hits.map(renderFactLine);
+    const shown = lines.slice(0, FACT_ANSWER_CAP);
+    const rest = lines.slice(FACT_ANSWER_CAP);
+    const extra = rest.length ? `\n…and ${rest.length} more — say 'more' to see them.` : "";
+    const prefix = `no direct facts about "${term}" — showing its known synonym "${variant}" (source: ${source}):\n`;
+    return { text: prefix + shown.join("\n") + extra, ...(rest.length ? { pending: { items: rest, noun: "facts" } } : {}) };
+  }
+  return null;
+}
+
 /** "what did i tell you about X" — the multi-turn recall phrasing (a sibling of
  *  factAnswer's "what do you know about X" KNOW_ABOUT form): everything remembered
  *  that mentions X on either side. */
@@ -1399,6 +1769,29 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null) {
   return renderMany(hits);
 }
 
+/** Bug B4 (0.8.2 follow-up): taught facts about ONE resolved entity, trust-
+ *  ranked and rendered the same way factReadBack's own lines are — the seam
+ *  `/describe` was missing. `renderDescribe` (codegraph.mjs) and `dispatchTool`
+ *  (server.mjs) never receive `memoryDir`, so ACE-taught facts about the
+ *  resolved entity were architecturally invisible to `/describe`; this reads
+ *  memory directly and the CALLER (runCommand) appends the result to
+ *  renderDescribe's own output, mirroring the ask-path's existing
+ *  `factAnswer(...) ?? factReadBack(...)` append discipline rather than
+ *  threading memoryDir through the pure describe renderer itself. Subject-side
+ *  only (a `/describe` names ONE code entity as the subject of its own facts,
+ *  not every fact that merely mentions it in passing) — null when memory holds
+ *  nothing about this subject. */
+async function describedFacts(memoryDir, label) {
+  let normFactTerm;
+  try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
+  const rows = await factRows(memoryDir);
+  if (!rows.length) return null;
+  const variants = factTermVariants(normFactTerm, label);
+  const hits = rows.filter((f) => variants.has(f.subject)).sort((a, b) => b.trust - a.trust);
+  if (!hits.length) return null;
+  return `taught facts:\n${hits.map((f) => `  ${renderFactLine(f)}`).join("\n")}`;
+}
+
 // ---- W5: corpus on-demand — LOCAL tier only, behind an explicit flag ----
 
 /** The opt-in env flag: TMCT_CORPUS_LOOKUP=1 lets an unknown-term miss consult
@@ -1837,7 +2230,13 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   if (!handled && miss && isConversational(query)) {
     // A conversational miss (a greeting, "what can you do", a very short non-code
     // line) gets the friendly orientation (module-aware: empty → --repo/tmct init).
-    answer = orientationAnswer(templates, graph); via = "template"; handled = true;
+    // Bug B1 (0.8.2 follow-up): this branch carries via:"template" and never
+    // reaches the composed-only wall-shortening gate below, so a second
+    // identical orientation-class turn used to repeat the full blurb verbatim —
+    // collapse to a one-liner on that repeat, mirroring WALL_REPEAT_ONELINER.
+    const orientation = orientationAnswer(templates, graph);
+    answer = (last?.answer === orientation) ? ORIENTATION_REPEAT_ONELINER : orientation;
+    via = "template"; handled = true;
   } else if (!handled && memoryDir) {
     // W4: vocabulary/definition questions consult the MEMORY graph's Facts alongside
     // the schema-docs surface — a remembered fact answers a miss OR extends a (non-
@@ -1856,9 +2255,25 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       // W2: after the honest miss is composed, consult the folded-session memory. A
       // relevant enough block ANSWERS — recalled Q/A framed + cited first, with the
       // engine's own miss hint kept below; no hit leaves the miss byte-unchanged.
-      const recalled = await recallFromBlocks(memoryDir, query);
+      const recalled = await recallFromBlocks(memoryDir, query, graph);
       if (recalled) {
-        answer = `${recalled}\n\n${answer}`;
+        // Bug A root cause 2 (0.8.2 follow-up): a successful recall always sets
+        // recordMiss = false below, which is the SAME flag the composed-path
+        // wall-shortening pass (further down) gates on — so a recall-then-wall
+        // combo used to carry the full, un-shortened grammar-cheat-sheet dump on
+        // every repeat, never collapsing to shortMissHint/WALL_REPEAT_ONELINER the
+        // way a plain wall does. Apply the identical shortening/repeat-suppression
+        // logic to the TRAILING miss text here, keyed off the same WALL_MISS_RE +
+        // `last` check (using the non-anchored twin, since a repeated
+        // recall-then-wall's own last answer is itself prefixed with the recall
+        // frame, not starting with the wall text).
+        let trailing = answer;
+        if (WALL_MISS_RE.test(trailing)) {
+          trailing = (last?.answer && WALL_MISS_ANYWHERE_RE.test(String(last.answer)))
+            ? WALL_REPEAT_ONELINER
+            : shortMissHint(query);
+        }
+        answer = `${recalled}\n\n${trailing}`;
         via = "recall";
         recordMiss = false; // memory answered it, cited — no longer a blank
       }
@@ -1908,6 +2323,19 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       }
     }
   }
+  // (3b) ONTOLOGY SYNONYM EXPANSION (PLAN_ontology-hierarchies.md §3 tracks
+  // a+b) — a LAST-RESORT vocabulary-term retry via known synonyms, tried only
+  // once composed/fact/corpus-seon have ALL declined (via === "composed" still
+  // standing here), so it can never hijack a real schema/concept-force answer
+  // (see synonymFactAnswer's own docblock for why gating on miss alone isn't
+  // enough). Every hit cites its synonym term + licensing corpus source.
+  if (miss && recordMiss && via === "composed") {
+    const syn = await synonymFactAnswer(memoryDir, query, envelope);
+    if (syn) {
+      answer = syn.text; via = "fact"; recordMiss = false;
+      if (syn.pending) factPending = syn.pending;
+    }
+  }
   // (4) #2 TEACH lane — a teach-shaped would-miss nothing above answered: route to
   // memory, or say what CAN be remembered (LOUD), never the wall / a silent drop.
   if (miss && recordMiss && via === "composed") {
@@ -1923,6 +2351,15 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     const authored = authorLane(query, { graph });
     if (authored) { answer = authored.text; via = authored.via; recordMiss = false; }
   }
+  // (4b2) #5(f) PRESUPPOSITION HONEST-NUDGE (ADVANCED_GRAMMAR track f) — "why
+  // does X still/again import Y": names the presupposition being checked
+  // (against the graph, confidently) before answering what survives. A
+  // CONFIRMED presupposition is a real answer (recordMiss:false); a REFUTED
+  // one is still an honest, confident correction, not a miss.
+  if (miss && recordMiss && via === "composed") {
+    const presup = await presuppositionNudge(query, { graph, memoryDir });
+    if (presup) { answer = presup.text; via = "presupposition"; recordMiss = false; }
+  }
   // (4c) CAPABILITY NUDGES (0.8.2 WS4) — risk scoring / code opinions / "write me
   // code" imperatives / motive-"why": an honest wall pointing at the nearest real
   // query shapes. recordMiss stays TRUE — a capability wall is still a miss and
@@ -1961,6 +2398,20 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       via = "corpus";
     }
   }
+  // ADVANCED_GRAMMAR track (a) — counterfactual marker (PLAN_ADVANCED_GRAMMAR.md
+  // §2a): "if X were deleted, what would break" compiles to a REAL traversal
+  // (interpret/normalize.mjs's COUNTERFACTUAL_RE rewrite, "which modules
+  // transitively import X") — but the consequent is hypothetical, so a plain
+  // traversal answer would over-claim it as present-tense fact. normalize.mjs
+  // only rewrites the QUESTION; this names the SAME raw query shape here (the
+  // one seam that sees both the original text and the final answer) and marks
+  // the answer as conditional. Gated to a genuine non-miss composed traversal
+  // — a counterfactual that happens to miss keeps its ordinary honest-miss
+  // wording, never a fabricated "hypothetically" wrapper around a blank.
+  const counterfactualSubject = String(query).trim().match(COUNTERFACTUAL_RE);
+  if (!recordMiss && via === "composed" && counterfactualSubject) {
+    answer = `hypothetically, if ${counterfactualSubject[1].trim()} were removed: ${answer}`;
+  }
   // The concept force answers WITH real example instances — those are the entities the
   // turn "asked about" (the SchemaClass meta-node is documentation, not a code entity),
   // so record + expand them, not the schema match.
@@ -2061,7 +2512,17 @@ async function runCommand(line, { config, source, graph, focus, memoryDir }) {
     // Same class-gate as the ask path (nextFocus): a command whose arg resolves to a
     // Commit/Session/schema node records the resolution but does not displace a
     // standing code-entity focus that "it" is meant to keep binding to.
-    if (ent) return mk(answer, { resolvedIds: [ent.id], newFocus: nextFocus(graph, focus, ent) });
+    if (ent) {
+      // Bug B4 (0.8.2 follow-up): /describe's code-map render never sees memory,
+      // so a taught fact about the resolved entity is invisible to it — append
+      // matching taught facts (subject === the resolved entity, trust-ranked)
+      // under the code-map answer, mirroring the ask-path's fact-append pattern.
+      if (name === "describe" && memoryDir) {
+        const facts = await describedFacts(memoryDir, ent.label);
+        if (facts) answer = `${answer}\n${facts}`;
+      }
+      return mk(answer, { resolvedIds: [ent.id], newFocus: nextFocus(graph, focus, ent) });
+    }
   }
   return mk(answer);
 }
@@ -2456,10 +2917,26 @@ export async function createSession({
     promptFor: () => promptFor(focus),
 
     /** One dispatched turn through the FULL sink sequencing (writeLog → writeSidecar
-     *  → telemetry → upsertGraph, in that exact order). Returns { answer, end, prompt }. */
+     *  → telemetry → upsertGraph, in that exact order). Returns { answer, end, prompt }.
+     *  A throwing runTurn must never abort the session: a piped/non-interactive driver
+     *  has no other chance to see this turn's answer, and losing the catch here also
+     *  skips session.close() upstream, leaving the log/sidecar streams unflushed for
+     *  every LATER turn too — found live via a piped-stdin driver hitting a bad turn. */
     async turn(line) {
-      const { answer, logLines, record, focus: nextFocus, last: nextLast, end } =
-        await runTurn(line, { config, source, graph, focus, last, memoryDir: repo, sessionId, env, lexicon });
+      let result;
+      try {
+        result = await runTurn(line, { config, source, graph, focus, last, memoryDir: repo, sessionId, env, lexicon });
+      } catch (e) {
+        const ts = new Date().toISOString();
+        const message = e instanceof Error ? e.message : String(e);
+        await writeLog(`${ts}\n> ${line}\nerror: ${message}\n`);
+        const errorRecord = { type: "error", ts, query: line, error: message };
+        await writeSidecar(errorRecord);
+        turnRecords.push(errorRecord);
+        turns += 1;
+        return { answer: `Something went wrong answering that (${message}). Try rephrasing, or /help.`, end: false, prompt: promptFor(focus) };
+      }
+      const { answer, logLines, record, focus: nextFocus, last: nextLast, end } = result;
       focus = nextFocus;
       last = nextLast;
       await writeLog(logLines.join("\n") + "\n");
@@ -2522,19 +2999,27 @@ export async function runChat({
   const prompt = () => { if (!closed) rl.prompt(); }; // input may end while a turn is in flight
 
   prompt();
-  for await (const raw of rl) { // Ctrl+D / closed stdin ends the iteration cleanly
-    const line = raw.trim();
-    if (line === "/exit") break;
-    if (line) {
-      const { answer, end, prompt: nextPrompt } = await session.turn(line);
-      output.write(answer + "\n");
-      rl.setPrompt(nextPrompt);
-      if (end) break; // a conversational "bye"/"goodbye" — clean end, same as /exit
+  // try/finally: session.close() is the ONLY code path that writes end-markers and
+  // flushes the log/sidecar write streams (stream.end()/sidecar.end()) — an
+  // unhandled throw anywhere in the loop body must still reach it, or a
+  // piped/non-interactive run can lose buffered writes outright, not just this
+  // turn's data. session.turn() now catches its own errors (see createSession),
+  // so this is defense in depth for anything else that might throw here.
+  try {
+    for await (const raw of rl) { // Ctrl+D / closed stdin ends the iteration cleanly
+      const line = raw.trim();
+      if (line === "/exit") break;
+      if (line) {
+        const { answer, end, prompt: nextPrompt } = await session.turn(line);
+        output.write(answer + "\n");
+        rl.setPrompt(nextPrompt);
+        if (end) break; // a conversational "bye"/"goodbye" — clean end, same as /exit
+      }
+      prompt();
     }
-    prompt();
+  } finally {
+    rl.close();
+    await session.close();
   }
-  rl.close();
-
-  await session.close();
   return { logFile: session.logFile, sidecarFile: session.sidecarFile, turns: session.turns };
 }