@polycode-projects/the-mechanical-code-talker 1.5.4 → 1.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",

package/src/chat.mjs

@@ -58,7 +58,7 @@ import {
   VERB_TO_KIND, WHERE_MARKERS, MENTION_MARKERS, ENTITY_TO_TYPE, PASSIVE_PARTICIPLE_TO_KIND,
   stripTrailingScopeFiller, stripTrailingDiscourseTag,
 } from "./ask-vocab.mjs";
-import { COUNTERFACTUAL_RE, correctMisspellings, applyPreambleFrames, escapeRegex } from "./interpret/normalize.mjs";
+import { COUNTERFACTUAL_RE, correctMisspellings, applyPreambleFrames, normalizeQuery, escapeRegex } from "./interpret/normalize.mjs";
 import { fuzzyMatchInSet, fuzzyBound } from "./interpret/fuzzy.mjs";
 
 // uuidv7 lives in ./uuid.mjs (shared with telemetry + the bench stamp); re-exported
@@ -2196,6 +2196,31 @@ async function generalVerbTeach(payload) {
   return { subject, predicate, object };
 }
 
+/** HANDOVER.md 2026-07-10 item 2 — is `word` a genuine NOUN/PROPN, per wink-nlp's
+ *  optional POS tagger (ask-nlp.mjs's nlpAdapter, the SAME adapter the closed
+ *  structural grammar already leans on)? Used to let ONE narrow bare (unwrapped)
+ *  general-verb teach sentence through below: GENERAL_VERB_TEACH_RE's shape
+ *  ("<word> <word> <rest>") is too permissive to trust on a bare sentence with no
+ *  "remember"/"note" signal at all — "tell me a joke" and "explain the class
+ *  hierarchy to me" match the IDENTICAL shape (subject="tell"/"explain", the
+ *  imperative verb itself, mistaken for a subject) and must never be silently
+ *  reified as bogus mgx:me/mgx:the facts (confirmed live: both are tagged VERB).
+ *  A genuine declarative's first word is a NOUN/PROPN instead ("grace mentors
+ *  alan", "sam owns TaskController" — confirmed live: both tagged NOUN). No wink
+ *  installed degrades to false (never a guess), same as every other optional-
+ *  adapter path in this codebase. */
+async function subjectIsNounOrPropn(word) {
+  try {
+    const { nlpAdapter } = await import("./ask-nlp.mjs");
+    const adapter = nlpAdapter();
+    if (!adapter) return false;
+    const [tag] = adapter.posTags([String(word || "")]);
+    return tag === "NOUN" || tag === "PROPN";
+  } catch {
+    return false;
+  }
+}
+
 // ---- General verb-to-predicate DIRECT-QUESTION retrieval (item 5, this
 // session's follow-up to the teach mechanism above): "does margo eat ribs" /
 // "did margo eat ribs" / "what does margo eat" against a fact taught via
