klypix-mcp 1.18.1 → 1.20.0

package/bin/klypix-mcp.mjs

@@ -24,7 +24,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk,
 } from '../src/klypix-core.mjs';
 
 // Real package version for the MCP handshake (was hardcoded '1.0.0', which
@@ -116,6 +116,17 @@ server.registerTool('search_all_brains', {
   },
 }, async ({ query, as_of }) => toContent(await opSearchAllBrains({ vault: VAULT, query, as_of, log })));
 
+server.registerTool('brain_ask', {
+  title: 'Ask the project brain a question (whole-brain, correction-aware answer)',
+  description: 'Answer a natural-language question from the WHOLE project brain — "what did we decide about X?", "where did the auth work land?", "why did we drop Y?". Ranks every card (semantic on-device + lexical hybrid), INCLUDES superseded/archived history (flagged, so you can see how a decision changed), and attaches each stale card\'s live CORRECTION so the answer reflects the current truth, not an outdated card. Returns a synthesis-ready context (full cards + provenance + lifecycle) for you to turn into a direct, cited answer — it does not itself write prose. Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup). Optional as_of (YYYY-MM-DD) answers "what was true then". Defaults to the project brain ("brain").',
+  inputSchema: {
+    question: z.string().describe('The natural-language question to answer from the brain.'),
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+    as_of: z.string().optional().describe('Optional YYYY-MM-DD: answer as of that date (superseded cards count as live if they were current then).'),
+    k: z.number().optional().describe('Max cards to surface for synthesis (default 10, capped 20).'),
+  },
+}, async ({ question, canvas, as_of, k }) => toContent(await opBrainAsk({ vault: VAULT, canvas, question, as_of, k, log })));
+
 server.registerTool('brain_insights', {
   title: 'What matters in a brain — hubs, orphans, stale questions',
   description: 'Structural read of a brain.klypix: the most-connected "hub" cards (load-bearing decisions), orphaned decisions (no connections — maybe forgotten), stale open questions (aging & unresolved), and area sizes. Use to answer "what matters here / what am I forgetting / what should I review?" — read it at the start of a planning session, or before tidying.',
@@ -127,22 +138,24 @@ server.registerTool('brain_insights', {
 
 server.registerTool('brain_connect', {
   title: 'Connect related-but-unlinked brain cards (densify the graph)',
-  description: 'Finds genuinely related cards that AREN\'T linked yet and proposes connections — semantic similarity when the on-device model is installed, else shared tags + [[mentions]]. Dry-run by default (review the suggestions); pass apply:true to draw them (ADDITIVE — never deletes; the human can remove any arrow). Use after brain_insights flags many orphans, to turn a flat list into a real knowledge graph.',
+  description: 'Finds genuinely related cards that AREN\'T linked yet and proposes connections — semantic similarity when the on-device model is installed, else shared tags + [[mentions]]. Dry-run by default (review the suggestions); pass apply:true to draw them (ADDITIVE — never deletes; the human can remove any arrow). Use after brain_insights flags many orphans, to turn a flat list into a real knowledge graph. To DISMISS a brain_reconcile false-positive contradiction, pass pairs:[{fromId,toId}] (the ids are in the reconcile output) with relationship:"not_contradiction" — a persisted dismissal that stops that pair ever resurfacing as a candidate.',
   inputSchema: {
     canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
     apply: z.boolean().optional().describe('false (default) = suggest only; true = draw the connections.'),
     max: z.number().optional().describe('Max connections to propose/draw (default 24).'),
     threshold: z.number().optional().describe('Min semantic similarity 0–1 to link (default 0.45). Higher = fewer, tighter links.'),
+    pairs: z.array(z.object({ fromId: z.string(), toId: z.string() })).optional().describe('Explicit card-id pairs to connect (bypasses auto-proposal). Use to dismiss a reconcile false-positive: pass the two card ids with relationship:"not_contradiction".'),
+    relationship: z.string().optional().describe('Relationship for explicit `pairs` (e.g. "not_contradiction" to permanently dismiss a contradiction candidate, or "relates_to", "depends_on", "supports").'),
   },
-}, async ({ canvas, apply, max, threshold }) => toContent(await opBrainConnect({ vault: VAULT, canvas, apply, max, threshold, log })));
+}, async ({ canvas, apply, max, threshold, pairs, relationship }) => toContent(await opBrainConnect({ vault: VAULT, canvas, apply, max, threshold, pairs, relationship, log })));
 
 server.registerTool('brain_reconcile', {
   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.',
+  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.',
   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").'),
+    mode: z.enum(['all', 'contradictions', 'migrations', 'legacy']).optional().describe('Which pass to run (default "all"): contradictions · migrations · legacy (pre-v1.15 raw-bash ship cards to tidy).'),
   },
 }, async ({ canvas, root, mode }) => toContent(await opBrainReconcile({ vault: VAULT, canvas, root, mode })));
 

package/package.json

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

package/src/agent-rules.mjs

@@ -55,7 +55,7 @@ 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.
+- with the \`klypix-canvas\` MCP server: to **answer a question** from the brain ("what did we decide about X?", "where did Y land?"), call \`brain_ask\` — it ranks the whole brain, includes superseded history, and surfaces the current truth for any corrected card. Use \`search_canvases\` for a raw keyword lookup, \`read_canvas\` (canvas: \`"brain"\`) for the whole thing, or \`brain_insights\` for the load-bearing cards.
 - or via CLI: \`npx klypix-read brain.klypix\`
 
 **When you make a real decision, finding, or milestone — capture it HERE** so it persists for the next session/agent:

package/src/global-brain-hook.mjs

@@ -307,6 +307,12 @@ function touchSession(sid, patch = {}) {
                 // 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 ?? []),
+                // Sibling ledger for LARGE cards (>1KB) with a much deeper cap: the
+                // 100-entry `injected` set evicts old ids in a long session, so a big
+                // card injected early could re-inflate full-text after ~100 other
+                // cards scrolled it out. Big cards are rare, so this cap effectively
+                // never evicts one — enforcing "no >1KB card full-text twice".
+                injectedBig: patch.injectedBig !== undefined ? patch.injectedBig : (prev.injectedBig ?? []),
                 startedAt: prev.startedAt || now, lastSeen: now,
             });
             fs.mkdirSync(SESSIONS_DIR, { recursive: true });
@@ -436,9 +442,16 @@ function messageFooter(sid, tp) {
         fs.writeFileSync(SESSIONS_FILE, JSON.stringify(d2));
     } catch { /* */ } finally { if (got) releaseLock(SESSIONS_LOCK); }
     if (!show.length) return '';
+    // De-dupe identical message TEXT within one delivery: the same note can reach
+    // the lane twice (posted via both the 🧠 MSG marker and the brain_message MCP
+    // twin, or re-sent) as two distinct ids — all are already acked above, so
+    // dropping the repeats here shows each note once without ever re-surfacing it.
+    const seenTxt = new Set();
+    const showUniq = show.filter(m => { const k = String(m.text || '').replace(/\s+/g, ' ').trim().toLowerCase(); if (!k || seenTxt.has(k)) return false; seenTxt.add(k); return true; });
+    if (!showUniq.length) return '';
     const ago = (ts) => { const mm = Math.max(0, Math.round((now - (ts || now)) / 60000)); return mm <= 0 ? 'just now' : `${mm}m ago`; };
     const out = ['', '## 📨 Message(s) from another session in this project (delivered once — act on or reply to them)'];
-    for (const m of show.slice(0, 6)) out.push(`- from ${String(m.from || '?').slice(0, 8)} · ${ago(m.ts)}: ${String(m.text).replace(/\s+/g, ' ').trim().slice(0, 400)}`);
+    for (const m of showUniq.slice(0, 6)) out.push(`- from ${String(m.from || '?').slice(0, 8)} · ${ago(m.ts)}: ${String(m.text).replace(/\s+/g, ' ').trim().slice(0, 400)}`);
     out.push('Reply with `🧠 MSG [<their-id or all>]: <text>` — it reaches them on their next prompt.');
     return '\n' + out.join('\n');
 }
@@ -1236,15 +1249,30 @@ async function promptRetrieve(lib) {
         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.
+        // Awaits-merge decay: a hit saying "PR #N awaits merge" gets a merged-overlay
+        // when a harvested ship event already recorded #N MERGED (deterministic, no
+        // retirement — the fact is right, only its status decayed).
+        let mergeOv = new Map();
+        if (struct && typeof lib.mergeOverlaysFor === 'function') {
+            try { mergeOv = lib.mergeOverlaysFor(struct, freshHits.map(h => h.card)); } catch { /* best-effort */ }
+        }
+        const mergeTag = (id) => { const m = mergeOv.get(id); return m ? `\n  ↳ ⚠️ PR #${m.num} is since MERGED${m.date ? ` (ship event ${m.date})` : ''} — this "awaits merge" note is stale; nothing to do.` : ''; };
+        // Per-session injection dedup: a card already shown full-text this session
+        // renders as one headline, not another ~600 words of context. LARGE cards
+        // (>1KB) are tracked in a separate, deep-capped ledger so the 100-entry
+        // `injected` set's eviction can never re-inflate one (the observed 3× bug).
+        const BIG_CHARS = 1000;
         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 injectedBig = new Set((me && Array.isArray(me.injectedBig)) ? me.injectedBig : []);
+        const isBig = (c) => flat(c.text).length > BIG_CHARS;
+        const wasInjected = (c) => injected.has(c.id) || (isBig(c) && injectedBig.has(c.id));
         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)");
