@polycode-projects/the-mechanical-code-talker 1.0.8 → 1.0.9

package/src/codegraph.mjs

@@ -1408,7 +1408,7 @@ export function renderUntested(graph) {
   return `${untested.length} source module(s) with no covering test module:\n  ${capJoin(untested, COVERAGE_CAP, "\n  ")}`;
 }
 
-const HISTORY_CAP = 15;
+export const HISTORY_CAP = 15;
 
 /** Recent commits that touched a symbol's module — from `touches` (seon:history).
  *  Replaces `git log -- <file>`. Commits are listed newest-first (git-log order). */

package/src/interpret/normalize.mjs

@@ -146,7 +146,19 @@ const isListingRemainder = (rest) => {
 // splice — "." joins the delimiter class for exactly this reason; a bare
 // greeting alone ("hi.") still can't match since the regex also requires a
 // non-empty remainder AFTER the delimiter.
-const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy|g'?day|good\s+(?:morning|afternoon|evening|day)|greetings|salutations)(?:\s+there)?\s*[,.—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
+// "yeah nah" (AU/NZ informal opener, §3b, Tier 6 playtest): a soft discourse
+// filler AU/NZ speakers lead a sentence with, distinct from an actual "no" —
+// chat.mjs's own GREET closed set already recognizes the BARE phrase, but a
+// fused lead-in ("yeah nah, what does the router do") had no preamble form at
+// all and fell straight to the raw grammar wall, the exact failure g'day's own
+// fix (just above) closed for that dialect's greeting word.
+// "howdy pardner" (Tier 6 playtest, §3b dialect axis): "howdy" alone already
+// matched, but a VOCATIVE word right after it ("pardner", a US-Western/cowboy
+// register touch) sat between the greeting and its delimiter, where only the
+// literal word "there" was tolerated — "howdy pardner, remember that X" fell
+// straight to the raw grammar wall. A small closed vocative set, same
+// discipline as the greeting word list itself.
+const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy|g'?day|yeah\s+nah|good\s+(?:morning|afternoon|evening|day)|greetings|salutations)(?:\s+(?:there|pardner|folks|friend|mate))?\s*[,.—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
 /** Thanks lead-in with a delimiter (+ optional "quick question" bridge), the
  *  sibling of GREETING_PREAMBLE_RE for the "thanks" word family (Bug B2, 0.8.2
  *  follow-up): "thanks, <Q>" / "thanks so much, <Q>" -> "<Q>". chat.mjs's
@@ -158,6 +170,45 @@ const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy|g'?day|good\s+(?:mo
  *  non-empty-remainder-REQUIRED discipline as the greeting frame, so a bare
  *  "thanks so much" (no delimiter, no question) stays small-talk. */
 const THANKS_PREAMBLE_RE = /^(?:thanks|thank\s+you|many\s+thanks|thx|ty|cheers)(?:\s+(?:so\s+much|a\s+lot|very\s+much|a\s+bunch))?\s*[,—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
+/** An ACKNOWLEDGEMENT lead-in with a delimiter, the sibling of GREETING_PREAMBLE_RE/
+ *  THANKS_PREAMBLE_RE for the "ok"/"cool" word family (Tier 6 playtest: "ok cool,
+ *  what about the TaskController" — a drill-down continuation politely
+ *  acknowledging the PREVIOUS answer before asking the next question). chat.mjs's
+ *  OK_ACK set already treats a BARE "ok"/"cool"/"sounds good" as small-talk, but a
+ *  CHAINED lead-in ("ok cool, X") left "cool"/"," debris ahead of the real
+ *  question — same failure class GREETING/THANKS' own multi-word lead-ins had.
+ *  The marker group repeats (`+`) so a stack of ack-words peels in one pass ("ok
+ *  cool" both go), each followed by whitespace/comma; same delimiter- and
+ *  non-empty-remainder-REQUIRED discipline as the two frames above. */
+// "no worries" (Tier 6 playtest, §3b dialect axis, AU/NZ): a casual "that's
+// fine"/"no problem" opener that also, like the other ack words, sometimes
+// leads straight into the NEXT question rather than standing alone. "aight"
+// (cycle 5, §3b typo/elongation axis): the further-dropped texting-register
+// contraction of "alright", chainable with the others just like "ok cool,".
+const ACK_PREAMBLE_RE = /^(?:(?:ok(?:ay)?|aight|cool|alright|sure|right|fine|great|nice|got it|gotcha|sounds good|no worries|no problem)[\s,]+)+(.+)$/i;
+/** A SELF-ORIENTATION lead-in with a delimiter — "just poking around, what's
+ *  in this repo", "just browsing, X", "just exploring, X" (Tier 6 playtest,
+ *  §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;
+/** 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
+ *  you maybe possibly tell me... what saveStore does"). Unlike ACK_PREAMBLE_RE,
+ *  no delimiter is required — a hedge adverb modifies the verb it precedes
+ *  directly ("maybe possibly tell me"), so requiring a comma would miss the
+ *  common case; unconditional strip, same as the other preamble frames (none
+ *  of these three words is grammar-owned vocabulary). Deliberately a narrow,
+ *  closed three-word set. */
+const HEDGE_ADVERB_PREAMBLE_RE = /^(?:(?:maybe|possibly|perhaps)\s+)+(.+)$/i;
+/** A floating "if it's not too much trouble"/"if that's not too much bother"
+ *  aside — a genuine mid-sentence PARENTHETICAL (unlike every other frame
+ *  here, this is NOT anchored to the start of the string), stripped wherever
+ *  it appears, comma-bounded on either side. Tier 6 playtest's own example
+ *  phrase: "...tell me, if its not too much trouble, what saveStore does". */
+const TROUBLE_ASIDE_RE = /,?\s*if\s+(?:it'?s|it\s+is|that'?s|that\s+is)\s+not\s+too\s+much\s+(?:trouble|bother|hassle)\s*,?\s*/i;
 /** Modal politeness wrapper: "can/could/would/will you [please] <Q>[, please][?]"
  *  -> "<Q>". FILLER_WORDS already ate "can you"/"please" as words; this frame
  *  removes them as a WRAPPER so the ", please" comma never survives into the
@@ -176,6 +227,16 @@ const MODAL_WRAPPER_RE = /^(?:can|could|would|will)\s+you\s+(?:please\s+)?(.+?)(
  *  "explain" elaboration request (WHY set) are matched on the RAW turn text
  *  before normalizeQuery ever runs, so neither is touched by this frame. */
 const EXPLAIN_WRAPPER_RE = /^explain\s+(?:to\s+me\s+|please\s+)*(.+?)\??$/i;
+/** "tell me <Q>" (bare, no "about") -> "<Q>" — the sibling of EXPLAIN_WRAPPER_RE
+ *  for the "tell me" verb family when what follows is already a full WH-question
+ *  rather than a bare noun. "tell me about X" is vagueTouchTermOf's own separate
+ *  territory (chat.mjs) and is untouched here: this frame's interrogative-lead
+ *  gate can only ever fire on a remainder that "about X" never satisfies (it
+ *  starts with "about", not a WH-word). Found live (Tier 6 playtest): "could you
+ *  maybe possibly tell me... what saveStore does" left "tell me what saveStore
+ *  does" needing one more unwrap after HEDGE_ADVERB_PREAMBLE_RE and
+ *  MODAL_WRAPPER_RE peeled their own layers. */
+const TELL_ME_WRAPPER_RE = /^tell\s+me\s+(.+?)\??$/i;
 /** show/give-me presentation bridge: "show me [the] <thing>". Three-way:
  *  a KIND-listing remainder is left untouched (the compositional list grammar
  *  owns "show me untested modules"); a remainder carrying a relation verb or an
@@ -204,21 +265,63 @@ const SHOW_GIVE_ME_RE = /^(?:show|give)\s+me\s+(?:the\s+)?(.+?)\??$/i;
 const LEADING_CONNECTIVE_RE = /^(?:and|also|so|then|now|but)\s+(.+)$/i;
 const QUESTION_AUX_LEAD_RE = /^(?:does|do|did|is|are|was|were|has|have|had|can|could|will|would|should)\b/i;
 
+/** A TOPIC-SWITCH / self-interruption preamble — "actually never mind, what
+ *  calls X", "no wait, I meant what calls Y", "hold on, where is Z defined"
+ *  (Tier 6 playtest, §3: "no wait", mid-conversation topic switches). A real
+ *  user abandoning whatever they were about to say and asking something else
+ *  instead — same species as LEADING_CONNECTIVE_RE just above (a discourse
+ *  marker carrying no query content of its own, gated on a real question
+ *  following it), just a richer closed marker set than a single connective
+ *  word, and CHAINABLE ("actually" + "never mind" + "i meant" can all stack —
+ *  the fixpoint loop below peels one per pass). Deliberately NOT the same
+ *  mechanism as SELF_CORRECTION_RE (this file, further down): that shape
+ *  requires an explicit "sorry"/"i mean" marker WITH a mandatory trailing
+ *  delimiter, modeling a mid-sentence restart of the SAME clause with real
+ *  text on both sides; this one is a STANDALONE marker at the very start of
+ *  the turn with nothing meaningful before it, and the delimiter (a comma) is
+ *  optional — colloquial speech routinely drops it ("no wait i meant …"). The
+ *  marker group REPEATS (`+`, mirroring ACK_PREAMBLE_RE just above) so a stack
+ *  of markers peels in ONE pass ("actually" + "never mind," both go) — unlike
+ *  LEADING_CONNECTIVE_RE's single-word frame, gating on the remainder after
+ *  only the FIRST marker would reject the strip before later markers ever get
+ *  a chance to peel (found live: "actually never mind, X" left "never mind,
+ *  X" as the gated remainder, which itself never looks like a question lead,
+ *  so the whole frame silently declined). None of these markers is grammar-
+ *  owned vocabulary (VERB_TO_KIND/ENTITY_TO_TYPE), so — same as GREETING_
+ *  PREAMBLE_RE/THANKS_PREAMBLE_RE/ACK_PREAMBLE_RE above — the strip is
+ *  unconditional; no interrogative-lead gate needed. */
+const TOPIC_SWITCH_PREAMBLE_RE =
+  /^(?:(?:actually|no\s+wait|wait|hold\s+on|never\s+mind|scratch\s+that|on\s+second\s+thought|i\s+mean(?:t)?)[\s,.]+)+(.+)$/i;
+
 /** Apply the closed preamble frames in order (greeting -> modal -> show/give-me),
  *  repeated to a small fixpoint so stacked wrappers ("hey, can you show me X
  *  please") peel fully. Pure and idempotent; unmatched text passes through. */
 export function applyPreambleFrames(text) {
   let q = String(text || "");
+  // The trouble-aside is a mid-sentence parenthetical, not a start-anchored
+  // wrapper — stripped unconditionally, once, before the fixpoint loop (it
+  // never interacts with the other frames' anchoring).
+  q = q.replace(TROUBLE_ASIDE_RE, " ").replace(/\s+/g, " ").trim();
   for (let pass = 0; pass < 3; pass++) {
     const before = q;
     let m = q.match(GREETING_PREAMBLE_RE);
     if (m) q = m[1].trim();
     m = q.match(THANKS_PREAMBLE_RE);
     if (m) q = m[1].trim();
+    m = q.match(ACK_PREAMBLE_RE);
+    if (m) q = m[1].trim();
+    m = q.match(BROWSING_PREAMBLE_RE);
+    if (m) q = m[1].trim();
+    m = q.match(HEDGE_ADVERB_PREAMBLE_RE);
+    if (m) q = m[1].trim();
+    m = q.match(TOPIC_SWITCH_PREAMBLE_RE);
+    if (m) q = m[1].trim();
     m = q.match(MODAL_WRAPPER_RE);
     if (m) q = m[1].trim();
     m = q.match(EXPLAIN_WRAPPER_RE);
     if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
+    m = q.match(TELL_ME_WRAPPER_RE);
+    if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
     m = q.match(SHOW_GIVE_ME_RE);
     if (m) {
       const rest = m[1].trim();
@@ -229,7 +332,22 @@ export function applyPreambleFrames(text) {
     m = q.match(LEADING_CONNECTIVE_RE);
     if (m) {
       const rest = m[1].trim();
-      if (INTERROGATIVE_LEAD_RE.test(rest) || QUESTION_AUX_LEAD_RE.test(rest)) q = rest;
+      // Tier 6 playtest cycle 5: a leading connective ("so") sandwiched
+      // BETWEEN two other discourse markers ("aight cool, so actually wait,
+      // what calls X") used to block the WHOLE fixpoint — the remainder right
+      // after "so" ("actually wait, X") isn't ITSELF a question yet (it still
+      // has its own marker prefix), so the original interrogative-only gate
+      // rejected the strip, and TOPIC_SWITCH_PREAMBLE_RE (anchored to start)
+      // never got a chance at "actually" while "so " still sat in front of
+      // it. Also accepting a remainder that matches one of this file's OWN
+      // other closed preamble frames is safe by the same logic those frames
+      // already rely on: each is anchored + closed-vocabulary, so a match
+      // here guarantees the NEXT pass strips it too, not a guess.
+      if (
+        INTERROGATIVE_LEAD_RE.test(rest) || QUESTION_AUX_LEAD_RE.test(rest)
+        || TOPIC_SWITCH_PREAMBLE_RE.test(rest) || ACK_PREAMBLE_RE.test(rest)
+        || HEDGE_ADVERB_PREAMBLE_RE.test(rest) || BROWSING_PREAMBLE_RE.test(rest)
+      ) q = rest;
     }
     if (q === before) break;
   }
@@ -298,7 +416,23 @@ export function applySubordinationFrames(text) {
 // NOT match on a bare dash alone with no marker word: an ordinary em-dash aside
 // ("modules — like Base — that inherit from X") is common prose, not a restart, and
 // treating every dash as a delimiter would be a guess this file's discipline forbids
-// everywhere else. ----
+// everywhere else.
+//
+// Tier 6 playtest tried making the trailing delimiter optional too (to catch
+// "what calls listTasks -- oh wait, i mean createTask" — no comma after "i
+// mean") and reverted it live: this regex's `.+?` prefix discards EVERYTHING
+// before the marker, which is correct for a FULL-CLAUSE restart (the remainder
+// is a complete new question, verb included, e.g. "which classes inherit from
+// Base") but wrong for an OBJECT-ONLY restart, where the verb clause ("what
+// calls") must survive and only the object swaps. Without the delimiter, this
+// object-only shape reduced to the bare noun "createTask" alone (no verb at
+// all) — a genuine regression from the honest "did you mean listTasks or
+// createTask?" ambiguity nudge the UNCHANGED regex already gives (a real
+// candidate list including the correct answer is an acceptable FLOW under
+// SKILL_CHAT_PLAYTEST.md §0/§2, not a dead end) to a hard wall. Fixing the
+// object-only case properly needs verb-clause-preserving logic this closed,
+// delimiter-anchored frame mechanism isn't shaped for — left as a genuine,
+// narrower ceiling rather than risk widening this proven, tested regex. ----
 const SELF_CORRECTION_RE =
   /^.+?(?:\s*(?:--|—|-)\s*)?\b(?:sorry|i\s+mean)\b\s*(?:--|—|-|,|:)\s*(.+)$/i;
 

package/src/interpret/strategies/grammar.mjs

@@ -7,6 +7,7 @@
 import {
   VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
   META_MEANING_VERBS, WHERE_MARKERS, MENTION_MARKERS,
+  INHERITS_REVERSE_VERBS, stripTrailingScopeFiller,
 } from "../../ask-vocab.mjs";
 import { escapeRegex } from "../normalize.mjs";
 
@@ -20,13 +21,28 @@ const TEMPLATES = [
   // does/is/do/did, which the reverse/forward templates below never match (those start with
   // which/what), so precedence between T1 and the rest is structural, not a tie-break guess.
   // "did" joins does/do for the past-tense commit forms ("did commit <sha> touch X").
+  // REVERSE VERB SWAP (Seonix Batch 2 Fix 2): this template fixes subject/object by regex
+  // capture POSITION, not by the verb's semantic direction — fine for every forward verb
+  // ("subclass of", "imports", …), but "is X a superclass of Y" MEANS the reverse of "is X
+  // a subclass of Y" (Y inherits from X, not X from Y). INHERITS_REVERSE_VERBS (ask-vocab.mjs)
+  // is the closed set of such reverse phrasings; when the matched verb is one of them,
+  // subject/object are swapped here, once, at parse time — so downstream evaluation (ask.mjs)
+  // sees "is Y a subclass of X" and needs zero changes of its own. (In practice this exact
+  // regex only ever matches a does/do/did lead, so "is …" phrasings actually reach the "ask"
+  // shape via keywords.mjs's decomposition strategy instead — that strategy applies the same
+  // swap for the same reason; this branch is kept for any does/do/did-led phrasing that names
+  // a reverse verb, and for structural symmetry with that sibling strategy.)
   {
     name: "ask",
     re: new RegExp(`^(?:does|do|did)\\s+(.+?)\\s+(${VERB_ALT})\\s+(.+?)\\??$`, "i"),
-    build: (m) => ({
-      shape: "ask", entityType: null, modifier: "direct",
-      kind: VERB_TO_KIND[m[2].toLowerCase()], subject: m[1].trim(), object: m[3].trim(),
-    }),
+    build: (m) => {
+      const verb = m[2].toLowerCase();
+      const kind = VERB_TO_KIND[verb];
+      let subject = m[1].trim();
+      let object = m[3].trim();
+      if (INHERITS_REVERSE_VERBS.includes(verb)) [subject, object] = [object, subject];
+      return { shape: "ask", entityType: null, modifier: "direct", kind, subject, object };
+    },
   },
   // T2 reverse: "which <entity> [<modifier>] <verb> <object>" — the operator's own example shape.
   {
@@ -63,15 +79,32 @@ const TEMPLATES = [
     build: (m) => ({ shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: m[1].trim() }),
   },
   // T5 meta: "what is a/an <term>" — the OTHER worked phrasing ("what is a Commit").
-  // The indefinite article is REQUIRED (not optional): a bare "what is <anything>"
-  // would also swallow "what is the meaning of this codebase" (an existing, deliberately
-  // honest grammar-miss regression case — ask.test.mjs/ask-dual-strategy.test.mjs both
-  // assert it stays null), which never mentions "a"/"an" before its tail. Requiring the
-  // article keeps this template's reach to the one worked shape without reopening that.
+  // Seonix Batch 2 Fix 1: the indefinite article is now OPTIONAL, but the BARE
+  // (no-article) form is restricted to the CLOSED vocabulary ENTITY_TO_TYPE already
+  // imported above (function/method/class/module/attribute/variable/change/commit,
+  // singular and plural) — build() returns null (same "this template didn't actually
+  // match, keep scanning" contract T8/"when" below already relies on — see
+  // parseAnchored's own docblock) when the bare form's object isn't one of those
+  // closed terms, so the scan falls through exactly as if this template had not
+  // matched at all. This keeps "what is a doohickey"/"widget"/"gizmo" (still routed
+  // here via the WITH-article, fully unrestricted `(.+?)` path — pinned to resolve as
+  // an honest meta miss downstream, ask-combo.test.mjs/chat-readback.test.mjs) working
+  // unmodified, while ALSO keeping the two pinned bare-form honest misses intact:
+  // "what is the meaning of this codebase" (ask.test.mjs/ask-dual-strategy.test.mjs)
+  // and "what is exposed" (ask.test.mjs:840) both have bare objects absent from
+  // ENTITY_TO_TYPE, so build() still rejects them and they still fall through to null.
+  // Fix 3: stripTrailingScopeFiller (ask-vocab.mjs) trims a curated trailing clause
+  // ("what is a Module in this graph" -> "Module") off the object before it's
+  // returned, so a scoping tail never corrupts the lookup term either the bare-form
+  // check above or downstream resolution/rendering perform.
   {
     name: "meta-whatis",
-    re: new RegExp(`^what\\s+(?:is|are)\\s+(?:an?)\\s+(.+?)\\??$`, "i"),
-    build: (m) => ({ shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: m[1].trim() }),
+    re: new RegExp(`^what\\s+(?:is|are)\\s+(?:(an?)\\s+)?(.+?)\\??$`, "i"),
+    build: (m) => {
+      const object = m[2].trim();
+      if (!m[1] && !ENTITY_TO_TYPE[object.toLowerCase()]) return null; // bare form: closed-set only
+      return { shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: stripTrailingScopeFiller(object) };
+    },
   },
   // T6 mention: "where is <term> mentioned/referenced" — the prose/mentions surface
   // (2026-07-02 query families). Tried BEFORE T7: T7's trailing marker is optional,

package/src/interpret/strategies/keywords.mjs

@@ -8,6 +8,7 @@
 import {
   VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
   WHERE_MARKERS, MENTION_MARKERS, PLACEHOLDER_NOUNS, PASSIVE_PARTICIPLE_TO_KIND,
+  INHERITS_REVERSE_VERBS,
 } from "../../ask-vocab.mjs";
 import { STOPWORDS } from "../normalize.mjs";
 import { VOCAB_WORDS, eligibleForCanon, fuzzyVocabWord } from "../fuzzy.mjs";
@@ -227,7 +228,20 @@ export function parseKeywordSpot(text, nlp = null) {
     }
   }
 
-  if (beforeText && afterText) return { shape: "ask", entityType: null, modifier: "direct", kind, subject: beforeText, object: afterText };
+  if (beforeText && afterText) {
+    // REVERSE VERB SWAP (Seonix Batch 2 Fix 2): this decomposition assigns subject/
+    // object by POSITION (before the verb / after it), not by the verb's semantic
+    // direction — the same structural fact grammar.mjs's T1 "ask" template comment
+    // explains. "is X a superclass of Y" (or its bare "superclass" stem — see
+    // INHERITS_REVERSE_VERBS's own comment in ask-vocab.mjs) means the REVERSE of
+    // "is X a subclass of Y": swap once, here, at parse time, so evaluation always
+    // sees the equivalent forward-phrased question.
+    const verbPhrase = canonWords.slice(verbHit.start, verbHit.end).join(" ");
+    let subject = beforeText;
+    let object = afterText;
+    if (INHERITS_REVERSE_VERBS.includes(verbPhrase)) [subject, object] = [object, subject];
+    return { shape: "ask", entityType: null, modifier: "direct", kind, subject, object };
+  }
   if (afterText) return { shape: "reverse", entityType, modifier, kind, object: afterText };
   // forward keeps the spotted entityType ("which modules did commit <sha> touch" is a
   // forward decomposition — subject before the verb — whose asked grain would otherwise

package/src/memory/core.mjs

@@ -424,12 +424,26 @@ export async function appendUtterances(dir, utterances) {
  *  spelling and the graph stays queryable: ConceptNet's /c/en/foo_bar, a
  *  grammar's tmct:Foo_bar and a bare "Foo bar" all become "foo bar". The
  *  PREDICATE is deliberately NOT normalized this way - it is a controlled
- *  vocabulary term (rdfs:subClassOf) whose casing is meaningful. */
+ *  vocabulary term (rdfs:subClassOf) whose casing is meaningful.
+ *
+ *  Tier-5 playtest fix (2026-07-09): also strips a leading "the"/"a"/"an" —
+ *  found live via "remember that THE logger module is deprecated" (teach-side
+ *  already stripped it before this ran, so storage was unaffected) followed by
+ *  "what do you know about THE logger module" / "who maintains THE tasks
+ *  handler" (recall-side queries, which do NOT pre-strip their own captured
+ *  term before calling this) genuinely missing the just-taught fact — every
+ *  recall regex in chat.mjs (KNOW_ABOUT_RE, WHO_OWNS_RE, ISA_ASK_RE, …) calls
+ *  factTermVariants -> normFactTerm on the raw captured term, so fixing it
+ *  ONCE here closes the gap for all of them instead of patching each site.
+ *  Safe for storage too (idempotent — an already-stripped subject is
+ *  unaffected); the article is a determiner, never semantically distinguishing
+ *  for a code-entity or common-noun term in this domain. */
 export function normFactTerm(t) {
   let s = normText(t);
   s = s.replace(/^\/c\/[a-z]{2,3}\//i, "");
   s = s.replace(/^[a-z][\w.-]*:/i, "");
   s = s.replace(/_/g, " ").replace(/\s+/g, " ").trim();
+  s = s.replace(/^(?:the|an?)\s+/i, "");
   return s.toLowerCase();
 }