@polycode-projects/the-mechanical-code-talker 1.12.0 → 2.0.2

package/corpus/README.md

@@ -2,7 +2,7 @@
 
 The corpuses tmct ships so that an **empty** tmct still has a vocabulary
 (ROADMAP Phase 2). Everything here is plain, diffable data; the loaders live
-in `src/corpus/`. Related committed data lives in `data/` (response templates
+in `src/adapters/corpus/`. Related committed data lives in `data/` (response templates
 + the SE phrase book — items 4+7).
 
 ## The tiering policy (tier-1 / tier-2 / tier-3)
@@ -13,7 +13,7 @@ tmct's knowledge arrives in three tiers, distinguished by **when** it lands and
 | Tier | What | Ships in the package? | Lands when | Provenance |
 |---|---|---|---|---|
 | **1 — base** | the general English/tech ConceptNet slice + the response templates + the SE phrasebook — the vocabulary every tmct has out of the box | **yes**, committed here | `tmct init` seeds `.tmct/` from committed data (offline, $0) | `corpus:conceptnet /r/…` |
-| **2 — specialised** | LANGUAGE- or DOMAIN-specific fact sets (`aws`, `python`, `java`) plus one deliberately NON-code-domain "wider general-knowledge" bundle (`general`) so tmct can "expand into a concept for an applicable codebase" — or into a seed set that isn't code at all | **no** — selected per repo | activated via `src/extensions.mjs`'s `[extensions.tier2-<id>] active = true` (or `tmct init --corpus <id>`), inactive by default | `corpus:tier2-<id> /r/…` |
+| **2 — specialised** | LANGUAGE- or DOMAIN-specific fact sets (`aws`, `python`, `java`) plus one deliberately NON-code-domain "wider general-knowledge" bundle (`general`) so tmct can "expand into a concept for an applicable codebase" — or into a seed set that isn't code at all | **no** — selected per repo | activated via `src/services/extensions.mjs`'s `[extensions.tier2-<id>] active = true` (or `tmct init --corpus <id>`), inactive by default | `corpus:tier2-<id> /r/…` |
 | **3 — learned** | facts tmct writes from the actual conversation / the actual codebase it is pointed at | never committed | at runtime, into `.tmct/memory/` | `chat:…`, `codegraph:…` |
 
 **Offline / $0 is the default at every tier.** Tier-1 is committed. Tier-2's
@@ -29,6 +29,10 @@ loudly instead of seeding garbage.
 
 ## What's here
 
+`LICENSES.json` in this directory is the machine-readable rollup of the table
+below — one entry per corpus family ({path, upstream, license, shareAlike,
+notice}), guarded by `test/estate/corpus-licences.test.mjs`.
+
 | Path | What | Size | Licence |
 |---|---|---|---|
 | `conceptnet/slice.jsonl` | tier-1: filtered English/tech-domain ConceptNet 5.7 slice, quality-filtered (one assertion per line) | ~1.35 MB | **CC-BY-SA 4.0** (see `conceptnet/LICENSE-NOTICE`) |
@@ -39,9 +43,9 @@ loudly instead of seeding garbage.
 | `tier2/manifest.json` | tier-2: index of specialised corpuses (id, kind, description, source, sha256, size) | — | MPL-2.0 |
 | `tier2/generate.mjs` | tier-2: the curated-corpus generator + manifest writer (+ opt-in network-fetch path) | — | MPL-2.0 |
 | `tier2/{aws,python,java,general}.jsonl` | tier-2 SAMPLE corpuses — same fact shape as the tier-1 slice, loadable via the same path (`general` is the one deliberately non-code-domain bundle) | ~4-6 KB each | MPL-2.0 |
-| `tier2/human.jsonl` | the DEFAULT active bundle (archive/PLAN_SEED.md): the everyday "human-world" persona, Small tier (664 facts) — hand-curated from Open English WordNet, bridged to Schema.org's top-level classes (archive/PLAN_SEED.md §3, §8) | ~80 KB | MPL-2.0 (hand-authored fact set; not a verbatim WordNet/Schema.org excerpt — see `tier2/generate.mjs`'s own header comment) |
-| `tier2/human-medium.jsonl` / `tier2/human-large.jsonl` | SIZE tiers of the SAME `human` bundle (archive/PLAN_SEED.md §3) — each holds ONLY the facts that size adds beyond the previous one; both shipped INACTIVE by default, activated via `tmct init --persona-size medium\|large`. Built by `scripts/build-persona-tiers.mjs` from the same WordNet source, automatically curated (sense-ranked, blocklist/denylist-filtered) rather than hand-typed one at a time, given the scale (944 / ~12,000 facts) | ~111 KB / ~1.4 MB | MPL-2.0 (same "hand-authored in homage to the source's shape" basis as `human.jsonl`) |
-| `tier2/human-examples.jsonl` / `tier2/human-examples-medium.jsonl` / `tier2/human-examples-large.jsonl` | the example-sentence corpus (archive/PLAN_SEED.md §9) — real natural-language sentences mapped to the same curated vocabulary, NOT fact triples. Small/Medium tiers are 100% WordNet's own inline `example:` field (same CC-BY-4.0 basis as the fact bundles). Large tier ALSO includes a SemCor-filtered supplement (real Brown Corpus text, re-tagged to modern OEWN senses) for categories where WordNet's own inline coverage is thin (`human-nature` especially — `noun.animal.yaml`'s inline rate is under 1%, archive/PLAN_SEED.md §9's own measurement) | ~11 KB / ~43 KB / ~257 KB | **The WordNet-inline entries**: CC-BY-4.0 (Princeton WordNet + Open English WordNet team), reproduced verbatim (these ARE the source's own example sentences, not a paraphrase). **The `source: "semcor:…"` entries**: CC-BY-4.0 per this SemCor fork's own `LICENSE.md` (`~/projects/globalwordnet/semcor/`, real Brown Corpus text re-tagged to modern senses — the original 1960s Brown Corpus permissions aren't independently re-verified beyond that fork's own license statement; proceeding with attribution was an explicit operator decision, archive/PLAN_SEED.md §9) — each entry's own `source` field names its origin file (`semcor:<genre>/<file>.yaml`) for exactly this reason |
+| `tier2/human.jsonl` | the DEFAULT active bundle: the everyday "human-world" persona, Small tier (664 facts) — hand-curated from Open English WordNet, bridged to Schema.org's top-level classes | ~80 KB | MPL-2.0 (hand-authored fact set; not a verbatim WordNet/Schema.org excerpt — see `tier2/generate.mjs`'s own header comment) |
+| `tier2/human-medium.jsonl` / `tier2/human-large.jsonl` | SIZE tiers of the SAME `human` bundle — each holds ONLY the facts that size adds beyond the previous one; both shipped INACTIVE by default, activated via `tmct init --persona-size medium\|large`. Built by `scripts/build-persona-tiers.mjs` from the same WordNet source, automatically curated (sense-ranked, blocklist/denylist-filtered) rather than hand-typed one at a time, given the scale (944 / ~12,000 facts) | ~111 KB / ~1.4 MB | MPL-2.0 (same "hand-authored in homage to the source's shape" basis as `human.jsonl`) |
+| `tier2/human-examples.jsonl` / `tier2/human-examples-medium.jsonl` / `tier2/human-examples-large.jsonl` | the example-sentence corpus — real natural-language sentences mapped to the same curated vocabulary, NOT fact triples. Small/Medium tiers are 100% WordNet's own inline `example:` field (same CC-BY-4.0 basis as the fact bundles). Large tier ALSO includes a SemCor-filtered supplement (real Brown Corpus text, re-tagged to modern OEWN senses) for categories where WordNet's own inline coverage is thin (`human-nature` especially — `noun.animal.yaml`'s inline rate is under 1%) | ~11 KB / ~43 KB / ~257 KB | **The WordNet-inline entries**: CC-BY-4.0 (Princeton WordNet + Open English WordNet team), reproduced verbatim (these ARE the source's own example sentences, not a paraphrase). **The `source: "semcor:…"` entries**: CC-BY-4.0 per this SemCor fork's own `LICENSE.md` (a local uncommitted checkout of `globalwordnet/semcor`, real Brown Corpus text re-tagged to modern senses — the original 1960s Brown Corpus permissions aren't independently re-verified beyond that fork's own license statement; proceeding with attribution was an explicit operator decision) — each entry's own `source` field names its origin file (`semcor:<genre>/<file>.yaml`) for exactly this reason |
 
 And alongside (same phase, different directory because it is tmct-original
 data, not a derived corpus):