-        const newlyInjected = [];
+        const newlyInjected = [], newlyBig = [];
+        const noteInjected = (c) => { newlyInjected.push(c.id); if (isBig(c)) newlyBig.push(c.id); };
         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);
@@ -1256,11 +1284,11 @@ async function promptRetrieve(lib) {
                 let correctorLine = false;
                 if (!shownNow.has(ov.by.id)) {
                     correctorLine = true;
-                    if (injected.has(ov.by.id)) {
+                    if (wasInjected(ov.by)) {
                         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);
+                        noteInjected(ov.by);
                     }
                     shownNow.add(ov.by.id);
                 }
@@ -1268,16 +1296,20 @@ async function promptRetrieve(lib) {
                 shownNow.add(h.card.id);
                 continue;
             }
-            if (injected.has(h.card.id)) {
-                lines.push(`- (already shown this session) ${head(h.card, 110)}`);
+            if (wasInjected(h.card)) {
+                lines.push(`- (already shown this session) ${head(h.card, 110)}${mergeTag(h.card.id)}`);
                 shownNow.add(h.card.id);
                 continue;
             }
-            lines.push(`- ${flat(h.card.text)}`);
+            lines.push(`- ${flat(h.card.text)}${mergeTag(h.card.id)}`);
             shownNow.add(h.card.id);
-            newlyInjected.push(h.card.id);
+            noteInjected(h.card);
+        }
+        if (newlyInjected.length) {
+            const patch = { injected: [...new Set([...injected, ...newlyInjected])].slice(-100) };
+            if (newlyBig.length) patch.injectedBig = [...new Set([...injectedBig, ...newlyBig])].slice(-400);
+            touchSession(sid, patch);
         }
-        if (newlyInjected.length) touchSession(sid, { injected: [...new Set([...injected, ...newlyInjected])].slice(-100) });
     }
     const parts = [];
     if (lines.length) parts.push(lines.join('\n'));

