@polycode-projects/the-mechanical-code-talker 1.4.1 → 1.5.2

package/data/templates/constructions/agent-noun-relations.toml

@@ -0,0 +1,98 @@
+# data/templates/constructions/agent-noun-relations.toml — construction-grammar
+# template bank (PLAN_ADVANCED_GRAMMAR.md track (d)): per-construction closed
+# template families as DATA, loaded by src/interpret/strategies/constructions.mjs
+# beside grammar.mjs's anchored T1-T10 grammar (this file's constructions are the
+# next numbers, T11-T13 — see the `id` field on each [[construction]] below; do
+# not renumber grammar.mjs's own T1-T10, this is an ADDITIVE, own-class strategy).
+#
+# The linguistic point (Construction Grammar, Goldberg 1995/2006): the SAME
+# underlying relation ("things that import X") is realized by a developer through
+# several distinct surface CONSTRUCTIONS — a prepositional NP ("importers of X"),
+# a genitive-'s NP ("X's importers"), and a bare compound-juxtaposition NP ("X
+# importers") — each its own grammatical FORM pairing with the same MEANING. This
+# is a genuine gap, not a duplicate of grammar.mjs's T1-T10 or normalize.mjs's
+# PHRASING_FRAMES: the "of"-NP form already reaches the graph correctly via the
+# keyword-spot strategy's decomposition (interpret/strategies/keywords.mjs), but
+# the genitive/compound forms do NOT — keyword-spot mis-parses "store.mjs's
+# importers" / "store.mjs importers" as shape "forward" (reading store.mjs as the
+# grammatical SUBJECT doing the importing) instead of "reverse" (store.mjs is the
+# OBJECT being imported; the agent noun names WHO does the verb TO it) — confirmed
+# live before this file existed. These three constructions fix that, and route
+# the "of" form through the same anchored, closed table for consistency.
+#
+# Two [[relation]] tables define the closed AGENT-NOUN vocabulary (a plural
+# nominalization of a relation verb -> {kind, entityType?}), validated at load
+# time by the strategy against RELATIONS' own kind vocabulary (ask-vocab.mjs) and
+# ENTITY_TO_TYPE's canonical class names — an unrecognized kind/entityType is
+# REJECTED (the entry is dropped, never guessed into the nearest match), same
+# "closed is deliberate" discipline as ask-vocab.mjs's RELATIONS table itself.
+#
+# Deliberately narrow, hand-curated set (not exhaustive): each noun is one a
+# developer plausibly types for THIS codebase's relations, same judgment-call
+# discipline ask-vocab.mjs's file header already states. "testers"/"containers"/
+# "exporters"/"definers" were considered and left out — too easily confused with
+# unrelated code-domain nouns (a Docker "container", a DI "container", a test
+# "runner") or simply not natural developer phrasing; a false-positive match on
+# an unrelated identifier is worse than an honest miss, so the set stays small.
+
+[[relation]]
+noun = "importers"
+kind = "imports"
+entityType = "Module"     # the imports edge is module-grain only
+
+[[relation]]
+noun = "callers"
+kind = "calls"
+# no entityType: calls resolves at function/method OR module grain (ask.mjs's
+# own fine/coarse call-edge handling) — leaving this unset means entityType null,
+# "any grain", exactly like grammar.mjs's own bare "what calls X" (T3 forward).
+
+[[relation]]
+noun = "users"
+kind = "uses"
+# uses is itself a query-side union (imports + calls + callsSymbol, ask-vocab.mjs)
+# — no single entityType is correct, so this stays grain-agnostic too.
+
+[[relation]]
+noun = "subclasses"
+kind = "inherits"
+entityType = "Class"      # inherits is Class -> Class only
+
+# ---- constructions: pattern -> AST skeleton -------------------------------
+# Pattern DSL (src/interpret/strategies/constructions.mjs compiles this):
+#   <AGENT>  one of the [[relation]] nouns above (closed alternation, longest
+#            noun first so e.g. a hypothetical multi-word noun would never be
+#            shadowed by a shorter one sharing a prefix)
+#   <TERM>   a free-text object term, non-greedy — the SAME "capture the rest,
+#            let resolveObject do real matching" contract every anchored
+#            template in grammar.mjs already uses
+#   any other text is a literal (case-insensitive, whitespace-normalized)
+# Every construction here compiles to shape="reverse": the AGENT noun names the
+# relation's SUBJECT side, <TERM> is the OBJECT being related-to — precisely
+# grammar.mjs's own T2 "reverse" shape (entityType/modifier/kind/object), just
+# reached from a different surface form. A future construction needing a
+# different `shape` is free to declare one; the strategy loader supports the
+# full anchored-template shape vocabulary (ask/reverse/forward/where/when/
+# meta/mentions), not "reverse" exclusively — this bank simply doesn't need the
+# others yet.
+
+[[construction]]
+id = "T11"
+name = "agent-noun-of"
+comment = "\"importers of X\" -> reverse imports X. Also reached (correctly) by keyword-spot today; kept here for a single closed, anchored source of truth and byte-identical precedence with the other two surface forms below."
+pattern = "<AGENT> of <TERM>"
+shape = "reverse"
+
+[[construction]]
+id = "T12"
+name = "agent-noun-genitive"
+comment = "\"X's importers\" -> reverse imports X. The genitive-'s NP; keyword-spot currently mis-reads this as forward (X importing things) — this construction is the fix."
+pattern = "<TERM>'s <AGENT>"
+shape = "reverse"
+
+[[construction]]
+id = "T13"
+name = "agent-noun-compound"
+comment = "\"X importers\" (bare compound-noun juxtaposition, no possessive marker or preposition) -> reverse imports X. The same mis-parse as T12's genitive form, without the apostrophe; a developer drops the 's as often as they keep it."
+pattern = "<TERM> <AGENT>"
+shape = "reverse"

