klypix-mcp 1.16.0 → 1.17.0

package/bin/klypix-mcp.mjs

@@ -137,13 +137,14 @@ server.registerTool('brain_connect', {
 }, async ({ canvas, apply, max, threshold }) => toContent(await opBrainConnect({ vault: VAULT, canvas, apply, max, threshold, log })));
 
 server.registerTool('brain_reconcile', {
-  title: 'Reconcile the brain against committed migrations (find unrecorded rollouts)',
-  description: 'External-state check the brain otherwise CANNOT do: a brain only knows facts someone narrated (a marker, a commit body), so a DB migration APPLIED to prod — which narrates nothing — silently never lands. This lists committed migration files (Supabase / Rails / Prisma / Knex / generic) under the project and flags any that NO brain card references, so you can confirm the rollout with one marker. It reads ONLY the filesystem — never the database, never the network — and never claims a migration was applied, only that it is unrecorded. Defaults to the migrations dir beside the project brain; pass root to point elsewhere. Run it when you want to be sure the brain reflects what actually shipped.',
+  title: 'Reconcile the brain — contradictions between cards + unrecorded migrations',
+  description: 'Truth maintenance in two passes. (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 ✓; a false POLARITY pair is dismissed by deliberately connecting the pair (brain_connect), while a correction-cue pair clears only when the stale card is retired. (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. 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)."),
+    mode: z.enum(['all', 'contradictions', 'migrations']).optional().describe('Which pass to run (default "all").'),
   },
-}, async ({ canvas, root }) => toContent(await opBrainReconcile({ vault: VAULT, canvas, root })));
+}, async ({ canvas, root, mode }) => toContent(await opBrainReconcile({ vault: VAULT, canvas, root, mode })));
 
 server.registerTool('brain_garden', {
   title: 'Garden the brain — consolidate over-grown areas (sleep-time compute)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.16.0",
+  "version": "1.17.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"
+    "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"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/src/agent-rules.mjs

@@ -54,6 +54,7 @@ Treat it as authoritative project context, and as **the place project knowledge
 survives across sessions, agents, and context resets.
 
 **At the start of a task — read it** so you know the project's state and past decisions:
+- if \`.claude/brain-brief.md\` exists, read it — it is the full session brief the brain hook regenerates at every session start (Focus, open questions, skills, recent decisions).
 - with the \`klypix-canvas\` MCP server: call \`search_canvases\` / \`read_canvas\` (canvas: \`"brain"\`), or \`brain_insights\` for the load-bearing cards.
 - or via CLI: \`npx klypix-read brain.klypix\`
 
@@ -64,7 +65,11 @@ survives across sessions, agents, and context resets.
 
 Capture **sparingly** — real decisions / milestones / open questions / reusable gotchas, not routine
 steps — and capture it **at the moment you decide** (a one-line marker inline), not batched or left in
-a scratch file to rot. Link related cards with \`[[other-card]]\`.
+a scratch file to rot. Link related cards with \`[[other-card]]\`. To **correct a stale card**, include
+the word \`CORRECTION\` (or "was WRONG" / "OBSOLETE" — UPPERCASE, the deliberate signal) in the
+decision — capture then supersedes the stale card across ALL areas (archived with an arrow + a
+receipt, restorable if wrong). Suspect stale facts survive somewhere? Run \`brain_reconcile\` — it
+surfaces contradiction candidates to confirm.
 
 **Memory routing (important).** If your host has its OWN memory/notes store, that is for *user*
 preferences and how to work with this person — keep using it for that. But **project** knowledge

package/src/global-brain-hook.mjs

@@ -303,6 +303,10 @@ function touchSession(sid, patch = {}) {
                 // ships ACCUMULATE across turns (deduped, last 5) so a peer sees the
                 // session's recent ship-events, not just the latest turn's.
                 ships: patch.ships !== undefined ? [...new Set([...(prev.ships || []), ...patch.ships])].slice(-5) : (prev.ships ?? []),
+                // Card ids already injected full-text into THIS session's prompts —
+                // the per-prompt recall renders a re-hit as one headline instead of
+                // re-paying the full card (a ~600-word card was injected 3× before).
+                injected: patch.injected !== undefined ? patch.injected : (prev.injected ?? []),
                 startedAt: prev.startedAt || now, lastSeen: now,
             });
             fs.mkdirSync(SESSIONS_DIR, { recursive: true });
@@ -348,7 +352,7 @@ function peerFooter(sid) {
         else if (p.branch && myBranch && p.branch === myBranch) warn = '  · ⚠️ same branch — pull/rebase before you commit';
         lines.push(`- session ${String(p.id).slice(0, 8)} · ${bits.join(' · ')}${warn}`);
     }
-    lines.push('Ping the other session before touching shared files; check the brain for what they decided/shipped.');
+    lines.push('Coordinate BEFORE touching shared files: reply with `🧠 MSG [<their id-prefix or branch>]: <text>` (or call the `brain_message` MCP tool) — delivered once at their next prompt. Check the brain for what they decided/shipped.');
     return lines.join('\n');
 }
 
@@ -972,7 +976,10 @@ async function capture(lib) {
             const key = sha(('ship|' + p.area + '|' + summary).toLowerCase());
             if (seen.has(key)) break;                         // already captured this ship
             seen.add(key);
-            cards.push({ text: `${p.area}: 🏁 ${summary}\n#${slugify(p.area)}`, area: p.area, borderColor: 'rgba(59,130,246,0.8)', createdVia: 'ship-event' });
+            // #auto marks machine-harvested provenance: the repeat-detector demands an
+            // entity-token match on these (they're dense with generic ship verbs) and
+            // the gardener consolidates them at a shorter age.
+            cards.push({ text: `${p.area}: 🏁 ${summary}\n#${slugify(p.area)} #auto`, area: p.area, borderColor: 'rgba(59,130,246,0.8)', createdVia: 'ship-event' });
             shipSummaries.push(summary);
             ledger.push({ action: 'ship-event', area: p.area, preview: summary });
             break;                                            // one pattern per command
@@ -1047,10 +1054,17 @@ async function capture(lib) {
     const bits = [`${stats.added} added`];
     if (stats.resolved) bits.push(`${stats.resolved} resolved`);
     if (stats.updated) bits.push(`${stats.updated} updated`);
+    if (stats.merged) bits.push(`${stats.merged} merged`);
     if (stats.closed) bits.push(`${stats.closed} closed`);
     if (stats.superseded) bits.push(`${stats.superseded} superseded`);
     if (stats.linked) bits.push(`${stats.linked} linked`);
     process.stderr.write(`[brain] capture: ${bits.join(' · ')} → brain.klypix\n`);
+    // Receipt for correction-driven (cross-area / low-bar) supersedes — the
+    // confirmation channel: say WHAT was archived and how to undo a wrong grab.
+    if (Array.isArray(stats.corrections) && stats.corrections.length) {
+        process.stderr.write(`[brain] correction supersede: ${stats.corrections.map(c => `"${c.old}" (${c.overlap})`).join('; ')} — archived + arrowed; restore from Archive or ~ update if wrong\n`);
+    }
+    if (stats.added > 0 && !stats.linked) process.stderr.write(`[brain] note: ${stats.added} card(s) landed unlinked — \`brain_connect\` (or [[wikilinks]] next time) wires them into the graph\n`);
     appendJsonl(LEDGER, { ts: nowIso(), mode: 'capture', stats, decisions: ledger }, 1000);
     appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'capture', ok: true, brainBytes: brainBytes(), added: stats.added, skipped: ledger.filter(d => d.action.startsWith('skipped')).length }, 500);
 }