@@ -53,17 +57,17 @@ data, not a derived corpus):
 
 ## How seeding works
 
-`src/corpus/conceptnet.mjs` turns the slice into tmct memory facts:
+`src/adapters/corpus/conceptnet.mjs` turns the slice into tmct memory facts:
 
 ```js
-import { seedMemory } from "./src/corpus/conceptnet.mjs";
+import { seedMemory } from "./src/adapters/corpus/conceptnet.mjs";
 await seedMemory(repoDir);            // writes <repoDir>/.tmct/memory/graph.json
 await seedMemory(repoDir, { limit: 500 }); // capped (fast bootstrap)
 ```
 
 - Each assertion whose relation maps to an ACE-OWL pattern
-  (`src/corpus/conceptnet-map.toml`, `ace != "none"`) becomes one reified
-  fact via `src/memory/core.mjs` `appendFact`:
+  (`src/adapters/corpus/conceptnet-map.toml`, `ace != "none"`) becomes one reified
+  fact via `src/adapters/memory/core.mjs` `appendFact`:
   `{subject:"software bug", predicate:"rdfs:subClassOf", object:"error",
   provenance:"corpus:conceptnet /r/IsA"}`.
 - **Idempotent**: fact ids are content-hashed from the normalized triple, and
@@ -79,7 +83,7 @@ A tier-2 corpus is a small, curated, LANGUAGE- or DOMAIN-specific fact set in
 the **exact tier-1 fact shape** — one JSON object per line,
 `{"start":"/c/en/…","rel":"/r/…","end":"/c/en/…","weight":N,"surfaceText":"…"}`,
 with `rel` drawn only from the mapped relations in
-`src/corpus/conceptnet-map.toml`. Because the shape is identical, a tier-2 file
+`src/adapters/corpus/conceptnet-map.toml`. Because the shape is identical, a tier-2 file
 loads and seeds through the very same `loadSlice()`/`toFacts()` path as the
 tier-1 slice — `tier2/generate.mjs --verify` proves it (each sample loads and
 all its facts seed cleanly, no `ace=none` dead rows).
