@polycode-projects/the-mechanical-code-talker 0.2.0 → 0.3.0

package/src/interpret/merge.mjs

@@ -0,0 +1,148 @@
+// interpret/merge.mjs — class-grouped merging of strategy results (ROADMAP item 8).
+// Grown from ask.mjs's original two-way merge ("one strategy hit -> use it; both
+// hit and agree -> use it; both hit and DISAGREE -> a genuine parse-level
+// ambiguity; neither hits -> the honest grammar miss") into a general rule over N
+// strategies and N result CLASSES:
+//
+//   · SAME-class candidates merge and rank — identical parses (sameParse) dedupe
+//     onto the highest-precedence strategy's candidate, exactly as the legacy
+//     merge returned "either" result on agreement; multiple DISTINCT parses
+//     surviving in the winning class are the legacy {ambiguousParse, candidates}
+//     surface, rendered by ask.mjs as "this could mean more than one thing: …".
+//   · DISTINCT-class groups produce the ambiguity SURROUND: the winning class
+//     answers, and each other class's best candidate is listed as an
+//     "if you mean X then …" line (alternateLines below) — the generalization of
+//     the engine's existing announced-correction shapes ("assuming you meant …").
+//
+// Winner selection is deterministic: the class holding the highest-confidence
+// candidate wins; a confidence tie goes to the earlier-registered strategy. The
+// two legacy strategies share one class ("graph-query"), so their merge reduces
+// exactly to the original behavior by construction.
+
+const DEFAULT_CONFIDENCE = 0.5;
+
+// "commit abc1234" and bare "abc1234" are the SAME term once resolveObject's
+// commit-sha tier strips the noun — the anchored strategy captures the noun inside
+// its object span while keyword-spot consumes it as the entity keyword, so without
+// this the two strategies would "disagree" over a word that names no different thing.
+const cmpTerm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ").replace(/^commit\s+(?=[0-9a-f]{7,40}$)/, "");
+
+/** Do two independently-produced parses mean the same graph query? Same
+ *  shape, same relation kind, and matching term(s) (both subject and object
+ *  for "ask"; just object otherwise) — anything less is a genuine
+ *  disagreement, not a near-miss to paper over. */
+export function sameParse(p, q) {
+  if (p.shape !== q.shape || p.kind !== q.kind) return false;
+  if (p.shape === "ask") return cmpTerm(p.subject) === cmpTerm(q.subject) && cmpTerm(p.object) === cmpTerm(q.object);
+  return cmpTerm(p.object) === cmpTerm(q.object);
+}
+
+/** Merge an array of strategy results ({strategyId, class, candidates:[{parsed,
+ *  confidence?, note?}]}), in strategy-registration (= precedence) order, into
+ *    { class, parsed, winner, alternates } | null
+ *  where `parsed` is the winning class's single merged parse OR the legacy
+ *  {ambiguousParse: true, candidates} tie, `winner` is the winning candidate
+ *  record, and `alternates` lists each OTHER class's best candidate (its parse
+ *  not sameParse-equal to a winning one — a cross-class agreement is agreement,
+ *  not an alternative reading). Null when nothing parsed anywhere. */
+// Candidate `via` values that mark an APPROXIMATE reading (a bounded-edit-
+// distance or lemma rewrite happened on the way to this parse). The engine's
+// tier discipline — "exact curated match always wins; lower tiers fire only on
+// a miss" — must survive the merge: an approximate candidate is DISCARDED
+// outright whenever any exact candidate parsed at all (rule a), and dedupe keys
+// on (parse, via) so an approximate twin can never collapse onto (or stand in
+// for) an exact parse and smuggle its "assuming you meant …" announcement into
+// an exact answer (rule b). A candidate with no `via` (or via:"exact") is exact
+// — the legacy strategies set none.
+const APPROXIMATE_VIAS = new Set(["fuzzy", "lemma", "spell"]);
+const isApproximate = (c) => APPROXIMATE_VIAS.has(c.via);
+
+export function mergeStrategyResults(results) {
+  const valid = (results || []).filter((r) => r && Array.isArray(r.candidates) && r.candidates.length);
+  if (!valid.length) return null;
+  // flatten candidates in precedence order (validity-checked)
+  let flat = [];
+  for (const r of valid) {
+    for (const c of r.candidates) {
+      if (!c || !c.parsed) continue;
+      flat.push({
+        parsed: c.parsed,
+        confidence: typeof c.confidence === "number" ? c.confidence : DEFAULT_CONFIDENCE,
+        note: c.note || null,
+        via: c.via || null,
+        strategyId: r.strategyId,
+        class: r.class,
+      });
+    }
+  }
+  // rule (a): any exact parse anywhere discards every approximate candidate —
+  // exact curated evidence always wins, so a fuzzy/lemma reading may only ever
+  // compete when NOTHING parsed exactly.
+  if (flat.some((c) => !isApproximate(c))) flat = flat.filter((c) => !isApproximate(c));
+  if (!flat.length) return null;
+  // group by class, preserving precedence order
+  const groups = new Map();
+  for (const c of flat) {
+    if (!groups.has(c.class)) groups.set(c.class, []);
+    groups.get(c.class).push(c);
+  }
+  // within-class dedupe: an identical parse collapses onto its first (highest-
+  // precedence) occurrence — the survivor keeps the strongest confidence and
+  // counts how many strategies agreed on it. Dedupe keys on (parse, via) — rule
+  // (b) — so distinct provenances never merge (moot after rule (a) globally
+  // splits exact from approximate, but held here as its own invariant).
+  const merged = [];
+  for (const [cls, cands] of groups) {
+    const distinct = [];
+    for (const c of cands) {
+      const dup = distinct.find((d) => sameParse(d.parsed, c.parsed) && d.via === c.via);
+      if (dup) {
+        dup.agreed += 1;
+        dup.confidence = Math.max(dup.confidence, c.confidence);
+        continue;
+      }
+      distinct.push({ ...c, agreed: 1 });
+    }
+    if (distinct.length) merged.push({ class: cls, candidates: distinct });
+  }
+  if (!merged.length) return null;
+  const top = (g) => Math.max(...g.candidates.map((c) => c.confidence));
+  let winner = merged[0];
+  for (const g of merged) if (top(g) > top(winner)) winner = g;
+  // >1 DISTINCT parse in the winning class -> the legacy parse-level ambiguity,
+  // surfaced honestly (never a silently-preferred guess) — byte-identical to the
+  // original two-strategy disagreement shape.
+  const parsed = winner.candidates.length === 1
+    ? winner.candidates[0].parsed
+    : { ambiguousParse: true, candidates: winner.candidates.map((c) => c.parsed) };
+  const alternates = merged
+    .filter((g) => g !== winner)
+    .map((g) => g.candidates[0])
+    .filter((a) => !winner.candidates.some((w) => sameParse(w.parsed, a.parsed)));
+  return { class: winner.class, parsed, winner: winner.candidates[0], alternates };
+}
+
+/** One-line, honest rephrasing of an alternate's parse — the default `describe`
+ *  for alternateLines. Template only, reads straight off the parsed fields (the
+ *  same discipline as ask.mjs's describeParse; callers with richer noun tables
+ *  may pass their own describe). */
+export function describeAlternate(p) {
+  if (!p) return "something else";
+  if (p.ambiguousParse) return "one of several readings";
+  const obj = p.object ?? p.subject ?? "?";
+  return `${p.kind} "${obj}"`;
+}
+
+/** The distinct-class ambiguity SURROUND: one "if you mean X then …" line per
+ *  alternate. `answerFor(alternate)` (optional) supplies the "then …" tail — a
+ *  caller holding the graph can answer each alternate reading outright; without
+ *  it the line honestly points at the rephrase instead of pretending to answer.
+ *  Message shape generalizes the engine's announced-correction precedents
+ *  ("assuming you meant …" / "this could mean more than one thing: …"). */
+export function alternateLines(alternates, { describe = describeAlternate, answerFor = null } = {}) {
+  return (alternates || []).map((a) => {
+    const meaning = a.note || describe(a.parsed);
+    const tail = (answerFor && answerFor(a)) || "ask it that way";
+    return `if you mean ${meaning} then ${tail}`;
+  });
+}