@@ -1196,20 +1210,74 @@ async function promptRetrieve(lib) {
     const head = (c, n = 120) => { const t = flat(c.text); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
     const lines = [];
     if (repeats.length) {
+        // A nudged "already shipped" card may itself have been CORRECTED since —
+        // nudging the agent to reuse a stale fact would be worse than no nudge.
+        let repOverlays = new Map();
+        if (struct && typeof lib.correctionOverlaysFor === 'function') {
+            try { repOverlays = lib.correctionOverlaysFor(struct, repeats.map(r => r.card)); } catch { /* best-effort */ }
+        }
         lines.push('## ⚠️ Possible repeat — this may already be done (reuse/supersede, don’t silently redo)');
         for (const r of repeats) {
             const verb = r.kind === 'superseded'
                 ? `you moved OFF this ${day(r.card.createdAt)} — check what replaced it before redoing`
                 : `already ${r.kind} ${day(r.card.createdAt)} — reuse/build on it, or supersede it deliberately`;
-            lines.push(`- [${flat(r.card.area) || '?'}] ${head(r.card)}  · ${verb}`);
+            const ov = repOverlays.get(r.card.id);
+            const corr = ov ? `  · ⚠️ a live CORRECTION exists — read it first: “${head(ov.by, 90)}”` : '';
+            lines.push(`- [${flat(r.card.area) || '?'}] ${head(r.card)}  · ${verb}${corr}`);
         }
         lines.push('Read the matching card (klypix-canvas MCP / brain) BEFORE redoing. Other project? use search_all_brains.');
     }
     if (freshHits.length) {
+        // Truth-decay guard: for each hit with a supersede/close edge or an
+        // overlapping live correction-cue card, inject the CORRECTOR full-text
+        // FIRST and reduce the stale hit to a labeled headline — a stale card
+        // must never stand alone (the worst failure mode a memory can have).
+        let overlays = new Map();
+        if (struct && typeof lib.correctionOverlaysFor === 'function') {
+            try { overlays = lib.correctionOverlaysFor(struct, freshHits.map(h => h.card)); } catch { /* best-effort */ }
+        }
+        // Per-session injection dedup: a card already shown full-text this
+        // session renders as one headline, not another ~600 words of context.
+        let me = null; try { me = readSessions().find(s => s.id === sid) || null; } catch { /* */ }
+        const injected = new Set((me && Array.isArray(me.injected)) ? me.injected : []);
+        const shownNow = new Set();
         lines.push(semMode === 'sem-hit'
             ? "# Related prior decisions (semantic match — no exact keyword overlap; full brain via the klypix-canvas MCP)"
             : "# Relevant prior decisions from this project's brain (task-matched; full brain via the klypix-canvas MCP)");
-        for (const h of freshHits) lines.push(`- ${flat(h.card.text)}`);
+        const newlyInjected = [];
+        for (const h of freshHits) {
+            if (shownNow.has(h.card.id)) continue;                      // already rendered this turn (e.g. as a corrector)
+            const ov = overlays.get(h.card.id);
+            if (ov) {
+                // The STALE demotion is UNCONDITIONAL — even when the corrector
+                // already rendered (as its own hit, or for a twin), the stale
+                // card must never fall through to the plain full-text branch.
+                // The corrector prints full-text at most once per session.
+                let correctorLine = false;
+                if (!shownNow.has(ov.by.id)) {
+                    correctorLine = true;
+                    if (injected.has(ov.by.id)) {
+                        lines.push(`- ⚠️ CORRECTED — current (already shown this session): ${head(ov.by, 110)}`);
+                    } else {
+                        lines.push(`- ⚠️ CORRECTED — current: ${flat(ov.by.text)}`);
+                        newlyInjected.push(ov.by.id);
+                    }
+                    shownNow.add(ov.by.id);
+                }
+                lines.push(`${correctorLine ? '  ↳' : '-'} ⚠️ recall matched a STALE card${ov.kind === 'edge' ? ' (superseded)' : ''}: “${head(h.card, 110)}” — do NOT act on it${correctorLine ? '' : ' (its CORRECTION is listed above)'}. Reconcile: \`brain_reconcile\` (contradictions) or a ✓/~ marker.`);
+                shownNow.add(h.card.id);
+                continue;
+            }
+            if (injected.has(h.card.id)) {
+                lines.push(`- (already shown this session) ${head(h.card, 110)}`);
+                shownNow.add(h.card.id);
+                continue;
+            }
+            lines.push(`- ${flat(h.card.text)}`);
+            shownNow.add(h.card.id);
+            newlyInjected.push(h.card.id);
+        }
+        if (newlyInjected.length) touchSession(sid, { injected: [...new Set([...injected, ...newlyInjected])].slice(-100) });
     }
     const parts = [];
     if (lines.length) parts.push(lines.join('\n'));
@@ -1437,6 +1505,8 @@ function legendFooter() {
         + '🧠 **Capture markers** — write these in your reply; the Stop hook harvests them into the brain (no separate log step). Use sparingly, for real decisions / milestones / discoveries:\n'
         + '`🧠 BRAIN [Area]: decision` · `[Area] ?: open question` · `[Area] !: milestone` · `[Area] +: 🛠️ skill (reusable how-to / gotcha — resurfaces every session, never ages out)` · `[Area] ✓: resolves+archives the matching card` · `[Area] ~: updates it in place` · 🎯 in text = a goal (reads as open).\n'
         + 'Optional suffixes: `closes: <card title / [[wikilink]]>` (resolve the strategy/question this fulfils) · `ev: <file[:line]>, PR#<n>` (anchor to code → auto drift-badge).\n'
+        + '**Correcting a stale card:** include the word `CORRECTION` (or "was WRONG" / "OBSOLETE" — UPPERCASE; casing is the deliberate-signal, casual prose never fires it) in the decision — the capture then hunts the stale card across ALL areas at a lower match bar and supersedes it (archived + arrowed, with a receipt; restore from Archive if it grabbed the wrong one). A rephrased duplicate `?` merges into the existing open question instead of stacking a twin.\n'
+        + '**Session brief:** the SessionStart hook prints a ≤2KB ultra brief and writes the FULL brief to `.claude/brain-brief.md` — read that file when planning non-trivial work.\n'
         + '**Routing:** capture project decisions / milestones / open questions / gotchas HERE, *at the moment you decide* — this brain is the shared, portable memory that survives context resets and the next agent reads. A host memory store (if any) is for *user* preferences; never leave project state only in a private scratchpad.\n'
         + 'Coordinate with a concurrent session: `🧠 MSG [<their-id or all>]: <text>` — a one-time note (NOT a brain card) delivered to that session on its next prompt.\n';
 }
@@ -1447,18 +1517,55 @@ async function read(lib) {
     // immediately. Files/ships come from Stop (what this session actually edits).
     touchSession(input.session_id, { branch: gitBranch() });
     const { struct } = await lib.parseKlypix(fs.readFileSync(BRAIN));
-    // Default = TIERED brief (open questions + recent + area map) so the
-    // session-start cost stays flat as the brain grows. --full = everything.
     const { freshness, drifted } = computeFreshness(struct);
-    const outStr = (!process.argv.includes('--full') && typeof lib.structToBrief === 'function')
-        ? lib.structToBrief(struct, { freshness })
-        : lib.structToMarkdown(struct);
-    // ⚡ In-flight footer goes RIGHT AFTER the brief (highest signal: what a peer
-    // shipped seconds ago, before it's in the brain) — closes the 1.3.17-blindness gap.
-    process.stdout.write(outStr + inflightFooter(input.session_id, struct) + selfHealFooter(drifted) + reconcileFooter(lib, struct) + staleOpenFooter(lib, struct) + selfCheckFooter() + doctorFooter() + versionCurrencyFooter() + messageFooter(input.session_id || '', input.transcript_path) + legendFooter() + memoryFooter());
+    // The FULL brief: tiered brief + every self-heal/health footer. Messages are
+    // deliberately NOT part of it (messageFooter ACKS on read — it must only ever
+    // go to stdout, where the agent actually sees it, exactly once).
+    const full = ((typeof lib.structToBrief === 'function') ? lib.structToBrief(struct, { freshness }) : lib.structToMarkdown(struct))
+        + inflightFooter(input.session_id, struct) + selfHealFooter(drifted) + reconcileFooter(lib, struct) + staleOpenFooter(lib, struct)
+        + selfCheckFooter() + doctorFooter() + versionCurrencyFooter() + legendFooter() + memoryFooter();
+    const emitFull = () => {
+        process.stdout.write(full + messageFooter(input.session_id || '', input.transcript_path));
+        appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'read', ok: true, briefBytes: Buffer.byteLength(full), cards: struct?.counts?.cards ?? null }, 500);
+    };
+    // --full = everything to stdout (manual runs); also the fallback when the
+    // live klypix-format predates the ultra tier (version skew) or the brief
+    // file can't be written (stdout is then the only channel).
+    if (process.argv.includes('--full') || typeof lib.structToUltraBrief !== 'function') return emitFull();
+    // Default = ULTRA tier. The harness persists hook stdout and shows only a
+    // ~2KB preview, so a 13KB brief was mostly invisible — write the FULL brief
+    // to a stable project-local file and print a tier that fits the preview
+    // whole: Focus + conflicts + open questions + alerts + the file's path.
+    const briefRel = '.claude/brain-brief.md';
+    try {
+        fs.mkdirSync(path.resolve(CWD, '.claude'), { recursive: true });
+        fs.writeFileSync(path.resolve(CWD, briefRel),
+            '<!-- auto-generated by the brain hook at session start — read it, don\'t edit it; regenerated next session -->\n' + full, 'utf8');
+    } catch { return emitFull(); }
+    const ultra = lib.structToUltraBrief(struct, { freshness, briefPath: briefRel });
+    // Self-heal tiers compress to ONE line up here; the actionable detail (which
+    // cards, which markers to emit) lives in the brief file.
+    const heals = [];
+    if (drifted && drifted.length) heals.push(`${drifted.length} code-anchored fact(s) DRIFTED`);
+    try {
+        if (typeof lib.findUnrecordedMigrations === 'function') {
+            const files = collectMigrationFiles(CWD);
+            if (files.length) { const { total } = lib.findUnrecordedMigrations(struct, files, { max: 6 }); if (total) heals.push(`${total} unrecorded migration(s)`); }
+        }
+    } catch { /* */ }
+    try { if (typeof lib.findStaleOpenCards === 'function') { const { total } = lib.findStaleOpenCards(struct, { max: 5 }); if (total) heals.push(`${total} open card(s) look already done`); } } catch { /* */ }
+    const healLine = heals.length ? `\n🔧 Self-heal: ${heals.join(' · ')} — detail + fix markers in ${briefRel}.` : '';
+    // 📨 messages are delivered-ONCE (acked the moment this reads them) — they
+    // go right after the ultra brief, at the top of the visible window, never
+    // after a stack of footers that could push them past a preview cut.
+    const messages = messageFooter(input.session_id || '', input.transcript_path);
+    const out = ultra + messages + healLine
+        + inflightFooter(input.session_id, struct)
+        + selfCheckFooter() + doctorFooter() + versionCurrencyFooter();
+    process.stdout.write(out);
     // Heartbeat: prove the brief actually injected (and how big) so a dead or
     // stale live-copy of the hook stops being a silent no-op.
-    appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'read', ok: true, briefBytes: Buffer.byteLength(outStr), cards: struct?.counts?.cards ?? null }, 500);
+    appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'read', ok: true, briefBytes: Buffer.byteLength(out), fullBriefBytes: Buffer.byteLength(full), cards: struct?.counts?.cards ?? null }, 500);
 }
 
 // Registry of every brain this machine has touched — written on each hook run,

