@polycode-projects/the-mechanical-code-talker 2.5.0 → 2.5.3

package/src/tools/definitions.mjs

@@ -180,6 +180,19 @@ export const TOOL_DEFINITIONS = Object.freeze([
     inputSchema: classArg("The class to walk the inheritance edges of."),
     example: { class: "Field" },
   },
+  {
+    name: "tmct_related",
+    tier: "cold",
+    summary: "A term's synonyms (skos:altLabel) and related concepts (skos:related), from the memory graph's relation facts.",
+    inputSchema: {
+      type: "object",
+      required: ["term"],
+      properties: {
+        term: { type: "string", description: "The term whose synonyms / related concepts you want." },
+      },
+    },
+    example: { term: "sofa" },
+  },
   {
     name: "tmct_architecture",
     tier: "cold",

package/src/tools/handlers/index.mjs

@@ -14,6 +14,7 @@ import { tmct_impact } from "./tmct-impact.mjs";
 import { tmct_search } from "./tmct-search.mjs";
 import { tmct_members } from "./tmct-members.mjs";
 import { tmct_subclasses } from "./tmct-subclasses.mjs";
+import { tmct_related } from "./tmct-related.mjs";
 import { tmct_architecture } from "./tmct-architecture.mjs";
 import { tmct_exports } from "./tmct-exports.mjs";
 import { tmct_untested } from "./tmct-untested.mjs";
@@ -38,6 +39,7 @@ export const HANDLERS = Object.freeze({
   tmct_search,
   tmct_members,
   tmct_subclasses,
+  tmct_related,
   tmct_architecture,
   tmct_exports,
   tmct_untested,

package/src/tools/handlers/tmct-related.mjs

@@ -0,0 +1,30 @@
+// tmct_related — a term's synonyms (skos:altLabel) and related concepts (skos:related),
+// served from the conversational-memory graph's mgx:synonym / mgx:relatedTo / mgx:similarTo
+// facts through the derived SKOS concept view (src/domain/skos-view.mjs). A term the store
+// holds no relation facts for misses honestly — never a guessed neighbour.
+
+import { ToolError } from "../../adapters/config.mjs";
+import { relatedForTerm } from "../../domain/skos-view.mjs";
+import { memoryFactRows } from "../memory-fallthrough.mjs";
+import { requiredArg } from "./kit.mjs";
+
+export async function tmct_related(args, { config }) {
+  const term = requiredArg(args, "term");
+  const hit = relatedForTerm(await memoryFactRows(config), term);
+  if (!hit) {
+    throw new ToolError(
+      `no synonym or related facts for "${term}" in the memory graph. ` +
+        "This view answers where the store holds mgx:synonym / mgx:relatedTo facts (a corpus import seeds them).",
+    );
+  }
+  const lines = [`${hit.prefLabel} [${hit.conceptId}]`];
+  if (hit.synonyms.length) lines.push(`synonyms (skos:altLabel): ${hit.synonyms.join(", ")}`);
+  if (hit.related.length) lines.push(`related (skos:related): ${hit.related.map((c) => c.prefLabel).join(", ")}`);
+  lines.push("(from the memory graph's mgx:synonym / mgx:relatedTo / mgx:similarTo facts)");
+  return lines.join("\n");
+}
+
+// The memory graph is this tool's only source — it answers with or without a
+// code-map graph, so the shared code-graph load (which refuses an empty graph)
+// must not gate it.
+tmct_related.ownsGraphLoad = true;

package/ROADMAP.md

@@ -1,130 +0,0 @@
-# ROADMAP — tmct's current shape and what's next
-
-Forward-looking at a **feature level**: what tmct is capable of right now, and what's planned next.
-No session narrative, no dated diary, no "shipped/DONE" history — that's what git log and the
-`archive/`/`BENCHMARK_*.md`/`CAPABILITIES_*.md` records are for. For **task-level** pickup (specific
-open items, session-scoped), see `HANDOVER.md` instead — this file doesn't duplicate that list.
-
-## What tmct is
-
-A tolerant, ELIZA/PARRY-style chat surface over a codebase, obsessed with software the way PARRY was
-obsessed with the mafia — deterministic, zero-cost, **no LLM anywhere in the product path**. Guides a
-user toward precision queries rather than guessing; every answer is grounded, restates every genuine
-reading it finds in full, or is an honest miss when nothing grounds it at all. Its visual surfaces —
-the ledger explorer with its in-browser chat (`tmct viz`), the animated plan page
-(`chat --prompt … --render blocks`), and the Pages homepage hero — are the same graph read out loud:
-same engine, same provenance, no LLM.
-
-## Ambition
-
-Declared, forward-looking goals — not yet achieved, stated here so they steer future work instead of
-getting silently traded away by inherited caution:
-
-- **Reach for Llama-3-level natural language fluency.** by growing rich
-  template/surface-realization variety, so an answer shape has many valid phrasings instead of one
-  fixed slot-fill.
-- **Resolve ambiguity breadth-first, always.** Every genuinely valid reading gets its own real answer
-  restated in full, never a bare "could mean X or Y — try rephrasing" punt, bounded only by existing
-  clipping/pagination limits. L
-- **Paraphrase alongside the original, verified, never instead of it.** A surface-realization variant
-  sits next to the literal grounded answer, never replacing it, and its accuracy is checked, not
-  assumed — by running tmct's own deterministic inference/consistency machinery (`src/domain/syllogise.mjs`)
-  against both the original and the paraphrase: they must entail the same conclusions, and neither may
-  contradict the other sentence-by-sentence..
-
-
-## What's next (feature-shaped — see `HANDOVER.md` for the current task-level list)
-
-- **`PLAN_ADVENTURE.md`** — a text-adventure architectural stretch. Its world-state and
-  actions-as-data substrate shipped generically with the planning lane (action rule kinds,
-  per-step board snapshots, legal-move enumeration); what remains its own is the imperative
-  command grammar ("go north", "take the key"), the NPC turn scheduler, the Ashcombe Hall
-  corpus, and the room-look digest.
-- **`PLAN_SYLLOGIST.md`** — the reasoning engine's research horizon. The single-justification
-  retraction slice shipped (`retractSubClassOf`, justification persistence and cascade across all
-  five rules); still open there: the ATMS generalization (alternate justification sets per fact),
-  incremental matching (§2), and relevance under budget (§4).
-- **`PLAN_GUESS_NUMBER.md`** — closed-loop planning over hidden state (belief-interval bisection,
-  thinker-mode secret commitment, observation folding) on top of the shipped planner substrate.
-  Design-only.
-- **`PLAN_CODE.md`** — small JS-function and HTML/CSS-fragment synthesis, plus goal-directed
-  program repair (tests as the goal state, mutation templates as planning actions), via a sandboxed
-  headless browser (Track 1, rule/frame synthesis, already shipped). Blocked on a sandbox
-  dependency decision.
-- **`PLAN_AGENTS.md`** — the governing plan for tmct's broader multi-repo arc (marginalia, seonix,
-  a pluggable LLM rung for Claude Code/Bedrock/Copilot). Check its own sequencing table for current
-  phase status, not this file.
-
-
-## Research horizon
-
-*(2026-07-08 research pass — a direction recorded so it isn't re-discovered from scratch, not a
-committed build plan. Nothing below is scheduled.)*
-
-**Before the horizon — known-how, no research risk**, just scheduling: `PLAN_CODE.md` Tracks 2-4
-(mutation search/repair, JS/HTML/CSS synthesis — APR and CEGIS are established techniques);
-RETE/incremental forward-chaining (`PLAN_SYLLOGIST.md` §2 — Forgy 1982, a citable algorithm not yet
-ported); contingent/conformant planning under initial-state uncertainty (Bonet & Geffner 2000,
-Hoffmann & Brafman 2006, Petrick & Bacchus 2002 all have working algorithms, none yet applied here).
-
-**After the horizon — genuinely unsolved in the field**, named as real research targets with
-citations, not stop signs:
-- **The frame problem / relevance realization** (open-world planning boundary). McCarthy & Hayes
-  1969 named it; Jaeger, Riedl, Djedovic, Vervaeke & Walsh (2024) argue it may not be algorithmically
-  solvable in the general case. Speculative angle: bounded (N+1) goal recognition — recognize
-  declared goal 1..N, or reject to an explicit "escalate" class, via parse-shape membership.
-- **Bounded, incremental, trust-tiered, retraction-safe justification tracking** — `PLAN_SYLLOGIST.md`
-  §3. Doyle's JTMS (1979) and de Kleer's ATMS (1986) solve retraction; DRed/RDFox's Backward-Forward
-  solve incremental Datalog maintenance; nobody's published the combination with tmct's
-  multi-trust-tier, hard-budget requirement. The JTMS-lite slice shipped (one persisted
-  justification per entailed fact, VERIFY-backed retraction, all five rules); the open piece is the
-  ATMS generalization — alternate justification SETS per fact (see that doc's 2026-07-15 addendum).
-- **A shared ~2M-word cross-domain ontology** (general-English + technical/scientific/programming).
-  Merging collides senses of lexically-shared words (`class`, `cache`, `thread`, `field`, `state`)
-  across registers; knowledge-based WSD is real but weaker than supervised/neural WSD (Lesk 1986;
-  Raganato, Camacho-Collados & Navigli, EACL 2017). BabelNet proves cross-resource sense merging is
-  achievable at scale but solves the cross-*lingual*, not cross-*domain*, axis, and carries a
-  non-commercial licence. Speculative angle: mutual disambiguation from already-resolved neighbouring
-  terms in tmct's own closed graph (a bounded reading of Gale/Church/Yarowsky's "one sense per
-  discourse" regularity) — not published anywhere found for this application. Fresh live instance
-  (2026-07-11): `"tail"` (Unix process vs. animal body part) collides under `normFactTerm`'s
-  cross-corpus flattening, `src/adapters/memory/core.mjs:1109-1134`.
-
-**Tier-4: learn-on-miss acquisition**. The strongest
-miss signal tmct can emit: lexicon term recognized, query built cleanly, zero matches anywhere — the
-question was well-formed and the knowledge is simply absent. Web search on the resolved term → clean
-the fetched text into the ACE-OWL controlled grammar → store with source provenance → answer the
-original question, citing what was just learned. Strictly opt-in, offline default inviolable.
-Prerequisites: the provenance-trust policy must extend to `via:"learned:web"`, never silently
-blending web-sourced facts with graph/operator facts.
-
-## Design docs
-
-Every substantial design lives in its own `PLAN_*.md` at the repo root; `archive/` holds the shipped
-and closed ones. This file points to them, it doesn't repeat their content. Each plan states its own
-status in its opening lines — read it there, because a status quoted here would rot.
-
-| Plan | What it's for |
-| --- | --- |
-| [PLAN_ADVENTURE.md](PLAN_ADVENTURE.md) | a text adventure as an architectural stretch: imperative command grammar, NPC turn scheduler, room-look digest |
-| [PLAN_AGENTS.md](PLAN_AGENTS.md) | the governing plan for the multi-repo arc (marginalia, seonix, a pluggable LLM rung), with its own phase sequencing |
-| [PLAN_CHILD_CORPUS.md](PLAN_CHILD_CORPUS.md) | a wider default seed corpus, chosen by age of acquisition |
-| [PLAN_CLASS_QUERY.md](PLAN_CLASS_QUERY.md) | "list/count all X of class Y", reconciled against what already shipped |
-| [PLAN_CODE.md](PLAN_CODE.md) | program synthesis over tmct's closed DSLs, plus JS/HTML/CSS fragments and goal-directed program repair |
-| [PLAN_CONSISTENCY_CHECK.md](PLAN_CONSISTENCY_CHECK.md) | tmct as a consistency service for an LLM tool loop |
-| [PLAN_DIALOGUE_ACTS.md](PLAN_DIALOGUE_ACTS.md) | naming tmct's turn types to ISO 24617-2 dialogue acts, deterministically |
-| [PLAN_EMBEDDINGS.md](PLAN_EMBEDDINGS.md) | the semantic-similarity axis, and the way back to it |
-| [PLAN_GRAPH_SCAN.md](PLAN_GRAPH_SCAN.md) | seed and query cost at `init:xl`/`init:xxl` corpus scale |
-| [PLAN_GUESS_NUMBER.md](PLAN_GUESS_NUMBER.md) | closed-loop planning over hidden state, via belief-interval bisection |
-| [PLAN_MUD.md](PLAN_MUD.md) | persistent, shared tmct worlds over a `server:` memory backend |
-| [PLAN_NLU_BENCHMARKS.md](PLAN_NLU_BENCHMARKS.md) | scoring tmct on the CLINC150 and HWU64 intent sets |
-| [PLAN_OPEN_ITEMS.md](archive/PLAN_OPEN_ITEMS.md) | delivered — the 2.0.3-cycle build order, archived |
-| [PLAN_PARAPHRASE_VERIFICATION.md](PLAN_PARAPHRASE_VERIFICATION.md) | checking a paraphrase against the graph before it prints |
-| [PLAN_PURGE.md](archive/PLAN_PURGE.md) | delivered — promoted the load-bearing code, deleted the dead weight, archived |
-| [PLAN_REPO_INDEX.md](PLAN_REPO_INDEX.md) | tmct grows its own code parsers, ported from seonix |
-| [PLAN_SYLLOGIST.md](PLAN_SYLLOGIST.md) | the reasoning engine's incrementality and retraction horizon |
-| [PLAN_SYLLOGIST_EL_DL.md](PLAN_SYLLOGIST_EL_DL.md) | beyond OWL 2 RL: an EL classifier, then a DL tableau prover |
-
-`SKILL_*.md` docs specify the repeatable measurement and build cycles (the benchmarks, the capability
-audit, the background strategy advisor, plain-prose writing). `HANDOVER.md` is the single
-current-open-items list.