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

package/ROADMAP.md

@@ -14,34 +14,41 @@ the file has been deleted.
 
 ## Where we are now (2026-07-06)
 
-**Built: v0.8.0 — Phase 11 landed (Phases 0–10 shipped in 0.7.1).** All five Phase-11 tracks are
-built, merged, and measured; `npm test` green (**869**). Push/publish held for the operator. Highlights:
-
-- **Track 1 — chat levers (measured).** Pronoun/focus binding, discourse-count anaphora, and C1
-  temporal-over-relative composition all landed. `CHATBENCH_0.8.0`: tier-1 spine **331→333**, all three
-  lever families moved their cells (the B1-temporal control did not spill); judged fixed tag
-  `multi-turn-focus` **1.433→1.9** (the pronoun lever's echo). The judged pooled mean (1.44) is **not
-  case-comparable** to 0.7.1's 1.488 — the graded draw re-samples 10% of cells each run, so §1 compares
-  cell-level, not the scalar; the deterministic tier-1 spine is the load-bearing PASS.
-- **Track 2 — the router (designed → DEMONSTRATED).** The Anthropic-compatible `/v1/messages` shim
-  (`serve` mode), the Stage-0 capability registry (STRIPS/PDDL operators, closed-world default-deny),
-  and the resolver (S1) + guardrail (S4) + planner (S3, pure-JS POP/HTN + Steel & Ho monitor). Measured:
-  `AGENTBENCH_0.8.0` (shim-transport floor, 46% completion) → `AGENTBENCH_0.8.0_001` (the real router):
-  **96% completion at 0% hallucination on every rung**, clearing the closed-world ladder to **C1**. The
-  honest gate the phase was staked on is **met on its hallucination axis (0%)**. **Caveat (stated in the
-  artifact):** AGENTBENCH grades the correct **call-plan + proof**, *not* the executed composed result,
-  and B1/B2/C1 are thin rungs (2–3 cases); the C2 case is honestly **refused** (Stage 5, unbuilt).
-- **Track 3 — bedrock-meter surface.** `../bedrock-meter` gained a cost-ascending router ladder with the
-  **tmct `$0` rung at rank 0 below nova-micro**; an end-to-end test meters an in-envelope request at
-  **£0** and escalates out-of-envelope to nova-micro (that repo: 73 green, unpushed).
-- **Track 4 — playtest.** Three frozen dialogue-flow transcripts (`test/chatflow-{coverage,history,
-  architecture}.test.mjs`) from routing dead-ends off the grammar wall.
-- **Track 5 — research.** `docs/references/planning/` gained Stage-2 intent-frames + Stage-5
-  goal-reasoner design notes + a BDI/Goal-Driven-Autonomy reference entry.
-
-**Next:** the C2 goal-reasoner (Stage 5) and Stage-2 imperative intent frames are the designed-but-
-unbuilt edge; the tier-4/tier-5 items in Phase LATER remain the long tail. See Phase 11 below and
-`HANDOVER.md` for the open follow-ups.
+**Built: v0.8.1 — Phase 11 deepened (0.8.0 shipped + published; 0.8.1 push held for the operator).**
+`npm test` green (**916**). 0.8.1 hardened the router with real *reasoning* measurement and closed the
+frontier stages, all under the same demonstrated-vs-designed honesty discipline:
+
+- **AGENTBENCH now grades the executed composed RESULT, not just the call-plan** (retires the headline
+  0.8.0 caveat). Under result-grading the resolver is **97% plan / 91% result / 0% hallucination**; the
+  honest gap lands exactly where reasoning is hard (C1, C2).
+- **Stage 5 — the C2 goal-reasoner** (BDI + Goal-Driven Autonomy) genuinely lifts result-completion.
+  The honest, **like-for-like** figure is the *driver swap on the identical 39-case ladder*
+  (`AGENTBENCH_0.8.1_001`): resolver **85% → goal-reasoner 95% result** (+10pp, purely the driver, 0%
+  hallucination). C2 is **cleared for one declared coverage-invariant goal-rule** — real and
+  phrasing-robust (validated by held-out phrasings graded blind, no request-string literals), but
+  **thinly sampled, not rule-general**; the open-world case is honestly **refused**. *(NB: the
+  cross-release "0→83% C2" reads on a grown 6-case C2 ladder whose 4 new cases exercise the
+  goal-reasoner — not a like-for-like rate; the same-basket win is one case fixed, 0→50% original C2.)*
+- **Stage 2 — imperative intent frames + ACE reach** (`AGENTBENCH_0.8.1_002`, goal driver): **100% plan
+  / 95% result / 0% hallucination**. `tmct_calls` is now **genuinely NL-reachable** via a distinct
+  edge-dump frame (not by un-tagging — bidirectional conformance enforces it; `NOT_NL_REACHABLE` is now
+  `{}`). ACE is wired **async** into the interpret pipeline so the synchronous CHATBENCH parse spine is
+  **byte-identical** — ACE is inert in the shipped product path (`interpret()` is called nowhere in
+  chat/ask/server/bin), reach without regression.
+- **Chat surface (CHATBENCH_0.8.1):** quick wins (singular "what is a test", friendly commit-author
+  refs, "No tests cover X" honest-empty, the chatbench discourse-count flake root-caused + scrubbed) +
+  two playtests (coverage-survey + authorship routing; **6 frozen `chatflow-*` transcripts** total).
+  Joint deterministic CHATBENCH (both new frame tables together): **no tier-1 regression vs 0.7.1.**
+  Judged tags touched by the text changes were re-judged (not blanket-reused) — see `CHATBENCH_0.8.1`.
+
+**Shipped earlier in v0.8.0 (published):** all five Phase-11 tracks — the `/v1/messages` shim + Stage-0
+registry + resolver/guardrail/planner (`AGENTBENCH_0.8.0_001`: 96% *plan* completion, 0% hallucination,
+closed-world C1); the three chat levers (`CHATBENCH_0.8.0`: tier-1 331→333); the `../bedrock-meter` `$0`
+rung (rank 0 below nova-micro, £0 metered e2e); the playtest; and the Stage-2/Stage-5 research notes.
+
+**Next:** grow the thin C2/coverage sampling to a second goal-rule; author→commit querying (a dead-end
+the friendly-commit-ref quick win opened); AGENTBENCH ladder depth; the tier-4/tier-5 Phase LATER long
+tail. See Phase 11 below and `HANDOVER.md` for the full open-follow-up list.
 
 ## The umbrella product definition (item 1)
 
@@ -628,7 +635,7 @@ you toward precision" promise on the conversational surface.
   with new graded cells for the miss / empty-graph / concept-touch surfaces so these become
   regression-protected levers, not one-off polish.
 
-## Phase 11 — The capability router & the agentic bench (0.8.0 — LANDED)
+## Phase 11 — The capability router & the agentic bench (0.8.0 shipped · 0.8.1 deepened)
 
 *(Operator-directed 2026-07-06; built the same day across five concurrent tracks.)* tmct as a **deterministic, no-LLM
 tool router** behind an Anthropic-compatible API — the workstream specified in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",

package/src/ask.mjs

@@ -1646,6 +1646,17 @@ function symbolLabelOf(ind) {
   return ["Function", "Method"].includes(ind.class) ? `function ${label}()` : label;
 }
 
+/** A FRIENDLY commit reference for a "who touched X" list — the raw sha alone reads as
+ *  noise, so when the Commit individual carries an author (mgx:commitAuthor → key
+ *  "author") name them beside it. The label is already the graph's short ref (the
+ *  builder stores sha.slice(0,12)), so it is used verbatim. Degrades gracefully: a
+ *  commit with no recorded author renders the sha alone, exactly as before. */
+function commitRefOf(ind) {
+  const sha = String(ind.label || ind.id || "");
+  const author = (ind.attributes || []).find((a) => a.key === "author")?.value;
+  return author ? `${sha} (${author})` : sha;
+}
+
 function listJoin(syms) {
   return syms.length > 1 ? `${syms.slice(0, -1).join(", ")} and ${syms[syms.length - 1]}` : syms[0];
 }
@@ -1834,6 +1845,20 @@ function renderCore(parsed, result) {
         miss: true, ambiguous: false,
       };
     }