package/src/interpret/normalize.mjs

@@ -0,0 +1,117 @@
+// interpret/normalize.mjs — the input-normalization pass (ROADMAP item 10) and the
+// shared text-prep helpers every interpretation strategy reads. Extracted MOVE-only
+// from ask.mjs (item 13, chat/primitives split): the code here is the §3.5
+// normalization pipeline exactly as it ran inside ask.mjs — contractions expanded,
+// curated misspelling/wrong-word corrections applied, g-dropped words restored,
+// filler/politeness stripped, then the small closed set of rhetorical frames
+// rewritten to the canonical form of the SAME question. Pure, deterministic,
+// idempotent — both parsing strategies (and any future one) see identical text.
+//
+// This is the pipeline's documented PRE-PASS: interpret/pipeline.mjs runs
+// normalizeInput() once, hands every strategy the normalized text (plus the raw
+// text in ctx.raw), and records whether normalization changed the input.
+
+import {
+  CONTRACTIONS, MISSPELLINGS, WRONG_WORDS, G_DROP, FILLER_WORDS,
+  NEGATION_FRAMES, COMMIT_CONTENT_FRAMES,
+} from "../ask-vocab.mjs";
+
+export function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ---- §3.5 normalization — runs before EITHER parsing strategy sees the text ----
+
+/** contraction/informal-spelling table -> word-boundary regex, longest phrase
+ *  first (so "there's" doesn't get shadowed by a shorter overlapping entry). */
+const tableRe = (table) => new RegExp(
+  "\\b(" + Object.keys(table).sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
+  "gi",
+);
+const CONTRACTION_RE = tableRe(CONTRACTIONS);
+// misspelling/wrong-word CORRECTIONS (ask-vocab.mjs) — same mechanism, applied
+// after contractions: restore the intended spelling first, then map misused
+// words to their canonical schema term. Deterministic and curated, so they run
+// BEFORE either parse strategy and ahead of the bounded edit-distance fallback.
+// The trailing lookahead refuses to rewrite a word glued to a dotted extension:
+// WRONG_WORDS entries are real English words that plausibly NAME modules
+// ("revision.mjs", "property.py"), and a correction that corrupts an object
+// term would be a guess — the exact thing these tables exist to avoid.
+const correctionRe = (table) => new RegExp(
+  "\\b(" + Object.keys(table).sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b(?!\\.[a-z0-9])",
+  "gi",
+);
+const MISSPELLING_RE = correctionRe(MISSPELLINGS);
+const WRONG_WORD_RE = correctionRe(WRONG_WORDS);
+
+/** Free-text -> normalized free-text: contractions expanded, g-dropped words
+ *  restored, filler/politeness words stripped. Idempotent and pure — the same
+ *  input always normalizes the same way, so both parsing strategies see
+ *  identical text and their outputs are directly comparable. Deliberately
+ *  does NOT force lowercase: object/subject terms (module names like
+ *  "myFile", class names like "Base") are meaningfully cased, and every
+ *  substitution below already matches case-insensitively (`i`/`gi` flags) —
+ *  forcing the whole string to lowercase would silently corrupt every parsed
+ *  term's case instead. */
+export function normalizeQuery(text) {
+  let q = String(text || "");
+  q = q.replace(CONTRACTION_RE, (m) => CONTRACTIONS[m.toLowerCase()]);
+  q = q.replace(MISSPELLING_RE, (m) => MISSPELLINGS[m.toLowerCase()]);
+  q = q.replace(WRONG_WORD_RE, (m) => WRONG_WORDS[m.toLowerCase()]);
+  q = q.replace(G_DROP, "$1ing");
+  if (FILLER_WORDS.length) {
+    const fillerRe = new RegExp(
+      "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
+      "gi",
+    );
+    q = q.replace(fillerRe, " ");
+  }
+  // emphatic trailing punctuation (item 10): a run of terminal "?" collapses to
+  // one — the anchored templates consume exactly one optional trailing "?", so
+  // "…walk.mjs??" otherwise leaks a stray "?" into the captured object term (the
+  // keyword-spot strategy already strips the whole run, and the two strategies
+  // then "disagreed" over punctuation that was never part of the intent).
+  q = q.replace(/\?{2,}\s*$/, "?");
+  return q.replace(/\s+/g, " ").trim();
+}
+
+/** Recognized rhetorical/idiomatic constructions rewritten to the canonical form
+ *  of the SAME question before either parse strategy sees the text — a small
+ *  closed pattern set, not a general rewriter. Two families, tried in order:
+ *  COMMIT_CONTENT_FRAMES first ("what was in commit <sha>" -> "what did <sha>
+ *  touch"; sha-anchored, so it can't swallow a containment question), then the
+ *  §3.6 negative-rhetorical NEGATION_FRAMES. First matching frame across both wins
+ *  and rewriting stops; unmatched text passes through unchanged. */
+export function applyNegationFrames(text) {
+  for (const frame of [...COMMIT_CONTENT_FRAMES, ...NEGATION_FRAMES]) {
+    const m = text.match(frame.re);
+    if (m) return frame.to(m).replace(/\s+/g, " ").trim();
+  }
+  return text;
+}
+
+// ---- shared text-prep helpers (used by the strategies, the compositional
+// grammar, and ask.mjs's relaxation cascade alike) ----
+
+/** Question/auxiliary/article scaffolding the decomposition strategies skip when
+ *  splitting residual words into subject/object terms. Shared so every strategy
+ *  (and the cascade's structural-word set) reads the SAME list. */
+export const STOPWORDS = new Set([
+  "what", "who", "which", "where", "when", "why", "how",
+  "does", "do", "did", "is", "are", "was", "were", "the", "a", "an", "of", "to", "from", "at", "in", "on",
+  "there", "something", "anything", "nothing", "one", "any",
+  // temporal filler in when-questions ("when was X last touched") — a symbol
+  // literally named "last" would be the accepted residual cost, same trade as
+  // every other stopword.
+  "last",
+]);
+
+/** Split free text into words: trailing "?" run stripped, commas treated as
+ *  spaces, mid-word "." preserved (object terms are routinely dotted file/module
+ *  names — "a.py", "utils.mjs"). */
+export const splitWords = (text) => String(text).replace(/\?+\s*$/, "").replace(/,/g, " ").split(/\s+/).filter(Boolean);
+
+/** Flatten a phrase list into its lowercase constituent words — the standard way
+ *  a vocab table's multi-word phrases feed a word-level set (the cascade's
+ *  content-vocab union, the noise-strip KEEP set). */
+export const wordsOf = (arr) => arr.flatMap((p) => String(p).toLowerCase().split(" "));

