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

package/src/interpret/merge.mjs

@@ -25,7 +25,18 @@ const DEFAULT_CONFIDENCE = 0.5;
 // 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}$)/, "");
+// A leading DETERMINER is the same kind of non-difference (0.8.2 feel wave): the
+// anchored grammar captures "the logger" while keyword-spot captures "logger", and
+// the resulting "ambiguity" asked the user to choose between identical readings.
+const cmpTerm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ")
+  .replace(/^(?:the|a|an)\s+/, "")
+  .replace(/^commit\s+(?=[0-9a-f]{7,40}$)/, "");
+
+// Leading-determiner probe over a parse's term slots — the dedupe below keeps the
+// det-LESS twin so downstream term resolution sees the bare object ("logger",
+// never "the logger").
+const LEADING_DET_RE = /^\s*(?:the|a|an)\s+/i;
+const detCount = (p) => [p?.subject, p?.object].filter((t) => LEADING_DET_RE.test(String(t || ""))).length;
 
 /** Do two independently-produced parses mean the same graph query? Same
  *  shape, same relation kind, and matching term(s) (both subject and object
@@ -99,6 +110,10 @@ export function mergeStrategyResults(results) {
       if (dup) {
         dup.agreed += 1;
         dup.confidence = Math.max(dup.confidence, c.confidence);
+        // determiner-insensitive collapse: when the agreeing parses differ only
+        // by a leading determiner, the det-less reading's parse survives (the
+        // representative's strategy/confidence standing is unchanged).
+        if (detCount(c.parsed) < detCount(dup.parsed)) dup.parsed = c.parsed;
         continue;
       }
       distinct.push({ ...c, agreed: 1 });

package/src/interpret/normalize.mjs

@@ -13,7 +13,7 @@
 
 import {
   CONTRACTIONS, MISSPELLINGS, WRONG_WORDS, G_DROP, FILLER_WORDS,
-  NEGATION_FRAMES, COMMIT_CONTENT_FRAMES,
+  NEGATION_FRAMES, COMMIT_CONTENT_FRAMES, VERB_TO_KIND,
 } from "../ask-vocab.mjs";
 
 export function escapeRegex(s) {
@@ -44,8 +44,92 @@ const correctionRe = (table) => new RegExp(
 const MISSPELLING_RE = correctionRe(MISSPELLINGS);
 const WRONG_WORD_RE = correctionRe(WRONG_WORDS);
 
+// ---- closed PREAMBLE frames (0.8.2 feel wave, PLAN_CHAT_FEEL item 2) — the
+// conversational wrapping a developer puts AROUND a real question: a greeting
+// lead-in with a delimiter ("hey there, quick question - …"), the modal
+// politeness wrapper ("can you … please"), and the show/give-me presentation
+// bridge. These are DELIMITER- and PHRASE-anchored, so they must run BEFORE the
+// FILLER-strip pass below: FILLER_WORDS strips "hey"/"can you" as bare words, so
+// after that pass the frames' anchors are gone while the punctuation debris
+// ("there, quick question -") still poisons the parse (the playtest wall).
+// Applied inside normalizeQuery — the one seam BOTH composition sites (ask.mjs
+// parseQuery and interpret/pipeline.mjs normalizeInput) run first — AFTER the
+// word-restoring correction tables (so "gimme"/"shwo me" are already "give me"/
+// "show me") and BEFORE the filler strip. Closed patterns, applied in order to a
+// small fixpoint; unmatched text passes through byte-unchanged. ----
+
+/** Any relation verb phrase from the shared vocabulary — the show/give-me
+ *  bridge's "this remainder is a real relation query" probe. */
+const RELATION_VERB_RE = new RegExp(
+  "\\b(?:" + Object.keys(VERB_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
+  "i",
+);
+/** A remainder that opens interrogatively is already a question — unwrap it. */
+const INTERROGATIVE_LEAD_RE = /^(?:which|what|who|whose|where|when|why|how)\b/i;
+/** A remainder that is a KIND listing ("show me [the] untested modules", "show
+ *  me the tests") already belongs to the compositional list/qualifier grammar,
+ *  whose LIST_TRIGGERS include "show me"/"give me" — leave the WHOLE text
+ *  untouched so that working path keeps it. Two shapes: a plural kind noun in
+ *  tail position, or a bare (det +) singular kind noun and nothing else. */
+const LISTING_TAIL_KINDS = new Set([
+  "modules", "files", "functions", "methods", "classes", "attributes", "fields",
+  "properties", "variables", "globals", "commits", "changes", "tests", "members",
+]);
+const BARE_KIND_RE = /^(?:all\s+|the\s+)?(?:module|file|function|method|class|attribute|field|property|variable|global|commit|change|test|member)\??$/i;
+const isListingRemainder = (rest) => {
+  if (BARE_KIND_RE.test(rest)) return true;
+  const words = rest.replace(/\?+\s*$/, "").trim().split(/\s+/);
+  return LISTING_TAIL_KINDS.has((words[words.length - 1] || "").toLowerCase());
+};
+
+/** Greeting lead-in with a delimiter (+ optional "quick question" bridge):
+ *  "hey there, quick question - <Q>" -> "<Q>". The delimiter and the non-empty
+ *  remainder are REQUIRED, so a bare "hey there" stays a greeting for chat's
+ *  conversational lane, and "hey tmct, …" (a vocative, no delimiter after the
+ *  greeting word) is left for the noise-strip tier that already owns it. */
+const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy)(?:\s+there)?\s*[,—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
+/** Modal politeness wrapper: "can/could/would/will you [please] <Q>[, please][?]"
+ *  -> "<Q>". FILLER_WORDS already ate "can you"/"please" as words; this frame
+ *  removes them as a WRAPPER so the ", please" comma never survives into the
+ *  parsed object term. The unwrapped remainder flows on through the ordinary
+ *  passes, so "can you tell me a joke" -> "tell me a joke" -> (FILLER) "a joke"
+ *  — byte-identical to what the bare form normalizes to (the hm-joke wall). */
+const MODAL_WRAPPER_RE = /^(?:can|could|would|will)\s+you\s+(?:please\s+)?(.+?)(?:[,\s]+please)?\??$/i;
+/** show/give-me presentation bridge: "show me [the] <thing>". Three-way:
+ *  a KIND-listing remainder is left untouched (the compositional list grammar
+ *  owns "show me untested modules"); a remainder carrying a relation verb or an
+ *  interrogative lead is a real query merely presented — unwrap to it ("show me
+ *  which modules import X" -> "which modules import X"); anything else is an
+ *  entity presentation — bridge to the describe surface ("show me the store
+ *  module" -> "describe store module"). */
+const SHOW_GIVE_ME_RE = /^(?:show|give)\s+me\s+(?:the\s+)?(.+?)\??$/i;
+
+/** Apply the closed preamble frames in order (greeting -> modal -> show/give-me),
+ *  repeated to a small fixpoint so stacked wrappers ("hey, can you show me X
+ *  please") peel fully. Pure and idempotent; unmatched text passes through. */
+export function applyPreambleFrames(text) {
+  let q = String(text || "");
+  for (let pass = 0; pass < 3; pass++) {
+    const before = q;
+    let m = q.match(GREETING_PREAMBLE_RE);
+    if (m) q = m[1].trim();
+    m = q.match(MODAL_WRAPPER_RE);
+    if (m) q = m[1].trim();
+    m = q.match(SHOW_GIVE_ME_RE);
+    if (m) {
+      const rest = m[1].trim();
+      if (!isListingRemainder(rest)) {
+        q = (RELATION_VERB_RE.test(rest) || INTERROGATIVE_LEAD_RE.test(rest)) ? rest : `describe ${rest}`;
+      }
+    }
+    if (q === before) break;
+  }
+  return q;
+}
+
 /** Free-text -> normalized free-text: contractions expanded, g-dropped words
- *  restored, filler/politeness words stripped. Idempotent and pure — the same
+ *  restored, closed preamble frames peeled, 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
@@ -59,6 +143,10 @@ export function normalizeQuery(text) {
   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");
+  // closed preamble frames (greeting lead-in, modal wrapper, show/give-me
+  // bridge) — AFTER the correction tables (a repaired "give me"/"show me" still
+  // feeds the bridge) but BEFORE the filler strip erases their anchor words.
+  q = applyPreambleFrames(q);
   if (FILLER_WORDS.length) {
     const fillerRe = new RegExp(
       "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
@@ -173,8 +261,25 @@ export const PHRASING_FRAMES = Object.freeze([
   // separate authorship edge; "touched" IS the authorship signal (the churn commits
   // carry the author), so these are true synonyms of "who touched X", not a new
   // capability. Anaphora rides through untouched ("who wrote it" → "who touched it").
-  { re: /^who\s+(?:wrote|authored)\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },
-  { re: /^who\s+is\s+the\s+authors?\s+of\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },
+  // SHA GUARD (0.8.2 feel wave): a COMMIT object is NOT a synonym — "who is the
+  // author of abc1234" rewritten to "who touched abc1234" dumps the commit's
+  // touch-SET instead of naming its author. The negative lookahead refuses the
+  // rewrite when the object is a bare (optionally "commit "-prefixed) 7-40 char
+  // hex sha, leaving the un-rewritten form for the author lane to consume;
+  // file/symbol objects (anything non-sha, e.g. "deadbeef.mjs") keep the rewrite.
+  { re: /^who\s+(?:wrote|authored)\s+(?:the\s+)?(?!(?:commit\s+)?[0-9a-f]{7,40}\??$)(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },
+  { re: /^who\s+is\s+the\s+authors?\s+of\s+(?:the\s+)?(?!(?:commit\s+)?[0-9a-f]{7,40}\??$)(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },
+
+  // HAS-TESTS → the coverage question the RELATIONS table answers. "does X have
+  // tests" parses "have" as a defines-verb (VERB_TO_KIND), producing the garbled
+  // "No — no defines edge found from X to <whatever resolves>" receipt; "is X
+  // tested" traverses tests edges from the WRONG side (subject = X). Both mean
+  // the coverage question "what tests X" — rewrite onto it. Closed to a
+  // tests/coverage object ("does X have methods/members" stays the members
+  // family) and refuses any "not" in the subject span, so the set-complement
+  // negations ("is X not tested") keep their own handler downstream.
+  { re: /^(?:does|do)\s+(?!.*\bnot\b)(.+?)\s+have\s+(?:any\s+)?(?:tests?|test\s+coverage|coverage)\??$/i, to: (m) => `what tests ${m[1]}` },
+  { re: /^(?:is|are)\s+(?!.*\bnot\b)(.+?)\s+tested\??$/i, to: (m) => `what tests ${m[1]}` },
 
   // NEEDS-TESTS → the untested-module survey. "what needs tests" / "what needs
   // testing" is the plainest way to ask which modules are uncovered, and it hit the

package/src/memory/core.mjs

@@ -78,7 +78,7 @@ const MEMORY_VOCABULARY = [
   { prop: DERIVED_FROM_PROP, predicate: "derivedFrom", note: "umbrella: a Fact derived from a Source (or another Fact). ext ref prov:wasDerivedFrom (UNVERIFIED-pending-web-check)" },
   { prop: STATED_BY_PROP, predicate: "statedBy", note: "subPropertyOf derivedFrom: a Source directly asserts this Fact (one edge per independent source — replaces the factProvenance union)" },
   { prop: CANONICALISED_FROM_PROP, predicate: "canonicalisedFrom", note: "subPropertyOf derivedFrom: a canonical Fact cleaned from a raw Block/Source, never replacing it" },
-  { prop: "mgx:sourceType", note: "a Source's kind: operator | provider | corpus | web | entailed (the trust-prior key)" },
+  { prop: "mgx:sourceType", note: "a Source's kind: operator | teach | provider | corpus | web | entailed (the trust-prior key)" },
   { prop: "mgx:sourceUrl", note: "a web Source's URL" },
   { prop: "mgx:sourceRule", note: "an entailed Source's rule id" },
   { prop: TRUST_SCORE_PROP, note: "materialised trust cache in [0,1] — pure function of a fact's Sources + createdAt (memory/trust.mjs); invalidated when a statedBy edge is added" },
@@ -171,6 +171,7 @@ function setAttr(ind, prop, key, value) {
 function sourceIdFor(desc) {
   switch (desc?.kind) {
     case "operator": return { id: OPERATOR_SOURCE_ID, type: "operator" };
+    case "teach": return { id: "src:teach-chat", type: "teach" };
     case "provider": return { id: `src:provider:${desc.name}`, type: "provider" };
     case "corpus": return { id: `src:corpus:${desc.name}`, type: "corpus" };
     case "web": return { id: `src:learned:web:${fnv1aHex(String(desc.url || ""))}`, type: "web", url: String(desc.url || "") };
@@ -209,6 +210,7 @@ function upsertSource(payload, desc, createdAtCandidate) {
  * through. The tag formats are exactly what the writers produce:
  *   corpus:conceptnet /r/IsA   → { kind:"corpus",   name:"conceptnet" }
  *   ace:chat:<session>@<ts>    → { kind:"operator",  createdAt:<ts> }
+ *   teach:chat:<session>@<ts>  → { kind:"teach",     createdAt:<ts> }
  *   web:<url> | url:<url>      → { kind:"web",       url:<url> }
  *   entailed:<rule>            → { kind:"entailed",  rule:<rule> }
  * chat:/session: refs map to the operator; an unknown tag → null (no Source).
@@ -222,6 +224,11 @@ export function provenanceTagToSource(tag) {
     const at = head.indexOf("@");
     return { kind: "operator", createdAt: at >= 0 ? head.slice(at + 1) : "" };
   }
+  if (head.startsWith("teach:")) {
+    // the chat teach lane's natural frames — chat.mjs's teachProvenanceTag
+    const at = head.indexOf("@");
+    return { kind: "teach", createdAt: at >= 0 ? head.slice(at + 1) : "" };
+  }
   if (head.startsWith("web:")) return { kind: "web", url: head.slice("web:".length) };
   if (head.startsWith("url:")) return { kind: "web", url: head.slice("url:".length) };
   if (head.startsWith("entailed:")) return { kind: "entailed", rule: head.slice("entailed:".length) };

package/src/memory/trust.mjs

@@ -4,7 +4,7 @@
 // Trust is a COMPUTED attribute of a Fact — never hand-set — a pure function of
 // its Source edges, those Sources' types, and its mgx:createdAt. Three inputs
 // combine:
-//   - a Source-TYPE PRIOR (operator > provider > corpus > web > entailed);
+//   - a Source-TYPE PRIOR (operator > teach > provider > corpus > web > entailed);
 //   - CORROBORATION over the fact's distinct Sources by noisy-OR
 //     (1 − Π(1 − wᵢ), capped at 1) — two independent web sources (0.4) reach
 //     0.64, a lone operator fact is already 1.0;
@@ -26,11 +26,15 @@
 export const TRUST_SCORE_PROP = "mgx:trustScore";
 export const TRUST_INPUTS_PROP = "mgx:trustInputs";
 
-/** Source-type priors — the ordering operator > provider-graph > curated-corpus
- *  > web > unverified-entailment. The entailed value is a FLOOR before premise
- *  adjustment (see the entailed hook below). */
+/** Source-type priors — the ordering operator > teach > provider-graph >
+ *  curated-corpus > web > unverified-entailment. `teach` is the chat teach
+ *  lane's natural-frame writes ("remember that …", "<Name> owns <X>") — still
+ *  operator speech, but through a looser recognizer than the ACE-parsed
+ *  operator assert, so it sits just below the operator prior. The entailed
+ *  value is a FLOOR before premise adjustment (see the entailed hook below). */
 export const SOURCE_PRIOR = Object.freeze({
   operator: 1.0,
+  teach: 0.95,
   provider: 0.9,
   corpus: 0.7,
   web: 0.4,

package/src/router/call-validator.mjs

@@ -0,0 +1,45 @@
+// src/router/call-validator.mjs — pure registry validators shared by the
+// product router (resolver / guardrail / goal-reasoner) + the bench grader
+// (agentbench/grade.mjs re-exports these). Depends ONLY on registry.mjs — no
+// bench code — so the product←bench dependency stays inverted: the bench
+// imports the product, never the other way round. No I/O, no Date.now, no LLM.
+
+import { isCapability, argKeysOf, requiredArgsOf, preconditionsOf, PRECOND } from "./registry.mjs";
+
+/** Every way a single produced call can be a HALLUCINATION — the one thing a
+ *  deterministic router must never do. Returns [] for a clean call, else a list
+ *  of { reason, detail }:
+ *    - "undeclared"  — name is not in the case's declared toolset
+ *    - "unknown-tool"— name is not a registry capability at all
+ *    - "unknown-arg" — an input key the capability does not accept
+ *    - "missing-arg" — a required arg absent (and no any-present precond covers it)
+ *  Any nonempty result = AUTOMATIC FAIL for the case. */
+export function hallucinationsIn(call, declaredTools) {
+  const problems = [];
+  const name = call?.name;
+  if (typeof name !== "string" || !name) return [{ reason: "unknown-tool", detail: "no tool name" }];
+  if (!isCapability(name)) return [{ reason: "unknown-tool", detail: name }];
+  if (!declaredTools.includes(name)) problems.push({ reason: "undeclared", detail: name });
+  const input = call.input && typeof call.input === "object" ? call.input : {};
+  const accepted = argKeysOf(name);
+  for (const key of Object.keys(input)) {
+    if (!accepted.has(key)) problems.push({ reason: "unknown-arg", detail: `${name}.${key}` });
+  }
+  // required-arg presence, honoring an any-present disjunction (search: query|kind)
+  const anyGroups = preconditionsOf(name)
+    .filter((p) => p.pred === PRECOND.anyPresent)
+    .map((p) => p.params);
+  const present = (k) => input[k] !== undefined && input[k] !== null && String(input[k]).trim() !== "";
+  for (const req of requiredArgsOf(name)) {
+    if (!present(req)) problems.push({ reason: "missing-arg", detail: `${name}.${req}` });
+  }
+  for (const group of anyGroups) {
+    if (!group.some(present)) problems.push({ reason: "missing-arg", detail: `${name} needs one of ${group.join("|")}` });
+  }
+  return problems;
+}
+
+/** True iff a produced call is dispatchable-shaped (no hallucination). */
+export function isCallWellFormed(call, declaredTools) {
+  return hallucinationsIn(call, declaredTools).length === 0;
+}

package/src/router/goal-reasoner.mjs

@@ -43,8 +43,8 @@
 
 import { backwardChain, extractEntity } from "./resolver.mjs";
 import { capabilityByName, effectsOf } from "./registry.mjs";
-import { hallucinationsIn } from "../../agentbench/grade.mjs";
-import { intersect } from "../../agentbench/results.mjs";
+import { hallucinationsIn } from "./call-validator.mjs";
+import { intersect } from "./set-algebra.mjs";
 
 // Hard OUTER-tick budget — the meta-loop runs at most this many ticks, then
 // REFUSES (escalate). Independent of BDI convergence and of the monotone
@@ -55,8 +55,23 @@ export const MAX_TICKS = 16;
 // ---- the DECLARED goal model (data, mirroring registry.mjs's STRIPS operators)
 // A goal-rule is a maintenance INVARIANT over the graph, plus the epistemic
 // sub-goals whose facts decide whether it is violated and the DECLARED priority
-// that breaks ties in first-step arbitration. Growing this set is the "long-chain
+// that settles ties in first-step arbitration. Growing this set is the "long-chain
 // deduction library" the RFC flags — same discipline as syllogise's rule set.
+//
+// Each rule declares (pure frozen data, no code):
+//   focusClass — the entity class the scoped reading binds its focus to.
+//   modes      — which deduced scopes the rule covers ("scoped" = a bound focus;
+//                "global" = whole-graph keystone arbitration). A rule whose
+//                sub-goals are all entity-scoped has no global reading.
+//   subGoals   — the epistemic facts to gather, IN DECLARED ORDER (each
+//                backward-chains to a capability, exactly like an NL intent).
+//   compose    — the declarative fold of the gathered facts into the scoped
+//                answer: intersect(a, b), each side naming a gathered topic,
+//                optionally bound to the focus (`of:"focus"`), optionally with
+//                the focus itself unioned in (`withFocus` — the change footprint).
+//   priorityTopic / coverageTopic — the global keystone arbitration keys
+//                (argmax |priority(m)| over the coverage-violating set).
+//   achieves   — the meta-goal topic the composed answer achieves.
 export const GOAL_RULES = Object.freeze([
   Object.freeze({
     id: "coverage-invariant",
@@ -65,8 +80,8 @@ export const GOAL_RULES = Object.freeze([
     // closure) MUST have direct test coverage. A Module that is untested AND
     // impactful VIOLATES it — an active goal to close the coverage gap.
     invariant: "an impactful module must be tested",
-    // the epistemic facts a plan must gather to evaluate the invariant (each
-    // backward-chains to a capability, exactly like the resolver's NL intents).
+    focusClass: "Module",
+    modes: Object.freeze(["scoped", "global"]),
     subGoals: Object.freeze(["impact", "untested"]),
     // the DECLARED priority key for first-step arbitration: a violation's
     // priority is its blast radius |impact(module)| — the wider the reach, the
@@ -74,9 +89,41 @@ export const GOAL_RULES = Object.freeze([
     priorityTopic: "impact",
     // the coverage predicate the invariant screens on.
     coverageTopic: "untested",
+    // scoped fold: untested ∩ ({focus} ∪ impact(focus)) — the change footprint.
+    compose: Object.freeze({
+      op: "intersect",
+      a: Object.freeze({ topic: "untested" }),
+      b: Object.freeze({ topic: "impact", of: "focus", withFocus: true }),
+      names: "the change's untested footprint",
+      empty: "no coverage gap",
+    }),
     // the meta-goal topic the composed answer achieves (backward-chained below).
     achieves: "coverage-gap",
   }),
+  Object.freeze({
+    id: "cochange-risk-invariant",
+    kind: "maintenance",
+    // INVARIANT: a module CHANGE-COUPLED with the focus (they historically land
+    // in the same commits) MUST have direct test coverage. A coupled module that
+    // is untested VIOLATES it — an active goal over the focus's coupling set.
+    invariant: "a module change-coupled with the focus must be tested",
+    focusClass: "Module",
+    // scoped ONLY: both sub-goals are read relative to a bound focus; there is
+    // no whole-graph keystone reading declared for change-coupling.
+    modes: Object.freeze(["scoped"]),
+    subGoals: Object.freeze(["cochanges", "untested"]),
+    priorityTopic: "cochanges",
+    coverageTopic: "untested",
+    // scoped fold: cochanges(focus) ∩ untested — the coupled-but-untested set.
+    compose: Object.freeze({
+      op: "intersect",
+      a: Object.freeze({ topic: "cochanges", of: "focus" }),
+      b: Object.freeze({ topic: "untested" }),
+      names: "the change-coupled untested set",
+      empty: "every change-coupled module is tested",
+    }),
+    achieves: "cochange-risk",
+  }),
 ]);
 
 /** Backward-chain a meta-goal topic to the declared goal-rule that achieves it —
@@ -85,6 +132,28 @@ export function backwardChainGoal(topic) {
   return GOAL_RULES.find((r) => r.achieves === topic) || null;
 }
 
+/** THE RULE-SELECTION DEDUCTION (replaces the old single-rule hard-wiring): a
+ *  declared goal-rule APPLIES to a request iff
+ *    (1) every one of its epistemic sub-goal topics backward-chains to a
+ *        capability IN the declared toolset (the closed-world groundability
+ *        screen — the meta-level twin of "never select an out-of-set call"),
+ *    (2) the deduced mode is one of the rule's declared modes, and
+ *    (3) a scoped reading's bound focus is of the rule's declared focusClass.
+ *  Pure over the goal model + registry: nothing here reads the request string.
+ *  The caller REFUSES on zero matches (the open-world goal-generation seam) and
+ *  on more than one (an ambiguous meta-goal — arbitration between meta-goals is
+ *  undeclared, so guessing one would be an invented goal). */
+export function applicableRules(declaredTools, focus, mode) {
+  const declared = Array.isArray(declaredTools) ? declaredTools : [];
+  return GOAL_RULES.filter((rule) =>
+    rule.modes.includes(mode)
+    && (mode !== "scoped" || (focus != null && focus.class === rule.focusClass))
+    && rule.subGoals.every((topic) => {
+      const cap = backwardChain(topic);
+      return Boolean(cap && declared.includes(cap.name));
+    }));
+}
+
 const refuse = (why, driver) => ({ calls: [], refused: true, terminated: true, proof: [], composed: null, driver, why });
 
 /** THREATS lifted to the meta-level: any pending intention whose needed condition
@@ -130,11 +199,12 @@ async function groundSubGoal(topic, entityLabel, tools, ctx) {
 }
 
 /** BDI DROP CONDITIONS (Rao & Georgeff): an intention persists until it is
- *  achieved / impossible / its goal lapses. Returns the reason string, or null
- *  to KEEP committing to it. Pure — unit-testable in isolation. */
-export function dropCondition(intention, observed, mode, focus) {
+ *  achieved / impossible / its goal lapses. `focusClass` is the SELECTED rule's
+ *  declared focus class (never a literal here — the rule is the authority).
+ *  Returns the reason string, or null to KEEP committing to it. Pure. */
+export function dropCondition(intention, observed, mode, focus, focusClass) {
   if (observed.has(intention.key)) return "achieved";       // fact now gathered
-  if (mode === "scoped" && (!focus || focus.class !== "Module")) return "lapsed"; // focus moved
+  if (mode === "scoped" && (!focus || focus.class !== focusClass)) return "lapsed"; // focus moved
   return null;                                               // else keep the commitment
 }
 
@@ -148,21 +218,32 @@ export function dropCondition(intention, observed, mode, focus) {
  *  ctx: { dispatch(name,input)->{ok,result}, resolve(term)->{match,ambiguous} }. */
 export async function goalReason(request, tools, ctx, { driver = "goal-0.8.1" } = {}) {
   const declared = Array.isArray(tools) ? tools : [];
-  const rule = backwardChainGoal("coverage-gap");
-  if (!rule) return refuse("no declared goal-rule achieves the meta-goal — escalate", driver);
 
-  // STEP 1 — deduce the goal scope from the DECLARED model + a bound focus.
+  // STEP 1 — deduce the goal scope from the DECLARED model + a bound focus,
+  // then SELECT the goal-rule by pure applicability (no request keyword ever):
+  // a bound focus reads scoped, no focus reads global (keystone arbitration).
   const focus = focusOf(request, ctx);
-  let mode;
-  if (focus && focus.class === "Module") mode = "scoped"; // assess the focus module's change footprint
-  else if (focus) mode = "escalate";                      // a non-Module focus: no declared rule covers it
-  else mode = "global";                                   // no focus => rank the whole codebase (keystone)
+  const mode = focus ? "scoped" : "global";
 
-  // The open-world goal-generation seam, named honestly: a resolved focus the
-  // declared goal model does not cover is REFUSED, never given an invented goal.
-  if (mode === "escalate") {
-    return refuse(`open-world: no declared goal-rule covers a ${focus.class} focus (the coverage-invariant is Module-scoped) — escalate`, driver);
+  // The open-world goal-generation seam, named honestly: a resolved focus whose
+  // class NO declared goal-rule scopes is REFUSED, never given an invented goal.
+  if (focus && !GOAL_RULES.some((r) => r.focusClass === focus.class)) {
+    const covered = [...new Set(GOAL_RULES.map((r) => r.focusClass))].join("/");
+    return refuse(`open-world: no declared goal-rule covers a ${focus.class} focus (the declared goal-rules are ${covered}-scoped) — escalate`, driver);
+  }
+
+  // Rule selection is a DEDUCTION over the goal model + the declared toolset:
+  // 0 applicable rules => the same open-world seam (nothing declared grounds the
+  // request's scope in this toolset); >1 => an AMBIGUOUS meta-goal (arbitration
+  // between meta-goals is undeclared) — both are honest refusals, never a guess.
+  const applicable = applicableRules(declared, focus, mode);
+  if (!applicable.length) {
+    return refuse(`open-world: no declared goal-rule is applicable in ${mode} mode (each needs a sub-goal capability outside the declared toolset, or a scope it does not declare) — escalate`, driver);
+  }
+  if (applicable.length > 1) {
+    return refuse(`ambiguous meta-goal: ${applicable.length} declared goal-rules apply (${applicable.map((r) => r.id).join(", ")}) — meta-goal arbitration is undeclared, refuse rather than guess — escalate`, driver);
   }
+  const rule = applicable[0];
 
   // the glass-box WHY, citing the declared goal-rule by backward-chain (the C2
   // twin of resolver.mjs's "backward-chain => <capability>" provenance).
@@ -175,15 +256,22 @@ export async function goalReason(request, tools, ctx, { driver = "goal-0.8.1" }
   const calls = [];
   const observed = new Map();     // intention.key -> gathered result set
 
-  // STEP 2/3 — the pending INTENTIONS (epistemic sub-goals), each carrying its
-  // declared execution order (arbitration is least-commitment: min order first,
-  // the keystone selection over the gathered facts happens at compose).
-  //   scoped: gather impact(focus) then the untested coverage-scan.
-  //   global: gather untested first, then EXPAND to impact-of-each (GDA replan).
-  const pending = mode === "scoped"
-    ? [{ topic: "impact", of: focus.label, key: `impact:${focus.label}`, order: 0 },
-       { topic: "untested", of: null, key: "untested", order: 1 }]
-    : [{ topic: "untested", of: null, key: "untested", order: 0 }];
+  // STEP 2/3 — the pending INTENTIONS: the rule's epistemic sub-goals IN
+  // DECLARED ORDER (arbitration is least-commitment: min order first, the
+  // keystone selection over the gathered facts happens at compose). A topic
+  // binds the focus iff its capability declares a REQUIRED parameter (read from
+  // the registry, never special-cased by topic name); in global mode there is
+  // no focus to bind, so entity-scoped topics are deferred to the GDA expansion
+  // (gather the coverage scan first, then EXPAND to priority-of-each violator).
+  const bindsEntity = (topic) => {
+    const cap = backwardChain(topic);
+    return Boolean(cap && cap.parameters.some((p) => p.required));
+  };
+  const pending = rule.subGoals
+    .filter((topic) => mode === "scoped" || !bindsEntity(topic))
+    .map((topic, i) => (mode === "scoped" && bindsEntity(topic)
+      ? { topic, of: focus.label, key: `${topic}:${focus.label}`, order: i }
+      : { topic, of: null, key: topic, order: i }));
 
   let committed = null;   // the persisted BDI intention (not re-derived each tick)
   let expanded = false;   // one-shot guard: the single bounded GDA expansion
@@ -197,7 +285,7 @@ export async function goalReason(request, tools, ctx, { driver = "goal-0.8.1" }
     // (3b) PERSISTENCE — keep the committed intention unless a BDI drop condition
     //      fires; only THEN re-arbitrate. This is the "commitment, not recomputed
     //      preference" that stops the loop thrashing.
-    if (committed && dropCondition(committed, observed, mode, focus)) committed = null;
+    if (committed && dropCondition(committed, observed, mode, focus, rule.focusClass)) committed = null;
     if (!committed || !pending.includes(committed)) {
       // (3a) FIRST-STEP ARBITRATION — least-commitment: the lowest declared order
       //      among pending. Threat-aware: skip a step that would clobber another
@@ -220,17 +308,17 @@ export async function goalReason(request, tools, ctx, { driver = "goal-0.8.1" }
     pending.splice(pending.indexOf(committed), 1);
     committed = null;
 
-    // GDA EXPANSION (monitor -> replan), ONCE: on observing the untested set in
-    // global mode, expand to the priority sub-goal (impact) for each violating
-    // module, so arbitration can rank them. Bounded by |untested| (finite) and
-    // fired at most once (the `expanded` guard) => the pending set still
-    // converges.
+    // GDA EXPANSION (monitor -> replan), ONCE: on observing the coverage set in
+    // global mode (guarded on the rule DECLARING a global reading), expand to
+    // the priority sub-goal for each violating module, so arbitration can rank
+    // them. Bounded by the finite coverage set and fired at most once (the
+    // `expanded` guard) => the pending set still converges.
     let expandedThisTick = false;
-    if (mode === "global" && achievedTopic === rule.coverageTopic && !expanded) {
+    if (mode === "global" && rule.modes.includes("global") && achievedTopic === rule.coverageTopic && !expanded) {
       expanded = true;
       expandedThisTick = true;
-      const untested = observed.get("untested") || [];
-      untested.forEach((m, i) => pending.push({ topic: rule.priorityTopic, of: m, key: `impact:${m}`, order: 100 + i }));
+      const violating = observed.get(rule.coverageTopic) || [];
+      violating.forEach((m, i) => pending.push({ topic: rule.priorityTopic, of: m, key: `${rule.priorityTopic}:${m}`, order: 100 + i }));
     }
 
     // the invariant, enforced mechanically: the pending set shrank by one this
@@ -245,21 +333,31 @@ export async function goalReason(request, tools, ctx, { driver = "goal-0.8.1" }
   // facts (all INSIDE the driver's timeout guard; no unbounded post-work).
   let composed;
   if (mode === "scoped") {
-    // the coverage-gap of the focus: the untested modules in its change
-    // FOOTPRINT ({focus} ∪ its impact closure) — a real composed set (∅ = no gap).
-    const footprint = [focus.label, ...(observed.get(`impact:${focus.label}`) || [])];
-    composed = intersect(observed.get("untested") || [], footprint);
-    why.push(`compose: untested ∩ ({${focus.label}} ∪ impact) = the change's untested footprint (${composed.length ? composed.join(", ") : "∅ — no coverage gap"})`);
+    // interpret the rule's DECLARATIVE compose spec: intersect two gathered
+    // sides, each a topic (optionally focus-bound, optionally with the focus
+    // itself unioned in — the change-footprint shape). ∅ is a real answer.
+    const sideSet = (side) => {
+      const key = side.of === "focus" ? `${side.topic}:${focus.label}` : side.topic;
+      const set = observed.get(key) || [];
+      return side.withFocus ? [focus.label, ...set] : set;
+    };
+    const sideDesc = (side) => (side.withFocus
+      ? `({${focus.label}} ∪ ${side.topic})`
+      : side.of === "focus" ? `${side.topic}(${focus.label})` : side.topic);
+    const spec = rule.compose;
+    composed = intersect(sideSet(spec.a), sideSet(spec.b));
+    why.push(`compose: ${sideDesc(spec.a)} ∩ ${sideDesc(spec.b)} = ${spec.names} (${composed.length ? composed.join(", ") : `∅ — ${spec.empty}`})`);
   } else {
-    // KEYSTONE arbitration: among the coverage violations (untested modules), pick
-    // the highest declared priority — the widest blast radius |impact(m)| — tie
-    // broken by label order. The single most-worth-covering module.
-    const untested = observed.get("untested") || [];
-    const ranked = untested
-      .map((m) => ({ m, weight: (observed.get(`impact:${m}`) || []).length }))
+    // KEYSTONE arbitration: among the coverage violations, pick the highest
+    // declared priority — the widest |priority(m)| set — tie broken by label
+    // order. The single most-worth-covering module. Only a rule declaring a
+    // global mode ever reaches here (applicability screened on rule.modes).
+    const violating = observed.get(rule.coverageTopic) || [];
+    const ranked = violating
+      .map((m) => ({ m, weight: (observed.get(`${rule.priorityTopic}:${m}`) || []).length }))
       .sort((a, b) => b.weight - a.weight || String(a.m).localeCompare(String(b.m)));
     composed = ranked.length ? [ranked[0].m] : [];
-    why.push(`keystone: argmax |impact| over ${untested.length} untested module(s) => ${composed.length ? `${composed[0]} (weight ${ranked[0].weight})` : "∅"}`);
+    why.push(`keystone: argmax |${rule.priorityTopic}| over ${violating.length} ${rule.coverageTopic} module(s) => ${composed.length ? `${composed[0]} (weight ${ranked[0].weight})` : "∅"}`);
   }
 
   return { calls, refused: false, terminated: true, proof, why, composed, driver, observed: `goal(${mode}): ${calls.map((c) => c.name).join(" -> ")}` };

package/src/router/guardrail.mjs

@@ -28,7 +28,7 @@
 // Pure over its inputs + ctx.resolve (the binding oracle). No network, no Date.now.
 
 import { capabilityByName, preconditionsOf, PRECOND } from "./registry.mjs";
-import { hallucinationsIn } from "../../agentbench/grade.mjs";
+import { hallucinationsIn } from "./call-validator.mjs";
 
 /** Validate a proposed tool_use. Returns a glass-box verdict:
  *    { ok, tool, denied:[{reason,detail}], steps:[{pred,ok,...}], provenance }

package/src/router/planner.mjs

@@ -74,7 +74,28 @@ export function decompose(request) {
     };
   }
 
-  // METHOD 3 — SEQUENCING: split on the ordered connectives. Least commitment:
+  // METHOD 3 — the MEMBER-FILTER recipe: "which/what methods|members of X …
+  // (end up|eventually)? calling/reaching Y". A C1 surface-syntax recipe like the
+  // conditional and relative-filter methods above (the C1 discipline: a closed,
+  // authored shape — NOT the C2 goal-reasoner's deduction). Decomposes to
+  // [enumerate members(X), filter by bounded transitive call-reach of Y]. The
+  // second segment is the filter TARGET, role "member-filter": the DRIVER owns
+  // the per-member callees hop + the reachability fold (driver-resolver.mjs) —
+  // segment 2 is not a resolvable leaf sub-goal on its own.
+  const mem = raw.match(
+    /^(?:which|what)\s+(?:methods?|members?)\s+of\s+(.+?)\s+(?:(?:end\s+up|eventually)\s+)?(?:calls?|calling|reach(?:es|ing)?|invokes?|invoking)\s+(.+?)\s*\??$/i,
+  );
+  if (mem) {
+    return {
+      method: "member-filter",
+      segments: [
+        { text: `members ${mem[1].trim()}`, role: "action", thread: false },
+        { text: mem[2].trim(), role: "member-filter", thread: true },
+      ],
+    };
+  }
+
+  // METHOD 4 — SEQUENCING: split on the ordered connectives. Least commitment:
   // we only split where a connective actually is.
   const parts = raw.split(/\s*(?:,\s*then\s+|,\s+and\s+then\s+|\s+and\s+then\s+|\s+then\s+|,\s+|\s+and\s+)\s*/i)
     .map((s) => s.replace(/^(?:then\s+|and\s+then\s+|and\s+|also\s+|check\s+|next\s+)/i, "").trim())