@@ -97,7 +101,7 @@ sha256) in one deterministic pass. Curated data is authored in that file so it
 stays reviewable; a corpus too big to hand-curate is a `fetch` manifest entry
 (URL + sha256, opt-in network — `fetchCorpus()` is the reference downloader).
 
-**How tier-2 wires into `tmct init` (done — `src/extensions.mjs`):**
+**How tier-2 wires into `tmct init` (done — `src/services/extensions.mjs`):**
 `resolveExtensions(repoRoot)` ships all four tier-2 bundles as
 shipped-but-inactive `BUILTIN_EXTENSIONS` entries (`tier2-aws`/`tier2-python`/
 `tier2-java`/`tier2-general`); `[extensions.tier2-<id>] active = true` in
@@ -116,13 +120,13 @@ A term that would otherwise be silently dropped when a bundle is seeded (an
 `ace = "none"` relation like RelatedTo/HasContext, e.g. from a broader slice)
 can optionally be captured instead of vanishing: `seedMemory`'s
 `captureUnknownContext: true` option (default off) runs
-`src/corpus/unknown-ingest.mjs` over the same batch — see that module's own
+`src/adapters/corpus/unknown-ingest.mjs` over the same batch — see that module's own
 doc comment.
 
 ## How to regenerate / extend
 
 See `conceptnet/README.md` — one command per route (API vs dump), the
 quality-filter pass, plus the seed-term list to extend. The test suite
-(`test/corpus-conceptnet.test.mjs`, `test/corpus-templates.test.mjs`) guards the
+(`test/adapters/corpus-conceptnet.test.mjs`, `test/corpus-templates.test.mjs`) guards the
 contracts: slice/mapping drift, en→en shape, the ≤ 1.5 MB budget, template
 ids/slots, and end-to-end seeding.

package/corpus/conceptnet/README.md

@@ -31,7 +31,7 @@ see `LICENSE-NOTICE` in this directory for the full attribution.
    suffixes are stripped (`/c/en/bug/n` → `/c/en/bug`); self-loops after
    stripping are dropped.
 2. **Canonical relations only**: the closed set of 34 relations (the same set
-   mapped in `src/corpus/conceptnet-map.toml`), minus three filtered by
+   mapped in `src/adapters/corpus/conceptnet-map.toml`), minus three filtered by
    policy: `/r/EtymologicallyRelatedTo`, `/r/EtymologicallyDerivedFrom`,
    `/r/ExternalURL` (etymology noise and link-outs — no consumer in tmct).
 3. **Tech-domain seed terms**: at least one endpoint's bare term is in the
@@ -90,7 +90,7 @@ from the same ConceptNet dump by (a) widening the tech domain with the
 `EXTRA_SEEDS` list in `filter-dump.mjs` (~230 tech terms — languages,
 frameworks, data structures, cloud/infra, protocols, tools, ML) and (b) raising
 `MAX_BYTES` in `filter-dump.mjs` from 1.4 MB to 4.5 MB with the matching test
-budget assertion (`test/corpus-conceptnet.test.mjs`) raised from 1.5 MB to
+budget assertion (`test/adapters/corpus-conceptnet.test.mjs`) raised from 1.5 MB to
 5 MB. The widened seed set matched **45,633 unique en→en assertions** (all under
 budget, so no tier-trimming was needed this pass), and the quality filter
 trimmed them to the committed **44,947 clean facts**. Regenerate with:
@@ -149,14 +149,14 @@ To extend the domain, add seed terms to `EXTRA_SEEDS` in `filter-dump.mjs` (the
 dump route that produces the committed slice) or `SEED_TERMS` in
 `fetch-slice.mjs` (the API route) and re-run. `npm test` guards the contract:
 every relation present in the slice must have a row in
-`src/corpus/conceptnet-map.toml` (drift guard), en→en shape and the ≤ 5 MB
+`src/adapters/corpus/conceptnet-map.toml` (drift guard), en→en shape and the ≤ 5 MB
 budget are asserted, and the seeding path is exercised end-to-end.
 
 ## Consumers
 
-- `src/corpus/conceptnet.mjs` — `loadSlice()` / `toFacts()` / `seedMemory()`:
+- `src/adapters/corpus/conceptnet.mjs` — `loadSlice()` / `toFacts()` / `seedMemory()`:
   maps mappable assertions onto memory facts
   (`{subject, predicate, object, provenance:"corpus:conceptnet /r/…"}`)
   and seeds `.tmct/memory/` via `appendFact` (idempotent).
-- `src/corpus/conceptnet-map.toml` — the relation → ACE-OWL pattern table
+- `src/adapters/corpus/conceptnet-map.toml` — the relation → ACE-OWL pattern table
   deciding which relations emit facts and under which predicate URI.

package/corpus/conceptnet/fetch-slice.mjs

@@ -12,7 +12,7 @@
 // Filter rules (also documented in README.md here):
 //   - /query?node=/c/en/<term>&other=/c/en — both endpoints English;
 //   - keep only edges whose rel is one of the 34 canonical relations
