@polycode-projects/the-mechanical-code-talker 3.0.6 → 3.0.8

package/README.md

@@ -17,6 +17,30 @@ Teach it a fact in plain English and it mints a node. Ask it a question and
 it answers from what it was seeded with, what you taught it, and what it can
 derive by rule from both. Every answer is either grounded or an honest miss.
 
+## Repository layout
+
+| directory | contains |
+|---|---|
+| `bin/` | the CLI entrypoint (`tmct.mjs`) |
+| `src/` | the shipped product: `domain/` (pure logic), `adapters/` (I/O, storage, providers), `services/` (chat, adventure, research, ledger, plan), `surfaces/` (CLI, HTTP, TUI, web), `index/` (repo indexing) |
+| `corpus/` | committed corpus and template data (ConceptNet, WordNet, NameNet, the generated persona vocab) |
+| `data/` | seed data assets: sprites, phrasebook, games, response templates |
+| `ontology/` | the software ontology (`tmct-core.ttl`) and memory shapes, in Turtle |
+| `scripts/` | build, check, and maintenance scripts (`npm run` targets live here) |
+| `examples/` | runnable example scripts and fixture repos used by the README's own examples and the test suite |
+| `demo/` | standalone demo scripts (e.g. the agentic-loop demo) |
+| `electron/` | the Electron desktop app wrapper |
+| `docs/` | reference docs: the adapter/repository-interface contracts, bibliography |
+| `test/` | the unit, corpus, and estate-guard test suite (`npm test`) |
+| `test-e2e/` | the end-to-end suite: real CLI/TUI spawns and Playwright browser journeys (`npm run test:e2e`) |
+| `test-benchmarks/` | the benchmark harnesses (agentbench, chatbench, idxbench, infbench, ingestbench, researchbench, synthbench) and their shared `benchlib/` |
+| `reports/` | benchmark write-ups (`BENCHMARK_*.md`) and `PAGE_WEIGHTS.md` — see the root `STATUS.md` for the one-page summary these feed |
+| `playtests/` | numbered playtest session logs, one edge found and fixed per entry |
+| `archive/` | delivered `PLAN_*.md`/`BENCHMARK_*.md` docs, kept for history |
+| `public/` | the built demo site — a gitignored output of `npm run demo:build`, never hand-edited |
+
+`node_modules/` (dependencies) and dotfiles/hidden tooling directories are omitted above.
+
 ## Teach it, then ask it to reason
 
 This is real, runnable output. No cherry-picking, no model anywhere in the
