klypix-mcp 1.21.2 → 1.22.0

package/README.md

@@ -75,6 +75,23 @@ or the Claude Code project-brain hook. (`search_all_brains` is also hook-fed —
 reads the cross-project registry the hook writes, so it stays empty until a hook
 has registered at least one brain.)
 
+### Updates — the propagation contract
+
+`npx klypix-mcp install` lays the whole brain (hooks + engine + local MCP server)
+into `~/.claude/project-brain`, and the emitted MCP config runs the server **from
+that installed bundle** (no npx cache to go stale). From then on updates are
+automatic: at session start the hook checks npm (≤ once/24h, fail-open, disable
+with `KLYPIX_AUTO_UPDATE=0`) and self-installs a newer release, so a publish
+reaches every machine by its **next session**.
+
+One honest caveat: a running stdio MCP server can't hot-swap, and **resuming a
+session (or opening a new chat in the same app) does not respawn it** — only a
+full app quit + reopen (or `/mcp` reconnect after the old process exits) starts
+the new binary. `brain_doctor` tells you when that's needed: its RUNNING line
+compares the *live server's* self-reported version against the installed bundle
+and npm, and reads `DRIFTED → /mcp reconnect` instead of pretending a stale
+server is current.
+
 ## Also speaks A2A (Agent-to-Agent)
 
 The same engine is exposed as an **A2A agent** so other agents and orchestrators

package/bin/klypix-install.mjs

