mcts-mem 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 B.M.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# MCTS-Mem
+
+> MCTS-Mem is a structured, verifiable memory of *how a project was decided* — every
+> choice that stuck, every alternative that was tried, and the recorded reason each one
+> won or lost. You read it by **following its structure**, not by searching it, and a
+> linter checks it the way a compiler checks code — so the knowledge stays consistent
+> and trustworthy instead of becoming a pile of notes that might quietly contradict
+> itself. Built once from a project's history, kept current as it evolves, and read by
+> humans and AI agents before they change anything.
+
+## Remember how you got here, not the code
+
+On a large project, people don't carry the code in their heads — they carry **how it
+got there**: the decisions that worked, the ones that failed, and the facts that drove
+each. The current code is only the latest path; the durable asset is the knowledge
+accumulated reaching it, and that knowledge — not the source — is what lets someone
+change the system confidently, or even understand it. Today it lives in people's heads
+and in chat logs that evaporate.
+
+MCTS-Mem takes that knowledge out of individual brains and puts it in one place,
+organized by a model of how it accumulates: every decision, fact, failure, and
+contradiction sits at the point in the design it bears on. Thousands of commits' worth
+of reasoning — normally scattered across diffs, dead branches, and deleted files —
+becomes one artifact a newcomer or an agent can read in minutes, share, and build on.
+
+## Structure is the point
+
+A pile of notes — however well written — can hold contradictions and errors that are
+never found. You retrieve a passage but can't be sure it's complete, current, or
+consistent with what's filed elsewhere, and deciding on knowledge you only *probably*
+have is a risk you can't measure. That is the ceiling a free-text or embedding-based
+memory hits: it can recall, but it can't guarantee the recalled set is consistent — so
+every answer carries a residue of doubt.
+
+Structure removes the doubt. You don't search the tree, you **follow** it: each node
+leads to its alternatives, its supporting evidence, and the decisions made downstream,
+so the shape itself is the index and tells you where to look next. And because a
+decision lives at one node with its evidence and alternatives beside it, **what you see
+at that node is everything you need to decide** — not a sample that might be missing the
+contradicting fact two hops away. The gain isn't just speed; the answer is **accurate,
+deterministic, and verifiable**, and you reason *with confidence*, because anything that
+could make you wrong would itself be at the node.
+
+## Verified like source code
+
+Structure is only trustworthy if it's *enforced*, so the rules are executable.
+`npx mcts-mem lint` runs a set of mechanical, deterministic checks over the whole tree —
+each the executable form of a rule the skills specify — and passes only when every
+invariant holds:
+
+- **Links resolve.** Every cross-reference points at a real node; nothing dangles.
+- **Re-decisions can't contradict themselves.** A replacement and the alternative it
+  superseded must record the *same* reason, **verbatim** on both sides — a tree whose
+  two halves tell different stories won't pass.
+- **History is append-only.** No recorded fact or move can be silently edited or
+  deleted; corrections are *new, dated* entries, so the record of what was believed and
+  when stays auditable.
+- **Every claim is sourced.** Each fact and move ends with one tag answering *what could
+  prove it wrong* — `(code)` (checkable against the code), `(sourced)` (resting on a human
+  record: commit message, doc, paper, chat log, author), or `(uncertain)` (an unbacked
+  reading of intent). Evidence, record, and guess are never confused.
+- **Every node earns its place.** A node that records no decision, evidence, or
+  alternative is rejected; reading a node is never noise.
+
+Lint checks *consistency*, not truth — whether a measurement is correct is a separate
+matter — but when it passes, those guarantees are *proven*, not hoped for. The memory is
+checked the way code is checked by a compiler and a test suite, which is what most
+memory systems cannot offer: its **logical consistency is a property of the artifact**,
+not of how carefully someone wrote it down.
+
+Because the record is append-only and every fact carries its origin, it can also be
+**re-checked**. History can be wrong — an early bad measurement can drive a decision
+that was reasonable on the data but wrong in fact. You reproduce the fact, append the
+corrected one, and **re-decide**: the solution is re-found under updated knowledge,
+without erasing the record of how it was first reached.
+
+## A remembered search — why "MCTS"
+
+Building the system *was* a search over a space of possible designs: you try a branch,
+learn something (a fact), and that result shapes where you look next. Like Monte-Carlo
+Tree Search, MCTS-Mem records that search — the branches taken and abandoned, and the
+evidence (the **value**) on each — so the next exploration starts from the accumulated
+result instead of from scratch. New or re-validated facts update that value, and that is
+what **improves the policy**: stronger evidence revives a branch pruned on bad data, or
+retires one that only looked good on thin data. This is the one sense in which "search"
+applies — the exploration that *produced* the tree, never how you read it.
+
+## Beyond software
+
+Anything that advances by trying things and learning fits the same model. A team on a
+hard task records what it learned, what failed, what succeeded, and the decisions that
+followed. Research does it explicitly: run an experiment, record the facts, decide how
+to improve the method — which is exactly *refining the search policy* for the next
+experiment.
+
+And because every memory shares one model, **memories merge**. Separate trees combine
+into a single prior for a whole topic — for instance, general JIT-engine knowledge that
+unifies what was learned building JSC and V8 — turning the accumulated reasoning of many
+independent efforts into one thing you can consult.
+
+## How to use it
+
+MCTS-Mem ships as two **skills** plus a small helper CLI. You don't run a program against
+your codebase — you point your AI coding agent at a skill, and it follows the method:
+
+- **`mcts-mem-use`** — consult a tree before you plan a change, and update it when you
+  re-decide something. Reach for it before any non-trivial design, refactor, or rewrite in
+  a repo that has an `mcts_mem/` folder.
+- **`mcts-mem-build`** — the one-time job of reconstructing a tree from a project's history
+  (git, design docs, the author). Run it once per repository; `mcts-mem-use` keeps it
+  current afterward.
+
+Each skill is a single self-contained `SKILL.md` — the tree format and the full method are
+written inside it, so any agent that can load a skill can read and maintain a tree with no
+other setup. See [Installation](#installation) to add them to your agent.
+
+The one piece of running code is the linter: `npx mcts-mem lint <path-to-mcts_mem>`
+validates a tree the way a compiler validates source — links resolve, re-decisions agree,
+history is append-only, every claim is tagged. Run it after any edit; a clean lint is a
+cheap, mechanical guarantee that the structure holds.
+
+## Installation
+
+MCTS-Mem is **two skills** plus a helper **CLI**. Only the skills are "installed" — the CLI
+needs nothing, because the skills call it via `npx mcts-mem` on demand.
+
+### Install the skills
+
+Paste this to your coding agent (Claude Code, Cursor, Codex, Gemini CLI, …):
+
+> Install the MCTS-Mem skills. Fetch these two files from
+> https://github.com/mbbill/MCTS-Mem — `skills/mcts-mem-build/SKILL.md` and
+> `skills/mcts-mem-use/SKILL.md` — and save each into your agent's skills directory,
+> preserving the folder names (`mcts-mem-build/`, `mcts-mem-use/`).
+
+Your agent already knows where its skills live, so this works in any of them. The two skills
+are the open [Agent Skills](https://agentskills.io) format, so the same files work across
+agents — nothing here is specific to one tool.
+
+Prefer to do it by hand? Copy the two folders under `skills/` into your agent's skills path
+— e.g. `~/.claude/skills/` (personal) or `.claude/skills/` (project) for Claude Code.
+
+### The CLI
+
+No install step. The skills run the linter as `npx mcts-mem lint <path>`, which fetches the
+published package on demand.
+
+## The deeper idea
+
+Why a design memory is shaped like a *search* — and why that matters more as AI makes
+building cheap enough to explore the solution space in earnest — is in
+[`rationale.md`](rationale.md): the MCTS framing, the model's own evolution (including the
+dead ends it discarded), and the honest constraints on what it can do.

package/bin/mcts-mem.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+process.exit(run(process.argv.slice(2)));

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "mcts-mem",
+  "version": "0.1.0",
+  "description": "Build, verify, and explore an MCTS-Mem design tree — a structured, linter-checked memory of how a project was decided.",
+  "type": "module",
+  "bin": {
+    "mcts-mem": "bin/mcts-mem.js"
+  },
+  "author": "B.M. <mbbill@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mbbill/MCTS-Mem.git"
+  },
+  "homepage": "https://github.com/mbbill/MCTS-Mem#readme",
+  "bugs": {
+    "url": "https://github.com/mbbill/MCTS-Mem/issues"
+  },
+  "keywords": [
+    "mcts-mem",
+    "design-memory",
+    "design-rationale",
+    "adr",
+    "architecture",
+    "linter",
+    "agent-skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  }
+}