package/src/klypix-core.mjs

@@ -26,6 +26,7 @@ import {
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
   findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
   selectGardenCandidates, applyGarden, detectContradictions,
+  rankForQuestion, questionContextToMarkdown, findLegacyShipCards,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -369,6 +370,40 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
   return { blocks: [text(`# Cross-project matches for "${query}" (${scored.length} hits in ${brains.length} brains, top ${top.length} · ${mode}${asOfNote})\n\n${lines.join('\n')}`)] };
 }
 
+// ── brain_ask — answer a natural-language question over the WHOLE brain ───────
+// "What did we decide about X?" / "Where did the auth work land?" The daily-use
+// surface: hybrid retrieval (semantic on-device + lexical) over every card
+// (including archived history, flagged), correction-aware (a stale hit carries its
+// live correction), assembled into a SYNTHESIS-READY context the calling agent
+// turns into a direct, cited answer. The engine never calls an LLM (pure retrieval
+// + assembly) — same "engine selects, model writes" contract as brain_connect.
+export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log = () => {} }) {
+  const q = String(question || '').trim();
+  if (!q) return err('brain_ask needs a question.');
+  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>".`);
+  const asOfTs = as_of ? Date.parse(as_of) : null;
+  if (as_of && Number.isNaN(asOfTs)) return err(`Bad as_of date: "${as_of}" — use YYYY-MM-DD.`);
+  let struct;
+  try { ({ struct } = await parseKlypix(fs.readFileSync(t.file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  const stamp = brainStamp(t.file, struct, t.how);
+  // Semantic blend (best-effort, time-bounded): embed the question + the brain's
+  // cards on-device, hand rankForQuestion a Map<cardId, cosine>. A missing/warming
+  // model degrades cleanly to pure lexical.
+  let semantic = null, mode = 'lexical';
+  try {
+    const pipe = await Promise.race([getEmbedder(log), new Promise(r => setTimeout(() => r(null), 20_000))]);
+    if (pipe) {
+      const [qv] = await embedTexts(pipe, [q]);
+      const vecs = await vectorsForBrain(pipe, t.file, struct.cards);
+      if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); mode = 'semantic+lexical (on-device)'; }
+    }
+  } catch { semantic = null; mode = 'lexical (semantic warming — retry for semantic ranking)'; }
+  const result = rankForQuestion(struct, q, { semantic, k: Math.max(1, Math.min(20, k || 10)), as_of: asOfTs != null ? as_of : null });
+  return { blocks: [text(stamp + questionContextToMarkdown(q, result, { mode, as_of: asOfTs != null ? as_of : null }))] };
+}
+
 export async function opBrainInsights({ vault, canvas, staleDays }) {
   const t = brainTarget(vault, canvas);
   if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
@@ -427,14 +462,30 @@ export async function opBrainReconcile({ vault, canvas, root, mode = 'all' }) {
       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')}`);
+        + `   · 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')}`);
     } 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.');
     }
   }
 
