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

package/ROADMAP.md

@@ -12,36 +12,65 @@ mapped into them (item numbers retained for traceability); the seven sketches
 formerly held in `code-talker-ideas.txt` are folded into items 8–11 below and
 the file has been deleted.
 
-## Where we are now (2026-07-06)
-
-**Built: v0.8.0 — Phase 11 landed (Phases 0–10 shipped in 0.7.1).** All five Phase-11 tracks are
-built, merged, and measured; `npm test` green (**869**). Push/publish held for the operator. Highlights:
-
-- **Track 1 — chat levers (measured).** Pronoun/focus binding, discourse-count anaphora, and C1
-  temporal-over-relative composition all landed. `CHATBENCH_0.8.0`: tier-1 spine **331→333**, all three
-  lever families moved their cells (the B1-temporal control did not spill); judged fixed tag
-  `multi-turn-focus` **1.433→1.9** (the pronoun lever's echo). The judged pooled mean (1.44) is **not
-  case-comparable** to 0.7.1's 1.488 — the graded draw re-samples 10% of cells each run, so §1 compares
-  cell-level, not the scalar; the deterministic tier-1 spine is the load-bearing PASS.
-- **Track 2 — the router (designed → DEMONSTRATED).** The Anthropic-compatible `/v1/messages` shim
-  (`serve` mode), the Stage-0 capability registry (STRIPS/PDDL operators, closed-world default-deny),
-  and the resolver (S1) + guardrail (S4) + planner (S3, pure-JS POP/HTN + Steel & Ho monitor). Measured:
-  `AGENTBENCH_0.8.0` (shim-transport floor, 46% completion) → `AGENTBENCH_0.8.0_001` (the real router):
-  **96% completion at 0% hallucination on every rung**, clearing the closed-world ladder to **C1**. The
-  honest gate the phase was staked on is **met on its hallucination axis (0%)**. **Caveat (stated in the
-  artifact):** AGENTBENCH grades the correct **call-plan + proof**, *not* the executed composed result,
-  and B1/B2/C1 are thin rungs (2–3 cases); the C2 case is honestly **refused** (Stage 5, unbuilt).
-- **Track 3 — bedrock-meter surface.** `../bedrock-meter` gained a cost-ascending router ladder with the
-  **tmct `$0` rung at rank 0 below nova-micro**; an end-to-end test meters an in-envelope request at
-  **£0** and escalates out-of-envelope to nova-micro (that repo: 73 green, unpushed).
-- **Track 4 — playtest.** Three frozen dialogue-flow transcripts (`test/chatflow-{coverage,history,
-  architecture}.test.mjs`) from routing dead-ends off the grammar wall.
-- **Track 5 — research.** `docs/references/planning/` gained Stage-2 intent-frames + Stage-5
-  goal-reasoner design notes + a BDI/Goal-Driven-Autonomy reference entry.
-
-**Next:** the C2 goal-reasoner (Stage 5) and Stage-2 imperative intent frames are the designed-but-
-unbuilt edge; the tier-4/tier-5 items in Phase LATER remain the long tail. See Phase 11 below and
-`HANDOVER.md` for the open follow-ups.
+## Where we are now (2026-07-07)
+
+**Built: v0.8.2 — the chat-feel wave + rule-general C2 (0.8.1 published; 0.8.2 gated green, push =
+the next operator action).** `npm test` green (**974**). 0.8.2 deepened both axes at once:
+
+- **Chat feel (CHATBENCH_0.8.2, deterministic tier):** tier-1 **334/334 (draw A) + 285/285 (draw
+  B)**, zero regressions; the cycle-1 standing hard-fail `gq-functions-call-fnalpha` **flipped
+  green**. Landed (PLAN_CHAT_FEEL items 1–5, 7, 8): recall hygiene, preamble/politeness frames,
+  calls∪callsSymbol + grain/meta fallbacks, the author lane, wall kindness + honest capability
+  nudges, teach-lane widening + the taught-class↔inherits bridge, receipt tails prose→detail.
+  Plus a live-found scale hotfix (edgesOfKind argument-spread overflow past ~100k edges, from a
+  27,770-module monorepo). **The judged (LLM) re-judge of the touched tags is DEFERRED
+  post-release (ship-over-delay)** — 0.8.1 judged scores stay the judged record and are stale on
+  those tags; see CHATBENCH_0.8.2.
+- **Agent (AGENTBENCH_0.8.2):** ladder 43→56 cases; goal driver **100% plan / 98% result / 0%
+  hallucination, all rungs gate-PASS** (one deliberate honest red: `ab-c2-what-to-test`); resolver
+  floor clean **A0–C1 100/100** via the new member-filter HTN method + per-member hop (flips
+  `ab-c1-widget-methods-calling` in both drivers). **C2 is now rule-general**: a second declared
+  goal-rule (`cochange-risk-invariant`) + pure `applicableRules` selection (0→refuse open-world,
+  >1→refuse ambiguous; grep-clean of request keywords). Bench-import inversion
+  (`src/router/call-validator.mjs` + `set-algebra.mjs`); bounded runner pool (`--concurrency` 8).
+
+**Shipped in v0.8.1 (published):** the same demonstrated-vs-designed honesty discipline, summarized:
+
+- **AGENTBENCH now grades the executed composed RESULT, not just the call-plan** (retires the headline
+  0.8.0 caveat). Under result-grading the resolver is **97% plan / 91% result / 0% hallucination**; the
+  honest gap lands exactly where reasoning is hard (C1, C2).
+- **Stage 5 — the C2 goal-reasoner** (BDI + Goal-Driven Autonomy) genuinely lifts result-completion.
+  The honest, **like-for-like** figure is the *driver swap on the identical 39-case ladder*
+  (`AGENTBENCH_0.8.1_001`): resolver **85% → goal-reasoner 95% result** (+10pp, purely the driver, 0%
+  hallucination). C2 is **cleared for one declared coverage-invariant goal-rule** — real and
+  phrasing-robust (validated by held-out phrasings graded blind, no request-string literals), but
+  **thinly sampled, not rule-general**; the open-world case is honestly **refused**. *(NB: the
+  cross-release "0→83% C2" reads on a grown 6-case C2 ladder whose 4 new cases exercise the
+  goal-reasoner — not a like-for-like rate; the same-basket win is one case fixed, 0→50% original C2.)*
+- **Stage 2 — imperative intent frames + ACE reach** (`AGENTBENCH_0.8.1_002`, goal driver): **100% plan
+  / 95% result / 0% hallucination**. `tmct_calls` is now **genuinely NL-reachable** via a distinct
+  edge-dump frame (not by un-tagging — bidirectional conformance enforces it; `NOT_NL_REACHABLE` is now
+  `{}`). ACE is wired **async** into the interpret pipeline so the synchronous CHATBENCH parse spine is
+  **byte-identical** — ACE is inert in the shipped product path (`interpret()` is called nowhere in
+  chat/ask/server/bin), reach without regression.
+- **Chat surface (CHATBENCH_0.8.1):** quick wins (singular "what is a test", friendly commit-author
+  refs, "No tests cover X" honest-empty, the chatbench discourse-count flake root-caused + scrubbed) +
+  two playtests (coverage-survey + authorship routing; **6 frozen `chatflow-*` transcripts** total).
+  Joint deterministic CHATBENCH (both new frame tables together): **no tier-1 regression vs 0.7.1.**
+  Judged tags touched by the text changes were re-judged (not blanket-reused) — see `CHATBENCH_0.8.1`.
+
+**Shipped earlier in v0.8.0 (published):** all five Phase-11 tracks — the `/v1/messages` shim + Stage-0
+registry + resolver/guardrail/planner (`AGENTBENCH_0.8.0_001`: 96% *plan* completion, 0% hallucination,
+closed-world C1); the three chat levers (`CHATBENCH_0.8.0`: tier-1 331→333); the `../bedrock-meter` `$0`
+rung (rank 0 below nova-micro, £0 metered e2e); the playtest; and the Stage-2/Stage-5 research notes.
+
+**Next (post-release, in order):** (1) the judged re-judge of the stale tags (the deferred half of
+the 0.8.2 evidence); (2) the chat-feel fast-follows from the confirmation playtest (recall
+conjunction enforcement, the fuzzy-entity FALSE-EMPTY confident-wrong class, function-grain
+coverage, module-grain overview); (3) the Track-1 trio against the measured red set (pron ×18,
+temporal b1×5 + c1×9, disc-count re-measure first); (4) `edgesOfKind` memoization + endpoint
+indices (perf at monorepo scale); (5) the seonix cutover ping + wh-scale feedback loop. Full list
+with targets in `HANDOVER.md`.
 
 ## The umbrella product definition (item 1)
 
@@ -628,7 +657,7 @@ you toward precision" promise on the conversational surface.
   with new graded cells for the miss / empty-graph / concept-touch surfaces so these become
   regression-protected levers, not one-off polish.
 
-## Phase 11 — The capability router & the agentic bench (0.8.0 — LANDED)
+## Phase 11 — The capability router & the agentic bench (0.8.0 shipped · 0.8.1 deepened · 0.8.2 feel + rule-general C2)
 
 *(Operator-directed 2026-07-06; built the same day across five concurrent tracks.)* tmct as a **deterministic, no-LLM
 tool router** behind an Anthropic-compatible API — the workstream specified in
@@ -650,6 +679,14 @@ real deliverable. The five tracks below are all built; the two research-agent st
 remain designed-not-built by intent.
 
 ### Track 1 — chat-surface levers (next CHATBENCH; all three)
+
+> **STATUS (0.8.2):** the surrounding feel surface landed — PLAN_CHAT_FEEL items **1–5, 7, 8**
+> (recall hygiene, preamble frames, call-relation self-consistency, author lane, wall kindness,
+> teach-lane widening, honest nudges) shipped and gate-verified deterministically. **The trio
+> below is DEFERRED post-release with measured targets** (advisor tick-4): pronoun red set = 18
+> g-b1-pron ids; temporal = g-b1-temp ×5 + g-c1-temp ×9; discourse-count re-measure first — it
+> sampled 0/5 red and is likely already green. See HANDOVER follow-up #3.
+
 The three levers `CHATBENCH_0.7.1` measured + ranked — which **double as router prerequisites** (they
 gate the A2→B1→C1 rungs, per Phase B of the router plan):
 1. **Pronoun / focus binding** — the "it → Commit" mis-bind (`B1 pron 1.24`); biggest movable mass.
@@ -659,6 +696,12 @@ gate the A2→B1→C1 rungs, per Phase B of the router plan):
 Land all three (not just #1); they raise the chat floor *and* the router's floor at once.
 
 ### Track 2 — the router build (the within-horizon slice, in order)
+
+> **STATUS (0.8.2):** the C1 composition gap closed — the **member-filter HTN method + per-member
+> callees hop** flips the standing C1 red in both drivers (resolver floor A0–C1 all 100/100); the
+> ladder grew 43→56 fixture-linted cases; the bench-import smell is inverted
+> (`src/router/call-validator.mjs` + `set-algebra.mjs`).
+
 Buildable now with a frontier model as co-author (see PLAN §"solved vs unsolved"):
 - **Phase A — the shim.** An Anthropic Messages API endpoint (`/v1/messages`, `tool_use`/`tool_result`
   blocks). **Extended:** also present as a **`bedrock-meter`-compatible routing target** (see below).
@@ -697,6 +740,12 @@ critical build path:
 - **Stage 5 — goal-reasoner, closed-world C2** — BDI + Goal-Driven Autonomy: deduce-goals (long-chain
   deduction) → plan-each (C1) → threat-aware, *persistent* first-step arbitration.
 
+> **STATUS (0.8.2):** both research stages are now BUILT and measured. Stage 2 landed in 0.8.1_002;
+> Stage 5's 0.8.1 "one thin rule" caveat is retired — **C2 is rule-general**: two declared
+> goal-rules (`coverage-invariant`, `cochange-risk-invariant`) selected by pure `applicableRules`
+> deduction with honest refusals at both failure modes (0 applicable = open-world, >1 = ambiguous),
+> zero request keywords. Goal driver: 100% plan / 98% result / 0% hallucination over 56 cases.
+
 ## Phase LATER — recognized, deferred, not now
 
 Features we have deliberately shaped seams for but will not build until the phases above have

package/data/templates/responses.jsonl

@@ -60,7 +60,7 @@
 {"id":"conversational-greeting-good-evening","class":"conversational","register":"friendly","template":"Good evening. Ask me about this codebase, or /help."}
 {"id":"conversational-thanks","class":"conversational","register":"friendly","template":"Any time. Ask another, or /help for what I can do."}
 {"id":"conversational-farewell","class":"conversational","register":"friendly","template":"Bye — flushing the session log. Come back with a question any time."}
-{"id":"orientation-friendly","class":"orientation","register":"friendly","template":"I answer questions about THIS codebase's structure — imports, calls, definitions,\nhistory and counts. For example:\n  which modules import walk.mjs\n  what calls buildContextBundle\n  how many classes are there\n/help for commands, /stats for an overview of the graph."}
+{"id":"orientation-friendly","class":"orientation","register":"friendly","template":"I answer questions about THIS codebase's structure — imports, calls, definitions,\nhistory and counts. For example:\n  which modules import {example1}\n  what calls {example2}\n  how many classes are there\n/help for commands, /stats for an overview of the graph."}
 {"id":"miss-no-previous-answer","class":"miss","register":"friendly","template":"No previous answer to expand yet — ask me a question first, then say \"why\" or \"say more\"."}
 {"id":"conversational-greeting-empty","class":"conversational","register":"friendly","template":"Hi. There's no code graph loaded here — for code structure (imports, calls, definitions) I need a `.tmct/graph.json`: point me at one with `--repo <path>`, or try the shipped example `npm run example:mini`. (tmct reads graphs; it doesn't index code itself.) For general vocabulary, `tmct init` seeds concepts — try \"what is a cache\". /help for commands."}
 {"id":"orientation-empty","class":"orientation","register":"friendly","template":"There's no code graph loaded here, so I can't answer structure questions (imports, calls, definitions) yet.\nFor those I need a `.tmct/graph.json` produced by a graph producer — point me at one with `--repo <path>`, or try the shipped example `npm run example:mini`. tmct reads graphs; it doesn't index code itself.\nFor general vocabulary, `tmct init` seeds concepts — try \"what is a cache\". /help for commands, /memory for what I remember."}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "0.8.0",
+  "version": "0.8.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.",

package/src/ask.mjs

@@ -77,7 +77,12 @@ import { nlpAdapter } from "./ask-nlp.mjs";
  *  classification, so they cannot drift in meaning). */
 function edgesOfKind(graph, kind) {
   const out = [];
-  for (const g of graph.relations) if (relationKind(g) === kind) out.push(...g.edges);
+  // Plain-loop append, NOT out.push(...g.edges): argument spread overflows the call
+  // stack past ~100k edges on graph-scale relation groups (see codegraph.mjs twin).
+  for (const g of graph.relations) {
+    if (relationKind(g) !== kind) continue;
+    for (const e of g.edges) out.push(e);
+  }
   return out;
 }
 