package/src/interpret/pipeline.mjs

@@ -0,0 +1,112 @@
+// interpret/pipeline.mjs — the multi-strategy interpretation pipeline (ROADMAP
+// item 8): run the request through ALL the classes of thing it could be, parse it
+// with each class's own strategy, then merge same-class results and surround
+// distinct-class results with "if you mean X then …" (interpret/merge.mjs).
+//
+// A STRATEGY is a plain object:
+//   { id, class, run(text, ctx) -> {strategyId, class, candidates:[{parsed,
+//     confidence?, note?, via?}]} | null }
+// `via` marks an APPROXIMATE reading ("fuzzy"/"lemma"/"spell"): the merge
+// discards approximate candidates whenever anything parsed exactly (the tier
+// discipline — exact curated match always wins — held across strategies).
+// `run` may be sync or async (Promise-returning); a strategy that THROWS or
+// rejects is dropped for that request — one broken strategy never takes the
+// pipeline down. Strategies are registered in the STRATEGIES array below in
+// PRECEDENCE order (earlier wins same-class dedupe ties and confidence ties) —
+// a new strategy (e.g. the Phase-2 ACE grammar, interpret/strategies/ace.mjs)
+// joins by pushing an entry here, not by editing the pipeline.
+//
+// NORMALIZATION PRE-PASS (ROADMAP item 10): interpret() normalizes the input
+// once (normalizeInput below — the same §3.5 pipeline + rhetorical frames
+// ask.mjs always ran) and hands every strategy the normalized text; the raw
+// text rides along in ctx.raw, and the returned record says whether
+// normalization changed the input (`normalizationChanged`), so a repaired
+// spelling/contraction is on the record, never silent.
+
+import { normalizeQuery, applyNegationFrames } from "./normalize.mjs";
+import { grammarStrategy } from "./strategies/grammar.mjs";
+import { keywordSpotStrategy } from "./strategies/keywords.mjs";
+import { noiseStripStrategy } from "./strategies/noise-strip.mjs";
+import { mergeStrategyResults } from "./merge.mjs";
+// Optional Node-only wink adapter — same viewer-bundle boundary as ask.mjs: an
+// inlining bundle strips this import and the `typeof` read below degrades to
+// adapter-less parsing instead of throwing over an undeclared identifier.
+import { nlpAdapter } from "../ask-nlp.mjs";
+
+/** The registered strategies, in precedence order. grammar + keyword-spot are
+ *  the two legacy parsers (one shared class, "graph-query" — their merge is
+ *  byte-identical to the original two-way agree/disagree behavior); noise-strip
+ *  is the item-10 tolerant fallback (its own class; it only fires when the
+ *  anchored grammar missed the text as-given, so it can never displace an
+ *  existing template parse). interpret/strategies/ace.mjs (Phase 2) will
+ *  register here the same way. */
+export const STRATEGIES = [grammarStrategy, keywordSpotStrategy, noiseStripStrategy];
+
+/** The documented normalization pre-pass: whitespace-collapse + the §3.5
+ *  normalization pipeline + the closed rhetorical-frame rewrites, applied ONCE
+ *  before any strategy runs. Returns {raw, text, changed}. */
+export function normalizeInput(input) {
+  const raw = String(input || "").trim().replace(/\s+/g, " ");
+  const text = raw ? applyNegationFrames(normalizeQuery(raw)) : "";
+  return { raw, text, changed: text !== raw };
+}
+
+function defaultNlp() {
+  return typeof nlpAdapter === "function" ? nlpAdapter() : null;
+}
+
+/** Synchronous strategy run — the path ask.mjs's parseQuery routes through (its
+ *  callers are synchronous). Skips a strategy that returns a Promise (an async
+ *  strategy can only participate via interpret()); a throwing strategy is
+ *  dropped, never a crash. Returns the strategy results in precedence order. */
+export function runStrategiesSync(text, ctx = {}, strategies = STRATEGIES) {
+  const results = [];
+  for (const s of strategies) {
+    try {
+      const r = s.run(text, ctx);
+      if (r && typeof r.then !== "function") results.push(r);
+    } catch {
+      // dropped — one broken strategy never takes the request down
+    }
+  }
+  return results;
+}
+
+/** The pipeline entry point: normalize once, run every registered strategy over
+ *  the normalized text (Promise.all — strategies are independent), merge, and
+ *  return the full interpretation record:
+ *    { raw, normalized, normalizationChanged,
+ *      results,                    // every strategy's own result, precedence order
+ *      parsed, class,              // the merged winner (parsed may be the legacy
+ *                                  //   {ambiguousParse, candidates} tie), or null
+ *      alternates }                // distinct-class runners-up for the
+ *                                  //   "if you mean X then …" surround
+ *  `ctx.strategies` overrides the registry (tests, embedders); `ctx.nlp`
+ *  overrides the lemma/POS adapter exactly as ask()'s own option does. Pure
+ *  given (text, strategies, adapter) — no graph access here: resolving terms
+ *  against a graph stays ask.mjs's job downstream. */
+export async function interpret(text, ctx = {}) {
+  const strategies = ctx.strategies || STRATEGIES;
+  const { raw, text: normalized, changed } = normalizeInput(text);
+  const record = {
+    raw, normalized, normalizationChanged: changed,
+    results: [], parsed: null, class: null, alternates: [],
+  };
+  if (!normalized) return record;
+  const runCtx = { ...ctx, nlp: ctx.nlp === undefined ? defaultNlp() : ctx.nlp, raw };
+  const settled = await Promise.all(strategies.map(async (s) => {
+    try {
+      return (await s.run(normalized, runCtx)) || null;
+    } catch {
+      return null; // dropped — a rejecting/throwing strategy never crashes interpret
+    }
+  }));
+  record.results = settled.filter((r) => r && Array.isArray(r.candidates) && r.candidates.length);
+  const merged = mergeStrategyResults(record.results);
+  if (merged) {
+    record.parsed = merged.parsed;
+    record.class = merged.class;
+    record.alternates = merged.alternates;
+  }
+  return record;
+}