+    // "what tests cover X" / "what tests X" — the tests themselves are the search
+    // target (no explicit entity keyword → entityType null), and "tests" reads as a
+    // verb phrase, so the generic "No <modules> found whose module directly tests <obj>"
+    // template garbles: it mislabels the searched kind as "modules" and lets the leaked
+    // "cover " verb ride into the object ("…directly tests cover X"). Render the honest
+    // empty as the natural "No tests cover X." The frozen entity-keyword form ("which
+    // modules test X", entityType="Module") keeps its pinned wording below.
+    if (parsed.kind === "tests" && !parsed.entityType) {
+      const obj = String(parsed.object || "").replace(/^cover(?:s|ing)?\s+/i, "").trim();
+      return {
+        content: `No tests cover ${obj}. (traversal: ${result.traversal || "no traversal resolved"})`,
+        miss: true, ambiguous: false,
+      };
+    }
     // NOTE (Cycle 5): a voice-nit rephrasing ("that directly <verb>") was reverted —
     // the frozen v1 cases.jsonl pins the "whose module directly <verb>s X" wording
     // (hm-empty-result-calls / tf-wat-calls / ns-wondering), and the case set is
@@ -1853,7 +1878,10 @@ function renderCore(parsed, result) {
   // Commit list ("which commits touched X") has no containing module to group by, so
   // anything that is not a fine entity takes the flat join.
   if (parsed.shape === "forward" || parsed.entityType === "Module" || result.matches.every((m) => !FINE_ENTITY_TYPES.has(m.class))) {
-    const shown = result.matches.slice(0, OVERFLOW_CAP).map((m) => m.label);
+    // A reverse "who touched X" resolves to Commit individuals — render friendly refs
+    // (short sha + author) instead of the raw stored sha; every other flat list (module
+    // labels, etc.) keeps its own label verbatim.
+    const shown = result.matches.slice(0, OVERFLOW_CAP).map((m) => m.class === "Commit" ? commitRefOf(m) : m.label);
     const extra = result.matches.length > OVERFLOW_CAP ? `, …and ${result.matches.length - OVERFLOW_CAP} more` : "";
     return { content: shown.join(" and ") + extra + ".", miss: false, ambiguous: false, matches: result.matches };
   }

package/src/chat.mjs

@@ -1332,6 +1332,19 @@ function relationTermOf(query, envelope) {
   if ((m = q.match(/^what\s+([a-z][a-z-]*?)\s+are\s+there$/))) return m[1];
   // "what is calling", "what is importing" (bare gerund, no object)
   if ((m = q.match(/^what\s+(?:is|are)\s+([a-z][a-z-]*ing)$/))) return m[1];
+  // THE SINGULAR META FORM — "what is a test" / "what is an import". The whole meta
+  // shape used to be excluded here to keep the frozen am-meta-imports ambiguity case
+  // ("what does imports mean") out; but that case is a DIFFERENT shape (ambiguousParse
+  // → envelope.parsed is null), and a relation word whose SINGULAR reads as a real
+  // graph-schema class/predicate ("what is a contains"/"cochange") answers non-miss
+  // from the ordinary meta path. So admit the article meta form ONLY when the ordinary
+  // path MISSED on a plain definitional parse (envelope.miss on a shape:"meta" object):
+  // an unambiguous relation word like "test" — no schema reading, no ambiguity — then
+  // reaches the relation-concept force exactly as its plural "what are the tests" does.
+  // RELATION_TERM still gates the term downstream, so a non-relation miss is untouched.
+  if (envelope?.miss === true && envelope?.parsed?.shape === "meta" && envelope.parsed.object) {
+    return envelope.parsed.object;
+  }
   return null;
 }
 

package/src/interpret/normalize.mjs

@@ -136,6 +136,26 @@ export const PHRASING_FRAMES = Object.freeze([
     to: (m) => `${m[2].toLowerCase()} ${m[1].toLowerCase()}`,
   },
 
+  // BARE COVERAGE SURVEY (no entity kind) → the attributive "<qualifier> modules"
+  // the grammar already answers. Once "what is a test" opens the topic, a developer
+  // asks the survey the plainest way — "what is untested", "what's not tested",
+  // "what isn't covered", "what is covered" — with NO entity noun at all, so the
+  // predicative-qualifier frame above (which needs a KIND between what/which and
+  // are/is) can't catch it, and it fell through to a soft wall ("no module matching
+  // 'not'…" / the "I answer questions…" orientation). Default the surveyed kind to
+  // modules (the same set "which modules are not tested" / "untested modules" return)
+  // and fold the negation into the qualifier (not tested → untested, not covered →
+  // uncovered). Anchored with no object, so "what tests cover X" / "what is a test"
+  // never match here.
+  {
+    re: /^what\s+(?:is|are)\s+(not\s+)?(tested|untested|covered|uncovered)\??$/i,
+    to: (m) => {
+      const q = m[2].toLowerCase();
+      const flipped = m[1] ? (q === "tested" ? "untested" : q === "covered" ? "uncovered" : q) : q;
+      return `${flipped} modules`;
+    },
+  },
+
   // CO-CHANGE → the "co-changes with" canonical the RELATIONS table answers. The
   // cochange verb synonyms (ask-vocab.mjs) include "co-changes with" / "moves
   // together with" / "tends to change together with", but NOT the plainest form a
@@ -145,6 +165,23 @@ export const PHRASING_FRAMES = Object.freeze([
   // onto "what co-changes with X" routes them to the working change-coupling query.
   { re: /^what\s+does\s+(.+?)\s+changes?\s+together\s+with\??$/i, to: (m) => `what co-changes with ${m[1]}` },
   { re: /^what\s+changes?\s+together\s+with\s+(.+?)\??$/i, to: (m) => `what co-changes with ${m[1]}` },
+
+  // AUTHORSHIP → the "who touched X" churn query. "who touched X" now names the
+  // commit author beside the sha (the 0.8.1 commit-ref quick-win), which invites the
+  // synonyms a developer reaches for next — "who wrote X", "who authored X", "who is
+  // the author of X" — and every one of them hit the grammar wall. tmct has no
+  // 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]}` },
+
+  // 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
+  // grammar wall ("no module matching 'needs'…"). Route it onto the same attributive
+  // survey the bare "what is untested" frame lands on. Closed to the tests/coverage
+  // object, so it can't swallow a general "what needs X".
+  { re: /^what\s+needs\s+(?:to\s+be\s+)?(?:a\s+)?(?:tested|tests?|testing|coverage|covering)\??$/i, to: () => "untested modules" },
 ]);
 
 /** Apply the phrasing frames (members-of-class + where-defined) — first match wins

package/src/interpret/pipeline.mjs

@@ -27,6 +27,13 @@ import { normalizeQuery, applyNegationFrames, applyPhrasingFrames } from "./norm
 import { grammarStrategy } from "./strategies/grammar.mjs";
 import { keywordSpotStrategy } from "./strategies/keywords.mjs";
 import { noiseStripStrategy } from "./strategies/noise-strip.mjs";
+// Optional Node-flavored ACE strategy — same viewer-bundle boundary as the
+// ask-nlp adapter below: the ACE grammar reaches grammar/ace.mjs -> lexicon.mjs,
+// which reads its committed JSON via Node fs, so an inlining viewer bundle strips
+// this import; the `typeof` guard where STRATEGIES is built then degrades to an
+// ace-less registry instead of throwing over an undeclared identifier. (ACE is
+// async-only anyway, so the sync parseQuery path the viewer uses never ran it.)
+import { aceStrategy } from "./strategies/ace.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
@@ -38,9 +45,17 @@ import { nlpAdapter } from "../ask-nlp.mjs";
  *  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];
+ *  existing template parse). interpret/strategies/ace.mjs (Phase 2 / Stage 2) is
+ *  the ACE-OWL controlled-fragment grammar, registered here as an ADDITIVE, own-
+ *  class ("ace-fact") strategy. It is ASYNC on purpose: runStrategiesSync (the
+ *  parseQuery / CHATBENCH-facing path) SKIPS Promise-returning strategies, so ACE
+ *  adds declarative-fragment reach to interpret() while leaving the sync spine
+ *  byte-stable (see strategies/ace.mjs for the full rationale). The `typeof` guard
+ *  mirrors the nlpAdapter degradation: a stripped ACE import (viewer bundle) leaves
+ *  the identifier undeclared, so the registry is ace-less there instead of a crash. */
+// eslint-disable-next-line no-undef
+const OPTIONAL_STRATEGIES = typeof aceStrategy !== "undefined" ? [aceStrategy] : [];
+export const STRATEGIES = [grammarStrategy, keywordSpotStrategy, noiseStripStrategy, ...OPTIONAL_STRATEGIES];
 
 /** The documented normalization pre-pass: whitespace-collapse + the §3.5
  *  normalization pipeline + the closed rhetorical-frame rewrites, applied ONCE

package/src/interpret/strategies/ace.mjs

@@ -0,0 +1,49 @@
+// interpret/strategies/ace.mjs — the ACE-OWL controlled-fragment grammar wired
+// into the interpretation pipeline as an ADDITIVE strategy (Stage 2, "ACE reach").
+//
+// The ACE engine (src/grammar/ace.mjs) has existed since Phase 2, but its pipeline
+// ADAPTER was the "real and empty" seam the pipeline header names (interpret/
+// pipeline.mjs). This file fills it. The contract is strictly ADD-ONLY:
+//
+//   · Its own class, "ace-fact" — DISJOINT from the graph-query strategies, so a
+//     clean ACE parse is a distinct-class ALTERNATE ("if you mean X then …"), never
+//     a same-class competitor that could displace a graph-query winner.
+//   · It emits a candidate ONLY on a CLEAN parse (parseAce returns triples). A
+//     structural-fit-with-residue (empty triples) or a total miss returns null, so
+//     a query sentence that merely LOOKS relation-shaped ("which modules import X",
+//     whose ACE residue is the "which") contributes nothing — fitting the grammar
+//     is a strong signal; missing it is a FEATURE and the tolerant strategies win.
+//
+// WHY ASYNC — the byte-stability guarantee. ask.mjs's parseQuery (the CHATBENCH
+// chat-facing path) runs strategies through runStrategiesSync, which — by the
+// pipeline's documented contract — SKIPS any Promise-returning strategy ("an async
+// strategy can only participate via interpret()"). Registering ACE async therefore
+// makes the sync parseQuery path PROVABLY untouched (CHATBENCH neutral, byte-for-
+// byte) while interpret() — the async pipeline — gains the declarative-fragment
+// reach. The work parseAce does is synchronous; the async wrapper is deliberate,
+// the mechanical seam that keeps the chat spine frozen. (grammar/ace.mjs itself is
+// imported UNCHANGED — no chat-facing edit.)
+
+import { parseAce } from "../../grammar/ace.mjs";
+
+/** Adapter: a clean ACE parse -> one candidate in its own class; anything else
+ *  (residue-only structural fit, or a hard miss) -> null. `via:"exact"` — a
+ *  controlled-grammar fit is exact evidence, never an approximate rewrite. */
+export function runAce(text) {
+  let parsed = null;
+  try { parsed = parseAce(text); } catch { return null; }
+  if (!parsed || !Array.isArray(parsed.triples) || parsed.triples.length === 0) return null;
+  return { strategyId: "ace", class: "ace-fact", candidates: [{ parsed, confidence: 0.85, via: "exact", note: `ACE ${parsed.pattern}` }] };
+}
+
+/** Pipeline registration (interpret/pipeline.mjs). ASYNC on purpose (see file
+ *  header): it participates in interpret() but is SKIPPED by runStrategiesSync,
+ *  so parseQuery — and the CHATBENCH spine it feeds — is byte-stable. */
+export const aceStrategy = {
+  id: "ace",
+  class: "ace-fact",
+  // eslint-disable-next-line require-await
+  async run(text) {
+    return runAce(text);
+  },
+};

package/src/router/goal-reasoner.mjs

@@ -0,0 +1,266 @@
+// src/router/goal-reasoner.mjs — Stage 5 of the capability router
+// (PLAN_CAPABILITY_ROUTER.md / STAGE_5_GOAL_REASONER.md): THE CLOSED-WORLD C2
+// GOAL-REASONER. "Self-directed" is not magic — it is a canned, HARD-BOUNDED
+// meta-loop (Rao & Georgeff BDI × Aha/Molineaux/Cox GDA × continual planning):
+//
+//     deduce current goals            (step 1 — the only genuinely new part)
+//   → plan for each goal              (step 2 — C1: the Stage-3 planner/resolver)
+//   → arbitrate the first steps       (step 3a — keystone, threat-aware)
+//   → PERSIST the committed intention  (step 3b — BDI drop conditions)
+//   → execute ONE, observe, repeat    (step 5 — Steel & Ho monitor / GDA replan)
+//
+// The elegance (RFC): C2 collapses into C1 + a goal-deduction step + an
+// action-selection rule. Everything except goal-deduction is solved machinery.
+// This module supplies the goal-deduction as a DEDUCTION over a DECLARED goal
+// model (never a judgement over the request string) and REFUSES at the
+// open-world goal-generation seam rather than inventing a goal — the C2 analogue
+// of the resolver's "never emit a call it cannot prove".
+//
+// DEDUCTION, NOT KEYWORD-MATCH. The current goals fall out of the KB via a
+// declared goal model (GOAL_RULES), exactly as syllogise chains a declared rule
+// over the graph under mechanical guards. The ONLY thing this reads off the
+// request is a FOCUS entity (delegated to the resolver's extractEntity + the
+// binding oracle — entity resolution, never intent keywords). Whether a goal is
+// active is then deduced from the graph (is the focus module untested? what does
+// its change reach?), so no request-string literal steers the routing.
+//
+// MECHANICAL TERMINATION (not a convergence argument). Two independent bounds:
+//   (1) a hard OUTER-tick budget MAX_TICKS (mirrors the planner's MAX_STEPS), and
+//   (2) a MONOTONE-PROGRESS invariant — every tick ACHIEVES exactly one intention
+//       (removes it from the pending set); the only growth is a SINGLE, bounded
+//       GDA expansion (impact-of-each over the finite untested set), gated by a
+//       one-shot flag. So the pending set strictly shrinks to the empty set in
+//       <= (initial + |untested|) ticks, and MAX_TICKS caps it absolutely. A tick
+//       that makes no progress HALTS (honest refuse). Termination is proven
+//       mechanically, not argued from BDI convergence.
+//
+// THREAT-AWARENESS (POP threats lifted to the meta-level). A first step that
+// clobbers another live goal's precondition is a threat. Here it is PROVABLY
+// absent: every registry capability is read-only with an EMPTY delete-list
+// (queries mutate nothing — the STRIPS closed world), so no step can delete a
+// condition another goal depends on. We compute this from the registry rather
+// than assume it (threatsAmong), so the guarantee is grounded, not asserted.
+
+import { backwardChain, extractEntity } from "./resolver.mjs";
+import { capabilityByName, effectsOf } from "./registry.mjs";
+import { hallucinationsIn } from "../../agentbench/grade.mjs";
+import { intersect } from "../../agentbench/results.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
+// invariant: a belt-and-braces mechanical stop, the meta-level twin of the
+// planner's MAX_STEPS. A deduce->plan->observe cycle can never wedge the caller.
+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
+// deduction library" the RFC flags — same discipline as syllogise's rule set.
+export const GOAL_RULES = Object.freeze([
+  Object.freeze({
+    id: "coverage-invariant",
+    kind: "maintenance",
+    // INVARIANT: a Module whose change reaches other modules (non-empty impact
+    // 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).
+    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
+    // higher the goal (keystone = the widest-reach untested module).
+    priorityTopic: "impact",
+    // the coverage predicate the invariant screens on.
+    coverageTopic: "untested",
+    // the meta-goal topic the composed answer achieves (backward-chained below).
+    achieves: "coverage-gap",
+  }),
+]);
+
+/** Backward-chain a meta-goal topic to the declared goal-rule that achieves it —
+ *  the goal-level twin of resolver.backwardChain (capability selection). Pure. */
+export function backwardChainGoal(topic) {
+  return GOAL_RULES.find((r) => r.achieves === topic) || null;
+}
+
+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
+ *  a candidate step's DELETE-effects would clobber (POP threats over the
+ *  conjunction of active goals). Computed from the registry's delete-lists. In
+ *  this read-only registry every capability's delete-list is empty, so this is
+ *  provably [] — but we DERIVE it rather than assume it, so the guarantee holds
+ *  the day a mutating capability is ever registered. Pure over the registry. */
+export function threatsAmong(candidateName, _pending) {
+  const cap = capabilityByName(candidateName);
+  const del = cap ? effectsOf(cap.name).del : [];
+  return del.length ? [{ name: candidateName, deletes: del }] : [];
+}
+
+/** Resolve the FOCUS the request scopes the goal model to — an entity binding
+ *  (extractEntity + the graph oracle), NOT an intent keyword. Returns the bound
+ *  individual or null (no bindable focus => a whole-graph / global goal). */
+function focusOf(request, ctx) {
+  const term = extractEntity(String(request || ""));
+  if (!term || !ctx || !ctx.resolve) return null;
+  const r = ctx.resolve(term);
+  return r && r.match && !r.ambiguous ? r.match : null;
+}
+
+/** Ground ONE epistemic sub-goal (a topic + optional bound entity) into a
+ *  grounded, EXECUTED call, or null when it is not groundable in the declared
+ *  toolset (=> the meta-loop escalates). Backward-chains topic->capability, binds
+ *  the entity, self-checks the same zero-hallucination gate the grader enforces,
+ *  then dispatches. Mirrors the resolver/planner's honest-miss discipline. */
+async function groundSubGoal(topic, entityLabel, tools, ctx) {
+  const cap = backwardChain(topic);
+  if (!cap || !tools.includes(cap.name)) return null; // no declared capability => escalate
+  // the arg grain: a no-arg coverage scan (untested) binds nothing; an entity
+  // topic binds the focus label to the capability's single slot.
+  const param = cap.parameters.find((p) => p.required);
+  if (param && !entityLabel) return null; // an entity topic with nothing to bind
+  const input = param && entityLabel ? { [param.arg]: entityLabel } : {};
+  const call = { name: cap.name, input };
+  if (hallucinationsIn(call, tools).length) return null; // never emit an unprovable call
+  const res = await ctx.dispatch(cap.name, input);
+  if (!res || !res.ok) return null; // honest miss at dispatch => escalate
+  return { call, result: Array.isArray(res.result) ? res.result : [] };
+}
+
+/** 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) {
+  if (observed.has(intention.key)) return "achieved";       // fact now gathered
+  if (mode === "scoped" && (!focus || focus.class !== "Module")) return "lapsed"; // focus moved
+  return null;                                               // else keep the commitment
+}
+
+/** THE META-LOOP. deduce current goals -> plan-each (C1) -> threat-aware
+ *  persistent first-step arbitration -> execute one -> observe -> repeat,
+ *  HARD-BOUNDED. Returns a loopResult { calls, refused, terminated, proof, why,
+ *  composed, driver } — a composed answer (the coverage-gap set for a focus, or
+ *  the keystone module globally) or an HONEST REFUSE at the open-world
+ *  goal-generation seam.
+ *
+ *  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.
+  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)
+
+  // 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 glass-box WHY, citing the declared goal-rule by backward-chain (the C2
+  // twin of resolver.mjs's "backward-chain => <capability>" provenance).
+  const why = [
+    `goal-deduction: backward-chain (achieves ${rule.achieves}) => goal-rule "${rule.id}" (${rule.invariant})`,
+    `mode: ${mode}${focus ? ` (focus ${focus.label} [${focus.class}])` : " (whole-graph / keystone arbitration)"}`,
+    "threat-check: read-only registry => every capability delete-list empty => meta-level POP threats provably none",
+  ];
+  const proof = [{ step: "goal-rule", rule: rule.id, achieves: rule.achieves, ok: true }];
+  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 }];
+
+  let committed = null;   // the persisted BDI intention (not re-derived each tick)
+  let expanded = false;   // one-shot guard: the single bounded GDA expansion
+  let ticks = 0;
+
+  while (pending.length) {
+    // (1) HARD OUTER BOUND — mechanical, independent of the monotone invariant.
+    if (ticks >= MAX_TICKS) return refuse(`meta-loop tick budget exhausted (${MAX_TICKS}) — escalate`, driver);
+    ticks += 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 || !pending.includes(committed)) {
+      // (3a) FIRST-STEP ARBITRATION — least-commitment: the lowest declared order
+      //      among pending. Threat-aware: skip a step that would clobber another
+      //      live goal (provably never, read-only) before committing.
+      const admissible = pending.filter((i) => threatsAmong(backwardChain(i.topic)?.name, pending).length === 0);
+      if (!admissible.length) return refuse("all first steps are threatened (would clobber a live goal) — escalate", driver);
+      committed = admissible.slice().sort((a, b) => a.order - b.order)[0];
+    }
+
+    // (5) EXECUTE ONE, then OBSERVE (Steel & Ho monitor).
+    const grounded = await groundSubGoal(committed.topic, committed.of, declared, ctx);
+    if (!grounded) return refuse(`sub-goal (knows ${committed.topic}${committed.of ? ` ${committed.of}` : ""}) not groundable in the declared toolset — escalate`, driver);
+    calls.push(grounded.call);
+    observed.set(committed.key, grounded.result);
+    proof.push({ step: "causal-link", producer: "graph", condition: committed.of ?? committed.topic, consumer: `${committed.topic}:${grounded.call.name}`, ok: true });
+
+    // MONOTONE PROGRESS — this tick ACHIEVED exactly one intention: drop it.
+    const before = pending.length;
+    const achievedTopic = committed.topic;
+    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.
+    let expandedThisTick = false;
+    if (mode === "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 }));
+    }
+
+    // the invariant, enforced mechanically: the pending set shrank by one this
+    // tick (progress) OR grew ONLY by the one-shot bounded expansion. Anything
+    // else is non-progress => HALT honestly rather than risk a livelock.
+    if (pending.length > before - 1 && !expandedThisTick) {
+      return refuse("meta-loop made no monotone progress — halting", driver);
+    }
+  }
+
+  // STEP 3a (the answer) — COMPOSE + arbitrate the keystone from the gathered
+  // 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"})`);
+  } 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 }))
+      .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})` : "∅"}`);
+  }
+
+  return { calls, refused: false, terminated: true, proof, why, composed, driver, observed: `goal(${mode}): ${calls.map((c) => c.name).join(" -> ")}` };
+}

package/src/router/resolver.mjs

@@ -21,8 +21,13 @@
 //      the topic to the capability. This is the Stage-1 deliverable proper.
 //   3. IMPERATIVE INTENT FRAMES (Stage 2, this module's FRAMES table) — curated
 //      phrasings the relational grammar does not carry ("blast radius of X",
-//      "who calls X", "search for X"): a regex -> {topic, arg}. Same backward
-//      chaining (topic -> capability), same resolveObject binding.
+//      "who calls X", "search for X", "the call edges of X", "explain X"): a
+//      regex -> {topic, arg}. Same backward chaining (topic -> capability), same
+//      resolveObject binding. This is the surface that lifts NL reach above the
+//      command register: it reaches tmct_calls (the raw call-edge dump — a grain
+//      the relational "call" verb collides with) via an EXPLICIT edge-dump frame,
+//      and it rescues a request whose NL parse selected an OUT-OF-SET capability
+//      by re-selecting a DECLARED one (resolveOne falls through to the frame).
 //
 // ENTITY BINDING is DELEGATED to `resolveObject` (ask.mjs — the tiered lemma/
 // fuzzy binding oracle with honest ambiguity). This module NEVER re-implements
@@ -77,9 +82,17 @@ export const UNMAPPED_KINDS = Object.freeze({
 // conformance test FAILS on an untagged gap; a genuinely-unreachable cap must be
 // tagged HERE with the Stage it needs, so the ceiling is honest rather than a
 // silent low-completion refuse. (Coordinator reinforcement 2.)
-export const NOT_NL_REACHABLE = Object.freeze({
-  tmct_calls: "the raw call-edge dump collides with tmct_callees on every NL phrasing (\"what does X call\" -> callees) and has no command verb; distinguishing it needs a Stage-2 intent frame we have not authored",
-});
+//
+// EMPTY as of Stage 2. tmct_calls — the raw call-edge dump that USED to sit here —
+// is now reached by a DEDICATED imperative frame keyed on the "call edges / call
+// graph / outgoing calls of X" phrasings the relational grammar does NOT carry
+// (see FRAMES below). The collision the old tag named is real, so the frame does
+// NOT touch the relational "call" verb (that still routes callers/callees); it
+// opens a SECOND, distinct surface that names the edge-dump grain explicitly. With
+// it every declared capability is NL/command/frame-reachable — the ceiling is
+// genuinely empty, not a silenced gap. (The conformance test enforces both
+// directions: an over-claimed tag would now fail, since tmct_calls IS reachable.)
+export const NOT_NL_REACHABLE = Object.freeze({});
 
 // ---- imperative intent FRAMES (Stage 2 — fills what the relational grammar and
 // the command register both miss). regex -> { topic, arg | noArg }. `arg` names
@@ -90,7 +103,14 @@ export const NOT_NL_REACHABLE = Object.freeze({
 export const FRAMES = Object.freeze([
   { re: /\buntested\b|\bwithout\s+(?:a\s+)?tests?\b|\bhas\s+no\s+tests?\b|\bneeds?\s+(?:a\s+)?tests?\b/i, topic: "untested", noArg: true },
   { re: /\bblast\s*radius\b|\bimpacts?\b|\bimpacted\b|what\s+(?:a\s+)?change.*(?:reach|affect|touch)|what\s+(?:depends?\s+on|dependents?)\b/i, topic: "impact", arg: "module" },
-  { re: /\bcallees?\b|what\s+does\s+\S+\s+call\b/i, topic: "callees", arg: "symbol" },
+  // tmct_calls (Stage 2 — the reachability win): the RAW call-edge dump, a grain
+  // the relational "call" verb collides with (which routes callers/callees). This
+  // frame does NOT use the bare verb — it keys on the EXPLICIT edge-dump nouns
+  // ("call edges", "call graph", "outgoing calls of X") the relational grammar
+  // never emits, so it opens a distinct surface without touching callers/callees.
+  // FIRST so its explicit phrasing wins before the callees/callers verb frames.
+  { re: /\bcall[\s-]*edges?\b|\bcall[\s-]*graph\b|\boutgoing\s+calls?\b|\bcall[\s-]*sites?\s+(?:of|in|out|from)\b/i, topic: "calls", arg: "symbol" },
+  { re: /\bcallees?\b|wh(?:at|o)\s+does\s+\S+\s+call\b/i, topic: "callees", arg: "symbol" },
   { re: /\bcallers?\b|who\s+calls\b|what\s+calls\b/i, topic: "callers", arg: "symbol" },
   { re: /\btests?\b.*\b(?:for|cover|covering|of)\b|which\s+tests?\b|covers?\b|covered\b|test\s+coverage\b/i, topic: "tests", arg: "symbol" },
   { re: /\bcochang|change[- ]coupl/i, topic: "cochanges", arg: "symbol" },
@@ -99,7 +119,7 @@ export const FRAMES = Object.freeze([
   { re: /\bmembers?\b|\bmethods?\s+of\b|\battributes?\s+of\b/i, topic: "members", arg: "class" },
   { re: /\bhistory\b|who\s+changed\b|commits?\s+(?:that\s+)?touch/i, topic: "history", arg: "symbol" },
   { re: /\bsignature\b/i, topic: "signature", arg: "symbol" },
-  { re: /\bdescribe\b|what\s+is\b|tell\s+me\s+about\b|definition\s+of\b/i, topic: "description", arg: "symbol" },
+  { re: /\bdescribe\b|\bexplain\b|what\s+is\b|tell\s+me\s+about\b|definition\s+of\b/i, topic: "description", arg: "symbol" },
   { re: /\bsearch\b|\bfind\b|look\s+for\b/i, topic: "matches", arg: "query" },
 ]);
 
@@ -129,6 +149,9 @@ const STOP = new Set([
   "export", "exports", "history", "commit", "commits", "signature", "search", "find", "look",
   "module", "modules", "class", "classes", "function", "functions", "symbol", "symbols",
   "untested", "blast", "radius", "change", "changes", "changing", "reach", "reaches", "affect", "affects",
+  // Stage-2 edge-dump + imperative-verb tokens (tmct_calls frame + explain/outgoing
+  // phrasings): none names an entity, so keep them out of the slot-filler's pool.
+  "explain", "edge", "edges", "graph", "outgoing", "site", "sites", "invoke", "invokes", "run", "runs", "execute", "executes",
 ]);
 
 /** Pull one entity token from a request (imperative-frame slot-filling). Prefer a
@@ -235,13 +258,28 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
   //    so we fall through and only surface the NL reason if the frame misses too.
   let pick = commandCapability(request, declared);
   let nlRefuse = null;
+  let nlUndeclared = null;
   if (!pick) {
     const mapped = mapParse(parseQuery(request));
-    if (mapped && !mapped.refuse) pick = mapped;
-    else if (mapped && mapped.refuse) nlRefuse = mapped.reason;
+    if (mapped && !mapped.refuse) {
+      // An NL parse that selects a DECLARED capability is the Stage-1 answer. One
+      // that selects an OUT-OF-SET capability is NOT terminal (Stage-2 widening):
+      // an imperative FRAME may still reach a DECLARED capability for the SAME
+      // request (e.g. keyword-spot mis-routes "outgoing calls of X" toward an
+      // out-of-set callers/callees, but the calls-frame reaches the declared
+      // tmct_calls). Hold the out-of-set name and fall through; surface it only if
+      // the frame misses too. This can only turn a refuse into a grounded DECLARED
+      // call — the declared/hallucination gates below still apply, never a guess.
+      if (declared.has(mapped.name)) pick = mapped;
+      else nlUndeclared = mapped.name;
+    } else if (mapped && mapped.refuse) nlRefuse = mapped.reason;
   }
   if (!pick) pick = mapFrame(request);
-  if (!pick) return REFUSE(nlRefuse || "no command, NL parse, or imperative frame selects a capability");
+  if (!pick) {
+    if (nlRefuse) return REFUSE(nlRefuse);
+    if (nlUndeclared) return REFUSE(`selected ${nlUndeclared} but it is not in the declared toolset`);
+    return REFUSE("no command, NL parse, or imperative frame selects a capability");
+  }
   let why = pick.why ?? [];
   if (!declared.has(pick.name)) return REFUSE(`selected ${pick.name} but it is not in the declared toolset`);