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

package/src/chat.mjs

@@ -45,7 +45,7 @@ import { createInterface } from "node:readline/promises";
 import { spawnSync } from "node:child_process";
 import { dispatchTool } from "./server.mjs";
 import { loadConfig, DEFAULT_GRAPH_REL } from "./config.mjs";
-import { parseEntities } from "./codegraph.mjs";
+import { parseEntities, edgesOfKind, renderAuthorCard, renderAuthorTouches, renderCommitAuthor } from "./codegraph.mjs";
 import { SESSIONS_DIR_REL, appendSessionToGraph } from "./sessions.mjs";
 import { uuidv7 } from "./uuid.mjs";
 import { createTelemetry } from "./telemetry.mjs";
@@ -518,10 +518,48 @@ export function moduleCountOf(graph) {
  *  orientation/greeting only fires when we actually hold an empty graph. */
 const noCodeGraph = (graph) => !!graph && moduleCountOf(graph) === 0;
 
+/** LIVE orientation examples (0.8.2 WS4 wall kindness): the example queries on the
+ *  orientation card name entities from the LOADED graph — the sorted-first Module
+ *  label and the sorted-first Function/Method label, deterministically — so a
+ *  stranger who types them verbatim gets a real answer on ANY graph (the old
+ *  hardcoded walk.mjs/buildContextBundle examples miss on every non-tmct graph).
+ *  A null (unknown) graph keeps the generic pair byte-for-byte. */
+function orientationExamples(graph) {
+  const generic = { example1: "walk.mjs", example2: "buildContextBundle" };
+  if (!graph || !Array.isArray(graph.individuals)) return generic;
+  const minLabel = (labels) => {
+    let best = null;
+    for (const l of labels) { const s = String(l || ""); if (s && (best === null || s < best)) best = s; }
+    return best;
+  };
+  // "which modules import <example1>" must ANSWER, so prefer a module that IS
+  // imported (an `imports` edge object); any module label as the fallback.
+  const importedMod = minLabel(edgesOfKind(graph, "imports")
+    .filter((e) => (graph.byId?.get?.(e.object)?.class || "") === "Module")
+    .map((e) => e.objectLabel || ""));
+  const anyMod = minLabel(graph.individuals.filter((i) => (i.class || "") === "Module").map((i) => i.label));
+  const example1 = importedMod ?? anyMod ?? generic.example1;
+  // "what calls <example2>" must ANSWER, so prefer a Function/Method that HAS a
+  // recorded caller (a `callsSymbol` edge object with a real individual), then a
+  // module-coarse called module, then any callable label, then example1.
+  const calledSym = minLabel(edgesOfKind(graph, "callsSymbol")
+    .filter((e) => ["Function", "Method"].includes(graph.byId?.get?.(e.object)?.class || ""))
+    .map((e) => e.objectLabel || graph.byId?.get?.(e.object)?.label || ""));
+  const calledMod = minLabel(edgesOfKind(graph, "calls")
+    .filter((e) => (graph.byId?.get?.(e.object)?.class || "") === "Module")
+    .map((e) => e.objectLabel || ""));
+  const anyFn = minLabel(graph.individuals
+    .filter((i) => i.class === "Function" || i.class === "Method").map((i) => i.label));
+  const example2 = calledSym ?? calledMod ?? anyFn ?? example1;
+  return { example1, example2 };
+}
+
 /** The orientation surface, module-aware: the empty variant (→ --repo/tmct init +
- *  seeded vocabulary) when there's no code graph, the standard one otherwise. */
+ *  seeded vocabulary) when there's no code graph, the standard one (with live
+ *  {example1}/{example2} query examples from the loaded graph) otherwise. */
 function orientationAnswer(templates, graph) {
-  return tRender(templates, noCodeGraph(graph) ? T_ORIENTATION_EMPTY : T_ORIENTATION) ?? TEMPLATES_UNAVAILABLE;
+  if (noCodeGraph(graph)) return tRender(templates, T_ORIENTATION_EMPTY) ?? TEMPLATES_UNAVAILABLE;
+  return tRender(templates, T_ORIENTATION, orientationExamples(graph)) ?? TEMPLATES_UNAVAILABLE;
 }
 
 /** A dynamic orientation string for the meta/self lane: a /stats-style overview
@@ -589,19 +627,70 @@ export function shortMissHint(query) {
 /** The exact opening of the engine's full grammar-wall miss — the ONLY miss the
  *  short-miss rewrites. Receipt-bearing misses (honest empties, unresolved terms,
  *  the empty-graph bootstrap note, compositional misses) never match, so their
- *  specific wording + traversal receipts stand. */
-const WALL_MISS_RE = /^couldn't parse this as a graph question\. Try:/;
+ *  specific wording + traversal receipts stand. Exported: the recall hygiene
+ *  (bestQaPair) reuses it so a folded wall answer is never replayed as a memory
+ *  (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:/;
 
 // #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
 // (LOUD, the working shape) — never the grammar wall, never a silent data loss.
+// 0.8.2 widens the lane with two NATURAL frames, both reified via appendFact
+// with a distinct teach:chat provenance (its own "teach" trust prior):
+//   - "remember/note that <X> is <adjective>" → an mgx:hasProperty fact —
+//     ONLY under the explicit wrapper (a bare "X is deprecated" is never
+//     silently swallowed);
+//   - "<Name> owns/maintains <X>" (bare declarative or wrapped) → an
+//     mgx:ownedBy fact, read back by "who owns <X>" (factReadBack).
 const TEACH_RE = /^(?:please\s+)?(?:remember|note|keep in mind|jot down|for the record|fyi)\b[:,]?\s*(?:that\s+)?(.+?)[.?!]*$/i;
 const BARE_DECLARATIVE_RE = /^(?:every |each |all |a |an )?[\w-]+ (?:is|are) (?:a |an )?[\w-]+$/i;
 /** Interrogative / auxiliary leads that make an "X is a Y"-shaped line a QUESTION
  *  ("what is a cache", "is a module a component"), never a teach declarative. */
 const QUESTION_LEAD_RE = /^(?:what|who|which|where|when|why|how|is|are|do|does|did|can|could|should|would|will|has|have)\b/i;
 
+// The teach lane's fact predicates (rendered via FACT_PREDICATE_PHRASES).
+const OWNED_BY_PREDICATE = "mgx:ownedBy";
+const HAS_PROPERTY_PREDICATE = "mgx:hasProperty";
+
+/** "<Name> owns/maintains <X>" — the ownership teach declarative. <Name> is one
+ *  or two name tokens, <X> one code-ish token (a path, a file, a symbol). The
+ *  BARE form additionally requires a Capitalized name (see teachLane), so
+ *  ordinary lowercase prose never lands a fact without the explicit wrapper. */
+const OWNS_TEACH_RE = /^([A-Za-z][\w'-]*(?:\s+[A-Z][\w'-]*)?)\s+(?:owns|maintains)\s+(\S+?)[.!?]*$/;
+
+/** "<X> is <adjective>" — the property teach payload (wrapper-REQUIRED): a lazy
+ *  subject and a single bare complement word. Never matches the "is a <noun>"
+ *  membership shape (that stays the ACE grammar's), so "remember that cache is
+ *  a store" still lands as rdfs:subClassOf, not a property. */
+const TEACH_PROPERTY_RE = /^(?:every\s+|each\s+|all\s+|the\s+)?(.+?)\s+(?:is|are)\s+(?!an?\b|the\b)([A-Za-z][\w-]*)$/i;
+
+/** The teach lane's provenance tag — mirrors grammar/assert.mjs's provenanceTag
+ *  shape under a distinct "teach:" family, so a taught fact is auditable apart
+ *  from the ACE-parsed asserts: teach:chat:<sessionId>@<ts>. core.mjs maps the
+ *  tag to a "teach" Source (trust prior in memory/trust.mjs). */
+const teachProvenanceTag = (sessionId, ts) => `teach:chat${sessionId ? `:${sessionId}` : ""}${ts ? `@${ts}` : ""}`;
+
+/** Reify one teach-lane fact + confirm (shared by the property and ownership
+ *  frames). Lazy + failure-tolerated: a write failure degrades to null (the
+ *  teach-miss text stands), never a crash. */
+async function teachFact(memoryDir, sessionId, { subject, predicate, object }) {
+  try {
+    const { appendFact, normFactTerm } = await import("./memory/core.mjs");
+    const s = normFactTerm(subject);
+    const o = normFactTerm(object);
+    if (!s || !o) return null;
+    await appendFact(memoryDir, {
+      subject: s, predicate, object: o,
+      provenance: teachProvenanceTag(sessionId, new Date().toISOString()),
+    });
+    const phrase = FACT_PREDICATE_PHRASES[predicate] || predicate;
+    return { text: `noted — remembered: ${s} ${phrase} ${o}`, via: "assert", miss: false };
+  } catch {
+    return null;
+  }
+}
+
 /** Sentence forms to try asserting for a teach payload: the payload as-is, and
  *  (if it carries no determiner) its "every …" universal — the ACE-OWL shape the
  *  grammar actually lands. */