@@ -2343,11 +2368,18 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = 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.
+  // form is double-gated: no interrogative lead, PLUS either side spelling a
+  // Capitalized token — so the "who owns <X>" READ question and ordinary
+  // lowercase prose ("everybody owns a share") never land a fact here.
+  // HANDOVER.md 2026-07-10 item 2 fix: the gate used to check ONLY the owner
+  // name (own[1]) — "sam owns TaskController" WALLED entirely, because "sam"
+  // isn't capitalized, even though "TaskController" (own[2], the owned thing)
+  // is an obviously code-shaped proper name and just as strong a signal that
+  // this isn't ordinary prose. Either side capitalized is now enough.
   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]))) {
+  if (own && memoryDir && !QUESTION_LEAD_RE.test(ownSrc)
+    && (wrapped || /^[A-Z]/.test(own[1]) || /^[A-Z]/.test(own[2]))) {
     const stored = await teachFact(memoryDir, sessionId, {
       subject: own[2], predicate: OWNED_BY_PREDICATE, object: own[1],
     });
@@ -2551,6 +2583,33 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
       const stored = await teachFact(memoryDir, sessionId, gv);
       if (stored) return stored;
     }
+  } else if (!wrapped && memoryDir && !QUESTION_LEAD_RE.test(correctMisspellings(raw))) {
+    // BARE path (HANDOVER.md 2026-07-10 item 2 fix): "grace mentors alan" — no
+    // "remember"/"note" wrapper at all — used to silently reach neither this
+    // frame NOR an honest miss, landing on the raw structural wall instead
+    // (or, at exactly <=3 words with no code-ish token, the UNRELATED
+    // isConversational() orientation card — see subjectIsNounOrPropn's own
+    // docblock for why a plain wrapper-required gate can't safely widen to
+    // bare sentences on shape alone: "tell me a joke" fits the identical SVO
+    // shape and must never be reified). Only a POS-confirmed NOUN/PROPN
+    // subject earns a try here — the same distinction that separates a
+    // genuine declarative from an imperative request. The QUESTION_LEAD_RE
+    // check runs the SAME correctMisspellings() pass ask.mjs's own typo
+    // tolerance already uses (not `raw` itself) — found live: "wich modules
+    // touch model.mjs" (a typo'd "which…" structural question, MISSPELLINGS-
+    // table-corrected everywhere ELSE in this file) POS-tags its uncorrected
+    // "wich" as a bare NOUN (wink's honest fallback for any unrecognized
+    // token, not a real signal), which would otherwise mis-store it as a
+    // fact instead of leaving it for the structural grammar's own typo-
+    // tolerant retry to answer for real.
+    const subjectWord = raw.match(/^([\w'-]+)/)?.[1];
+    if (subjectWord && (await subjectIsNounOrPropn(subjectWord))) {
+      const gv = await generalVerbTeach(raw);
+      if (gv) {
+        const stored = await teachFact(memoryDir, sessionId, gv);
+        if (stored) return stored;
+      }
+    }
   }
 
   let payload = null;
@@ -2716,6 +2775,24 @@ const WHAT_KNOW_RE = /^(?:what\s+(?:do\s+you|d'?you)\s+know(?:\s+so\s+far)?|what
 // "what does the do" is not real input) — a natural stranger-opener that was one
 // token away from already working.
 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(?:\s+(?:app|code|codebase|project|repo))?\s+do|what\s+does\s+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)|what\s+should\s+i\s+(?:read|look\s+at)\s+first(?:\s+to\s+understand\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?|where\s+should\s+i\s+start\s+reading(?:\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?|where\s+do\s+i\s+begin\s+reading(?:\s+(?:this\s+)?(?:codebase|code|repo|repository|project))?)$/;
+/** HANDOVER.md 2026-07-10 item 3 (part 2): a bare "what is in here"/"what's in
+ *  here"/"whats in here" — the SAME orientation intent as META_ORIENT_RE's own
+ *  "what's in this repo"-shaped members, just phrased with the CONTEXT_WORDS
+ *  pronoun "here" instead of a named noun (app/codebase/repo/…). ask.mjs's own
+ *  containment grammar parses "here" as a genuine pronoun object and, when a
+ *  focus IS standing, resolves it there exactly as intended — this regex is
+ *  ONLY ever tried when there is NO focus (see the call site's `!focus?.label`
+ *  gate), so that existing resolution path is completely untouched. With
+ *  nothing to resolve "here" against, ask.mjs's grammar instead renders the
+ *  honest but unhelpful "'here' needs a selected node…" miss — a poor answer
+ *  for a genuine first-time stranger who has never selected anything yet.
+ *  Tested against the NORMALIZED query (metaLane's call site runs
+ *  normalizeQuery first) rather than the raw text, so a preamble-wrapped
+ *  opener ("hey, first time trying this out - what is in here?") reaches this
+ *  exactly as the BARE "what is in here?" does — same preamble/filler-word
+ *  stripping ask.mjs's own grammar already applies before it ever sees the
+ *  pronoun. */
+const NO_FOCUS_WHATS_IN_HERE_RE = /^what(?:'s|s|\s+is)\s+in\s+here\??$/i;
 
 /** A SHORT memory summary (never a fact dump) for the bare "what do you know".
  *  This branch only fires when rows.length === 0 — i.e. precisely the case where
@@ -2813,7 +2890,7 @@ async function moduleOrientLane(query, { graph }) {
   return { text: moduleOverviewText(graph, ind), via: "meta" };
 }
 
-async function metaLane(query, { graph, memoryDir, last = null, templates = null, vocabHint = null }) {
+async function metaLane(query, { graph, memoryDir, last = null, templates = null, vocabHint = null, focus = null }) {
   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" };
@@ -2829,6 +2906,22 @@ async function metaLane(query, { graph, memoryDir, last = null, templates = null
     const text = orientationText(graph, templates, vocabHint);
     return { text: last?.answer === text ? META_ORIENT_REPEAT_ONELINER : text, via: "meta" };
   }
+  // HANDOVER.md 2026-07-10 item 3 (part 2): a bare "what is in here" with NO
+  // standing focus — see NO_FOCUS_WHATS_IN_HERE_RE's own docblock. Tested
+  // against normalizeQuery's output (the SAME normalization ask.mjs's own
+  // grammar runs before it ever sees the "here" pronoun), not the raw `q`
+  // above, so a preamble-wrapped opener reaches it identically to the bare
+  // form. Gated on !focus?.label so a real standing focus (where ask.mjs
+  // already resolves "here" against it) is completely unaffected — this only
+  // ADDS a fallback for the true first-turn case, never changes resolution
+  // when a focus exists.
+  if (!focus?.label) {
+    const stripped = normalizeQuery(String(query)).trim().replace(/[?.!]+$/, "").trim();
+    if (NO_FOCUS_WHATS_IN_HERE_RE.test(stripped)) {
+      const text = orientationText(graph, templates, vocabHint);
+      return { text: last?.answer === text ? META_ORIENT_REPEAT_ONELINER : text, 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
@@ -5814,7 +5907,28 @@ async function completionsRescueAnswer(query, { memoryDir, graph }) {
   if (!term) return null;
   try {
     const { generateCompletion } = await import("./completions/complete.mjs");
-    const result = await generateCompletion(memoryDir, term, { query: term, graph });
+    // HANDOVER.md item 1: broadSearch (src/completions/search.mjs) already accepts an
+    // optional Repository-Interface `graphService` — its own docblock names
+    // createGraphService(graph) (src/providers/graph-service.mjs) as the reference
+    // shape — but until now nothing ever handed one through, so this lane could only
+    // ever see memory BLOCKS saved via an explicit saveBlock() call. Ordinary chat
+    // teaching/asking never calls saveBlock(), so a subject's first-ever mention in a
+    // session always declined here, no matter how much the already-loaded graph (and
+    // any taught Facts about it) actually knew. createCompletionsGraphAdapter
+    // (src/completions/graph-adapter.mjs) wraps the SAME graph object this turn already
+    // has in scope (runTurn's own `graph` param, loaded once per session by the chat
+    // shell) plus this repo's already-loaded Fact store — no re-load, no new search
+    // machinery, just handing broadSearch the adapter it was always built to accept.
+    // Loading memory here (rather than letting generateCompletion load it itself at
+    // Stage 3) lets the SAME loaded payload double as the adapter's Fact-search source;
+    // passed straight through as opts.memory so Stage 3 doesn't re-read it a second
+    // time. A null/empty graph (no code entities loaded yet) or empty memory (no Facts
+    // taught yet) degrades to the pre-existing block-only search, exactly as before.
+    const { createCompletionsGraphAdapter } = await import("./completions/graph-adapter.mjs");
+    const { loadMemory } = await import("./memory/core.mjs");
+    const memory = await loadMemory(memoryDir);
+    const graphService = createCompletionsGraphAdapter(graph, memory);
+    const result = await generateCompletion(memoryDir, term, { query: term, graph, memory, graphService });
     if (!result || result.declined || !result.text) return null; // honest decline — never fabricate
     return { text: result.text };
   } catch {
@@ -6157,7 +6271,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // codebase", "how do i start") → a summary / orientation, answered before the
   // fact-dump readers so "what do you know" gets a summary, not raw facts.
   if (miss) {
-    const meta = await metaLane(query, { graph, memoryDir, last, templates, vocabHint });
+    const meta = await metaLane(query, { graph, memoryDir, last, templates, vocabHint, focus });
     if (meta) {
       answer = meta.text; via = meta.via; recordMiss = false; handled = true;
       note(trace, `lane: (1) META/SELF — bare self/session question recognized, answered via="${meta.via}"`);

package/src/completions/graph-adapter.mjs

@@ -0,0 +1,118 @@
+// completions/graph-adapter.mjs — HANDOVER.md item 1: the graphService-shaped adapter
+// src/completions/search.mjs's broadSearch() was always built to accept — its own
+// docblock names createGraphService(graph) (src/providers/graph-service.mjs) as the
+// reference shape — but until now nothing in live chat ever constructed and passed one
+// through (src/chat.mjs's completionsRescueAnswer called generateCompletion() with no
+// `graphService` at all). Without it, broadSearch could only ever see memory BLOCKS
+// saved via an explicit saveBlock() call — never the already-loaded code graph, and
+// never a taught Fact — so "give me a detailed summary of how X works" declined for any
+// subject on its first real mention in a session, no matter how much the graph or
+// taught Facts actually knew about it.
+//
+// createCompletionsGraphAdapter(graph, memory) wraps TWO already-loaded stores (never
+// re-loads either from disk — both are handed in by the caller, exactly as loaded for
+// this turn):
+//
+//   - .search(q, {limit}) delegates straight to createGraphService(graph).search() —
+//     the same ranked lexical module/symbol search every other Repository-Interface
+//     consumer uses (src/codegraph.mjs's searchModulesRanked/scoreSymbolsRanked under
+//     the hood). No new search machinery.
+//
+//   - .ask(q) does NOT delegate to createGraphService(graph).ask() (src/ask.mjs) —
+//     that engine is a mechanical NATURAL-LANGUAGE QUESTION grammar ("which functions
+//     call X", "what does X import"), and broadSearch always calls .ask() with the
+//     bare SUBJECT TERM itself ("TaskController"), not a question. Tried live: that
+//     produces an honest but useless "couldn't parse this as a graph question"
+//     rephrase-hint every time — real text, but not about the subject, and it would
+//     pollute the completion with noise. Instead .ask() here builds real sentences
+//     from two sources that a bare term CAN resolve against directly:
+//       1. resolveSymbol + renderDescribe (src/codegraph.mjs) — the SAME graph-only
+//          renderer src/server.mjs's own tmct_describe tool uses: real facts (defining
+//          module, contains, inherits, calls, tests, attributes, …), never invented.
+//       2. readFactRows(memory) (src/memory/core.mjs) — any TAUGHT Fact whose subject
+//          or object mentions the term. This is the one source the pipeline had NO
+//          path to before at all: Stage 3 (inferRelations) only ever augments groups
+//          that already exist from Stage 1's hits, so a subject with real taught Facts
+//          but zero blocks/code-graph hits still surfaced nothing.
+//     svc.ask() is still tried last, but its content is kept ONLY when it genuinely
+//     parsed (tmct_ask.miss === false) — e.g. the rare case where the bare term happens
+//     to also be a real registered question shape — never its own rephrase-hint noise.
+//
+// Every sentence this adapter returns traces to a real graph edge/attribute or a real
+// taught Fact — never invented, matching src/completions/'s extractive-only discipline
+// (see complete.mjs's own file header).
+
+import { createGraphService } from "../providers/graph-service.mjs";
+import { resolveSymbol, renderDescribe } from "../codegraph.mjs";
+import { readFactRows } from "../memory/core.mjs";
+
+/** renderDescribe() renders one LINE per fact (label header, each attribute, each edge
+ *  group) with no terminal punctuation of its own — fine for its own "compact plain-text
+ *  description for an agent consumer" purpose, but src/completions/rank.mjs's
+ *  splitSentences() treats each line as its own candidate sentence, and complete.mjs
+ *  joins kept sentences with a single space — so two adjacent kept lines without a
+ *  period between them would otherwise read as one run-on clause. Ensuring every line
+ *  ends in terminal punctuation here (never rewording/reordering the line itself) is
+ *  the cheapest fix that stays entirely inside this adapter, touching neither
+ *  renderDescribe() (server.mjs's tmct_describe tool relies on its current line shape)
+ *  nor rank.mjs/complete.mjs's own join logic. */
+function withTerminalPunctuation(text) {
+  return String(text || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => (/[.!?]$/.test(line) ? line : `${line}.`))
+    .join("\n");
+}
+
+/**
+ * @param {object|null} graph   a parseEntities() result (src/codegraph.mjs), or null
+ *   when no code graph is loaded — search()/the describe-half of ask() then honestly
+ *   contribute nothing, rather than throwing.
+ * @param {object|null} [memory=null]  a loadMemory() payload (src/memory/core.mjs), or
+ *   null when there's no Fact store to search — the Fact-half of ask() then honestly
+ *   contributes nothing.
+ * @returns {{search: Function, ask: Function}} a Repository-Interface-shaped
+ *   graphService satisfying src/completions/search.mjs's broadSearch() contract.
+ */
+export function createCompletionsGraphAdapter(graph, memory = null) {
+  const svc = graph ? createGraphService(graph) : null;
+
+  return {
+    search(q, { limit } = {}) {
+      if (!svc) return { ok: true, value: { results: [] } };
+      return svc.search(q, { limit });
+    },
+
+    ask(q) {
+      const term = String(q || "").trim();
+      if (!term) return { ok: true, value: { content: "" } };
+      const sentences = [];
+
+      if (svc) {
+        const { match, candidates } = resolveSymbol(graph, term);
+        if (match) sentences.push(withTerminalPunctuation(renderDescribe(graph, match, { candidates })));
+      }
+
+      if (memory) {
+        const needle = term.toLowerCase();
+        for (const row of readFactRows(memory)) {
+          if (!row.subject || !row.predicate || !row.object) continue;
+          const haystack = `${row.subject} ${row.object}`.toLowerCase();
+          if (!haystack.includes(needle)) continue;
+          sentences.push(`${row.subject} ${row.predicate} ${row.object}.`.trim());
+        }
+      }
+
+      if (svc) {
+        const res = svc.ask(term);
+        if (res?.ok && res.value?.tmct_ask?.miss === false && res.value.content) {
+          sentences.push(res.value.content);
+        }
+      }
+
+      if (!sentences.length) return { ok: true, value: { content: "" } };
+      return { ok: true, value: { content: sentences.join(" ") } };
+    },
+  };
+}

package/src/interpret/normalize.mjs

@@ -191,8 +191,19 @@ const ACK_PREAMBLE_RE = /^(?:(?:ok(?:ay)?|aight|cool|alright|sure|right|fine|gre
  *  §3: the vague-opener family a genuine first-time stranger types). Same
  *  delimiter-required discipline as GREETING/THANKS/ACK_PREAMBLE_RE above —
  *  a bare "just poking around" with no question stays small-talk (this file
- *  never claims a turn that has no remainder to hand back). */
-const BROWSING_PREAMBLE_RE = /^just\s+(?:poking\s+around|looking\s+around|browsing|exploring|checking\s+(?:this|it)\s+out)\s*[,.—–-]\s*(.+)$/i;
+ *  never claims a turn that has no remainder to hand back).
+ *  HANDOVER.md 2026-07-10 item 3: "first time trying this out"/"first time
+ *  using this"/"first time here" is the SAME self-orientation species — a
+ *  genuine stranger's opener, just phrased around their own inexperience
+ *  rather than what they're doing right now — found live as "hey, first
+ *  time trying this out - what is in here?" falling straight to the raw
+ *  grammar wall (GREETING_PREAMBLE_RE peels "hey,", but nothing recognized
+ *  the remainder as a preamble at all). Added as a sibling alternative in
+ *  the SAME regex/capture group, so it strips into the identical downstream
+ *  shape ("just poking around, X" and "first time trying this out, X" both
+ *  hand back the bare "X" for the ordinary pipeline to answer) rather than a
+ *  new frame with its own behavior. */
+const BROWSING_PREAMBLE_RE = /^(?:just\s+(?:poking\s+around|looking\s+around|browsing|exploring|checking\s+(?:this|it)\s+out)|first\s+time\s+(?:trying\s+this\s+out|using\s+this|here))\s*[,.—–-]\s*(.+)$/i;
 /** A repeated leading HEDGE ADVERB ("maybe", "possibly", "perhaps") ahead of a
  *  polite request verb — the sibling of ACK_PREAMBLE_RE for HEDGING rather than
  *  acknowledging (Tier 6 playtest §3's own stacked-politeness example: "could