-//     (src/corpus/conceptnet-map.toml is the same closed set);
+//     (src/adapters/corpus/conceptnet-map.toml is the same closed set);
 //   - drop en→en edges whose start/end still carry a sense suffix mismatch
 //     (we keep the bare /c/en/<term> and /c/en/<term>/<pos> forms, normalized
 //     to the bare term URI);

package/corpus/conceptnet/filter-dump.mjs

@@ -28,7 +28,7 @@
 
 import { createInterface } from "node:readline";
 import { SEED_TERMS, CANONICAL_RELS, FILTERED_RELS, bareEnTerm } from "./fetch-slice.mjs";
-import { loadMap } from "../../src/corpus/conceptnet.mjs";
+import { loadMap } from "../../src/adapters/corpus/conceptnet.mjs";
 
 const MAX_BYTES = 4_500_000; // committed-slice budget (hard cap 5 MB), grown for the ~40k tier-1 target
 

package/corpus/generated/README.md

@@ -1,36 +1,35 @@
 # corpus/generated/ — mechanically-generated ACE surface variants
 
-`ace-surface-variants.jsonl` — archive/PLAN_BREADTH_FIRST_NLU.md §6a's raw material for
-tmct's "richer template/surface-realization variety" goal. Never an LLM, never
+`ace-surface-variants.jsonl` — raw material for tmct's "richer
+template/surface-realization variety" goal. Never an LLM, never
 invented text: every row is a real seed sentence with one word swapped for a
 real WordNet synset sibling, or a real sentence's alternate ACE-grammar-
 declared surface form. Every row is self-verified — it re-parses against
-tmct's own `parseAce` (`src/grammar/ace.mjs`) before being written; a swap
+tmct's own `parseAce` (`src/domain/grammar/ace.mjs`) before being written; a swap
 that doesn't re-parse is dropped, never committed.
 
 Regenerate: `node scripts/generate-template-variants.mjs`. Coverage
 measurement: `node scripts/template-coverage.mjs` (baseline) and
 `node scripts/template-coverage.mjs --rescue corpus/generated/ace-surface-variants.jsonl`
-(after). See `archive/PLAN_TEMPLATE_COVERAGE.md` for the design and the real
-before/after numbers.
+(after).
 
 ## Row shapes
 
 | `kind` | What | Fields |
 |---|---|---|