@@ -619,9 +708,23 @@ function teachSuggestion(payload) {
 
 async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
   const raw = String(query).trim();
-  let payload = null;
   const m = raw.match(TEACH_RE);
-  if (m && /\b(?:is|are)\b/i.test(m[1])) payload = m[1].trim();
+  const wrapped = m ? m[1].trim() : null;
+
+  // OWNERSHIP — "<Name> owns/maintains <X>", bare or remember-wrapped. The bare
+  // form is double-gated: a Capitalized name AND no interrogative lead, so the
+  // "who owns <X>" READ question and ordinary prose never land a fact here.
+  const ownSrc = wrapped ?? raw.replace(/[.!?]+\s*$/, "");
+  const own = ownSrc.match(OWNS_TEACH_RE);
+  if (own && memoryDir && !QUESTION_LEAD_RE.test(ownSrc) && (wrapped || /^[A-Z]/.test(own[1]))) {
+    const stored = await teachFact(memoryDir, sessionId, {
+      subject: own[2], predicate: OWNED_BY_PREDICATE, object: own[1],
+    });
+    if (stored) return stored;
+  }
+
+  let payload = null;
+  if (wrapped && /\b(?:is|are)\b/i.test(wrapped)) payload = wrapped;
   else if (BARE_DECLARATIVE_RE.test(raw) && !QUESTION_LEAD_RE.test(raw)) payload = raw;
   if (!payload) return null;
   // Try to store it (a live session provides the write target). assertTurn returns
@@ -631,6 +734,19 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
       const stored = await assertTurn(cand, { memoryDir, sessionId, focus: null, lexicon });
       if (stored) return { text: stored.answer, via: "assert", miss: false };
     }
