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

package/src/extensions.mjs

@@ -1,54 +1,21 @@
-// extensions.mjs — the extension-pack seam: one place a host repo (or a
-// third-party package such as seonix/marginalia) declares which corpus/
-// lexicon/templates bundles feed tmct, and how much each bundle's facts are
-// trusted relative to the others.
+// extensions.mjs — the extension-pack seam: one place a host repo (or a third-party
+// package) declares which corpus/lexicon/templates bundles feed tmct, and how much each
+// bundle's facts are trusted relative to the others.
 //
 //   resolveExtensions(repoRoot) → { entries: Map<name, ResolvedEntry>, biasByBundle }
 //
-// BUILTIN_EXTENSIONS' DEFAULT ACTIVE BUNDLE IS `human` (PLAN_SEED.md, the
-// persona flip): a fresh repo now seeds an everyday-world vocabulary (people,
-// places, objects, nature, time/events, body/food, mind — hand-curated from
-// Open English WordNet + Schema.org) rather than the old implicit code-domain
-// default. `seon` and `conceptnet` are SHIPPED but now INACTIVE — both are
-// equally code/tech-domain-biased (conceptnet's committed slice was filtered
-// via a tech-domain seed-term match, PLAN_SEED.md §2), so BOTH flip together,
-// not just seon — a repo that wants the old behavior asks for it explicitly
-// (`tmct init --with-persona code`, or `[extensions.seon]`/`[extensions.
-// conceptnet]` `active = true`). Four more shipped-but-INACTIVE tier-2 bundles
-// (`tier2-aws` / `tier2-python` / `tier2-java` / `tier2-general`) round out the
-// catalog. Activating any of these is a config-only edit (`tmct init --corpus
-// aws`, or a `[extensions.tier2-aws] active = true` in tmct.toml) — zero code
-// change. `tier2-general`'s own 49-fact animal/weather set (PLAN_AGENTS.md
-// Phase 1) is superseded IN DEFAULT ROLE by `human`'s much larger
-// `human-nature` clump, but stays shipped/selectable on its own for a caller
-// that wants that narrow slice without the rest of the human persona.
+// `human` is the default active bundle (everyday-world vocabulary); `seon`/`conceptnet`
+// (code/tech-domain) and four tier-2 bundles ship inactive, activated via `tmct init
+// --with-persona`/`--corpus <id>` or a `[extensions.<name>] active = true` override.
+// `human-medium`/`human-large` are additive SIZE TIERS of `human`, not separate personas.
 //
-// `human-medium`/`human-large` (also shipped-but-INACTIVE) are SIZE TIERS of
-// the SAME `human` bundle, not separate personas (PLAN_SEED.md §3) — each
-// holds only the facts that size adds beyond the previous one. Activated
-// together via `tmct init --persona-size medium|large` (bin/tmct.mjs), which
-// resolves them through this same registry.
+// A `tmct.toml` `[extensions]` table-of-tables may override a recognized builtin, or
+// declare a new host entry with its own `kind` (corpus | lexicon | templates | pack |
+// ontology). A separate flat `[bias]` table (bundle-name → number) feeds
+// src/memory/bias.mjs's ranking.
 //
-// A `tmct.toml` may carry a top-level `[extensions]` table-of-tables
-// (`[extensions.tier2-aws]`, …): a RECOGNIZED name (one of the builtins above)
-// may override `active`/paths/etc; an UNRECOGNIZED name declares a brand new
-// host entry and MUST carry a `kind` (corpus | lexicon | templates | pack |
-// ontology) — a `pack` entry may combine any of corpus_path/lexicon_path/
-// templates_path/phrasebook_path under one `active` flag and one provenance
-// name, the shape a third-party vocabulary package hands tmct. `ontology` is a
-// DISTINCT, nameable kind for an ontology bundle (as opposed to a plain
-// `corpus` bundle) — its `ontology_path` key is just an alias populating the
-// SAME internal `corpusPath` field a corpus entry uses, so every downstream
-// seeder/loader needs zero branching by kind name.
-//
-// A SEPARATE top-level `[bias]` table (flat: bundle-name → number) feeds
-// src/memory/bias.mjs's ranking — never nested under `[extensions.*]`.
-//
-// Entries are returned in a FIXED, deterministic order — `seon` first, then
-// `conceptnet`, then every other entry sorted by name — mirroring the
-// seon-before-conceptnet idempotency-ordering precedent chat.mjs's
-// seedBootstrapMemory already establishes (seon's curated facts should win the
-// content-hash idempotency race over general ConceptNet noise).
+// Entries are returned in a fixed order: `seon` first, then `conceptnet`, then the rest
+// sorted by name (so seon's curated facts win idempotency races over ConceptNet noise).
 
 import { isAbsolute, join, resolve, dirname } from "node:path";
 import { readFile } from "node:fs/promises";
@@ -65,67 +32,45 @@ import {
   toFacts,
 } from "./corpus/conceptnet.mjs";
 
