klypix-mcp 1.76.0 → 1.78.0

package/README.md

@@ -1,12 +1,14 @@
 # Every project gets a brain.
 
-**A portable project workspace with a shared brain.**
+**Active state management for multi-agent coding — a local-first active context engine with a shared brain.**
 *One project. One shared understanding.*
 
-**One shared project brain for multi-agent coding.** `klypix-mcp` gives supported coding agents
-and humans one versioned `brain.klypix` in your repo, containing current decisions, corrections,
-evidence anchors, open questions, active work, and handoffs. Agents read it and write to it over
-MCP. You read it and correct it in the [KLYPIX app](https://klypix.com).
+**One actively managed project brain for multi-agent coding.** `klypix-mcp` keeps one versioned
+`brain.klypix` in your repo: the project's active state — current decisions, corrections, evidence
+anchors, open questions, active work, and handoffs. Corrections supersede stale decisions,
+`brain_challenge` tests proposed decisions against standing rules and reversed approaches, and
+sessions declare their scope and get warned about same-machine file overlap. Agents read it and
+write to it over MCP. You read it and correct it in the [KLYPIX app](https://klypix.com).
 
 > **One project. Many agents. One current understanding.**
 

package/bin/klypix-install.mjs

@@ -246,7 +246,15 @@ const flatten = (code) => code
     .replace(/\.\.\/src\/klypix-(core|format)\.mjs/g, './klypix-$1.mjs')
     // brain-doctor + agent-rules (the server's lazy `import('../src/brain-doctor.mjs')`
     // for the brain_doctor tool) → flat sibling refs in the runtime layout.
-    .replace(/\.\.\/src\/(bench|brain-doctor|agent-presence|agent-rules|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|semantic-memory|runtime-inspector|project-graph|git-capture-install)\.mjs/g, './$1.mjs')
+    // capture-gap: the worker imports it from BOTH brain_note (the per-session
+    // capture receipt) and brain_sync (the uncaptured-work check). Both are
+    // wrapped in try/catch by design, so an unflattened path here would not
+    // crash — it would make the agent-neutral half silently never fire in the
+    // deployed runtime. test/cli-args.mjs "G: no unresolved ../src/*.mjs" is the
+    // only thing standing between that and the field; it caught exactly this.
+    // (remote-client deliberately absent: the Remote feature was removed in
+    // 1.73.x, and this cherry-pick must not resurrect it — recorded rule.)
+    .replace(/\.\.\/src\/(bench|brain-doctor|agent-presence|agent-rules|capture-gap|enrichment|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|semantic-memory|runtime-inspector|project-graph|git-capture-install)\.mjs/g, './$1.mjs')
     .replace(/klypix-worker\.mjs/g, 'klypix-mcp-worker.mjs')
     .replace(/const PKG_VERSION = \(\(\) => \{[\s\S]*?\}\)\(\);/, `const PKG_VERSION = '${VERSION}'; // baked at install (flat layout has no package.json)`);
 
@@ -291,12 +299,15 @@ try {
     // (`git tag --points-at HEAD` semantics inside collectRepoState): the
     // release tag names the exact evidence commit, so any non-HEAD comparison
     // would certify code the tag never covered.
-    const checkout = exists(path.join(PKG_ROOT, '.git')) ? collectRepoState(PKG_ROOT) : null;
-    const sourceDecision = deploySourceDecision({ checkout, allowUntagged: ALLOW_UNTAGGED });
+    const gitPresent = exists(path.join(PKG_ROOT, '.git'));
+    const checkout = gitPresent ? collectRepoState(PKG_ROOT) : null;
+    const sourceDecision = deploySourceDecision({ checkout, allowUntagged: ALLOW_UNTAGGED, gitPresent });
     const checkoutLabel = `v${VERSION}, branch ${checkout?.branch || '(detached)'}, head ${checkout?.headShort || '?'}`;
     if (sourceDecision.action === 'refuse') {
         releaseInstallLockSync(installLock);
-        console.error(`✗ refusing to deploy an UNRELEASED source checkout machine-globally: ${checkoutLabel} — no release tag v${VERSION} at HEAD; no files were changed.`);
+        console.error(sourceDecision.source === 'unverifiable-git-state'
+            ? `✗ refusing to deploy from a git checkout whose state could NOT be verified: ${checkoutLabel} — the git probes failed (busy machine?); no files were changed. Retry, or acknowledge a dev deploy explicitly.`
+            : `✗ refusing to deploy an UNRELEASED source checkout machine-globally: ${checkoutLabel} — no release tag v${VERSION} at HEAD; no files were changed.`);
         console.error('  Released installs come from the registry: npx -y klypix-mcp@latest install');
         console.error('  To deliberately deploy this working tree (a dev deploy), acknowledge it: re-run with --allow-untagged or KLYPIX_MCP_ALLOW_UNTAGGED=1.');
         console.error('  An acknowledged dev deploy is stamped dev-owned, so brain_doctor shows it and auto-update will not silently replace it.');
@@ -380,7 +391,7 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [
@@ -402,8 +413,19 @@ try {
     let n = 0;
     for (const st of renameOrder) { renameSyncWithBackoff(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }
 
-    // 3) mark the dir an ESM package
-    fs.writeFileSync(path.join(BRAIN_DIR, 'package.json'), JSON.stringify({ name: 'klypix-project-brain', private: true, type: 'module' }, null, 2));
+    // 3) mark the dir an ESM package — WITH the brain-core version in it. The
+    // version was only ever discoverable from .brain-version.json or by regexing
+    // the baked PKG_VERSION out of klypix-mcp-server.mjs; an agent asked "what
+    // version is this brain?", read package.json (the one place everybody looks),
+    // got `version: undefined`, and reported the install unidentifiable
+    // (2026-08-16 field report). This is provenance, never the gate: the
+    // never-downgrade decision still reads .brain-version.json / .mcp-runtime.json.
+    fs.writeFileSync(path.join(BRAIN_DIR, 'package.json'), JSON.stringify({
+        name: 'klypix-project-brain',
+        ...(VERSION ? { version: VERSION } : {}),
+        private: true,
+        type: 'module',
+    }, null, 2));
 
     // 5) wire the 4 hooks into settings.json (refuse on invalid JSON; back up;
     // atomic). A background runtime-only update refreshes the scripts while

package/bin/klypix-worker.mjs

@@ -686,7 +686,19 @@ server.registerTool('brain_note', {
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
   },
 }, async ({ text, marker, area, closes, canvas }, extra) => {
-  return toContent(await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, via: extra.klypixClientName }));
+  // Both 1.77 and 1.78 ride this call: the enrichment question (the asker's
+  // vocabulary for retrieval) AND the per-session capture receipt below.
+  const result = await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, via: extra.klypixClientName, enrichmentQuestion: mcpPresence.declaredIntent });
+  // Per-session capture receipt — this is what stops the uncaptured-work nudge
+  // from firing at a session that DID record its reasoning, just through MCP
+  // rather than a 🧠 marker. The Stop hook and this server share one session-id
+  // space (the same presence lane), so the receipt written here is the one the
+  // hook reads. Best-effort: a receipt failure must never fail the note.
+  try {
+    const { recordSessionCapture } = await import('../src/capture-gap.mjs');
+    recordSessionCapture(extra?.klypixRequestIdentity?.sessionId || mcpPresence.id);
+  } catch { /* receipt is best-effort */ }
+  return toContent(result);
 });
 
 server.registerTool('brain_message', {
@@ -877,6 +889,77 @@ server.registerTool('brain_sync', {
       }
     } catch { /* observation is best-effort — never fail a sync */ }
   }
+  // ── Uncaptured-work check, host-neutral half ────────────────────────────────
+  // The Stop hook can REFUSE a stop; every other host has no lifecycle hook at
+  // all, so brain_sync is the only place the same question can be asked. Stamp
+  // the git HEAD at "start", and at "complete" compare it against HEAD: commits
+  // that landed during this task with nothing recorded about WHY is the same gap
+  // the hook catches, and it produces the same drafted card. Advisory only — it
+  // never changes status/mutation, so completion semantics are untouched.
+  let captureGapText = '';
+  {
+    const projectDir = report.structured?.project || mcpPresence.vault;
+    const sid = String(extra?.klypixRequestIdentity?.sessionId || mcpPresence.id || '');
+    // `require` does not exist in ESM — the child_process binding has to be
+    // imported, and gitOut must stay synchronous for the ancestry/count chain.
+    let execFileSync = null;
+    try { ({ execFileSync } = await import('child_process')); } catch { /* no child_process → no check */ }
+    const gitOut = (args) => {
+      if (!execFileSync) return '';
+      try {
+        return String(execFileSync('git', args, { cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 4000 })).trim();
+      } catch { return ''; }
+    };
+    // `git merge-base --is-ancestor` answers with its EXIT CODE and prints
+    // nothing, so it must be read as ok/not-ok — an output check would treat
+    // "not an ancestor" and "success" as the same empty string.
+    const gitOk = (args) => {
+      if (!execFileSync) return false;
+      try {
+        execFileSync('git', args, { cwd: projectDir, stdio: 'ignore', timeout: 4000 });
+        return true;
+      } catch { return false; }
+    };
+    try {
+      const gap = await import('../src/capture-gap.mjs');
+      if (phase === 'start' && projectDir && sid) {
+        const head = gitOut(['rev-parse', 'HEAD']);
+        if (head) gap.recordTaskBaseline(sid, { head, project: projectDir });
+      } else if (phase === 'complete' && projectDir && sid) {
+        const baseline = gap.readTaskBaseline(sid);
+        if (baseline?.head) {
+          // An ancestry check first: a rebase/reset makes the range meaningless,
+          // and reporting a rewritten history as "commits you didn't record" is
+          // exactly the cry-wolf that gets a nudge switched off.
+          const reachable = gitOk(['merge-base', '--is-ancestor', baseline.head, 'HEAD']);
+          const count = reachable ? Number(gitOut(['rev-list', '--count', '--no-merges', `${baseline.head}..HEAD`]) || 0) : 0;
+          if (count > 0) {
+            const subjects = gitOut(['log', '--no-merges', '--format=%s', `${baseline.head}..HEAD`])
+              .split('\n').map((s) => s.trim()).filter(Boolean).slice(0, 5);
+            // Bodies decide whether ANY rationale was recorded — the same rule
+            // the hook uses, so the two halves never disagree about one session.
+            const withRationale = gitOut(['log', '--no-merges', '--format=%x1e%b', `${baseline.head}..HEAD`])
+              .split('\x1e').map((b) => b.replace(/\s+/g, ' ').trim()).filter((b) => b.length >= 12).length;
+            const decision = gap.captureGapDecision({
+              commitTotal: count,
+              commitCards: withRationale,
+              sessionCaptured: gap.sessionHasCaptured(sid),
+            });
+            if (decision) {
+              const changed = gitOut(['diff', '--name-only', `${baseline.head}..HEAD`]).split('\n').filter(Boolean).slice(0, 20);
+              const draft = gap.draftCaptureMarker({
+                commits: subjects.map((subject) => ({ subject })),
+                filesTouched: changed,
+              });
+              captureGapText = gap.captureGapReason({ ...decision, draft, mode: 'advise' });
+              gap.recordCaptureGapNudge(sid);
+            }
+          }
+        }
+        gap.clearTaskBaseline(sid);
+      }
+    } catch { /* the check never fails a sync */ }
+  }
   let taskContext = null;
   if (phase !== 'complete' && include_context !== false && (intent || files?.length)) {
     taskContext = await opBrainTaskContext({
@@ -927,7 +1010,7 @@ server.registerTool('brain_sync', {
   return {
     content: [{
       type: 'text',
-      text: [report.text, harnessText, shipNotice, contextText, timingText].filter(Boolean).join('\n\n'),
+      text: [report.text, harnessText, shipNotice, captureGapText, contextText, timingText].filter(Boolean).join('\n\n'),
     }],
     structuredContent,
     ...(report.isError ? { isError: true } : {}),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "klypix-mcp",
-  "version": "1.76.0",
-  "description": "Shared project brain and MCP coordination server for multi-agent coding.",
+  "version": "1.78.0",
+  "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
   "license": "Apache-2.0",
   "keywords": [
@@ -83,7 +83,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && 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/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/enrichment.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/capture-gap.mjs

@@ -0,0 +1,258 @@
+// Uncaptured-work detection — ONE implementation, every host.
+//
+// Capture is opt-in: something has to CHOOSE to emit a 🧠 marker or call
+// brain_note. That fails hardest exactly where it matters most — a long, loaded
+// session is both the least likely to remember and the most likely to have
+// produced something worth keeping. The 2026-08-16 field report is the canonical
+// instance: a multi-session workstream took a file format to a REGISTERED IANA
+// media type (spec written, 8 schema-drift bugs fixed, PR merged, registration
+// landed) and the brain recorded NONE of it — the agent had been writing to its
+// own private per-project memory dir the whole time, which no peer can read.
+//
+// This module holds the parts that must behave identically whether the caller is
+// the Claude Code Stop hook (which can REFUSE the stop) or an MCP host calling
+// brain_sync(phase:"complete") (which can only advise). Both ask the same
+// question of the same facts and hand back the same drafted card.
+//
+// Three deliberate properties, each learned the hard way:
+//
+//   • A DRAFT, NOT AN ASSIGNMENT. Asking a drained session to "record the
+//     decision" buys a one-line receipt ("merged PR #406") — the event, never
+//     the reasoning, which is the half that was actually lost. So the draft
+//     pre-fills every mechanical fact from the artifacts themselves (ship, commit
+//     subjects, files, area) and leaves exactly ONE slot: why it matters. The
+//     agent supplies the only sentence it alone knows, or discards the card.
+//
+//   • PER-SESSION PROVENANCE, NOT FILE MTIME. The first cut stayed silent when
+//     brain.klypix changed during the session — which, on a shared brain with
+//     ten live sessions, means a PEER's card silences the session that shipped
+//     and recorded nothing. That is backwards: it goes quiet exactly in the
+//     multi-agent case. Silence now requires THIS session id to have captured.
+//
+//   • NARROW ON PURPOSE. A nudge that cries wolf gets ignored, then disabled.
+//     It needs a real artifact and a total absence of recorded rationale — a
+//     good commit body IS capture and buys silence.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// Shared sidecar: which sessions have been nudged (once each) and which have
+// captured something (so a later turn in the same session stays quiet). Lives
+// beside the other brain-home state; the Claude Code session id and the MCP
+// presence session id are the SAME id space (the hook and the server share one
+// lane), so a brain_note through MCP correctly silences the Stop hook.
+export function captureGapStatePath(home = os.homedir()) {
+    return path.join(home, '.claude', 'project-brain', '.capture-gap.json');
+}
+
+export function readCaptureGapState(file = captureGapStatePath()) {
+    try {
+        const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return {
+            nudged: Array.isArray(j?.nudged) ? j.nudged.map(String) : [],
+            captured: (j && typeof j.captured === 'object' && !Array.isArray(j.captured)) ? j.captured : {},
+            baselines: (j && typeof j.baselines === 'object' && !Array.isArray(j.baselines)) ? j.baselines : {},
+        };
+    } catch { return { nudged: [], captured: {}, baselines: {} }; }
+}
+
+// Best-effort, never throws. A torn write only loses the memo — `stop_hook_active`
+// remains the primary loop guard and a re-nudge is bounded to one extra turn.
+function writeCaptureGapState(state, file) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(state));
+    } catch { /* best-effort */ }
+}
+
+export function recordCaptureGapNudge(sessionId, file = captureGapStatePath()) {
+    const sid = String(sessionId || ''); if (!sid) return;
+    const state = readCaptureGapState(file);
+    state.nudged = [...state.nudged.filter(s => s !== sid), sid].slice(-300);
+    writeCaptureGapState(state, file);
+}
+
+// Called by EVERY capture path that knows its session: the Stop hook after an
+// authored capture, and the brain_note MCP verb. This is what makes the silence
+// rule per-session instead of per-file.
+export function recordSessionCapture(sessionId, file = captureGapStatePath(), now = Date.now()) {
+    const sid = String(sessionId || ''); if (!sid) return;
+    const state = readCaptureGapState(file);
+    state.captured[sid] = now;
+    // Bound the map: keep the 300 most recent sessions.
+    const entries = Object.entries(state.captured).sort((a, b) => Number(b[1]) - Number(a[1])).slice(0, 300);
+    state.captured = Object.fromEntries(entries);
+    writeCaptureGapState(state, file);
+}
+
+export function sessionHasCaptured(sessionId, file = captureGapStatePath()) {
+    const sid = String(sessionId || ''); if (!sid) return false;
+    return Boolean(readCaptureGapState(file).captured[sid]);
+}
+
+// ── Task baseline, for hosts with no lifecycle hook ──────────────────────────
+// The Stop hook gets its commit window from the hook's own per-project baseline.
+// An MCP host has no such thing, so brain_sync stamps the git HEAD at phase
+// "start" and reads it back at phase "complete" — the same "what landed during
+// this task" question, answered from the only two calls every host makes. Kept
+// in the same sidecar so there is one file to reason about.
+export function recordTaskBaseline(sessionId, { head = '', project = '' } = {}, file = captureGapStatePath(), now = Date.now()) {
+    const sid = String(sessionId || ''); if (!sid || !head) return;
+    const state = readCaptureGapState(file);
+    state.baselines = (state.baselines && typeof state.baselines === 'object' && !Array.isArray(state.baselines)) ? state.baselines : {};
+    state.baselines[sid] = { head: String(head), project: String(project || ''), at: now };
+    const entries = Object.entries(state.baselines).sort((a, b) => Number(b[1]?.at || 0) - Number(a[1]?.at || 0)).slice(0, 300);
+    state.baselines = Object.fromEntries(entries);
+    writeCaptureGapState(state, file);
+}
+
+export function readTaskBaseline(sessionId, file = captureGapStatePath()) {
+    const sid = String(sessionId || ''); if (!sid) return null;
+    const b = readCaptureGapState(file).baselines?.[sid];
+    return (b && b.head) ? b : null;
+}
+
+export function clearTaskBaseline(sessionId, file = captureGapStatePath()) {
+    const sid = String(sessionId || ''); if (!sid) return;
+    const state = readCaptureGapState(file);
+    if (state.baselines?.[sid]) { delete state.baselines[sid]; writeCaptureGapState(state, file); }
+}
+
+// ── The decision ─────────────────────────────────────────────────────────────
+// Returns null to stay silent, or the observed evidence. Pure: every input is
+// supplied by the caller, so the Stop hook (transcript + git) and brain_sync
+// (git + presence) can answer the same question from what each can see.
+export function captureGapDecision({
+    authored = 0, commitTotal = 0, commitCards = 0, shipped = [], pushed = false,
+    filesTouched = 0, sessionCaptured = false, stopHookActive = false,
+    alreadyNudged = false, env = process.env,
+} = {}) {
+    if (String(env.KLYPIX_BRAIN_NUDGE || '').toLowerCase() === 'off') return null;
+    if (stopHookActive || alreadyNudged) return null;
+    if (authored > 0 || commitCards > 0) return null;      // rationale exists somewhere
+    if (sessionCaptured) return null;                      // THIS session already fed the brain
+    const significant = shipped.length > 0 || commitTotal >= 2
+        || (pushed && commitTotal >= 1) || filesTouched >= 6;
+    if (!significant) return null;
+    const undocumented = Math.max(0, commitTotal - commitCards);
+    const evidence = [];
+    if (shipped.length) evidence.push(shipped.slice(0, 3).join(' · '));
+    if (commitTotal) evidence.push(`${commitTotal} new commit${commitTotal === 1 ? '' : 's'}${undocumented === commitTotal ? ' (no rationale body on any of them)' : ''}`);
+    else if (pushed) evidence.push('pushed to a remote');
+    if (filesTouched) evidence.push(`${filesTouched} file${filesTouched === 1 ? '' : 's'} edited`);
+    return evidence.length ? { evidence } : null;
+}
+
+// ── The draft ────────────────────────────────────────────────────────────────
+const slug = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const CC_SCOPE = /^(?:feat|fix|perf|refactor|chore|docs|test|build|ci)(?:\(([^)]+)\))?!?:\s*(.+)$/i;
+
+// The area a drafted card should land in, inferred from what the session
+// actually touched: a conventional-commit scope first (the author's own label),
+// then the dominant source directory, then a neutral fallback. Never invents a
+// topic — an area guessed from prose is worse than "Ship".
+export function inferArea({ commits = [], filesTouched = [] } = {}) {
+    for (const c of commits) {
+        const m = CC_SCOPE.exec(String(c?.subject || ''));
+        if (m && m[1] && m[1].trim()) return m[1].trim();
+    }
+    const counts = new Map();
+    for (const p of filesTouched) {
+        const parts = String(p).replace(/\\/g, '/').split('/').filter(Boolean);
+        // Skip a leading src/lib/app wrapper — "src" is never a useful area.
+        const seg = parts.length >= 2
+            ? (/^(src|lib|app|packages|apps)$/i.test(parts[0]) ? parts[1] : parts[0])
+            : '';
+        if (seg && !/\./.test(seg)) counts.set(seg, (counts.get(seg) || 0) + 1);
+    }
+    let best = '', n = 0;
+    for (const [k, v] of counts) if (v > n) { best = k; n = v; }
+    return best || 'Ship';
+}
+
+const shortFileList = (files, max = 3) => {
+    const uniq = [...new Set(files.map(f => String(f).replace(/\\/g, '/').split('/').pop()).filter(Boolean))];
+    if (!uniq.length) return '';
+    const head = uniq.slice(0, max).join(', ');
+    return uniq.length > max ? `${head} (+${uniq.length - max} more)` : head;
+};
+
+// Build the ready-to-emit marker. Everything mechanical is filled in from the
+// artifacts; the ONE thing left blank is the sentence only the session can
+// supply. That asymmetry is the whole design — a fully pre-written card would
+// just be approved, and we would be back to capturing the event without the why.
+export const WHY_SLOT = '<one sentence: the decision, obligation, or discovery a future session needs — if there is none, say so and discard this>';
+// A draft pasted back with the slot STILL IN IT is a placeholder wearing a
+// card's clothes: it would sit in the brain reading, to every future session, as
+// though the reasoning had been recorded. That is strictly worse than no card,
+// so the marker guard refuses it and says why. The sentinel deliberately matches
+// the head of WHY_SLOT above — test/capture-gap.mjs asserts the two agree, so
+// they cannot drift apart in silence.
+export const UNFILLED_DRAFT_RE = /WHY THIS MATTERS:\s*<\s*one sentence/i;
+export const looksLikeUnfilledDraft = (text) => UNFILLED_DRAFT_RE.test(String(text || ''));
+export function draftCaptureMarker({ shipped = [], commits = [], filesTouched = [], area = '' } = {}) {
+    const resolvedArea = area || inferArea({ commits, filesTouched });
+    const facts = [];
+    if (shipped.length) facts.push(shipped.slice(0, 2).join(' · '));
+    const subjects = commits
+        .map(c => { const m = CC_SCOPE.exec(String(c?.subject || '')); return (m ? m[2] : String(c?.subject || '')).trim(); })
+        .filter(Boolean).slice(0, 3);
+    if (subjects.length) facts.push(subjects.map(s => `"${s}"`).join('; '));
+    const files = shortFileList(filesTouched);
+    if (files) facts.push(files);
+    // A ship with no subjects and no files still deserves a draft — the marker
+    // shape matters more than the richness of the pre-fill.
+    const head = facts.length ? facts.join(' — ') : 'work completed this session';
+    const marker = shipped.length ? '!' : '';           // a ship is a milestone; everything else a decision
+    return {
+        area: resolvedArea,
+        marker,
+        text: `${head}. WHY THIS MATTERS: ${WHY_SLOT}`,
+        line: `🧠 BRAIN [${resolvedArea}]${marker ? ' ' + marker : ''}: ${head}. WHY THIS MATTERS: ${WHY_SLOT}`,
+        tags: [`#${slug(resolvedArea)}`].filter(Boolean),
+    };
+}
+
+// ── The message ──────────────────────────────────────────────────────────────
+// `mode` picks the register: 'refuse' is the Stop hook, which has just declined
+// to end the turn; 'advise' is brain_sync(complete) on a host with no lifecycle
+// hook, where this is the only channel available and nothing is being blocked.
+export function captureGapReason({ evidence = [], draft = null, mode = 'refuse' } = {}) {
+    const lead = mode === 'refuse'
+        ? '[brain] 🧠 UNCAPTURED WORK — this session produced durable artifacts and recorded NOTHING in the project brain.'
+        : '🧠 UNCAPTURED WORK — this task produced durable artifacts and recorded nothing in the project brain.';
+    const out = [
+        lead,
+        `  Observed: ${evidence.join(' · ')}.`,
+        '  Nothing recorded the reasoning: no 🧠 marker, no ✓/~, no rationale-bearing commit body, and this',
+        '  session has not written the brain through any channel.',
+    ];
+    if (draft) {
+        out.push(
+            '',
+            '  A card is DRAFTED from what this session actually did. The facts are filled in; supply the one',
+            '  sentence only you know, then emit it verbatim (or correct it first):',
+            '',
+            `    ${draft.line}`,
+            '',
+            mode === 'refuse'
+                ? '  Emitting that line in your reply is all it takes — the Stop hook harvests it. Or call brain_note.'
+                : '  Pass it to brain_note (text + area), or emit it as a marker if your host harvests them.',
+        );
+    } else {
+        out.push(
+            '  Record it now — one line in your reply:',
+            '    🧠 BRAIN [Area]: <the decision and why>      (`!` milestone · `?` open question · `+` reusable rule)',
+            '  — or call the brain_note MCP verb.',
+        );
+    }
+    out.push(
+        mode === 'refuse'
+            ? '  If there is genuinely nothing durable to keep, say so in one sentence and stop; this will not ask again this session.'
+            : '  If there is genuinely nothing durable to keep, ignore this; it will not be raised again for this session.',
+        '  NOTE: your own memory directory (~/.claude/projects/<project>/memory/) is NOT the project brain. Writing',
+        '  there is private to this host — no other session, agent, or human can read it. Only brain.klypix is shared.',
+    );
+    return out.join('\n') + '\n';
+}

package/src/enrichment.mjs

@@ -0,0 +1,167 @@
+// Retrieval enrichment — the question that produced a card becomes searchable
+// text for it.
+//
+// The measured failure of this brain's retrieval is a VOCABULARY gap inside a
+// compressed cosine space: paraphrase questions ("grab-and-move navigation")
+// share no words with the cards that answer them ("Pan = dedicated hand tool"),
+// and the 2026-08-17 A/B falsified structural enrichment (area/tags/neighbour
+// titles) a second time — prepending more project jargon compresses the space
+// further (recall@5 62% → 52%). What a card is missing is the ASKER'S language,
+// and the capture pipeline holds it for free: the human prompt (Claude hook,
+// machine-turn-guarded) or the session's declared intent (MCP brain_note) that
+// was live when the card was captured. Recording that alongside the card and
+// feeding it to the embedder widens the vocabulary bridge without a model call,
+// a format change, or anything new on the canvas.
+//
+// SIDECAR, DELIBERATELY. Card-shape changes are the expensive kind (merge
+// driver, sync, renderer, read_canvas all must learn them — recorded blast-
+// radius rule), and this data is a retrieval-quality signal with the same
+// machine-local scope as the vector cache it feeds. It lives beside that cache
+// in ~/.claude/project-brain/enrichment/, keyed per brain.
+//
+// KEYED BY BODY PREFIX, NOT CARD ID. Capture does not learn the id the engine
+// assigns, and ids change across merge twins. The stored card TEXT always
+// embeds the marker body verbatim, so a normalized body prefix is a stable,
+// id-free join key: the read side substring-matches it against normalized card
+// text — only for cards being (re)embedded, so the scan cost rides the
+// embedding cost it amortizes into.
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+export const ENRICHMENT_VERSION = 1;
+export const ENRICHMENT_MAX_ENTRIES = 4096;
+export const ENRICHMENT_MAX_QUESTIONS = 3;
+export const ENRICHMENT_MAX_QUESTION_CHARS = 240;
+export const ENRICHMENT_TTL_MS = 60 * 24 * 60 * 60 * 1000;   // 60 days
+export const ENRICHMENT_KEY_CHARS = 160;
+const ENRICHMENT_APPLY_CAP_CHARS = 400;   // max enrichment text appended per card at embed time
+
+const sha16 = (value) => crypto.createHash('sha1').update(String(value)).digest('hex').slice(0, 16);
+
+// One normalization for BOTH sides of the join. Lowercase + collapsed
+// whitespace survives the decorations capture adds around the body (area
+// prefix, emoji, #tags) because the body itself is embedded verbatim.
+export const normalizeForKey = (text) => String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+
+export const enrichmentKeyFor = (bodyText) => normalizeForKey(bodyText).slice(0, ENRICHMENT_KEY_CHARS);
+
+export function enrichmentFileFor(brainPath, home = os.homedir()) {
+  const key = sha16(path.resolve(String(brainPath || '')).replace(/\\/g, '/').toLowerCase());
+  return path.join(home, '.claude', 'project-brain', 'enrichment', `${key}.json`);
+}
+
+function readFile(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || parsed.v !== ENRICHMENT_VERSION || typeof parsed.entries !== 'object') return { v: ENRICHMENT_VERSION, entries: {} };
+    return parsed;
+  } catch {
+    // Corrupt or absent both start empty: enrichment is an additive quality
+    // signal, never load-bearing state — losing it costs recall, not truth.
+    return { v: ENRICHMENT_VERSION, entries: {} };
+  }
+}
+
+const cleanQuestion = (q) => String(q || '').replace(/\s+/g, ' ').trim().slice(0, ENRICHMENT_MAX_QUESTION_CHARS);
+
+/**
+ * Record question/intent text for captured card bodies. `items` is
+ * [{ body, question }]; entries merge per body key (deduped, newest kept,
+ * capped). Bounded overall: past ENRICHMENT_MAX_ENTRIES the OLDEST entries are
+ * pruned — enrichment is a rolling quality window, not an archive, and unlike
+ * the claims lane nothing downstream depends on any single entry existing.
+ */
+export function recordEnrichment(brainPath, items, { home = os.homedir(), now = Date.now() } = {}) {
+  const list = (Array.isArray(items) ? items : [])
+    .map((item) => ({ key: enrichmentKeyFor(item?.body), q: cleanQuestion(item?.question) }))
+    .filter((item) => item.key.length >= 24 && item.q.length >= 8);
+  if (!list.length) return { recorded: 0 };
+  const file = enrichmentFileFor(brainPath, home);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const data = readFile(file);
+  let recorded = 0;
+  for (const { key, q } of list) {
+    const entry = data.entries[key] || { q: [], ts: 0 };
+    if (!entry.q.includes(q)) {
+      entry.q = [q, ...entry.q].slice(0, ENRICHMENT_MAX_QUESTIONS);
+      recorded++;
+    }
+    entry.ts = now;
+    data.entries[key] = entry;
+  }
+  // TTL + size prune, oldest first.
+  const keys = Object.keys(data.entries);
+  for (const key of keys) {
+    if (now - Number(data.entries[key].ts || 0) > ENRICHMENT_TTL_MS) delete data.entries[key];
+  }
+  const remaining = Object.keys(data.entries);
+  if (remaining.length > ENRICHMENT_MAX_ENTRIES) {
+    remaining.sort((a, b) => Number(data.entries[a].ts || 0) - Number(data.entries[b].ts || 0));
+    for (const key of remaining.slice(0, remaining.length - ENRICHMENT_MAX_ENTRIES)) delete data.entries[key];
+  }
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(data), 'utf8');
+  fs.renameSync(tmp, file);
+  return { recorded };
+}
+
+/**
+ * Load the enrichment map for a brain: [{ key, q: [...] }]. Memoized on the
+ * file's mtime: the retrieval hot path hashes EVERY card on every call, so it
+ * must reuse one parsed array (and, via the join memo below, one join result
+ * per card) until the sidecar actually changes.
+ */
+const readMemo = new Map();   // file -> { stamp, entries }
+export function readEnrichment(brainPath, { home = os.homedir(), now = Date.now() } = {}) {
+  const file = enrichmentFileFor(brainPath, home);
+  // Invalidation stamp = mtime AND size. mtime alone is not enough: under load
+  // two writes can land inside one mtime tick, and the memo then served the
+  // PRE-rewrite parse — caught by EN2 failing in the full chain (same-tick
+  // corrupt-file rewrite read back as the old healthy entries) while passing
+  // standalone, where the writes never clustered.
+  let stamp = '';
+  try { const st = fs.statSync(file); stamp = `${st.mtimeMs}|${st.size}`; } catch { stamp = ''; }
+  const memo = readMemo.get(file);
+  if (memo && memo.stamp === stamp) return memo.entries;
+  const data = stamp ? readFile(file) : { entries: {} };
+  const entries = Object.entries(data.entries)
+    .filter(([, entry]) => now - Number(entry.ts || 0) <= ENRICHMENT_TTL_MS)
+    .map(([key, entry]) => ({ key, q: (entry.q || []).map(cleanQuestion).filter(Boolean) }));
+  readMemo.set(file, { stamp, entries });
+  if (readMemo.size > 8) readMemo.delete(readMemo.keys().next().value);
+  return entries;
+}
+
+// Join results memoized per entries-array identity (readEnrichment keeps the
+// array stable until the file changes), bounded so a pathological brain cannot
+// grow the memo without limit.
+const joinMemo = new WeakMap();   // entries[] -> Map(memoKey -> enrichment text)
+
+/**
+ * The enrichment text to append to ONE card's embed input: the questions of
+ * every entry whose body-prefix occurs in the card's normalized text. Linear
+ * in enrichment entries on a memo miss; a hit is one Map lookup.
+ */
+export function enrichmentTextFor(entries, cardText) {
+  if (!entries?.length) return '';
+  const haystack = normalizeForKey(String(cardText || '').slice(0, 1500));
+  if (haystack.length < 24) return '';
+  let cache = joinMemo.get(entries);
+  if (!cache) { cache = new Map(); joinMemo.set(entries, cache); }
+  const memoKey = `${haystack.slice(0, 64)}|${haystack.length}`;
+  const hit = cache.get(memoKey);
+  if (hit !== undefined) return hit;
+  const questions = [];
+  for (const entry of entries) {
+    if (haystack.includes(entry.key)) {
+      for (const q of entry.q) {
+        if (!questions.includes(q)) questions.push(q);
+      }
+    }
+  }
+  const result = questions.length ? questions.join('\n').slice(0, ENRICHMENT_APPLY_CAP_CHARS) : '';
+  if (cache.size < 8192) cache.set(memoKey, result);
+  return result;
+}

package/src/global-brain-hook.mjs

@@ -10,8 +10,12 @@
 //
 // Bulletproof by contract: it runs on EVERY session/turn in EVERY project, so
 // it must be an INSTANT no-op when there's no ./brain.klypix, must NEVER throw,
-// and must ALWAYS exit 0. The format/IO work is lazy-imported only when a brain
-// is actually present, keeping non-brain projects to a bare existsSync.
+// and must ALWAYS exit 0 — with exactly ONE deliberate exception: the
+// uncaptured-work nudge (captureGapDecision) exits 2 on the Stop hook to refuse
+// a stop that would have thrown away a session's reasoning. No FAILURE ever
+// exits non-zero; only that one guarded, once-per-session decision does.
+// The format/IO work is lazy-imported only when a brain is actually present,
+// keeping non-brain projects to a bare existsSync.
 //
 // This is the source-of-truth copy (lives in the KLYPIX repo, version
 // controlled); it is copied to ~/.claude/project-brain/ alongside
@@ -261,10 +265,24 @@ function transcriptSizeBytes(file) {
 //   LEDGER  (per-project): every capture DECISION — added / skipped-seen /
 //           skipped-example / resolve / update — so you can see exactly what
 //           the harvester did (and didn't) ingest, and why.
-//   HEALTH  (global): one line per hook run — mode, ok/err, brain + brief
+//   HEALTH  (per-project): one line per hook run — mode, ok/err, brain + brief
 //           bytes — so a dead/stale/unsynced live copy stops being invisible.
 const LEDGER = path.resolve(CWD, '.claude', 'brain-capture-log.jsonl');
-const HEALTH = path.join(os.homedir(), '.claude', 'project-brain', '.hook-health.jsonl');
+// HEALTH was ONE global file interleaving every project on the machine. Two ways
+// that misled (2026-08-16 field report, both reproduced): the 500-line cap is
+// GLOBAL, so a busy neighbour evicts a quiet project's whole history long before
+// it has 500 lines of its own; and `tail`-ing it from inside a project — which
+// the self-check footer's own pointer invites — answers a DIFFERENT project's
+// question (a KLYPIX line was read as AgentLit's, right down to a brainBytes that
+// matched neither). Now one file per project directory, keyed by basename + a
+// short hash of the absolute path so two checkouts both named `docs` stay apart.
+// The legacy global file is still READ as a fallback (project-filtered) so an
+// upgraded install isn't blind on its first session, and is never written again.
+const HEALTH_LEGACY = path.join(os.homedir(), '.claude', 'project-brain', '.hook-health.jsonl');
+const HEALTH = path.join(
+    os.homedir(), '.claude', 'project-brain', 'health',
+    `${(String(path.basename(CWD) || 'project').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'project')}-${sha(CWD.toLowerCase()).slice(0, 8)}.jsonl`,
+);
 // npm-currency cache — the Stop hook refreshes this at most once/day (best-effort,
 // failure-silent); the SessionStart footer reads ONLY this file (zero network) to
 // surface a stale install. {pkg, latest, checkedAt, lastError?}.
@@ -272,6 +290,11 @@ const NPM_CURRENCY = path.join(os.homedir(), '.claude', 'project-brain', '.npm-c
 const NPM_CURRENCY_TTL = 24 * 60 * 60 * 1000;   // ≤ once/day refresh throttle
 const LOCK = path.resolve(CWD, '.claude', 'brain-capture.lock');   // serialize concurrent captures
 const DRY = process.argv.includes('--dry-run');   // inspect a capture without writing
+// The hook exits 0 by contract. The ONE deliberate exception is the
+// uncaptured-work nudge (see captureGapDecision below), which uses the Stop
+// hook's documented exit-2 path to refuse a stop and hand the reason back to the
+// model. Nothing else ever sets this — a thrown error still exits 0.
+let EXIT_CODE = 0;
 const nowIso = () => { try { return new Date().toISOString(); } catch { return ''; } };
 const brainBytes = () => { try { return fs.statSync(BRAIN).size; } catch { return 0; } };
 function appendJsonl(file, obj, maxLines = 0) {
@@ -1787,16 +1810,23 @@ function commitToCard(c) {
         ...(closes ? { closes } : {}),
     };
 }
+// `total` is the RAW new-commit count and `entries` the raw commits themselves,
+// both independent of how many became cards — the counts differ exactly when
+// commits shipped without rationale (a bare `chore:`, a subject-only commit),
+// which is the signal the uncaptured-work nudge needs, and the entries are what
+// its DRAFT is built from (subjects the session already wrote beat anything the
+// hook could invent).
+const NO_COMMITS = (newLastCommit) => ({ cards: [], total: 0, entries: [], newLastCommit });
 async function gatherCommitCards(prevCommit) {
     let head = '';
-    try { head = git('rev-parse HEAD'); } catch { return { cards: [], newLastCommit: prevCommit }; }
-    if (!head) return { cards: [], newLastCommit: prevCommit };
-    if (!prevCommit) return { cards: [], newLastCommit: head };                 // BASELINE: record HEAD, capture nothing
-    if (head === prevCommit) return { cards: [], newLastCommit: head };         // no new commits
+    try { head = git('rev-parse HEAD'); } catch { return NO_COMMITS(prevCommit); }
+    if (!head) return NO_COMMITS(prevCommit);
+    if (!prevCommit) return NO_COMMITS(head);                                  // BASELINE: record HEAD, capture nothing
+    if (head === prevCommit) return NO_COMMITS(head);                          // no new commits
     try { execSync(`git merge-base --is-ancestor ${prevCommit} HEAD`, { cwd: CWD, stdio: 'ignore', timeout: 2000 }); }
-    catch { return { cards: [], newLastCommit: head }; }                        // history rewritten → re-baseline, don't dump
+    catch { return NO_COMMITS(head); }                                         // history rewritten → re-baseline, don't dump
     let raw = '';
-    try { raw = git(`log ${prevCommit}..HEAD --no-merges --format=%x1e%H%x1f%s%x1f%b`); } catch { return { cards: [], newLastCommit: head }; }
+    try { raw = git(`log ${prevCommit}..HEAD --no-merges --format=%x1e%H%x1f%s%x1f%b`); } catch { return NO_COMMITS(head); }
     const entries = parseCommitLog(raw);
     // Revert retraction (same batch): a "feat: X" shipped-and-reverted before
     // this hook ran must not close the open card X claimed to fulfil. Reverts
@@ -1827,9 +1857,45 @@ async function gatherCommitCards(prevCommit) {
             try { appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'commit-closes', ok: true, err: `closes stripped (branch ${branch || '?'} is not default)` }, 500); } catch { /* best-effort */ }
         }
     }
-    return { cards, newLastCommit: head };
+    return { cards, total: entries.length, entries: entries.slice(0, 15), newLastCommit: head };
 }
 
+// ── Uncaptured-work nudge — silence must not be enough to end a shipping session ──
+// Capture is OPT-IN: something has to CHOOSE to emit a 🧠 marker or call
+// brain_note. That fails hardest exactly where it matters most — a long, loaded
+// session is both the least likely to remember and the most likely to have
+// produced something worth keeping. The 2026-08-16 field report is the canonical
+// instance: a multi-session workstream took a file format to a REGISTERED IANA
+// media type (spec written, 8 schema-drift bugs fixed, PR merged, registration
+// landed) and the brain recorded NONE of it — the agent had been writing to its
+// own private per-project memory dir the whole time, which no peer can read.
+// Nothing noticed that a session had merged a PR and completed an external
+// registration while contributing zero cards; a human caught it by intuition.
+//
+// Closed with the escalation this product already relies on elsewhere: a warning
+// a model may relay or may not is worth little, so the Stop hook REFUSES the stop
+// (exit 2 — the documented "prevents Claude from stopping, continues the
+// conversation" path) and hands back what it observed. The session can still end
+// in one line ("nothing durable — the commit body covers it"); it can no longer
+// end by saying NOTHING.
+//
+// Deliberately narrow, because a nudge that cries wolf gets ignored and then
+// switched off:
+//   • fires only when NOTHING recorded rationale — no 🧠 marker, no ✓/~, and no
+//     rationale-bearing commit card either. A good commit body IS capture.
+//   • needs a real artifact: a ship event (PR merge / release / publish / tag),
+//     a push, ≥2 new commits, or ≥6 files edited this session.
+//   • silent if brain.klypix itself changed inside the session window — brain_note,
+//     an MCP verb, or a peer already fed it. A busy multi-session project therefore
+//     nudges rarely, which is the right direction: false silence beats false nagging.
+//   • at most ONCE per session (stop_hook_active, plus a durable session list for
+//     hosts that don't set it), and off entirely with KLYPIX_BRAIN_NUDGE=off.
+// The decision, the draft and the per-session bookkeeping live in
+// src/capture-gap.mjs so the Stop hook and brain_sync(complete) answer the same
+// question the same way. Imported LAZILY at the call site (typeof-guarded), so a
+// stale flat deployment missing the file degrades to no nudge rather than
+// crashing the capture — the same contract every other optional module here has.
+
 // ── Live cross-session ledger (in-flight ship/version/milestone, 2026-06-28) ─────
 // The brain is ASYNC: a session's decisions/ships land in brain.klypix only at Stop
 // (capture() below), so CONCURRENT sessions read PAST state and are BLIND to what a
@@ -2516,6 +2582,13 @@ async function capture(lib) {
     };
     const shellCmds = [];          // shell commands seen in the transcript (ship-event capture)
     const errorIds = new Set();    // tool_use ids whose result errored — skip those ship-events
+    // Question enrichment (1.77): the HUMAN prompt nearest above a marker is
+    // the natural-language question that produced the card — recorded to the
+    // retrieval sidecar so the card becomes findable in the asker's own words.
+    // deriveIntentFromPrompt is the machine-turn guard: harness-injected "user"
+    // turns (task notifications, hook output) never pollute the vocabulary.
+    let lastUserPrompt = '';
+    const enrichmentPairs = [];
     for (let transcriptIndex = 0; transcriptIndex < lines.length; transcriptIndex++) {
         const ln = lines[transcriptIndex];
         let e; try { e = JSON.parse(ln); } catch { continue; }
@@ -2531,6 +2604,14 @@ async function capture(lib) {
         );
         if (entryInScope) noteFiles(filesInEntry(e));
         scanToolBlocks(e, shellCmds, errorIds);
+        const um = e?.message ?? e;
+        if (um?.role === 'user') {
+            const rawUser = typeof um.content === 'string'
+                ? um.content
+                : Array.isArray(um.content) ? um.content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text).join('\n') : '';
+            const human = deriveIntentFromPrompt(rawUser);
+            if (human) lastUserPrompt = human.slice(0, 240);
+        }
         const text = textOf(e);
         if (!text.includes('🧠')) continue;
         for (const raw of text.split('\n')) {
@@ -2593,6 +2674,21 @@ async function capture(lib) {
                 ledger.push({ action: 'skipped-example', area, preview });
                 continue;
             }
+            // Fourth shape, same principle: a DRAFT (from the uncaptured-work
+            // nudge) pasted back with its "WHY THIS MATTERS:" slot unfilled. The
+            // draft deliberately pre-fills every mechanical fact and leaves one
+            // blank, so an unfilled one carries the event and none of the
+            // reasoning — and would read to every future session as though the
+            // reasoning HAD been recorded. Banking that is worse than banking
+            // nothing, so refuse it and say exactly why. The sentinel mirrors
+            // WHY_SLOT in capture-gap.mjs (inlined: this is the hot marker loop,
+            // which must not depend on an optional module being deployed).
+            if (/WHY THIS MATTERS:\s*<\s*one sentence/i.test(body)) {
+                ledger.push({ action: 'skipped-unfilled-draft', area, preview });
+                process.stderr.write('[brain] ⚠️ drafted card NOT captured — its "WHY THIS MATTERS:" slot is still the placeholder. '
+                    + 'Replace it with the one sentence only you know, then re-emit; or drop the card if there is nothing durable.\n');
+                continue;
+            }
             // Dedup is for ADDITIVE markers only (decision / ? / !): re-capturing
             // one would stack a duplicate card. Type is in the key so a self-heal
             // ~ / ✓ on the SAME text isn't confused with the original decision.
@@ -2625,6 +2721,7 @@ async function capture(lib) {
             const tagLine = [areaTag, ...fileTags].filter(Boolean).join(' ');
             const card = (area ? `${area}: ${prefix}${body}` : `${prefix}${body}`) + (tagLine ? `\n${tagLine}` : '');
             cards.push({ text: card, area, borderColor, ...(closes ? { closes } : {}), ...(evidence ? { evidence } : {}), ...(verify ? { verify } : {}) });
+            if (lastUserPrompt) enrichmentPairs.push({ body, question: lastUserPrompt });
             ledger.push({ action: type === '?' ? 'add-question' : type === '!' ? 'add-milestone' : isSkill ? 'add-skill' : 'add-decision', area, preview, files: fileTags, ...(closes ? { closes } : {}), ...(evidence ? { ev: evidence.map(e => e.ref) } : {}) });
         }
     }
@@ -2725,7 +2822,7 @@ async function capture(lib) {
     // Commit-body auto-capture: rationale-bearing feat/fix/perf commits since
     // the last run (independent of markers), pushed into the SAME capture batch.
     const prevCommit = readLastCommit();
-    const { cards: commitCards, newLastCommit } = await gatherCommitCards(prevCommit);
+    const { cards: commitCards, total: commitTotal, entries: commitEntries, newLastCommit } = await gatherCommitCards(prevCommit);
     for (const cc of commitCards) {
         // Auto-skill from the flow: a rule-stating commit ("fix: imports must stay
         // at top — TDZ") is a reusable gotcha, not a one-time event. Re-glyph it as a
@@ -2760,6 +2857,49 @@ async function capture(lib) {
         // is this turn's real touch-set — the other half of "own scope".
         await draftFindingsFromCards(cards, verified, sid, recentPaths);
     }
+    // Uncaptured-work nudge. Runs BEFORE the nothing-to-capture early return,
+    // because "the batch is empty" is precisely the case it exists for. It only
+    // writes stderr + sets the exit code, so the rest of capture() proceeds
+    // untouched. Lazy, typeof-guarded import: a stale flat deployment without
+    // capture-gap.mjs simply doesn't nudge.
+    const AUTHORED_ACTIONS = new Set(['add-decision', 'add-question', 'add-milestone', 'add-skill', 'resolve', 'update', 'skipped-seen']);
+    const authoredCount = ledger.filter(d => AUTHORED_ACTIONS.has(d.action)).length;
+    if (!DRY) {
+        try {
+            const gapLib = await import(new URL('./capture-gap.mjs', import.meta.url).href);
+            if (typeof gapLib.captureGapDecision === 'function') {
+                const sid = String(input.session_id || '');
+                const state = gapLib.readCaptureGapState();
+                const gap = gapLib.captureGapDecision({
+                    authored: authoredCount,
+                    commitTotal,
+                    commitCards: commitCards.length,
+                    shipped: shipSummaries,
+                    pushed: shellCmds.some(({ id, cmd }) => !errorIds.has(id) && /\bgit\s+push\b/i.test(cmd)),
+                    filesTouched: recentPaths.length,
+                    // Per-SESSION, not per-file: a peer writing the shared brain
+                    // must never silence the session that shipped and said nothing.
+                    sessionCaptured: Boolean(sid && state.captured[sid]),
+                    stopHookActive: input.stop_hook_active === true,
+                    alreadyNudged: Boolean(sid && state.nudged.includes(sid)),
+                });
+                if (gap) {
+                    const draft = typeof gapLib.draftCaptureMarker === 'function'
+                        ? gapLib.draftCaptureMarker({ shipped: shipSummaries, commits: commitEntries, filesTouched: recentPaths })
+                        : null;
+                    gapLib.recordCaptureGapNudge(sid);
+                    // fs.writeSync, not process.stderr.write — this is followed by
+                    // an immediate exit, and a piped stderr write can be async.
+                    try { fs.writeSync(2, gapLib.captureGapReason({ ...gap, draft, mode: 'refuse' })); } catch { /* */ }
+                    EXIT_CODE = 2;
+                    appendJsonl(HEALTH, {
+                        ts: nowIso(), project: path.basename(CWD), mode: 'capture-gap', ok: true,
+                        evidence: gap.evidence.join(' · '), drafted: Boolean(draft), area: draft?.area || null,
+                    }, 500);
+                }
+            }
+        } catch { /* the nudge is never allowed to break a capture */ }
+    }
     // A queued batch from a prior lock-refused capture counts as work to do —
     // the authoritative drain happens INSIDE the brain lock (doCapture), so two
     // concurrent sessions can never both land the same queued batch.
@@ -2907,6 +3047,15 @@ async function capture(lib) {
         try { stats = await doCapture(gotLock); } finally { if (gotLock) releaseLock(LOCK); }
     }
     if (!stats) return;
+    // Enrichment write rides ONLY a successful capture: cards that never landed
+    // must not acquire question text. Lazy + skew-safe — a stale deployment
+    // without enrichment.mjs just skips, costing recall, never correctness.
+    if (enrichmentPairs.length && stats.added > 0) {
+        try {
+            const enrich = await import(new URL('./enrichment.mjs', import.meta.url).href);
+            enrich.recordEnrichment(BRAIN, enrichmentPairs.map(pair => ({ body: pair.body, question: pair.question })));
+        } catch { /* stale deployment or unwritable sidecar — additive signal only */ }
+    }
     const bits = [`${stats.added} added`];
     if (stats.resolved) bits.push(`${stats.resolved} resolved`);
     if (stats.updated) bits.push(`${stats.updated} updated`);
@@ -2953,6 +3102,16 @@ async function capture(lib) {
     }
     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);
+    // Per-session capture receipt — the silence rule for a LATER turn of this same
+    // session. Only AUTHORED capture counts: a session whose only cards were
+    // machine-harvested ships/commits has still recorded no reasoning, and must
+    // stay nudgeable. brain_note (MCP) writes the same receipt for the same id.
+    if (authoredCount > 0 && stats.added + (stats.resolved || 0) + (stats.updated || 0) > 0) {
+        try {
+            const gapLib = await import(new URL('./capture-gap.mjs', import.meta.url).href);
+            gapLib.recordSessionCapture?.(String(input.session_id || ''));
+        } catch { /* receipt is best-effort */ }
+    }
 }
 
 // Keep a compact brain-brief block inside AGENTS.md so agents that read
@@ -3356,11 +3515,14 @@ function selfCheckFooter() {
     try {
         const probs = [];
         // (1) most-recent FAILED run per mode for THIS project, from the HEALTH log.
-        if (fs.existsSync(HEALTH)) {
+        // The per-project log needs no filter; the legacy global one (read only
+        // until this project has written its own file) still does.
+        {
             const proj = path.basename(CWD);
             const mine = [];
-            for (const ln of fs.readFileSync(HEALTH, 'utf8').split('\n').slice(-400)) {
-                if (!ln) continue; try { const o = JSON.parse(ln); if (o.project === proj) mine.push(o); } catch { /* skip */ }
+            const src = fs.existsSync(HEALTH) ? HEALTH : (fs.existsSync(HEALTH_LEGACY) ? HEALTH_LEGACY : null);
+            for (const ln of (src ? fs.readFileSync(src, 'utf8').split('\n').slice(-400) : [])) {
+                if (!ln) continue; try { const o = JSON.parse(ln); if (src === HEALTH || o.project === proj) mine.push(o); } catch { /* skip */ }
             }
             const latest = (mode) => { for (let i = mine.length - 1; i >= 0; i--) if (mine[i].mode === mode) return mine[i]; return null; };
             // Surface a mode's failure only if its latest run is ok:false AND RECENT.
@@ -3395,7 +3557,7 @@ function selfCheckFooter() {
         return '\n\n---\n## ⚠️ Brain self-check — the brain reported a problem with ITSELF\n'
             + 'The hook exits 0 by contract, so this is otherwise invisible (you\'d only notice by missing cards):\n'
             + probs.map(p => `- ${p}`).join('\n')
-            + `\n_Log: \`~/.claude/project-brain/.hook-health.jsonl\`. Re-deploy with \`node scripts/deploy-brain.mjs\`._\n`;
+            + `\n_Log (THIS project only): \`${HEALTH.replace(os.homedir(), '~')}\`. Re-deploy with \`node scripts/deploy-brain.mjs\`._\n`;
     } catch { return ''; }
 }
 
@@ -3467,7 +3629,22 @@ function bakedBrainVersion(brainDir = path.dirname(NPM_CURRENCY)) {
 // compare against — no nag, no noise.
 function versionCurrencyFooter({ file = NPM_CURRENCY, brainDir = path.dirname(NPM_CURRENCY), env = process.env } = {}) {
     try {
-        let cache; try { cache = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return ''; }
+        // TWO independent channels already fetch npm `latest` onto this machine and
+        // neither knew about the other: this cache (refreshed by the Claude Code Stop
+        // hook) and the MCP auto-updater's .autoupdate-status.json. On a machine driven
+        // mostly through another host the Stop hook rarely runs, so THIS cache can sit
+        // months behind while the updater's is current — the field report's "latest"
+        // was ~29 minor versions stale. Take the FRESHER of the two.
+        let cache; try { cache = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { cache = null; }
+        try {
+            const au = JSON.parse(fs.readFileSync(path.join(brainDir, '.autoupdate-status.json'), 'utf8'));
+            const auAt = Date.parse(au?.checkedAt);
+            if (/^\d+\.\d+\.\d+/.test(String(au?.latestVersion || '')) && Number.isFinite(auAt)
+                && (!cache || !Number.isFinite(cache.checkedAt) || auAt > cache.checkedAt)) {
+                cache = { pkg: 'klypix-mcp', latest: String(au.latestVersion), checkedAt: auAt };
+            }
+        } catch { /* no auto-update stamp → the Stop-hook cache stands alone */ }
+        if (!cache) return '';
         const latest = cache && cache.latest;
         // Require a well-formed semver before comparing — rejects missing, the
         // "(offline)" sentinel, and any hand-corrupted cache value (e.g. `123`,
@@ -3475,11 +3652,27 @@ function versionCurrencyFooter({ file = NPM_CURRENCY, brainDir = path.dirname(NP
         if (!latest || !/^\d+\.\d+\.\d+/.test(String(latest))) return '';
         const baked = bakedBrainVersion(brainDir);
         if (!baked) return '';                                           // nothing to compare → silent
-        if (cmpSemver(latest, baked) <= 0) return '';                    // current or ahead → silent
+        if (cmpSemver(latest, baked) <= 0) return '';                    // current or ahead => silent
+        // DATE the cached figure. This line reads as a live registry fact, and it
+        // isn't — it's whatever the Stop hook last fetched. A field report (2026-08-16)
+        // hit the failure mode: the notice claimed latest was one minor ahead while
+        // the registry was ~29 ahead, because the refresh had not run in a long time
+        // and nothing in the wording said so. Age is always shown; a cache older than
+        // the refresh TTL also says the refresh itself has stopped running, which is
+        // the real defect to chase (the number being wrong is only its symptom).
+        const ageMs = Number.isFinite(cache.checkedAt) ? Math.max(0, Date.now() - cache.checkedAt) : null;
+        const ageLabel = ageMs === null ? 'age unknown'
+            : ageMs < 90 * 60_000 ? 'checked just now'
+                : ageMs < 36 * 3_600_000 ? `checked ${Math.round(ageMs / 3_600_000)}h ago`
+                    : `checked ${Math.floor(ageMs / 86_400_000)}d ago`;
+        const staleCache = ageMs === null || ageMs > NPM_CURRENCY_TTL * 1.5;
+        const caveat = staleCache
+            ? ` The registry check is overdue (${ageLabel}), so \`v${latest}\` is a FLOOR — the real gap may be larger. Confirm with \`npm view klypix-mcp version\`.`
+            : ` (npm ${ageLabel}.)`;
         if (!autoUpdateEnabled(env)) {
-            return `\n\n---\n⚠️ **Brain update available** — installed brain core \`v${baked}\` < npm latest \`v${latest}\`. Automatic updates are off; run \`npx klypix-mcp install\`.\n`;
+            return `\n\n---\n⚠️ **Brain update available** — installed brain core \`v${baked}\` < npm latest \`v${latest}\`.${caveat} Automatic updates are off; run \`npx klypix-mcp install\`.\n`;
         }
-        return `\n\n---\n⬆️ **Brain update available** — installed brain core \`v${baked}\` < npm latest \`v${latest}\`. KLYPIX will install it automatically in the background; no action required.\n`;
+        return `\n\n---\n⬆️ **Brain update available** — installed brain core \`v${baked}\` < npm latest \`v${latest}\`.${caveat} KLYPIX will install it automatically in the background; no action required.\n`;
     } catch { return ''; }
 }
 
@@ -3545,7 +3738,8 @@ function legendFooter() {
         + '**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'
         + '**Verified-fix rule drafts:** when a session FIXES + VERIFIES something trap-shaped that landed as a one-off note, the Stop hook auto-DRAFTS a candidate 🛠️ rule (a per-project sidecar — never a brain card). Approve a real recurring trap with the `+` marker the nudge shows you and it becomes a standing rule that fires EVERY session (like the release-naming rule); ignore the rest and they age out. Draft-only, no blind auto-capture.\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'
+        + '**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.\n'
+        + '⚠️ **Your own memory directory is NOT this brain.** Claude Code\'s `~/.claude/projects/<project>/memory/` (and any equivalent host store) is PRIVATE to this host: no other session, agent, or human can read it. Both feel like "saving"; only `brain.klypix` is shared. A host store is for *user* preferences — never leave project state only there. (2026-08-16 field report: a whole workstream, ending in a registered IANA media type, went to the private store and reached the brain only because a human happened to ask.)\n'
         + 'Coordinate with a concurrent session: `🧠 MSG [<their-id or all>]: <text>` — a queued note (NOT a brain card), offered/acknowledged on supported model-context actions and replayed until the receiving model calls `brain_message_receipt` with its exact token.\n';
 }
 
@@ -3813,7 +4007,7 @@ if (!process.env.KLYPIX_BRAIN_NO_MAIN) {
             const mode = process.argv.includes('--prompt') ? 'prompt' : process.argv.includes('--capture') ? 'capture' : 'read';
             appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode, ok: false, err: String((e && e.message) || e).slice(0, 200) }, 500);
         } catch { /* even the breadcrumb is best-effort */ }
-    }).finally(() => process.exit(0));
+    }).finally(() => process.exit(EXIT_CODE));
 }
 
 // Exported for hermetic unit tests only (gated by KLYPIX_BRAIN_NO_MAIN above so the

package/src/install-version.mjs

@@ -72,8 +72,21 @@ export function highestInstalledBrainVersion({ stamp, runtime } = {}) {
 //              without a readable package version also proceeds — the
 //              installer's invalid-candidate refusal already fails closed on
 //              the version itself; this policy never double-guesses it.
-export function deploySourceDecision({ checkout, allowUntagged = false } = {}) {
-  if (!checkout) return { action: 'proceed', source: 'released-artifact' };
+export function deploySourceDecision({ checkout, allowUntagged = false, gitPresent = false } = {}) {
+  // `checkout` is null in TWO very different worlds, and conflating them was a
+  // fail-open found by five consecutive evidence-gate refusals (2026-08-18):
+  // an npm/npx tarball has no .git and IS the released artifact — but a real
+  // git checkout whose probes TIMED OUT under machine load also yields null,
+  // and the guard then deployed an untagged working tree as if it were the
+  // registry channel. The caller already knows whether .git exists; when it
+  // does, an unreadable git state must REFUSE — an honest, retryable refusal
+  // beats a silent unreleased deploy, which is the exact incident class this
+  // guard was built for.
+  if (!checkout) {
+    if (gitPresent && !allowUntagged) return { action: 'refuse', source: 'unverifiable-git-state' };
+    if (gitPresent) return { action: 'proceed', source: 'unverifiable-git-state', acknowledged: true };
+    return { action: 'proceed', source: 'released-artifact' };
+  }
   if (!checkout.packageVersion) return { action: 'proceed', source: 'unversioned-source' };
   if (checkout.isReleaseTag) return { action: 'proceed', source: 'released-tag' };
   return {

package/src/klypix-core.mjs

@@ -1103,7 +1103,7 @@ export async function opAddToCanvas({ vault, canvas, cards, connections, via })
 // open file any agent reads AND writes": a hookless client (Cursor/Cline/Desktop)
 // can now record a decision, ask an open question, mark a milestone, resolve a card,
 // or correct one — with the full lifecycle, not just a flat append.
-export async function opBrainNote({ vault, canvas, text: noteText, area, marker = '', closes, via }) {
+export async function opBrainNote({ vault, canvas, text: noteText, area, marker = '', closes, via, enrichmentQuestion = '' }) {
   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>".`);
@@ -1134,6 +1134,16 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
     let out = res.buffer; try { out = (await tidyBrain(res.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
     await atomicWrite(file, out);
     if (pendingShips.length) clearPendingShips(projectDir);   // durable now — safe to consume
+    // Question enrichment (1.77): the caller session's declared intent is the
+    // natural-language question that produced this card — recorded to the
+    // retrieval sidecar so brain_ask finds the card in the asker's vocabulary.
+    // Additive: any failure costs recall, never the write above.
+    if (enrichmentQuestion && (res.stats?.added || 0) > 0) {
+      try {
+        const enrich = await import('./enrichment.mjs');
+        enrich.recordEnrichment(file, [{ body: noteText, question: enrichmentQuestion }]);
+      } catch { /* sidecar unavailable — additive signal only */ }
+    }
     const s = res.stats || {};
     const bits = [`${s.added || 0} added`];
     for (const k of ['resolved', 'updated', 'merged', 'closed', 'superseded']) if (s[k]) bits.push(`${s[k]} ${k}`);

package/src/mcp-presence.mjs

@@ -3524,5 +3524,13 @@ export function createMcpPresence({
     decorateToolResult,
     get brainPath() { return brainPath; },
     get vault() { return vault; },
+    // The session's own declared intent (or ''), read fresh from the lane —
+    // the enrichment question source for MCP-side brain_note captures.
+    get declaredIntent() {
+      try {
+        const row = listActiveSessions(brainPath).find((s) => s.id === sessionId);
+        return String(row?.intent || '').slice(0, 240);
+      } catch { return ''; }
+    },
   };
 }

package/src/merge-brains.mjs

@@ -83,9 +83,15 @@ function sanitizeDeletionReceipt(raw) {
 //
 // VOLATILE = written by the act of saving, not by a human/agent decision:
 //   updatedAt — touch timestamp        zIndex — display order derived from zKey
+//   editedAt  — the desktop app's authored-edit stamp (2026-08-22): advances on
+//               content-level edits only, but an edit-then-undo cycle leaves the
+//               content identical while the stamp differs — exactly the
+//               same-meaning-different-bytes shape that spawned the updatedAt
+//               twins above. A card whose only difference is WHEN it was last
+//               edited has not diverged.
 // Everything else (content, colors, geometry, evidence, author…) stays load-
 // bearing: a real edit to any of them is still a real conflict.
-const VOLATILE_ITEM_FIELDS = ['updatedAt', 'zIndex'];
+const VOLATILE_ITEM_FIELDS = ['updatedAt', 'zIndex', 'editedAt'];
 
 const sortedStable = (v) => JSON.stringify(v, (_k, val) =>
   (val && typeof val === 'object' && !Array.isArray(val))

package/src/semantic-memory.mjs

@@ -8,6 +8,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
+import { enrichmentTextFor, readEnrichment } from './enrichment.mjs';
 import { createRequire } from 'module';
 
 const PB_DIR = path.join(os.homedir(), '.claude', 'project-brain');
@@ -577,13 +578,28 @@ function readCache(brainPath, desiredHashes) {
 
 async function vectorsForBrainUnlocked(pipe, brainPath, cards) {
   const want = cards.filter((card) => card.type !== 'container' && (card.text || '').trim());
-  const desiredHashes = new Map(want.map((card) => [card.id, sha1(String(card.text))]));
+  // Question enrichment (1.77): the prompt/intent that produced a card is
+  // appended to its EMBED input — the asker's own vocabulary bridging the
+  // paraphrase gap the 2026-08-17 error analysis measured. Additive and
+  // machine-local like this cache itself; an empty sidecar changes nothing,
+  // and the hash covers the enrichment so its arrival re-embeds exactly the
+  // cards it touches. (Structural context was measured HARMFUL twice — 62%→52%
+  // recall@5 — so only asker-language rides here, never area/tag jargon.)
+  let enrichmentEntries = [];
+  try { enrichmentEntries = readEnrichment(brainPath); } catch { enrichmentEntries = []; }
+  const embedInputFor = (card) => {
+    const base = String(card.text).slice(0, 1500);
+    const extra = enrichmentEntries.length ? enrichmentTextFor(enrichmentEntries, card.text) : '';
+    return extra ? `${base}
+${extra}` : base;
+  };
+  const desiredHashes = new Map(want.map((card) => [card.id, sha1(embedInputFor(card))]));
   const loaded = readCache(brainPath, desiredHashes);
   const { file, cache } = loaded;
   let dirty = loaded.dirty;
   const missing = want.filter((card) => cache.cards[card.id]?.h !== desiredHashes.get(card.id));
   if (missing.length) {
-    const vectors = await embedTexts(pipe, missing.map((card) => String(card.text).slice(0, 1500)));
+    const vectors = await embedTexts(pipe, missing.map((card) => embedInputFor(card)));
     missing.forEach((card, index) => {
       cache.cards[card.id] = { h: desiredHashes.get(card.id), v: vectors[index] };
     });