package/src/interpret/strategies/grammar.mjs

@@ -0,0 +1,137 @@
+// interpret/strategies/grammar.mjs — strategy 1: the anchored-template grammar,
+// extracted MOVE-only from ask.mjs (item 13). The original P0 grammar: the whole
+// (normalized) string must match one of TEMPLATES start-to-end, in fixed
+// precedence order; first fit wins, never ambiguous at the template level (a
+// question matching two shapes is a design smell we test against). Unweakened.
+
+import {
+  VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
+  META_MEANING_VERBS, WHERE_MARKERS, MENTION_MARKERS,
+} from "../../ask-vocab.mjs";
+import { escapeRegex } from "../normalize.mjs";
+
+const VERB_ALT = Object.keys(VERB_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
+const ENTITY_ALT = Object.keys(ENTITY_TO_TYPE).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
+const MODIFIER_ALT = Object.keys(MODIFIER_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
+const META_ALT = META_MEANING_VERBS.slice().sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
+
+const TEMPLATES = [
+  // T1 ASK: "does X import Y" / "is X a subclass of Y" -> Yes/No. Tried FIRST: it starts with
+  // does/is/do/did, which the reverse/forward templates below never match (those start with
+  // which/what), so precedence between T1 and the rest is structural, not a tie-break guess.
+  // "did" joins does/do for the past-tense commit forms ("did commit <sha> touch X").
+  {
+    name: "ask",
+    re: new RegExp(`^(?:does|do|did)\\s+(.+?)\\s+(${VERB_ALT})\\s+(.+?)\\??$`, "i"),
+    build: (m) => ({
+      shape: "ask", entityType: null, modifier: "direct",
+      kind: VERB_TO_KIND[m[2].toLowerCase()], subject: m[1].trim(), object: m[3].trim(),
+    }),
+  },
+  // T2 reverse: "which <entity> [<modifier>] <verb> <object>" — the operator's own example shape.
+  {
+    name: "reverse",
+    re: new RegExp(`^which\\s+(${ENTITY_ALT})\\s+(?:(${MODIFIER_ALT})\\s+)?(${VERB_ALT})\\s+(.+?)\\??$`, "i"),
+    build: (m) => ({
+      shape: "reverse",
+      entityType: ENTITY_TO_TYPE[m[1].toLowerCase()],
+      modifier: m[2] ? MODIFIER_TO_KIND[m[2].toLowerCase()] : "direct",
+      kind: VERB_TO_KIND[m[3].toLowerCase()],
+      object: m[4].trim(),
+    }),
+  },
+  // T3 forward: "what does <object> <verb>" — X is given, list its R-related things.
+  // "did" joins does/do for the past-tense commit forms ("what did commit <sha> touch").
+  {
+    name: "forward",
+    re: new RegExp(`^what\\s+(?:does|do|did)\\s+(.+?)\\s+(${VERB_ALT})\\??$`, "i"),
+    build: (m) => ({
+      shape: "forward", entityType: null, modifier: "direct",
+      kind: VERB_TO_KIND[m[2].toLowerCase()], object: m[1].trim(),
+    }),
+  },
+  // T4 meta: "what does <term> mean" — a question about the GRAPH'S OWN VOCABULARY
+  // (a SchemaClass/SchemaPredicate label, e.g. "cochange", or a raw prop token, e.g.
+  // "mgx:callsSymbol"), not a graph traversal over code edges. Tried after T3: T3 also
+  // starts "what does/do", but T3 only fires when the tail is a relation VERB_ALT
+  // phrase ("import"/"calls"/…), which "mean"/"means"/etc never are (disjoint tables —
+  // ask-vocab.mjs's file comment explains why they're kept separate), so the two never
+  // actually compete for the same input.
+  {
+    name: "meta-mean",
+    re: new RegExp(`^what\\s+(?:does|do|is|are)\\s+(.+?)\\s+(?:${META_ALT})\\??$`, "i"),
+    build: (m) => ({ shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: m[1].trim() }),
+  },
+  // T5 meta: "what is a/an <term>" — the OTHER worked phrasing ("what is a Commit").
+  // The indefinite article is REQUIRED (not optional): a bare "what is <anything>"
+  // would also swallow "what is the meaning of this codebase" (an existing, deliberately
+  // honest grammar-miss regression case — ask.test.mjs/ask-dual-strategy.test.mjs both
+  // assert it stays null), which never mentions "a"/"an" before its tail. Requiring the
+  // article keeps this template's reach to the one worked shape without reopening that.
+  {
+    name: "meta-whatis",
+    re: new RegExp(`^what\\s+(?:is|are)\\s+(?:an?)\\s+(.+?)\\??$`, "i"),
+    build: (m) => ({ shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: m[1].trim() }),
+  },
+  // T6 mention: "where is <term> mentioned/referenced" — the prose/mentions surface
+  // (2026-07-02 query families). Tried BEFORE T7: T7's trailing marker is optional,
+  // so without this ordering it would swallow the mention question and lose the
+  // marker that distinguishes "locate the definition" from "list the prose mentions".
+  {
+    name: "mention",
+    re: new RegExp(`^where\\s+(?:is|are|was|were)\\s+(.+?)\\s+(?:${MENTION_MARKERS.map(escapeRegex).join("|")})\\??$`, "i"),
+    build: (m) => ({ shape: "mentions", entityType: null, modifier: "direct", kind: "mentions", object: m[1].trim() }),
+  },
+  // T7 where: "where is <term> [defined|declared|located|implemented]" — definition
+  // location off the site attribute / defining module. "where" starts no other
+  // template, so precedence against T1-T5 is structural.
+  {
+    name: "where",
+    re: new RegExp(`^where\\s+(?:is|are|was|were)\\s+(.+?)(?:\\s+(?:${WHERE_MARKERS.map(escapeRegex).join("|")}))?\\??$`, "i"),
+    build: (m) => ({ shape: "where", entityType: null, modifier: "direct", kind: "where", object: m[1].trim() }),
+  },
+  // T8 when: "when did <term> [last] change/touched/updated…" — temporal shape over
+  // the touches edges + commit date attributes. The verb slot reuses VERB_ALT, but
+  // only the touches family carries dates to answer with, so build() rejects any
+  // other kind (returning null falls through — parseAnchored tolerates it) rather
+  // than pretending "when did X import Y" has a temporal answer.
+  {
+    name: "when",
+    re: new RegExp(`^when\\s+(?:did|does|do|was|were|is)\\s+(.+?)\\s+(?:last\\s+)?(${VERB_ALT})\\??$`, "i"),
+    build: (m) => (VERB_TO_KIND[m[2].toLowerCase()] === "touches"
+      ? { shape: "when", entityType: null, modifier: "direct", kind: "touches", object: m[1].trim() }
+      : null),
+  },
+];
+
+/** Strategy 1: the original P0 anchored grammar — the whole (normalized) string
+ *  must match one of TEMPLATES start-to-end. A build() may return null to reject
+ *  a structural match on curated grounds (T8's non-temporal verbs); the scan then
+ *  simply continues, exactly as if the regex had not matched. Pure. */
+export function parseAnchored(text) {
+  for (const t of TEMPLATES) {
+    const m = text.match(t.re);
+    if (m) {
+      const parsed = t.build(m);
+      if (parsed) return parsed;
+    }
+  }
+  return null;
+}
+
+/** Pipeline registration (interpret/pipeline.mjs): the anchored grammar as a
+ *  strategy. Class "graph-query" — shared with keyword-spot, so the two merge
+ *  (agree/disagree) exactly as the legacy two-way merge did. Confidence 0.9:
+ *  the highest of the registered strategies (a full-sentence template match is
+ *  the engine's most precise evidence), which also makes "graph-query" the
+ *  winning class whenever this strategy fires. */
+export const grammarStrategy = {
+  id: "grammar",
+  class: "graph-query",
+  run(text) {
+    const parsed = parseAnchored(text);
+    return parsed
+      ? { strategyId: "grammar", class: "graph-query", candidates: [{ parsed, confidence: 0.9 }] }
+      : null;
+  },
+};