@polycode-projects/the-mechanical-code-talker 1.10.14 → 1.11.5

package/README.md

@@ -114,6 +114,23 @@ tmct> /exit
 **[Try it live in your browser →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/)**
 is a real, interactive chat demo running client-side. Your browser runs the
 actual query engine against a small example codebase, no server, no install.
+The page leads with the **memory ledger**: every fact as a readable sentence,
+drill by clicking the terms inside them, and an in-page chat whose answers
+focus the ledger.
+
+Two more surfaces, both generated by tmct itself:
+
+```bash
+npx tmct viz                          # ledger.html — your own memory as the same
+                                      # readable, self-contained explorer
+npx tmct init
+npx tmct import --file .tmct/imports/games/hanoi-3.txt
+npx tmct chat --prompt 'disk-1 rests on disk-2. disk-2 rests on disk-3.
+  disk-3 rests on peg-a. the goal is that every disk rests on peg-c. solve it.' \
+  --render blocks --output plan.html  # an animated replay of the solved plan
+```
+
+More on the game file and the planner under "Teach it a game" below.
 
 ## How it interprets you
 
@@ -127,65 +144,38 @@ Those triples are statements it can store, retrieve, and answer from later.
 Text that doesn't fit the grammar still gets the tolerant strategies. Nothing
 is rejected for being loose, fuzzy, or misspelled.
 