@@ -227,7 +251,7 @@ resolves to a real graph traversal or declines cleanly:
   (*because/although/while*), conditionals, and false-premise flags ("why
   does X still import Y" when it no longer does).
 
-The full catalog with measured coverage lives in the `BENCHMARK_*.md`
+The full catalog with measured coverage lives in the `reports/BENCHMARK_*.md`
 reports.
 
 **Response finishing.** Before an answer prints, it is segmented into typed
@@ -1179,9 +1203,11 @@ service. The LLM agent stays outside tmct, as the no-LLM ethos requires.
 
 ## Measuring it
 
-What the 2.7.11/2.7.12 cycle measured, on 2026-07-19. Each figure links to its
-method and carries, in the same row, the caveat that changes what it means.
-The full tables, judge scores, and transcripts are in the linked write-ups.
+**For the latest measured numbers, see `STATUS.md`** — a one-page summary of the most
+recent full sweep, citing its source reports by name. What follows here is what the 2.7.11/2.7.12
+cycle measured, on 2026-07-19, kept for its own detail. Each figure links to its method and
+carries, in the same row, the caveat that changes what it means. The full tables, judge scores,
+and transcripts are in the linked write-ups.
 
 | What it does | Result (2.7.12) | Read the number with this | Method |
 |---|---|---|---|
@@ -1208,10 +1234,10 @@ The smallest real slice of each, the same invocations the test suite's
 bench-smoke lane replays:
 
 ```bash cwd=repo
-node chatbench/run.mjs --stamp smoke --only g-a1-naming-1 --out /tmp/chatbench-smoke
-node infbench/generate-cases.mjs --out /tmp/infbench-cases.jsonl
-node infbench/run.mjs --cases /tmp/infbench-cases.jsonl --only inf-1-lookup-subClassOf-001 --stamp smoke --out /tmp/infbench-smoke
-node agentbench/run.mjs --stamp smoke --driver stub --only ab-a0-describe-widget --out /tmp/agentbench-smoke
+node test-benchmarks/chatbench/run.mjs --stamp smoke --only g-a1-naming-1 --out /tmp/chatbench-smoke
+node test-benchmarks/infbench/generate-cases.mjs --out /tmp/infbench-cases.jsonl
+node test-benchmarks/infbench/run.mjs --cases /tmp/infbench-cases.jsonl --only inf-1-lookup-subClassOf-001 --stamp smoke --out /tmp/infbench-smoke
+node test-benchmarks/agentbench/run.mjs --stamp smoke --driver stub --only ab-a0-describe-widget --out /tmp/agentbench-smoke
 ```
 
 Grading beyond tier 1 uses an LLM as judge. The offline eval harness is the
@@ -1229,7 +1255,6 @@ hardened:
 - CI runs **SAST and secret detection**.
 - A nightly **`npm audit` + OSV-Scanner** job watches dependencies.
 - Releases are published with **npm provenance** (`--provenance`).
-- A coordinated-disclosure `SECURITY.md` policy covers reports.
 
 The content-address hash is single-sourced in `src/domain/hash.mjs`, so the
 cross-version-stable fact-id contract has exactly one definition.
@@ -1291,7 +1316,7 @@ edition, the retrieval date, the terms tmct uses, and what could not be verified
 
 | source | edition | what tmct uses it for |
 |---|---|---|
-| Council of Europe, CEFR — Companion volume | 2020, ISBN 978-92-871-8621-8 | The band labels A1–C2 the chat benchmark grades against. CEFR measures what a *person* can do communicatively; grading the difficulty of *prompts* by band is tmct's adaptation, not a CEFR-validated use. The band descriptions in `chatbench/GRADED.md` are tmct's own prose. |
+| Council of Europe, CEFR — Companion volume | 2020, ISBN 978-92-871-8621-8 | The band labels A1–C2 the chat benchmark grades against. CEFR measures what a *person* can do communicatively; grading the difficulty of *prompts* by band is tmct's adaptation, not a CEFR-validated use. The band descriptions in `test-benchmarks/chatbench/GRADED.md` are tmct's own prose. |
 | Reiter, "On Closed World Data Bases" | *Logic and Data Bases*, Plenum, 1978, pp. 55–76 | Both halves of the honest miss. The planner's operator model is **closed-world**, which is what makes a plan checkable. The chat layer is **open-world**: it will not read "no matching rule" as "the answer is no". |
 | Chow, "On optimum recognition error and reject tradeoff" | *IEEE Trans. Information Theory* 16(1), 1970 | Prior art for the goal. The literature calls a refusal **abstention**, or selective prediction, and Chow's reject option is its root. Those methods threshold a confidence score; tmct has none, and abstains because nothing matched — which is why the row above names the mechanism. |
 | Ji et al., "Survey of Hallucination in Natural Language Generation" | *ACM Computing Surveys* 55(12), 2023 | Groundedness, and what tmct is avoiding by having no model to hallucinate with. |

package/bin/tmct.mjs

@@ -467,7 +467,7 @@ async function activatePluggableInput(repoRoot, resolved) {
   }
   if (resolved.manifestEntry) {
     // Preserve the ORIGINAL `--corpus <tier2-id>` wording byte-for-byte
-    // (e2e/init-cli.test.mjs asserts on this exact shape).
+    // (test-e2e/init-cli.test.mjs asserts on this exact shape).
     return `seeded tier-2 corpus "${resolved.manifestEntry.id}" (${resolved.manifestEntry.kind}) — ${seeded.appended} fact(s) added`
       + `${seeded.skipped ? `, ${seeded.skipped} already present` : ""}. Source: corpus/tier2/${resolved.manifestEntry.file} (${resolved.manifestEntry.license}). `
       + `Activated in tmct.toml — future \`tmct init\`/chat sessions seed it automatically.\n`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "3.0.6",
+  "version": "3.0.8",
   "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; indexes a repo on request (tmct index) or reads any producer's graph.",
@@ -47,7 +47,8 @@
     "./createCompletionsGraphAdapter": "./src/services/completions.mjs",
     "./ingest": "./src/services/extract-facts.mjs",
     "./repository-interface": "./src/adapters/repository-interface.mjs",
-    "./conformance": "./src/tools/conformance.mjs"
+    "./conformance": "./src/tools/conformance.mjs",
+    "./ask-browser": "./src/surfaces/web/graph-ask-browser-entry.mjs"
   },
   "files": [
     "bin/",
@@ -87,9 +88,11 @@
     "test": "node --disable-warning=ExperimentalWarning --test --test-concurrency=8 \"test/**/*.test.mjs\"",
     "test:smoke": "node --disable-warning=ExperimentalWarning --test test/smoke/*.test.mjs",
     "test:fast": "node --disable-warning=ExperimentalWarning --test --test-concurrency=8 test/smoke/*.test.mjs test/fast/*.test.mjs test/tools/ask.test.mjs test/tools/server.test.mjs test/estate/import-layers.test.mjs",
-    "test:e2e": "node --disable-warning=ExperimentalWarning --test \"e2e/*.test.mjs\"",
-    "test:e2e:heavy": "node --disable-warning=ExperimentalWarning --test \"e2e/heavy/*.test.mjs\"",
-    "check:readme": "TMCT_CHECK_README=1 node --disable-warning=ExperimentalWarning --test e2e/readme-examples.test.mjs",
+    "test:unit": "node --disable-warning=ExperimentalWarning --test --test-concurrency=8 $(node scripts/list-unit-test-files.mjs)",
+    "test:slow": "node --disable-warning=ExperimentalWarning --test test/bench/synthbench-code.test.mjs test/estate/generated-artifacts.test.mjs test/readme/readme.test.mjs test/corpus/bench-smoke.test.mjs test/corpus/inference.test.mjs",
+    "test:e2e": "node --disable-warning=ExperimentalWarning --test \"test-e2e/*.test.mjs\"",
+    "test:e2e:heavy": "node --disable-warning=ExperimentalWarning --test \"test-e2e/heavy/*.test.mjs\"",
+    "check:readme": "TMCT_CHECK_README=1 node --disable-warning=ExperimentalWarning --test test-e2e/readme-examples.test.mjs",
     "e2e:browsers": "playwright install chromium",
     "gen:screenshots": "node scripts/gen-screenshots.mjs",
     "check:links": "node scripts/check-links.mjs",
@@ -128,16 +131,16 @@
     "serve:public": "node --disable-warning=ExperimentalWarning bin/tmct.mjs serve --host 0.0.0.0 --port 8787",
     "example:mini": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral",
     "example:polyglot": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --repo examples/polyglot --ephemeral",
-    "chatbench:run": "node chatbench/run.mjs",
-    "chatbench:judge": "node chatbench/judge.mjs",
-    "chatbench:judge:cached": "node chatbench/judge.mjs --cache chatbench/verdict-cache.json",
-    "agentbench:run": "node agentbench/run.mjs",
-    "infbench": "node infbench/generate-cases.mjs && node infbench/run.mjs",
-    "idxbench:run": "node idxbench/run.mjs",
-    "researchbench:run": "node researchbench/run.mjs",
-    "synthbench:code": "node synthbench/code/run.mjs",
-    "ingestbench:run": "node ingestbench/run.mjs",
-    "ingestbench:judge": "node ingestbench/judge.mjs",
+    "chatbench:run": "node test-benchmarks/chatbench/run.mjs",
+    "chatbench:judge": "node test-benchmarks/chatbench/judge.mjs",
+    "chatbench:judge:cached": "node test-benchmarks/chatbench/judge.mjs --cache test-benchmarks/chatbench/verdict-cache.json",
+    "agentbench:run": "node test-benchmarks/agentbench/run.mjs",
+    "infbench": "node test-benchmarks/infbench/generate-cases.mjs && node test-benchmarks/infbench/run.mjs",
+    "idxbench:run": "node test-benchmarks/idxbench/run.mjs",
+    "researchbench:run": "node test-benchmarks/researchbench/run.mjs",
+    "synthbench:code": "node test-benchmarks/synthbench/code/run.mjs",
+    "ingestbench:run": "node test-benchmarks/ingestbench/run.mjs",
+    "ingestbench:judge": "node test-benchmarks/ingestbench/judge.mjs",
     "corpus:matrix": "node scripts/corpus-matrix.mjs",
     "corpus:matrix:gaps": "node scripts/corpus-matrix.mjs --gaps",
     "template:coverage": "node scripts/template-coverage.mjs",

package/src/domain/answer-variants.json

@@ -10,7 +10,7 @@
         "ask.mjs metaFallbackEntityAnswer (\"X is a Y in this codebase, defined in Z ...\")"
       ],
       "deliberatelyNotUsedBy": [
-        "ask.mjs renderCore whereShape (\"X is defined in Y at line(s) Z\" / \"X is defined in Y (no line span...)\") -- chatbench/graded-pool-max.jsonl pins this exact substring as ground truth for 11 'where is X defined' cases (2 in the always-run promoted subset), and that pool is append-only/never-edited-mid-arc per SKILL_BENCHMARK_CEFR_ENGLISH.md."
+        "ask.mjs renderCore whereShape (\"X is defined in Y at line(s) Z\" / \"X is defined in Y (no line span...)\") -- test-benchmarks/chatbench/graded-pool-max.jsonl pins this exact substring as ground truth for 11 'where is X defined' cases (2 in the always-run promoted subset), and that pool is append-only/never-edited-mid-arc per SKILL_BENCHMARK_CEFR_ENGLISH.md."
       ]
     },
     "is-dated": {

package/src/domain/ask-vocab.mjs

@@ -287,6 +287,10 @@ export const ENTITY_TO_TYPE = Object.freeze({
   method: "Method", methods: "Method",
   class: "Class", classes: "Class",
   module: "Module", modules: "Module", mod: "Module", mods: "Module", file: "Module", files: "Module",
+  // "Package" is a pseudo-type like "Change" below: no node is ever stored
+  // with that class. ask.mjs derives packages from module labels, the same
+  // derivation the architecture map uses.
+  package: "Package", packages: "Package",
   attribute: "Attribute", attributes: "Attribute", field: "Attribute", fields: "Attribute",
   variable: "GlobalVariable", variables: "GlobalVariable", global: "GlobalVariable", globals: "GlobalVariable",
   // "Change" is a pseudo-type, not a node class: ask.mjs's traverse() reads it

package/src/domain/ask.mjs

@@ -15,7 +15,7 @@
 // ask.mjs's own `touches`/`cochange` verbs answer one-hop structural edges
 // (mgx:touchedByCommit / mgx:changeCoupledWith).
 
-import { relationKind, impactClosure, moduleCountOf, normPath, HISTORY_CAP } from "./codegraph.mjs";
+import { relationKind, impactClosure, moduleCountOf, normPath, packageCounts, modulesOf, HISTORY_CAP } from "./codegraph.mjs";
 import { isTestPath } from "./module-paths.mjs";
 import {
   RELATIONS,
@@ -84,6 +84,7 @@ const PLURAL_FORMS = {
   Attribute: ["attribute", "attributes"], GlobalVariable: ["variable", "variables"],
   Commit: ["commit", "commits"],
   Change: ["change", "changes"],
+  Package: ["package", "packages"],
   Fact: ["fact", "facts"], Utterance: ["utterance", "utterances"],
   Session: ["session", "sessions"], Source: ["source", "sources"], Rule: ["rule", "rules"],
 };
@@ -92,6 +93,23 @@ function nounFor(entityType, n) {
   return n === 1 ? s : p;
 }
 
+/** A discourse `set` referent for a class-homogeneous result list — the typed
+ *  content a listing/filter answer establishes, so a later "which of those …"
+ *  binds it (see evalCommitFilter for the shape the session layer registers).
+ *  Returns an empty array when nothing typed can be registered: no member
+ *  class, or an empty result. `extra` carries a lane's own sibling flags (the
+ *  anaphora lane's `bound: true`). */
+function setReferentsFor(cls, matches, lane, extra = {}) {
+  if (!cls || !matches.length) return [];
+  return [{
+    kind: "set", class: cls,
+    label: `${matches.length} ${nounFor(cls, matches.length)}`,
+    ids: matches.map((m) => m.id),
+    attrs: { count: matches.length },
+    lane, ...extra,
+  }];
+}
+
 /** A class enum rendered as prose words ("GlobalVariable" -> "global
  *  variable"), lowercase to match nounFor's own convention. For the render
  *  sites that must name the enum itself rather than a curated PLURAL_FORMS
@@ -834,7 +852,7 @@ function parseAggregate(w, lc, nlp) {
 
 const LIST_SKIP = new Set(["the", "a", "an", "all", "me", "us"]);
 const LIST_TRIGGERS_SORTED = [...LIST_TRIGGERS].sort((a, b) => b.split(" ").length - a.split(" ").length);
-const LISTABLE_KINDS = "functions, classes, methods, modules, attributes, variables, or commits";
+const LISTABLE_KINDS = "functions, classes, methods, modules, packages, attributes, variables, or commits";
 // A leading "in"/"inside"/"under" right after the entity noun is an
 // unambiguous location-scope tail, never a reverse-clause predicate object.
 const SCOPE_PREPOSITIONS = new Set(["in", "inside", "under"]);
@@ -1621,11 +1639,25 @@ function computeFind(graph, entityType, term) {
   return { narrow: [], broad: sortFindHits([...broadHits.values()]) };
 }
 
+/** The graph's packages as list/count-shaped individuals. Packages are derived
+ *  from module labels rather than stored as nodes (see codegraph.mjs's
+ *  packageCounts), so these carry a `pkg:` id of their own and resolve to
+ *  nothing in graph.byId — a follow-up that tries to traverse one gets an
+ *  empty result, never a wrong one. Ordered by module count, the same order
+ *  the architecture map prints, so the two surfaces agree. */
+function packageIndividuals(graph) {
+  return [...packageCounts(modulesOf(graph)).entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([dir]) => ({ id: `pkg:${dir}`, label: dir, class: "Package" }));
+}
+
 /** Compile a set-producing AST into an array of individuals. */
 function evalSet(graph, ast, opts) {
   switch (ast.node) {
     case "clause": return traverse(graph, ast.clause, opts).matches || [];
-    case "allOfClass": return graph.individuals.filter((i) => i.class === ast.entityType);
+    case "allOfClass":
+      if (ast.entityType === "Package") return packageIndividuals(graph);
+      return graph.individuals.filter((i) => i.class === ast.entityType);
     // Predicate-find as a set atom: the narrow-then-broaden cascade's result,
     // transparently flattened ("related, not exact" is a render concern).
     case "find": {
@@ -1806,7 +1838,13 @@ function evalAnaphora(graph, ast, opts) {
   const emptyClass = f && f.type === "entity" ? f.entityType : sameClass(baseItems);
   const common = items.length ? sameClass(items) : emptyClass;
   if (ast.mode === "count") return { compositeKind: "count", count: items.length, entityType: common, matches: [] };
-  return { compositeKind: "set", matches: items, entityType: common };
+  // A narrowed, class-homogeneous result registers as a NEW set referent so
+  // the narrowing survives a later count and binds a further "which of those".
+  // It rides `bound: true` (a follow-up derived FROM the standing set), so the
+  // session layer's register() does not evict the set on the class change a
+  // narrowing produces.
+  const referents = setReferentsFor(common, items, "anaphora", { bound: true });
+  return { compositeKind: "set", matches: items, entityType: common, referents };
 }
 
 // Structural kinds counted for "most-connected" (total degree). Symbol-grain and
@@ -1923,7 +1961,17 @@ function evalSuperlative(graph, ast) {
   if (!scored.length) return { compositeKind: "superlative", entityType: ast.entityType, matches: [] };
   const best = scored[0].score;
   const winners = scored.filter((s) => s.score === best).map((s) => s.ind);
-  return { compositeKind: "superlative", entityType: ast.entityType, metricNoun: ast.metricNoun, extreme: ast.extreme, score: best, matches: winners };
+  // What the ranking established, as discourse referents (see evalCommitFilter
+  // for the shape the session layer registers). A lone winner is one entity a
+  // later "it"/"this"/"that" can bind; a metric tie (two winners on the same
+  // score) is a set instead, since no singular form should silently pick one.
+  // The score itself is always a measure referent, so "is that bigger than X"
+  // binds the number the ranking produced rather than re-deriving it.
+  const referents = winners.length >= 2
+    ? setReferentsFor(ast.entityType, winners, "superlative")
+    : [{ kind: "entity", class: ast.entityType, label: winners[0].label, ids: [winners[0].id], attrs: {}, lane: "superlative" }];
+  referents.push({ kind: "measure", label: `${best} ${ast.metricNoun}`, ids: [], attrs: { metric: best }, lane: "superlative" });
+  return { compositeKind: "superlative", entityType: ast.entityType, metricNoun: ast.metricNoun, extreme: ast.extreme, score: best, matches: winners, referents };
 }
 
 /** Top-level "<kind> of/in <owner>" membership eval, covering both a bare
@@ -1938,6 +1986,9 @@ function evalMembershipComposite(graph, ast, opts) {
   const filterFn = qualNode
     ? (ind) => qualNode.filters.every((f) => qualHolds(graph, ind, QUALIFIERS[f]))
     : null;
+  // A class-typed membership result registers as a discourse set referent (see
+  // evalCommitFilter) so a later "which of those …" binds it.
+  const membershipReferents = (list) => setReferentsFor(entityType, list, "membership");
   const owner = resolveMembershipOwner(graph, memNode.term, opts && opts.contextId);
   if (owner.kind === "dir") {
     let objs;
@@ -1947,14 +1998,16 @@ function evalMembershipComposite(graph, ast, opts) {
       objs = uniqueById(MEMBERSHIP_KINDS.flatMap((k) => forwardOverSet(graph, k, ids))).filter((o) => o.class === entityType);
     }
     if (filterFn) objs = objs.filter(filterFn);
-    return { compositeKind: "set", matches: objs, entityType };
+    return { compositeKind: "set", matches: objs, entityType, referents: membershipReferents(objs) };
   }
   if (owner.kind === "miss") return { compositeKind: "set", matches: [], entityType };
   const { own, inherited, viaLabel } = computeMembership(graph, owner.id, owner.entityClass, entityType, filterFn);
   const inheritedNotOwn = !own.length && inherited.length > 0;
+  const finalMatches = inheritedNotOwn ? inherited : own;
   return {
-    compositeKind: "membership", entityType, matches: inheritedNotOwn ? inherited : own,
+    compositeKind: "membership", entityType, matches: finalMatches,
     inheritedNotOwn, viaLabel, ownerLabel: owner.label,
+    referents: membershipReferents(finalMatches),
   };
 }
 
@@ -2019,7 +2072,11 @@ function evalQualCheck(graph, ast, opts) {
   }
   const rawHolds = qualHolds(graph, r.match, QUALIFIERS[qualifier]);
   const holds = negated ? !rawHolds : rawHolds;
-  return { compositeKind: "qualCheck", subject: r.match, qualifier, negated, holds, matches: [r.match] };
+  // The subject the check resolved is a discourse referent either way — the
+  // answer being "no" does not make the entity any less bindable by a
+  // follow-up (see evalCommitFilter for the registration shape).
+  const referents = [{ kind: "entity", class: r.match.class, label: r.match.label, ids: [r.match.id], attrs: {}, lane: "qualCheck" }];
+  return { compositeKind: "qualCheck", subject: r.match, qualifier, negated, holds, matches: [r.match], referents };
 }
 
 /** Universal-over-a-set: the object is grounded first (an unknown one is an
@@ -2102,7 +2159,14 @@ function evalComposite(graph, ast, opts = {}) {
     && !(Array.isArray(opts.prev) && opts.prev.length)) {
     return { compositeMiss: true, reason: "no-prev", matches: [] };
   }
-  return { compositeKind: "set", matches: evalSet(graph, ast, opts), entityType: ast.entityType || null };
+  const matches = evalSet(graph, ast, opts);
+  const entityType = ast.entityType || null;
+  // A resolved, class-typed listing/filter set registers as a discourse
+  // referent (see evalCommitFilter) so a later "which of those …" binds it. A
+  // qualifier listing ("which modules are tested") registers the same way, just
+  // under its own lane name.
+  const referents = setReferentsFor(entityType, matches, ast.node === "qualifier" ? "qualifierListing" : "compositeSet");
+  return { compositeKind: "set", matches, entityType, referents };
 }
 
 // ---- compositional render: templated, same "honest miss vs cited hit"
@@ -2200,7 +2264,7 @@ function renderComposite(parsed, result, graph) {
     }
     // Kinds that don't live in a module (or have no module-scope parse at
     // all, like memory-graph classes) get no narrow-by-module hint.
-    const scopeable = !["Module", "Commit", "Fact", "Utterance", "Session", "Source", "Rule"].includes(result.entityType);
+    const scopeable = !["Module", "Package", "Commit", "Fact", "Utterance", "Session", "Source", "Rule"].includes(result.entityType);
     const hint = (!result.scoped && scopeable && result.matches.length > OVERFLOW_CAP)
       ? ` — narrow with "${nounFor(result.entityType, 2)} in <module>"`
       : "";
@@ -3111,8 +3175,15 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
       }
       commits.sort((a, b) => dateOf(b).localeCompare(dateOf(a)));
     }
+    // The dated commit this answer named is a discourse `event` referent, so a
+    // later "was that before X was touched" binds it (see evalCommitFilter).
+    // Only when a dated commit resolved — an undated one is the render's honest
+    // miss, and a referent with no date could not feed the comparison lane.
+    const referents = commits.length && dateOf(commits[0])
+      ? [{ kind: "event", class: "Commit", label: commits[0].label, ids: [commits[0].id], attrs: { date: dateOf(commits[0]).slice(0, 10) }, lane: "when" }]
+      : [];
     return {
-      matches: commits, objMatch, candidates, ambiguous, matchedVia, whenShape: true,
+      matches: commits, objMatch, candidates, ambiguous, matchedVia, whenShape: true, referents,
       traversal: `touches+touchesSymbol edges where object = ${objMatch.label}, newest commit date first`,
     };
   }
@@ -3135,8 +3206,14 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
       if (c && c.class === "Commit") commits.push(c);
     }
     commits.sort((a, b) => dateOf(b).localeCompare(dateOf(a)));
+    // The dated commit behind the "who last touched X" answer is the same
+    // `event` referent the when-shape registers, so either phrasing feeds a
+    // later temporal comparison. Registered only when the commit carries a date.
+    const referents = commits.length && dateOf(commits[0])
+      ? [{ kind: "event", class: "Commit", label: commits[0].label, ids: [commits[0].id], attrs: { date: dateOf(commits[0]).slice(0, 10) }, lane: "whoLast" }]
+      : [];
     return {
-      matches: commits, objMatch, candidates, ambiguous, matchedVia, whoLastShape: true,
+      matches: commits, objMatch, candidates, ambiguous, matchedVia, whoLastShape: true, referents,
       traversal: `touches+touchesSymbol edges where object = ${objMatch.label}, newest commit's author`,
     };
   }
@@ -4409,6 +4486,18 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
       content = `${content}\n(answering for ${result.objMatch.label} — ${others.length} other match${others.length === 1 ? "" : "es"}: ${list})`;
     }
   }
+  // A plain relation LISTING ("which modules import X", "which functions call
+  // X") resolves through the simple traverse path, not evalComposite, so it
+  // registers its class-typed result here — the same set referent the
+  // composite listing lanes emit, so a later "which of those …" binds it. Only
+  // a real, non-empty, class-homogeneous answer no lane already registered
+  // (the composite lanes set result.referents themselves).
+  if (!Array.isArray(result.referents) && !rendered.miss && !rendered.ambiguous
+    && (parsed?.shape === "reverse" || parsed?.shape === "forward")
+    && parsed.entityType && Array.isArray(result.matches) && result.matches.length
+    && result.matches.every((m) => m && m.class === parsed.entityType)) {
+    result = { ...result, referents: setReferentsFor(parsed.entityType, result.matches, "relationListing") };
+  }
   return {
     content,
     tmct_ask: {

package/src/domain/codegraph.mjs

@@ -1277,19 +1277,36 @@ export function renderSubclasses(graph, ind) {
 const ARCH_PKG_CAP = 25;
 const ARCH_HUB_CAP = 15;
 
+/** The directories that group a set of modules, each mapped to how many
+ *  modules it holds. A package is not a node class — no individual is ever
+ *  stored with class "Package" — so every surface that reports packages
+ *  (the architecture map, ask()'s package list and count) derives them from
+ *  module labels, and this is the one place that derivation lives. A module
+ *  at the repo root has no directory, so it groups under "(root)". */
+export function packageCounts(modules) {
+  const counts = new Map();
+  for (const m of modules) {
+    const dir = m.label.includes("/") ? m.label.slice(0, m.label.lastIndexOf("/")) : "(root)";
+    counts.set(dir, (counts.get(dir) || 0) + 1);
+  }
+  return counts;
+}
+
+/** Every module in the graph, optionally scoped to a path prefix. */
+export function modulesOf(graph, prefix = "") {
+  const norm = normPath(prefix);
+  return graph.individuals.filter(
+    (i) => (i.class || "") === "Module" && (!norm || normPath(i.label).startsWith(norm)),
+  );
+}
+
 /** Package/module tree + the most-imported (hub) modules — replaces reading the dir
  *  tree and many files to learn the shape. Optional `pkg` prefix scopes it. */
 export function renderArchitecture(graph, { pkg = "" } = {}) {
   const norm = normPath(pkg);
-  const modules = graph.individuals.filter(
-    (i) => (i.class || "") === "Module" && (!norm || normPath(i.label).startsWith(norm)),
-  );
+  const modules = modulesOf(graph, pkg);
   if (!modules.length) return norm ? `no modules under "${pkg}".` : "no modules in the graph.";
-  const pkgCount = new Map();
-  for (const m of modules) {
-    const dir = m.label.includes("/") ? m.label.slice(0, m.label.lastIndexOf("/")) : "(root)";
-    pkgCount.set(dir, (pkgCount.get(dir) || 0) + 1);
-  }
+  const pkgCount = packageCounts(modules);
   const inDeg = new Map();
   for (const e of edgesOfKind(graph, "imports")) inDeg.set(e.object, (inDeg.get(e.object) || 0) + 1);
   const modSet = new Set(modules.map((m) => m.id));

package/src/domain/interpret/normalize.mjs

@@ -110,10 +110,10 @@ const INTERROGATIVE_LEAD_RE = /^(?:which|what|who|whose|where|when|why|how)\b/i;
  *  untouched so that working path keeps it. Two shapes: a plural kind noun in
  *  tail position, or a bare (det +) singular kind noun and nothing else. */
 const LISTING_TAIL_KINDS = new Set([
-  "modules", "files", "functions", "methods", "classes", "attributes", "fields",
+  "modules", "files", "packages", "functions", "methods", "classes", "attributes", "fields",
   "properties", "variables", "globals", "commits", "changes", "tests", "members",
 ]);
-const BARE_KIND_RE = /^(?:all\s+|the\s+)?(?:module|file|function|method|class|attribute|field|property|variable|global|commit|change|test|member)\??$/i;
+const BARE_KIND_RE = /^(?:all\s+|the\s+)?(?:module|file|package|function|method|class|attribute|field|property|variable|global|commit|change|test|member)\??$/i;
 const isListingRemainder = (rest) => {
   if (BARE_KIND_RE.test(rest)) return true;
   const words = rest.replace(/\?+\s*$/, "").trim().split(/\s+/);

package/src/domain/reference-pack.mjs

@@ -12,6 +12,10 @@ import { RELATION_TERM } from "./concept.mjs";
 export const REFERENCE_PACK_NAME = "simplewiki";
 export const REFERENCE_SHARD_COUNT = 64;
 
+/** The grain cue every encyclopedia-grounded answer carries: this is a word's
+ *  general meaning, not something read out of the graph the session is about. */
+export const GENERAL_VOCABULARY_CUE = "General vocabulary, not from this codebase.";
+
 /** The shard a term's article row lives in: FNV-1a first byte mod 64, as the
  *  file basename "ref-00" … "ref-3f". Part of the pack's on-disk contract —
  *  the build script shards with THIS function, so the reader never scans. */
@@ -43,10 +47,14 @@ export function isReferenceArticleRow(row) {
 }
 
 /** The cited answer for a clean miss the pack could ground: the article's
- *  summary with its title, licence and revision-pinned URL always visible. */
+ *  summary with its title, licence and revision-pinned URL always visible,
+ *  then the grain cue. Without the cue a reader has to recognize the source
+ *  name to tell this apart from a fact read out of their own graph — both
+ *  answer the same "what is X" question in the same voice. */
 export function renderReferenceAnswer(term, article) {
   return `${term} — ${article.summary} (source: reference article "${article.title}", `
-    + `Simple English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`;
+    + `Simple English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`
+    + ` ${GENERAL_VOCABULARY_CUE}`;
 }
 
 /** The provenance tag a fact stored from a pack article carries —
@@ -88,7 +96,8 @@ export function liveProvenanceTag(article) {
  *  the revision-pinned URL always visible. */
 export function renderLiveReferenceAnswer(term, article) {
   return `${term} — ${article.summary} (source: live Wikipedia article "${article.title}", `
-    + `English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`;
+    + `English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`
+    + ` ${GENERAL_VOCABULARY_CUE}`;
 }
 
 /** The pure half of the LIVE clean-miss gate — same fold, shape check and

package/src/domain/router/call-validator.mjs

@@ -1,6 +1,6 @@
 // src/domain/router/call-validator.mjs — pure registry validators shared by the
 // product router (resolver / goal-reasoner) + the bench grader
-// (agentbench/grade.mjs re-exports these). Depends ONLY on registry.mjs — no
+// (test-benchmarks/agentbench/grade.mjs re-exports these). Depends ONLY on registry.mjs — no
 // bench code — so the product←bench dependency stays inverted: the bench
 // imports the product, never the other way round. No I/O, no Date.now, no LLM.
 

package/src/domain/router/drive.mjs

@@ -243,8 +243,8 @@ export async function runTaughtPlan(request, tools, ctx) {
 /** The full drive: resolver/planner first; a refusal there falls through to
  *  the taught world-goal lane (runTaughtPlan, above), and only a request that
  *  is not a world goal escalates to the closed-world goal-reasoner. Mirrors
- *  agentbench's driver-resolver.mjs + driver-goal.mjs composition, with no
- *  agentbench/ dependency (agentbench/ is dev-only, never shipped). Returns a
+ *  test-benchmarks/agentbench's driver-resolver.mjs + driver-goal.mjs composition, with no
+ *  test-benchmarks/agentbench/ dependency (test-benchmarks/agentbench/ is dev-only, never shipped). Returns a
  *  loopResult:
  *  `{ calls, refused, terminated, proof, why, driver, composed?, observed?, candidateResults? }`.
  *

package/src/domain/router/set-algebra.mjs

@@ -1,7 +1,7 @@
 // src/domain/router/set-algebra.mjs — the COMPOSITION OPERATORS: pure set-algebra a
 // multi-step plan needs to fold its threaded step result-sets into ONE composed
 // answer. Shared by the product router (goal-reasoner's relative-filter fold)
-// and the bench result-execution layer (agentbench/results.mjs re-exports
+// and the bench result-execution layer (test-benchmarks/agentbench/results.mjs re-exports
 // these) — the bench imports the product, never the other way round. The
 // resolver DRIVER picks the operator from the router's OWN HTN method
 // (relative-filter -> intersect; conditional -> fallback/guard) and applies it;