klypix-mcp 1.48.0 → 1.49.1

package/README.md

@@ -292,12 +292,43 @@ Apache-2.0 and work with no app installed. The app's interface is available in E
 
 ## Git and concurrency
 
-One file in your repo, committed with your code — versioned, branchable, portable.
+One file in your repo, committed with your code — versioned, branchable, portable. So two
+developers already share one brain the way they share code: clone, branch, pull.
 
-Be precise about what git does here: `brain.klypix` is a binary ZIP. Git shows
-`Bin 1308328 -> 1309005 bytes`, produces zero line diffs, and a merge conflict on it is an
-all-or-nothing take-ours or take-theirs. You cannot review a brain change in a PR diff. **All
-card-level merge safety comes from the KLYPIX engine, not from git.**
+Be precise about what git does on its own: `brain.klypix` is a binary ZIP. Git shows
+`Bin 1308328 -> 1309005 bytes` and produces zero line diffs, so out of the box a conflict on it is
+an all-or-nothing take-ours or take-theirs, and a reviewer sees nothing. **Card-level merge safety
+comes from the KLYPIX engine** — but since 1.48.0 you can hand that engine to git and read its
+output in a PR:
+
+```bash
+npx klypix-mcp git-driver install     # once per clone, in any repo
+```
+
+That registers a merge driver for `*.klypix` (a per-machine git config line plus a `.gitattributes`
+rule you commit) and provisions the engine it needs. When two people change the brain and one
+pulls, git calls the engine instead of stopping: new cards from both sides are kept, a card only
+one side edited takes that edit, and a card edited differently on both sides keeps **both**
+versions — the second as a linked twin, never a silent overwrite. Before returning, the merge
+asserts it still contains every surviving card from both sides and refuses rather than hand back a
+result that lost one.
+
+The honest boundary: a machine that has not run `git-driver install` simply gets the old binary
+conflict — safe degradation, not corruption — and git keeps both parents of every merge, so even a
+merge you dislike is reconstructable. It is a merge *on pull*, not live sync.
+
+For review, two commands turn a binary blob into something a human can read:
+
+```bash
+npx klypix-mcp diff main            # card-level: what was added / updated / removed
+npx klypix-mcp pr-brief origin/main # the brain cards that reference this PR's changed files
+```
+
+`diff` compares meaning rather than bytes (a re-save restamps timestamps; that is not a change).
+`pr-brief` matches a card's `#file-…` evidence anchors against the changed paths, so a reviewer
+sees the decisions already recorded about the code in front of them. `examples/github/brain-pr.yml`
+wires both into a sticky pull-request comment using nothing but the checkout and the default
+`GITHUB_TOKEN` — no KLYPIX service in the path.
 
 Concurrent sessions serialize behind a capture lock, and each write is a temp file plus an atomic
 rename, so a crash mid-write leaves the previous good file intact. The lock is advisory with a
@@ -307,6 +338,24 @@ was judged worse — but it is a real limit, not a guarantee.
 
 ---
 
+## The command line
+
+The MCP verbs below are what agents call. These are what **you** call:
+
+| Command | What it does |
+|---|---|
+| `npx klypix-mcp init` | Seed a starter `brain.klypix` here and print an MCP config |
+| `npx klypix-mcp install` | Install the engine + Claude Code hooks on this machine (see Quick start) |
+| `npx klypix-mcp link` | Wire this project for Cursor, Cline, Windsurf, Copilot, Gemini CLI, Aider (`--check` audits) |
+| `npx klypix-mcp doctor` | One verdict: version, hosts, live sessions, tool count, drift. Exits non-zero — usable as a CI gate |
+| `npx klypix-mcp conformance` | Launch two real MCP clients against this build and verify coordination behaviour |
+| `npx klypix-mcp git-driver` | Register the lossless `.klypix` merge driver for a repo (`status` to check) |
+| `npx klypix-mcp diff [ref]` | Card-level brain diff against a git ref, as markdown |
+| `npx klypix-mcp pr-brief [ref]` | Brain cards referencing the files changed since a ref, as markdown |
+| `npx klypix-mcp garden-code` | Print the human approval code `brain_garden` requires |
+
+---
+
 ## The 18 verbs
 
 | Tool | What it does |
