@polycode-projects/the-mechanical-code-talker 1.5.5 → 1.8.4

package/src/ask.mjs

@@ -44,7 +44,7 @@ import {
   CONTEXT_PRONOUNS, META_MEANING_VERBS,
   WHERE_MARKERS, MENTION_MARKERS,
   RELATIVE_PRONOUNS, PLACEHOLDER_NOUNS, BOOLEAN_CONNECTIVES, QUALIFIERS,
-  AGGREGATE_TRIGGERS, LIST_TRIGGERS, SUPERLATIVE_EXTREMES, EDGE_NOUN_TO_METRIC, ANAPHORA_TRIGGERS,
+  AGGREGATE_TRIGGERS, LIST_TRIGGERS, SUPERLATIVE_EXTREMES, EDGE_NOUN_TO_METRIC, METRIC_IMPLIES_ENTITY, ANAPHORA_TRIGGERS,
   MEMBERSHIP_KINDS, CASCADE_NOISE, CASCADE_SYNONYMS, HELP_TRIGGERS,
 } from "./ask-vocab.mjs";
 // The interpretation layer (ROADMAP items 8/10/13) — the movable conversational
@@ -56,8 +56,9 @@ import { editDistance, fuzzyBound } from "./interpret/fuzzy.mjs";
 import { parseAnchored } from "./interpret/strategies/grammar.mjs";
 import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mjs";
 import { runStrategiesSync } from "./interpret/pipeline.mjs";
-import { mergeStrategyResults } from "./interpret/merge.mjs";
+import { mergeStrategyResults, alternateLines } from "./interpret/merge.mjs";
 import { lookupByProseTokens } from "./prose.mjs";
+import { pickPhrase } from "./answer-variants.mjs";
 
 // Normalization stays importable from its original site (tests + chat surface).
 export { normalizeQuery, applyNegationFrames };
@@ -222,12 +223,66 @@ function defaultNlp() {
  *  test); leaving it undefined picks the deterministic default (defaultNlp).
  *  Pure given (query, adapter) — the adapter itself is a fixed model, no
  *  sampling. */