package/src/klypix-core.mjs

@@ -25,7 +25,7 @@ import {
   parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown,
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
   findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
-  selectGardenCandidates, applyGarden,
+  selectGardenCandidates, applyGarden, detectContradictions,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -405,7 +405,7 @@ export function collectMigrationFiles(root) {
   }
   return out;
 }
-export async function opBrainReconcile({ vault, canvas, root }) {
+export async function opBrainReconcile({ vault, canvas, root, mode = 'all' }) {
   const t = brainTarget(vault, canvas);
   if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
   if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
@@ -413,16 +413,49 @@ export async function opBrainReconcile({ vault, canvas, root }) {
   let struct;
   try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
   const stamp = brainStamp(file, struct, t.how);
+  const sections = [];
+
+  // (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).
+  if (mode === 'all' || mode === 'contradictions') {
+    const pairs = detectContradictions(struct);
+    if (pairs.length) {
+      const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+      const lines = pairs.map((p, i) =>
+        `${i + 1}. ${p.why} · overlap ${p.overlap}\n`
+        + `   · likely STALE   [${p.stale.area || '?'}] ${flat(p.stale.text).slice(0, 180)}\n`
+        + `   · likely CURRENT [${p.fresh.area || '?'}] ${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: a **polarity** pair is dismissed by deliberately connecting the two cards (\`brain_connect\`); a **correction-cue** pair only clears when the stale card is retired (✓ / supersede) — a mere link does not settle a declared correction._\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.');
+    }
+  }
+
+  // (2) MIGRATIONS — the brain reconciled against committed external state.
   // Migrations live in the CODE repo (usually beside brain.klypix), not in a
   // separate canvas vault — so default the root to the brain file's folder.
-  const repoRoot = root ? path.resolve(root) : path.dirname(file);
-  const files = collectMigrationFiles(repoRoot);
-  if (!files.length) return { blocks: [text(stamp + `No migration files under ${repoRoot} (looked in: ${MIGRATION_DIRS.join(', ')}). Nothing to reconcile.`)] };
-  const { gaps, total } = findUnrecordedMigrations(struct, files, { max: 20 });
-  if (!gaps.length) return { blocks: [text(stamp + `✓ All ${files.length} migration(s) under ${path.basename(repoRoot)} are referenced by a brain card — no unrecorded rollouts.`)] };
-  const lines = gaps.map(g => `- \`${g.path}\` — committed, but no brain card mentions it. If applied to prod, record it:\n    \`🧠 BRAIN [DB] !: migration ${g.file.replace(/\.sql$/i, '')} applied to prod ev: ${g.path}\``);
-  const more = total > gaps.length ? `\n\n…and ${total - gaps.length} more.` : '';
-  return { blocks: [text(stamp + `# ⚠️ ${total} migration(s) committed but unrecorded in the brain\n_The brain can't see prod — it flags migrations that are in git but unmentioned, so you can confirm the rollout. It never asserts a migration was applied. To dismiss one without applying, record any card that names it (e.g. "committed, not applied")._\n\n${lines.join('\n')}${more}`)] };
+  if (mode === 'all' || mode === 'migrations') {
+    const repoRoot = root ? path.resolve(root) : path.dirname(file);
+    const files = collectMigrationFiles(repoRoot);
+    if (!files.length) {
+      if (mode === 'migrations') sections.push(`No migration files under ${repoRoot} (looked in: ${MIGRATION_DIRS.join(', ')}). Nothing to reconcile.`);
+    } else {
+      const { gaps, total } = findUnrecordedMigrations(struct, files, { max: 20 });
+      if (!gaps.length) sections.push(`✓ All ${files.length} migration(s) under ${path.basename(repoRoot)} are referenced by a brain card — no unrecorded rollouts.`);
+      else {
+        const lines = gaps.map(g => `- \`${g.path}\` — committed, but no brain card mentions it. If applied to prod, record it:\n    \`🧠 BRAIN [DB] !: migration ${g.file.replace(/\.sql$/i, '')} applied to prod ev: ${g.path}\``);
+        const more = total > gaps.length ? `\n\n…and ${total - gaps.length} more.` : '';
+        sections.push(`# ⚠️ ${total} migration(s) committed but unrecorded in the brain\n_The brain can't see prod — it flags migrations that are in git but unmentioned, so you can confirm the rollout. It never asserts a migration was applied. To dismiss one without applying, record any card that names it (e.g. "committed, not applied")._\n\n${lines.join('\n')}${more}`);
+      }
+    }
+  }
+
+  if (!sections.length) sections.push('✓ Nothing to reconcile — no contradiction candidates, and no unrecorded migrations.');
+  return { blocks: [text(stamp + sections.join('\n\n---\n\n'))] };
 }
 
 // ── Brain gardener (two-phase: select → agent synthesizes → apply) ───────────
@@ -584,10 +617,16 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
     await atomicWrite(file, out);
     const s = res.stats || {};
     const bits = [`${s.added || 0} added`];
-    for (const k of ['resolved', 'updated', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);
+    for (const k of ['resolved', 'updated', 'merged', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);
+    // Correction receipt — a correction-cue note superseded a card cross-area /
+    // below the plain 0.6 bar; say WHAT was archived and how to undo, so the
+    // widened match is always confirmable rather than silent.
+    const corr = (Array.isArray(s.corrections) && s.corrections.length)
+      ? `\n↩︎ correction supersede: ${s.corrections.map(c => `"${c.old}"${c.area ? ` [${c.area}]` : ''} (overlap ${c.overlap})`).join('; ')} — archived + arrowed to your note. If it grabbed the wrong card, restore it from Archive or re-run with marker "~".`
+      : '';
     // Name the resolved brain explicitly (basename + how) so a write never lands
     // in a surprise file silently — the write-side twin of the read-op stamp.
-    return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in the KLYPIX app to see it.`)] };
+    return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in the KLYPIX app to see it.${corr}`)] };
   } catch (e) {
     return err(`brain_note failed (brain unchanged): ${e.message}`);
   }

package/src/klypix-format.mjs

@@ -681,6 +681,73 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     if (unshown > 0) hidden.push(`${unshown} older/over-budget decision${unshown === 1 ? '' : 's'}`);
     if (archivedCount > 0) hidden.push(`${archivedCount} archived/superseded`);
     if (hidden.length) push('', `*${hidden.join(' + ')} not shown — search the full brain via the klypix-canvas MCP (search/read tools) or \`node ~/.claude/project-brain/global-brain-hook.mjs --full\`.*`);
+    // Graph health, ambient: when a third of the live brain is unlinked, say so
+    // once (brain_insights has the detail; auto-linking at capture works the
+    // backlog down going forward).
+    const degIds = new Set();
+    for (const cn of struct.connections || []) { if (cn.fromId) degIds.add(cn.fromId); if (cn.toId) degIds.add(cn.toId); }
+    const orphanN = live.filter(c => !degIds.has(c.id)).length;
+    if (live.length >= 10 && orphanN / live.length > 0.3) push('', `*graph: ${orphanN}/${live.length} live cards have no connections — \`brain_connect\` (or capturing with [[wikilinks]]) densifies the graph.*`);
+    return out.join('\n') + '\n';
+}
+
+// ── Ultra brief (SessionStart stdout tier) ───────────────────────────────────
+// The harness persists hook stdout to a file and shows the agent only a ~2KB
+// PREVIEW — a 13.5KB brief was mostly invisible (everything after Focus/open
+// questions reached the agent only if it chose to open the file; it usually
+// didn't). This tier is sized to fit that preview WHOLE: Focus + conflicts +
+// open questions + a pointer to the FULL brief file the hook writes alongside.
+// The pointer + marker legend are reserved OUT of the budget so they always fit.
+export const ULTRA_BUDGET_CHARS = 1_800;   // sibling of BUDGET_CHARS above — sized for the harness preview, not token cost
+export function structToUltraBrief(struct, { freshness = null, briefPath = '.claude/brain-brief.md', budgetChars = ULTRA_BUDGET_CHARS } = {}) {
+    const texts = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim());
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const isFocus = (c) => /(^|\s)focus\b/i.test(c.area || '');
+    const live = texts.filter(c => !isArchived(c));
+    const focus = live.filter(isFocus);
+    const open = live.filter(c => /❓|🎯/.test(c.text) && !/🛠/.test(c.text) && !isFocus(c));
+    const skills = live.filter(c => /🛠/.test(c.text) && !isFocus(c));
+    const conflicts = (struct.connections || []).filter(c => c.relationship === 'conflicts_with');
+    const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    const fr = (c) => (freshness && freshness[c.id]) ? freshness[c.id] + ' ' : '';
+    const safeCut = (t, n) => { let s = t.slice(0, n); if (/[\uD800-\uDBFF]$/.test(s)) s = s.slice(0, -1); return s.trimEnd() + '…'; };
+    const head = (c, max = 150) => { const t = flat(c.text); return t.length > max ? safeCut(t, max - 1) : t; };
+    const out = [];
+    let used = 0;
+    const push = (...ls) => { for (const l of ls) { out.push(l); used += l.length + 1; } };
+    // Length-aware guard: a line only lands if it FITS — one long focus card
+    // must not blow the tier past the preview it exists to fit inside.
+    const pushIf = (l) => { if (used + l.length + 1 > budget) return false; out.push(l); used += l.length + 1; return true; };
+    const tail = [
+        '',
+        `📖 **Full brief: \`${briefPath}\`** — skills (${skills.length}), milestones, recent decisions, connections, self-heal detail. READ IT before planning non-trivial work.`,
+        '🧠 Capture: `🧠 BRAIN [Area]: <decision>` · `?` question · `!` milestone · `+` skill · `✓` resolve · `~` update · a "CORRECTION: …" decision supersedes its stale card across areas · suffixes `closes:` / `ev:` (full legend in the brief file).',
+    ];
+    const budget = Math.max(400, budgetChars - tail.reduce((s, l) => s + l.length + 1, 0));
+    push(`# ${struct.title} — brain (ultra brief)`);
+    push(`*${struct.counts.cards} cards · ${struct.counts.connections} connections — this is the preview tier; the full brief is one Read away (below)*`);
+    // clip = surrogate-safe truncation for arbitrary strings (head() covers cards).
+    const clip = (s, n) => { const t = flat(s); return t.length > n ? safeCut(t, n - 1) : t; };
+    if (focus.length && pushIf('') && pushIf('## 📌 Human focus (act on these first)')) {
+        let shown = 0;
+        for (const c of focus) { if (!pushIf(`- ${fr(c)}${head(c, 400)}`)) break; shown++; }
+        // Never present a truncated "act on these first" list as complete.
+        if (shown < focus.length) push(`- ⚠️ …and ${focus.length - shown} MORE focus card(s) — read the full brief before acting.`);
+    }
+    if (conflicts.length && pushIf('') && pushIf('## ⚠️ Conflicts to reconcile')) {
+        let shown = 0;
+        for (const c of conflicts.slice(0, 4)) { if (!pushIf(`- ${clip(c.from, 70)} ⚔️ ${clip(c.to, 70)}`)) break; shown++; }
+        if (shown < conflicts.length) pushIf(`- …and ${conflicts.length - shown} more conflict(s) — in the full brief.`);
+    }
+    if (open.length && pushIf('') && pushIf(`## Open questions & goals (${open.length})`)) {
+        let shown = 0;
+        for (const c of open) { if (!pushIf(`- ${fr(c)}${head(c)}`)) break; shown++; }
+        if (shown < open.length) pushIf(`- …and ${open.length - shown} more — in the full brief.`);
+    }
+    const areas = struct.cards.filter(c => c.type === 'container' && !/^archive$/i.test(c.title || ''))
+        .map(c => `${flat(c.title)} (${texts.filter(t => t.parentId === c.id).length})`);
+    if (areas.length) { pushIf(''); pushIf(clip('Areas: ' + areas.join(' · '), 240)); }
+    push(...tail);
     return out.join('\n') + '\n';
 }
 
