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

package/src/concept.mjs

@@ -213,6 +213,11 @@ export function composeConcept(graph, term, { definition = null, factRows = [] }
     instances: graphInstances.slice(0, MAX_EXAMPLES).map((i) => ({
       id: i.id, label: i.label, type: i.class,
     })),
+    // EVERY instance id (uncapped), for discourse-count anaphora ("count them" /
+    // "how many of those") over a truncated listing: `instances` is capped at
+    // MAX_EXAMPLES and the rest lives in `remainder` as prose labels, invisible to
+    // the counter — so a follow-up count would undercount without the full id set.
+    allInstanceIds: graphInstances.map((i) => i.id),
     // the un-shown instance labels + their plural noun, for the shell's "more"
     // pagination — empty when nothing was truncated.
     remainder: remainderLabels,

package/src/conformance.mjs

@@ -1,6 +1,6 @@
 // conformance.mjs — the Repository-Interface CONTRACT TEST SUITE as a reusable kit.
 //
-// PLAN_REPOSITORY_INTERFACE.md deliverable 3: an implementation is CONFORMANT iff it
+// archive/PLAN_REPOSITORY_INTERFACE.md deliverable 3: an implementation is CONFORMANT iff it
 // passes `runConformance(name, makeProvider)`. tmct's own fixture + bootstrap providers
 // pass it in `npm test`; an EXTERNAL producer (seonix) imports this kit from the
 // published package and runs the SAME suite against its native provider to claim

package/src/corpus/templates.mjs

@@ -19,7 +19,7 @@ const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 export const TEMPLATES_FILE = join(PKG_ROOT, "data", "templates", "responses.jsonl");
 export const PHRASEBOOK_FILE = join(PKG_ROOT, "data", "phrasebook", "software-phrases.txt");
 
-// Registers (Phase 6, PLAN_FORMULAIC_COMPETENCE.md): `terse|friendly` are the
+// Registers (Phase 6, archive/PLAN_FORMULAIC_COMPETENCE.md): `terse|friendly` are the
 // conversational bands; `technical` is the C1 / technical-paper band whose
 // templates render item-5 mechanical conclusions (count / comparison /
 // superlative + the provenance we already compute) as advanced prose. A

package/src/finish.mjs

@@ -1,5 +1,5 @@
 // finish.mjs — Phase 7 response finishing: the segmentation IR seam.
-// (PLAN_RESPONSE_FINISHING.md, "The segmentation IR (lever 1)".)
+// (archive/PLAN_RESPONSE_FINISHING.md, "The segmentation IR (lever 1)".)
 //
 // The governing principle is fact-invariance BY CONSTRUCTION. An answer is a
 // list of typed spans, [{ type, text }, …], carried alongside the flat string

package/src/hash.mjs

@@ -1,6 +1,6 @@
 // hash.mjs — the single home for tmct's content-address hash.
 //
-// FNV-1a 32-bit is deliberately home-grown (see PLAN_DEPENDENCY_STRATEGY.md): it
+// FNV-1a 32-bit is deliberately home-grown (see archive/PLAN_DEPENDENCY_STRATEGY.md): it
 // must be synchronous, browser-safe, dependency-free, and — critically —
 // CROSS-VERSION STABLE, because fact ids are content-addressed by it and a fact's
 // id is its identity across the whole memory graph. Every library candidate fails

package/src/interpret/normalize.mjs

@@ -118,6 +118,70 @@ export const PHRASING_FRAMES = Object.freeze([
   { re: /^what\s+(?:defined|declared)\s+(?:the\s+)?(?:function\s+|method\s+|class\s+|module\s+|variable\s+|constant\s+)?(.+?)\??$/i, to: (m) => `where is ${m[1]} defined` },
   //   "where's X defined" (the "where's" contraction is not in the contraction table)
   { re: /^where'?s\s+(?:the\s+)?(.+?)\s+(defined|declared|located|implemented)\??$/i, to: (m) => `where is ${m[1]} ${m[2]}` },
+
+  // PREDICATIVE QUALIFIER → the ATTRIBUTIVE form the grammar already answers. The
+  // adjective-qualifier post-filters (ask-vocab.mjs QUALIFIERS: tested/untested,
+  // public/private, exported, static/abstract/constant, …) parse in the ATTRIBUTIVE
+  // slot — "untested modules", "public methods" — but a developer just as naturally
+  // asks the PREDICATIVE "which modules are untested" / "what functions are tested",
+  // which hit the grammar wall (and, worse, the wall's own hint SUGGESTED "which
+  // functions are tested" — a shape it could not then answer). Rewriting the
+  // predicative "<which|what> <kind> are <QUALIFIER>" to "<QUALIFIER> <kind>" routes
+  // it onto the working attributive filter. Closed to the known qualifier adjectives
+  // (not a general "… are X" catch), and the QUALIFIER must sit immediately after
+  // are/is, so "which modules are NOT tested" never matches here — that keeps its own
+  // set-complement handler (matchNegationSet, downstream in ask.mjs's parseNegation).
+  {
+    re: /^(?:which|what)\s+(?:the\s+|all\s+)?([a-z][a-z-]*?)\s+(?:are|is)\s+(public|private|protected|static|abstract|constant|exported|re-?exported|tested|covered|untested|uncovered)\??$/i,
+    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
+  // developer types — the one the README itself prints and the relation renders as:
+  // "what does X change together with" / "what changes together with X". Both hit a
+  // dead-end ("couldn't resolve one of the terms" / the grammar wall); rewriting them
+  // 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
@@ -132,7 +196,7 @@ export function applyPhrasingFrames(text) {
   return text;
 }
 
-// ---- §B1 negation — the SET-COMPLEMENT frame (Cycle 5, PLAN_CYCLE_4.md). Recognizes
+// ---- §B1 negation — the SET-COMPLEMENT frame (Cycle 5, archive/PLAN_CYCLE_4.md). Recognizes
 // a BARE set-negation query — "which X do not <verb> Y", "X that don't <verb> Y",
 // "modules not importing Y", "which X are not <qualifier>" — and returns a descriptor
 // {entWord, predicate} that ask.mjs's compositional grammar turns into a bounded

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/interpret/strategies/keywords.mjs

@@ -12,7 +12,7 @@ import {
 import { STOPWORDS } from "../normalize.mjs";
 import { VOCAB_WORDS, eligibleForCanon, fuzzyVocabWord } from "../fuzzy.mjs";
 
-// Reversible-passive detection (Cycle 6, PLAN_CYCLE_4.md): the passive auxiliaries that,
+// Reversible-passive detection (Cycle 6, archive/PLAN_CYCLE_4.md): the passive auxiliaries that,
 // together with an agent-marking "by", flip the active reading, and the wh-words that
 // mark a QUESTIONED agent ("by which classes" / stranded "who is X tested by"). Bare
 // "do/does/did" are deliberately EXCLUDED — "which X do not <verb> Y" is a NEGATION, not
@@ -176,7 +176,7 @@ export function parseKeywordSpot(text, nlp = null) {
     if (objText) return { shape: "when", entityType: null, modifier: "direct", kind: "touches", object: objText };
   }
 
-  // reversible passive (Cycle 6, PLAN_CYCLE_4.md): "PATIENT is VERBed BY AGENT" — an
+  // reversible passive (Cycle 6, archive/PLAN_CYCLE_4.md): "PATIENT is VERBed BY AGENT" — an
   // agent-marking "by" plus a passive auxiliary flips the active reading, so the AGENT
   // (after "by") is the edge SUBJECT and the PATIENT the edge OBJECT. Object-first
   // phrasing is otherwise read subject-first and the edge traversed backwards. Fires

package/src/providers/bootstrap.mjs

@@ -1,5 +1,5 @@
 // The BOOTSTRAP reference provider — the empty/degenerate graph a fresh repo
-// "contains" before anything is indexed. PLAN_REPOSITORY_INTERFACE.md deliverable
+// "contains" before anything is indexed. archive/PLAN_REPOSITORY_INTERFACE.md deliverable
 // 2: "bootstrap returns honest empties".
 //
 // It implements every Repository-Interface service over the empty bootstrap

package/src/providers/fixture.mjs

@@ -1,5 +1,5 @@
 // The FIXTURE reference provider — a small, real, self-contained code graph that
-// implements every Repository-Interface service. PLAN_REPOSITORY_INTERFACE.md
+// implements every Repository-Interface service. archive/PLAN_REPOSITORY_INTERFACE.md
 // deliverable 2: "the executable specification an external producer reads first".
 //
 // It is a degenerate provider in the sense that its graph is tiny and its source

package/src/providers/graph-service.mjs

@@ -1,5 +1,5 @@
 // The reference Repository-Interface service over a parsed code graph.
-// PLAN_REPOSITORY_INTERFACE.md — "the executable specification".
+// archive/PLAN_REPOSITORY_INTERFACE.md — "the executable specification".
 //
 // createGraphService(graph) returns a typed service object implementing EVERY
 // service in src/repository-interface.mjs over the `{ individuals, byId,

package/src/repository-interface.mjs

@@ -1,6 +1,6 @@
 // The Repository Interface — tmct's OWNED, versioned contract between "interpret
 // the query" (tmct, the brittle side) and "ask the graph for truth" (a provider,
-// the stable side). PLAN_REPOSITORY_INTERFACE.md.
+// the stable side). archive/PLAN_REPOSITORY_INTERFACE.md.
 //
 // tmct defines and versions this shape; a provider (seonix, a fixture, a browser
 // page) IMPLEMENTS it over its native graph. Both sides already agree on the

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(" -> ")}` };
+}