-**Everyday question shapes.** Bare "what is Commit" (no article) now resolves
-like "what is a commit" for tmct's own vocabulary. "What's model.mjs for" and
-"what's model.mjs about" answer like "what does model.mjs do". "Is Base a
-superclass of Widget" is read as the reverse of "is Widget a subclass of
-Base", the same relationship either way round. "Recent commits" and "the last
-commit" resolve to real dated history, not a literal string miss. Polite or
-indirect framing reaches the same capability as a direct request: "I'd like
-you to remember X" teaches like bare "remember X"; "please tell me about X"
-and "search for X" describe and find exactly as their direct forms do.
-
-**Negation and passive.** "Which modules do *not* import X?" computes a bounded
-**set complement** over the graph. An empty result stays a miss rather than a
-fabricated list (a non-enumerable type, like arbitrary *changes*, is refused
-outright). Reversible-passive questions traverse the right direction:
-"what is imported by Y" and "what does Y import" are understood as opposite
-edges, not the same one.
-
-**Finding by description.** "find me the payment class" searches by type and a
-fuzzy match against the entity's own properties, instead of making you name it
-exactly. It checks the type itself and its subclasses first. Only if nothing
-matches there does it widen to a related type, and when it does, it says so
-plainly rather than presenting the looser match as exact.
-
-**Comparing two things.** "compare TaskController and UserController" or "how
-is TaskController different from UserController" lines up both entities'
-shared and differing edges side by side: *"Comparing TaskController and
-UserController (both Class): inherits [seon:hasSuperType]: TaskController (1)
--> Controller; UserController (1) -> Controller"*. Every row is a real edge
-or attribute from the graph, never a hand-written diff.
-
-**Up-refining to a containing module.** A class rarely has its own
-symbol-precise commit or import record. "who touched TaskController" answers
-from its containing module's real history instead of a confident-looking but
-wrong "nothing touched it".
-
-**Following a list.** tmct remembers the last list it gave you. After
-"which modules import src/core/model.mjs", "which of those are tested" or
-"how many of those" resolves "those"/"them" against that list, not a fresh,
-unresolved pronoun.
-
-**Synonyms and everyday phrasing.** tmct matches many of the words people
-actually use for the same idea, from a curated synonym list plus a filtered
-ConceptNet slice. A slightly different word for the same concept still
-resolves. It also follows a few common sentence shapes: clauses starting with
-*because/although/while*, and conditionals ("if X were removed, what
-breaks"). It flags a question whose premise doesn't hold, too: "why does X
-still import Y" when it no longer does.
-
-**Response finishing.** Before an answer is printed it is segmented into typed
-spans: prose versus *protected* entities, paths, numbers, code, provenance, and
-receipts. A small data-driven grammar pass then runs on the prose spans only,
-under a guard that proves the protected spans came through byte-for-byte. Today
-that pass fixes the a/an article defect. Broader voice and agreement rules are
-implemented but parked until they earn their place on the benchmark.
+On top of that base, tmct reads the shapes people actually use, and each one
+resolves to a real graph traversal or declines honestly:
+
+- everyday question forms: "what is Commit", "what's model.mjs for",
+  "recent commits" as real dated history;
+- polite or indirect framing: "I'd like you to remember X" teaches like bare
+  "remember X";
+- negation as a bounded **set complement**: "which modules do *not* import
+  X?", with an empty result staying a miss, never a fabricated list;
+- reversible passives: "what is imported by Y" and "what does Y import" are
+  opposite edges, not the same one;
+- finding by description: "find me the payment class" checks the type and
+  its subclasses first, and says so plainly when it widens;
+- comparison: "compare TaskController and UserController" lines up both
+  entities' real edges side by side, never a hand-written diff;
+- list follow-ups: after "which modules import src/core/model.mjs",
+  "which of those are tested" resolves against that list;
+- curated synonyms plus a filtered ConceptNet slice, clause openers
+  (*because/although/while*), conditionals, and false-premise flags ("why
+  does X still import Y" when it no longer does).
+
+The full catalog with measured coverage lives in `CAPABILITIES_1.7.3.md` and
+the `BENCHMARK_*.md` reports.
+
+**Response finishing.** Before an answer prints, it is segmented into typed
+spans: prose versus *protected* entities, paths, numbers, code, provenance,
+and receipts. A small data-driven grammar pass runs on the prose spans only,
+under a guard that proves the protected spans came through byte-for-byte.
 
 A frozen regression suite plays out full multi-turn dialogues built from these
-phrasings, at every complexity level this project defines. That ranges from a
-single question up to a messy, typo-ridden real user. Tier-by-tier detail is
-in `HANDOVER.md` and `ROADMAP.md`.
+phrasings, from a single question up to a messy, typo-ridden real user.
+Tier-by-tier detail is in `HANDOVER.md` and `ROADMAP.md`.
 
 ## How it guides you
 
@@ -250,13 +240,7 @@ const memory = await loadMemory(dir);
 const graphService = createCompletionsGraphAdapter(graph, memory);
 
 const { text } = await generateCompletion(dir, "Store", { query: "Store", graph, memory, graphService });
-console.log(text);
-```
-
-```
-Attribute: prose_tokens = memory record store [mgx:hasProseTokens]. Attribute:
-doc = In-memory record store. [seon:hasDoc]. Other matches: src/core/store.mjs
-(Module), loadStore (Function), saveStore (Function), testLoadStore (Function).
+console.log(text);   // prints the same text as the chat answer above
 ```
 
 Full pipeline design in `archive/PLAN_COMPLETIONS.md`.
@@ -328,6 +312,45 @@ proof chain, composed answer) for a caller that wants to consume this
 programmatically rather than read the report. `tmct plan --help` has the full
 flag reference.
 
+## Teach it a game, then ask it to plan
+
+The planner above works over a fixed toolset. This one works over rules you
+teach. A game definition is a plain-text file of controlled English — the
+classes, the pieces, the ordering, and the legal moves as taught action
+rules — with `#` comment lines carrying example prompts. `tmct init`
+scaffolds one at `.tmct/imports/games/hanoi-3.txt`, and
+`tmct import --file` teaches it sentence by sentence, reporting every line
+and refusing (exit 1) if any sentence declines.
+
+Then one message states the board and the goal, and "solve it" searches the
+taught rules for the shortest move sequence:
+
+```
+tmct> disk-1 rests on disk-2. disk-2 rests on disk-3. disk-3 rests on peg-a.
+      the goal is that every disk rests on peg-c. solve it.
+plan found — 7 moves (shortest):
+  1. move disk-1 onto peg-c
+  2. move disk-2 onto peg-b
+  3. move disk-1 onto disk-2
+  4. move disk-3 onto peg-c
+  5. move disk-1 onto peg-a
+  6. move disk-2 onto disk-3
+  7. move disk-1 onto disk-2
+
+because — you taught me the "move onto" rule and 3 ordering facts. Say "next" to make move 1, or ask "what moves are legal now".
+
+Goal (inferred): Plan a move sequence from the current state to the goal (7 moves).
+```
+
+"next" executes one move at a time, writing each board state into memory as
+facts; the final step re-reads those facts and confirms the goal from them,
+never assuming success. The search is genuine and domain-general: the test
+suite teaches Towers of Hanoi purely as sentences for 1 to 8 disks and
+asserts the plan is exactly 2^n − 1 moves every time, and a second game
+(`crates.txt`, stacking crates with different rules and a two-goal
+conjunction) solves with zero interpreter changes. `--render blocks` writes
+the plan as a self-contained animated page (see "Two more surfaces" above).
+
 ## How it remembers
 
 tmct's memory has two layers, both fed by every parsed request and response and
@@ -359,38 +382,21 @@ reasoning). Design detail and the full fact-count tables are in `archive/PLAN_SE
 The default memory backend writes an OWL-labelled JSON file under `.tmct/`.
 Two more exist: `memory` keeps taught facts in the process only, nothing
 written to disk; `sqlite` persists them to a local SQLite file instead
-(`.tmct/memory/graph.sqlite`).
-
-Pick one at init time and it sticks. `tmct init --memory-backend sqlite`
-writes the choice into `tmct.toml`, and every later `tmct chat` in that repo
-uses it with no flag needed:
-
-```bash
-tmct init --memory-backend sqlite     # writes [memory] backend = "sqlite" to tmct.toml
-tmct chat                             # picks it up automatically
-tmct chat --memory-backend memory     # override for just this session
-```
-
-Precedence is `--memory-backend` flag > `TMCT_MEMORY_BACKEND` env > tmct.toml's
-`[memory] backend` > the default. A library caller sets the same thing
-directly: `runChat({ memoryBackend: "sqlite" })`.
+(`.tmct/memory/graph.sqlite`). `tmct init --memory-backend sqlite` writes the
+choice into `tmct.toml` and every later `tmct chat` in that repo picks it up.
+Precedence is `--memory-backend` flag > `TMCT_MEMORY_BACKEND` env >
+tmct.toml's `[memory] backend` > the default. A library caller sets the same
+thing directly: `runChat({ memoryBackend: "sqlite" })`.
 
 Teaching isn't limited to the ACE grammar's fixed shapes. Tell tmct an
 arbitrary fact, like "margo really eats ribs", and it mints a fact you can
-later ask about directly: "what does margo eat", or "does margo eat ribs".
-
-New vocabulary compounds as you teach it. "redis is a cache" mints "redis" as
-a class-level concept even though it was never in the built-in lexicon, and a
-later "every cache is a store" does the same for "store," the other way
-round, as long as one side of the sentence is already grounded. tmct never
-mints a fact between two totally ungrounded terms. It declines instead, and
-nudges you to ground one side first. Quantified teaching works too: "some
-functions are risky" stores the quantifier, and a later "how many functions
-are risky" answers "A few."
-
-Once you've taught a few facts, "how many facts are there" counts them back.
-That's the same count phrasing a code graph answers "how many classes are
-there" with, just now reading tmct's own memory.
+ask about directly: "what does margo eat". New vocabulary compounds as you
+teach: "redis is a cache" mints "redis" even though it was never in the
+built-in lexicon, as long as one side of the sentence is already grounded —
+tmct never mints a fact between two totally ungrounded terms; it declines and
+nudges you to ground one side first. Quantified teaching stores the
+quantifier ("some functions are risky" … "how many functions are risky" →
+"A few."), and "how many facts are there" counts the store back.
 
 ### Provenance and trust
 
@@ -410,10 +416,8 @@ provenance** rather than silently picking a winner.
 
 `tmct syllogise [--depth n] [--budget n]` is an offline, bounded, deterministic
 batch that forward-chains the memory's `rdfs:subClassOf` closure into new
-**entailed** facts, pre-deriving what the trusted sources already imply. It runs
-once automatically after seeding and on demand; the entailed facts are
-**low-trust and retractable** (never outranking a stated fact) and this never runs
-on the chat's hot path.
+**entailed** facts. They are low-trust and retractable, never outranking a
+stated fact, and this never runs on the chat's hot path.
 
 ## Install & use
 
@@ -423,7 +427,7 @@ tmct                                  # bare = chat (the headline)
 tmct chat --repo /abs/path/to/repo    # chat over a specific repo's graph
 tmct init                             # scaffold .tmct/, tmct.toml, seed + provenance
 tmct syllogise                        # offline: pre-derive entailed facts (maintenance)
-npm run viz -- --output graph.html && open graph.html   # self-contained HTML graph view
+npm run viz && open ledger.html       # self-contained HTML memory-ledger explorer
 ```
 
 Inside the chat: `/help` lists commands, `/memory` inspects what tmct remembers
@@ -461,6 +465,11 @@ Usage:
                                see src/graph-merge.mjs); wins over --repo/TMCT_GRAPH_FILE/tmct.toml
        [--config <path>]       an alternate tmct.toml location (a file or a directory)
        [--ephemeral]           read the graph but write nothing back (demo/read-only)