-| `rescue` | A real docs-corpus sentence that almost fit the ACE grammar (exactly one undeclared word), rescued by substituting a WordNet synonym of that word that's ALSO already declared in `src/grammar/lexicon-core.json` | `sentence`, `rescued`, `from`, `to`, `pos`, `synsetId`, `sourceFile` |
+| `rescue` | A real docs-corpus sentence that almost fit the ACE grammar (exactly one undeclared word), rescued by substituting a WordNet synonym of that word that's ALSO already declared in `src/domain/grammar/lexicon-core.json` | `sentence`, `rescued`, `from`, `to`, `pos`, `synsetId`, `sourceFile` |
 | `variant` | A real WordNet/SemCor example sentence (`corpus/tier2/human-examples*.jsonl`) that already hits `parseAce`, with one content word swapped for a same-synset sibling (both ends independently declared in tmct's own lexicon) | `seed`, `generated`, `from`, `to`, `pos`, `synsetId`, `sourceCorpus` |
-| `alt-phrasing` | A possessive-pattern (#7) hit rewritten in the ACE grammar's OTHER declared surface form for the same triple (`"X's Y is Z"` <-> `"the Y of X is Z"`, both routed through `buildPossessive` in `src/grammar/ace.mjs`) | `seed`, `generated`, `pattern`, `form` |
+| `alt-phrasing` | A possessive-pattern (#7) hit rewritten in the ACE grammar's OTHER declared surface form for the same triple (`"X's Y is Z"` <-> `"the Y of X is Z"`, both routed through `buildPossessive` in `src/domain/grammar/ace.mjs`) | `seed`, `generated`, `pattern`, `form` |
 
 Every row also carries `provenance` (`wordnet:<synsetId>` or
 `grammar:ace.mjs pattern 7 (possessive) — …`).
 
 ## Not wired into the product path
 
-This corpus is not loaded by `src/chat.mjs`/`src/ask.mjs` or any other
+This corpus is not loaded by `src/services/chat.mjs`/`src/domain/ask.mjs` or any other
 product code — it is committed raw material, verified by
-`scripts/template-coverage.mjs`, per archive/PLAN_BREADTH_FIRST_NLU.md §6's explicit
-non-goal. Wiring it into live answer rendering is a separate, future phase.
+`scripts/template-coverage.mjs`. Wiring it into live answer rendering is a
+separate, future phase.
 
 ## Licence
 

package/corpus/namenet/README.md

@@ -0,0 +1,39 @@
+# corpus/namenet — the committed Open English Namenet conversion
+
+`namenet.jsonl` is a mechanical, ConceptNet-shape conversion of **three
+human-reviewed linking tables from the Open English Namenet project** — one
+`/r/Synonym` row per accepted name/label link:
+
+```json
+{"start":"/c/en/canis_lupus","rel":"/r/Synonym","end":"/c/en/wolf","weight":2,"surfaceText":"[[Canis lupus]] means the same as [[wolf]]"}
+```
+
+**Licence: CC-BY-4.0** as this repository's conservative label — the source
+repository declares no explicit licence of its own. Read `LICENSE-NOTICE` in
+this directory before redistributing more widely.
+
+## Provenance
+
+- **Source:** three reviewed CSVs (`species_reviewed.csv`,
+  `taxon2common_reviewed.csv`, `linked_occupations_reviewed.csv`) from a local
+  uncommitted checkout of
+  [globalwordnet/english-namenet](https://github.com/globalwordnet/english-namenet)
+  — never vendored into this repository. Species rows also cross-reference a
+  local Open English WordNet checkout (the same source
+  `corpus/wordnet/generate.mjs` reads) to resolve synset ids into lemmas.
+- **Why every row is `/r/Synonym`:** each accepted CSV row links two
+  name-lists a human reviewer confirmed denote the SAME real-world thing (a
+  species, a folk-taxonomic category, an occupation) — never a
+  broader/narrower or capability relation. See `generate.mjs`'s header comment
+  for the accept/skip rules per source file.
+- The output is indexed with a byte count and sha256 checksum in
+  `manifest.json`.
+
+## How to regenerate
+
+```
+node corpus/namenet/generate.mjs [namenetDir]
+TMCT_NAMENET_DIR=/path/to/english-namenet node corpus/namenet/generate.mjs
+```
+
+A maintainer tool, run by hand, offline.

package/corpus/seon/README.md

@@ -26,7 +26,7 @@ CC-BY-SA like the ConceptNet slice.
 
 Each line is exactly `{ "start", "rel", "end", "weight" }` with `/c/en/<term>`
 endpoints, so the existing `loadSlice` / `loadMap` / `toFacts` / `seedMemory`
-(`src/corpus/conceptnet.mjs`) consume this file with **no code change** — pass it as
+(`src/adapters/corpus/conceptnet.mjs`) consume this file with **no code change** — pass it as
 the `slicePath`.
 
 ```jsonc
@@ -36,7 +36,7 @@ the `slicePath`.
 {"start":"/c/en/java_class","rel":"/r/IsA","end":"/c/en/class","weight":2}
 ```
 
-Only relations already mapped in `src/corpus/conceptnet-map.toml` are used, so there
+Only relations already mapped in `src/adapters/corpus/conceptnet-map.toml` are used, so there
 is **no slice/map drift** (verified: the file loads through `toFacts` cleanly). The
 emitted-predicate breakdown:
 

package/corpus/tier2/generate.mjs

@@ -12,7 +12,7 @@
 // (corpus/conceptnet/slice.jsonl): one JSON object per line,
 //   {"start":"/c/en/<term>","rel":"/r/<Rel>","end":"/c/en/<concept>","weight":N,"surfaceText":"…"}
 // with `rel` drawn ONLY from the mapped relations in
-// src/corpus/conceptnet-map.toml, so a tier-2 file loads through the very same
+// src/adapters/corpus/conceptnet-map.toml, so a tier-2 file loads through the very same
 // loadSlice()/toFacts() path as the tier-1 slice (this file's --verify proves
 // it). The Wave-2 tier-2 SEEDER (see ../README.md) is what stamps the right
 // provenance (`corpus:tier2:<id> /r/…`) instead of the conceptnet default.
@@ -244,7 +244,7 @@ export const CORPUSES = {
   // PLAN_SEED.md — the default "human-world" persona (the operator's own
   // framing: SEON+ConceptNet's code-domain bias was never the only sensible
   // default; this is the general-knowledge seed set that REPLACES it as the
-  // default active bundle, per src/extensions.mjs's builtinExtensions()).
+  // default active bundle, per src/services/extensions.mjs's builtinExtensions()).
   // Hand-curated from two locally-cloned reference sources
   // (scripts/extract-persona-sources.mjs's worksheet — never a mechanical
   // dump of either): Open English WordNet (CC-BY-4.0, Princeton WordNet +
@@ -264,7 +264,7 @@ export const CORPUSES = {
     description: "The default human-world persona (PLAN_SEED.md): everyday people, places, objects, nature, time/events, body/food and mind vocabulary, hand-curated from Open English WordNet (CC-BY-4.0) and bridged to Schema.org's (Apache-2.0) top-level classes — replaces the code-domain SEON+ConceptNet default.",
     // Every noun/verb/adjective this corpus's facts depend on, so a live
     // sentence built from the SAME curated vocabulary ("a man has a hat") can
-    // actually parse — src/grammar/lexicon-core.json carries the real
+    // actually parse — src/domain/grammar/lexicon-core.json carries the real
     // entries (PLAN_SEED.md §4's "two vocabulary surfaces", gated
     // independently); this list is the --verify drift-guard's source of
     // truth (below), not a second copy of the lexicon file itself.
@@ -684,7 +684,7 @@ export const CORPUSES = {
       // ---- human-bridge (~10 facts) — the cross-ontology showcase
       // (PLAN_SEED.md §8): a WordNet-side root/common term paired with its
       // Schema.org-inspired counterpart from human-base, above. scm-sco
-      // (src/syllogise.mjs, unmodified) proves a chain spanning both
+      // (src/domain/syllogise.mjs, unmodified) proves a chain spanning both
       // sources once a WordNet-side ⊑-chain reaches one of these —
       // test/chat-cross-ontology-bridge.test.mjs exercises this live.
       ["person", "/r/IsA", "schema_person"],
@@ -14883,7 +14883,7 @@ export async function fetchCorpus(url, expectedSha) {
  * Alignment drift-guard for a corpus entry that declares an optional
  * `lexicon` sub-key (today: only `human` — PLAN_SEED.md §4's "two vocabulary
  * surfaces" seam): the corpus fact set and the ACE parser's closed-set
- * vocabulary (src/grammar/lexicon-core.json) are two SEPARATE files, gated
+ * vocabulary (src/domain/grammar/lexicon-core.json) are two SEPARATE files, gated
  * independently, so nothing stops them drifting apart over time. Two
  * directions, both real (mirroring conceptnet-map.toml's own "slice relation
  * missing from map = error" precedent):
@@ -14916,7 +14916,7 @@ async function verifyLexiconAlignment(id, spec) {
   const properNames = (spec.lexicon.properNames || []).map((n) => n.toLowerCase());
   const declared = [...nouns, ...verbs, ...adjectives, ...properNames];
 
-  const lexPath = fileURLToPath(new URL("../../src/grammar/lexicon-core.json", import.meta.url));
+  const lexPath = fileURLToPath(new URL("../../src/domain/grammar/lexicon-core.json", import.meta.url));
   const lex = JSON.parse(await readFile(lexPath, "utf8"));
   const inLexicon = (w) => Boolean(lex.nouns[w] || lex.verbs[w] || lex.adjectives[w]
     || (lex.properNames || []).some((n) => n.toLowerCase() === w));
@@ -14945,9 +14945,56 @@ async function verifyLexiconAlignment(id, spec) {
   console.error(`  verify ${id}: lexicon sub-key (${declared.length} words: ${nouns.length} nouns, ${verbs.length} verbs, ${adjectives.length} adjectives, ${properNames.length} proper names) is aligned both ways`);
 }
 
+// The human-examples bundles are real example SENTENCES (Open English WordNet
+// inline examples; the large tier also SemCor text), not fact triples: they are
+// built by scripts/build-persona-examples.mjs, never seed through
+// loadSlice()/toFacts(), and carry the source text's CC-BY-4.0 licence rather
+// than the curated fact bundles' MPL-2.0. They are indexed under a separate
+// `examples` key (NOT `corpuses`, which `tmct init --corpus` treats as
+// seedable fact sets) so the licence record and checksums stay machine-readable
+// without making the sentence files look importable.
+const EXAMPLE_BUNDLES = [
+  {
+    id: "human-examples",
+    file: "human-examples.jsonl",
+    description: "Example sentences for the Small human persona: Open English WordNet's own inline example sentences, reproduced verbatim.",
+  },
+  {
+    id: "human-examples-medium",
+    file: "human-examples-medium.jsonl",
+    description: "Example sentences added by the Medium persona tier: Open English WordNet inline examples, reproduced verbatim.",
+  },
+  {
+    id: "human-examples-large",
+    file: "human-examples-large.jsonl",
+    description: "Example sentences added by the Large persona tier: Open English WordNet inline examples plus a SemCor-filtered supplement (Brown Corpus text re-tagged to modern OEWN senses).",
+  },
+];
+
+const EXAMPLES_LICENSE = "CC-BY-4.0 (verbatim Open English WordNet / SemCor example sentences — see corpus/README.md and corpus/LICENSES.json)";
+
+async function exampleBundleManifestEntries() {
+  const entries = [];
+  for (const { id, file, description } of EXAMPLE_BUNDLES) {
+    const text = await readFile(join(HERE, file), "utf8");
+    entries.push({
+      id,
+      kind: "examples",
+      description,
+      source: { kind: "curated", tool: "scripts/build-persona-examples.mjs" },
+      file,
+      rows: text.split("\n").filter(Boolean).length,
+      bytes: Buffer.byteLength(text),
+      sha256: sha256(text),
+      license: EXAMPLES_LICENSE,
+    });
+  }
+  return entries;
+}
+
 async function main() {
   const verify = process.argv.includes("--verify");
-  const manifest = { version: 1, generated: "by corpus/tier2/generate.mjs", corpuses: [] };
+  const manifest = { version: 1, generated: "by corpus/tier2/generate.mjs", corpuses: [], examples: [] };
 
   for (const [id, spec] of Object.entries(CORPUSES)) {
     const text = corpusJsonl(id);
@@ -14966,12 +15013,14 @@ async function main() {
     console.error(`  ${id}: ${spec.facts.length} facts, ${Buffer.byteLength(text)} bytes`);
   }
 
+  manifest.examples = await exampleBundleManifestEntries();
+
   const manifestText = JSON.stringify(manifest, null, 2) + "\n";
   await writeFile(join(HERE, "manifest.json"), manifestText);
-  console.error(`wrote manifest.json (${manifest.corpuses.length} corpuses)`);
+  console.error(`wrote manifest.json (${manifest.corpuses.length} corpuses, ${manifest.examples.length} example bundles)`);
 
   if (verify) {
-    const { loadSlice, loadMap, toFacts } = await import("../../src/corpus/conceptnet.mjs");
+    const { loadSlice, loadMap, toFacts } = await import("../../src/adapters/corpus/conceptnet.mjs");
     const map = await loadMap();
     for (const c of manifest.corpuses) {
       const assertions = await loadSlice(join(HERE, c.file));

package/corpus/tier2/manifest.json

@@ -100,5 +100,49 @@
       "sha256": "754d9d4c046f92994a5f5fa0abde27af65a47ec546b3051bf972bfa76b642917",
       "license": "MPL-2.0"
     }
+  ],
+  "examples": [
+    {
+      "id": "human-examples",
+      "kind": "examples",
+      "description": "Example sentences for the Small human persona: Open English WordNet's own inline example sentences, reproduced verbatim.",
+      "source": {
+        "kind": "curated",
+        "tool": "scripts/build-persona-examples.mjs"
+      },
+      "file": "human-examples.jsonl",
+      "rows": 120,
+      "bytes": 11168,
+      "sha256": "592b3525248379b03b5818237a8b76c83060a704a585ee91a13996b22252a7a9",
+      "license": "CC-BY-4.0 (verbatim Open English WordNet / SemCor example sentences — see corpus/README.md and corpus/LICENSES.json)"
+    },
+    {
+      "id": "human-examples-medium",
+      "kind": "examples",
+      "description": "Example sentences added by the Medium persona tier: Open English WordNet inline examples, reproduced verbatim.",
+      "source": {
+        "kind": "curated",
+        "tool": "scripts/build-persona-examples.mjs"
+      },
+      "file": "human-examples-medium.jsonl",
+      "rows": 356,
+      "bytes": 43269,
+      "sha256": "40313cbf63d49fb4af08f0cb27d92c55877d3dbe7eb0bc791bd63e56c183418e",
+      "license": "CC-BY-4.0 (verbatim Open English WordNet / SemCor example sentences — see corpus/README.md and corpus/LICENSES.json)"
+    },
+    {
+      "id": "human-examples-large",
+      "kind": "examples",
+      "description": "Example sentences added by the Large persona tier: Open English WordNet inline examples plus a SemCor-filtered supplement (Brown Corpus text re-tagged to modern OEWN senses).",
+      "source": {
+        "kind": "curated",
+        "tool": "scripts/build-persona-examples.mjs"
+      },
+      "file": "human-examples-large.jsonl",
+      "rows": 1928,
+      "bytes": 257180,
+      "sha256": "fa5646f45451f948156686882f46c522939bbe43158ee42a7628fccf74d8966f",
+      "license": "CC-BY-4.0 (verbatim Open English WordNet / SemCor example sentences — see corpus/README.md and corpus/LICENSES.json)"
+    }
   ]
 }

package/corpus/wordnet/README.md

@@ -0,0 +1,37 @@
+# corpus/wordnet — the committed Open English WordNet conversion
+
+`wordnet-xl.jsonl` and `wordnet-full.jsonl` are a mechanical, ConceptNet-shape
+conversion of **real Open English WordNet (OEWN) structural relation data** —
+one row per relation edge or synonym-chain pair:
+
+```json
+{"start":"/c/en/dog","rel":"/r/IsA","end":"/c/en/canine","weight":2,"surfaceText":"[[dog]] is a kind of [[canine]]"}
+```
+
+**Licence: CC-BY-4.0** (Open English WordNet-derived data; NOT this repo's
+MPL-2.0) — see `LICENSE-NOTICE` in this directory for the full attribution.
+
+## Provenance
+
+- **Source:** the Open English WordNet YAML synset source
+  (`src/yaml/{noun,verb,adj,adv}.*.yaml`, 107,526 synsets), read from a local
+  uncommitted checkout of
+  [globalwordnet/english-wordnet](https://github.com/globalwordnet/english-wordnet)
+  — never vendored into this repository.
+- **What is read:** each synset's structural fields (`hypernym`, `mero_part`,
+  `mero_member`, `mero_substance`, `causes`, `attribute`, `similar`, `also`,
+  `members`) — never the `definition`/`example` free prose.
+- `wordnet-xl.jsonl` is a bounded ~24,000-fact prioritized subset (hypernym
+  backbone plus synonym chains for the most-referenced synsets);
+  `wordnet-full.jsonl` is the complete conversion. Both are indexed with byte
+  counts and sha256 checksums in `manifest.json`.
+
+## How to regenerate
+
+```
+node corpus/wordnet/generate.mjs [yamlDir]
+TMCT_WORDNET_YAML_DIR=/path/to/yaml node corpus/wordnet/generate.mjs
+```
+
+A maintainer tool, run by hand, offline. See `generate.mjs`'s header comment
+for the full relation-mapping table and direction rules.

package/corpus/wordnet/generate.mjs

@@ -100,7 +100,7 @@ export const RELATION_MAP = Object.freeze({
 export const SKIPPED_RELATIONS = Object.freeze(["entails", "exemplifies"]);
 
 // ---- term encoding (pure, unit-tested) -------------------------------------
-// Exact inverse of src/corpus/conceptnet.mjs's termText() decode
+// Exact inverse of src/adapters/corpus/conceptnet.mjs's termText() decode
 // (`/^\/c\/en\/([^/]+)/` then `.replace(/_/g, " ")`): lowercase, spaces ->
 // underscores, wrapped as `/c/en/<term>`. Nothing else is touched — any other
 // punctuation (apostrophes, hyphens) round-trips through termText() unchanged

package/data/templates/constructions/agent-noun-relations.toml

@@ -1,6 +1,6 @@
 # data/templates/constructions/agent-noun-relations.toml — construction-grammar
 # template bank (PLAN_ADVANCED_GRAMMAR.md track (d)): per-construction closed
-# template families as DATA, loaded by src/interpret/strategies/constructions.mjs
+# template families as DATA, loaded by src/domain/interpret/strategies/constructions.mjs
 # beside grammar.mjs's anchored T1-T10 grammar (this file's constructions are the
 # next numbers, T11-T13 — see the `id` field on each [[construction]] below; do
 # not renumber grammar.mjs's own T1-T10, this is an ADDITIVE, own-class strategy).
@@ -59,7 +59,7 @@ kind = "inherits"
 entityType = "Class"      # inherits is Class -> Class only
 
 # ---- constructions: pattern -> AST skeleton -------------------------------
-# Pattern DSL (src/interpret/strategies/constructions.mjs compiles this):
+# Pattern DSL (src/domain/interpret/strategies/constructions.mjs compiles this):
 #   <AGENT>  one of the [[relation]] nouns above (closed alternation, longest
 #            noun first so e.g. a hypothetical multi-word noun would never be
 #            shadowed by a shorter one sharing a prefix)

package/data/templates/grammar-rules.toml

@@ -2,7 +2,7 @@
 # (PLAN_RESPONSE_FINISHING.md, "The grammar pass (lever 2)").
 #
 # Each [[rule]] is a corrective grammar rule applied by applyGrammar() in
-# src/finish.mjs over the PROSE spans of a segmented answer — NEVER the flat
+# src/services/finish.mjs over the PROSE spans of a segmented answer — NEVER the flat
 # string, and NEVER a protected span (entity / path / number / code / provenance
 # / receipt). The engine reads STRUCTURE, never guesses from surface: an article
 # rule that would touch the word inside the following protected span refuses to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.12.0",
+  "version": "2.0.2",
   "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.",
@@ -39,27 +39,14 @@
   "bin": {
     "tmct": "./bin/tmct.mjs"
   },
-  "main": "./src/index.mjs",
+  "main": "./src/services/index.mjs",
   "exports": {
-    ".": "./src/index.mjs",
-    "./chat": "./src/chat.mjs",
-    "./resolveObject": "./src/ask.mjs",
-    "./ask": "./src/ask.mjs",
-    "./relationKind": "./src/codegraph.mjs",
-    "./impactClosure": "./src/codegraph.mjs",
-    "./dispatchTool": "./src/server.mjs",
-    "./fetchEntities": "./src/source.mjs",
-    "./repository-interface": "./src/repository-interface.mjs",
-    "./graph-service": "./src/providers/graph-service.mjs",
-    "./providers/fixture": "./src/providers/fixture.mjs",
-    "./providers/bootstrap": "./src/providers/bootstrap.mjs",
-    "./conformance": "./src/conformance.mjs",
-    "./init": "./src/init.mjs",
-    "./extensions": "./src/extensions.mjs",
-    "./toml-config": "./src/toml-config.mjs",
-    "./generateCompletion": "./src/completions/complete.mjs",
-    "./createCompletionsGraphAdapter": "./src/completions/graph-adapter.mjs",
-    "./plan": "./src/router/drive.mjs"
+    ".": "./src/services/index.mjs",
+    "./plan": "./src/domain/router/drive.mjs",
+    "./generateCompletion": "./src/services/completions.mjs",
+    "./createCompletionsGraphAdapter": "./src/services/completions.mjs",
+    "./repository-interface": "./src/adapters/repository-interface.mjs",
+    "./conformance": "./src/tools/conformance.mjs"
   },
   "files": [
     "bin/",
@@ -83,6 +70,8 @@
   "scripts": {
     "help": "node bin/tmct.mjs --help",
     "test": "node --test \"test/**/*.test.mjs\"",
+    "test:e2e": "node --test \"e2e/**/*.test.mjs\"",
+    "e2e:browsers": "playwright install chromium",
     "chat": "node bin/tmct.mjs",
     "chat:repo": "node bin/tmct.mjs chat --repo",
     "init": "node bin/tmct.mjs init",
@@ -110,6 +99,8 @@
   },
   "devDependencies": {
     "esbuild": "^0.28.1",
-    "ink-testing-library": "^4.0.0"
+    "ink-testing-library": "^4.0.0",
+    "playwright": "1.61.1",
+    "publint": "0.3.21"
   }
 }

package/src/{ask-nlp.mjs → adapters/ask-nlp.mjs}

@@ -1,5 +1,5 @@
 // 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.
+// Loaded lazily via src/adapters/wink-model.mjs; failure is cached as null, never a throw.
 
 import { winkInstance } from "./wink-model.mjs";
 

package/src/{config.mjs → adapters/config.mjs}

@@ -21,7 +21,7 @@ export class ToolError extends Error {
 
 export function loadConfig(env = process.env, cwd = process.cwd()) {
   // Always resolve to an absolute path, even when TMCT_GRAPH_FILE is set to a
-  // relative one — src/source-slice.mjs's path-traversal guard compares an
+  // relative one — src/adapters/source-slice.mjs's path-traversal guard compares an
   // always-absolute resolve(repoRoot, site.path) against repoRoot itself, so a
   // relative repoRoot (derived from this graphFile) would make that guard
   // reject every read, not just traversal attempts.