@@ -89,6 +94,12 @@ function edgesOfKind(graph, kind) {
 // "which functions call X" should read off callsSymbol (fn->fn), not the module-coarse "calls".
 const SYMBOL_GRAIN_SIBLING = { calls: "callsSymbol", touches: "touchesSymbol" };
 const FINE_ENTITY_TYPES = new Set(["Function", "Method", "Class", "Attribute", "GlobalVariable"]);
+// The fn/method FAMILY (0.8.2 WS1): callers of a symbol are recorded at whichever
+// grain the extractor saw (a method Widget.render is class "Method"), but a person
+// asking "which functions call X" means the callable family, not the storage class.
+// Used ONLY as an empty-result fallback (see traverse's reverse symbol-grain path):
+// an exact-class answer is never widened, so every non-empty answer is byte-stable.
+const FINE_CLASS_SIBLING = { Function: "Method", Method: "Function" };
 
 // Query-side UNION families (2026-07-02 query families): a parsed kind that is not
 // itself a stored predicate but a curated union of stored kinds — "what uses X"
@@ -125,6 +136,24 @@ function verbFor(kind) {
   return REVERSE_MISS_VERB[kind] || kind;
 }
 
+// Leading-relation-verb strip for the tests-kind honest empty (0.8.2 WS1): the
+// keyword strategy can match the "tests" NOUN as the relation verb and leave the
+// user's OWN verb at the head of the object term ("do any tests touch f.mjs" →
+// object "touch f.mjs"), which the old ^cover-only strip missed ("No tests cover
+// touch app/lib/f.mjs."). The closed list is read from ask-vocab.mjs's exported
+// VERB_TO_KIND (derived from the RELATIONS verb table — the source of truth,
+// including the `tests` kind's own verbs: cover/check/verify/exercise/…), longest
+// phrase first so multi-word verbs strip whole; a bare optional s/ing/ed tail keeps
+// the previously-stripped inflections ("covering") without enumerating them. Only
+// ever applied to the tests-kind zero-hit template's object — never to resolution.
+const LEADING_RELATION_VERB_RE = new RegExp(
+  `^(?:${Object.keys(VERB_TO_KIND)
+    .sort((a, b) => b.length - a.length)
+    .map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|")})(?:s|ing|ed)?\\s+`,
+  "i",
+);
+
 // ---- the parsing strategies + normalization + fuzzy service formerly defined
 // here now live in src/interpret/ (items 8/10/13): interpret/normalize.mjs
 // (normalizeQuery, applyNegationFrames, STOPWORDS, splitWords), interpret/
@@ -1416,7 +1445,29 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
       const token = (i.attributes || []).find((a) => a.key === "token")?.value;
       return token && String(token).toLowerCase() === termLc;
     });
