@polycode-projects/the-mechanical-code-talker 2.11.6 → 2.11.10

package/README.md

@@ -124,14 +124,14 @@ page answers codebase questions live, and eight more pages each ground their
 own domain: a full chat seeded with 32,646 facts (the same nine bands as
 `npm run init:xl`, capped to a 38.7 MB download, 2.1 MB on the wire), the
 **memory ledger** (every fact as a readable sentence; drill by clicking the
-terms inside), the **code explorer** (the same ledger UI refocused on a code
-graph, with a hint rail of suggested next questions), an **ingest page** that
-turns pasted or dropped text into grounded facts and downloads them as
-canonical JSONL, a Towers-of-Hanoi plan replayed move by move, the
-spider-and-fly and text-adventure games, and a sprite gallery whose chat dock
-answers from 1,033 generated sprite facts. The chat page and the ledger take
-the same paste-or-drop text in place; every page that holds a fact store
-exports it as JSONL.
+terms inside), and the **code explorer** (the same ledger UI refocused on a
+code graph, with a hint rail of suggested next questions). An **ingest
+page** turns pasted or dropped text into grounded facts and downloads them
+as canonical JSONL. The rest are a Towers-of-Hanoi plan replayed move by
+move, the spider-and-fly and text-adventure games, and a sprite gallery
+whose chat dock answers from 1,033 generated sprite facts. The chat page and
+the ledger take the same paste-or-drop text in place; every page that holds
+a fact store exports it as JSONL.
 The site hosts its own copy of wink-nlp, ships its assets precompressed,
 and a service worker precaches the big ones, so a second visit works
 offline. `tmct chat --render spider-fly|adventure|sprites [--output <path>]`