package/src/cli.js

@@ -0,0 +1,110 @@
+// mcts-mem — build, verify, and explore an MCTS-Mem design tree.
+
+import { lint } from './lint.js';
+import { view, show } from './view.js';
+import { uncertain } from './uncertain.js';
+
+const VERSION = '0.1.0';
+const DEFAULT_ROOT = 'mcts_mem';
+
+const HELP = `mcts-mem — work with an MCTS-Mem design tree
+(a structured, linter-checked memory of how a project was decided)
+
+usage: mcts-mem <command> [path] [options]
+       path defaults to ./${DEFAULT_ROOT}
+
+commands:
+  lint [path] [--skeleton]
+        Verify the tree against the grammar — structure, entry form, provenance
+        tags, verbatim move pairs, append-only history, links, and "every node
+        records a real decision". Run it like a compiler: after any edit, until
+        clean. Prints each violation as "[R-rule] path: message" and exits 1;
+        exits 0 when the tree is clean.
+        --skeleton  Build-time only. Skips the R-thin check (a node with no
+                    alternative / Facts / Moves / children is just a module-map
+                    entry). A freshly-built Stage-1 skeleton is nodes + items
+                    with no decisions recorded yet, so R-thin would fire on every
+                    node; lint with --skeleton until history is folded in and the
+                    tree pruned, then lint without it. (The mcts-mem-build skill
+                    drives this; you won't need it on a finished tree.)
+
+  view [path] [--alt] [--depth N]
+        Render the decision tree. Node names are styled by confidence: bold =
+        fought over (≥5 facts), dim = unweighed (reconsider freely). Annotations
+        show facts (Nf), moves (Nm), and alternatives (↩N). --alt also walks the
+        rejected alternatives; --depth limits how deep to render.
+
+  show <node> [path]
+        Print one node in full — its items, Facts, Moves, sub-decisions, and the
+        alternatives it beat. <node> is a node name or a logical path.
+
+  uncertain [path]
+        List every (uncertain) entry — the worklist of decisions whose why is not
+        yet backed by code or a source.
+
+  help | --help | -h        show this
+  --version                 print version
+`;
+
+function parse(args) {
+  const flags = {};
+  const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--depth') flags.depth = Number(args[++i]);
+    else if (a === '--skeleton') flags.skeleton = true;
+    else if (a === '--alt') flags.alt = true;
+    else if (a.startsWith('--')) flags[a.slice(2)] = true;
+    else pos.push(a);
+  }
+  return { flags, pos };
+}
+
+export function run(argv) {
+  const cmd = argv[0];
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (cmd === '--version' || cmd === '-v') {
+    console.log(VERSION);
+    return 0;
+  }
+  const { flags, pos } = parse(argv.slice(1));
+  try {
+    switch (cmd) {
+      case 'lint': {
+        const root = pos[0] || DEFAULT_ROOT;
+        const { errors, nodeCount, factCount } = lint(root, flags);
+        if (errors.length) {
+          console.error(`${errors.length} violation(s):`);
+          for (const e of errors) console.error(`  [${e.rule}] ${e.path}: ${e.msg}`);
+          return 1;
+        }
+        console.log(`lint clean: ${nodeCount} nodes, ${factCount} fact files`);
+        return 0;
+      }
+      case 'view': {
+        const root = pos[0] || DEFAULT_ROOT;
+        view(root, { alt: !!flags.alt, depth: flags.depth || Infinity });
+        return 0;
+      }
+      case 'show': {
+        if (!pos[0]) { console.error('show: needs a <node> name or logical path'); return 2; }
+        const root = pos[1] || DEFAULT_ROOT;
+        return show(root, pos[0]);
+      }
+      case 'uncertain': {
+        const root = pos[0] || DEFAULT_ROOT;
+        return uncertain(root);
+      }
+      default:
+        console.error(`unknown command: ${cmd}\n`);
+        process.stdout.write(HELP);
+        return 2;
+    }
+  } catch (e) {
+    console.error(`mcts-mem ${cmd}: ${e.message}`);
+    return 1;
+  }
+}