-    if (!match) return { matches: [], objMatch: null, candidates: [], traversal: `schema lookup for "${term}"`, ambiguous: false };
+    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;
+        return {
+          matches: [hit], objMatch: hit, candidates: [], ambiguous: false,
+          metaCodeClass: true, metaModuleLabel: modLabel,
+          traversal: `schema lookup for "${term}" (miss), then unique Class individual by label`,
+        };
+      }
+      return { matches: [], objMatch: null, candidates: [], traversal: `schema lookup for "${term}"`, ambiguous: false };
+    }
     return {
       matches: [match], objMatch: match, candidates: [],
       traversal: `schema lookup for "${term}"`, ambiguous: false,
@@ -1536,9 +1587,22 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
   }
 
   if (shape === "forward") {
-    const edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.subject === objMatch.id);
-    const matches = edges.map((e) => graph.byId.get(e.object)).filter(Boolean);
-    return { matches, objMatch, candidates, traversal: `${kindsFor(kind).join("+")} edges where subject = ${objMatch.label}`, ambiguous, matchedVia };
+    // FORWARD CALL UNION (0.8.2 WS1): a kind with a symbol-grain sibling scans the
+    // UNION coarse+sibling when the resolved SUBJECT is itself a fine symbol —
+    // "what does Widget.render call" lives on callsSymbol (fn->fn), which the
+    // module-coarse scan alone can never reach (a coarse edge's subject is a
+    // module, so a Function/Method subject rendered a false "no calls edges" while
+    // the reverse direction answered). Module subjects never carry a sibling edge,
+    // so their scan — and the traversal receipt — stays byte-identical. The receipt
+    // names what was actually scanned ("calls+callsSymbol edges where subject = X").
+    const fwdSibling = SYMBOL_GRAIN_SIBLING[kind];
+    const subjIsFineSymbol = !!(fwdSibling && objMatch.class && FINE_ENTITY_TYPES.has(objMatch.class));
+    const fwdKinds = subjIsFineSymbol ? [...new Set([...kindsFor(kind), fwdSibling])] : kindsFor(kind);
+    const edges = fwdKinds.flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.subject === objMatch.id);
+    const targets = edges.map((e) => graph.byId.get(e.object)).filter(Boolean);
+    // dedupe only on the widened scan — the coarse-only path keeps its exact shape.
+    const matches = subjIsFineSymbol ? uniqueById(targets) : targets;
+    return { matches, objMatch, candidates, traversal: `${fwdKinds.join("+")} edges where subject = ${objMatch.label}`, ambiguous, matchedVia };
   }
 
   // reverse + transitive (PLAN_MECHANICAL_CHAT.md P1): the gate above guarantees kind is