@@ -224,7 +224,8 @@ try {
     else console.error(`⚠ readiness: ${notWired.length} hook(s) did NOT take (${notWired.join(', ')}) — the brain will read but not capture/sync. Re-run \`npx klypix-mcp install --force\` or check ${SETTINGS}.`);
     console.log(`✓ MCP server runs from the local bundle (node ${fwd(path.join(BRAIN_DIR, 'klypix-mcp-server.mjs'))}) — no npx cache, works offline, always the installed version.`);
     if (migrated) console.log(`✓ migrated ${migrated.file} klypix-canvas server: ${migrated.from} → ${migrated.to} (backup: .mcp.json.klypix-bak). Reconnect (/mcp) or restart to pick it up.`);
-    console.log('  Every project with a ./brain.klypix now auto-reads its brief + captures decisions. Restart open Claude Code sessions to load the hooks.');
+    console.log('  Every project with a ./brain.klypix now auto-reads its brief + captures decisions.');
+    console.log('  ⚠ Open sessions keep their OLD server until relaunched: fully quit & reopen the app (a session resume / new chat does NOT respawn the MCP server). `brain_doctor`\'s RUNNING line confirms when you\'re current.');
     console.log('  Verify anytime: `npx klypix-mcp doctor` (is the brain current + wired + in sync, who else is live).');
 } catch (e) {
     if (gotLock) releaseLock();

package/bin/klypix-mcp.mjs

@@ -154,7 +154,7 @@ server.registerTool('brain_connect', {
 
 server.registerTool('brain_reconcile', {
   title: 'Reconcile the brain — contradictions between cards + unrecorded migrations',
-  description: 'Truth maintenance. (1) CONTRADICTIONS: finds same-subject live card pairs where one carries an explicit correction cue (uppercase "CORRECTION", "was WRONG", "OBSOLETE" — that side is the presumed truth) or the two use opposite polarity words (deferred↔wired, broken↔fixed, dead↔live), i.e. stale facts whose correction never got linked — candidates only, YOU confirm each: retire the stale card via brain_note ✓. Dismiss a FALSE positive (either kind) by connecting the two ids with brain_connect pairs + relationship:"not_contradiction" — persisted, so it never resurfaces. (2) MIGRATIONS: lists committed migration files (Supabase / Rails / Prisma / Knex / generic) that NO brain card references, so an applied-but-unnarrated rollout can be recorded. (3) LEGACY: pre-v1.15 raw-bash ship cards to tidy. Reads ONLY the filesystem — never the database, never the network — and changes nothing. Run it periodically, or when recall surfaces something you believe is stale.',
+  description: 'Truth maintenance. (1) CONTRADICTIONS: finds same-subject live card pairs where one carries an explicit correction cue (uppercase "CORRECTION", "was WRONG", "OBSOLETE" — that side is the presumed truth, UNLESS the cue predates its counterpart: then the pair is marked "presumed superseded" and the newer card is presumed current — verify before retiring) or the two use opposite polarity words (deferred↔wired, broken↔fixed, dead↔live), i.e. stale facts whose correction never got linked — candidates only, YOU confirm each: retire the stale card via brain_note ✓. Dismiss a FALSE positive (either kind) by connecting the two ids with brain_connect pairs + relationship:"not_contradiction" — persisted, so it never resurfaces (and its cue stops overlaying recall/ask for that pair). (2) MIGRATIONS: lists committed migration files (Supabase / Rails / Prisma / Knex / generic) that NO brain card references, so an applied-but-unnarrated rollout can be recorded. (3) LEGACY: pre-v1.15 raw-bash ship cards to tidy. Reads ONLY the filesystem — never the database, never the network — and changes nothing. Run it periodically, or when recall surfaces something you believe is stale.',
   inputSchema: {
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
     root: z.string().optional().describe("Project root holding the migrations dir (default: the brain file's folder)."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.21.2",
+  "version": "1.22.0",
   "description": "An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.",
   "type": "module",
   "license": "MIT",
@@ -53,7 +53,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs"
+    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/src/klypix-core.mjs

@@ -452,10 +452,13 @@ export async function opBrainReconcile({ vault, canvas, root, mode = 'all' }) {
 
   // (1) CONTRADICTIONS — the brain reconciled against ITSELF. Same-subject live
   // pairs where one side carries an explicit correction cue (that side is the
-  // presumed truth) or the two use opposite polarity words (deferred↔wired,
-  // broken↔fixed …). Candidates only — nothing is changed here; the agent/human
-  // confirms each. This is the retroactive cleaner for stale/correction pairs
-  // that slipped past capture (cross-area + reworded → no supersede possible).
+  // presumed truth — UNLESS the cue predates its counterpart, then the newer
+  // card is presumed to have superseded the correction and the pair is marked
+  // "presumed superseded") or the two use opposite polarity words
+  // (deferred↔wired, broken↔fixed …). Candidates only — nothing is changed
+  // here; the agent/human confirms each. This is the retroactive cleaner for
+  // stale/correction pairs that slipped past capture (cross-area + reworded →
+  // no supersede possible).
   if (mode === 'all' || mode === 'contradictions') {
     const pairs = detectContradictions(struct);
     if (pairs.length) {
@@ -464,7 +467,7 @@ export async function opBrainReconcile({ vault, canvas, root, mode = 'all' }) {
         `${i + 1}. ${p.why} · overlap ${p.overlap}\n`
         + `   · likely STALE   [${p.stale.area || '?'}] (id ${p.stale.id}) ${flat(p.stale.text).slice(0, 180)}\n`
         + `   · likely CURRENT [${p.fresh.area || '?'}] (id ${p.fresh.id}) ${flat(p.fresh.text).slice(0, 180)}`);
-      sections.push(`# ⚔️ ${pairs.length} contradiction candidate(s) — confirm, then reconcile\n_Candidates only — nothing was changed. For each REAL contradiction: retire the stale card with \`brain_note\` marker \`✓\` (text = what it resolved to), or record a correction-cue decision ("CORRECTION: …", uppercase) — capture auto-supersedes it across areas. Dismissing a FALSE positive (either kind — polarity OR correction-cue): \`brain_connect\` with \`pairs:[{fromId, toId}]\` and \`relationship:"not_contradiction"\` using the ids above — the dismissal is persisted, so that pair never resurfaces here again._\n\n${lines.join('\n')}`);
+      sections.push(`# ⚔️ ${pairs.length} contradiction candidate(s) — confirm, then reconcile\n_Candidates only — nothing was changed. For each REAL contradiction: retire the stale card with \`brain_note\` marker \`✓\` (text = what it resolved to), or record a correction-cue decision ("CORRECTION: …", uppercase) — capture auto-supersedes it across areas. A pair marked "presumed superseded" is INVERTED — its correction card PREDATES its counterpart (e.g. the old fact was re-captured after the correction): verify which side is real before retiring anything; if the correction still holds, re-assert it (a \`~\` update or a fresh CORRECTION card) instead of retiring it. Dismissing a FALSE positive (either kind — polarity OR correction-cue): \`brain_connect\` with \`pairs:[{fromId, toId}]\` and \`relationship:"not_contradiction"\` using the ids above — the dismissal is persisted, so that pair never resurfaces here (and its cue never re-attaches as a recall/ask overlay)._\n\n${lines.join('\n')}`);
     } else if (mode === 'contradictions') {
       sections.push('✓ No contradiction candidates — no live card pair shows a correction cue or a polarity flip over the same subject.');
     }

package/src/klypix-format.mjs

@@ -1378,8 +1378,22 @@ export function detectContradictions(struct, { minOverlap = 0.45, topK = 12 } =
             if (!subjectHit) continue;
             let why = null, staleC = null, freshC = null;
             if (aCue !== bCue) {
-                why = 'correction-cue';                                  // one side explicitly corrects — it is the presumed truth
-                freshC = aCue ? a : b; staleC = aCue ? b : a;
+                const cueC = aCue ? a : b, otherC = aCue ? b : a;
+                // Recency: the cue side is the presumed truth ONLY for cards that
+                // existed when it was written. Against a STRICTLY NEWER card the
+                // presumption inverts — the newer card superseded the correction
+                // (field 2026-07-12: a 07-11 audit correction was flagged CURRENT
+                // over the 07-12 R1 cards that post-dated it).
+                const inverted = (cueC.createdAt || 0) && (otherC.createdAt || 0) && cueC.createdAt < otherC.createdAt;
+                why = inverted ? 'correction-cue (cue predates its counterpart — presumed superseded)' : 'correction-cue';
+                freshC = inverted ? otherC : cueC; staleC = inverted ? cueC : otherC;
+                // Skills are standing reference (corrected in place with ~, never
+                // retirable by ✓/supersede) — presenting one as "likely STALE"
+                // invites a retire the engine would refuse; skip the pair. Checked
+                // on the RESOLVED stale side, so it covers both directions — incl.
+                // an inverted pair whose cue card is itself a 🛠 skill (a skill
+                // documenting the CORRECTION convention carries the cue token).
+                if (/🛠/.test(staleC.text || '')) continue;
             } else if (!aCue && !linked.has(a.id + '|' + b.id)) {
                 const la = lower.get(a.id), lb = lower.get(b.id);
                 for (const { x, y, rx, ry } of POLARITY_RES) {
@@ -1598,7 +1612,13 @@ const cueMatch = (a, b, bar) => {
 //   • edge — an outgoing "superseded by"/"closed by" arrow (drawn by capture or
 //     a confirmed reconcile) whose successor still has text;
 //   • cue  — a LIVE correction-cue card that lexically overlaps it ≥ `at`, ANY
-//     area (the un-edged pair the capture-time supersede missed).
+//     area (the un-edged pair the capture-time supersede missed) — EXCEPT:
+//       - a cue STRICTLY OLDER than the card (recency guard — an old correction
+//         must never be served as the current truth for a card that post-dated
+//         it; field 2026-07-12: 17 of 32 live overlays pointed backward),
+//       - a 🛠 skill card as the overlay TARGET (standing reference, corrected
+//         in place with ~ — never labeled stale by a lexical match),
+//       - a pair dismissed with a not_contradiction edge (same human verdict).
 // The caller injects the corrector FIRST (labeled) and reduces the stale hit to
 // a headline — the stale text never stands alone. Pure + cheap: correction-cue
 // cards are rare and the hit list is ≤topK.
@@ -1608,8 +1628,14 @@ export function correctionOverlaysFor(struct, cards, { at = CORRECTION_SUPERSEDE
     const byId = new Map(struct.cards.map(c => [c.id, c]));
     const isArchived = (c) => /^archive$/i.test(c.area || '');
     const successorOf = new Map();
+    // A confirmed not_contradiction dismissal is the same human verdict for the
+    // overlay: that cue does not correct that card — the CUE path never
+    // re-attaches the pair (an explicit superseded-by edge still wins: both are
+    // deliberate verdicts and the edge is the stronger one).
+    const dismissed = new Set();
     for (const cn of struct.connections || []) {
         if (cn.label === 'superseded by' || cn.label === 'closed by') successorOf.set(cn.fromId, cn.toId);
+        if (cn.relationship === 'not_contradiction' || cn.label === 'not a contradiction') { dismissed.add(cn.fromId + '|' + cn.toId); dismissed.add(cn.toId + '|' + cn.fromId); }
     }
     const cues = struct.cards.filter(c => c.type !== 'container' && !isArchived(c) && (c.text || '').trim() && hasCorrectionCue(c.text));
     for (const card of cards) {
@@ -1617,10 +1643,20 @@ export function correctionOverlaysFor(struct, cards, { at = CORRECTION_SUPERSEDE
         const succ = successorOf.has(card.id) ? byId.get(successorOf.get(card.id)) : null;
         if (succ && (succ.text || '').trim()) { out.set(card.id, { kind: 'edge', by: succ }); continue; }
         if (hasCorrectionCue(card.text)) continue;   // the hit IS a correction — nothing to overlay
+        if (/🛠/.test(card.text || '')) continue;    // skills are standing reference, corrected in place with ~ — never labeled STALE by a lexical cue (mirror the supersede/resolve guards)
         const cTok = tokenSet(card.text);
         let best = null, bestS = 0;
         for (const cue of cues) {
             if (cue.id === card.id) continue;
+            if (dismissed.has(cue.id + '|' + card.id)) continue;
+            // Recency guard: a correction can only correct facts that existed when
+            // it was written — a cue STRICTLY older than the card must never be
+            // served as its "current truth" (field 2026-07-12: a 07-11 audit
+            // correction overlaid the 07-12 cards that superseded it, and a June
+            // "deploy did not stick" correction poisoned July version answers,
+            // steering synthesis BACKWARD). Equal/unknown stamps keep the overlay
+            // (same-batch captures share a timestamp; missing dates can't be judged).
+            if ((cue.createdAt || 0) && (card.createdAt || 0) && cue.createdAt < card.createdAt) continue;
             const s = cueMatch(cTok, stripCueMeta(tokenSet(cue.text)), at);
             if (s > bestS) { bestS = s; best = cue; }
         }