package/data/templates/responses.jsonl

@@ -66,6 +66,7 @@
 {"id":"orientation-empty","class":"orientation","register":"friendly","template":"I'm tmct — a deterministic, offline chat assistant (no LLM). {vocabHint} /memory for what I remember.\nFor code structure (imports, calls, definitions) point me at a repo: `--repo <path>`, or try the shipped example `npm run example:mini`. tmct reads graphs; it doesn't index code itself.\n/help for commands."}
 {"id":"identity-self","class":"conversational","register":"friendly","template":"I'm tmct — a deterministic, offline chat assistant. No LLM: wink-nlp parsing over a seeded ontology/lexicon, plus a code graph when you point me at a repo with `--repo <path>`. /help for commands, /stats for an overview."}
 {"id":"identity-not-an-llm","class":"conversational","register":"friendly","template":"No — no LLM involved. tmct is deterministic: wink-nlp parsing over a graph/ontology, not a language model. /help for commands."}
+{"id":"identity-no-feelings","class":"conversational","register":"friendly","template":"No — I don't have feelings, opinions, or consciousness. tmct is deterministic: wink-nlp parsing over a graph/ontology, not a mind. /help for commands."}
 {"id":"technical-density","class":"count","register":"technical","template":"{subject} carries {count} {noun} across {scope} — a concentration well above what a codebase of this size typically sustains ({provenance})."}
 {"id":"technical-comparison","class":"count","register":"technical","template":"At {count} {noun}, {subject} sits {comparison} the comparable-project baseline, a divergence that reflects deliberate structure rather than measurement noise ({provenance})."}
 {"id":"technical-superlative","class":"count","register":"technical","template":"No {noun} in {scope} is more {metric} than {subject}; it leads the next candidate by a clear margin of {count} ({provenance})."}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.4.1",
+  "version": "1.5.2",
   "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.",