+    // PROPERTY teach — "remember/note that <X> is <adjective>": wrapper-REQUIRED
+    // (a bare "X is deprecated" is never silently reified), and only after the
+    // ACE grammar declined (unknown words / not the membership shape), so a
+    // wrapped "X is a Y" over known lexicon still lands as rdfs:subClassOf.
+    if (wrapped) {
+      const prop = wrapped.match(TEACH_PROPERTY_RE);
+      if (prop) {
+        const stored = await teachFact(memoryDir, sessionId, {
+          subject: prop[1], predicate: HAS_PROPERTY_PREDICATE, object: prop[2],
+        });
+        if (stored) return stored;
+      }
+    }
   }
   const suggestion = teachSuggestion(payload);
   const did = suggestion && suggestion !== payload.toLowerCase() ? ` Did you mean: "${suggestion}"?` : "";
@@ -647,7 +763,10 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
 // reference with no graph entity or predicate, so real graph queries ("what does X
 // import", the meta "what does imports mean", "what did i ask before") never match.
 const WHAT_KNOW_RE = /^what\s+(?:do\s+you|d'?you)\s+know(?:\s+so\s+far)?$/;
-const META_ORIENT_RE = /^(?:what(?:'s| is| are)?\s+this(?:\s+(?:codebase|repo|repository|project|code|thing))?|what\s+(?:codebase|repo|repository|project)\s+is\s+this|what\s+am\s+i\s+looking\s+at|what\s+is\s+tmct|how\s+do\s+i\s+(?:start|begin|get\s+started|get\s+going|load\s+(?:my\s+)?code|index\s+(?:my\s+)?(?:code|repo|repository)|use\s+(?:this|you|tmct))|where\s+do\s+i\s+(?:start|begin))$/;
+// 0.8.2 WS4 wall kindness (c): the most likely stranger openers — "what does this
+// app/codebase do", "what is this app (for)" — join the orientation lane, so a
+// first-touch question gets the live overview instead of the grammar wall.
+const META_ORIENT_RE = /^(?:what(?:'s| is| are)?\s+this(?:\s+(?:app|codebase|repo|repository|project|code|thing))?|what\s+(?:codebase|repo|repository|project)\s+is\s+this|what\s+does\s+(?:this|the)\s+(?:app|code|codebase|project|repo)\s+do|what\s+is\s+(?:this|the)\s+app(?:\s+for)?|what\s+am\s+i\s+looking\s+at|what\s+is\s+tmct|how\s+do\s+i\s+(?:start|begin|get\s+started|get\s+going|load\s+(?:my\s+)?code|index\s+(?:my\s+)?(?:code|repo|repository)|use\s+(?:this|you|tmct))|where\s+do\s+i\s+(?:start|begin))$/;
 
 /** A SHORT memory summary (never a fact dump) for the bare "what do you know". */
 async function memorySummary(memoryDir, graph) {
@@ -670,9 +789,112 @@ async function metaLane(query, { graph, memoryDir }) {
     return { text: await memorySummary(memoryDir, graph), via: "meta" };
   }
   if (META_ORIENT_RE.test(q)) return { text: orientationText(graph), via: "meta" };
+  // 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
+  // isConversational. The form is closed + unambiguous (7-40 hex chars), so the
+  // meta lane delegates it to the author lane here. Unknown/ambiguous shas return
+  // null and fall through unchanged.
+  if (AUTHOR_SHA_RE.test(q)) return authorLane(q, { graph });
   return null;
 }
 
+// #4 INTENT LANE — AUTHOR (0.8.2 WS4). Author is a Commit ATTRIBUTE (key
+// "author"/mgx:commitAuthor), never an individual, so "who is Grace Hopper" can't
+// resolve as an entity — this lane reads the attribute through codegraph.mjs's
+// authorIndex renderers instead. WOULD-MISS gated (the ladder consults it only on
+// a miss) + CLOSED whole-line regexes + an EXACT case-insensitive author-name hit:
+// an unknown name renders null here and falls through to the ordinary honest miss
+// (never a guess, never a hijacked graph query).
+const AUTHOR_NAME_SRC = "([A-Za-z][\\w'.-]*(?:\\s+[A-Za-z][\\w'.-]*){0,3})";
+const AUTHOR_WHO_IS_RE = new RegExp(`^who\\s+is\\s+${AUTHOR_NAME_SRC}$`, "i");
+const AUTHOR_TOUCHED_RE = new RegExp(
+  `^what\\s+(?:did|has)\\s+${AUTHOR_NAME_SRC}\\s+(?:touch(?:ed)?|chang(?:e|ed)|work(?:ed)?\\s+on|commit(?:ted)?)$`, "i");
+// The sha authorship forms — the interpret layer no longer rewrites these (WS2 guard).
+const AUTHOR_SHA_RE = /^who\s+(?:authored|wrote|is\s+the\s+author\s+of)\s+(?:commit\s+)?([0-9a-fA-F]{7,40})$/i;
+
+function authorLane(query, { graph }) {
+  if (!graph) return null;
+  const q = String(query).trim().replace(/[?.!]+$/, "").replace(/\s+/g, " ");
+  const sha = q.match(AUTHOR_SHA_RE);
+  if (sha) {
+    const line = renderCommitAuthor(graph, sha[1]);
+    return line ? { text: line, via: "author" } : null;
+  }
+  const touched = q.match(AUTHOR_TOUCHED_RE);
+  if (touched) {
+    const text = renderAuthorTouches(graph, touched[1]);
+    if (text) return { text, via: "author" };
+  }
+  const who = q.match(AUTHOR_WHO_IS_RE);
+  if (who) {
+    const text = renderAuthorCard(graph, who[1]);
+    if (text) return { text, via: "author" };
+  }
+  return null;
+}
+
+// #5(d,e)/#8 CAPABILITY NUDGES (0.8.2 WS4) — closed regexes on the would-miss path
+// for asks the graph genuinely cannot answer: risk scoring, code opinions, writing
+// code, and motive-"why". Each renders an HONEST wall pointing at the nearest real
+// query shapes. These REMAIN recorded as misses (recordMiss stays TRUE): a
+// capability wall must never fold into a recallable answer — WS3's fold hygiene is
+// the second belt, this gate is the braces.
+const RISK_NUDGE_RE = /\brisk(?:iest|y)\b/i;
+const OPINION_ADJ_SRC =
+  "(?:good|bad|clean|messy|ugly|nice|great|terrible|awful|solid|elegant|readable|maintainable|well[- ]written|well[- ]structured|spaghetti|ok|okay|decent|healthy)";
+const OPINION_NUDGE_RE = new RegExp(`^is\\s+(?:this|the)\\s+code(?:base)?\\s+(?:any\\s+)?${OPINION_ADJ_SRC}\\b`, "i");
+// Imperative "write code for me": a leading make/write/create/add/generate/
+// implement/fix/refactor (optionally "can you …"-wrapped) aimed at a code noun (or
+// a focus-resolvable "it"). "tell" is deliberately NOT a verb here — "tell me a
+// joke" (the graded hm-joke case) must keep its ordinary honest miss.
+const IMPERATIVE_NUDGE_RE =
+  /^(?:please\s+)?(?:(?:can|could|would|will)\s+you\s+(?:please\s+)?)?(?:make|write|create|add|generate|implement|fix|refactor)\b(?=.*\b(?:tests?|code|functions?|methods?|modules?|class(?:es)?|files?|it)\b)/i;
+const WHY_UNTESTED_RE = /^why\s+(?:is|are)(?:n't|\s+not)?\s+(.+?)\s+(?:untested|not\s+tested|uncovered)$/i;
+
+/** The <name> a nudge shows: the focus label when the query leans on a pronoun (or
+ *  gave us nothing better), else the captured subject; "<name>" as the placeholder. */
+function nudgeName(captured, focus) {
+  const c = String(captured || "").trim();
+  if (c && !/^(?:it|this|that|they|them)$/i.test(c)) return c;
+  return focus?.label || "<name>";
+}
+
+/** The capability-nudge answer for a would-miss query, or null. Order matters only
+ *  for the opinion gate: it must fire BEFORE the short-miss's "is a <thing> a
+ *  <kind>" membership hint would (the caller runs this whole step before the
+ *  short-miss rewrite). */
+function nudgeAnswer(query, focus) {
+  const q = String(query).trim().replace(/[?.!]+$/, "").replace(/\s+/g, " ");
+  if (OPINION_NUDGE_RE.test(q)) {
+    const name = focus?.label || "<name>";
+    return "I don't hold opinions — I read structure, not quality. I can show what an opinion would rest on: "
+      + `/stats (shape), "untested modules" (coverage), "who touched ${name}" (churn).`;
+  }
+  if (RISK_NUDGE_RE.test(q)) {
+    const name = focus?.label || "<name>";
+    return "I don't score risk — but two honest proxies live in the graph: "
+      + `"/impact ${name}" (what a change reaches) and "who touched ${name}" (churn).`;
+  }
+  const why = q.match(WHY_UNTESTED_RE);
+  if (why) {
+    const name = nudgeName(why[1], focus);
+    return "I can't know why — the graph records what IS, not intent. "
+      + `"what tests ${name}" and "untested modules" show the coverage facts.`;
+  }
+  if (IMPERATIVE_NUDGE_RE.test(q)) {
+    const name = nudgeName(/\b(?:it|this)\b/i.test(q) ? "it" : "", focus);
+    return "I don't write code — I read a graph of it. "
+      + `/tests ${name} shows what covers it; "untested modules" shows the gaps.`;
+  }
+  return null;
+}
+
+/** 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.";
+
 // ---- 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).
@@ -747,12 +969,15 @@ const RECALL_TOP_K = 2;
 
 /** Frame/stop words ignored when checking that a recalled Q genuinely shares
  *  vocabulary with the live query — at least one shared CONTENT word is required,
- *  so "which …" alone can never masquerade as a memory. */
+ *  so "which …" alone can never masquerade as a memory. Includes PATH-NOISE
+ *  tokens (src, lib, mjs, …): "who owns src/handlers/tasks.mjs" must never
+ *  recall "who touched src/core/store.mjs" off "src" alone. */
 const RECALL_STOPWORDS = new Set([
   "the", "a", "an", "and", "or", "for", "with", "about", "into", "from",
   "which", "what", "who", "how", "when", "where", "why",
   "does", "do", "did", "is", "are", "was", "were", "there",
   "me", "my", "we", "i", "you", "it", "this", "that", "in", "of", "to",
+  "src", "lib", "app", "mjs", "cjs", "js", "ts", "py", "index", "main", "test",
 ]);
 const recallWords = (s) => new Set(
   String(s).toLowerCase().split(/[^a-z0-9.]+/).filter((w) => w.length >= 3 && !RECALL_STOPWORDS.has(w)),
@@ -767,9 +992,18 @@ function uuidv7Day(id) {
   return ms > 0 && Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : null;
 }
 
+/** A recall frame's opening — a stored ANSWER carrying it is a replay of an
+ *  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 NO pair shares a content word — the block
- *  matched on packaging, not substance, so the honest miss must stand. */
+ *  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) {
   const qWords = recallWords(query);
   const pairs = [];
@@ -781,17 +1015,20 @@ function bestQaPair(blockText, query) {
   let best = null;
   let bestScore = 0;
   for (const p of pairs) {
-    let score = 0;
-    for (const w of recallWords(p.q)) if (qWords.has(w)) score += 1;
-    if (score > bestScore) { best = p; bestScore = score; }
+    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 > bestScore) { best = p; bestScore = shared.length; }
   }
   return best;
 }
 
 /** W2 seam: consult the folded-session block index for an honest miss. A
  *  sufficiently-relevant hit returns the recalled Q/A, framed and cited to its
- *  session; anything less returns null and the miss stands unchanged. Lazy +
- *  failure-tolerated (chat.mjs ethos): a broken memory store degrades to null. */
+ *  session; anything less returns null and the miss stands BYTE-UNCHANGED. A
+ *  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) {
   try {
     const { retrieveBlocks } = await import("./memory/blocks.mjs");
@@ -802,8 +1039,7 @@ async function recallFromBlocks(memoryDir, query) {
     if (!pair) return null;
     const day = uuidv7Day(best.id);
     const cite = `session ${String(best.id).slice(0, 8)}${day ? `, ${day}` : ""}`;
-    const qa = pair.a ? `Q: ${pair.q}\n  A: ${pair.a}` : `Q: ${pair.q}`;
-    return `you asked about this before (${cite}):\n  ${qa}`;
+    return `you asked about this before (${cite}):\n  Q: ${pair.q}\n  A: ${pair.a}`;
   } catch {
     return null;
   }
@@ -838,6 +1074,7 @@ const FACT_PREDICATE_PHRASES = {
   "mgx:hasFirstSubevent": "begins with",
   "mgx:hasLastSubevent": "ends with",
   "mgx:hasPrerequisite": "requires",
+  "mgx:ownedBy": "is owned by", // the teach lane's ownership frame ("Priya owns tasks.mjs")
 };
 const factPhrase = (f) => `${f.subject} ${FACT_PREDICATE_PHRASES[f.predicate] || f.predicate} ${f.object}`;
 
@@ -848,7 +1085,9 @@ const factPhrase = (f) => `${f.subject} ${FACT_PREDICATE_PHRASES[f.predicate] ||
  *  for themselves. Provenance stays VERBATIM either way. */
 function renderFactLine(f) {
   const cite = f.provenance ? ` (source: ${f.provenance})` : "";
-  if (f.provenance.includes("ace:chat")) return `you told me: ${factPhrase(f)}${cite}`;
+  // ace:chat = the ACE-parsed operator assert; teach:chat = the teach lane's
+  // natural frames — both are things the operator SAID, so both read first-person.
+  if (f.provenance.includes("ace:chat") || f.provenance.includes("teach:chat")) return `you told me: ${factPhrase(f)}${cite}`;
   // CORPUS facts are background DATA — present the relation plainly, cited to its
   // source, NEVER "i learned: …" (the footgun: a first-person claim over corpus noise).
   if (f.provenance.includes("corpus:")) return `${factPhrase(f)}${cite}`;
@@ -975,6 +1214,9 @@ const TOLD_ABOUT_RE = /^what\s+(?:did|have)\s+(?:i|we|you)\s+(?:told|tell|said|s
 /** "what kind of thing is an X" — the subject-side membership phrasing the grammar
  *  doesn't parse: reports X's OWN remembered type (falling back to X's members). */
 const KIND_OF_RE = /^what\s+kind\s+of\s+(?:thing|class|type|category|entity)?\s*(?:is|are)\s+(?:an?\s+)?(.+?)[?.!\s]*$/i;
+/** "who owns <X>" / "who maintains <X>" — the closed ownership read-back over
+ *  the teach lane's mgx:ownedBy facts. */
+const WHO_OWNS_RE = /^who\s+(?:owns|maintains)\s+(.+?)[?.!\s]*$/i;
 /** WHOLE-STORE recall (CHATBENCH_006 lever 3): "what did i tell you [last time]",
  *  "what facts do you know", "what do you remember" — list EVERY remembered fact
  *  (no subject/object term to filter on), cited, higher-trust first. The multi-turn
@@ -992,6 +1234,39 @@ async function entityClassNoun(graph, term) {
   return cls && CLASS_LABELS[cls] ? CLASS_LABELS[cls][0] : null;
 }
 
+/** A relation group that carries class-inheritance edges — the same token family
+ *  codegraph.mjs's relationKind classifies as "inherits" (checked locally over
+ *  prop+predicate so this file adds no codegraph import surface). */
+const INHERITS_GROUP_RE = /inherit|supertype|subclass|extend|specializ/i;
+/** How far up an inheritance chain the class↔instance bridge walks. */
+const INHERITS_MAX_HOPS = 8;
+
+/** Walk the code graph's `inherits` chain UPWARD from an entity id — each
+ *  superclass as { id, label }, bounded (≤ INHERITS_MAX_HOPS) and cycle-safe.
+ *  Read-only over graph.relations; feeds the class↔instance bridge so a taught
+ *  "controller ⊑ handler" composes with a graph "TaskController inherits
+ *  Controller". Follows the FIRST outgoing inherits edge per hop (single
+ *  inheritance is the emitted shape). */
+function inheritsChain(graph, startId) {
+  const out = [];
+  if (!graph || !startId) return out;
+  const seen = new Set([startId]);
+  let cur = startId;
+  for (let hop = 0; hop < INHERITS_MAX_HOPS; hop += 1) {
+    let edge = null;
+    for (const g of graph.relations || []) {
+      if (!INHERITS_GROUP_RE.test(`${g?.prop || ""} ${g?.predicate || ""}`)) continue;
+      edge = (g.edges || []).find((e) => e?.subject === cur) || null;
+      if (edge) break;
+    }
+    if (!edge || seen.has(edge.object)) break;
+    seen.add(edge.object);
+    out.push({ id: edge.object, label: edge.objectLabel || edge.object });
+    cur = edge.object;
+  }
+  return out;
+}
+
 /** ASSERT-RECALL MULTI-TURN READ-BACK (PLAN_CYCLE_4 tail → cycle-005 lever 2):
  *  once "every X is a Y" is asserted in an earlier turn, the graded assert-recall
  *  cells (B2/C1 assert) query it back across turns in shapes the graph grammar
@@ -1046,9 +1321,45 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null) {
       .filter((f) => subjCandidates.has(f.subject) && objVariants.has(f.object))
       .sort(byTrust)[0];
     if (hit) return { text: `yes — ${renderFactLine(hit)}`, replace: true };
+    // CLASS↔INSTANCE BRIDGE (0.8.2): when X resolves to a graph entity, its
+    // inherits chain's superclass LABELS are subject candidates too — a taught
+    // "controller ⊑ handler" composes with a graph "TaskController inherits
+    // Controller" so "is TaskController a handler" answers yes, naming BOTH
+    // sources (the graph edge + the taught fact with its provenance).
+    const ent = await resolveEntity(graph, isaAsk[1]);
+    if (ent) {
+      const bridgeSubjects = new Map(); // fact-term variant → the superclass label as spelled in the graph
+      for (const sup of inheritsChain(graph, ent.id)) {
+        for (const v of factTermVariants(normFactTerm, sup.label)) {
+          if (!subjCandidates.has(v) && !bridgeSubjects.has(v)) bridgeSubjects.set(v, sup.label);
+        }
+      }
+      const bridged = isa
+        .filter((f) => bridgeSubjects.has(f.subject) && objVariants.has(f.object))
+        .sort(byTrust)[0];
+      if (bridged) {
+        return {
+          text: `yes — the code graph says ${ent.label} inherits ${bridgeSubjects.get(bridged.subject)}, and ${renderFactLine(bridged)}`,
+          replace: true,
+        };
+      }
+    }
     return null; // no remembered fact — the honest miss stands (never a guessed "no")
   }
 
+  // (a2) OWNERSHIP read-back — "who owns/maintains <X>": the teach lane's
+  // mgx:ownedBy facts about X, trust-ranked, each cited (the source receipt
+  // stays in the render). No fact → null, the honest miss stands.
+  const owns = q.match(WHO_OWNS_RE);
+  if (owns) {
+    const variants = factTermVariants(normFactTerm, owns[1]);
+    const hits = rows
+      .filter((f) => f.predicate === OWNED_BY_PREDICATE && variants.has(f.subject))
+      .sort(byTrust);
+    if (!hits.length) return null;
+    return renderMany(hits);
+  }
+
   // (b) RECALL — "what did i tell you about X": every remembered fact mentioning X.
   const told = q.match(TOLD_ABOUT_RE);
   if (told) {
@@ -1332,6 +1643,19 @@ function relationTermOf(query, envelope) {
   if ((m = q.match(/^what\s+([a-z][a-z-]*?)\s+are\s+there$/))) return m[1];
   // "what is calling", "what is importing" (bare gerund, no object)
   if ((m = q.match(/^what\s+(?:is|are)\s+([a-z][a-z-]*ing)$/))) return m[1];
+  // THE SINGULAR META FORM — "what is a test" / "what is an import". The whole meta
+  // shape used to be excluded here to keep the frozen am-meta-imports ambiguity case
+  // ("what does imports mean") out; but that case is a DIFFERENT shape (ambiguousParse
+  // → envelope.parsed is null), and a relation word whose SINGULAR reads as a real
+  // graph-schema class/predicate ("what is a contains"/"cochange") answers non-miss
+  // from the ordinary meta path. So admit the article meta form ONLY when the ordinary
+  // path MISSED on a plain definitional parse (envelope.miss on a shape:"meta" object):
+  // an unambiguous relation word like "test" — no schema reading, no ambiguity — then
+  // reaches the relation-concept force exactly as its plural "what are the tests" does.
+  // RELATION_TERM still gates the term downstream, so a non-relation miss is untouched.
+  if (envelope?.miss === true && envelope?.parsed?.shape === "meta" && envelope.parsed.object) {
+    return envelope.parsed.object;
+  }
   return null;
 }
 
@@ -1590,10 +1914,35 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     const taught = await teachLane(query, { memoryDir, sessionId, lexicon });
     if (taught) { answer = taught.text; via = taught.via; recordMiss = taught.miss; }
   }
+  // (4b) #4 AUTHOR lane (0.8.2 WS4) — "who is <Name>", "what did <Name> touch",
+  // "who authored <sha>": the Commit author ATTRIBUTE answered as a person, off
+  // codegraph.mjs's authorIndex renderers. Closed regexes + an exact case-
+  // insensitive author hit only; an unknown name falls through to the ordinary
+  // honest miss below (never a guess).
+  if (miss && recordMiss && via === "composed") {
+    const authored = authorLane(query, { graph });
+    if (authored) { answer = authored.text; via = authored.via; 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
+  // must never become a recallable answer. The opinion gate fires HERE, before the
+  // short-miss's "is a <thing> a <kind>" membership hint could claim the line.
+  if (miss && recordMiss && via === "composed") {
+    const nudged = nudgeAnswer(query, newFocus);
+    if (nudged) { answer = nudged; via = "miss"; }
+  }
   // (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
+  // wall/short-miss (it matched WALL_MISS_RE), the second consecutive wall collapses
+  // to a one-liner whose text does NOT match WALL_MISS_RE — self-limiting, so a
+  // third consecutive miss re-offers the tailored hint instead of droning.
   if (miss && recordMiss && via === "composed" && WALL_MISS_RE.test(answer)) {
-    answer = shortMissHint(query); via = "miss";
+    answer = (last?.answer && WALL_MISS_RE.test(String(last.answer)))
+      ? WALL_REPEAT_ONELINER
+      : shortMissHint(query);
+    via = "miss";
   }
   // #4 HONEST-EMPTY POLISH — an empty CODE graph: any still-standing engine
   // dead-end (an honest empty, the short miss, the bootstrap note) carries the exit