+  // (1b) LEGACY SHIP CARDS — pre-v1.15 auto-captured "merged PR — auto-captured
+  // (`gh …`)" cards with raw shell text / path-scraped junk PR numbers. Already
+  // excluded from repeat-matching (so they no longer cry wolf); this surfaces them
+  // for optional one-time cleanup. Suggestion-only — retire each with a ✓ marker.
+  if (mode === 'all' || mode === 'legacy') {
+    const { cards: legacy, total } = findLegacyShipCards(struct);
+    if (legacy.length) {
+      const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+      const lines = legacy.map(c => `- (id ${c.id}) [${c.area || '?'}] ${flat(c.text).slice(0, 140)}`);
+      const more = total > legacy.length ? `\n\n…and ${total - legacy.length} more.` : '';
+      sections.push(`# 🧹 ${total} legacy raw-bash ship card(s) — optional cleanup\n_Pre-v1.15 auto-capture residue (raw shell command / path-scraped PR numbers). They are ALREADY excluded from repeat-detection, so this is cosmetic hygiene, not a correctness fix. To tidy: retire each with \`brain_note\` marker \`✓\`, or leave them — they no longer trigger false repeat warnings._\n\n${lines.join('\n')}${more}`);
+    } else if (mode === 'legacy') {
+      sections.push('✓ No legacy raw-bash ship cards — every ship card is a clean fact.');
+    }
+  }
+
   // (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.
@@ -495,7 +546,7 @@ export async function opBrainGarden({ vault, canvas, apply = false, syntheses })
   }
 }
 