@@ -36,6 +36,9 @@
   "engines": {
     "node": ">=24"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "bin": {
     "tmct": "./bin/tmct.mjs"
   },
@@ -68,6 +71,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@polycode-projects/ace-owl": "^0.1.0",
     "ink": "^7.1.0",
     "react": "^19.2.7",
     "smol-toml": "^1.7.0",

package/src/ask-vocab.mjs

@@ -307,6 +307,40 @@ export function stripTrailingScopeFiller(text) {
   return text.replace(TRAILING_SCOPE_FILLER_RE, "").trim();
 }
 
+/** Trailing bare discourse tags — the same curated "then"/"though" pair
+ *  ask.mjs's PRED_LEAD_SKIP already recognizes as a trailing discourse tag on
+ *  an otherwise-bare follow-up ("how many of those then"). A "what is X"
+ *  meta-whatis question wasn't tolerant of this yet: "what is a component
+ *  then" captured the literal unknown term "component then" instead of
+ *  "component" (HANDOVER.md 2026-07-10, item 8). Stripped the same
+ *  closed-list way as TRAILING_SCOPE_FILLER, just above. "too" (playtest
+ *  sprint round 2): "is UserController a validator too then" — a STACKED
+ *  pair of trailing tags — needed both "too" added to the set AND the strip
+ *  applied twice (below), since a single pass only ever removes the
+ *  outermost tag. */
+export const TRAILING_DISCOURSE_TAG = Object.freeze(["then", "though", "too"]);
+
+const TRAILING_DISCOURSE_TAG_RE = new RegExp(
+  `\\s+(?:${TRAILING_DISCOURSE_TAG.join("|")})\\s*[?.!]*$`, "i",
+);
+
+/** Strip trailing bare discourse tags (TRAILING_DISCOURSE_TAG, above) off the
+ *  end of a captured meta-whatis term — "what is a component then" resolves
+ *  the same term as "what is a component". Applied up to twice (a stacked
+ *  "too then"/"then too" is the only worked case that ever needs a second
+ *  pass; no phrasing seen so far stacks a third), mirroring
+ *  stripTrailingScopeFiller's own single-clause discipline for the common
+ *  single-tag case while still covering the rarer double-tag one. */
+export function stripTrailingDiscourseTag(text) {
+  let out = text;
+  for (let pass = 0; pass < 2; pass += 1) {
+    const next = out.replace(TRAILING_DISCOURSE_TAG_RE, "").trim();
+    if (next === out) break;
+    out = next;
+  }
+  return out;
+}
+
 /** relation token -> flat verb-phrase list, the shape ask.mjs's VERB_TO_KIND
  *  table needs (phrase -> kind), derived once from RELATIONS. */
 export const VERB_TO_KIND = Object.freeze(
@@ -319,7 +353,11 @@ export const ENTITY_TO_TYPE = Object.freeze({
   function: "Function", functions: "Function",
   method: "Method", methods: "Method",
   class: "Class", classes: "Class",
-  module: "Module", modules: "Module", file: "Module", files: "Module",
+  // "mod"/"mods" (HANDOVER.md 2026-07-10 item 10): a rushed-dev abbreviation
+  // prefix ("mod store.mjs imports") used to land in disambiguation instead of
+  // resolving cleanly, since nothing recognized "mod" as this same Module noun
+  // — same alias-of-Module trade "file"/"files" already make just above.
+  module: "Module", modules: "Module", mod: "Module", mods: "Module", file: "Module", files: "Module",
   attribute: "Attribute", attributes: "Attribute", field: "Attribute", fields: "Attribute",
   variable: "GlobalVariable", variables: "GlobalVariable", global: "GlobalVariable", globals: "GlobalVariable",
   // "changes" in a touch question ("which changes touch commit <sha>") means the

package/src/ask.mjs

@@ -324,6 +324,7 @@ function parseComposite(text, nlp) {
     || parseNegation(text, nlp, 0)
     || parseForwardNegation(w, lc, nlp)
     || parseTemporal(w, lc, nlp, 0)
+    || parseCommitFilter(w, lc)
     || parseAnaphora(w, lc, nlp)
     || parseAggregate(w, lc, nlp)
     || parseSuperlative(w, lc, nlp)
@@ -533,6 +534,61 @@ function parseTemporal(w, lc, nlp, depth = 0) {
   return { node: "temporal", inner, entityType: (noun && noun.entityType) || null };
 }
 
+// COMMIT FILTER (Track 1 temporal lever, PLAN_CHAT_FEEL item 6 remainder) — "what
+// changed since/before/after/on <date-or-commit>": a date-qualified SURVEY of every
+// recorded commit (distinct from the flat when-shape above, which dates ONE named
+// entity's touch history). The pivot is either a literal ISO-8601 date (yyyy-mm-dd,
+// mgx:commitDate's own format, so a lexical compare is a chronological one) or a
+// named commit — resolved at EVAL time (graph-dependent), whose own recorded date
+// becomes the pivot and who is excluded from its own before/after comparison (never
+// "before/after itself"). "in"/"during" are deliberately NOT among the qualifiers:
+// "what changed in <commit>" already means something else (that commit's own touch-
+// set — the commit-as-subject flip elsewhere in this file), and this recognizer must
+// never shadow it.
+const COMMIT_FILTER_OPS = new Set(["since", "before", "after", "on"]);
+function parseCommitFilter(w, lc) {
+  if (lc[0] !== "what" || lc[1] !== "changed") return null;
+  let i = 2;
+  if (lc[i] === "ever") i += 1;
+  if (!COMMIT_FILTER_OPS.has(lc[i])) return null;
+  const op = lc[i];
+  const pivotRaw = w.slice(i + 1).join(" ").trim();
+  if (!pivotRaw) return { node: "miss", reason: `"what changed ${op}" needs a date or commit afterward` };
+  return { node: "commitFilter", op, pivotRaw };
+}
+
+// Minimal code-identifier token shape — dotted paths ("app/lib/e.mjs"), Capitalized
+// symbols ("Store"), or lowerCamelCase symbols ("fnAlpha"). Intentionally DUPLICATED
+// from chat.mjs's own NAME_TOKEN_RE (chat.mjs ~line 4998, used there for exactly this
+// kind of code-identifier detection in discourseRewrite) rather than imported:
+// chat.mjs only ever imports ask.mjs LAZILY (dynamic `await import("./ask.mjs")`,
+// per chat.mjs's own top-of-file comment), so a static ask.mjs -> chat.mjs import
+// would invert that layering for the sake of one regex. Keep the two in sync by
+// hand if either changes.
+const ANAPHORA_NAME_TOKEN_RE = /\b[\w-]+(?:[/.][\w-]+)+\b|\b[A-Z][A-Za-z0-9_]*\b|\b[a-z][a-z0-9]*[A-Z][A-Za-z0-9]*\b/;
+
+/** Distinct code-identifier-shaped tokens in `words` (original case preserved —
+ *  the regex cares about case), in first-occurrence order, de-duplicated
+ *  case-insensitively. Feeds parseAnaphora's in-sentence candidate-set fix
+ *  (HANDOVER.md item 1, C2 pronoun-binding): "which of them <filter>" doesn't
+ *  ALWAYS mean "the previous turn's answer set" — when the SAME sentence already
+ *  named 2+ real candidates before the trigger ("app/lib/e.mjs ... app/lib/f.mjs
+ *  ... which of them ...", a single turn, no prior turn at all), THAT'S the
+ *  referent. Ordinary English words (even repeated nouns) never match this
+ *  regex, so this never widens beyond genuine code identifiers. */
+function inSentenceNameTokens(words) {
+  const seen = new Set();
+  const out = [];
+  for (const raw of words) {
+    if (!raw || !ANAPHORA_NAME_TOKEN_RE.test(raw)) continue;
+    const key = raw.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(raw);
+  }
+  return out;
+}
+
 /** ANAPHORA over the previous result set: "which of those/them <filter>", "how many
  *  of those <filter>". Requires "of <pronoun>" (so a bare "those" in a term never
  *  fires). Returns a {node:"anaphora"} (mode count|list), a miss (filter present but
@@ -569,7 +625,19 @@ function parseAnaphora(w, lc, nlp) {
   const mode = AGGREGATE_TRIGGERS.includes(head) || /^(how many|how much|count|number|quantity|total)\b/.test(head) ? "count" : "list";
   const filter = parsePredicateFilter(w.slice(p + 1), nlp);
   if (filter === undefined) return { node: "miss", reason: "the follow-up filter didn't parse" };
-  return { node: "anaphora", mode, filter };
+  // in-sentence candidate set (HANDOVER.md item 1): if the SAME utterance already
+  // named 2+ real code identifiers BEFORE the "of them"/"of those" trigger — e.g.
+  // "app/lib/e.mjs ... because it imports app/lib/f.mjs — which of them imports
+  // app/lib/f.mjs" — those are the referent, not a previous turn's cached result
+  // set. evalAnaphora tries this FIRST and only falls back to opts.prev when it's
+  // absent or resolves to fewer than 2 real graph entities, so an ordinary
+  // multi-turn follow-up (no named entities in the current utterance at all) is
+  // completely unaffected.
+  const cutIdx = viaOf ? p - 1 : p;
+  const candidateTerms = inSentenceNameTokens(w.slice(0, cutIdx));
+  const ast = { node: "anaphora", mode, filter };
+  if (candidateTerms.length >= 2) ast.candidateTerms = candidateTerms;
+  return ast;
 }
 
 /** Parse a trailing filter (for anaphora, and any "of those that …" tail) into
@@ -1053,6 +1121,22 @@ function parseRelationalOrQualified(w, lc, nlp, depth) {
     if (RECENT_COMMIT_LEAD.has(lc[i]) && nextNoun && nextNoun.entityType === "Commit" && i + 2 === lc.length) {
       return { node: "recentCommits" };
     }
+    // Track 1 temporal lever (remainder) — the SAME bare lead, past an optional
+    // copula + determiner ("what IS THE newest commit", "what WAS THE latest
+    // commit"): FRAME_WORDS only strips "what"/"which"/…, so "is the"/"was the"
+    // left `i` sitting on the copula, never reaching the check above at all. A
+    // narrow lookahead (never mutating `i`, so every OTHER branch here is
+    // byte-identical) that re-tries the exact same closed RECENT_COMMIT_LEAD
+    // check past those two filler words only — an honest decline (falls through)
+    // the instant either word doesn't match, never a guess.
+    if (COPULA_WORDS.has(lc[i])) {
+      let j = i + 1;
+      if (j < lc.length && (lc[j] === "the" || lc[j] === "a" || lc[j] === "an")) j += 1;
+      const leadNoun = j + 1 < lc.length ? entityNoun(lc[j + 1]) : null;
+      if (RECENT_COMMIT_LEAD.has(lc[j]) && leadNoun && leadNoun.entityType === "Commit" && j + 2 === lc.length) {
+        return { node: "recentCommits" };
+      }
+    }
     // CASCADE_NOISE_SET excluded alongside STOPWORDS (Tier-2 playtest, cycle 8):
     // "what about classes"/"how about the modules" used to reach here with
     // "about" sitting right where a real qualifying adjective would ("payment"
@@ -1343,6 +1427,42 @@ function moduleIdOf(graph, ind) {
   return qualSets(graph).moduleOfSymbol.get(ind.id) || null;
 }
 
+/** META FALLBACK TO REAL ENTITIES (0.8.2 WS1; widened + extracted HANDOVER.md
+ *  2026-07-10 item 6): "what is a Record" used to say "'Record' isn't a term in
+ *  this graph's own vocabulary" even when Record is a real code-graph entity —
+ *  after a SchemaClass/SchemaPredicate miss, an exact case-insensitive UNIQUE
+ *  label match against a small set of real code-entity classes (Class/Function/
+ *  Method/GlobalVariable/Attribute — not just Class; CHATBENCH g-a2-naming-6:
+ *  "what does fnAlpha mean", a Function, hit this same false vocabulary-miss
+ *  wall). Uniqueness is GLOBAL across all these classes together, not per-class:
+ *  a name colliding across two different classes stays an honest miss, never a
+ *  guess at which one was meant. Extracted (not just inlined in traverse()'s own
+ *  meta branch below) so chat.mjs's BARE "what is X" last-resort lane — no
+ *  article, so T5's structural parse never even produces a meta shape to reach
+ *  traverse() at all (CHATBENCH g-a2-naming-2: "what is Widget") — can reuse the
+ *  exact same lookup + wording, rather than risk the two silently drifting
+ *  apart. Returns null on anything less than a unique exact hit. */
+const META_FALLBACK_CLASSES = new Set(["Class", "Function", "Method", "GlobalVariable", "Attribute"]);
+export function metaFallbackEntityAnswer(graph, term) {
+  const termLc = String(term || "").trim().toLowerCase();
+  if (!termLc) return null;
+  const hits = (graph?.individuals || []).filter((i) => META_FALLBACK_CLASSES.has(i.class) && String(i.label).toLowerCase() === termLc);
+  if (hits.length !== 1) return null;
+  const hit = hits[0];
+  const mid = moduleIdOf(graph, hit);
+  const modLabel = (mid && graph.byId.get(mid)?.label)
+    || String((hit.attributes || []).find((a) => a.key === "site")?.value || "").split(":")[0]
+    || null;
+  const noun = nounFor(hit.class, 1);
+  const article = noun === "attribute" ? "an" : "a";
+  const definedIn = modLabel ? `, defined in ${modLabel}` : "";
+  const followUp = hit.class === "Class" ? ` or "which classes inherit from ${hit.label}"` : "";
+  return {
+    text: `${hit.label} is ${article} ${noun} in this codebase${definedIn} — try "describe ${hit.label}"${followUp}.`,
+    hit, modLabel,
+  };
+}
+
 // ---- MEMBERSHIP inheritance cascade (HANDOVER item 6) — "<kind> of <owner>" walks
 // UP `inherits` when the owner's own surface has nothing, exactly the way
 // computeFind's narrow-then-broaden pass does for predicate-find, below. ----
@@ -1704,12 +1824,36 @@ function evalBoolean(graph, ast, opts) {
   return acc;
 }
 
-/** Anaphora over ask()'s `prev` id array — filter/count the previous answer's ids.
- *  No prev supplied → honest miss (never a guess), like an unresolved pronoun. */
+/** Resolve parseAnaphora's in-sentence candidateTerms (HANDOVER.md item 1) to real
+ *  graph entities, de-duplicated by resolved id. Returns null (not just []) when
+ *  fewer than 2 resolve, so the caller can tell "no in-sentence candidates" apart
+ *  from "named candidates that happen to fail resolution" and fall back to
+ *  opts.prev either way — never a guess, same discipline as everywhere else in
+ *  this function. */
+function resolveInSentenceCandidates(graph, terms) {
+  if (!Array.isArray(terms) || terms.length < 2) return null;
+  const seen = new Set();
+  const resolved = [];
+  for (const term of terms) {
+    const r = resolveObject(graph, term);
+    if (r && r.match && !seen.has(r.match.id)) { seen.add(r.match.id); resolved.push(r.match); }
+  }
+  return resolved.length >= 2 ? resolved : null;
+}
+
+/** Anaphora over the candidate set: EITHER the current utterance's own in-sentence
+ *  named entities (parseAnaphora's candidateTerms — a single turn, no prior turn
+ *  needed at all, HANDOVER.md item 1), tried first, OR ask()'s `prev` id array (a
+ *  genuine previous-turn follow-up), filtered/counted the same way either way. No
+ *  candidate set at all → honest miss (never a guess), like an unresolved pronoun. */
 function evalAnaphora(graph, ast, opts) {
-  const prev = opts && opts.prev;
-  if (!Array.isArray(prev) || !prev.length) return { compositeMiss: true, reason: "no-prev", matches: [] };
-  const baseItems = prev.map((id) => graph.byId.get(id)).filter(Boolean);
+  const inSentence = resolveInSentenceCandidates(graph, ast.candidateTerms);
+  let baseItems = inSentence;
+  if (!baseItems) {
+    const prev = opts && opts.prev;
+    if (!Array.isArray(prev) || !prev.length) return { compositeMiss: true, reason: "no-prev", matches: [] };
+    baseItems = prev.map((id) => graph.byId.get(id)).filter(Boolean);
+  }
   let items = baseItems;
   const f = ast.filter;
   if (f && f.type === "qual") {
@@ -1770,6 +1914,41 @@ function evalRecentCommits(graph) {
   return { compositeKind: "recentCommits", matches: commits };
 }
 
+const COMMIT_FILTER_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** COMMIT FILTER eval — resolves the pivot (a literal ISO date, or a NAMED commit
+ *  whose own recorded date becomes the pivot — resolved here, graph-dependent, per
+ *  the parser's own doc), then filters every Commit individual's date against it.
+ *  A pivot that IS itself a commit is excluded from its own comparison. An
+ *  unresolvable pivot (neither a date nor a known commit) declines honestly
+ *  (pivotResolved:false) rather than guessing an empty result. */
+function evalCommitFilter(graph, ast) {
+  const { op, pivotRaw } = ast;
+  const dateOf = (c) => String((c.attributes || []).find((a) => a.key === "date")?.value || "").slice(0, 10);
+  let pivotDate = null;
+  let pivotId = null;
+  if (COMMIT_FILTER_DATE_RE.test(pivotRaw)) {
+    pivotDate = pivotRaw;
+  } else {
+    const { match, ambiguous } = resolveObject(graph, pivotRaw, { expectedClass: "Commit" });
+    if (match && !ambiguous && match.class === "Commit" && dateOf(match)) {
+      pivotId = match.id;
+      pivotDate = dateOf(match);
+    }
+  }
+  if (!pivotDate) return { compositeKind: "commitFilter", op, pivotRaw, pivotResolved: false, matches: [] };
+  const matches = graph.individuals
+    .filter((i) => i.class === "Commit" && i.id !== pivotId && dateOf(i))
+    .filter((c) => {
+      const d = dateOf(c);
+      if (op === "since") return d >= pivotDate;
+      if (op === "before") return d < pivotDate;
+      if (op === "after") return d > pivotDate;
+      return d === pivotDate; // "on"
+    })
+    .sort((a, b) => dateOf(b).localeCompare(dateOf(a)));
+  return { compositeKind: "commitFilter", op, pivotRaw, pivotDate, pivotResolved: true, matches };
+}
+
 /** TEMPORAL over a nested set (lever 3) — the commits that touched ANY member of the
  *  inner set, newest commit date first. Reuses the SAME touches→commit→date-sort the
  *  flat when-shape runs (mgx:commitDate is ISO-8601, so a lexical sort IS a date sort;
@@ -1898,6 +2077,7 @@ export function evalComposite(graph, ast, opts = {}) {
   if (ast.node === "superlative") return evalSuperlative(graph, ast);
   if (ast.node === "temporal") return evalTemporal(graph, ast, opts);
   if (ast.node === "recentCommits") return evalRecentCommits(graph);
+  if (ast.node === "commitFilter") return evalCommitFilter(graph, ast);
   if (ast.node === "anaphora") return evalAnaphora(graph, ast, opts);
   // membership inheritance cascade (HANDOVER item 6), TOP-LEVEL: a bare "<kind> of
   // <owner>" node, or a qualifier wrapping one ("public methods of <owner>") — see
@@ -2069,6 +2249,33 @@ function renderComposite(parsed, result) {
       miss: false, ambiguous: false, matches: result.matches,
     };
   }
+  // Track 1 temporal lever (remainder): "what changed since/before/after/on
+  // <date-or-commit>" — same dated-list rendering convention as recentCommits just
+  // above, scoped to the resolved pivot. An unresolvable pivot names itself and the
+  // two supported pivot shapes (never a silent guess); a resolved pivot with no
+  // qualifying commits is an honest empty (never the generic orientation blurb).
+  if (result.compositeKind === "commitFilter") {
+    if (!result.pivotResolved) {
+      return {
+        content: `"${result.pivotRaw}" isn't a recognized date (yyyy-mm-dd) or a known commit — try "what changed since 2026-06-01" or "what changed before <commit>".`,
+        miss: true, ambiguous: false, matches: [],
+      };
+    }
+    if (!result.matches.length) {
+      return { content: `no commits recorded ${result.op} ${result.pivotRaw}.`, miss: true, ambiguous: false, matches: [] };
+    }
+    const dateOf = (c) => String((c.attributes || []).find((a) => a.key === "date")?.value || "");
+    const shown = result.matches.slice(0, HISTORY_CAP).map((c) => {
+      const day = dateOf(c).slice(0, 10);
+      const msg = (c.attributes || []).find((a) => a.key === "message")?.value || "";
+      return `${c.label}${day ? ` (${day})` : ""}${msg ? ` — ${msg}` : ""}`;
+    });
+    const tail = result.matches.length > HISTORY_CAP ? ` …+${result.matches.length - HISTORY_CAP} more` : "";
+    return {
+      content: `${result.matches.length} commit(s) changed ${result.op} ${result.pivotRaw}: ${shown.join(", ")}${tail}.`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
   if (result.compositeKind === "superlative") {
     if (!result.matches.length) return { content: `no ${nounFor(result.entityType, 2)} to rank in this index.`, miss: true, ambiguous: false };
     const lead = result.extreme === "most" ? "the most" : "the fewest";
@@ -2733,24 +2940,17 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
       return token && String(token).toLowerCase() === termLc;
     });
     if (!match) {
-      // META FALLBACK TO REAL ENTITIES (0.8.2 WS1): "what is a Record" used to say
-      // "'Record' isn't a term in this graph's own vocabulary" even when Record is a
-      // code-graph Class individual. After the SchemaClass/SchemaPredicate miss, try
-      // an exact case-insensitive UNIQUE label match against class === "Class"
-      // individuals; a unique hit renders a describe-style one-liner (see render's
-      // metaCodeClass branch). Anything less than a unique exact hit keeps the
-      // honest vocabulary miss — never a guess.
-      const classHits = (graph.individuals || []).filter((i) => i.class === "Class" && String(i.label).toLowerCase() === termLc);
-      if (classHits.length === 1) {
-        const hit = classHits[0];
-        const mid = moduleIdOf(graph, hit);
-        const modLabel = (mid && graph.byId.get(mid)?.label)
-          || String((hit.attributes || []).find((a) => a.key === "site")?.value || "").split(":")[0]
-          || null;
+      // META FALLBACK TO REAL ENTITIES (0.8.2 WS1; widened + extracted to
+      // metaFallbackEntityAnswer, HANDOVER.md 2026-07-10 item 6) — see that
+      // function's own docblock for the full "what is a Record"/"what does
+      // fnAlpha mean" history. A unique hit renders straight from its own text
+      // (render()'s metaCodeClass branch just passes it through).
+      const fallback = metaFallbackEntityAnswer(graph, term);
+      if (fallback) {
         return {
-          matches: [hit], objMatch: hit, candidates: [], ambiguous: false,
-          metaCodeClass: true, metaModuleLabel: modLabel,
-          traversal: `schema lookup for "${term}" (miss), then unique Class individual by label`,
+          matches: [fallback.hit], objMatch: fallback.hit, candidates: [], ambiguous: false,
+          metaCodeClass: true, metaFallbackText: fallback.text,
+          traversal: `schema lookup for "${term}" (miss), then unique code-entity individual by label`,
         };
       }
       return { matches: [], objMatch: null, candidates: [], traversal: `schema lookup for "${term}"`, ambiguous: false };
@@ -2862,6 +3062,30 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
     };
   }
 
+  // who-last (HANDOVER.md 2026-07-10 item 5): "who last touched X" — the SAME
+  // newest-commit-first resolution as "when" just above (single most-recent
+  // toucher, not the full touch history), rendered as the commit's AUTHOR
+  // instead of its date. A dedicated shape rather than reusing "when" outright:
+  // render() needs to know to answer with "who", not "when", off the same
+  // sorted commit list.
+  if (shape === "whoLast") {
+    const dateOf = (c) => String((c.attributes || []).find((a) => a.key === "date")?.value || "");
+    const edges = ["touches", "touchesSymbol"].flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.object === objMatch.id);
+    const seen = new Set();
+    const commits = [];
+    for (const e of edges) {
+      if (seen.has(e.subject)) continue;
+      seen.add(e.subject);
+      const c = graph.byId.get(e.subject);
+      if (c && c.class === "Commit") commits.push(c);
+    }
+    commits.sort((a, b) => dateOf(b).localeCompare(dateOf(a)));
+    return {
+      matches: commits, objMatch, candidates, ambiguous, matchedVia, whoLastShape: true,
+      traversal: `touches+touchesSymbol edges where object = ${objMatch.label}, newest commit's author`,
+    };
+  }
+
   // commit-as-subject flip: touches edges are stored commit -> entity, so when the
   // RESOLVED term of a touches question is itself a Commit — "which changes touch
   // commit ef74e44e25c8" (reverse), "what did commit abc1234 touch" (forward),
@@ -3171,16 +3395,14 @@ function renderCore(parsed, result) {
         miss: true, ambiguous: false,
       };
     }
-    // meta fallback hit (0.8.2 WS1, see traverse's meta branch): the term is not
-    // schema vocabulary but IS a unique code-graph Class — a describe-style
-    // one-liner pointing at the real entity, instead of the false vocabulary miss.
+    // meta fallback hit (0.8.2 WS1, widened + extracted to metaFallbackEntityAnswer,
+    // HANDOVER.md 2026-07-10 item 6, see traverse's meta branch): the term is not
+    // schema vocabulary but IS a unique code-graph entity (Class/Function/Method/
+    // GlobalVariable/Attribute) — its pre-rendered describe-style one-liner is
+    // passed straight through, so this stays byte-identical to whatever chat.mjs's
+    // bare "what is X" last-resort lane produces by calling the SAME function.
     if (result.metaCodeClass) {
-      const label = result.objMatch.label;
-      const definedIn = result.metaModuleLabel ? `, defined in ${result.metaModuleLabel}` : "";
-      return {
-        content: `${label} is a class in this codebase${definedIn} — try "describe ${label}" or "which classes inherit from ${label}".`,
-        miss: false, ambiguous: false, matches: result.matches,
-      };
+      return { content: result.metaFallbackText, miss: false, ambiguous: false, matches: result.matches };
     }
     const doc = (result.objMatch.attributes || []).find((a) => a.key === "doc")?.value || "";
     const kindWord = result.objMatch.class === "SchemaClass" ? "a class in the graph's schema" : "a predicate (relation) in the graph's schema";
@@ -3285,6 +3507,30 @@ function renderCore(parsed, result) {
       miss: false, ambiguous: false, matches: result.matches,
     };
   }
+  // who-last: newest touching commit's AUTHOR (HANDOVER.md 2026-07-10 item 5) — the
+  // superlative "who" mirror of whenShape just above. "who last touched X" used to
+  // fall into the ordinary reverse-list render below and name EVERY toucher; this
+  // answers with the single most recent one instead. Unlike whenShape, no date is
+  // needed to answer "who" — an undated-but-authored commit still resolves.
+  if (result.whoLastShape) {
+    const subject = result.objMatch.label;
+    if (!result.matches.length) {
+      return { content: `no recorded commit touches ${subject} in this index.`, miss: true, ambiguous: false };
+    }
+    const newest = result.matches[0];
+    const author = (newest.attributes || []).find((a) => a.key === "author")?.value;
+    if (!author) {
+      return {
+        content: `commit ${newest.label} last touched ${subject}, but this index records no commit author — regenerate the graph to attach mgx:commitAuthor.`,
+        miss: true, ambiguous: false,
+      };
+    }
+    const more = result.matches.length - 1;
+    return {
+      content: `${subject} was last touched by ${author} (commit ${newest.label})${more ? `; ${more} earlier commit${more === 1 ? "" : "s"} recorded` : ""}.`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
   // commit-as-subject answers ("which changes touch commit X", "what did commit X
   // touch"): cite the commit, group the touched entities by CLASS — modules and
   // symbols are different grains of the same answer, and flattening them into one