@@ -1577,8 +1641,23 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
   if (symbolKind && (FINE_ENTITY_TYPES.has(entityType) || objIsFineSymbol)) {
     const edges = edgesOfKind(graph, symbolKind).filter((e) => e.object === objMatch.id);
     const subjects = uniqueById(edges.map((e) => graph.byId.get(e.subject)).filter(Boolean));
-    const matches = (!entityType || entityType === "Change") ? subjects : subjects.filter((i) => i.class === entityType);
-    return { matches, objMatch, candidates, traversal: `${symbolKind} edges where object = ${objMatch.label}`, ambiguous, matchedVia };
+    let matches = (!entityType || entityType === "Change") ? subjects : subjects.filter((i) => i.class === entityType);
+    let widenNote = "";
+    // FINE-GRAIN FAMILY FALLBACK (0.8.2 WS1): when the exact-class filter comes back
+    // EMPTY and the asked grain is Function/Method, retry with the family sibling —
+    // "which functions call fnAlpha" must not hide the recorded caller Widget.render
+    // just because the extractor stored it as class Method. Fallback-only by
+    // construction (the exact filter must be empty first), so every currently
+    // non-empty answer is byte-identical; the widening is said in the traversal.
+    const siblingClass = FINE_CLASS_SIBLING[entityType];
+    if (!matches.length && siblingClass) {
+      const widened = subjects.filter((i) => i.class === siblingClass);
+      if (widened.length) {
+        matches = widened;
+        widenNote = `, widened to ${siblingClass} subjects (no ${entityType} recorded)`;
+      }
+    }
+    return { matches, objMatch, candidates, traversal: `${symbolKind} edges where object = ${objMatch.label}${widenNote}`, ambiguous, matchedVia };
   }
 
   // General case: some predicates are already fine-grained (inherits: Class->Class, contains:
@@ -1646,6 +1725,17 @@ function symbolLabelOf(ind) {
   return ["Function", "Method"].includes(ind.class) ? `function ${label}()` : label;
 }
 
+/** A FRIENDLY commit reference for a "who touched X" list — the raw sha alone reads as
+ *  noise, so when the Commit individual carries an author (mgx:commitAuthor → key
+ *  "author") name them beside it. The label is already the graph's short ref (the
+ *  builder stores sha.slice(0,12)), so it is used verbatim. Degrades gracefully: a
+ *  commit with no recorded author renders the sha alone, exactly as before. */
+function commitRefOf(ind) {
+  const sha = String(ind.label || ind.id || "");
+  const author = (ind.attributes || []).find((a) => a.key === "author")?.value;
+  return author ? `${sha} (${author})` : sha;
+}
+
 function listJoin(syms) {
   return syms.length > 1 ? `${syms.slice(0, -1).join(", ")} and ${syms[syms.length - 1]}` : syms[0];
 }
@@ -1703,6 +1793,17 @@ 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.
+    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,
+      };
+    }
     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";
     return { content: `${result.objMatch.label} is ${kindWord}: ${doc}`, miss: false, ambiguous: false, matches: result.matches };
@@ -1713,7 +1814,7 @@ function renderCore(parsed, result) {
   if (result.mentionsShape) {
     if (!result.matches.length) {
       return {
-        content: `"${parsed.object}" is not mentioned in any indexed identifier or doc-comment prose. (traversal: ${result.traversal})`,
+        content: `"${parsed.object}" is not mentioned in any indexed identifier or doc-comment prose.`,
         miss: true, ambiguous: false,
       };
     }
@@ -1770,7 +1871,7 @@ function renderCore(parsed, result) {
   if (result.whenShape) {
     const subject = result.objMatch.label;
     if (!result.matches.length) {
-      return { content: `no recorded commit touches ${subject} in this index. (traversal: ${result.traversal})`, miss: true, ambiguous: false };
+      return { content: `no recorded commit touches ${subject} in this index.`, miss: true, ambiguous: false };
     }
     const newest = result.matches[0];
     const date = (newest.attributes || []).find((a) => a.key === "date")?.value || "";
@@ -1800,7 +1901,7 @@ function renderCore(parsed, result) {
     const cite = `commit ${result.objMatch.label}`;
     if (!result.matches.length) {
       return {
-        content: `${cite} touched nothing recorded in the index. (traversal: ${result.traversal})`,
+        content: `${cite} touched nothing recorded in the index.`,
         miss: true, ambiguous: false,
       };
     }
@@ -1818,8 +1919,11 @@ function renderCore(parsed, result) {
     if (!result.objMatch || !result.subjMatch) {
       return { content: `couldn't resolve one of the terms in this question.`, miss: true, ambiguous: false };
     }
+    // the yes render is plain words — the traversal string IS "<kind> edge from
+    // <A> to <B>", so it reads as the sentence itself, not a parenthetical receipt
+    // (the receipt still rides on the result's traversal field for why/verbose).
     return {
-      content: result.answer ? `Yes. (${result.traversal})` : `No — no ${parsed.kind} edge found from ${result.subjMatch.label} to ${result.objMatch.label}.`,
+      content: result.answer ? `Yes — ${result.traversal}.` : `No — no ${parsed.kind} edge found from ${result.subjMatch.label} to ${result.objMatch.label}.`,
       miss: !result.answer, ambiguous: false,
     };
   }
@@ -1830,7 +1934,24 @@ function renderCore(parsed, result) {
     // subject-first phrasing rather than reusing reverse's "found ... that OBJECT" template.
     if (parsed.shape === "forward") {
       return {
-        content: `${result.objMatch.label} has no ${parsed.kind} edges in the index. (traversal: ${result.traversal || "no traversal resolved"})`,
+        content: `${result.objMatch.label} has no ${parsed.kind} edges in the index.`,
+        miss: true, ambiguous: false,
+      };
+    }
+    // "what tests cover X" / "what tests X" — the tests themselves are the search
+    // target (no explicit entity keyword → entityType null), and "tests" reads as a
+    // verb phrase, so the generic "No <modules> found whose module directly tests <obj>"
+    // template garbles: it mislabels the searched kind as "modules" and lets the user's
+    // leaked verb ride into the object ("…tests cover touch X"). Any leading relation
+    // verb (cover/touch/check/verify/… — LEADING_RELATION_VERB_RE, built from the
+    // ask-vocab verb table) is stripped, so the honest empty reads as the natural
+    // "No tests cover X." The frozen entity-keyword form ("which modules test X",
+    // entityType="Module") keeps its pinned wording below.
+    if (parsed.kind === "tests" && !parsed.entityType) {
+      const stripped = String(parsed.object || "").replace(LEADING_RELATION_VERB_RE, "").trim();
+      const obj = stripped || String(parsed.object || "").trim();
+      return {
+        content: `No tests cover ${obj}.`,
         miss: true, ambiguous: false,
       };
     }
@@ -1840,7 +1961,7 @@ function renderCore(parsed, result) {
     // append-only/sacred mid-arc, so the honest-miss phrasing stays as-is.
     const entityWord = nounFor(parsed.entityType || "Module", 2);
     return {
-      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}. (traversal: ${result.traversal || "no traversal resolved"})`,
+      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}.`,
       miss: true, ambiguous: false,
     };
   }
@@ -1853,7 +1974,10 @@ function renderCore(parsed, result) {
   // Commit list ("which commits touched X") has no containing module to group by, so
   // anything that is not a fine entity takes the flat join.
   if (parsed.shape === "forward" || parsed.entityType === "Module" || result.matches.every((m) => !FINE_ENTITY_TYPES.has(m.class))) {
-    const shown = result.matches.slice(0, OVERFLOW_CAP).map((m) => m.label);
+    // A reverse "who touched X" resolves to Commit individuals — render friendly refs
+    // (short sha + author) instead of the raw stored sha; every other flat list (module
+    // labels, etc.) keeps its own label verbatim.
+    const shown = result.matches.slice(0, OVERFLOW_CAP).map((m) => m.class === "Commit" ? commitRefOf(m) : m.label);
     const extra = result.matches.length > OVERFLOW_CAP ? `, …and ${result.matches.length - OVERFLOW_CAP} more` : "";
     return { content: shown.join(" and ") + extra + ".", miss: false, ambiguous: false, matches: result.matches };
   }