@@ -477,9 +526,9 @@ Read this section before you build on any of it.
 Every number here is measured on our own project brain. Nothing below is published, benchmarked or
 independently validated.
 
-- **Dogfood scale.** KLYPIX itself is built with its own brain: **1,523 cards and 1,404
+- **Dogfood scale.** KLYPIX itself is built with its own brain: **1,645 cards and 1,521
   connections**, written by multiple concurrent agent sessions, receipts in the file. Current as of
-  2026-07-30.
+  2026-08-01.
 - **Recall.** 73% of past decisions recovered with one search round, 55% brief-only, 0% cold.
   Caveat that travels with it: n=20, our own brain, self-authored questions, LLM-judged.
 - **Ranker.** recall@5 of the true source card went **15% → 40%** across two upgrades (n=20 frozen
@@ -487,7 +536,7 @@ independently validated.
   experiment that *regressed* — contextual prefixes on short cards — is recorded next to the wins.
 - **What we do not publish.** No download count: this package's own 24-hour auto-updater generates
   most of it, so it is not a user count. No adoption, team or customer figures. No brief-token
-  figure — the last one was measured at ~600 cards and is stale at 1,523.
+  figure — the last one was measured at ~600 cards and is stale at 1,645.
 - **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The
   numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.48.0",
+  "version": "1.49.1",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",

package/src/klypix-merge-driver.mjs

@@ -31,7 +31,7 @@
 // resolves to the edit — no-loss wins over delete).
 
 import fs from 'node:fs';
-import { mergeBrains } from './merge-brains.mjs';
+import { mergeBrains, sameMeaning } from './merge-brains.mjs';
 import { parseKlypix, shard } from './klypix-format.mjs';
 
 // id -> verbatim item JSON string for one side (null for an empty/absent side).
@@ -68,8 +68,11 @@ try {
       const inA = ai.has(id), inB = ti.has(id);
       if (inA && inB) continue;                                   // alive on both
       if (!inA && !inB) { deletedIds.push(id); continue; }        // deleted on both
+      // "Untouched" by MEANING, not bytes — a side that merely re-saved the
+      // file restamps volatile fields (updatedAt), and a byte compare would
+      // read that as an edit and silently refuse to propagate a real delete.
       const survivorJson = inA ? ai.get(id) : ti.get(id);
-      if (survivorJson === baseJson) deletedIds.push(id);         // delete vs untouched → honor
+      if (sameMeaning(survivorJson, baseJson)) deletedIds.push(id);   // delete vs untouched → honor
       // delete vs EDIT → no tombstone; union keeps the edited card
     }
   }

package/src/merge-brains.mjs