+       [--prompt "<text>"]     one-shot: run the prompt's sentences as turns and print
+                               the final answer (teach state first, trigger last)
+       [--render blocks]       with --prompt: when the final turn produced a plan,
+                               write it as a self-contained animated page
+       [--output <path>]       the rendered page's path (default plan.html)
        [--narrate]             start with narrate mode on — a verbose, developer-facing
                                trace of decision points/matched pattern/results/goal per
                                turn, appended under a "--- narrate ---" marker (also
@@ -518,6 +527,9 @@ already set up. Its `--graph` flag works differently from the others: it appends
        [--ontology <name|path>]  DIFFERENT operation from the others: it APPENDS to
        [--lexicon <name|path>]   tmct.toml's graph_files array (multi-graph growth),
        [--graph <path>]        never an extensions-bundle activation.
+       [--file <definition.txt>]  teach a plain-text definition file sentence by
+                               sentence (# lines are comments); any declined
+                               sentence exits non-zero with the sentence named
        [--memory-backend <default|memory|sqlite>]  same knob as `tmct init`
        [--config <path>]
 ```
@@ -540,23 +552,18 @@ inference" above:
        [--config <path>]      bounded, low-trust, retractable entailed facts (never on the chat path)
 ```
 
-`tmct viz` renders the memory graph to a single HTML file you can open in a browser:
+`tmct viz` renders the memory graph as the ledger explorer — a single,
+self-contained HTML file you can open in a browser:
 
 ```
-  tmct viz [--repo <abs>]      write one self-contained, navigable HTML file rendering the
-       [--focus <id>]         memory graph: pan/zoom, click a node for its label/class/
-       [--term <word>]        timestamps. Seeds from the most recently created individual
-       [--depth <n>]          by default (--focus <id> or --term <word> override it);
-       [--limit <n>]          --output defaults to graph.html in the cwd.
-       [--hub-degree <n>]     --depth = max arcs (hops) from the focus node (default 3);
-       [--edge-kind <mode>]   --limit = spiral length, total nodes walked (default 300);
-       [--output <path>]      --hub-degree = stop expanding THROUGH a node above N
-       [--config <path>]      connections, still shows it (default 40); --edge-kind =
-                               meta|relation|both (default both) — which edge kinds the
-                               walk follows (provenance-only, concept-relations-only, or
-                               both — see the page's own edge-kind toggle to change this
-                               live); --term <word> resolves to the Fact(s) whose subject/
-                               object normalizes to that word and seeds from there.
+  tmct viz [--repo <abs>]      write one self-contained HTML page: the memory graph as a
+       [--focus <term>]       readable ledger of fact-sentences around one focus term,
+       [--term <word>]        with segments, a two-hop minimap, and an in-page chat dock
+       [--limit <n>]          that answers from the embedded graph. Focuses on the newest
+       [--output <path>]      taught fact's subject by default (--focus <term> or
+       [--config <path>]      --term <word> override it); --output defaults to
+                               ledger.html in the cwd; --limit caps the embedded fact
+                               rows; --term resolves via the same normalization chat uses.
 ```
 
 `tmct serve` runs an Anthropic Messages API-compatible HTTP endpoint over the graph,
@@ -606,7 +613,7 @@ recognized key set, so you can see the full surface in one place
 # Newline-delimited-file form is also accepted: repositories = "repos.txt"
 repositories = ["../other-service", "../another-service"]
 
-# Where generated output (e.g. tmct viz's default graph.html) resolves to.
+# Where generated output (e.g. tmct viz's default ledger.html) resolves to.
 out_root = "./out"
 
 # The code-graph JSON artifact. TMCT_GRAPH_FILE overrides this at runtime.

package/ROADMAP.md

@@ -10,7 +10,10 @@ open items, session-scoped), see `HANDOVER.md` instead — this file doesn't dup
 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.
+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
 
@@ -48,9 +51,16 @@ getting silently traded away by inherited caution:
   and an NPC turn scheduler. Design-only.
 - **`PLAN_SYLLOGIST.md`** — retraction-aware consistency checking under a hard budget and trust
   tiers, the one open piece of the reasoning engine's research horizon. Design-only.
-- **`PLAN_GUESS_NUMBER.md` / `PLAN_HANOI.md`** — closed-loop and open-loop planning domains for the
-  `findActionPath`/`findReachableSet` kernels, both already built and proven but not yet wired to
-  either domain. Design-only.
+- **`PLAN_HANOI.md`** — shipped in full, including the follow-ups: river-crossing (co-travel
+  effects, the forbidden-together constraint frame, 7-crossing oracle) and planner-side
+  consumption of `taught:` capability records (`/plan` in chat and bin). See its dated addenda.
+- **`PLAN_GUESS_NUMBER.md`** — the closed-loop (observe-and-replan) planning domain for the same
+  kernels. Design-only.
+- **`PLAN_VIZ_LEDGER.md`** — shipped in full, including the follow-ups, all resolved by
+  operator decision 2026-07-15: the ledger IS the `tmct viz` surface (node-link page removed),
+  `factAnswer`/`factReadBack` carry the additive `goal` field the dock renders, multi-valued
+  has/can facts are exempt from `findContradictions`, and page weight is budgeted (~561 KB
+  after this batch; revisit only if outgrown). See its dated addendum.
 - **`PLAN_CODE.md`** — small JS-function and HTML/CSS-fragment synthesis via a sandboxed headless
   browser (Track 1, program synthesis, already shipped). Blocked on a sandbox dependency decision.
 - **`PLAN_AGENTS.md`** — the governing plan for tmct's broader multi-repo arc (marginalia, seonix,