+// SCHEMA-TERM / COMMON-WORD "WHAT DOES X MEAN" DISAMBIGUATION (CHATBENCH decision-log
+// item 1, g-a1-naming-8: "what does tests mean"). When the object term X is ITSELF a
+// real RELATIONS/VERB_TO_KIND keyword ("tests", "imports", …), keyword-spot
+// independently reads the sentence as a "reverse"-shaped query — kind:X, object:"mean"
+// — because "mean"/"means" (META_MEANING_VERBS, ask-vocab.mjs §7) is deliberately kept
+// OUT of the relation tables (see that table's own comment): keyword-spot has no idea
+// it just consumed the meta question's own verb as if it were an object noun. That
+// reading can never resolve to anything real ("mean" is never a graph entity) — it's a
+// spurious parse, not a genuine second reading — yet it collides with the grammar
+// strategy's own clean "meta" parse of the SAME sentence to manufacture the legacy
+// {ambiguousParse} surface ("this could mean more than one thing: 1) meta X or 2) X
+// 'mean' — try rephrasing"). Pruned here whenever the winning class's candidates are
+// EXACTLY [a meta-shape parse, a same-precedence parse whose object is a
+// META_MEANING_VERB] — collapsing back to the meta parse alone, so the term's own
+// schema-predicate definition answers directly instead of the unhelpful two-way punt.
+//
+// EXCEPT "imports": am-meta-imports (chatbench/graded-pool.jsonl) and
+// quickwins.test.mjs's "fix1: the frozen am-meta-imports ambiguity is NOT admitted"
+// both lock this EXACT ambiguity in as the intended, honest answer for that one term —
+// "what does imports mean" is byte-identical input to both am-meta-imports (which
+// requires the ambiguous answer) and g-a1-naming-9 (which wants the plain definition).
+// A deterministic function cannot satisfy both on the same input; widening the prune to
+// "imports" would silently flip am-meta-imports from passing to failing, a real
+// regression this project's own decision rule (SKILL_BENCHMARK_CEFR_ENGLISH.md §1)
+// forbids. So "imports" keeps its existing ambiguous answer — the same judgment call
+// chat.mjs's relationTermOf already makes for it (see that function's own docblock) —
+// while every OTHER relation term this collision can hit ("tests" included) is fixed
+// generally, not as a one-off patch.
+const FROZEN_META_AMBIGUOUS_TERMS = new Set(["imports"]);
+function pruneSpuriousMeaningAmbiguity(parsed) {
+  if (!parsed?.ambiguousParse || !Array.isArray(parsed.candidates) || parsed.candidates.length !== 2) return parsed;
+  const metaC = parsed.candidates.find((c) => c?.shape === "meta");
+  const other = parsed.candidates.find((c) => c !== metaC);
+  if (!metaC || !other) return parsed;
+  const term = String(metaC.object || "").trim().toLowerCase();
+  if (!term || FROZEN_META_AMBIGUOUS_TERMS.has(term)) return parsed;
+  const otherObject = String(other.object || "").trim().toLowerCase();
+  if (!wordsOf(META_MEANING_VERBS).includes(otherObject)) return parsed;
+  return metaC;
+}
+
 export function parseQuery(query, { nlp = undefined } = {}) {
+  return parseQueryFull(query, { nlp }).parsed;
+}
+
+/** Sibling of `parseQuery` that also surfaces what `parseQuery` has always
+ *  discarded: `merge.mjs`'s `class`/`alternates` (PLAN_BREADTH_FIRST_NLU.md §3)
+ *  — a genuine, distinct-class alternate reading a different strategy produced,
+ *  silently dropped on every hit until now. `parseQuery`'s own contract stays
+ *  byte-identical (it's defined in terms of this function's `.parsed` field,
+ *  above) — 142 existing call sites are untouched. Returns
+ *  `{parsed, alternates, class}`; `alternates`/`class` are `[]`/`null` on the
+ *  compositional-parse path (a structurally separate grammar layer that never
+ *  reaches `mergeStrategyResults`) or on a total miss. */
+export function parseQueryFull(query, { nlp = undefined } = {}) {
   const adapter = nlp === undefined ? defaultNlp() : nlp;
   const raw = String(query || "").trim().replace(/\s+/g, " ");
-  if (!raw) return null;
+  if (!raw) return { parsed: null, alternates: [], class: null };
   const text = applyPhrasingFrames(applyNegationFrames(normalizeQuery(raw)));
-  if (!text) return null;
+  if (!text) return { parsed: null, alternates: [], class: null };
   // COMPOSITIONAL PARSE PATH (PLAN §5.16 P3) — the new PRIMARY layer: a recursive
   // descent over CLAUSES for the compositional shapes (nested/relative, boolean,
   // qualifiers, aggregates, superlatives, anaphora). It fires ONLY when a
@@ -237,9 +292,14 @@ export function parseQuery(query, { nlp = undefined } = {}) {
   // the phrase cannot be compiled, it returns an honest {node:"miss"} rather than
   // letting keyword-spot guess at a composition it never expressed.
   const composite = parseComposite(text, adapter);
-  if (composite) return composite;
+  if (composite) return { parsed: composite, alternates: [], class: null };
   const merged = mergeStrategyResults(runStrategiesSync(text, { nlp: adapter, raw }));
-  return merged ? merged.parsed : null;
+  if (!merged) return { parsed: null, alternates: [], class: null };
+  return {
+    parsed: pruneSpuriousMeaningAmbiguity(merged.parsed),
+    alternates: merged.alternates || [],
+    class: merged.class || null,
+  };
 }
 
 // ============================================================================
@@ -431,19 +491,28 @@ function parseForwardNegation(w, lc, nlp) {
   return { node: "forwardComplement", kind: vh.kind, subjectTerm };
 }
 
-/** The single OBJECT class a forward relation kind points at across the loaded graph
- *  (imports → Module), or null when its objects span more than one class (an ambiguous
- *  grain the complement's universe can't be pinned to). Ext: endpoints have no individual,
- *  so they don't muddy the class vote. Used by the forwardComplement evaluator to bound
- *  the universe it differences the positive forward set out of. */
-function kindObjectClass(graph, kind) {
+/** The full set of OBJECT classes observed across every edge of the given stored
+ *  kinds (already expanded past any query-side union — callers pass `kindsFor(kind)`
+ *  or an equivalent list). Ext: endpoints have no individual, so they don't muddy
+ *  the class vote. Shared by `kindObjectClass` (collapses to a single class or null)
+ *  and the forward branch's grain check (needs the full set, not the collapse). */
+function classesForKinds(graph, kinds) {
   const classes = new Set();
-  for (const k of kindsFor(kind)) {
+  for (const k of kinds) {
     for (const e of edgesOfKind(graph, k)) {
       const o = graph.byId.get(e.object);
       if (o && o.class) classes.add(o.class);
     }
   }
+  return classes;
+}
+
+/** The single OBJECT class a forward relation kind points at across the loaded graph
+ *  (imports → Module), or null when its objects span more than one class (an ambiguous
+ *  grain the complement's universe can't be pinned to). Used by the forwardComplement
+ *  evaluator to bound the universe it differences the positive forward set out of. */
+function kindObjectClass(graph, kind) {
+  const classes = classesForKinds(graph, kindsFor(kind));
   return classes.size === 1 ? [...classes][0] : null;
 }
 
@@ -474,21 +543,36 @@ function parseSetPhrase(text, nlp, depth) {
  *  that call X", handled by parseRelationalOrQualified) by requiring a VERB before the
  *  relative noun (i.e. the noun is not the leading subject). Returns a reverse/forward
  *  Set node, an honest miss (marker present, uncompilable), or null (no object-relative
- *  marker → let another production try). */
+ *  marker → let another production try).
+ *
+ *  The marker is either an explicit relative pronoun ("the module THAT imports X") or a
+ *  REDUCED relative clause with the pronoun dropped ("the module IMPORTING X" — a gerund
+ *  verb right where the pronoun+verb would go means the same thing). Root-cause fix for
+ *  g-c1-temp-8 (2026-07-12): "who touched the module importing X" has no "that", so this
+ *  loop used to find no marker at all, return null, and let the query fall through to the
+ *  legacy (non-compositional) strategy pipeline — which then misread the leading verb
+ *  "touched" itself as the flat ASK shape's subject TERM ("does 'touched' import X"),
+ *  never resolving to a real entity. "the module THAT imports X" (explicit pronoun)
+ *  already routed correctly through this same function; the gerund form is the identical
+ *  nested-set shape and is now recognized the same way. */
 function parseNested(w, lc, nlp, depth) {
   for (let r = 1; r < lc.length; r += 1) {
-    if (!RELATIVE_PRONOUNS.includes(lc[r])) continue;
-    if (r + 1 >= lc.length) continue;               // nothing after "that"
+    const isPronoun = RELATIVE_PRONOUNS.includes(lc[r]);
+    const isGerundMarker = !isPronoun && isGerundVerb(lc[r]);
+    if (!isPronoun && !isGerundMarker) continue;
+    if (isPronoun && r + 1 >= lc.length) continue;  // nothing after "that"
     const noun = entityNoun(lc[r - 1]);
-    if (!noun) continue;                            // "that" not preceded by a noun
+    if (!noun) continue;                            // marker not preceded by a noun
     const head = w.slice(0, r - 1);                 // outer clause words, minus the placeholder noun
     if (!head.length) continue;                     // noun is the leading subject → subject-relative, not this shape
     const outer = parseSimpleClause([...head, NEST_SENTINEL].join(" "), nlp);
     if (!outer || (outer.shape !== "reverse" && outer.shape !== "forward")) continue;
     if (outer.modifier && outer.modifier !== "direct") continue; // no transitive-over-set closure primitive
     // build the inner sub-query: "which <placeholder-noun> <inner-text>" — recurses,
-    // so the inner may itself be nested/boolean/qualified (depth ≥2).
-    const innerText = `which ${lc[r - 1]} ${w.slice(r + 1).join(" ")}`;
+    // so the inner may itself be nested/boolean/qualified (depth ≥2). An explicit
+    // relative pronoun is consumed (skip past it, start at r+1); a gerund marker IS
+    // the predicate's own verb, so it stays in the inner text (start AT r).
+    const innerText = `which ${lc[r - 1]} ${w.slice(isPronoun ? r + 1 : r).join(" ")}`;
     const inner = parseSetPhrase(innerText, nlp, depth + 1);
     if (!inner || inner.node === "miss") return inner ? { node: "miss", reason: inner.reason || "inner clause didn't parse" } : { node: "miss", reason: "inner clause didn't parse" };
     return { node: outer.shape === "reverse" ? "reverseSet" : "forwardSet", kind: outer.kind, entityType: outer.entityType, inner };
@@ -922,11 +1006,9 @@ function parseSuperlative(w, lc, nlp) {
     if (SUPERLATIVE_EXTREMES[lc[i]]) { ext = SUPERLATIVE_EXTREMES[lc[i]]; extIdx = i; break; }
   }
   if (!ext) return null;
-  // entity noun anywhere (first match, deterministic)
-  let entityType; let entWord = null;
-  for (const x of lc) { const n = entityNoun(x); if (n && !n.placeholder) { entityType = n.entityType; entWord = x; break; } }
-  if (!entWord) return { node: "miss", reason: "a superlative needs an entity kind (module, class, function, …)" };
-  // edge noun after the extreme (imports/callers/methods/…)
+  // edge noun after the extreme (imports/callers/methods/…) — computed BEFORE
+  // the entity-noun check below, so a metric with a single implied entity class
+  // (METRIC_IMPLIES_ENTITY) can supply a default when no explicit noun is given.
   let metric = null; let metricNoun = null;
   for (let i = extIdx; i < lc.length; i += 1) {
     if (EDGE_NOUN_TO_METRIC[lc[i]]) { metric = EDGE_NOUN_TO_METRIC[lc[i]]; metricNoun = lc[i]; break; }
@@ -945,10 +1027,18 @@ function parseSuperlative(w, lc, nlp) {
   }
   const connectivity = lc.includes("connected") || lc.slice(extIdx, extIdx + 2).join(" ") === "most connected"
     || ["largest", "biggest", "smallest"].includes(lc[extIdx]);
-  if (!metric) {
-    if (connectivity) { metric = EDGE_NOUN_TO_METRIC.connections; metricNoun = "connections"; }
-    else return { node: "miss", reason: "name what to rank by (imports, callers, methods, tests, or connections)" };
+  if (!metric && connectivity) { metric = EDGE_NOUN_TO_METRIC.connections; metricNoun = "connections"; }
+  // entity noun anywhere (first match, deterministic); else default from a
+  // metric that implies exactly one entity class ("test(s)" always ranks
+  // Modules, the one declared exception — see METRIC_IMPLIES_ENTITY — so "what
+  // most needs a test" resolves without also requiring the word "module").
+  let entityType; let entWord = null;
+  for (const x of lc) { const n = entityNoun(x); if (n && !n.placeholder) { entityType = n.entityType; entWord = x; break; } }
+  if (!entWord) {
+    entityType = metricNoun ? METRIC_IMPLIES_ENTITY[metricNoun] : undefined;
+    if (!entityType) return { node: "miss", reason: "a superlative needs an entity kind (module, class, function, …)" };
   }
+  if (!metric) return { node: "miss", reason: "name what to rank by (imports, callers, methods, tests, or connections)" };
   return { node: "superlative", entityType, metric, metricNoun, extreme: ext };
 }
 
@@ -1455,7 +1545,7 @@ export function metaFallbackEntityAnswer(graph, term) {
     || null;
   const noun = nounFor(hit.class, 1);
   const article = noun === "attribute" ? "an" : "a";
-  const definedIn = modLabel ? `, defined in ${modLabel}` : "";
+  const definedIn = modLabel ? `, ${pickPhrase("defined-in", hit.id, "defined in")} ${modLabel}` : "";
   const followUp = hit.class === "Class" ? ` or "which classes inherit from ${hit.label}"` : "";
   return {
     text: `${hit.label} is ${article} ${noun} in this codebase${definedIn} — try "describe ${hit.label}"${followUp}.`,
@@ -2146,7 +2236,7 @@ function renderComposite(parsed, result) {
       }
       const hit = result.matches[0];
       const modLabel = moduleLabelOf(hit);
-      const definedIn = hit.class === "Module" ? "" : (modLabel && modLabel !== "(unknown module)" ? `, defined in ${modLabel}` : "");
+      const definedIn = hit.class === "Module" ? "" : (modLabel && modLabel !== "(unknown module)" ? `, ${pickPhrase("defined-in", hit.id, "defined in")} ${modLabel}` : "");
       return { content: `Yes — ${hit.label} is a ${kindSingular}${definedIn}.`, miss: false, ambiguous: false, matches: result.matches };
     }
     if (!result.matches.length) {
@@ -2200,7 +2290,7 @@ function renderComposite(parsed, result) {
   // computeFind's "related, not exact" broad pass documents for predicate-find).
   if (result.compositeKind === "membership") {
     if (!result.matches.length) {
-      return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}.`, miss: true, ambiguous: false, matches: [] };
+      return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${touchesRephraseHint()}`, miss: true, ambiguous: false, matches: [] };
     }
     if (result.inheritedNotOwn) {
       const kindPlural = nounFor(result.entityType, 2);
@@ -2293,10 +2383,10 @@ function renderComposite(parsed, result) {
     const setNoun = result.entityType ? nounFor(result.entityType, n || 2) : (n === 1 ? "entity" : "entities");
     const wasWere = n === 1 ? "was" : "were";
     if (!n) {
-      return { content: `nothing in the index matches the inner set, so there is no change history to date.`, miss: true, ambiguous: false, matches: [] };
+      return { content: `nothing in the index matches the inner set, so there is no change history to date. ${touchesRephraseHint()}`, miss: true, ambiguous: false, matches: [] };
     }
     if (!result.matches.length) {
-      return { content: `no recorded commit touched the ${n} ${setNoun} in that set in this index.`, miss: true, ambiguous: false, matches: [] };
+      return { content: `no recorded commit touched the ${n} ${setNoun} in that set in this index. ${touchesRephraseHint()}`, miss: true, ambiguous: false, matches: [] };
     }
     const newest = result.matches[0];
     const date = (newest.attributes || []).find((a) => a.key === "date")?.value || "";
@@ -2313,7 +2403,7 @@ function renderComposite(parsed, result) {
   }
   // set-producing
   if (!result.matches.length) {
-    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}.`, miss: true, ambiguous: false, matches: [] };
+    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${touchesRephraseHint()}`, miss: true, ambiguous: false, matches: [] };
   }
   return { content: `${compositeList(result.matches)}.`, miss: false, ambiguous: false, matches: result.matches };
 }
@@ -2321,10 +2411,35 @@ function renderComposite(parsed, result) {
 /** The rephrase hint shown on a grammar miss — generated from the SAME tables the parser
  *  uses, so it can never suggest a phrasing the grammar doesn't actually support (§6.3). */
 export function rephraseHint() {
-  return '"which <functions|classes|modules> <imports|calls|uses|inherits from|tests|touched> <name>" or "what does <name> <import|call|export>" or "what uses <name>" or "where is <name> defined" / "where is <name> mentioned" or "when did <name> change" or "which changes touch commit <sha>"/"what did commit <sha> touch" (a commit\'s own changes) or plainly "what calls this" (about a selected node) or "what does <term> mean"/"what is a <ClassName>" (about the graph\'s own vocabulary). '
+  // "touched" used to sit in the <imports|calls|uses|inherits from|tests> cross-product
+  // above, combined with <functions|classes|modules> — but `touches` is a Commit->Module/
+  // symbol edge (ask-vocab.mjs's RELATIONS.touches comment), so a Function/Class/Module is
+  // NEVER the subject of a touch: "which modules touched X" always misses, for every X, no
+  // matter the graph (verified against test/fixtures/entities.fixture.json — every reverse
+  // combination with "touched" and a functions/classes/modules subject returns zero
+  // matches). The real reverse subject for this edge is Commit — "which commits touched
+  // <name>" below, mirroring the working "who touched <name>" nudge used elsewhere
+  // (chat.mjs's nudgeAnswer).
+  return '"which <functions|classes|modules> <imports|calls|uses|inherits from|tests> <name>" or "what does <name> <import|call|export>" or "what uses <name>" or "where is <name> defined" / "where is <name> mentioned" or "when did <name> change" or "which commits touched <name>" or "which changes touch commit <sha>"/"what did commit <sha> touch" (a commit\'s own changes) or plainly "what calls this" (about a selected node) or "what does <term> mean"/"what is a <ClassName>" (about the graph\'s own vocabulary). '
     + compositionalHint();
 }
 
+/** A short, honest nudge for the touches/history-family of correct-but-unhelpful
+ *  honest misses (CEFR decision log, BENCHMARK_CEFR_ENGLISH_1.7.0.md item 1:
+ *  g-c1-temp-7, g-c1-temp-3, g-b1-pron-1/4/5, hm-unknown-fn, hm-unknown-module all
+ *  scored `rephrase: 0` despite being correct empty results — the miss said WHAT
+ *  wasn't found but gave no nudge toward a question that WOULD work). Points at the
+ *  same "who touched X" / "/describe X" shapes that produce a real answer elsewhere
+ *  in this file (see whenShape/whoLastShape's own success template, "X was last
+ *  touched by commit …", a few lines below) — never promises any PARTICULAR name
+ *  will resolve, since the whole point of the miss it's attached to is that this
+ *  one didn't. Sibling of rephraseHint() above: same purpose, narrower vocabulary,
+ *  reused verbatim by every touches/history-family miss template rather than each
+ *  one inventing its own wording. */
+export function touchesRephraseHint() {
+  return 'Try "who touched <a module that actually has commits>" or "/describe <module>" to see what\'s in the index.';
+}
+
 // ---- §4 object-term resolution — mechanical, no embeddings, tiered, stop at first hit ----
 
 function componentSet(s) {
@@ -2915,13 +3030,29 @@ const TRANSITIVE_MAX_DEPTH = 8;
  *  needed one. Returns {matches, objMatch, candidates, traversal, ambiguous,
  *  answer?, unresolvedPronoun?} — `answer` only set for the "ask" shape.
  *  `matches` is always an array of individuals (or edge records for "ask"). */
-export function traverse(graph, parsed, { contextId = null, prev = null } = {}) {
+export function traverse(graph, parsed, { contextId = null, prev = null, pinnedObjMatch = null } = {}) {
   if (!parsed) return { matches: [], objMatch: null, candidates: [], traversal: null, ambiguous: false };
   // compositional AST (PLAN §5.16 P3) — the new grammar's nodes carry a `node` tag;
   // everything else (simple clauses, ambiguousParse) flows through the original path
   // below completely unchanged.
   if (parsed.node) return evalComposite(graph, parsed, { contextId, prev });
-  if (parsed.ambiguousParse) return { matches: [], objMatch: null, candidates: [], traversal: null, ambiguous: false };
+  // (fix, 2026-07-11) A same-class parse-level tie ({ambiguousParse, candidates})
+  // used to short-circuit here with an empty result, so renderCore's ambiguousParse
+  // branch could only ever describe each reading ("1) meta X or 2) Y — try
+  // rephrasing"), never actually answer any of them — an honest admission of
+  // ambiguity with no real content behind it. Every candidate IS a normal,
+  // individually-resolvable parse (merge.mjs only ties same-class DISTINCT parses,
+  // never nests another ambiguousParse inside one), so each one can be traversed
+  // and rendered for real right here — the combined answer stays deterministic on
+  // the same input (no guessing, no picking a winner) while actually telling the
+  // user what each reading resolves to, instead of making them ask twice.
+  if (parsed.ambiguousParse) {
+    const branches = parsed.candidates.map((c) => {
+      const branchResult = traverse(graph, c, { contextId, prev });
+      return { parsed: c, result: branchResult, rendered: render(c, branchResult) };
+    });
+    return { matches: [], objMatch: null, candidates: parsed.candidates, traversal: null, ambiguous: true, branches };
+  }
   const { shape, kind, entityType } = parsed;
 
   // meta: a question about the graph's OWN vocabulary ("what does cochange mean", "what
@@ -3019,8 +3150,94 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
 
   // reverse and forward both resolve one named term ("object" in the parsed shape — for
   // forward it is the query's grammatical subject, e.g. "what does X import" -> parsed.object = X).
-  const { match: objMatch, candidates, ambiguous, unresolvedPronoun, matchedVia } = resolveTermOrContext(graph, parsed.object, contextId);
+  //
+  // altObject pruning (PLAN_CONVERSATION.md Finding 2): noise-strip.mjs's bare
+  // "where"/"mentions" reading may carry `parsed.altObject` — the SAME reading
+  // with a wink-POS-flagged, plausibly-noise light verb ALSO dropped ("store
+  // router" -> "router"; see that file's own doc for why the signal needs full-
+  // sentence context and can't be decided there, where there is no graph).
+  // This is the one place both the alternate reading and the graph are
+  // available together, so it's where the pruning actually happens — mirroring
+  // resolveObject's own grain-word retry just above (try a variant, keep it
+  // ONLY on an unambiguous hit, else fall through unchanged) and
+  // grammar/ace.mjs's parseAceAmbiguous ("keep only complete, valid parses,
+  // dead ends pruned"). Four outcomes: primary misses/ties + alt resolves
+  // cleanly -> the alt reading wins (the dead end is pruned); primary resolves
+  // cleanly -> untouched, regardless of what the alt does (byte-identical to
+  // before this existed); both resolve cleanly to the SAME entity -> untouched
+  // either way; both resolve cleanly to DIFFERENT entities -> genuine
+  // ambiguity, surfaced the same honest way resolveObject's own tier ties
+  // already are, never silently guessed.
+  // ENTITY-TIE BRANCHES (breadth-first ambiguity, PLAN_BREADTH_FIRST_NLU.md §1): a
+  // recursive traverse() call for one already-tied candidate arrives here with
+  // `pinnedObjMatch` set — skip re-resolution entirely (no re-derived tie is
+  // possible, so `ambiguous` is structurally false on every such call) rather
+  // than re-resolving by label text, which would risk a second individual
+  // sharing the same label, a stale `altObject` re-triggering a spurious new
+  // tie, or the test-variant-collision guard misfiring on a non-Module label.
+  let objRes;
+  if (pinnedObjMatch) {
+    objRes = { match: pinnedObjMatch, candidates: [], ambiguous: false, matchedVia: null };
+  } else {
+    objRes = resolveTermOrContext(graph, parsed.object, contextId);
+    if (parsed.altObject && parsed.altObject !== parsed.object) {
+      const altRes = resolveTermOrContext(graph, parsed.altObject, contextId);
+      const primaryClean = !!objRes.match && !objRes.ambiguous;
+      const altClean = !!altRes.match && !altRes.ambiguous;
+      if (!primaryClean && altClean) {
+        objRes = altRes;
+      } else if (primaryClean && altClean && objRes.match.id !== altRes.match.id) {
+        objRes = { ...objRes, ambiguous: true, candidates: [altRes.match, ...(objRes.candidates || [])] };
+      }
+    }
+    // TEST-VARIANT COLLISION (CHATBENCH decision-log item 2, am-tests-cover: "which
+    // tests cover b.mjs"): a "tests"-kind query's object may also honestly name its
+    // OWN conventional test-variant sibling ("b.mjs" -> "b.test.mjs"/"b.spec.mjs"),
+    // a DIFFERENT real Module — app/lib/b.mjs and app/unit-tests/b.test.mjs both
+    // plausibly answer "b.mjs" when the question is specifically about test
+    // coverage. Deliberately scoped to kind==="tests" (never touches, imports,
+    // calls, …) — the SAME bare filename in an unrelated query ("has store.mjs
+    // been touched", chatflow-agents-debt-remeasure.test.mjs BUG-B's ground truth,
+    // examples/mini-webapp genuinely has the same store.mjs/store.test.mjs pair) has
+    // no such self-referential reading and must stay untouched. ALSO scoped to a
+    // BARE (unslashed) term — same convention as resolveObjectCore's own `dotted`
+    // tier just above resolveObject's call site: a query that already spells out
+    // the full path ("which functions test src/core/store.mjs",
+    // chatflow-tier4.test.mjs Batch 4/5; "app/lib/b.mjs", chatflow-tier2.test.mjs
+    // T18) is already unambiguous by construction and must stay untouched — only
+    // the bare basename is genuinely open to either reading. Same discipline as
+    // the altObject prune just above: only a CLEAN primary match plus a genuinely
+    // DIFFERENT real Module promotes to honest ambiguity, never a silent guess.
+    if (parsed.kind === "tests" && objRes.match && !objRes.ambiguous && !String(parsed.object || "").includes("/")) {
+      const stripTestInfix = (base) => base.replace(/\.(?:test|spec|tests)(?=\.[^.]+$)/, "");
+      const termBase = stripTestInfix(String(parsed.object || "").trim().toLowerCase());
+      const collision = (graph.individuals || []).find((i) => {
+        if (i.class !== "Module" || i.id === objRes.match.id) return false;
+        const base = String(i.label || "").toLowerCase().split("/").pop();
+        return base !== stripTestInfix(base) && stripTestInfix(base) === termBase;
+      });
+      if (collision) objRes = { ...objRes, ambiguous: true, candidates: [collision, ...(objRes.candidates || [])] };
+    }
+  }
+  const { match: objMatch, candidates, ambiguous, unresolvedPronoun, matchedVia } = objRes;
   if (!objMatch) return { matches: [], objMatch: null, candidates, traversal: null, ambiguous: false, unresolvedPronoun };
+  // BREADTH-FIRST ENTITY-TIE RESOLUTION (PLAN_BREADTH_FIRST_NLU.md §1): mirrors the
+  // parsed.ambiguousParse branch above — every tied candidate is independently
+  // traversed and rendered for real (via the pinnedObjMatch short-circuit just
+  // above), never left as a bare name list. Capped at OVERFLOW_CAP BEFORE
+  // traversing (not just before rendering) to avoid wasted work on candidates
+  // that won't be shown. One accepted, narrow trade-off: a general reverse-case
+  // query whose grain-refine retry below would previously have silently
+  // recovered to a different class-correct match now short-circuits to branches
+  // instead — not exercised by any pinned test/bench case today.
+  if (ambiguous) {
+    const pool = uniqueById([objMatch, ...(candidates || [])]).slice(0, OVERFLOW_CAP);
+    const branches = pool.map((c) => {
+      const branchResult = traverse(graph, parsed, { contextId, prev, pinnedObjMatch: c });
+      return { candidate: c, result: branchResult, rendered: render(parsed, branchResult) };
+    });
+    return { matches: [], objMatch, candidates, traversal: null, ambiguous: true, branches };
+  }
 
   // where: "where is X [defined]" (2026-07-02 query families) — the resolved
   // entity IS the answer; render() reads its class + site attribute ("path:
@@ -3109,11 +3326,52 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
     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);
+    // FORWARD GRAIN CHECK (PLAN_CONVERSATION.md Finding 3): entityType flows in from
+    // parseKeywordSpot for every forward query, but until now was consulted ONLY by
+    // the commit-as-subject flip above — every other forward query scanned blind,
+    // regardless of what class the kind's edges actually target. A kind whose real
+    // observed target classes never include the asked entityType (nor its
+    // FINE_CLASS_SIBLING family partner) can never honestly answer it — "what
+    // modules does X have" via `defines`, whose real targets are only
+    // {Class,Attribute,Method,Function}, never Module — so this is an honest decline,
+    // not a blind filter that would silently produce a false empty. "Change" is the
+    // touches-family wildcard pseudo-type (no individual is ever classed "Change"),
+    // exempted the same way the reverse branch exempts it (see its own comment above).
+    if (entityType && entityType !== "Change") {
+      const wantClasses = classesForKinds(graph, fwdKinds);
+      const siblingClass = FINE_CLASS_SIBLING[entityType];
+      if (!wantClasses.has(entityType) && !(siblingClass && wantClasses.has(siblingClass))) {
+        return {
+          matches: [], objMatch, candidates, ambiguous, matchedVia,
+          forwardGrainMiss: true, wantClasses: [...wantClasses],
+          traversal: `${fwdKinds.join("+")} edges where subject = ${objMatch.label} (grain mismatch: this "${kind}" relation never targets a ${entityType})`,
+        };
+      }
+    }
     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 };
+    const deduped = subjIsFineSymbol ? uniqueById(targets) : targets;
+    // PER-TRAVERSAL GRAIN FILTER (same Finding 3 fix): once grain passes above (or
+    // entityType is null/"Change"), still keep only the matches of the ASKED class —
+    // mirrors the reverse branch's own subjects.filter + sibling-widen-on-empty
+    // fallback just below, so a forward answer never leaks a wrong-class match once
+    // an entityType was actually asked for ("which functions does saveStore call"
+    // must not render a Class as if it were a function).
+    let matches = deduped;
+    let filterNote = "";
+    if (entityType && entityType !== "Change") {
+      matches = deduped.filter((m) => m.class === entityType);
+      const siblingClass = FINE_CLASS_SIBLING[entityType];
+      if (!matches.length && siblingClass) {
+        const widened = deduped.filter((m) => m.class === siblingClass);
+        if (widened.length) {
+          matches = widened;
+          filterNote = `, widened to ${siblingClass} subjects (no ${entityType} recorded)`;
+        }
+      }
+    }
+    return { matches, objMatch, candidates, traversal: `${fwdKinds.join("+")} edges where subject = ${objMatch.label}${filterNote}`, ambiguous, matchedVia };
   }
 
   // reverse + transitive (PLAN_MECHANICAL_CHAT.md P1): the gate above guarantees kind is
@@ -3338,6 +3596,57 @@ function describeParse(p) {
   return `${ent}${p.kind} "${obj}"`;
 }
 
+/** PLAN_BREADTH_FIRST_NLU.md §Track 6 (operator directive) — the canonical
+ *  restatement of what a query was understood to mean, in BOTH forms the
+ *  operator asked for: an English gloss in tmct's own preferred phrasing
+ *  (`english`) and a compact, machine-parsable notation of the same
+ *  structured fact (`machine`) — a simple `shape(kind, args...)` call form,
+ *  not raw JSON, so it stays human-readable at a glance too. Every clause is
+ *  a plain template read off `parsed`'s own already-compiled fields, never
+ *  generated — the same discipline as `describeParse`/`render()`. Returns
+ *  `null` when there's nothing to canonicalize (`parsed` itself is null).
+ *  Scoped to the flat query shapes `traverse()`/`render()` operate on; a
+ *  compositional AST (`parsed.node`) gets an honest, coarser fallback —
+ *  full per-node-type canonicalization is real future work, not silently
+ *  faked here. */
+function canonicalOf(parsed) {
+  if (!parsed) return null;
+  if (parsed.ambiguousParse) {
+    return {
+      english: `ambiguous: ${parsed.candidates.map(describeParse).join(" — or — ")}`,
+      machine: `ambiguousParse(${parsed.candidates.map((c) => canonicalOf(c)?.machine).join(", ")})`,
+    };
+  }
+  if (parsed.node) {
+    // Compositional AST — coarse, honest fallback (see docblock above).
+    return { english: `a compositional query (${parsed.node})`, machine: `composite(${parsed.node})` };
+  }
+  const q = (s) => JSON.stringify(String(s ?? ""));
+  const args = [];
+  if (parsed.kind) args.push(parsed.kind);
+  if (parsed.entityType) args.push(`entityType=${parsed.entityType}`);
+  if (parsed.modifier && parsed.modifier !== "direct") args.push(`modifier=${parsed.modifier}`);
+  if (parsed.subject != null) args.push(`subject=${q(parsed.subject)}`);
+  if (parsed.object != null) args.push(q(parsed.object));
+  const machine = `${parsed.shape}(${args.join(", ")})`;
+  let english;
+  if (parsed.shape === "ask") {
+    english = `does "${parsed.subject}" ${verbFor(parsed.kind)} "${parsed.object}"?`;
+  } else if (parsed.shape === "meta") {
+    english = `what does "${parsed.object}" mean, in this graph's own vocabulary?`;
+  } else if (parsed.shape === "mentions") {
+    english = `where is "${parsed.object}" mentioned?`;
+  } else if (parsed.shape === "where") {
+    english = `where is "${parsed.object}" defined?`;
+  } else {
+    const ent = parsed.entityType ? nounFor(parsed.entityType, 2) + " that " : "";
+    english = parsed.shape === "forward"
+      ? `what "${parsed.object}" itself ${verbFor(parsed.kind)}`
+      : `${ent}${verbFor(parsed.kind)} "${parsed.object}"`;
+  }
+  return { english, machine };
+}
+
 /** Render a compiled query result into {content, miss, ambiguous, matches?, candidates?}.
  *  Every branch is a template, not generation — §5's grouping/pluralization/overflow rules.
  *  A tier-5 fuzzy object resolution is ANNOUNCED, not silent: the answer is prefixed
@@ -3357,6 +3666,21 @@ function renderCore(parsed, result) {
   }
   if (parsed.node) return renderComposite(parsed, result);
   if (parsed.ambiguousParse) {
+    // Each branch was actually resolved in traverse() above (never guessed at) —
+    // show every reading's real, effective answer, not just its one-line label, so
+    // the same input always reproduces the same full multi-reading answer (copy the
+    // same prompt back in and get the identical result, not a coin flip).
+    if (result.branches && result.branches.length) {
+      const options = result.branches
+        .map((b, i) => `${i + 1}) as ${describeParse(b.parsed)}: ${b.rendered.content}`)
+        .join("\n");
+      return {
+        content: `this could mean more than one thing:\n${options}\n(ask one of these directly, or try rephrasing more specifically, to get just that reading)`,
+        miss: false, ambiguous: true, candidates: parsed.candidates.map(describeParse),
+      };
+    }
+    // Fallback (no `result.branches` — e.g. a caller invoking render() directly
+    // with a hand-built result, bypassing traverse()): the old bare-label listing.
     const options = parsed.candidates.map((p, i) => `${i + 1}) ${describeParse(p)}`).join(" or ");
     return {
       content: `this could mean more than one thing: ${options} — try rephrasing more specifically.`,
@@ -3388,6 +3712,19 @@ function renderCore(parsed, result) {
       miss: true, ambiguous: false,
     };
   }
+  // forward-shape honest miss (PLAN_CONVERSATION.md Finding 3): the resolved SUBJECT
+  // is real, but the asked entityType can never appear among this kind's own real
+  // target classes at all — distinct from wrongGrainMiss above (which is about the
+  // resolved OBJECT term's class on the reverse side) and from the plain forward
+  // zero-hit template below (which is a genuinely empty edge scan, not a class the
+  // relation can never produce).
+  if (result.forwardGrainMiss) {
+    const wantNouns = result.wantClasses.map((c) => nounFor(c, 2));
+    return {
+      content: `${result.objMatch.label}'s "${verbFor(parsed.kind)}" relation in this index never produces ${nounFor(parsed.entityType, 2)} — only ${listJoin(wantNouns)}.`,
+      miss: true, ambiguous: false,
+    };
+  }
   if (parsed.shape === "meta") {
     if (!result.objMatch) {
       return {
@@ -3443,7 +3780,7 @@ function renderCore(parsed, result) {
     const what = /^(?:commit[:\s])?[0-9a-f]{7,40}$/i.test(objText) ? "commit"
       : (!objText.includes("/") && /^[\w$]+(\.[\w$]+)+$/.test(objText) ? "symbol" : fallback);
     return {
-      content: `no ${what} matching "${parsed.object}" found in the index.`,
+      content: `no ${what} matching "${parsed.object}" found in the index. ${touchesRephraseHint()}`,
       miss: true, ambiguous: false, candidates: [],
     };
   }
@@ -3457,9 +3794,16 @@ function renderCore(parsed, result) {
     const noun = pool.length && pool.every((i) => i.class === "Commit") ? "commit" : "module";
     const shown = pool.slice(0, OVERFLOW_CAP).map((i) => i.label);
     const extra = pool.length > OVERFLOW_CAP ? `, …and ${pool.length - OVERFLOW_CAP} more` : "";
+    const lead = `"${parsed.object}" matches more than one ${noun} ambiguously — did you mean ${listJoin(shown)}${extra}? Try one of those. If you're not sure, narrow it to one name.`;
+    // BREADTH-FIRST (PLAN_BREADTH_FIRST_NLU.md §1): strictly additive to `lead` —
+    // every currently-pinned assertion (test/chat-cefr-1.6.1-decision-log.test.mjs,
+    // chatbench/graded-pool.jsonl's am-tests-cover) is a substring check against
+    // `lead` alone, so appending each branch's real answer never breaks a pin.
+    const content = (result.branches && result.branches.length)
+      ? `${lead}\n${result.branches.map((b, i) => `${i + 1}) ${b.candidate.label}: ${b.rendered.content}`).join("\n")}`
+      : lead;
     return {
-      content: `"${parsed.object}" matches more than one ${noun} ambiguously — did you mean ${listJoin(shown)}${extra}? Try one of those.`,
-      miss: false, ambiguous: true, candidates: pool.map((i) => i.label),
+      content, miss: false, ambiguous: true, candidates: pool.map((i) => i.label),
     };
   }
   // where: the resolved entity's own location, cited off the site attribute.
@@ -3473,6 +3817,14 @@ function renderCore(parsed, result) {
     }
     const m = String(result.site || "").match(/^(.*):(\d+)(?:-(\d+))?$/);
     if (m) {
+      // "is defined in" stays UNVARIED here on purpose: chatbench/graded-pool-max.jsonl
+      // pins this exact substring as ground truth for "where is X defined" cases
+      // (g-a1-svo-7/12/18/22/40/43, g-a2-noise-svo-3/9/13/14/15 — 2 of which,
+      // g-a1-svo-12 and g-a2-noise-svo-13, are in the promoted always-run subset),
+      // and SKILL_BENCHMARK_CEFR_ENGLISH.md declares that pool append-only/never
+      // edited mid-arc. The other two "defined in" call sites (metaFallbackEntityAnswer
+      // and the composite exists-hit above) answer a DIFFERENT query shape ("what is a
+      // X" / "is there a X"), so they carry the variety instead.
       const lines = m[3] && m[3] !== m[2] ? `lines ${m[2]}-${m[3]}` : `line ${m[2]}`;
       return { content: `${symbolLabelOf(ind)} is defined in ${m[1]} at ${lines}.`, miss: false, ambiguous: false, matches: result.matches };
     }
@@ -3486,7 +3838,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.`, miss: true, ambiguous: false };
+      return { content: `no recorded commit touches ${subject} in this index. ${touchesRephraseHint()}`, miss: true, ambiguous: false };
     }
     const newest = result.matches[0];
     const date = (newest.attributes || []).find((a) => a.key === "date")?.value || "";
@@ -3499,7 +3851,7 @@ function renderCore(parsed, result) {
     const msg = (newest.attributes || []).find((a) => a.key === "message")?.value || "";
     const day = String(date).slice(0, 10);
     if (newest.id === result.objMatch.id) {
-      return { content: `commit ${newest.label} is dated ${day}${msg ? ` ("${msg}")` : ""}.`, miss: false, ambiguous: false, matches: result.matches };
+      return { content: `commit ${newest.label} ${pickPhrase("is-dated", newest.id, "is dated")} ${day}${msg ? ` ("${msg}")` : ""}.`, miss: false, ambiguous: false, matches: result.matches };
     }
     const more = result.matches.length - 1;
     return {
@@ -3515,7 +3867,7 @@ function renderCore(parsed, result) {
   if (result.whoLastShape) {
     const subject = result.objMatch.label;
     if (!result.matches.length) {
-      return { content: `no recorded commit touches ${subject} in this index.`, miss: true, ambiguous: false };
+      return { content: `no recorded commit touches ${subject} in this index. ${touchesRephraseHint()}`, miss: true, ambiguous: false };
     }
     const newest = result.matches[0];
     const author = (newest.attributes || []).find((a) => a.key === "author")?.value;
@@ -3600,7 +3952,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}.`,
+      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}. ${touchesRephraseHint()}`,
       miss: true, ambiguous: false,
     };
   }
@@ -4020,7 +4372,7 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
     return {
       content: rephraseHint(),
       tmct_ask: {
-        mechanical: true, parsed: null, matches: [], traversal: null,
+        mechanical: true, parsed: null, canonical: null, matches: [], traversal: null,
         miss: true, ambiguous: false, matchedVia: null, help: true, relaxed: null,
       },
     };
@@ -4030,7 +4382,8 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
   // rest of the pipeline (direct parse, relaxation, resolveObject) never has to know
   // this phrase existed — see substituteLastCommitPhrase's own doc above.
   query = substituteLastCommitPhrase(graph, query);
-  const direct = parseQuery(query, { nlp });
+  const directFull = parseQueryFull(query, { nlp });
+  const direct = directFull.parsed;
   // The relaxation cascade fires ONLY when the DIRECT parse would miss (no parse, a
   // compositional {node:"miss"}, or an unresolved named term) — a clean hit, an
   // ambiguous parse, an unresolved-pronoun miss, and a real-but-empty answer all keep
@@ -4045,14 +4398,63 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
   const rendered = render(parsed, result);
   // If relaxation materially rewrote the query and produced a real answer, note it
   // lightly (terse, honest) so the reader knows how the question was read.
-  const content = (relaxed && !rendered.miss && relaxed.to !== relaxed.from)
+  let content = (relaxed && !rendered.miss && relaxed.to !== relaxed.from)
     ? `read as "${relaxed.to}" — ${rendered.content}`
     : rendered.content;
+  // ALTERNATES ON HITS (breadth-first, PLAN_BREADTH_FIRST_NLU.md §3): a genuine
+  // distinct-class alternate reading from a different strategy (merge.mjs's
+  // `alternates`) used to be silently discarded on every call, including a real
+  // hit — surface it now, answered for real via the same traverse()+render()
+  // idiom the ambiguousParse/entity-tie branches already use. Scoped tightly to
+  // the ONE case this is unambiguously safe: the direct parse (untouched by
+  // relaxation, itself not already an ambiguous/miss result) produced a genuine
+  // answer. Relaxation rewrote the query, so `directFull`'s alternates no
+  // longer describe the question actually answered — skipped rather than shown
+  // stale.
+  //
+  // REAL-ANSWER-ONLY, never the bare "ask it that way" pointer (live-caught,
+  // 2026-07-11): a lower-precedence strategy's "alternate" is often pure noise,
+  // not a genuine second reading — e.g. keyword-spot misreading a stripped
+  // filler phrase as the query's SUBJECT ("hey man which modules import X" ->
+  // an "ask" parse with subject:"hey man"). That never resolves to a real graph
+  // entity, so `alternateLines`'s default "if you mean X then ask it that way"
+  // fallback would surface exactly the low-value dead-end nudge this whole plan
+  // exists to eliminate — worse, it's non-deterministic across equivalent
+  // phrasings (test/interpret.test.mjs's own noise-strip parity check caught
+  // this: "hey man which modules import X" must answer byte-identically to the
+  // clean phrasing, and a garbage alternate broke that). So: compute each
+  // alternate's real answer directly (not via alternateLines' fallback-prone
+  // default) and only ever append lines for alternates that resolved to
+  // something real — an alternate that can't be answered is dropped silently,
+  // never padded with an unhelpful pointer.
+  if (!relaxed && !rendered.miss && !rendered.ambiguous && directFull.alternates.length) {
+    const answered = directFull.alternates
+      .map((a) => {
+        const altResult = traverse(graph, a.parsed, { contextId, prev });
+        const altRendered = render(a.parsed, altResult);
+        return altRendered.miss ? null : { a, text: altRendered.content };
+      })
+      .filter(Boolean);
+    if (answered.length) {
+      const lines = alternateLines(answered.map((x) => x.a), {
+        answerFor: (a) => answered.find((x) => x.a === a)?.text || null,
+      });
+      content = `${content}\n${lines.join("\n")}`;
+    }
+  }
   return {
     content,
     tmct_ask: {
       mechanical: true,
       parsed: (parsed && !parsed.ambiguousParse) ? parsed : null,
+      // PLAN_BREADTH_FIRST_NLU.md §Track 6 (operator directive): the canonical
+      // restatement of what the request was understood to mean, ALWAYS present
+      // when anything parsed at all — not gated on ambiguity/miss the way the
+      // ambiguity-branch labels are. `english` is the human-readable gloss in
+      // tmct's own phrasing; `machine` is the same fact in a compact,
+      // machine-parsable notation (a plain `shape(kind, args...)` call form).
+      // Both are read straight off `parsed` — never generated.
+      canonical: canonicalOf(parsed),
       matches: (result.matches || []).map((m) => ({
         id: m.id, label: m.label, type: m.class, module: m.class ? moduleLabelOf(m) : undefined,
       })),