@polycode-projects/the-mechanical-code-talker 1.9.2 → 1.10.0

package/bin/tmct.mjs

@@ -103,6 +103,14 @@ Usage:
        [--host <h>] [--port <n>]  (POST /v1/messages) over the graph — a deterministic,
        [--graph <path>]        no-LLM "model" a tool-loop client can call; $0 usage.
        [--config <path>]       Defaults: host 127.0.0.1, port 8787. Ctrl+C to stop.
+  tmct plan "<request>"        the capability router: compose/execute read-only graph-
+       [--repo <abs>]          query tool calls for a compound or maintenance-goal
+       [--graph <path>]        request ("of the modules impacted by X, which are
+       [--config <path>]       untested", "what most needs a test") — a real STRIPS/
+       [--tools <a,b,...>]     PDDL planner (src/router/*), never a guessed call.
+       [--json]                Prints the grounded step sequence + composed answer,
+                               or an honest "no plan found". --tools restricts the
+                               declared toolset; --json prints the full loop result.
   tmct cli <tool> '{…}'        invoke a graph tool directly (carry-over, de-emphasized)
   tmct cli digest '{…}'        architecture map + per-module context bundles
   tmct --help                  show this help
@@ -658,6 +666,22 @@ async function main() {
       process.stderr.write(`tmct init: ${e?.message || e}\n`);
       process.exit(2);
     }
+    // `init` takes no positional argument at all, so a bare "sqlite"/"memory"/
+    // "default" here almost always means `npm run init --memory-backend X`
+    // was typed without the `--` separator npm needs — npm silently drops its
+    // own unrecognized flag and forwards only the bare word.
+    if (!memoryBackendVal) {
+      const strayBackendWord = rest.find((a) => ["default", "memory", "sqlite"].includes(a));
+      if (strayBackendWord) {
+        process.stderr.write(
+          `tmct init: read a bare "${strayBackendWord}" as --memory-backend ${strayBackendWord} — ` +
+          `npm likely dropped your --memory-backend flag because "npm run init --memory-backend ${strayBackendWord}" ` +
+          `needs a "--" before it: npm run init -- --memory-backend ${strayBackendWord} (or npm run init:sqlite, ` +
+          `or npx tmct init --memory-backend ${strayBackendWord} directly).\n`,
+        );
+        memoryBackendVal = strayBackendWord;
+      }
+    }
 
     // Resolve + validate EVERY pluggable input BEFORE touching disk — mirrors
     // `--with-persona`'s own "validate before scaffolding" discipline, and the
@@ -1079,6 +1103,107 @@ async function main() {
     return; // the listening server keeps the event loop alive
   }
 
+  if (mode === "plan") {
+    // `tmct plan "<request>"` — the capability router (src/router/*), surfaced
+    // for real: a STRIPS/PDDL-style planner over the SAME read-only graph-query
+    // tools chat/serve dispatch. A single-shot request ("who calls X") resolves
+    // directly; a compound request ("of the modules impacted by X, which are
+    // untested", "assess Y and then check Z") decomposes into an ordered call
+    // sequence with a causal-link proof, then folds the executed results into one
+    // composed answer; a request neither stage grounds escalates to the
+    // closed-world goal-reasoner (a maintenance-invariant deduction — coverage
+    // gaps, change-coupling risk — never a keyword guess). Anything none of the
+    // three grounds is an HONEST "no plan found", never a guessed call — same
+    // "grounded or an honest miss" contract as every other tmct answer path.
+    const rest = process.argv.slice(3);
+    if (rest.includes("--help") || rest.includes("-h")) {
+      process.stdout.write(
+        "tmct plan \"<request>\" — the capability router: compose/execute read-only\n" +
+        "graph-query tool calls for a compound or maintenance-goal request.\n\n" +
+        "Usage:\n" +
+        "  tmct plan \"<request>\" [--repo <abs>] [--graph <path>] [--config <path>]\n" +
+        "       [--tools <name,name,...>] [--json]\n\n" +
+        "  --repo <abs>     target a repo's graph (<abs>/.tmct/graph.json); default: git root/cwd\n" +
+        "  --graph <path>   explicit graph file (repeatable — multiple graphs merge)\n" +
+        "  --config <path>  an alternate tmct.toml location (a file or a directory)\n" +
+        "  --tools <list>   restrict the declared toolset (comma-separated capability\n" +
+        "                   names, e.g. tmct_impact,tmct_untested); default: every\n" +
+        "                   registered capability\n" +
+        "  --json           print the full machine-readable loop result instead of\n" +
+        "                   the human-readable report (a non-zero exit still means\n" +
+        "                   an honest refusal, not a crash)\n\n" +
+        "Examples:\n" +
+        "  tmct plan \"of the modules impacted by src/lib/http.mjs, which are untested\"\n" +
+        "  tmct plan \"what most needs a test in this codebase\"\n" +
+        "  tmct plan \"who calls createApp\"\n",
+      );
+      return;
+    }
+    const { strFlag, resolveRuntimeConfig } = await import("../src/cli-args.mjs");
+    const toolsFlag = strFlag(rest, ["--tools"]);
+    const jsonFlag = rest.includes("--json");
+    // The request is every argv token that isn't a recognized flag or its value,
+    // rejoined with single spaces — so both `tmct plan "quoted request"` and a
+    // bare `tmct plan unquoted request words` work.
+    const FLAG_WITH_VALUE = new Set(["--repo", "--graph", "--config", "--tools"]);
+    const requestParts = [];
+    for (let i = 0; i < rest.length; i += 1) {
+      const a = rest[i];
+      if (FLAG_WITH_VALUE.has(a)) { i += 1; continue; }
+      if (a === "--json") continue;
+      requestParts.push(a);
+    }
+    const request = requestParts.join(" ").trim();
+    if (!request) {
+      process.stderr.write("tmct plan: needs a request, e.g. `tmct plan \"of the modules impacted by X, which are untested\"`\n");
+      process.exit(2);
+    }
+    const { config } = await resolveRuntimeConfig({ argv: rest });
+    const { buildCapabilityPlanCtx, runCapabilityPlan, declaredCapabilityNames } = await import("../src/router/drive.mjs");
+    const declared = declaredCapabilityNames();
+    let tools = declared;
+    if (toolsFlag) {
+      tools = toolsFlag.split(",").map((s) => s.trim()).filter(Boolean);
+      const unknown = tools.filter((t) => !declared.includes(t));
+      if (unknown.length) {
+        process.stderr.write(`tmct plan: unknown --tools name(s): ${unknown.join(", ")}. Registered capabilities: ${declared.join(", ")}.\n`);
+        process.exit(2);
+      }
+    }
+    let ctx;
+    try {
+      ctx = await buildCapabilityPlanCtx({ config });
+    } catch (e) {
+      process.stderr.write(`tmct plan: could not load the graph — ${e?.message || e}\n`);
+      process.exit(1);
+    }
+    const result = await runCapabilityPlan(request, tools, ctx);
+    if (jsonFlag) {
+      process.stdout.write(JSON.stringify({ request, ...result }, null, 2) + "\n");
+      process.exit(result.refused ? 1 : 0);
+    }
+    process.stdout.write(`tmct plan: "${request}"\n`);
+    if (result.refused) {
+      process.stdout.write(`no plan found — ${Array.isArray(result.why) ? result.why.join("; ") : result.why}\n`);
+      if (result.c1Why) {
+        process.stdout.write(`(the direct router also declined: ${Array.isArray(result.c1Why) ? result.c1Why.join("; ") : result.c1Why})\n`);
+      }
+      process.exit(1);
+    }
+    process.stdout.write(`driver: ${result.driver}\n\nsteps:\n`);
+    for (let i = 0; i < result.calls.length; i += 1) {
+      const c = result.calls[i];
+      let text = "";
+      try { text = await ctx.dispatch(c.name, c.input || {}).then((r) => (r.ok ? r.text : `(unresolved: ${r.error})`)); }
+      catch (e) { text = `(error: ${e?.message || e})`; }
+      process.stdout.write(`  ${i + 1}. ${c.name} ${JSON.stringify(c.input || {})}\n     ${String(text).split("\n").join("\n     ")}\n`);
+    }
+    if (result.composed !== undefined && result.composed !== null) {
+      process.stdout.write(`\ncomposed answer (${result.composed.length}): ${result.composed.length ? result.composed.join(", ") : "(empty set)"}\n`);
+    }
+    return;
+  }
+
   if (mode === "cli") {
     await runCliMode();
     return;
@@ -1087,7 +1212,7 @@ async function main() {
   // An unknown mode gets the instructive usage line and exit 2. (A bare invocation
   // never lands here — the argv splice above rewrote it to `chat`.)
   process.stderr.write(`tmct: unknown invocation "${process.argv.slice(2).join(" ")}". ` +
-    "Use `chat`, `memory`, `init`, `import`, `extend --validate`, `syllogise`, `serve`, `cli digest …`, or `cli <tool> …`.\n");
+    "Use `chat`, `memory`, `init`, `import`, `extend --validate`, `syllogise`, `serve`, `plan`, `cli digest …`, or `cli <tool> …`.\n");
   process.exit(2);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "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.",
@@ -58,7 +58,8 @@
     "./extensions": "./src/extensions.mjs",
     "./toml-config": "./src/toml-config.mjs",
     "./generateCompletion": "./src/completions/complete.mjs",
-    "./createCompletionsGraphAdapter": "./src/completions/graph-adapter.mjs"
+    "./createCompletionsGraphAdapter": "./src/completions/graph-adapter.mjs",
+    "./plan": "./src/router/drive.mjs"
   },
   "files": [
     "bin/",
@@ -85,6 +86,7 @@
     "chat": "node bin/tmct.mjs",
     "chat:repo": "node bin/tmct.mjs chat --repo",
     "init": "node bin/tmct.mjs init",
+    "init:sqlite": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init --memory-backend sqlite",
     "init:persona:human": "node bin/tmct.mjs init --with-persona human",
     "init:persona:empty": "node bin/tmct.mjs init --with-persona empty",
     "init:large": "node bin/tmct.mjs init && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java",

package/src/answer-variants.mjs

@@ -1,33 +1,10 @@
-// answer-variants.mjs — deterministic, committed answer-phrasing variety
-// ("wiring the generated corpus into the live answer path", ROADMAP.md's
-// What's next item / archive/PLAN_TEMPLATE_COVERAGE.md's stated follow-on).
+// answer-variants.mjs — deterministic, committed answer-phrasing variety for
+// a curated set of answer templates (answer-variants.json).
 //
-// A SMALL, curated, committed table (answer-variants.json) of safe cosmetic/
-// locational/connector-word rephrasings for a deliberately narrow set of
-// answer templates in ask.mjs/chat.mjs -- never a relation verb (imports/
-// calls/tests/inherits/touches), never an entity id/label/path, never a miss/
-// rephrase-hint template. Each pool was hand-reviewed for meaning-safety in
-// its SPECIFIC rendered sentence (see answer-variants.json's own "curation"
-// field) -- WordNet was consulted but its sense-1 lookups mostly resolved to
-// the wrong sense for this domain-specific connector vocabulary, so nothing
-// here was auto-accepted from a raw synset match.
-//
-// Selection is a pure hash, never Math.random/Date.now: the SAME (poolId, key)
-// always picks the SAME form, so the same query against the same entity
-// renders byte-identical text every time (pinnable in tests), while different
-// entities/answers spread across the pool's forms. This is the ONE place that
-// hash-and-pick logic lives -- every call site below imports pickPhrase
-// rather than re-deriving its own index arithmetic.
-//
-// Lazy + failure-tolerant load (chat.mjs's own "a turn never crashes" ethos,
-// see chatTemplates()): a missing/corrupt data file, or `node:fs` simply
-// being unavailable, degrades to always returning `base` -- never a throw.
-// That second case is load-bearing, not theoretical: ask.mjs is bundled
-// whole into the browser "Ask the graph" panel (scripts/build-ask-bundle.mjs
-// stubs node:fs's readFileSync as a function that THROWS when called, so the
-// browser bundle still boots; this module's readFileSync call only ever
-// happens lazily inside pickPhrase, wrapped in try/catch, exactly so that
-// throw is caught here and never reaches the caller.
+// Selection is a pure hash of (poolId, key), never Math.random/Date.now, so
+// output is byte-identical across runs (pinnable in tests). Load is lazy and
+// failure-tolerant (missing file, or a stubbed node:fs in the browser bundle,
+// both degrade to returning `base`) rather than throwing.
 
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -48,13 +25,8 @@ function loadData() {
 }
 
 /** Deterministically choose `base` or one of `poolId`'s committed variants,
- *  keyed on `key` -- pass something stable that identifies THIS specific
- *  answer (an entity's own `id` for entity-anchored templates; any other
- *  stable string, e.g. a graph-summary key, for templates with no single
- *  entity). Same (poolId, key) always returns the same string; an unknown
- *  pool, a missing/unreadable data file, or a falsy `key` all fall back to
- *  `base` unconditionally -- variety is strictly additive, never a way to
- *  lose the original wording. */
+ *  keyed on `key`. Any failure (unknown pool, unreadable data, falsy `key`)
+ *  falls back to `base`. */
 export function pickPhrase(poolId, key, base) {
   if (!key) return base;
   const data = loadData();

package/src/ask-browser-entry.mjs

@@ -1,18 +1,7 @@
 // ask-browser-entry.mjs — the esbuild entry for `tmct viz`'s embedded "Ask the
-// graph" chat panel (PLAN_BREADTH_FIRST_NLU.md §5 follow-on, operator directive
-// 2026-07-11: a real NL chat running client-side against the embedded graph,
-// via tmct's OWN JS engine — not reimplemented, not a stub).
-//
-// Precedent: seonix's own `src/ask-browser-entry.mjs` (PLAN_CHAT_EXTRACTION.md
-// Stage 5) proved this exact approach in production — esbuild + a Node-builtin
-// stub plugin bundles tmct's real ask() into a single browser IIFE. This entry
-// mirrors that pattern, adapted for tmct bundling its OWN ask.mjs directly
-// (no external package import needed — we're already inside the source tree)
-// and extended with the graph-traversal exports `tmct viz`'s own client-side
-// re-focus/re-walk needs (spiralExpand etc. — seonix's code-graph viewer
-// recomputes depth with its own hand-rolled client-side BFS; tmct's viewer
-// reuses the real spiralExpand instead, so the browser walk is byte-identical
-// to the CLI's).
+// graph" chat panel: a real NL chat running client-side against the embedded
+// graph, via tmct's own JS engine (esbuild + a Node-builtin stub plugin
+// bundles tmct's real ask() into a single browser IIFE).
 //
 import { ask, parseQuery } from "./ask.mjs";
 import {
@@ -21,15 +10,8 @@ import {
   edgeKindsFor, collapseToTopN,
 } from "./codegraph.mjs";
 
-// PLAN_VIZ_MEMORY.md Bug 2 fix + Controls port: deriveFactTermGraph/
-// pickLegendDimension/legendValueFor/MEMORY_FACT_LINK_KINDS/edgeKindsFor/
-// collapseToTopN are exported here (alongside the pre-existing traversal
-// exports) so the viewer page's client-side recentre/edge-kind-toggle/
-// dimension-switcher (a user double-clicking a node, changing which edge
-// kinds the walk follows, or flipping the legend from "split by predicate"
-// to "split by trust source") re-derives the SAME term graph, kind set, and
-// legend the CLI's own generation-time computeVizGraph used — never a second
-// hand-rolled copy that could drift.
+// Exported so the viewer page's client-side recentre/edge-kind-toggle/
+// dimension-switcher reuses the same computation as the CLI, not a second copy.
 globalThis.tmctViz = {
   ask, parseQuery, parseEntities, spiralExpand, mostRecentIndividual, derivedUpdatedAt,
   MEMORY_SPIRAL_EXPAND_KINDS, MEMORY_FACT_LINK_KINDS, buildVizNodesAndEdges,

package/src/ask-browser.bundle.js

@@ -1837,8 +1837,7 @@
     //   (neither recognizes the bare "is in" idiom once "else" sits in front of it).
     //   The only rescue was the relaxation cascade's drop-unmatched layer — but that
     //   layer refuses to accept a relaxed reading that still renders an honest EMPTY
-    //   (by design: relaxation must turn a miss into a real answer, never into
-    //   another kind of miss), so a genuinely empty class ("what else is in
+    //   , so a genuinely empty class ("what else is in
     //   Task.complete" — a method, no members) bottomed out at the bare grammar
     //   wall instead of the specific "no contains edges" receipt. Routing this
     //   frame onto the SAME direct "what does X contain" path the plain "what is

package/src/ask-nlp.mjs

@@ -1,18 +1,11 @@
-// ask-nlp.mjs — the OPTIONAL wink-nlp adapter behind ask.mjs's lemma/POS tier.
-//
-// wink-nlp and wink-eng-lite-web-model are loaded through the shared leaf loader
-// src/wink-model.mjs (Node `createRequire` fallback + a browser registration seam),
-// so this file no longer carries its own Node-only load block. The load happens
-// lazily on first use and failure is cached as null: a checkout without the optional
-// deps installed answers exactly like the browser bundle, it never throws.
+// ask-nlp.mjs — the optional wink-nlp adapter behind ask.mjs's lemma/POS tier.
+// Loaded lazily via src/wink-model.mjs; failure is cached as null, never a throw.
 
 import { winkInstance } from "./wink-model.mjs";
 
-let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
+let cached; // undefined = not tried yet; null = unavailable
 
-/** Lazily build the {lemma, posTags} adapter, or null when wink isn't loadable.
- *  Deterministic: wink-nlp's tagger/lemmatiser is a fixed model with no sampling,
- *  so the same input always yields the same tags/lemmas across processes. */
+/** Lazily build the {lemma, posTags} adapter, or null when wink isn't loadable. */
 export function nlpAdapter() {
   if (cached !== undefined) return cached;
   try {
@@ -20,8 +13,7 @@ export function nlpAdapter() {
     if (!nlp) { cached = null; return cached; }
     const its = nlp.its;
     cached = {
-      /** Lowercase lemma of a single token ("imported" -> "import"); the word
-       *  itself when wink has nothing better (unknown words come back as-is). */
+      /** Lowercase lemma of a single token ("imported" -> "import"). */
       lemma(word) {
         const w = String(word || "");
         try {
@@ -31,12 +23,7 @@ export function nlpAdapter() {
           return w.toLowerCase();
         }
       },
-      /** True when wink's lexicon flags the word as an English stop word
-       *  ("anyway", "well", "also", …). Consulted by the noise-strip strategy
-       *  (interpret/strategies/noise-strip.mjs) as its wink tier — the strategy's
-       *  own KEEP set screens out the grammar's load-bearing words (which/what/
-       *  does/…) BEFORE this is asked, so wink flagging a question word is
-       *  harmless by construction. False on any surprise, never a throw. */
+      /** True when wink's lexicon flags the word as an English stop word. */
       isStopWord(word) {
         try {
           const out = nlp.readDoc(String(word || "")).tokens().out(its.stopWordFlag);
@@ -45,10 +32,9 @@ export function nlpAdapter() {
           return false;
         }
       },
-      /** UPOS tags aligned to the CALLER's word array. wink re-tokenizes (it
-       *  splits "walk.mjs" into three tokens), so each input word is greedily
-       *  matched to the run of wink tokens that spell it and takes its FIRST
-       *  sub-token's tag; null per word on any surprise, never a throw. */
+      /** UPOS tags aligned to the caller's word array. wink re-tokenizes, so
+       *  each input word is greedily matched to the run of wink tokens that
+       *  spell it and takes its first sub-token's tag. */
       posTags(words) {
         try {
           const toks = nlp.readDoc(words.join(" ")).tokens();