@@ -712,11 +779,20 @@ export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2,
         const titleW = wordsOf(c.title);
         const bodyW = wordsOf(c.text);
         const tagStems = new Set((c.tags || []).map(t => String(t).toLowerCase().replace(/^#/, '').replace(/^(file|dir)-/, '')).filter(Boolean));
+        // Log-length normalization: a flat 1pt/word-hit made LONG cards outrank
+        // short ones purely by having more vocabulary to hit (one ~600-word card
+        // was re-injected into 3 prompts on those cheap hits). Body hits are
+        // scaled by log2 of the body's distinct-word count — ≤64 words is EXACTLY
+        // unpenalized (log2(64)=6), a 600-word card scores ~0.65/hit, so a
+        // body-only match on a big card needs 5 distinct hits to clear the recall
+        // minScore of 3 — by design. Title/tag hits (the precise signals) are
+        // untouched.
+        const lenNorm = Math.min(1, 6 / Math.max(6, Math.log2(bodyW.size || 1)));
         let score = 0;
         for (const tok of tokens) {
             if (titleW.has(tok)) score += 3;
             else if (tagStems.has(tok)) score += 3;
-            else if (bodyW.has(tok)) score += 1;
+            else if (bodyW.has(tok)) score += lenNorm;
         }
         if (score <= 0) continue;
         if ((c.createdAt || 0) >= cutoff) score += 0.5; // gentle recency tiebreak, never dominant
@@ -785,6 +861,23 @@ export function findUnrecordedMigrations(struct, files, { max = 6 } = {}) {
 // recall list still shows below). Returns each card's `kind` so the caller can
 // say "reuse it" (shipped/resolved) vs "see what replaced it" (superseded).
 // Pure + node-runnable; reuses the one shared tokenizer — no divergent scorer.
+// Generic work-verbs establish that a prompt is WORK, not WHICH work — two of
+// them shared with a 🏁 ship-card title used to clear the floor ("deploy it"
+// flagged two unrelated PR-merge cards; zero true positives all session).
+// Excluded from repeat scoring entirely; the loose recall list still sees them.
+const REPEAT_VERB_STOP = new Set([
+    'deploy', 'deployed', 'deploying', 'deploys', 'ship', 'shipped', 'shipping', 'ships',
+    'merge', 'merged', 'merges', 'merging', 'release', 'released', 'releases', 'releasing',
+    'publish', 'published', 'publishes', 'publishing', 'push', 'pushed', 'land', 'landed',
+    'build', 'builds', 'building', 'built', 'check', 'checked', 'checking', 'checks',
+    'plan', 'planned', 'planning', 'plans', 'best', 'class', 'cut', 'hand', 'handoff',
+    'report', 'reports', 'live', 'latest', 'done', 'complete', 'completed', 'finish', 'finished',
+    'work', 'task', 'feature',
+]);
+// Entity-shaped token — the kind that pins WHICH work: carries a digit (version,
+// PR#), or a kebab/snake identifier. A #file-/#dir- tag-stem match counts as an
+// entity at match time regardless of shape (tags are capture-stamped anchors).
+const isEntityToken = (t) => /\d/.test(t) || t.includes('-') || t.includes('_');
 export function detectRepeatWork(struct, query, { topK = 2, minScore = 5, minTokens = 2 } = {}) {
     const tokens = Array.isArray(query) ? query.filter(Boolean) : queryTokens(query);
     if (tokens.length < minTokens || !struct || !Array.isArray(struct.cards)) return [];
@@ -802,13 +895,19 @@ export function detectRepeatWork(struct, query, { topK = 2, minScore = 5, minTok
         const titleW = wordsOf(firstMeaningful || c.title);
         const bodyW = wordsOf(c.text);
         const tagStems = new Set((c.tags || []).map(t => String(t).toLowerCase().replace(/^#/, '').replace(/^(file|dir)-/, '')).filter(Boolean));
-        let score = 0, matched = 0;
+        // Auto-harvested ship cards (#auto, one-line merge/release events) are
+        // dense with exactly the verbs above — they additionally need ≥1 ENTITY
+        // token matched before a nudge is worth showing.
+        const isAuto = (c.tags || []).some(t => String(t).toLowerCase().replace(/^#/, '') === 'auto');
+        let score = 0, matched = 0, entities = 0;
         for (const tok of tokens) {
-            if (titleW.has(tok)) { score += 3; matched++; }
-            else if (tagStems.has(tok)) { score += 3; matched++; }
-            else if (bodyW.has(tok)) { score += 1; matched++; }
+            if (REPEAT_VERB_STOP.has(tok)) continue;  // "that it's work" ≠ "which work"
+            if (titleW.has(tok)) { score += 3; matched++; if (isEntityToken(tok)) entities++; }
+            else if (tagStems.has(tok)) { score += 3; matched++; entities++; }
+            else if (bodyW.has(tok)) { score += 1; matched++; if (isEntityToken(tok)) entities++; }
         }
         if (matched < minTokens || score < minScore) continue;   // precision-first floor
+        if (isAuto && entities < 1) continue;                    // auto cards: entity anchor required
         out.push({ card: c, score, kind });
     }
     out.sort((a, b) => b.score - a.score || (rank[b.kind] - rank[a.kind]) || (b.card.createdAt || 0) - (a.card.createdAt || 0));
@@ -855,6 +954,84 @@ export function detectConflicts(struct, { minOverlap = 0.45, topK = 12 } = {}) {
     return out.slice(0, topK);
 }
 
+// ── Contradiction candidates (reconcile-proper) ──────────────────────────────
+// The retroactive cleaner for stale/correction pairs that slipped past capture
+// (cross-area + reworded → no supersede possible by construction). Unlike
+// detectConflicts (a pre-filter for an LLM verifier), this is precision-scoped
+// enough to surface DIRECTLY for human/agent confirmation: same-subject live
+// pairs where (a) exactly ONE side carries an explicit correction cue
+// (CORRECTION / OBSOLETE / was WRONG / stale note resolved) — that side is the
+// presumed truth — or (b) the two sides use OPPOSITE polarity words about the
+// same subject (deferred↔wired, broken↔fixed, dead↔live …). Pairs already
+// settled by a supersede/close/conflict arrow are excluded; a plain relates_to
+// arrow is NOT a settlement. Suggestion-only — never writes. Pure, node-runnable.
+const POLARITY_PAIRS = [
+    ['deferred', 'wired'], ['deferred', 'shipped'], ['deferred', 'live'], ['deferred', 'enabled'],
+    ['broken', 'fixed'], ['broken', 'working'], ['dead', 'live'], ['dead', 'alive'],
+    ['disabled', 'enabled'], ['blocked', 'unblocked'], ['wrong', 'correct'], ['removed', 'restored'],
+];
+// WORD-boundary matchers, precompiled — substring includes() made 'deadline'
+// carry the 'dead' pole and 'delivery' carry 'live', and blocked↔unblocked
+// could never fire ('unblocked' contains 'blocked').
+const POLARITY_RES = POLARITY_PAIRS.map(([x, y]) => ({ x, y, rx: new RegExp(`\\b${x}\\b`), ry: new RegExp(`\\b${y}\\b`) }));
+export function detectContradictions(struct, { minOverlap = 0.45, topK = 12 } = {}) {
+    if (!struct || !Array.isArray(struct.cards)) return [];
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !isArchived(c));
+    // Cue meta words stripped up front — same-subject matching must compare the
+    // SUBJECT, not the vocabulary of the correction act (see stripCueMeta above).
+    const wset = new Map(live.map(c => [c.id, stripCueMeta(new Set(queryTokens(c.text)))]));
+    const lower = new Map(live.map(c => [c.id, String(c.text).toLowerCase()]));
+    // settled — fully reconciled (supersede/close/conflict arrow): excludes the
+    //   pair regardless of kind.
+    // linked — ANY deliberate edge (label !== 'auto'): dismisses a POLARITY pair
+    //   ("I looked, they relate, not a contradiction"), but never a cue pair —
+    //   a correction that [[wikilinks]] its stale card must still surface until
+    //   the stale card is actually retired. Auto-drawn edges dismiss nothing.
+    const settled = new Set(), linked = new Set();
+    for (const e of struct.connections || []) {
+        const k1 = e.fromId + '|' + e.toId, k2 = e.toId + '|' + e.fromId;
+        if (e.label === 'superseded by' || e.label === 'closed by' || e.relationship === 'conflicts_with') { settled.add(k1); settled.add(k2); }
+        if (e.label !== 'auto') { linked.add(k1); linked.add(k2); }
+    }
+    const out = [];
+    for (let i = 0; i < live.length; i++) {
+        for (let j = i + 1; j < live.length; j++) {
+            const a = live[i], b = live[j];
+            if (settled.has(a.id + '|' + b.id)) continue;
+            const A = wset.get(a.id), B = wset.get(b.id);
+            if (A.size < 4 || B.size < 4) continue;
+            let inter = 0; for (const t of A) if (B.has(t)) inter++;
+            const overlap = inter / Math.min(A.size, B.size);           // same subject?
+            const aCue = hasCorrectionCue(a.text), bCue = hasCorrectionCue(b.text);
+            // Cue-asymmetric pairs may also match on absolute subject mass (long
+            // cards — see cueMatch above); cue-less pairs keep the strict ratio.
+            const subjectHit = overlap >= minOverlap
+                || (aCue !== bCue && inter >= CUE_STRONG_SHARED && overlap >= CUE_RELAXED_COEF);
+            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;
+            } 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) {
+                    // each side must carry ONE pole only (word-level) — a card
+                    // narrating "from deferred to wired" holds both and
+                    // contradicts neither.
+                    if ((rx.test(la) && !ry.test(la) && ry.test(lb) && !rx.test(lb))
+                        || (ry.test(la) && !rx.test(la) && rx.test(lb) && !ry.test(lb))) { why = `polarity: ${x} ↔ ${y}`; break; }
+                }
+                if (why) [staleC, freshC] = (a.createdAt || 0) <= (b.createdAt || 0) ? [a, b] : [b, a];  // later card = presumed truth
+            }
+            if (!why) continue;
+            out.push({ stale: staleC, fresh: freshC, why, overlap: Math.round(overlap * 100) / 100, cue: aCue || bCue });
+        }
+    }
+    out.sort((x, y) => (Number(y.cue) - Number(x.cue)) || (y.overlap - x.overlap));
+    return out.slice(0, topK);
+}
+
 // ── Brain insights ───────────────────────────────────────────────────────────
 // "What matters here, and what am I forgetting?" — a deterministic structural
 // read of the brain (borrowed from graphify's GRAPH_REPORT, applied to the
@@ -948,9 +1125,12 @@ export function proposeStructuralConnections(struct, { maxPerCard = 2 } = {}) {
     const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !/^archive$/i.test(c.area || ''));
     const linked = new Set(struct.connections.map(c => [c.fromId, c.toId].sort().join('|')));
     const titleIx = live.filter(c => (c.title || '').trim()).map(c => ({ id: c.id, t: c.title.trim().toLowerCase() }));
+    // 'auto' is PROVENANCE, not topic — as a shared tag it would link every
+    // harvested ship card to every other one (junk edges that then push their
+    // degree past the garden's dormancy guard).
     const tagsOf = (c) => (c.tags || [])
         .map(t => String(t).toLowerCase().replace(/^#/, ''))
-        .filter(t => t && t !== 'area' && t !== String(c.area || '').toLowerCase());
+        .filter(t => t && t !== 'area' && t !== 'auto' && t !== String(c.area || '').toLowerCase());
     const cand = [];
     for (const c of live) {
         for (const link of (c.links || [])) {
@@ -1005,6 +1185,83 @@ const overlapScore = (a, b) => {
 // failed to fire.)
 const coverageOf = (target, hay) => { if (!target.size) return 0; let h = 0; for (const w of target) if (hay.has(w)) h++; return h / target.size; };
 
+// ── Truth decay (P1) — corrections must never lose to the cards they correct ─
+// A correction-cue note explicitly declares an older fact stale ("CORRECTION:",
+// "was WRONG", "OBSOLETE", "stale note resolved"). The same-area ≥0.6 supersede
+// can miss it BY CONSTRUCTION (the correction often lands in a different area,
+// reworded) — the stale card then stays live and recall serves it alone. Shared
+// by: the capture-side widened supersede, the recall-side overlay below, and
+// detectContradictions.
+// DELIBERATE cue only: the uppercase forms are the documented convention, and
+// case-sensitivity is what keeps casual prose ("the floor calc was wrong",
+// "remove obsolete helper", "color-correction") from firing a cross-area
+// supersede on an innocent card. "stale note resolved" is the one
+// natural-language phrase, accepted in any case (it is never incidental).
+export const CORRECTION_RE = /\bCORRECTIONS?\b|\bOBSOLETE\b|\bwas WRONG\b/;
+const CORRECTION_PHRASE_RE = /\bstale note (?:is )?resolved\b/i;
+export const hasCorrectionCue = (t) => CORRECTION_RE.test(String(t || '')) || CORRECTION_PHRASE_RE.test(String(t || ''));
+export const CORRECTION_SUPERSEDE_AT = 0.4;   // widened cross-area bar (vs same-area SUPERSEDE_AT 0.6)
+// Cue META words describe the act of correcting, not the subject — left in, they
+// dilute the overlap denominator and push real correction pairs just under the
+// bar (the field fixture lands at 0.375 with them, 0.5 without). Stripped before
+// every correction-overlap comparison.
+const CORRECTION_META = new Set(['correction', 'corrections', 'obsolete', 'stale', 'note', 'notes', 'resolved', 'wrong']);
+const stripCueMeta = (set) => { const out = new Set(); for (const w of set) if (!CORRECTION_META.has(w)) out.add(w); return out; };
+// Long-card reality: a correction's SUBJECT is a fraction of each card — the
+// overlap COEFFICIENT alone punishes long↔long pairs (the real field pair
+// measures 0.33 with 17 shared subject tokens, under every per-ratio bar). A
+// cue-gated match therefore also fires on ABSOLUTE subject mass: ≥10 shared
+// meaningful tokens at ≥0.25 coefficient. Cue-gated ONLY — plain supersede and
+// polarity pairs keep their strict ratio bars (no cue prior to lean on).
+const CUE_STRONG_SHARED = 10, CUE_RELAXED_COEF = 0.25;
+// Floor 3 (not overlapScore's 4): after stripCueMeta a terse deliberate
+// correction ("CORRECTION: the vault default was WRONG — use cwd") keeps only
+// 3-ish subject tokens; at 4 it silently no-oped. ≤2-token corrections still
+// no-op (too little signal to archive on) — they land as a new card; use ~ to
+// edit a card in place instead.
+const cueMatch = (a, b, bar) => {
+    if (a.size < 3 || b.size < 3) return 0;
+    let inter = 0; for (const w of a) if (b.has(w)) inter++;
+    const coef = inter / Math.min(a.size, b.size);
+    return (coef >= bar || (inter >= CUE_STRONG_SHARED && coef >= CUE_RELAXED_COEF)) ? coef : 0;
+};
+
+// Recall-side guard: given the cards recall is about to inject, return for each
+// one the card that CORRECTS it, found two ways:
+//   • 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).
+// 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.
+export function correctionOverlaysFor(struct, cards, { at = CORRECTION_SUPERSEDE_AT } = {}) {
+    const out = new Map();
+    if (!struct || !Array.isArray(struct.cards) || !Array.isArray(cards) || !cards.length) return out;
+    const byId = new Map(struct.cards.map(c => [c.id, c]));
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const successorOf = new Map();
+    for (const cn of struct.connections || []) {
+        if (cn.label === 'superseded by' || cn.label === 'closed by') successorOf.set(cn.fromId, cn.toId);
+    }
+    const cues = struct.cards.filter(c => c.type !== 'container' && !isArchived(c) && (c.text || '').trim() && hasCorrectionCue(c.text));
+    for (const card of cards) {
+        if (!card || !card.id) continue;
+        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
+        const cTok = tokenSet(card.text);
+        let best = null, bestS = 0;
+        for (const cue of cues) {
+            if (cue.id === card.id) continue;
+            const s = cueMatch(cTok, stripCueMeta(tokenSet(cue.text)), at);
+            if (s > bestS) { bestS = s; best = cue; }
+        }
+        if (best && bestS > 0) out.set(card.id, { kind: 'cue', by: best, overlap: Math.round(bestS * 100) / 100 });
+    }
+    return out;
+}
+
 // ── Auto-skill classifier (skills emerge from the flow, not just the '+' marker) ─
 // A REUSABLE skill (how-to / gotcha / convention) reads as a GENERAL RULE that
 // applies next time — distinct from a one-time decision ("we shipped X"). This is
@@ -1024,9 +1281,12 @@ export function looksLikeSkill(text) {
 }
 
 export async function captureIntoBrain(buffer, { cards = [], resolutions = [], updates = [] } = {}) {
-    const SUPERSEDE_AT = 0.6, RESOLVE_AT = 0.3, UPDATE_AT = 0.45, CLOSE_COVER_AT = 0.6;
+    const SUPERSEDE_AT = 0.6, RESOLVE_AT = 0.3, UPDATE_AT = 0.45, CLOSE_COVER_AT = 0.6, QUESTION_MERGE_AT = 0.6;
     let work = buffer;
-    const stats = { added: 0, superseded: 0, resolved: 0, linked: 0, updated: 0, closed: 0 };
+    // corrections[] lists cross-area/low-bar supersedes driven by a correction
+    // cue, so the surface (brain_note result / capture stderr) can say WHAT was
+    // archived and how to undo — the confirmation channel for the widened match.
+    const stats = { added: 0, superseded: 0, resolved: 0, linked: 0, updated: 0, closed: 0, merged: 0, corrections: [] };
 
     // Pass 1 — resolutions + supersede marking operate on EXISTING cards.
     if (resolutions.length || cards.length || updates.length) {
@@ -1093,24 +1353,36 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
         };
         canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
 
-        // RESOLVE (✓ markers) — best live match in the area; ❓ cards preferred.
+        // RESOLVE (✓ markers) — best live match in the area, PLUS its near-tie
+        // twins: a rephrased duplicate ❓ scores within a hair of its sibling, and
+        // resolving only the first left the twin open forever (it kept surfacing
+        // in every brief as still-to-do). Precision-kept: the set is the best
+        // match ± 0.1, never everything above the loose 0.3 floor. ❓ preferred.
         const milestonesFallback = [];
         for (const r of resolutions) {
             const rTok = tokenSet(r.text);
-            let best = null, bestScore = 0;
+            const cands = [];
             for (const c of liveTextCards()) {
                 if (r.area && (c.area || '').toLowerCase() !== r.area.toLowerCase()) continue;
+                if (/🛠/.test(c.text)) continue; // skills are standing reference — a ✓ must never archive one (mirror the supersede guard)
                 const s = overlapScore(rTok, tokenSet(c.text)) + (/❓|🎯/.test(c.text) ? 0.15 : 0);
-                if (s > bestScore) { bestScore = s; best = c; }
+                if (s > 0) cands.push({ c, s });
             }
-            if (best && bestScore >= RESOLVE_AT) {
-                await rewriteCard(best.id, j => {
-                    j.content = `${j.content}\n✅ ${today}: ${r.text}`;
-                    j.borderColor = 'rgba(16,185,129,0.35)';
-                });
-                await archiveCard(best.id);
-                best.text += ` ✅ ${r.text}`; // keep in-memory struct honest for later matching
-                stats.resolved++;
+            cands.sort((a, b) => b.s - a.s);
+            const bestScore = cands.length ? cands[0].s : 0;
+            const set = bestScore >= RESOLVE_AT
+                ? cands.filter(x => x.s >= Math.max(RESOLVE_AT, bestScore - 0.1)).slice(0, 3)
+                : [];
+            if (set.length) {
+                for (const { c: best } of set) {
+                    await rewriteCard(best.id, j => {
+                        j.content = `${j.content}\n✅ ${today}: ${r.text}`;
+                        j.borderColor = 'rgba(16,185,129,0.35)';
+                    });
+                    await archiveCard(best.id);
+                    best.text += ` ✅ ${r.text}`; // keep in-memory struct honest for later matching
+                    stats.resolved++;
+                }
             } else {
                 milestonesFallback.push({ text: (r.area ? `${r.area}: ` : '') + `🏁 ${r.text}`, area: r.area, borderColor: 'rgba(59,130,246,0.8)' });
             }
@@ -1146,6 +1418,34 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             }
         }
 
+        // MERGE-ON-CAPTURE for duplicate open questions — a rephrased ❓ that
+        // heavily overlaps an EXISTING live ❓ updates that card in place (fresh
+        // wording + createdAt) instead of stacking a twin the close-pass would
+        // later miss. (Supersede deliberately skips ? cards, so without this
+        // twins could never merge at capture at all.)
+        for (let i = cards.length - 1; i >= 0; i--) {
+            const card = cards[i];
+            if (!/❓/.test(card.text) || /🏁|🛠/.test(card.text)) continue;
+            const nTok = tokenSet(card.text);
+            let best = null, bestScore = 0;
+            for (const c of liveTextCards()) {
+                if (!/❓/.test(c.text)) continue;
+                const s = overlapScore(nTok, tokenSet(c.text));
+                if (s > bestScore) { bestScore = s; best = c; }
+            }
+            if (best && bestScore >= QUESTION_MERGE_AT) {
+                await rewriteCard(best.id, j => {
+                    j.content = String(card.text);
+                    j.createdAt = now;
+                    if (card.createdVia) j.createdVia = String(card.createdVia);
+                    if (Array.isArray(card.evidence) && card.evidence.length) j.evidence = card.evidence;
+                });
+                best.text = String(card.text);
+                cards.splice(i, 1);
+                stats.merged++;
+            }
+        }
+
         // SUPERSEDE — pre-mark old cards that a NEW decision replaces. The arrow
         // to the new card is drawn in pass 2 (after the new ids exist), matched
         // back by remembering which old card each new card displaced.
@@ -1153,22 +1453,36 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             if (/❓|🎯|🏁|🛠/.test(card.text)) continue; // only plain decisions supersede (not questions/goals/milestones/skills)
             const nTok = tokenSet(card.text);
             const area = (card.area || '').toLowerCase();
+            // A correction-cue note ("CORRECTION: … was WRONG") declares it
+            // replaces something — widen the search to ALL areas and lower the
+            // bar: a cross-area reworded correction could never fire the
+            // same-area 0.6 path by construction, which is exactly how stale
+            // cards outlived their corrections in the field.
+            const isCorrection = hasCorrectionCue(card.text);
+            const nTokCmp = isCorrection ? stripCueMeta(nTok) : nTok;   // cue meta words dilute the denominator
             let best = null, bestScore = 0;
             for (const c of liveTextCards()) {
-                if (area && (c.area || '').toLowerCase() !== area) continue;
+                if (!isCorrection && area && (c.area || '').toLowerCase() !== area) continue;
                 if (/🛠/.test(c.text)) continue; // never auto-archive a 🛠️ skill via a decision's supersede — skills are standing reference (correct with ~)
-                const s = overlapScore(nTok, tokenSet(c.text));
+                // cueMatch returns 0 unless it clears the widened bar (ratio OR
+                // absolute subject mass) — so for corrections, any non-zero fires.
+                const s = isCorrection ? cueMatch(nTokCmp, tokenSet(c.text), CORRECTION_SUPERSEDE_AT) : overlapScore(nTok, tokenSet(c.text));
                 if (s > bestScore) { bestScore = s; best = c; }
             }
-            if (best && bestScore >= SUPERSEDE_AT) {
+            if (best && (isCorrection ? bestScore > 0 : bestScore >= SUPERSEDE_AT)) {
                 await rewriteCard(best.id, j => {
                     j.content = `↩︎ superseded ${today}\n${j.content}`;
                     j.borderColor = 'rgba(120,120,135,0.5)';
                 });
                 await archiveCard(best.id);
+                const wasCross = isCorrection && (bestScore < SUPERSEDE_AT || (area && (best.area || '').toLowerCase() !== area));
                 best.text = `↩︎ ${best.text}`;
                 card.__supersedes = best.id;
                 stats.superseded++;
+                // Surface the widened match for confirmation: the caller tells the
+                // agent what was archived and how to undo (restore from Archive /
+                // re-run with ~) — the widened bar acts WITH a visible receipt.
+                if (wasCross) stats.corrections.push({ old: (best.title || String(best.text).replace(/^↩︎\s*/, '').slice(0, 80)), area: best.area || null, overlap: Math.round(bestScore * 100) / 100 });
             }
         }
 
@@ -1184,25 +1498,41 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             if (!target) continue;
             const wantTitle = target.replace(/^\[\[/, '').replace(/\]\]$/, '').trim().toLowerCase();
             const tTok = tokenSet(target);
-            let best = null, bestScore = 0;
+            // Collect EVERY live card the close-target covers — near-duplicate ❓
+            // twins score together, and the old first-match-and-break resolved one
+            // while its twin stayed "open" in every brief forever. Capped for
+            // safety: a close-target is deliberate, so >4 matches means it was too
+            // generic to trust beyond the strongest few.
+            const matches = [];
             for (const c of liveTextCards()) {
+                if (/🛠/.test(c.text)) continue; // skills are standing reference — a closes: must never archive one (mirror the supersede guard)
                 const ct = (c.title || '').trim().toLowerCase();
-                // Title fast-path: exact / prefix / or the card title CONTAINS the
-                // target (handles the common "Area: <title> (extra…)" card title).
-                if (ct && wantTitle.length >= 6 && (ct === wantTitle || ct.startsWith(wantTitle) || wantTitle.startsWith(ct) || ct.includes(wantTitle))) { best = c; bestScore = 1; break; }
+                // Title fast-path: exact / prefix (≥6 chars), or the card title
+                // CONTAINS the target — the contains variant needs a LONGER target
+                // (≥10) because a short generic word ("sandbox") appears in many
+                // unrelated titles and the multi-close below would sweep them all.
+                if (ct && wantTitle.length >= 6 && (ct === wantTitle || ct.startsWith(wantTitle) || wantTitle.startsWith(ct))) { matches.push({ c, cov: 1 }); continue; }
+                if (ct && wantTitle.length >= 10 && ct.includes(wantTitle)) { matches.push({ c, cov: 1 }); continue; }
                 // Else target-coverage (≥2 tokens, no floor): a short deliberate
                 // close-target whose tokens are present in a card is a precise hit.
-                if (tTok.size >= 2) { const cov = coverageOf(tTok, tokenSet(c.text)); if (cov > bestScore) { bestScore = cov; best = c; } }
+                if (tTok.size >= 2) { const cov = coverageOf(tTok, tokenSet(c.text)); if (cov >= CLOSE_COVER_AT) matches.push({ c, cov }); }
             }
-            if (best && bestScore >= CLOSE_COVER_AT) {
-                const ship = String(card.text).replace(/\s+/g, ' ').replace(/^[^:\n]{1,40}:\s*/, '').replace(/^🏁\s*/, '').trim().slice(0, 80);
+            matches.sort((a, b) => b.cov - a.cov);
+            // >4 matches means the target was too GENERIC to trust a sweep —
+            // fall back to the single best match (the pre-1.17 behavior) rather
+            // than archive four semi-related cards in iteration order.
+            const chosen = matches.length > 4 ? matches.slice(0, 1) : matches;
+            if (!chosen.length) continue;
+            const ship = String(card.text).replace(/\s+/g, ' ').replace(/^[^:\n]{1,40}:\s*/, '').replace(/^🏁\s*/, '').trim().slice(0, 80);
+            card.__closesIds = [];
+            for (const { c: best } of chosen) {
                 await rewriteCard(best.id, j => {
                     j.content = `${j.content}\n✅ ${today}: closed by → ${ship}`;
                     j.borderColor = 'rgba(16,185,129,0.35)';
                 });
                 await archiveCard(best.id);
                 best.text = `✅ ${best.text}`;
-                card.__closes = best.id;
+                card.__closesIds.push(best.id);
                 stats.closed++;
             }
         }
@@ -1238,11 +1568,13 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
         const titleIndex = struct.cards
             .filter(c => (c.title || '').trim())
             .map(c => ({ id: c.id, t: c.title.trim().toLowerCase() }));
+        const newIds = new Set();
         for (const card of cards) {
             const created = findNew(card.text);
             if (!created) continue;
+            newIds.add(created.id);
             if (card.__supersedes) addConn(card.__supersedes, created.id, 'superseded by', undefined);
-            if (card.__closes) addConn(card.__closes, created.id, 'closed by', undefined);
+            for (const cid of (card.__closesIds || [])) addConn(cid, created.id, 'closed by', undefined);
             for (const link of (created.links || [])) {
                 const want = String(link).trim().toLowerCase();
                 if (!want) continue;
@@ -1250,6 +1582,21 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                 if (target) addConn(created.id, target.id, undefined, 'relates_to');
             }
         }
+        // Structural auto-link for the NEW cards — the graph used to form only
+        // when someone explicitly ran brain_connect (never, in practice: 66%
+        // orphans in the field). Run the cheap tag/[[title]] proposer over the
+        // post-append struct and keep only edges touching a just-added card
+        // (≤2 per card via the proposer's own cap), labeled 'auto' so they're
+        // distinguishable from deliberate arrows. Best-effort: an auto-link
+        // failure must never fail a capture.
+        if (newIds.size) {
+            try {
+                for (const e of proposeStructuralConnections(struct, { maxPerCard: 2 })) {
+                    if (!newIds.has(e.fromId) && !newIds.has(e.toId)) continue;
+                    addConn(e.fromId, e.toId, 'auto', 'relates_to');
+                }
+            } catch { /* auto-linking is opportunistic */ }
+        }
         work = await finalizeBrainZip(zip, canvas, manifest, now);
     }
 
@@ -1265,6 +1612,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
 // to Archive, and arrowed → the synthesis. Nothing is deleted (archived verbatim).
 const GARDEN_KEEP_NEWEST = 8;       // per area, never consolidate the newest N
 const GARDEN_MIN_AGE_DAYS = 14;     // only cards older than this are candidates
+const GARDEN_AUTO_MIN_AGE_DAYS = 7; // #auto ship-event cards age out sooner — the durable fact usually also exists as a hand-written milestone
 const GARDEN_MIN_CANDIDATES = 3;    // don't bother merging fewer than this
 const GARDEN_MAX_DEGREE = 1;        // SMART guard: protect load-bearing cards —
 //   only consolidate cards with ≤ this many connections (orphans + leaves). A
@@ -1311,9 +1659,11 @@ export function selectGardenCandidates(struct, { keepNewest = GARDEN_KEEP_NEWEST
         const children = struct.cards
             .filter(c => c.type === 'text' && c.parentId === ctn.id && (c.text || '').trim() && !/⤵|↩|✅|🛠/.test(c.text))  // 🛠️ skills are standing reference — never consolidate them away
             .sort((a, b) => (a.createdAt || 0) - (b.createdAt || 0));
+        const autoCutoff = now - GARDEN_AUTO_MIN_AGE_DAYS * 86_400_000;
+        const isAuto = (c) => (c.tags || []).some(t => String(t).toLowerCase().replace(/^#/, '') === 'auto');
         const old = children
             .slice(0, Math.max(0, children.length - keepNewest))
-            .filter(c => (c.createdAt || 0) < cutoff && (degree.get(c.id) || 0) <= maxDegree);  // dormant: old AND peripheral
+            .filter(c => (c.createdAt || 0) < (isAuto(c) ? autoCutoff : cutoff) && (degree.get(c.id) || 0) <= maxDegree);  // dormant: old AND peripheral (#auto ages faster)
         if (old.length >= minCandidates) out.push({ containerId: ctn.id, title, candidates: old.map(c => ({ id: c.id, text: c.text, createdAt: c.createdAt || 0, degree: degree.get(c.id) || 0 })) });
     }
     return out;