package/src/lint.js

@@ -0,0 +1,192 @@
+// Linter for an MCTS-Mem design tree — the executable form of the grammar the
+// skills specify. A faithful port of the rule set: structure, entry form,
+// provenance, verbatim move pairs, append-only, "not a module map", etc.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import {
+  loadTree,
+  parseNode,
+  blocks,
+  normWhy,
+  ENTRY_HEAD,
+  PROV,
+  MOVE_VERB,
+  LINK,
+} from './tree.js';
+
+export function lint(root, opts = {}) {
+  const { skeleton = false } = opts;
+  const ctx = loadTree(root);
+  const display = (p) => path.relative(path.dirname(ctx.root), p);
+  const errors = [];
+  const err = (rule, p, msg) => errors.push({ rule, path: display(p), msg });
+
+  // ---------- R-root ----------
+  const top = ctx.nodeFiles.filter((p) => path.dirname(p) === ctx.root);
+  if (top.length !== 1) {
+    err('R-root', ctx.root, `expected exactly 1 top-level node, found ${top.length}: ` +
+      top.map((t) => path.basename(t)).join(', '));
+  }
+
+  // ---------- R-orphan / R-empty ----------
+  for (const d of ctx.dirs) {
+    const name = path.basename(d);
+    const base = name.endsWith('.fact') ? name.slice(0, -5)
+      : name.endsWith('.alt') ? name.slice(0, -4) : name;
+    const sibling = path.join(path.dirname(d), base + '.md');
+    if (!fs.existsSync(sibling)) err('R-orphan', d, `directory has no sibling ${base}.md`);
+    if ((name.endsWith('.alt') || name.endsWith('.fact')) &&
+        !fs.readdirSync(d).some((f) => f.endsWith('.md'))) {
+      err('R-empty', d, 'empty structure directory');
+    }
+  }
+
+  // ---------- per-node grammar ----------
+  for (const p of ctx.nodeFiles) {
+    const node = ctx.parsed.get(p);
+    const text = node.text;
+
+    // R-title
+    const first = text.split('\n').find((l) => l.trim()) || '';
+    if (first.startsWith('#')) err('R-title', p, 'file starts with a heading; items come first, no titles');
+
+    // R-sections
+    const allowed = ['## Facts', '## Moves'];
+    const seq = node.headings;
+    const bad = seq.filter((h) => !allowed.includes(h));
+    if (bad.length) err('R-sections', p, `unexpected heading(s): ${JSON.stringify(bad)}`);
+    const order = allowed.filter((h) => seq.includes(h));
+    if (JSON.stringify(seq) !== JSON.stringify(order)) err('R-sections', p, `sections out of order: ${JSON.stringify(seq)}`);
+
+    // R-items / R-tail
+    for (const para of node.itemsText.trim().split(/\n\s*\n/)) {
+      if (!para) continue;
+      if (!para.startsWith('- ')) {
+        err('R-items', p, `non-item content in items section: ${JSON.stringify(para.split('\n')[0].slice(0, 60))}`);
+      }
+      const flat = para.replace(/\s+/g, ' ');
+      const m = /(^|[ ,;(])(so|so that|because|thus|hence|since|therefore)[ ,]/i.exec(flat);
+      if (para.startsWith('- ') && m && m[2].toLowerCase() !== 'since') {
+        err('R-tail', p, `item has a rationale tail (${JSON.stringify(m[1].trim())}); move the why to Facts/Moves: ${JSON.stringify(flat.slice(0, 70))}`);
+      }
+    }
+
+    // R-entry / R-prov / R-verb / R-join over Facts + Moves
+    for (const [kind, list] of [['Facts', node.facts], ['Moves', node.moves]]) {
+      for (const b of list) {
+        if (!ENTRY_HEAD.test(b)) err('R-entry', p, `${kind} entry malformed head: ${JSON.stringify(b.split('\n')[0].slice(0, 70))}`);
+        if (!PROV.test(b)) err('R-prov', p, `${kind} entry missing provenance tag: ${JSON.stringify(b.split('\n')[0].slice(0, 70))}`);
+        if (kind === 'Moves' && !MOVE_VERB.test(b)) err('R-verb', p, `Moves entry has no boundary verb: ${JSON.stringify(b.split('\n')[0].slice(0, 70))}`);
+        if (/\b(which is why|that is why|the reason|hence|therefore)\b/i.test(b.replace(/\s+/g, ' '))) {
+          err('R-join', p, `${kind} entry chains two claims (atomize it): ${JSON.stringify(b.split('\n')[0].slice(0, 70))}`);
+        }
+      }
+    }
+
+    // R-redundant: a rationale fact must not share a commit with a Moves entry on this node
+    const moveHashes = new Set();
+    for (const b of node.moves) { const m = ENTRY_HEAD.exec(b); if (m && m[3]) moveHashes.add(m[3]); }
+    for (const b of node.facts) {
+      const m = ENTRY_HEAD.exec(b);
+      if (m && m[4].trim() === 'rationale' && m[3] && moveHashes.has(m[3])) {
+        err('R-redundant', p, `rationale fact shares commit ${m[3]} with a move on this node; the move already records the why`);
+      }
+    }
+
+    // R-meta: the tree never references its own construction
+    for (const w of ['ledger', 'batch report', 'design tree', 'extraction run', 'deferred until']) {
+      if (text.toLowerCase().includes(w)) err('R-meta', p, `workflow-metadata vocabulary in tree: ${JSON.stringify(w)}`);
+    }
+  }
+
+  // ---------- R-link ----------
+  for (const p of ctx.nodeFiles) {
+    const text = ctx.parsed.get(p).text.replace(/`[^`]*`/g, '');
+    for (const m of text.matchAll(LINK)) {
+      if (ctx.resolve(m[1], p) === null) err('R-link', p, `unresolvable link [[${m[1]}]]`);
+    }
+  }
+
+  // ---------- R-pair: replaced <-> replaced by, verbatim why ----------
+  // The twin is matched by identity (it points back to the winner) and the why
+  // must be verbatim — NOT by hash: each side records its own commit, which may
+  // differ (only the <why> is required identical).
+  for (const p of ctx.nodeFiles) {
+    for (const b of ctx.parsed.get(p).moves) {
+      const m = /^- \S+( \([0-9a-f]{8}\))? replaced \[\[([^\]]+)\]\]:/.exec(b);
+      if (!m) continue;
+      const loserRef = m[2];
+      const loser = ctx.resolve(loserRef, p);
+      if (loser === null) continue; // R-link already fired
+      // the loser must carry a 'replaced by' move with the SAME why; the two
+      // sides' dates/hashes may differ, so match on the verbatim why, not the hash
+      const twins = (ctx.parsed.get(loser)?.moves ?? []).filter((tb) =>
+        /^- \S+( \([0-9a-f]{8}\))? replaced by \[\[/.test(tb));
+      if (!twins.length) err('R-pair', p, `replaced [[${loserRef}]] has no 'replaced by' twin in ${path.basename(loser)}`);
+      else if (!twins.some((tb) => normWhy(tb) === normWhy(b))) err('R-pair', p, `why differs from twin in ${path.basename(loser)}`);
+    }
+  }
+
+  // ---------- R-frozen ----------
+  for (const p of ctx.nodeFiles) {
+    const inAltMember = path.basename(path.dirname(p)).endsWith('.alt');
+    const inAltSubtree = p.includes('.alt' + path.sep);
+    const mv = ctx.parsed.get(p).moves;
+    const last = mv.length ? mv[mv.length - 1] : '';
+    if (inAltMember && !/(replaced by \[\[|removed:)/.test(last)) {
+      err('R-frozen', p, ".alt member's Moves must end in 'replaced by'/'removed'");
+    }
+    if (!inAltSubtree && /replaced by \[\[/.test(last) && !last.includes('revived')) {
+      err('R-frozen', p, "main-tree node ends 'replaced by' (should it be in .alt/?)");
+    }
+  }
+
+  // ---------- R-thin (skipped under --skeleton) ----------
+  if (!skeleton) {
+    for (const p of ctx.nodeFiles) {
+      const base = p.slice(0, -3);
+      const hasMd = (dir) => fs.existsSync(dir) && fs.readdirSync(dir).some((f) => f.endsWith('.md'));
+      const node = ctx.parsed.get(p);
+      if (!(hasMd(base + '.alt') || hasMd(base) || node.facts.length || node.moves.length)) {
+        err('R-thin', p, 'node has no .alt/, no Facts, no Moves, and no children — it asserts a ' +
+          'component without recording a decision (module-map node); fold it into its parent, or ' +
+          'record the decision (alternative, rationale fact)');
+      }
+    }
+  }
+
+  // ---------- R-factfile ----------
+  for (const p of ctx.factFiles) {
+    if (/^#+ /m.test(fs.readFileSync(p, 'utf8'))) err('R-factfile', p, 'fact file contains headings');
+  }
+
+  // ---------- R-append: Facts/Moves are append-only vs git HEAD ----------
+  // A deliberate, bulk rewrite of committed history (a sanctioned migration) is
+  // handled by committing it — once committed, HEAD is the new baseline and this
+  // passes; there is no flag to switch the integrity check off.
+  {
+    const git = (...a) => execFileSync('git', a, { cwd: ctx.root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    let repoRoot = null;
+    try { repoRoot = git('rev-parse', '--show-toplevel').trim(); } catch { /* not a git repo */ }
+    if (repoRoot) {
+      const treeEntries = new Set();
+      for (const p of ctx.nodeFiles) {
+        const n = ctx.parsed.get(p);
+        for (const b of [...n.facts, ...n.moves]) treeEntries.add(b.replace(/\s+/g, ' '));
+      }
+      for (const p of ctx.nodeFiles) {
+        const rel = path.relative(repoRoot, p);
+        let old;
+        try { old = git('show', `HEAD:${rel}`); } catch { continue; } // new file
+        const on = parseNode(old);
+        const oldEntries = [...on.facts, ...on.moves].map((b) => b.replace(/\s+/g, ' '));
+        const gone = oldEntries.filter((e) => !treeEntries.has(e));
+        if (gone.length) err('R-append', p, `${gone.length} committed Facts/Moves entr${gone.length === 1 ? 'y' : 'ies'} edited or removed`);
+      }
+    }
+  }
+
+  return { errors, nodeCount: ctx.nodeFiles.length, factCount: ctx.factFiles.length };
+}

package/src/tree.js

@@ -0,0 +1,194 @@
+// Shared model of an MCTS-Mem design tree: walk the filesystem, parse each node
+// into items / Facts / Moves, and resolve [[links]]. Every other command builds
+// on this. The parsing here mirrors the grammar the linter enforces.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const ENTRY_HEAD =
+  /^- (\d{4}-\d{2}-\d{2})( \(([0-9a-f]{8})\))? ([a-z][a-z -]*?)(:| \[\[)/;
+export const PROV = /\((code|sourced|uncertain)\)\.?\s*$/;
+export const MOVE_VERB =
+  /^- \S+( \([0-9a-f]{8}\))? (replaced by \[\[[^\]]+\]\]:|replaced \[\[[^\]]+\]\]:|dropped:|removed:|revived:)/;
+export const LINK = /\[\[([^\]]+)\]\]/g;
+
+// split a section body into "- " entry blocks separated by blank lines
+export function blocks(text) {
+  const out = [];
+  let cur = [];
+  for (const line of (text || '').split('\n')) {
+    if (line.startsWith('- ') && cur.length) {
+      out.push(cur.join('\n'));
+      cur = [line];
+    } else if (line.trim() === '') {
+      if (cur.length) { out.push(cur.join('\n')); cur = []; }
+    } else if (cur.length) {
+      cur.push(line);
+    } else if (line.startsWith('- ')) {
+      cur = [line];
+    }
+  }
+  if (cur.length) out.push(cur.join('\n'));
+  return out.filter((b) => b.trim());
+}
+
+// strip entry head + provenance, collapse whitespace and backticks → comparable why
+export function normWhy(b) {
+  let s = b.replace(/^- [^:]*?(?:\[\[[^\]]+\]\])?:/, '');
+  s = s.trim().replace(PROV, '');
+  return s.replace(/`/g, '').replace(/\s+/g, ' ').trim().replace(/\.+$/, '');
+}
+
+// parse one node file into its three parts plus the raw heading list (for R-sections)
+export function parseNode(text) {
+  text = text.replace(/\r\n?/g, '\n'); // normalize CRLF / lone CR so headings parse
+  const headings = [];
+  const sections = {};
+  let itemsLines = [];
+  let curName = null;
+  let cur = [];
+  for (const line of text.split('\n')) {
+    const h = /^(#+ .*)$/.exec(line);
+    if (h) {
+      headings.push(h[1]);
+      if (curName !== null) sections[curName] = cur.join('\n');
+      const hm = /^## (.+)$/.exec(line);
+      curName = hm ? hm[1].trim() : ` ${headings.length}`;
+      cur = [];
+    } else if (curName === null) {
+      itemsLines.push(line);
+    } else {
+      cur.push(line);
+    }
+  }
+  if (curName !== null) sections[curName] = cur.join('\n');
+  return {
+    text,
+    headings,
+    itemsText: itemsLines.join('\n'),
+    facts: blocks(sections.Facts ?? ''),
+    moves: blocks(sections.Moves ?? ''),
+  };
+}
+
+// parse an entry block into structured fields (for view / uncertain)
+export function parseEntry(block) {
+  const flat = block.replace(/\s+/g, ' ').trim();
+  const m = ENTRY_HEAD.exec(block);
+  const tagM = PROV.exec(flat);
+  const isMove = MOVE_VERB.test(block);
+  let verb = null;
+  if (isMove) {
+    const vm = /(replaced by|replaced|dropped|removed|revived)/.exec(flat);
+    verb = vm ? vm[1] : null;
+  }
+  return {
+    raw: block,
+    flat,
+    date: m ? m[1] : null,
+    hash: m ? m[3] || null : null,
+    kind: m ? m[4].trim() : null,
+    tag: tagM ? tagM[1] : null,
+    isMove,
+    verb,
+  };
+}
+
+function stemOf(p) {
+  return path.basename(p).slice(0, -3);
+}
+
+// logical path: relative to root, with .alt segments stripped (pivot-proof)
+export function logical(root, p) {
+  const rel = path.relative(root, p).slice(0, -3);
+  return rel
+    .split(path.sep)
+    .map((seg) => (seg.endsWith('.alt') ? seg.slice(0, -4) : seg))
+    .join('/');
+}
+
+// Load and parse a whole tree rooted at `root` (the dir holding the single top node).
+export function loadTree(root) {
+  root = path.resolve(root);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`tree root not found: ${root}`);
+  }
+  // canonicalize symlinks so paths agree with git's `rev-parse --show-toplevel`
+  // (otherwise the R-append check silently no-ops under /tmp, /var → /private, etc.)
+  root = fs.realpathSync(root);
+  const nodeFiles = [];
+  const factFiles = [];
+  const dirs = [];
+  (function rec(d) {
+    let ents;
+    try {
+      ents = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of ents) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) {
+        dirs.push(full);
+        rec(full);
+      } else if (e.name.endsWith('.md')) {
+        (path.basename(d).endsWith('.fact') ? factFiles : nodeFiles).push(full);
+      }
+    }
+  })(root);
+
+  const parsed = new Map();
+  for (const p of nodeFiles) parsed.set(p, parseNode(fs.readFileSync(p, 'utf8')));
+
+  const stems = new Map();
+  for (const p of nodeFiles) {
+    const s = stemOf(p);
+    if (!stems.has(s)) stems.set(s, []);
+    stems.get(s).push(p);
+  }
+
+  const ctx = { root, nodeFiles, factFiles, dirs, parsed, stems };
+  ctx.stem = stemOf;
+  ctx.logical = (p) => logical(root, p);
+  ctx.resolve = (ref, frm) => resolve(ctx, ref, frm);
+  return ctx;
+}
+
+// resolve a [[link]] target to a node (or fact) file path, or null
+export function resolve(ctx, ref, frm) {
+  if (ref.includes('.fact/')) {
+    const tail = ref.split('/').pop() + '.md';
+    const cand = ctx.factFiles.filter(
+      (f) => f.endsWith(tail) || logical(ctx.root, f).endsWith(ref)
+    );
+    return cand[0] ?? null;
+  }
+  const name = ref.split('/').pop();
+  const cands = ctx.stems.get(name) ?? [];
+  if (cands.length === 1) return cands[0];
+  const near = cands.filter(
+    (c) =>
+      path.dirname(c).startsWith(path.dirname(frm)) ||
+      path.dirname(frm).startsWith(path.dirname(c).replace('.alt', ''))
+  );
+  return near.length === 1 ? near[0] : cands[0] ?? null;
+}
+
+// structural relatives of a node file p = <dir>/<name>.md
+export function relatives(ctx, p) {
+  const base = p.slice(0, -3); // strip .md
+  const subtree = base; // <dir>/<name>/
+  const altDir = base + '.alt';
+  const factDir = base + '.fact';
+  const childOf = (dir) =>
+    ctx.nodeFiles.filter((q) => path.dirname(q) === dir).sort();
+  const factsIn = (dir) =>
+    fs.existsSync(dir)
+      ? fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort()
+      : [];
+  return {
+    children: childOf(subtree),
+    alts: childOf(altDir),
+    factFiles: factsIn(factDir).map((f) => path.join(factDir, f)),
+  };
+}