@@ -168,13 +168,14 @@ The same ledger UI, refocused on a code graph, also runs as a desktop app. It
 reads a `graph.json` (or a repo's `.tmct/` folder), shows every import, call and
 `contains` edge as a plain sentence around a focus symbol, and docks a live chat
 over the same graph. A hint rail suggests the next question from what the graph
-actually holds — "what does X import", "which functions call Y", "list
-functions" — so every suggestion resolves to a real answer.
+actually holds: "what does X import", "which functions call Y", "list
+functions". Every suggestion resolves to a real answer.
 
-The identical page also runs as a plain hosted page, over the demo code
-graph — **[try it live →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/code.html)**
-— for a look with nothing to install. The desktop build below is for
-exploring your own repo or graph, which the hosted page cannot reach.
+The identical page also runs as a plain hosted page over the demo code
+graph, with nothing to install:
+**[try it live →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/code.html)**.
+The desktop build below is for exploring your own repo or graph, which the
+hosted page cannot reach.
 
 Electron is a dev-only dependency and never ships in the npm package. Because
 `.npmrc` sets `ignore-scripts=true`, installing it does not fetch the runtime
@@ -188,8 +189,8 @@ npm run electron                        # open the code explorer on the demo gra
 ```
 
 Open a graph or a repo from the window's title bar to explore your own code.
-The UI is channel-agnostic — only the Electron shell (`electron/main.mjs` +
-`electron/preload.cjs`) is desktop-specific; the same page stays servable as a
+The UI is channel-agnostic. Only the Electron shell (`electron/main.mjs` +
+`electron/preload.cjs`) is desktop-specific. The same page stays servable as a
 plain web page. `npm run test:electron` runs the shell smoke via Playwright and
 skips cleanly when the binary is absent.
 
@@ -226,8 +227,8 @@ 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 `CAPABILITIES_2.7.12.md` and
-the `BENCHMARK_*.md` reports.
+The full catalog with measured coverage lives in the `BENCHMARK_*.md`
+reports.
 
 **Response finishing.** Before an answer prints, it is segmented into typed
 spans: prose versus *protected* entities, paths, numbers, code, provenance,
@@ -310,7 +311,7 @@ planner over the same read-only graph-query tools chat/serve use
 step in order with a provable causal-link proof chain, and folds the results
 into one answer. A request neither the planner nor a single lookup can ground
 escalates to a closed-world goal-reasoner, which deduces maintenance goals
-(coverage gaps, change-coupling risk) straight from the graph — never from
+(coverage gaps, change-coupling risk) straight from the graph, never from
 keywords in your question. Anything none of that grounds is an honest "no plan
 found", the same "grounded or an honest miss" rule as everywhere else in tmct.
 
@@ -344,7 +345,7 @@ composed answer (4): src/handlers/base.mjs, src/handlers/users.mjs, src/server/a
 ```
 
 tmct planned two calls (`tmct_impact` then `tmct_untested`), ran both against the
-real graph, and intersected the results itself — you get the four modules that
+real graph, and intersected the results itself. You get the four modules that
 are both downstream of the change AND missing coverage, not two separate lists
 you'd have to cross-reference by hand.
 
@@ -361,7 +362,7 @@ composed answer (1): src/lib/http.mjs
 
 It deduced the goal ("an impactful module must be tested"), gathered every
 untested module, ranked each by blast radius, and named the one worth testing
-first — `src/lib/http.mjs`, the module with the widest reach.
+first: `src/lib/http.mjs`, the module with the widest reach.
 
 `--tools tmct_impact,tmct_untested` restricts which capabilities the planner is
 allowed to use; `--json` prints the full machine-readable loop result (calls,
@@ -372,9 +373,9 @@ flag reference.
 ## Teach it a game, then ask it to plan
 
 The planner above works over a fixed toolset. This one works over rules you
-teach. A game definition is a plain-text file of controlled English — the
+teach. A game definition is a plain-text file of controlled English: the
 classes, the pieces, the ordering, and the legal moves as taught action
-rules — with `#` comment lines carrying example prompts. `tmct init`
+rules, with `#` comment lines carrying example prompts. `tmct init`
 scaffolds one at `.tmct/imports/games/hanoi-3.txt`, and
 `tmct import --file` teaches it sentence by sentence, reporting every line
 and refusing (exit 1) if any sentence declines.
@@ -402,8 +403,8 @@ Goal (inferred): Plan a move sequence from the current state to the goal (7 move
 facts stamped with the step that produced them ("disk-1@step1 rests on peg-c",
 sourced to the plan). The final step re-reads the store and confirms the goal
 from those written facts, never assuming success. The stamp is what makes each
-step a separate record; a question about the piece itself ("where does disk-1
-rest?", "is disk-1 clear?") reads the current board — the latest step's facts,
+step a separate record. A question about the piece itself ("where does disk-1
+rest?", "is disk-1 clear?") reads the current board: the latest step's facts,
 not every step at once. The search is
 domain-general: the test
 suite teaches Towers of Hanoi purely as sentences for 1 to 8 disks and
@@ -417,17 +418,17 @@ the plan as a self-contained animated page (see "Two more surfaces" above).
 Three games run inside an ordinary chat session, no setup.
 
 **Guess the number.** Say `I'm thinking of a number between 1 and 100` and
-tmct guesses by narrowing an interval — answer `higher`, `lower`, or
+tmct guesses by narrowing an interval: answer `higher`, `lower`, or
 `correct`. It finds any number in at most 7 guesses, and if your answers
 contradict each other it names the contradicting pair and stops rather than
 guessing on. Say `think of a number` to swap seats: tmct commits to a secret
-and answers your guesses honestly, reveals on request, and corrects you from
-its own record if you claim it already said `correct`. The behaviour is
-pinned by `test/corpus/games/guess-number.jsonl`.
+and sticks to it. It answers your guesses, reveals the number on request, and
+corrects you from its own record if you claim it already said `correct`. The
+behaviour is pinned by `test/corpus/games/guess-number.jsonl`.
 
 **A text adventure.** Say `start the adventure` (or `play ashcombe hall`)
 and tmct loads a small country-house mystery from a lazily-fetched worlds
-pack (`corpus/worlds/`) into the session's ordinary memory graph — rooms,
+pack (`corpus/worlds/`) into the session's ordinary memory graph: rooms,
 objects and people become graph facts, and the verbs (`go`, `take`, `open`,
 `unlock`, `look`…) are taught action rules, not hard-wired code. Every move
 writes per-turn snapshot facts, `look` is an extractive digest of the graph,
@@ -436,30 +437,30 @@ schedule whether you are there to see it or not. The full worked mystery is
 pinned step by step in `test/corpus/games/adventure.jsonl`.
 
 **Two agents, planning against each other.** Say `play spider and fly` (or
-`watch the spider and the fly`) and tmct runs both sides itself — neither is
+`watch the spider and the fly`) and tmct runs both sides itself. Neither is
 player-controlled. A spider hunts a fly across a 10×10 web; each side only
 believes what it can currently see (`vision_radius`, tunable), a fly wanders
 when nothing threatens it and evades when something does, a spider avoids
 other spiders, chases what it believes it sees, and builds a web when it
 holds position. Mass is real: both sides waste away each turn they don't
 eat, and a spider gains exactly the mass of what it catches. You can address
-either side directly (`@spider the fly is east`) to feed it a belief — true
-or false — and watch a wrong assertion mislead it for as long as the real
+either side directly (`@spider the fly is east`) to feed it a belief, true
+or false, and watch a wrong assertion mislead it for as long as the real
 target stays out of sight. `tmct.toml`'s `[games.spider-fly]` table tunes
 every rate; the full mechanic is pinned in `test/corpus/games/spider-fly.jsonl`.
 
 ## Learning on a miss
 
-A question tmct cannot ground is still an honest miss — but on the cleanest
-kind of miss (a recognised word, a clean parse, simply no facts anywhere) it
+A question tmct cannot ground is still an honest miss. But on the cleanest
+kind of miss (a recognised word, a clean parse, simply no facts anywhere), it
 now consults two shipped, lazily-loaded packs before giving up:
 
-- `corpus/child/` — 93k everyday-world triples filtered from ConceptNet by a
+- `corpus/child/`: 93k everyday-world triples filtered from ConceptNet by a
   child-concept seed. Asked `what is a kettle` cold, tmct loads the term's
   triples into memory (provenance `child:conceptnet:kettle`, ranked below
   anything you teach) and answers from them; the next ask answers from
   memory directly.
-- `corpus/reference/` — 3,887 Simple English Wikipedia summaries. When the
+- `corpus/reference/`: 3,887 Simple English Wikipedia summaries. When the
   triples cannot answer, a matching article answers as a cited read-out
   (`source: reference article "Otter"…, CC BY-SA 4.0`).
 
@@ -495,7 +496,7 @@ by cleaned session logs:
   relevance rather than loaded wholesale.
 
 Every session also writes its own human-readable transcript,
-`.tmct/session-<id>.md` — a glow-friendly Markdown file with one heading per
+`.tmct/session-<id>.md`, a glow-friendly Markdown file with one heading per
 turn, the question as a blockquote, the reply in a fenced block. The
 browser chat page's "export .md" button writes the same shape.
 
@@ -538,7 +539,7 @@ Teaching isn't limited to the ACE grammar's fixed shapes. Tell tmct an
 arbitrary fact, like "margo really eats ribs", and it mints a fact you can
 ask about directly: "what does margo eat". New vocabulary compounds as you
 teach: "redis is a cache" mints "redis" even though it was never in the
-built-in lexicon, as long as one side of the sentence is already grounded —
+built-in lexicon, as long as one side of the sentence is already grounded.
 tmct never mints a fact between two totally ungrounded terms; it declines and
 nudges you to ground one side first. Quantified teaching stores the
 quantifier ("some functions are risky" … "how many functions are risky" →
@@ -553,13 +554,13 @@ rather than the code graph. A taught class answers both shapes too: after
 
 When you ask about a term, the read-back shows each "is a kind of" object with
 its own superclass chain: "what is rover" answers "rover is a kind of dog →
-canine → mammal → animal". If one label carries two unrelated senses — you
-taught "rover is a dog" and a corpus row says "rover is a scout" — the answer
+canine → mammal → animal". If one label carries two unrelated senses (you
+taught "rover is a dog" and a corpus row says "rover is a scout"), the answer
 groups by concept ("rover, the dog:" / "rover, the scout:") instead of listing
 two unrelated lines as if they were one thing. The split is deterministic over
 the stored hierarchy: two senses part when a stored disjointness separates
 their ancestors, when their chains never meet, or when they meet only at the
-very top. When the evidence is thin the answer stays a flat list — grouping is
+very top. When the evidence is thin the answer stays a flat list. Grouping is
 presentation, and it never retracts or reranks a fact.
 
 Teaching doesn't have to be typed, either. `tmct extract` runs a plain text
@@ -586,14 +587,14 @@ carries an `extracted:<file>` provenance tag at its own trust tier.
 recognizer skips: a copula or a known relation verb flanked by two nouns
 becomes a candidate triple, stored under its own `optimistic-extract:<file>`
 provenance (prior 0.35, below every curated pack) with no operator tag riding
-alongside — so a fuzzy guess can never corroborate a curated fact. It is an
+alongside, so a fuzzy guess can never corroborate a curated fact. It is an
 attempt, not full NLU: a sentence with no clean pair yields nothing.
 `--canonical` prints each grounded fact as a triple, noting how each endpoint
 already links into the store.
 
 The same pipeline is one library seam, `ingestText(text, options)` (exported
 as `@polycode-projects/the-mechanical-code-talker/ingest`), and one cold tool,
-`tmct_ingest` — so a browser page, a script, or a tool-calling agent can ground
+`tmct_ingest`. A browser page, a script, or a tool-calling agent can ground
 text without the CLI.
 
 ### Provenance and trust
@@ -754,7 +755,7 @@ already set up. Its `--graph` flag works differently from the others: it appends
 ```
 
 `tmct extract` is the document route into memory described under "Teach it"
-above — the same teach recognizer, reading a file instead of your typing:
+above: the same teach recognizer, reading a file instead of your typing:
 
 ```output:help:extract
   tmct extract <text-file>     read a plain text file's sentences through the chat's own
@@ -787,7 +788,7 @@ inference" above:
                                retractable entailed facts (never on the chat path)
 ```
 
-`tmct viz` renders the memory graph as the ledger explorer — a single,
+`tmct viz` renders the memory graph as the ledger explorer, a single,
 self-contained HTML file you can open in a browser:
 
 ```output:help:viz
@@ -867,7 +868,7 @@ aws/python/java) into ~7,380 facts on the default sqlite backend, a working
 example to copy from. `init:xl` starts from the large persona tier and adds
 the wordnet-xl corpus (~72,000 facts); `init:xxl` swaps wordnet-xl for the
 full WordNet slice plus namenet (~239,000 facts, the biggest committed
-vocabulary — expect its imports to take a minute). The xl chain, spelled out:
+vocabulary, so expect its imports to take a minute). The xl chain, spelled out:
 
 ```bash e2e heavy
 npx tmct init --persona-size large   # npm run init:xl runs this whole chain from a clone
@@ -1171,12 +1172,12 @@ 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 |
 |---|---|---|---|
-| Multi-hop entailment | 379/379 chat cases and 100/100 kernel cases, 0% fabrication, all bands pass | The case set is unchanged from 2.6.0 (same templates, same counts) — the one real move this cycle is INF-4's ceiling-graded count dropping 35→30, five cases that now pass as genuine capability instead of against the declared honest-miss floor. | `BENCHMARK_INFERENCE_2.7.12.md` |
-| Tool-call planning | 68/68 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. 2.6.0 gated at TOOL-7 (62/66, 94%) — this cycle's router uplift (a guarded RECOVER step, a tied-candidate composer) cleared it, a real capability move, not a ruler change. | `BENCHMARK_AGENT_2.7.12.md` |
+| Multi-hop entailment | 379/379 chat cases and 100/100 kernel cases, 0% fabrication, all bands pass | The case set is unchanged from 2.6.0 (same templates, same counts). The one real move this cycle is INF-4's ceiling-graded count dropping 35→30: five cases that now pass as genuine capability instead of against the declared honest-miss floor. | `BENCHMARK_INFERENCE_2.7.12.md` |
+| Tool-call planning | 68/68 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. 2.6.0 gated at TOOL-7 (62/66, 94%). This cycle's router uplift (a guarded RECOVER step, a tied-candidate composer) cleared it: a real capability move, not a ruler change. | `BENCHMARK_AGENT_2.7.12.md` |
 | Groundedness | Every answer carries a source, and an empty graph reports itself empty. Judge-scored mean 1.809/2 over 138 cases, 5 hard fails, 136/138 tier-1. | Judged (`claude-haiku-4-5-20251001`, `judge-prompt-v2`) at N=1. The judge prompt moved v1→v2 since 2.6.0, so this is a measurement, not a clean lever comparison against the prior cycle. The judge runs in the offline eval harness, never in the product. | `BENCHMARK_CEFR_ENGLISH_2.7.12.md` |
 | Abstention (the honest miss) | 0% fabrication across 479 inference rows (379 chat + 100 kernel) and 0% hallucination across 272 agent rows | Structural, not a tuned threshold. tmct abstains because nothing matched, so the rows test a property of a no-model design rather than a score. | `BENCHMARK_INFERENCE_2.7.12.md`, `BENCHMARK_AGENT_2.7.12.md` |
-| Determinism | Byte-identical on rerun — a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.7.12.md` |
-| Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check — the single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `NEXT.md`). | `BENCHMARK_CONVERSATION_2.7.11.md` |
+| Determinism | Byte-identical on rerun: a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.7.12.md` |
+| Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check. The single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `NEXT.md`). | `BENCHMARK_CONVERSATION_2.7.11.md` |
 
 Three offline benchmark rigs live in a clone (they are not in the npm
 package). Each replays a committed case set through the real product and

package/bin/tmct.mjs

@@ -1261,7 +1261,8 @@ async function main() {
     const rest = process.argv.slice(3);
     if (rest.includes("--help") || rest.includes("-h")) {
       process.stdout.write(
-        "tmct serve — Anthropic Messages API-compatible endpoint (POST /v1/messages)\n\n" +
+        "tmct serve — Anthropic Messages API-compatible endpoint (POST /v1/messages)\n" +
+        "             plus a capability-router plan verb (POST /v1/plan)\n\n" +
         "Usage:\n" +
         "  tmct serve [--repo <abs>] [--graph <path>] [--config <path>] [--host <h>] [--port <n>]\n\n" +
         "  --repo <abs>   target a repo's graph (<abs>/.tmct/graph.json); default: git root/cwd\n" +
@@ -1270,9 +1271,14 @@ async function main() {
         "  --config <path>  an alternate tmct.toml location (a file or a directory)\n" +
         "  --host <h>     bind address (default 127.0.0.1)\n" +
         "  --port <n>     TCP port (default 8787; 0 picks an ephemeral port)\n\n" +
-        "Request:  { model, messages:[...], tools:[...], max_tokens, system? }\n" +
-        "Response: { id, type:\"message\", role:\"assistant\", content:[...blocks], stop_reason, usage }\n" +
-        "          usage is always { input_tokens: 0, output_tokens: 0 } — tmct is the $0 floor.\n",
+        "POST /v1/messages\n" +
+        "  Request:  { model, messages:[...], tools:[...], max_tokens, system? }\n" +
+        "  Response: { id, type:\"message\", role:\"assistant\", content:[...blocks], stop_reason, usage }\n" +
+        "            usage is always { input_tokens: 0, output_tokens: 0 } — tmct is the $0 floor.\n\n" +
+        "POST /v1/plan\n" +
+        "  Request:  { request: \"<NL request>\", tools?: [\"tmct_impact\", ...] }\n" +
+        "  Response: the capability-router loop result — grounded { driver, calls, proof,\n" +
+        "            composed?, usage } or an in-band honest { refused: true, why }.\n",
       );
       return;
     }
@@ -1287,13 +1293,19 @@ async function main() {
     // REPLACES serve's old cwd-only default (loadConfig had no git-root
     // fallback) with the same git-root-aware default every other subcommand
     // now shares — a deliberate, documented unification, not a regression.
-    const { config } = await resolveRuntimeConfig({ argv: rest });
-    const srv = await startServer({ config, host, port });
+    const { repo, config, toml } = await resolveRuntimeConfig({ argv: rest });
+    // Open the taught store the same env > tmct.toml > default way `tmct plan`
+    // does, so /v1/plan reasons over the taught world/rule records chat wrote —
+    // registered per request and unregistered after, never mutated by serve.
+    const { openMemoryBackend } = await import("../src/adapters/memory/core.mjs");
+    const backendChoice = String(process.env.TMCT_MEMORY_BACKEND || toml?.memory?.backend || "").trim().toLowerCase();
+    const { dir: memoryDir, close: closeMemoryStore } = await openMemoryBackend(repo, backendChoice);
+    const srv = await startServer({ config, host, port, memoryDir });
     process.stdout.write(
-      `tmct serve — Anthropic Messages API at ${srv.url}/v1/messages (POST) — ` +
+      `tmct serve — Anthropic Messages API at ${srv.url}/v1/messages (POST), plan at ${srv.url}/v1/plan (POST) — ` +
       `graph ${srv.config.graphFile} — usage billed $0 — Ctrl+C to stop\n`,
     );
-    const shutdown = async () => { await srv.close(); process.exit(0); };
+    const shutdown = async () => { await srv.close(); await closeMemoryStore(); process.exit(0); };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     return; // the listening server keeps the event loop alive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.6",
+  "version": "2.11.10",
   "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.",
@@ -144,6 +144,7 @@
     "build:plan-bundle": "node scripts/build-plan-bundle.mjs",
     "build:ledger-bundle": "node scripts/build-ledger-bundle.mjs",
     "build:ingest-bundle": "node scripts/build-ingest-bundle.mjs",
+    "build:research-bundle": "node scripts/build-research-bundle.mjs",
     "build:code-explorer-bundle": "node scripts/build-code-explorer-bundle.mjs",
     "build:electron": "node scripts/build-electron-app.mjs",
     "electron": "electron electron/main.mjs",

package/src/adapters/toml-config.mjs

@@ -108,6 +108,8 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   const seedCfg = {};
   if (seed.enabled !== undefined) seedCfg.enabled = seed.enabled;
   if (seed.limit !== undefined) seedCfg.limit = seed.limit;
+  if (seed.capture_unknown_context !== undefined) seedCfg.captureUnknownContext = seed.capture_unknown_context;
+  if (seed.unknown_context_limit !== undefined) seedCfg.unknownContextLimit = seed.unknown_context_limit;
   if (Object.keys(seedCfg).length) cfg.seed = seedCfg;
 
   // Extension-pack seam (src/services/extensions.mjs): sparse PASS-THROUGH only — the

package/src/domain/ask-vocab.mjs

@@ -317,6 +317,38 @@ export const PASSIVE_PARTICIPLE_TO_KIND = Object.freeze({
   touched: "touches", changed: "touches", modified: "touches", edited: "touches", updated: "touches",
 });
 
+// ---- stacked reduced-relative clauses: a "<participle> <preposition>" bigram
+// that opens a reduced relative modifying a head noun ("classes INHERITED FROM
+// Widget DEFINED IN c.mjs"). Each entry names the relation kind and which role
+// the following term fills:
+//   role "object" — the surface is active-disguised, the preposition marks the
+//     relation's OBJECT, so the answer is the SUBJECTS pointing at the term (a
+//     reverse traversal): "inherited from Widget" -> the classes that inherit
+//     Widget.
+//   role "agent"  — a genuine passive whose "by"/"in" marks the AGENT, so the
+//     answer is the term's own FORWARD targets: "defined in c.mjs" -> what
+//     c.mjs defines.
+// Only consulted by parseStackedReducedRelative, which requires TWO such
+// bigrams on one head noun; a single reduced relative keeps its existing route.
+// Naming senses and directionally-ambiguous bigrams ("imported from", "used
+// in/for", "called <name>") are deliberately absent so they stay honest misses.
+export const REDUCED_RELATIVE_CLAUSES = Object.freeze({
+  "inherited from": { kind: "inherits", role: "object" },
+  "extended from": { kind: "inherits", role: "object" },
+  "subclassed from": { kind: "inherits", role: "object" },
+  "defined in": { kind: "defines", role: "agent" },
+  "declared in": { kind: "defines", role: "agent" },
+  "contained in": { kind: "contains", role: "agent" },
+  "imported by": { kind: "imports", role: "agent" },
+  "called by": { kind: "calls", role: "agent" },
+  "used by": { kind: "uses", role: "agent" },
+  "tested by": { kind: "tests", role: "agent" },
+  "covered by": { kind: "tests", role: "agent" },
+  "touched by": { kind: "touches", role: "agent" },
+  "changed by": { kind: "touches", role: "agent" },
+  "exported by": { kind: "reexports", role: "agent" },
+});
+
 // ---- normalization: contractions/informal spellings expanded before parsing,
 // shared by both parse strategies. ----
 export const CONTRACTIONS = Object.freeze({

package/src/domain/ask.mjs

@@ -23,7 +23,7 @@ import {
   CONTEXT_PRONOUNS, META_MEANING_VERBS,
   WHERE_MARKERS, MENTION_MARKERS,
   RELATIVE_PRONOUNS, PLACEHOLDER_NOUNS, BOOLEAN_CONNECTIVES, QUALIFIERS,
-  PASSIVE_PARTICIPLE_TO_KIND, GENERIC_AGENT_WORDS,
+  PASSIVE_PARTICIPLE_TO_KIND, GENERIC_AGENT_WORDS, REDUCED_RELATIVE_CLAUSES,
   AGGREGATE_TRIGGERS, LIST_TRIGGERS, SUPERLATIVE_EXTREMES, EDGE_NOUN_TO_METRIC, METRIC_IMPLIES_ENTITY, ANAPHORA_TRIGGERS,
   MEMBERSHIP_KINDS, CASCADE_NOISE, CASCADE_SYNONYMS, HELP_TRIGGERS,
   stripTrailingScopeFiller,
@@ -236,9 +236,57 @@ function parseComposite(text, nlp) {
     || parseList(w, lc, nlp, 0)
     || parseNested(w, lc, nlp, 0)
     || parsePluralAnaphoraObject(w, lc, nlp)
+    || parseStackedReducedRelative(w, lc)
     || parseRelationalOrQualified(w, lc, nlp, 0);
 }
 
+// Two reduced relatives stacked on one head noun ("classes INHERITED FROM
+// Widget DEFINED IN c.mjs") — a garden-path shape a naive incremental parser
+// misattaches as a second main clause. Both clauses modify the head, so the
+// reading is their intersection. Each clause's REDUCED_RELATIVE_CLAUSES entry
+// says whether its term is the relation's object (reverse: the subjects that
+// point at it) or its agent (forward: the term's own targets). The head noun's
+// entityType rides the SEED clause, so a forward "defines" leg that would
+// otherwise return every symbol is filtered to the asked kind. Anything that
+// isn't exactly [lead] head bigram term bigram term returns null, leaving
+// every other shape's behavior byte-identical.
+const STACKED_RRC_LEAD = new Set(["which", "the", "all"]);
+function parseStackedReducedRelative(w, lc) {
+  let i = 0;
+  if (STACKED_RRC_LEAD.has(lc[i])) i += 1;
+  const noun = entityNoun(lc[i]);
+  if (!noun || noun.placeholder || !noun.entityType) return null;
+  const entityType = noun.entityType;
+  i += 1;
+  const bigramAt = (k) => (k + 1 < lc.length ? REDUCED_RELATIVE_CLAUSES[`${lc[k]} ${lc[k + 1]}`] : undefined);
+  const rr1 = bigramAt(i);
+  if (!rr1) return null;
+  const term1Start = i + 2;
+  let split = -1;
+  let rr2;
+  for (let k = term1Start; k + 1 < lc.length; k += 1) {
+    const hit = bigramAt(k);
+    if (hit) { split = k; rr2 = hit; break; }
+  }
+  if (split < 0) return null;
+  const term1 = w.slice(term1Start, split).join(" ").trim();
+  const term2 = w.slice(split + 2).join(" ").trim();
+  if (!term1 || !term2) return null;
+  const clauseFor = (rr, term) => (rr.role === "object"
+    ? { shape: "reverse", kind: rr.kind, entityType, modifier: "direct", object: term }
+    : { shape: "forward", kind: rr.kind, modifier: "direct", object: term });
+  const seed = clauseFor(rr1, term1);
+  seed.entityType = entityType;   // head-noun class filter on the seed set
+  return {
+    node: "boolean",
+    entityType,
+    atoms: [
+      { op: "seed", kind: "set", ast: { node: "clause", clause: seed } },
+      { op: "intersection", kind: "set", ast: { node: "clause", clause: clauseFor(rr2, term2) } },
+    ],
+  };
+}
+
 // Negation as set complement: "which X do not <verb> Y" compiles to
 // allOfClass(kind) DIFFERENCE (the positive result set). The "Change"
 // pseudo-type has no bounded enumerable universe, so a complement over
@@ -598,6 +646,12 @@ function parsePredicateFilter(words, nlp) {
   const restLc = lc.slice(i);
   if (!rest.length) return { type: "all" };
   if (restLc.every((x) => QUALIFIERS[x])) return { type: "qual", filters: restLc };
+  // A bare concrete entity noun ("which of them are functions") narrows the
+  // prior set to one class rather than testing a relation.
+  if (rest.length === 1) {
+    const en = entityNoun(restLc[0]);
+    if (en && !en.placeholder && en.entityType) return { type: "entity", entityType: en.entityType };
+  }
   const clause = parseSimpleClause(`what ${rest.join(" ")}`, nlp);
   if (clause && (clause.shape === "reverse" || clause.shape === "forward") && clause.object) {
     return { type: "clause", clause };
@@ -1729,6 +1783,8 @@ function evalAnaphora(graph, ast, opts) {
   const f = ast.filter;
   if (f && f.type === "qual") {
     items = items.filter((ind) => f.filters.every((q) => qualHolds(graph, ind, QUALIFIERS[q])));
+  } else if (f && f.type === "entity") {
+    items = items.filter((ind) => ind.class === f.entityType);
   } else if (f && f.type === "clause") {
     const r = resolveObject(graph, f.clause.object);
     if (!r.match) items = [];
@@ -1743,9 +1799,12 @@ function evalAnaphora(graph, ast, opts) {
   }
   // A count over a prior set names the entity kind when survivors share a
   // class; fall back to the prior set's own class when the filter empties it,
-  // so the honest-empty render still names what was checked.
+  // so the honest-empty render still names what was checked. An entity-type
+  // filter that empties the set names the FILTER's kind ("functions"), not the
+  // base set's — the reader asked which of them were that kind.
   const sameClass = (list) => (list.length && list.every((x) => x.class === list[0].class) ? list[0].class : null);
-  const common = items.length ? sameClass(items) : sameClass(baseItems);
+  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 };
 }
@@ -3296,6 +3355,15 @@ function bareVerbFor(kind) {
   return RELATIONS[kind]?.bare || kind;
 }
 
+/** The passive participle of a relation ("uses" -> "used", "imports" ->
+ *  "imported"), for the confirming "X is <participle> by Y" frame. The bare
+ *  forms in this vocabulary are all regular, so a single +d/+ed rule covers
+ *  them. */
+function passiveParticipleFor(kind) {
+  const bare = bareVerbFor(kind);
+  return bare.endsWith("e") ? `${bare}d` : `${bare}ed`;
+}
+
 /** English gloss of a SET-COMPLEMENT AST — the shape parseNegation compiles
  *  "which X do not <verb> Y" into (allOfClass DIFFERENCE the positive set).
  *  Restates the question in the same grammar the positive canonical uses
@@ -3747,11 +3815,28 @@ function renderCore(parsed, result, graph) {
       };
     }
     const entityWord = nounFor(parsed.entityType || "Module", 2);
+    // Name the resolved antecedent, not the raw pronoun: "who touched it" that
+    // bound "it" to fnAlpha must say so, or the receipt reads as though nothing
+    // was resolved at all. Scoped to a context pronoun so a typed term keeps the
+    // wording the reader chose, never its normalized graph label.
+    const object = (result.objMatch && CONTEXT_PRONOUNS.includes(String(parsed.object || "").toLowerCase()))
+      ? result.objMatch.label
+      : parsed.object;
     return {
-      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}. ${touchesRephraseHint(graph)}`,
+      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${object}. ${touchesRephraseHint(graph)}`,
       miss: true, ambiguous: false,
     };
   }
+  // A polar reverse question ("is X used anywhere") with exactly one match
+  // reads as a confirming yes that names the single subject, rather than a bare
+  // one-item list. Scoped to one match: two or more keep the plain list.
+  if (parsed.polar && result.matches.length === 1) {
+    const objLabel = result.objMatch?.label || parsed.object;
+    return {
+      content: `Yes — ${objLabel} is ${passiveParticipleFor(parsed.kind)} by ${result.matches[0].label}.`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
   // Route by the matched entities' actual class, not just the parsed hint —
   // grouping module-level matches by-module would read as nonsense ("in
   // a.mjs there is a.mjs"). Fine-grained grouping only applies to sub-module

package/src/domain/domain.mjs

@@ -228,6 +228,20 @@ export function stateFromFacts(factRows, domain) {
   return state;
 }
 
+/** The highest @stepN snapshot index present for a domain individual, or 0
+ *  when the board carries no snapshot layer yet. A freshly minted plan reads
+ *  this as its stepBase, so its own @stepK writes stack ABOVE any standing
+ *  snapshot instead of colliding with it and being read as the same layer. */
+export function maxSnapshotStep(factRows, domain) {
+  const individuals = domainIndividuals(domain);
+  let max = 0;
+  for (const row of factRows || []) {
+    const m = SNAPSHOT_RE.exec(normTerm(row.subject));
+    if (m && individuals.has(m[1])) max = Math.max(max, Number(m[2]));
+  }
+  return max;
+}
+
 /** Canonical identity for a state (rows are kept sorted). NUL-joined so
  *  multi-word terms can never collide with the separator; spelled without an
  *  escape sequence because tooling has twice turned a source-level \\0 into a

package/src/domain/interpret/strategies/keywords.mjs

@@ -19,6 +19,11 @@ import { VOCAB_WORDS, eligibleForCanon, fuzzyVocabWord } from "../fuzzy.mjs";
 const PASSIVE_AUX = new Set(["is", "are", "was", "were", "be", "been", "being", "get", "gets", "got"]);
 const WH_WORDS = new Set(["which", "what", "who", "whom", "whose"]);
 const PLACEHOLDER_SET = new Set(PLACEHOLDER_NOUNS.map((w) => w.toLowerCase()));
+// A trailing time adverb on a bare passive ("was X touched RECENTLY") is not the
+// relation's object — it modifies the whole clause. Only consulted on the
+// participle path with no agent "by", so it can never touch an active-verb
+// object slot. Mirrors ask.mjs's TEMPORAL_TRAIL_FILLER for the when-shape.
+const TEMPORAL_TRAILING_ADVERBS = new Set(["recently", "lately", "yet", "already", "ever", "again"]);
 // See ask-vocab.mjs's own HAS_FAMILY_VERBS for why a bare have-family verb
 // never resolves to `defines` in this strategy's two-named-role "ask" shape
 // below (the forward/reverse branches keep their own tested grain-check
@@ -198,7 +203,14 @@ export function parseKeywordSpot(text, nlp = null) {
     .join(" ")
     .trim();
   const beforeText = sideText(0, verbHit.start);
-  const afterText = sideText(verbHit.end, words.length);
+  let afterText = sideText(verbHit.end, words.length);
+  // A lone trailing time adverb after a bare participle ("was it touched
+  // recently") is clause-level, not the relation's object; drop it so the
+  // sentence reaches the bare-passive branch and answers over the patient
+  // instead of trying to resolve "recently" as a term.
+  if (verbFromParticiple && !lcWords.includes("by") && TEMPORAL_TRAILING_ADVERBS.has(afterText.toLowerCase())) {
+    afterText = "";
+  }
   const kind = verbHit.kind;
   // slices read canonWords, not lcWords: the entity/modifier spans were matched
   // against the canonicalized array, whose word IS the table key.
@@ -316,7 +328,11 @@ export function parseKeywordSpot(text, nlp = null) {
     // nobody asked, so this declines and the sentence misses honestly.
     if (beforeText.split(/\s+/).length > 1) return null;
     if (kind === "touches") return stamp({ shape: "when", entityType: null, modifier: "direct", kind, object: beforeText });
-    return stamp({ shape: "reverse", entityType, modifier, kind, object: beforeText });
+    // A sentence that LEADS with the passive auxiliary is an interrogative
+    // yes/no ("is X used anywhere"), not a declarative patient statement; mark
+    // it so a single reverse match can render a confirming Yes frame.
+    const polar = PASSIVE_AUX.has(lcWords[0]);
+    return stamp({ shape: "reverse", entityType, modifier, kind, object: beforeText, ...(polar ? { polar: true } : {}) });
   }
   // forward keeps the spotted entityType (traverse()'s commit-as-subject grain
   // selection); modifier stays hardcoded since no forward closure traversal exists.