@@ -40,9 +40,56 @@ const isValidZKey = (k) => { try { generateKeyBetween(k, null); return true; } c
 const rand = () => Math.random().toString(36).slice(2, 10);
 const ARCHIVE = /^archive$/i;
 
-// Load one .klypix buffer into a flat, comparison-friendly shape. Unchanged
-// cards across ancestor/descendant buffers keep byte-identical item JSON, so a
-// simple string compare detects real content edits.
+// ── Semantic item comparison (2026-08-01 field fix) ─────────────────────────
+// A raw byte compare of item JSON was the change detector, on the assumption
+// that "unchanged cards keep byte-identical JSON". That assumption DIED the
+// day cards gained touch metadata: `updatedAt` is restamped whenever a card is
+// written, so two sides holding the SAME card with the SAME text differ in
+// bytes — and every first real sync spawned __agconf conflict twins for cards
+// nobody edited (field-proven on the founder's pump-doctor brain: 5 twins,
+// differing field list = ["updatedAt"] exactly).
+//
+// The fix is the same discipline the sync core and the brain diff already use:
+// compare PARSED MEANING with volatile/derived fields stripped, key-sorted so
+// two writers' key orders can't fake a difference. Byte-compare survives as the
+// fallback for anything unparseable — a malformed item must never crash a merge.
+//
+// VOLATILE = written by the act of saving, not by a human/agent decision:
+//   updatedAt — touch timestamp        zIndex — display order derived from zKey
+// Everything else (content, colors, geometry, evidence, author…) stays load-
+// bearing: a real edit to any of them is still a real conflict.
+const VOLATILE_ITEM_FIELDS = ['updatedAt', 'zIndex'];
+
+const sortedStable = (v) => JSON.stringify(v, (_k, val) =>
+  (val && typeof val === 'object' && !Array.isArray(val))
+    ? Object.fromEntries(Object.keys(val).sort().map(k => [k, val[k]]))
+    : val);
+
+function itemSignature(json) {
+  if (json == null) return null;
+  try {
+    const obj = JSON.parse(json);
+    for (const f of VOLATILE_ITEM_FIELDS) delete obj[f];
+    return sortedStable(obj);
+  } catch {
+    return json;                      // unparseable → byte identity, as before
+  }
+}
+
+/** True when two item JSON strings mean the same thing (volatile fields aside).
+ *  EXPORTED as the single definition of "did this card actually change" — the
+ *  git merge driver and the Brain Sync core both decide committed-absence
+ *  tombstones with it, so all three transports agree on what an edit is. */
+export const sameMeaning = (a, b) => {
+  if (a === b) return true;           // fast path: byte-identical
+  if (a == null || b == null) return false;
+  return itemSignature(a) === itemSignature(b);
+};
+
+// Load one .klypix buffer into a flat, comparison-friendly shape. Item JSON is
+// kept VERBATIM (the merge must write back exactly what a side held); whether
+// two versions actually differ is decided by sameMeaning(), never by these
+// bytes — see its note on volatile fields.
 async function loadSide(buf) {
   if (!buf) return null;
   const { zip, canvas, manifest, struct } = await parseKlypix(buf);
@@ -128,9 +175,13 @@ export async function mergeBrains({ base = null, ours, theirs, deletedIds = [] }
     // ── Choose CONTENT ──────────────────────────────────────────────────────
     let json, side;
     if (inO && inT) {
-      const oChg = !inB || O.items[id] !== baseItem(id);
-      const tChg = !inB || T.items[id] !== baseItem(id);
-      if (inB && oChg && tChg && O.items[id] !== T.items[id]) {
+      // Change + divergence are judged by MEANING, not bytes (see sameMeaning):
+      // a restamped `updatedAt` is not an edit, and two copies of one card that
+      // differ only in volatile fields are not in conflict.
+      const oChg = !inB || !sameMeaning(O.items[id], baseItem(id));
+      const tChg = !inB || !sameMeaning(T.items[id], baseItem(id));
+      const diverged = !sameMeaning(O.items[id], T.items[id]);
+      if (inB && oChg && tChg && diverged) {
         // GENUINE content conflict: a card that EXISTED at open, edited differently
         // on both sides → human stays live, agent version preserved as a twin.
         json = O.items[id]; side = 'ours';
@@ -138,7 +189,7 @@ export async function mergeBrains({ base = null, ours, theirs, deletedIds = [] }
         extras.push({ id: twinId, json: T.items[id], srcPos: T.positions[id] || O.positions[id], of: id });
         conflicts.push({ id, kind: 'content', keptLive: 'ours', twin: twinId });
       } else if (tChg && !oChg) { json = T.items[id]; side = 'theirs'; delta.updated.push(id); }
-      else if (!inB && O.items[id] !== T.items[id]) {
+      else if (!inB && diverged) {
         // Same NEW card (same id) present on BOTH sides but never in base — e.g. an
         // agent card the app also holds via live-apply, re-serialized slightly
         // differently. It's the SAME card, NOT a conflict → take the disk/agent