package/src/uncertain.js

@@ -0,0 +1,37 @@
+// List every (uncertain) entry — the worklist of decisions whose *why* is not
+// yet backed by the code or any source. Resolve these by finding a source,
+// asking a human, or accepting they are lost; never by guessing.
+
+import { loadTree, parseEntry } from './tree.js';
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const dim = (s) => c('2', s);
+const bold = (s) => c('1', s);
+
+export function uncertain(root) {
+  const ctx = loadTree(root);
+  let n = 0;
+  for (const p of ctx.nodeFiles) {
+    const node = ctx.parsed.get(p);
+    const hits = [...node.facts, ...node.moves]
+      .map(parseEntry)
+      .filter((e) => e.tag === 'uncertain');
+    if (!hits.length) continue;
+    console.log(bold(ctx.logical(p)));
+    for (const e of hits) {
+      n++;
+      const claim = e.flat
+        .replace(/^- [^:]*?(?:\[\[[^\]]+\]\])?:/, '')
+        .replace(/\(uncertain\)\.?\s*$/, '')
+        .trim();
+      console.log('  ' + dim(`${e.date || ''} ${e.hash ? '(' + e.hash + ')' : ''}`.trim()) + ` ${claim}`);
+    }
+  }
+  console.log();
+  console.log(n === 0
+    ? 'no open uncertainties — every recorded why is backed by code or a source.'
+    : dim(`${n} uncertain ${n === 1 ? 'entry' : 'entries'}: each is a real decision whose why is unbacked. ` +
+        'Resolve by finding a source, asking a human, or accepting it is lost — never by guessing.'));
+  return 0;
+}