-export async function opBrainConnect({ vault, canvas, apply = false, max = 24, threshold = 0.45, log = () => {} }) {
+export async function opBrainConnect({ vault, canvas, apply = false, max = 24, threshold = 0.45, pairs = null, relationship = null, label = null, log = () => {} }) {
   const tgt = brainTarget(vault, canvas);
   if (tgt.ambiguous) return ambiguousBrainErr(tgt.ambiguous);
   if (!tgt.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}.`);
@@ -507,6 +558,28 @@ export async function opBrainConnect({ vault, canvas, apply = false, max = 24, t
   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('|')));
 
+  // ── Explicit-pairs mode ─────────────────────────────────────────────────────
+  // Draw EXACTLY the given card-id pairs with a chosen relationship, bypassing the
+  // auto-proposer. This is the persisted DISMISS path for a reconcile false
+  // positive: pass relationship:"not_contradiction" and detectContradictions will
+  // treat the pair as settled forever (the escape hatch a correction-cue false
+  // positive — which has no stale card to retire — previously lacked).
+  if (Array.isArray(pairs) && pairs.length) {
+    const rel = typeof relationship === 'string' && relationship ? relationship : 'relates_to';
+    const lbl = (typeof label === 'string' && label) ? label : (rel === 'not_contradiction' ? 'not a contradiction' : undefined);
+    const explicit = pairs
+      .filter(p => p && p.fromId && p.toId && byId.has(p.fromId) && byId.has(p.toId) && p.fromId !== p.toId)
+      .map(p => ({ fromId: p.fromId, toId: p.toId, relationship: rel, ...(lbl ? { label: lbl } : {}) }));
+    if (!explicit.length) return err('pairs needs [{fromId, toId}, …] where both ids are real cards in this brain (see the ids in brain_reconcile output).');
+    const render2 = (e) => `- ${flat(byId.get(e.fromId)?.text)} ↔ ${flat(byId.get(e.toId)?.text)}  (${e.relationship}${e.label ? `: ${e.label}` : ''})`;
+    if (!apply) return { blocks: [text(`# ${explicit.length} explicit connection(s) to draw\n_Re-run with apply:true to draw them.${rel === 'not_contradiction' ? ' These pairs will then be permanently dismissed as contradiction candidates.' : ''}_\n\n${explicit.map(render2).join('\n')}`)] };
+    try {
+      const { buffer, added } = await addBrainConnections(fs.readFileSync(file), explicit);
+      await atomicWrite(file, buffer);
+      return { blocks: [text(`✓ Drew ${added} connection(s)${rel === 'not_contradiction' ? ' — these pair(s) are now dismissed and will NOT resurface as brain_reconcile contradiction candidates' : ''}.\n\n${explicit.slice(0, added).map(render2).join('\n')}`)] };
+    } catch (e) { return err(`Apply failed (brain unchanged): ${e.message}`); }
+  }
+
   let edges = [];
   let mode = 'structural (shared tags + [[mentions]])';
   const pipe = await Promise.race([getEmbedder(log), new Promise(r => setTimeout(() => r(null), 20_000))]);

package/src/klypix-format.mjs

@@ -127,7 +127,11 @@ export async function parseKlypix(buffer) {
     return { struct, zip, assetPaths, isV4, canvas, manifest };
 }
 
-const REL = new Set(['leads_to', 'depends_on', 'relates_to', 'conflicts_with', 'supports', 'questions', 'costs', 'blocks']);
+// 'not_contradiction' is a DISMISSAL edge, not a topical relation: an agent draws
+// it between two cards a reconcile pass flagged as a FALSE contradiction, and
+// detectContradictions then treats the pair as settled forever (the persisted
+// dismiss path the correction-cue false-positive previously lacked).
+const REL = new Set(['leads_to', 'depends_on', 'relates_to', 'conflicts_with', 'supports', 'questions', 'costs', 'blocks', 'not_contradiction']);
 
 /**
  * Build a real .klypix v4 file (nodebuffer) from a simple spec:
@@ -827,13 +831,17 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     const out = [];
     const push = (...lines) => { for (const l of lines) { out.push(l); used += l.length + 1; } };
 
+    // Overdue open cards (self-declared deadline passed) — badged inline so a
+    // stale-dated reminder is flagged the next session instead of decaying silently.
+    const overdueById = findOverdueOpenCards(struct).byId;
+    const odBadge = (c) => { const o = overdueById.get(c.id); return o ? `  ·  ⏰ OVERDUE — deadline ${o.date} passed ${o.daysOverdue}d ago; verify or close (✓)` : ''; };
     push(`# ${struct.title} — brain brief`);
     push(`*${struct.format} · ${struct.counts.cards} cards · ${struct.counts.connections} connections · tiered brief (focus + open + last ${recentDays}d headlines); full cards via klypix-canvas MCP search*`);
     if (focus.length) {
         push('', '## 📌 Human focus (cards the human placed here — act on these first)');
-        for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
+        for (const c of focus) push(`- ${fr(c)}${flat(c.text)}${odBadge(c)}`);
     }
-    if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
+    if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}${odBadge(c)}`); }
     if (skills.length) {
         push('', '## 🛠️ Skills — how we do things here (reusable; applies every session)');
         for (const c of skills.slice(0, maxSkills)) push(`- ${fr(c)}${flat(c.text)}`);
@@ -942,9 +950,13 @@ export function structToUltraBrief(struct, { freshness = null, briefPath = '.cla
         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})`)) {
+    // Overdue opens lead (and get a ⏰ prefix) so a passed deadline is never the
+    // line that falls off the bottom of the preview-sized budget.
+    const overdueById = findOverdueOpenCards(struct).byId;
+    const openSorted = open.slice().sort((a, b) => (overdueById.has(b.id) ? 1 : 0) - (overdueById.has(a.id) ? 1 : 0));
+    if (open.length && pushIf('') && pushIf(`## Open questions & goals (${open.length}${overdueById.size ? `, ${overdueById.size} ⏰ overdue` : ''})`)) {
         let shown = 0;
-        for (const c of open) { if (!pushIf(`- ${fr(c)}${head(c)}`)) break; shown++; }
+        for (const c of openSorted) { if (!pushIf(`- ${overdueById.has(c.id) ? '⏰ OVERDUE ' : ''}${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 || ''))
@@ -1006,6 +1018,118 @@ export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2,
     return scored.filter(s => s.score >= minScore).slice(0, topK);
 }
 
+// ── Ask-the-brain — whole-brain, correction-aware retrieval for a question ───
+// The surface a human actually uses ("what did we decide about X?", "where did
+// the auth work land?"). Distinct from the per-prompt recall hook (which injects
+// a few RELATED cards into every prompt) and search_canvases (raw substring): this
+// RANKS the whole brain against a natural-language question and assembles a
+// SYNTHESIS-READY context for the calling agent to answer from — the engine stays
+// model-free (mirrors brain_connect/garden: engine selects, model writes prose).
+// Three things make it an ANSWER path, not a card dump:
+//   1. Hybrid-ready — lexical always (the shared scorer's weights + length-norm),
+//      semantic blended when the caller (core, with the on-device embedder) passes
+//      a sim map; on a lexical miss the semantic floor still surfaces paraphrases.
+//   2. History-aware — INCLUDES archived/superseded cards (penalized + flagged), so
+//      "what did we decide" can show the arc (decided A → changed to B), and an
+//      optional as_of answers "what was true then".
+//   3. Truth-aware — every stale hit carries its live CORRECTION (the P1 machinery),
+//      so the agent answers from the correction, never the outdated card alone.
+// Pure + node-runnable. `semantic` is Map<cardId, 0..1> or null.
+const deathDateOfCard = (text) => { const m = /(?:↩︎ superseded|↩ superseded|✅) (\d{4}-\d{2}-\d{2})/.exec(String(text)); return m ? Date.parse(m[1]) : null; };
+export function rankForQuestion(struct, question, { semantic = null, k = 10, as_of = null, now = Date.now(), semFloor = 0.30, recentDays = 30 } = {}) {
+    const tokens = queryTokens(question);
+    if (!struct || !Array.isArray(struct.cards) || (!tokens.length && !semantic)) return { hits: [], total: 0, tokens };
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const asOfTs = as_of ? Date.parse(as_of) : null;
+    const timeTravel = asOfTs != null && Number.isFinite(asOfTs);
+    const cutoff = now - recentDays * 86_400_000;
+    const scored = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || !(c.text || '').trim()) continue;
+        const arch = isArchived(c);
+        if (timeTravel) {
+            if ((c.createdAt || 0) > asOfTs) continue;                     // didn't exist yet
+            if (arch) {
+                // A card archived NOW: keep it ONLY if it demonstrably outlived
+                // as_of (its retirement is stamped LATER) — then it was the live
+                // truth then. If it died by as_of, or carries NO dated stamp (we
+                // can't prove it was still live), exclude it — precision-first, so
+                // a "what was true then" answer never asserts a since-dead fact.
+                const died = deathDateOfCard(c.text);
+                if (died == null || died <= asOfTs) continue;
+            }
+        }
+        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));
+        const lenNorm = Math.min(1, 6 / Math.max(6, Math.log2(bodyW.size || 1)));
+        let lex = 0;
+        for (const tok of tokens) {
+            if (titleW.has(tok)) lex += 3;
+            else if (tagStems.has(tok)) lex += 3;
+            else if (bodyW.has(tok)) lex += lenNorm;
+        }
+        const sem = semantic ? (semantic.get(c.id) ?? null) : null;
+        if (lex <= 0 && (sem == null || sem < semFloor)) continue;         // no lexical AND no strong semantic → skip
+        // In time-travel a surviving card WAS live at as_of, so it is NOT stale
+        // history — don't demote or flag it as archived (that status is a present
+        // fact). Outside time-travel, archived cards are demoted but never excluded
+        // (history matters for "what did we…").
+        const effArch = timeTravel ? false : arch;
+        let score = sem != null ? sem * 10 + Math.min(lex, 6) * 0.5 : lex;
+        if (!timeTravel && (c.createdAt || 0) >= cutoff) score += 0.5;
+        if (/🛠/.test(c.text)) score += 1;                                  // standing skills
+        if (effArch) score -= 1.5;
+        scored.push({ card: c, score, sem, archived: effArch });
+    }
+    scored.sort((a, b) => b.score - a.score || (b.card.createdAt || 0) - (a.card.createdAt || 0));
+    const top = scored.slice(0, k);
+    // Correction overlays on the surfaced hits — a stale card gets its live
+    // corrector so the agent answers from the truth (edge or cue; P1 machinery).
+    // NOT in time-travel: a correction is a PRESENT fact; importing a future
+    // corrector into a "what was true then" answer would contaminate it (a
+    // 2026-05 correction leaking into a 2026-02 query). Then-live cards stand
+    // as they were.
+    let overlays = new Map();
+    if (!timeTravel) { try { overlays = correctionOverlaysFor(struct, top.map(h => h.card)); } catch { /* best-effort */ } }
+    const hits = top.map(h => ({ ...h, correction: overlays.get(h.card.id) || null }));
+    return { hits, total: scored.length, tokens };
+}
+
+// Assemble the ranked hits into a SYNTHESIS-READY markdown context: a header that
+// instructs the agent to answer the question directly (cite cards, honor
+// corrections, admit gaps), then each hit full-text with provenance + lifecycle +
+// its correction. Char-budgeted so a huge brain can't blow the tool result.
+export function questionContextToMarkdown(question, result, { mode = 'lexical', as_of = null, budgetChars = 9000 } = {}) {
+    const { hits, total } = result;
+    const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    const day = (ts) => ts ? new Date(ts).toISOString().slice(0, 10) : '';
+    if (!hits.length) {
+        return `# No brain cards answer: “${flat(question)}”\n`
+            + `Searched the whole brain (${mode}) and found nothing relevant. Tell the user the brain doesn't cover this yet — don't guess. If you learn the answer this session, capture it: \`🧠 BRAIN [Area]: <decision>\`.\n`;
+    }
+    const out = [];
+    out.push(`# Answer “${flat(question)}” from these ${hits.length} brain card(s)${as_of ? ` (as of ${as_of})` : ''} — ${total} matched, ${mode} ranking`);
+    out.push('_Synthesize a DIRECT answer from the cards below, then cite the ones you used by [Area]+date. Where a card is marked ⚠️ CORRECTED, answer from the correction, NOT the stale card. Include superseded/archived cards only to show how a decision CHANGED. If the cards don\'t actually answer the question, say so — don\'t pad._');
+    out.push('');
+    let used = out.join('\n').length;
+    let shown = 0;
+    for (const h of hits) {
+        const c = h.card;
+        const status = h.archived ? ' · ⛔ archived/superseded' : '';
+        const rel = h.sem != null ? ` · sim ${h.sem.toFixed(2)}` : '';
+        let block = `## [${flat(c.area) || 'Notes'}] ${day(c.createdAt)}${status}${rel}\n${flat(c.text)}`;
+        if (h.correction) {
+            block += `\n\n  ⚠️ CORRECTED — this card is STALE; the current truth is:\n  ${flat(h.correction.by.text).slice(0, 600)}`;
+        }
+        if (used + block.length + 2 > budgetChars && shown > 0) { out.push(`\n_…and ${hits.length - shown} more matched card(s) omitted for length — narrow the question or use search for the rest._`); break; }
+        out.push(block, '');
+        used += block.length + 2;
+        shown++;
+    }
+    return out.join('\n') + '\n';
+}
+
 // ── External-state reconcile — migration omission tripwire ───────────────────
 // The brain is a NARRATION-capture system: a fact exists only if someone wrote a
 // 🧠 marker or a rationale-bearing commit body. Applying a DB migration to prod