-// corpus/namenet/generate.mjs's output — same small-top-up shape as the
-// wordnet-xl/wordnet-full entries below, just a single bundle (not
-// worth PKG_ROOT-style plumbing through corpus/conceptnet.mjs for one
-// directory constant, so computed locally here instead).
+// corpus/namenet/generate.mjs's output — a single small top-up bundle.
 const NAMENET_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "corpus", "namenet");
 
 export const EXTENSION_KINDS = Object.freeze(["corpus", "lexicon", "templates", "pack", "ontology"]);
 
-// The definitional-band-first predicate order chat.mjs's bootstrap has always
-// passed for the ConceptNet seed (SEED_PREFER) — re-declared here (not
-// imported from chat.mjs) to keep this module off chat.mjs's heavy graph, the
-// same "re-declare, don't import" discipline init.mjs's own SEED_PREFER uses.
+// The definitional-band-first predicate order for the ConceptNet seed (re-declared,
+// not imported, to keep this module off chat.mjs's heavy graph).
 const CONCEPTNET_PREFER = ["rdfs:subClassOf", "rdf:type", "mgx:usedFor", "mgx:partOf", "mgx:capableOf"];
 
 /** The shipped defaults — a FRESH object per call, so a caller can never
  *  accidentally mutate a module-level singleton. */
 function builtinExtensions() {
   return {
-    // WAS active:true (the implicit code-domain default) — now opt-in.
-    // PLAN_SEED.md §2: re-activate explicitly (`tmct init --with-persona
-    // code`, or `[extensions.seon] active = true`) for the old behavior.
+    // Opt-in code-domain bundle.
     seon: {
       kind: "corpus",
       active: false,
       corpusPath: SEON_CONCEPTS_FILE,
       provenancePrefix: "corpus:seon",
     },
-    // WAS active:true — now opt-in too, not just seon (PLAN_SEED.md §2: the
-    // committed slice is itself tech-domain-filtered, equally biased).
+    // Opt-in too: the committed slice is tech-domain-filtered, equally biased.
     conceptnet: {
       kind: "corpus",
       active: false,
       corpusPath: CONCEPTNET_SLICE_FILE,
       provenancePrefix: "corpus:conceptnet",
-      // matches chat.mjs's seedBootstrapMemory exactly: uncapped, definitional
-      // band first.
       limit: undefined,
       prefer: CONCEPTNET_PREFER,
     },
-    // NEW — the default active bundle (PLAN_SEED.md). Everyday-world
-    // vocabulary: people, places, objects, nature, time/events, body/food,
-    // mind, plus the human-base/human-bridge scaffolding connecting WordNet's
-    // and Schema.org's independently-built taxonomies (PLAN_SEED.md §3, §8).
+    // The default active bundle: everyday-world vocabulary plus the scaffolding
+    // connecting WordNet's and Schema.org's independently-built taxonomies.
     human: {
       kind: "corpus",
       active: true,
       corpusPath: join(TIER2_DIR, "human.jsonl"),
       provenancePrefix: "corpus:human",
     },
-    // NEW — Medium/Large SIZE tiers of the SAME `human` bundle (PLAN_SEED.md
-    // §3), not separate personas: each file holds ONLY the facts that size
-    // adds beyond the previous one (Medium beyond Small, Large beyond
-    // Medium), so activating them is purely ADDITIVE alongside `human`
-    // (never a replacement for it). Both ship INACTIVE — Small stays the
-    // unconditional default — and are activated together via `tmct init
-    // --persona-size medium|large` (bin/tmct.mjs), which resolves them
-    // through this SAME BUILTIN_EXTENSIONS lookup and the ordinary
-    // `--corpus <id>` activation seam (activatePluggableInput). "large"
-    // activates BOTH human-medium and human-large (Large's facts are
-    // Medium's plus its own — both bundles must be active to reach the
-    // full ~13,600-fact total).
+    // Medium/Large SIZE tiers of `human` (additive, not separate personas): each file
+    // holds only the facts that size adds beyond the previous one.
     "human-medium": {
       kind: "corpus",
       active: false,
@@ -162,17 +107,8 @@ function builtinExtensions() {
       corpusPath: join(TIER2_DIR, "general.jsonl"),
       provenancePrefix: "corpus:tier2-general",
     },
-    // corpus/wordnet/generate.mjs's output: a mechanical ConceptNet-shape
-    // conversion of Open English WordNet's structural relations, not
-    // hand-curated like the tier-2 bundles above (NOT called "tier-3" —
-    // corpus/README.md's tiering policy already uses that name for something
-    // else, runtime-learned facts that are never committed; this bundle is
-    // curated + committed, tier-2-shaped, just too large to hand-author).
-    // Named directly "wordnet-xl"/"wordnet-full" so `tmct import --corpus
-    // wordnet-xl` resolves straight through this BUILTIN_EXTENSIONS lookup,
-    // the same seam every other recognized name already uses — no change
-    // needed to bin/tmct.mjs's tier-2-manifest-id resolution path. Shipped
-    // inactive, like every other opt-in bundle here.
+    // corpus/wordnet/generate.mjs's output: a mechanical ConceptNet-shape conversion of
+    // Open English WordNet, too large to hand-curate like the tier-2 bundles above.
     "wordnet-xl": {
       kind: "corpus",
       active: false,
@@ -185,12 +121,8 @@ function builtinExtensions() {
       corpusPath: join(WORDNET_DIR, "wordnet-full.jsonl"),
       provenancePrefix: "corpus:wordnet-full",
     },
-    // corpus/namenet/generate.mjs's output: species/common-name and
-    // Wikidata-label/WordNet-lemma synonym pairs, mechanically derived from
-    // three human-reviewed Open English Namenet linking tables. A small,
-    // explicitly OPTIONAL top-up bundle (not a primary corpus) — same
-    // BUILTIN_EXTENSIONS seam as wordnet-xl/wordnet-full above, so `tmct
-    // import --corpus namenet` resolves directly here. Shipped inactive.
+    // corpus/namenet/generate.mjs's output: species/common-name and Wikidata/WordNet
+    // synonym pairs. A small, optional top-up bundle, not a primary corpus.
     namenet: {
       kind: "corpus",
       active: false,
@@ -202,9 +134,8 @@ function builtinExtensions() {
 
 export const BUILTIN_EXTENSIONS = Object.freeze(builtinExtensions());
 
-/** Validate one RESOLVED extension entry — throws a clear, specific error
- *  naming the offending key. Shared by resolveExtensions (every entry, always
- *  on) and Part 4's validateExtensionPack (a candidate pack directory). */
+/** Validate one RESOLVED extension entry — throws a clear, specific error naming the
+ *  offending key. Shared by resolveExtensions and validateExtensionPack. */
 export function validateExtensionEntry(name, entry) {
   if (!entry || typeof entry !== "object") {
     throw new Error(`extension "${name}": entry must be an object`);
@@ -278,20 +209,14 @@ function mergeExtensionEntry(name, builtin, override, repoRoot) {
 }
 
 /**
- * Resolve every extension entry a repo carries — the shipped builtins plus
- * whatever `tmct.toml`'s `[extensions]`/`[bias]` tables add or override.
- * Returns `{ entries, biasByBundle }`:
- *   - `entries`: Map<name, ResolvedEntry> in FIXED order (seon, conceptnet,
- *     then the rest sorted by name). EVERY entry is present (active or not) —
- *     callers filter by `.active` themselves (Part 2's corpus loader loop).
- *   - `biasByBundle`: { bundleName: number } from the flat top-level `[bias]`
- *     table (default {} — every bundle then ranks at bias 1, see bias.mjs).
- * No `tmct.toml` (or one with no `[extensions]`/`[bias]` tables) resolves to
- * exactly today's implicit seon+conceptnet default, byte-identical.
+ * Resolve every extension entry a repo carries — the shipped builtins plus whatever
+ * `tmct.toml`'s `[extensions]`/`[bias]` tables add or override. Returns
+ * `{ entries, biasByBundle }`: `entries` is Map<name, ResolvedEntry> in fixed order (every
+ * entry present, active or not — callers filter by `.active`); `biasByBundle` is
+ * { bundleName: number } from the flat `[bias]` table (default {}).
  *
- * `configFile` (optional): an explicit tmct.toml path override — `tmct extend
- * --validate <dir> --config <path>` — read INSTEAD of `<repoRoot>/tmct.toml`;
- * `repoRoot` still anchors every resource path (unchanged).
+ * `configFile` (optional): an explicit tmct.toml path read instead of
+ * `<repoRoot>/tmct.toml`; `repoRoot` still anchors every resource path.
  */
 export async function resolveExtensions(repoRoot, { configFile } = {}) {
   const raw = repoRoot ? await loadTomlConfig(repoRoot, configFile ? { file: configFile } : {}) : null;
@@ -324,25 +249,14 @@ export async function resolveExtensions(repoRoot, { configFile } = {}) {
 
 // ---- Part 2: the unified corpus loader loop ---------------------------------
 
-/** Seed every ACTIVE `corpus`/`ontology`-kind entry, plus any ACTIVE `pack`-kind
- *  entry that declares a `corpusPath` (in the Map's own fixed order — seon,
- *  conceptnet, then the rest sorted by name) into `repo`'s memory, ONE
- *  seedMemory() call per bundle. Shared by chat.mjs's first-run bootstrap,
- *  `tmct init`'s seed step and `tmct init --corpus <id>` — so all three read
- *  the SAME loop instead of three independent hardcoded call sites.
- *
- *  BUGFIX (this batch): a `pack`-kind entry's `corpusPath` used to be silently
- *  skipped here despite this module's own docblock claiming pack entries
- *  combine corpus_path/lexicon_path/etc — a pack's corpus facts never made it
- *  into memory. Fixed by seeding any active pack entry that declares a
- *  corpusPath, alongside corpus/ontology entries.
+/** Seed every ACTIVE `corpus`/`ontology`-kind entry, plus any ACTIVE `pack`-kind entry
+ *  that declares a `corpusPath`, into `repo`'s memory, one seedMemory() call per bundle.
+ *  Shared by chat.mjs's first-run bootstrap, `tmct init`'s seed step, and
+ *  `tmct init --corpus <id>`.
  *
- *  FAILURE-TOLERANT per bundle (init.mjs's own doctrine: a missing/broken
- *  corpus degrades to "not seeded", never a crash): one bad third-party pack's
- *  seedMemory throw is CAUGHT and recorded as `perBundle[name].error` — logged
- *  in the structured result rather than silently swallowed — while every
- *  OTHER bundle still seeds normally. Returns
- *  `{ appended, skipped, total, perBundle: { name: {appended,skipped,total,error?} } }`. */
+ *  FAILURE-TOLERANT per bundle: one bad third-party pack's seedMemory throw is caught and
+ *  recorded as `perBundle[name].error` while every other bundle still seeds normally.
+ *  Returns `{ appended, skipped, total, perBundle: { name: {appended,skipped,total,error?} } }`. */
 export async function seedActiveCorpusEntries(repo, entries) {
   const { seedMemory } = await import("./corpus/conceptnet.mjs");
   const perBundle = {};
@@ -350,13 +264,6 @@ export async function seedActiveCorpusEntries(repo, entries) {
   let skipped = 0;
   let total = 0;
   for (const [name, entry] of entries instanceof Map ? entries : new Map()) {
-    // PLAN_SEED.md §2 bug fix: a "pack"-kind entry with its own corpusPath
-    // combines corpus/lexicon/templates under one active flag (this module's
-    // own docblock says so) but was previously never actually seeded here —
-    // only bare `kind: "corpus"` entries were. Broadened, not narrowed: every
-    // existing `kind: "corpus"`/`kind: "ontology"` entry (seon/conceptnet/
-    // human/tier2-*) behaves identically to before; only a pack entry that
-    // DOES carry a corpusPath newly qualifies.
     if (!entry.active) continue;
     const seedable = entry.kind === "corpus" || entry.kind === "ontology" || (entry.kind === "pack" && entry.corpusPath);
     if (!seedable) continue;
@@ -373,8 +280,6 @@ export async function seedActiveCorpusEntries(repo, entries) {
       skipped += res.skipped;
       total += res.total;
     } catch (err) {
-      // Logged (in the structured result), never silently swallowed — but this
-      // ONE bundle's failure never aborts the others.
       perBundle[name] = { appended: 0, skipped: 0, total: 0, error: err && err.message ? err.message : String(err) };
     }
   }
@@ -384,16 +289,10 @@ export async function seedActiveCorpusEntries(repo, entries) {
 // ---- Part 3: lexicon-bundle merge -------------------------------------------
 
 /** Merge every ACTIVE `lexicon`/`pack` entry's declared lexicon file into one
- *  `{nouns, verbs, adjectives, properNames}` object — the exact shape
- *  grammar/lexicon.mjs's `loadLexicon(extra)` already accepts. Bundles merge
- *  in ASCENDING bias order (lowest first) so `loadLexicon`'s existing "extra
- *  entries win on conflict" last-write-wins semantics resolve a same-lemma
- *  collision by BIAS, deterministically, rather than by arbitrary load order —
- *  a higher-bias bundle's entry always wins. Ties (equal/absent bias) keep the
- *  entries' `entries` Map iteration order (itself the fixed seon/conceptnet/
- *  sorted-rest order). Entries with no lexiconPath are skipped. Returns `null`
- *  when nothing merges (so a caller can pass `undefined` through to
- *  `loadLexicon` unchanged — the byte-identical no-extension default). */
+ *  `{nouns, verbs, adjectives, properNames}` object (grammar/lexicon.mjs's `loadLexicon`
+ *  shape). Bundles merge in ascending bias order so a same-lemma collision resolves by
+ *  bias, deterministically — a higher-bias bundle's entry always wins. Returns `null`
+ *  when nothing merges. */
 export async function mergedLexiconExtra(entries, biasByBundle = {}) {
   const candidates = [];
   for (const [name, entry] of entries instanceof Map ? entries : new Map()) {
@@ -425,13 +324,10 @@ export async function mergedLexiconExtra(entries, biasByBundle = {}) {
 
 // ---- Part 4: `tmct extend --validate <dir>` ---------------------------------
 
-/** Validate one CANDIDATE extension pack entry against a directory — reuses
- *  the existing throw-loudly primitives (loadSlice/loadMap/toFacts,
- *  loadLexicon, loadTemplates) rather than inventing new shape-checking logic.
- *  `candidate` is a resolved-shape entry (see mergeExtensionEntry) whose paths
- *  are absolute or resolved against `dir`. Returns
- *  `{ ok, results: [{kind, path, ok, error?, counts?}] }` — never throws;
- *  every failure is CAUGHT and reported as one `results[]` row. */
+/** Validate one CANDIDATE extension pack entry against a directory, reusing the existing
+ *  throw-loudly primitives (loadSlice/loadMap/toFacts, loadLexicon, loadTemplates).
+ *  `candidate` is a resolved-shape entry whose paths are absolute or resolved against
+ *  `dir`. Returns `{ ok, results: [{kind, path, ok, error?, counts?}] }`; never throws. */
 export async function validateExtensionPack(dir, candidate) {
   const results = [];
   const abs = (p) => (p ? (isAbsolute(p) ? p : resolve(dir, p)) : p);

package/src/finish.mjs

@@ -1,25 +1,11 @@
-// finish.mjs — Phase 7 response finishing: the segmentation IR seam.
-// (archive/PLAN_RESPONSE_FINISHING.md, "The segmentation IR (lever 1)".)
+// finish.mjs — response finishing: the segmentation IR seam.
 //
-// The governing principle is fact-invariance BY CONSTRUCTION. An answer is a
-// list of typed spans, [{ type, text }, …], carried alongside the flat string
-// (never replacing it). Every type except `prose` is PROTECTED: entities,
-// paths, numbers, code, provenance and receipts are byte-copied through
-// finishing untouched, and only prose spans are ever handed to a (future)
-// grammar-rule engine. Segmentation makes "turn app/lib/a.mjs into an.mjs"
-// UNREPRESENTABLE — the protected spans are not in the rule engine's input.
-//
-// This module is the FOUNDATION step: pure structure, ZERO behaviour change.
-// It provides:
-//   - the segment type vocabulary + the protected/prose split,
-//   - maskSegments(answer, { graph }) — a conservative masker for the composed
-//     (non-template) path (the templated path segments in corpus/templates.mjs),
-//   - an INVARIANCE CHECKER (the protected-span multiset must survive any
-//     prose-only transform), the property future grammar rules are gated on,
-//   - a NO-OP finish(result, ctx) — the seam a later wave wires into chat.mjs.
-//
-// Byte-exact reconstruction is the whole contract here: flatten(segments) ===
-// answer for every producer, and finish() returns its input byte-for-byte.
+// Fact-invariance by construction: an answer is a list of typed spans,
+// [{ type, text }, …], carried alongside the flat string. Every type except
+// `prose` is PROTECTED — byte-copied through finishing untouched — so only
+// prose spans ever reach the grammar-rule engine; a rule can't touch a fact
+// because a fact is never in its input. Byte-exact reconstruction is the
+// whole contract: flatten(segments) === answer for every producer.
 
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -31,7 +17,7 @@ import { flatten } from "./corpus/templates.mjs";
 export { flatten };
 
 const GRAMMAR_DIR = dirname(fileURLToPath(import.meta.url));
-/** The data-driven grammar-rule table (Phase 7, lever 2). */
+/** The data-driven grammar-rule table. */
 export const GRAMMAR_RULES_FILE = join(GRAMMAR_DIR, "..", "data", "templates", "grammar-rules.toml");
 
 /** The segment type vocabulary. `prose` is the only unprotected type. */
@@ -49,15 +35,10 @@ export function isProtected(type) {
   return type !== "prose";
 }
 
-// --- Conservative masker for the composed path ------------------------------
-// The templated path gets segments almost for free (corpus/templates.mjs
-// renderSegments). The composed path (ask engine, plain/conversational turns)
-// hands finishing a hand-built flat string; maskSegments walks it and marks
-// PROTECTED anything matching one of the patterns below, leaving everything
-// else prose. Policy: CONSERVATIVE — when unsure, protect. An un-adopted render
-// site simply presents its whole answer as a single prose span (pass no graph
-// and match nothing → one prose segment), and the invariance checker still
-// guards it. flatten(maskSegments(answer, ctx)) === answer, always.
+// --- Conservative masker for the composed (non-template) path ---------------
+// Walks a hand-built flat answer string and marks PROTECTED anything matching
+// one of the patterns below; everything else is prose. Conservative: when
+// unsure, protect. flatten(maskSegments(answer, ctx)) === answer, always.
 
 // Parenthesized receipts: "(traversal: calls edges where object = fnAlpha)" and
 // the repair receipt 'read as "which modules import a.mjs"'.
@@ -195,16 +176,11 @@ export function assertInvariance(before, after) {
   return after;
 }
 
-// --- The grammar-rule engine (lever 2) --------------------------------------
-// applyGrammar transforms ONLY the prose spans of a segment list. It NEVER
-// regexes the flat answer string and NEVER touches a protected span — the
-// invariance checker is treated as NECESSARY-BUT-NOT-SUFFICIENT (a token the
-// masker failed to protect would sit in a prose span, and a corrupting rule that
-// mangled it would pass the multiset check because prose is unchecked). So the
-// only defence is that a rule literally cannot receive a protected span: every
-// handler below filters `type === "prose"` and byte-copies the rest. Each rule's
-// NEUTRAL behaviour is byte-stable; the only byte changes are GENUINE fixes to
-// defects tmct itself generates. Rules are chosen to commute → idempotent.
+// --- The grammar-rule engine -------------------------------------------------
+// applyGrammar transforms ONLY the prose spans; every handler below filters
+// `type === "prose"` and byte-copies the rest, since the invariance checker
+// alone can't catch a rule that corrupts a span the masker mis-protected
+// (prose is unchecked). Rules are chosen to commute → idempotent.
 
 const escapeRe2 = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
@@ -247,8 +223,8 @@ function pluralityOf(seg) {
 
 // Rule 1 — article selection (a/an). Reads the following word: in-span when the
 // whole "a word" pair is inside one prose span; across the boundary when the
-// prose ends in "a"/"an" and the next span supplies the word (guard #3: it only
-// fires when it can read the real next token, else it leaves the article alone).
+// prose ends in "a"/"an" and the next span supplies the word (only fires when
+// it can read the real next token, else it leaves the article alone).
 function ruleArticle(segments, rule) {
   const out = segments.map((s) => ({ ...s }));
   for (let i = 0; i < out.length; i += 1) {
@@ -312,20 +288,10 @@ function ruleAgreement(segments, rule) {
   return out;
 }
 
-// Rule 3 — sentence capitalisation. Capitalises (a) the very first character
-// when the answer OPENS on a prose span (the ORIGINAL single-answer scope,
-// unchanged), (b) every INTERNAL sentence boundary inside a single prose span
-// — a run of terminal punctuation + whitespace followed by a lowercase letter
-// — and (c) a sentence boundary that CROSSES a span boundary: a prose span
-// ends in terminal punctuation (+ optional trailing whitespace) and the next
-// real-content span is itself prose starting lowercase (any purely-whitespace
-// prose spans in between are skipped over). (b) and (c) are the
-// PLAN_COMPLETIONS.md Stage 6 generalisation — a genuinely multi-sentence
-// completion needs every internal boundary capitalised, not just the whole-
-// answer opener. A boundary that lands on a PROTECTED span (path/entity/…) is
-// left exactly as grounded — a protected span's casing is never
-// rule-transformed, the same guard (a) always applied to an answer that opens
-// on one.
+// Rule 3 — sentence capitalisation: (a) the answer-initial letter, (b) every
+// internal sentence boundary within one prose span, (c) a boundary that
+// crosses a span boundary (skipping purely-whitespace spans in between). A
+// boundary landing on a protected span is left alone — never rule-transformed.
 function ruleCapitalise(segments) {
   if (!segments.length) return segments;
   const out = segments.map((s) => ({ ...s }));
@@ -380,12 +346,10 @@ function ruleList(segments, rule) {
 
 // Rule 5 — terminal punctuation. Collapses ANY run of 2+ sentence stops within
 // a prose span to a single stop ("done.." → "done."; "Sentence one.. Sentence
-// two!!" → "Sentence one. Sentence two!") — generalised (PLAN_COMPLETIONS.md
-// Stage 6) from the original single-answer scope (only the LAST prose span,
-// only a run anchored at the very end of the answer) to every internal
-// sentence boundary a multi-sentence completion can carry. A legitimate
-// fragment/list answer that ends without a stop is unaffected — there is
-// nothing to collapse.
+// two!!" → "Sentence one. Sentence two!"), across every internal sentence
+// boundary a multi-sentence completion can carry, not just the answer's end.
+// A legitimate fragment/list answer that ends without a stop is unaffected —
+// there is nothing to collapse.
 function ruleTerminal(segments, rule) {
   const stops = (rule.stops && rule.stops.length ? rule.stops : [".", "!", "?"]).map(escapeRe2).join("");
   const re = new RegExp(`([${stops}])(?:\\s*[${stops}])+(\\s*)`, "g");
@@ -420,7 +384,7 @@ export function grammarRules() {
 
 /** Apply the grammar rules to a segment list, in file order, transforming ONLY
  *  prose spans. Asserts fact-invariance at the end (the protected multiset must
- *  be identical) and returns the transformed segments. Idempotent by design:
+ *  be identical) and returns the transformed segments. Idempotent:
  *  applyGrammar(applyGrammar(x)) yields the same flattened text as applyGrammar(x). */
 export function applyGrammar(segments, rules = grammarRules()) {
   let cur = segments;
@@ -435,37 +399,17 @@ export function applyGrammar(segments, rules = grammarRules()) {
 }
 
 // --- The finish() seam ------------------------------------------------------
-// finish() is the LAST transform in a turn:
-//   1. take the result's `segments` (attached by a producer) or mask its
-//      `answer` via maskSegments(result.answer, ctx),
-//   2. map ONLY the prose spans through the grammar-rule engine (applyGrammar),
-//   3. re-flatten, ASSERTING the invariance checker holds (guard #4: this runs
-//      in production, not just in tests — a corruption throws, never ships),
-//   4. rewrite result.answer (and thus logLines); `via` is unchanged.
-//
-// NEUTRAL finishing is BYTE-STABLE: when no rule fires, the flattened answer is
-// byte-identical to the input and finish() returns its argument by REFERENCE, so
-// every byte-exact assertion (test/showcase.test.mjs) stays green untouched. A
-// genuine fix (e.g. "a artifact" → "an artifact") rebuilds the result with the
-// corrected answer. Idempotent by construction: finish(finish(x)) === finish(x).
-//
-// INTENDED chat.mjs SEAM (a sibling/later wave wires this, foreign file): in
-// runTurn, at the `withLast` seam, `result = finish(result, { graph })` so every
-// producer passes through once. Until then finish() is exercised by its unit +
-// golden tests; wiring it changes no fact, only fixes our own generated defects.
+// The last transform in a turn: mask (or reuse existing) segments, run
+// applyGrammar over the prose spans, re-flatten, and assert invariance before
+// rewriting result.answer/logLines. Byte-stable when neutral: finish() returns
+// its argument by REFERENCE when no rule fired. Idempotent by construction.
 //
-// ctx.rules (optional, additive): a caller-supplied rule table overriding the
-// cached grammarRules() for this call only — e.g. completions/complete.mjs's
-// Stage 6 pass force-enables the sentence-capitalisation rule (PARKED in the
-// live chat table per grammar-rules.toml's own cycle-006 note) because a
-// genuinely multi-sentence extractive completion needs every internal sentence
-// boundary capitalised to read as one voice, without touching the chat
-// pipeline's default live/parked flags. Every EXISTING call site omits
-// ctx.rules and is therefore byte-identical to before this option existed.
+// ctx.rules (optional): a caller-supplied rule table overriding the cached
+// grammarRules() for this call only. Every existing call site omits it.
 
 /** Finish a turn result: grammar-correct its prose spans, preserving every fact.
  *  Byte-stable when neutral (returns its argument unchanged); rebuilds only on a
- *  genuine fix. Throws if finishing would move any protected span (guard #4).
+ *  genuine fix. Throws if finishing would move any protected span.
  *  @param {{rules?: object[]}} [ctx.rules] optional rule-table override (see above) */
 export function finish(result, ctx = {}) {
   if (!result || typeof result.answer !== "string") return result;

package/src/grammar/ace.mjs

@@ -1,5 +1,5 @@
-// grammar/ace.mjs — tmct's deterministic ACE-OWL sub-fragment parser (ROADMAP
-// Phase 2, item 2). Implements the 8 controlled-English sentence patterns of
+// grammar/ace.mjs — tmct's deterministic ACE-OWL sub-fragment parser.
+// Implements the 8 controlled-English sentence patterns of
 // docs/references/schemas/ace-owl-fragment.md and nothing more: fitting the
 // grammar is a strong signal, missing it is a FEATURE — parseAce returns null
 // (or an empty-triples result carrying the unknown words as `residue`) and the
@@ -18,21 +18,13 @@
 //            empty — feeds the pipeline's "if you mean X…" surround).
 //   null     the sentence does not fit the fragment at all.
 //
-// Term style: classes/individuals are `tmct:<lexeme>` CURIEs (lexicon lemma
-// for nouns, canonical spelling for proper names, the literal token for
-// code-shaped references like chat.mjs); predicates are the OWL/RDF(S)
-// vocabulary terms or the lexicon verb's tmct:<3sg> predicate
-// (lexicon.mjs's predicateOf). Restriction and intersection class
-// expressions get READABLE deterministic node names (tmct:some-imports-test,
-// tmct:module-that-imports-test) instead of blank nodes, so the same
-// sentence always re-emits the same triples and appendFact stays idempotent.
-// An intersection is flattened to repeated owl:intersectionOf triples (one
-// per member) — the flat-JSON stand-in for an RDF list, documented in
-// ontology/tmct-core.ttl. `lexicon.ns` is always "tmct:" here (lexicon.mjs's
-// DEFAULT_NS) — every term this module mints is namespaced off `lexicon.ns`
-// rather than a hardcoded literal purely so a caller can supply its own
-// already-namespaced lexicon (extensions.mjs's mergedLexiconExtra); tmct
-// itself only ever runs one namespace.
+// Term style: classes/individuals are `tmct:<lexeme>` CURIEs; predicates are
+// OWL/RDF(S) vocabulary terms or the lexicon verb's tmct:<3sg> predicate
+// (lexicon.mjs's predicateOf). Restriction/intersection nodes get READABLE
+// deterministic names (tmct:some-imports-test) instead of blank nodes, so the
+// same sentence always re-emits the same triples and appendFact stays
+// idempotent; an intersection flattens to repeated owl:intersectionOf triples
+// (documented in ontology/tmct-core.ttl).
 
 import {
   loadLexicon, lookupNoun, lookupVerb, lookupAdjective, lookupProperName,
@@ -190,22 +182,11 @@ function parseRelation(lexicon, toks, lower) {
   return null;
 }
 
-// ---- ambiguity: breadth-first candidate parses, dead ends pruned, survivors
-// surfaced rather than guessed (the operator's own framing — see
-// PLAN_DID_YOU_SEE_HER_DUCK.md's Origin section). parseRelation just above is
-// UNCHANGED — it is still the greedy, first-verb-position-wins fast path
-// every existing caller keeps using, so every single-reading sentence (the
-// overwhelming majority) is completely unaffected. parseRelationHits and
-// parseAceAmbiguous below are a separate, ADDITIVE scan that a caller opts
-// into only when it wants to know whether more than one reading survives. ----
+// ---- ambiguity: an additive scan a caller opts into to see every surviving
+// reading, never displacing parseRelation's own greedy first-match path. ----
 
-/** Pattern 3 — EVERY verb-position split, not just the first: for each token
- *  index that lookupVerb recognizes, resolve both sides and keep it ONLY if
- *  it is a complete, valid parse (a genuine hit — a missOrNull/null split is
- *  a dead end, pruned here rather than surfaced as "ambiguity"). Duplicate
- *  logic with parseRelation is deliberate: parseRelation must stay byte-for-
- *  byte unchanged for every existing caller, so this is a standalone reader,
- *  not a refactor of shared internals. */
+/** Pattern 3 — every verb-position split (not just the first), keeping only
+ *  complete, valid parses; a dead-end split is pruned, not surfaced. */
 function parseRelationHits(lexicon, toks, lower) {
   const hits = [];
   for (let i = 1; i < toks.length - 1; i += 1) {
@@ -233,14 +214,9 @@ function parseRelationHits(lexicon, toks, lower) {
   return hits;
 }
 
-/** Public ambiguity surface: parse `sentence` and, ONLY when more than one
- *  independent, COMPLETE relation-pattern reading survives (parseRelationHits
- *  above), return them all, each labeled by the token it read as the verb.
- *  Returns null for the overwhelming majority of sentences: anything not
- *  relation-shaped (mirrors parseAce's own dispatch gate exactly, so this
- *  only ever fires on a sentence parseAce would ALSO route to parseRelation),
- *  and any relation-shaped sentence with 0 or 1 surviving readings — the
- *  ordinary parseAce path is authoritative and untouched either way. */
+/** Public ambiguity surface: null unless 2+ independent, complete
+ *  relation-pattern readings survive, in which case all are returned, each
+ *  labeled by the token read as its verb. */
 export function parseAceAmbiguous(sentence, lexicon = loadLexicon()) {
   const toks = tokenize(sentence);
   if (toks.length < 4) return null; // 3 tokens: exactly one verb position is even possible

package/src/grammar/assert.mjs

@@ -1,6 +1,6 @@
 // grammar/assert.mjs — the grammar→memory bridge: parseAce a sentence and land
 // every emitted triple in tmct's OWN memory graph via memory/core.mjs's
-// appendFact (ROADMAP Phase 2 item 2 meeting Phase 1 item 9).
+// appendFact.
 //
 // appendFact normalizes each triple's subject/object through normFactTerm
 // (tmct:Legacy-module → "legacy-module"; the predicate keeps its vocabulary

package/src/grammar/lexicon-core.json

@@ -1,5 +1,5 @@
 {
-  "comment": "tmct's starter lexicon (ROADMAP Phase 2, item 2), now covering BOTH the original software domain and (PLAN_SEED.md, the default 'human-world' persona) everyday people/places/objects/nature/time/body/mind vocabulary. Every word the ACE-OWL sub-fragment parser (src/grammar/ace.mjs) is allowed to understand is DECLARED here — tmct never guesses a word's category. Nouns may declare a possessive property typing ('data' or 'object', pattern 7) or an irregular 'plural' (WordNet-sourced human nouns like 'man'/'child' need this — the morphology fold only handles regular -s/-ies/-es endings); adjectives MUST declare a type ('subclass' forms a class, 'data' asserts a boolean-ish datatype property, pattern 8); verbs may declare a preposition ('depend' + 'on' → dependsOn). The human-domain additions are flat and simple by design (breadth over depth — no gender/kinship taxonomy, no formal role hierarchy), matching corpus/tier2/generate.mjs's CORPUSES.human.lexicon sub-key, which --verify drift-checks against. Extend via loadLexicon(extra) with this same shape.",
+  "comment": "tmct's starter lexicon (ROADMAP Phase 2, item 2), now covering BOTH the original software domain and (PLAN_SEED.md, the default 'human-world' persona) everyday people/places/objects/nature/time/body/mind vocabulary. Every word the ACE-OWL sub-fragment parser (src/grammar/ace.mjs) is allowed to understand is DECLARED here — tmct never guesses a word's category. Nouns may declare a possessive property typing ('data' or 'object', pattern 7) or an irregular 'plural' (WordNet-sourced human nouns like 'man'/'child' need this — the morphology fold only handles regular -s/-ies/-es endings); adjectives MUST declare a type ('subclass' forms a class, 'data' asserts a boolean-ish datatype property, pattern 8); verbs may declare a preposition ('depend' + 'on' → dependsOn). The human-domain additions are flat and simple (breadth over depth — no gender/kinship taxonomy, no formal role hierarchy), matching corpus/tier2/generate.mjs's CORPUSES.human.lexicon sub-key, which --verify drift-checks against. Extend via loadLexicon(extra) with this same shape.",
   "nouns": {
     "module": {},
     "class": {},