package/src/view.js

@@ -0,0 +1,155 @@
+// Explore an MCTS-Mem tree from the terminal: render the decision tree with
+// confidence signals (fact density, alternatives), and show a single node.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadTree, parseEntry, relatives } from './tree.js';
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const dim = (s) => c('2', s);
+const bold = (s) => c('1', s);
+const cyan = (s) => c('36', s);
+const yellow = (s) => c('33', s);
+
+function build(ctx, p) {
+  const rel = relatives(ctx, p);
+  const node = ctx.parsed.get(p);
+  return {
+    p,
+    name: ctx.stem(p),
+    facts: node.facts.length,
+    moves: node.moves.length,
+    altCount: rel.alts.length,
+    children: rel.children.map((q) => build(ctx, q)),
+    alts: rel.alts.map((q) => build(ctx, q)),
+  };
+}
+
+function annot(n) {
+  const bits = [];
+  if (n.facts) bits.push(dim(`${n.facts}f`));
+  if (n.moves) bits.push(dim(`${n.moves}m`));
+  if (n.altCount) bits.push(dim(`↩${n.altCount}`));
+  return bits.length ? '  ' + bits.join(' ') : '';
+}
+
+// name styled by confidence signal: thick with facts = fought over; no signal = reconsider freely
+function label(n, rejected) {
+  let name = n.name;
+  if (rejected) return dim('✗ ' + name);
+  if (n.facts >= 5) name = bold(name);
+  else if (n.facts === 0 && n.moves === 0 && n.altCount === 0) name = dim(name);
+  return name + annot(n);
+}
+
+function renderTree(ctx, { alt = false, depth = Infinity } = {}) {
+  const top = ctx.nodeFiles.filter((p) => path.dirname(p) === ctx.root);
+  if (top.length !== 1) {
+    console.log(yellow(`(tree has ${top.length} top-level nodes; expected 1 — run \`mcts-mem lint\`)`));
+    if (!top.length) return;
+  }
+  const root = build(ctx, top[0]);
+  console.log(label(root, false));
+  const walk = (n, prefix, d) => {
+    if (d <= 0) return;
+    const kids = [
+      ...n.children.map((k) => [k, false]),
+      ...(alt ? n.alts.map((k) => [k, true]) : []),
+    ];
+    kids.forEach(([k, rej], i) => {
+      const last = i === kids.length - 1;
+      console.log(prefix + dim(last ? '└─ ' : '├─ ') + label(k, rej));
+      walk(k, prefix + (last ? '   ' : dim('│') + '  '), d - 1);
+    });
+  };
+  walk(root, '', depth);
+  console.log();
+  console.log(dim('legend: ') + bold('bold') + dim(' = fought over (≥5 facts) · ') +
+    dim('dim') + dim(' = unweighed, reconsider freely · Nf facts · Nm moves · ↩N alternatives'));
+  if (!alt) console.log(dim('        pass --alt to walk the rejected alternatives'));
+}
+
+function findNode(ctx, query) {
+  const q = query.replace(/\.md$/, '');
+  const exact = ctx.nodeFiles.filter((p) => ctx.stem(p) === q);
+  if (exact.length === 1) return exact[0];
+  const byLogical = ctx.nodeFiles.filter((p) => ctx.logical(p) === q || ctx.logical(p).endsWith('/' + q));
+  const pool = exact.length ? exact : byLogical;
+  return pool.length === 1 ? pool[0] : pool;
+}
+
+function showNode(ctx, query) {
+  const found = findNode(ctx, query);
+  if (Array.isArray(found)) {
+    if (!found.length) { console.log(yellow(`no node matches "${query}"`)); return 1; }
+    console.log(yellow(`"${query}" is ambiguous — ${found.length} matches:`));
+    for (const p of found) console.log('  ' + ctx.logical(p));
+    return 1;
+  }
+  const p = found;
+  const node = ctx.parsed.get(p);
+  const rel = relatives(ctx, p);
+  const inAlt = p.includes('.alt' + path.sep);
+
+  console.log(bold(ctx.logical(p)) + (inAlt ? '  ' + dim('(superseded / rejected — in .alt/)') : ''));
+  console.log();
+  // Items
+  const items = node.itemsText.trim();
+  if (items) console.log(items);
+  // Facts
+  if (node.facts.length) {
+    console.log('\n' + cyan('## Facts'));
+    for (const b of node.facts) {
+      const e = parseEntry(b);
+      console.log('  ' + dim(`${e.date || ''} ${e.hash ? '(' + e.hash + ')' : ''}`.trim()) +
+        ` ${e.kind || ''}` + (e.tag ? ' ' + tagColor(e.tag) : ''));
+      console.log('    ' + claim(e));
+    }
+  }
+  // Moves
+  if (node.moves.length) {
+    console.log('\n' + cyan('## Moves'));
+    for (const b of node.moves) {
+      const e = parseEntry(b);
+      console.log('  ' + dim(`${e.date || ''} ${e.hash ? '(' + e.hash + ')' : ''}`.trim()) +
+        ` ${e.verb || ''}` + (e.tag ? ' ' + tagColor(e.tag) : ''));
+      console.log('    ' + claim(e));
+    }
+  }
+  // relatives
+  if (rel.children.length) {
+    console.log('\n' + cyan('sub-decisions:'));
+    for (const q of rel.children) console.log('  ' + ctx.stem(q));
+  }
+  if (rel.alts.length) {
+    console.log('\n' + cyan('alternatives (rejected / superseded):'));
+    for (const q of rel.alts) console.log('  ' + dim('✗ ') + ctx.stem(q));
+  }
+  if (rel.factFiles.length) {
+    console.log('\n' + cyan('graduated evidence (.fact/):'));
+    for (const f of rel.factFiles) console.log('  ' + path.basename(f));
+  }
+  return 0;
+}
+
+function tagColor(tag) {
+  if (tag === 'code') return c('32', '(code)');
+  if (tag === 'sourced') return c('34', '(sourced)');
+  if (tag === 'uncertain') return c('33', '(uncertain)');
+  return `(${tag})`;
+}
+
+// the entry text minus its "- date (hash) kind:" / "- ... verb:" head and trailing tag
+function claim(e) {
+  let s = e.flat.replace(/^- [^:]*?(?:\[\[[^\]]+\]\])?:/, '').trim();
+  s = s.replace(/\((code|sourced|uncertain)\)\.?\s*$/, '').trim();
+  return s;
+}
+
+export function view(root, opts) {
+  return renderTree(loadTree(root), opts);
+}
+export function show(root, query) {
+  return showNode(loadTree(root), query);
+}