@@ -1081,6 +1205,35 @@ const REPEAT_VERB_STOP = new Set([
 // 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('_');
+// ── Legacy raw-bash ship cards (pre-v1.15 auto-capture residue) ──────────────
+// Before the v1.15 ship-capture rewrite, auto-harvest dumped the RAW shell command
+// into the card ("🏁 merged PR #850 — auto-captured (`cd /c/Users/…/8db42`)") and
+// scraped stray path digits as PR numbers ("merged PR #238886"). These are dense
+// with generic ship verbs + junk numbers, so the possible-repeat warner kept
+// matching them and crying wolf — training agents to ignore repeat warnings. They
+// are (a) excluded from detectRepeatWork below and (b) surfaced by findLegacyShip-
+// Cards for a one-time cleanup. Detection is SIGNATURE-based (not just "old"), so a
+// CLEAN ship card ("Ship: 🏁 merged PR #286") is never touched.
+export const isLegacyRawShipCard = (text) => {
+    const t = String(text || '');
+    if (!/🏁|\bmerged\b|\brelease|\bpublish|\bshipped\b|\btagged\b/i.test(t)) return false;   // ship-shaped only
+    return /auto-captured/i.test(t)                              // the explicit pre-v1.15 stamp
+        || /`[^`]*\b(?:cd|gh|git|npm|node|npx)\b[^`]*`/i.test(t) // a raw shell command left inside the card
+        || /(?:\/c\/users\/|[a-z]:[\\/]+users[\\/]|\/(?:home|users|mnt|tmp)\/)/i.test(t)   // a filesystem-path fragment
+        || /\b(?:PR|pull request|#)\s*#?\d{6,}\b/i.test(t);      // a 6+ digit "PR number" = scraped path digits, not a real PR
+};
+// One-time cleanup surface: the legacy raw-bash ship cards still live in a brain.
+// Suggestion-only (retire each with a ✓ marker) — they're already excluded from
+// repeat-matching, so this is cosmetic hygiene, not a correctness fix.
+export function findLegacyShipCards(struct, { max = 20 } = {}) {
+    const empty = { cards: [], total: 0 };
+    if (!struct || !Array.isArray(struct.cards)) return empty;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const hits = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim()
+        && !isArchived(c) && !/↩|✅/.test(c.text) && isLegacyRawShipCard(c.text));
+    return { cards: hits.slice(0, max), total: hits.length };
+}
+
 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 [];
@@ -1091,6 +1244,7 @@ export function detectRepeatWork(struct, query, { topK = 2, minScore = 5, minTok
         if (c.type === 'container' || !(c.text || '').trim()) continue;
         const kind = kindOf(c.text);
         if (!kind) continue;                          // only COMPLETED-work cards qualify
+        if (isLegacyRawShipCard(c.text)) continue;    // pre-v1.15 raw-bash residue — never a repeat candidate (nonsense scraped PR numbers)
         // Score the first MEANINGFUL line, not a marker stamp: supersede/resolve
         // prepend "↩︎ superseded <date>" / lead with "✅ …", which would otherwise
         // become the title and hide the real content from title-weighted matching.
@@ -1195,6 +1349,12 @@ export function detectContradictions(struct, { minOverlap = 0.45, topK = 12 } =
     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); }
+        // Explicit "not a contradiction" dismissal — settles BOTH a cue pair and a
+        // polarity pair. This is the persisted escape hatch for a correction-cue
+        // FALSE positive: it had no stale card to retire, so a plain link never
+        // cleared it and it re-reported on every run forever. A deliberate
+        // not_contradiction edge (brain_connect pairs:…) now permanently dismisses it.
+        if (e.relationship === 'not_contradiction' || e.label === 'not a contradiction') { settled.add(k1); settled.add(k2); }
         if (e.label !== 'auto') { linked.add(k1); linked.add(k2); }
     }
     const out = [];
@@ -1465,6 +1625,50 @@ export function correctionOverlaysFor(struct, cards, { at = CORRECTION_SUPERSEDE
     return out;
 }
 
+// ── Awaits-merge decay — the deterministic twin of the correction overlay ────
+// A milestone written minutes before the human merges ("PR #332 awaits founder
+// merge") stays stale forever, even though ship-event auto-capture DOES record
+// "merged PR #332" — nothing linked the two. Matching a "PR #N" + awaits-cue card
+// against a harvested "merged PR #N" is EXACT-STRING, zero-inference work. Given
+// the cards recall is about to inject, return for each one carrying an unmet
+// merge that the ship event contradicts a merged-overlay {num, by, date}. The
+// caller annotates the card (never retires it — the fact is right, only its
+// status decayed). Pure + cheap. PR numbers are capped at 5 digits — a 6+ digit
+// "#N" is a path-scraped junk number (see isLegacyRawShipCard), never a real PR.
+const PR_MERGE_AWAIT_RE = /\b(?:await(?:s|ing)?|pending|not\s+yet|yet\s+to\s+be|to\s+be|unmerged|needs?)\b[^.\n]{0,24}?\bmerg/i;
+const PR_MERGED_RE = /\bmerged\b[^.\n]{0,16}?(?:PR|pull\s+request|#)\s*#?(\d{1,5})\b/i;
+const PR_REFS_RE = /\b(?:PR|pull\s+request|#)\s*#?(\d{1,5})\b/ig;
+function prNumbersIn(text) {
+    const out = new Set(); const s = String(text || '');
+    PR_REFS_RE.lastIndex = 0; let m;
+    while ((m = PR_REFS_RE.exec(s))) out.add(m[1]);
+    return out;
+}
+export function mergeOverlaysFor(struct, cards) {
+    const out = new Map();
+    if (!struct || !Array.isArray(struct.cards) || !Array.isArray(cards) || !cards.length) return out;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    // Index PR number → the NEWEST live card that says it merged (ship event or hand marker).
+    const mergedBy = new Map();
+    for (const c of struct.cards) {
+        if (c.type === 'container' || isArchived(c) || !(c.text || '').trim()) continue;
+        const mm = PR_MERGED_RE.exec(c.text); if (!mm) continue;
+        const prev = mergedBy.get(mm[1]);
+        if (!prev || (c.createdAt || 0) >= (prev.createdAt || 0)) mergedBy.set(mm[1], c);
+    }
+    if (!mergedBy.size) return out;
+    for (const card of cards) {
+        if (!card || !card.id || !(card.text || '').trim()) continue;
+        if (PR_MERGED_RE.test(card.text)) continue;       // the hit IS a merge note — nothing to overlay
+        if (!PR_MERGE_AWAIT_RE.test(card.text)) continue; // must actually claim it's awaiting a merge
+        for (const num of prNumbersIn(card.text)) {
+            const by = mergedBy.get(num);
+            if (by && by.id !== card.id) { out.set(card.id, { kind: 'merged', num, by, date: by.createdAt ? new Date(by.createdAt).toISOString().slice(0, 10) : null }); break; }
+        }
+    }
+    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
@@ -2012,6 +2216,45 @@ export function findStaleOpenCards(struct, { coverAt = 0.6, max = 5 } = {}) {
     return { gaps: out.slice(0, max), total: out.length };
 }
 
+// ── Open-question deadline awareness ─────────────────────────────────────────
+// An open card can carry a self-declared deadline ("Rotate NPM_TOKEN before
+// ~2026-07-03"). Once that day passes the card is OVERDUE — but nothing surfaced
+// it, so it decayed silently and served the same stale reminder a day late. This
+// parses an EXPLICIT, cue-anchored ISO date only (a bare date elsewhere in the
+// card — "shipped 2026-06-30" — is NOT a deadline), so a false overdue flag can't
+// fire. Deadline = end of the named UTC day. Used to badge overdue opens in both
+// brief tiers (the "flag it in the next session's brief" acceptance criterion).
+const DEADLINE_RE = /\b(?:before|by|due(?:\s+(?:date|by|on))?|deadline|until|no\s+later\s+than|not\s+later\s+than|eod|end\s+of(?:\s+day)?)\b[^\n.]{0,32}?~?\s*(\d{4}-\d{2}-\d{2})\b/i;
+export function parseDeadline(text) {
+    const m = DEADLINE_RE.exec(String(text || ''));
+    if (!m) return null;
+    const ts = Date.parse(m[1] + 'T23:59:59Z');   // due at the END of the named day (UTC)
+    return Number.isFinite(ts) ? { date: m[1], ts } : null;
+}
+// Live open (❓/🎯) cards whose parsed deadline has passed, newest-overdue-last so
+// the most-overdue lead. Injectable `now` for hermetic tests. Skips already
+// resolved/superseded cards (they carry ✅/↩︎) and skills (standing reference).
+export function findOverdueOpenCards(struct, { now = Date.now() } = {}) {
+    const empty = { overdue: [], total: 0, byId: new Map() };
+    if (!struct || !Array.isArray(struct.cards)) return empty;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const dayMs = (iso) => Date.parse(iso + 'T00:00:00Z');
+    const nowDay = dayMs(new Date(now).toISOString().slice(0, 10));
+    const out = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || !(c.text || '').trim() || isArchived(c)) continue;
+        if (/↩|✅/.test(c.text)) continue;                       // already superseded/resolved
+        if (!/❓|🎯/.test(c.text) || /🛠/.test(c.text)) continue; // open questions & goals only
+        const d = parseDeadline(c.text);
+        // Overdue gate is LENIENT (end of the named day, d.ts) — a card isn't overdue
+        // at 00:01 on its deadline day. The DISPLAY count is a whole-calendar-day
+        // difference, so "before 2026-07-03" seen on 2026-07-04 reads "passed 1d ago".
+        if (d && d.ts < now) out.push({ card: c, date: d.date, daysOverdue: Math.max(0, Math.round((nowDay - dayMs(d.date)) / 86_400_000)) });
+    }
+    out.sort((a, b) => b.daysOverdue - a.daysOverdue);
+    return { overdue: out, total: out.length, byId: new Map(out.map(o => [o.card.id, o])) };
+}
+
 // ── Deliberate note → capture input ──────────────────────────────────────────
 // Turn ONE structured note into captureIntoBrain's input shape — the deliberate
 // twin of the Stop hook's transcript marker parser. This is what lets an ON-DEMAND