klypix-mcp 1.85.0 → 1.86.0

package/README.md

@@ -789,19 +789,37 @@ Read this section before you build on any of it.
 Every number here is measured on our own project brain. Nothing below is published, benchmarked or
 independently validated.
 
-- **Dogfood scale.** KLYPIX itself is built with its own brain: **2,479 cards and 2,018
+- **Dogfood scale.** KLYPIX itself is built with its own brain: **2,695 cards and 2,333
   connections**, written by multiple concurrent agent sessions, receipts in the file. Current as of
-  2026-08-13.
+  2026-09-16.
 - **Recall.** 73% of past decisions recovered with one search round, 55% brief-only, 0% cold.
   Caveat that travels with it: n=20, our own brain, self-authored questions, LLM-judged.
-- **Ranker.** With the production embedder (the eval harness was fixed 2026-08-10 — it had been
-  measuring a vector space the product does not use): recall@5 **30%**, recall@10 35%, recall@20
-  45%, MRR 0.22 of the true source card on n=20 frozen human-paraphrase questions. Lexical-only
-  scores 0% on the same set. The previously published "15% → 40% with the reranker" is **retired**:
-  re-measured validly, the reranker *reduced* recall@5 to 25% and now ships off by default. At n=20
-  every one of these percentages carries a ±20-point 95% confidence interval — treat them as
-  directional until the larger frozen set lands. The regressions are recorded next to the wins:
-  contextual prefixes on short cards, and the reranker itself.
+- **Ranker (`brain_ask`).** Measured 2026-09-16 on the real 2,695-card brain with the production
+  embedder, n=107 frozen questions (agent-authored, adversarially verified, four strata), model-free
+  rank of the true source card: recall@5 **63%** (95% CI 53–71), recall@10 65%, recall@20 69%, MRR
+  0.43, top-1 33%. The stratum that matters most is the honest one: **paraphrase questions that share
+  no words with their card reach recall@5 44%**; status, temporal and multi-hop questions sit at
+  81–93% because they still share vocabulary. Lexical-only scores 0% on the same set.
+- **Second brain.** The same ranker on a different project's brain (1,601 cards, 19 hand-written
+  paraphrases, first cross-brain run): recall@5 **42%** (CI 23–64), top-1 11%, MRR 0.25. Paraphrase
+  recall transfers between brains; the ranker is not tuned to the brain it was built on. It is
+  simply weak on paraphrase everywhere — the embedder's ceiling, documented in `rankForQuestion`.
+- **Retired numbers.** "recall@5 30% (n=20)", "15% → 40% with the reranker" and the "5% → 15% →
+  40%" curve are all **retired**: the first was the n=20 set the larger set replaced, the others were
+  measured with a reranker that ships off by default (validly re-measured it *reduced* recall@5) or
+  by a harness that had drifted from the production vector space (fixed 2026-08-10). The
+  regressions are recorded next to the wins: contextual prefixes on short cards, and the reranker.
+- **The per-prompt hook lane** (the retrieval every Claude Code session receives on every prompt)
+  had never been measured before 1.86. `scripts/eval-hook-lane.mjs` now measures it through the
+  production rankers on a private capture-pair set built from the machine's own enrichment sidecar
+  (`scripts/build-hook-eval-set.mjs`). First measurement, 110 real prompts on our own brain: the
+  lexical lane fired on 97% of content-bearing prompts and held the right card in its top five 29%
+  of the time, and the lane as a whole injected cards on 93% of prompts that should inject nothing
+  (acknowledgements, console echoes, relayed machine turns). 1.86 raises the lexical bar so a
+  single title word no longer injects, and skips the uncorroborated semantic guess for prompts with
+  fewer than four content words: junk injection 93% → 35%, mean cards injected on junk 3.6 → 1.5,
+  at a one-question cost on the 35 real prompts (inside noise). The prompts stay private; the
+  sweep tables are in the source next to the bars they chose.
 - **What we do not publish.** No download count: this package's own 24-hour auto-updater generates
   most of it, so it is not a user count. No adoption, team or customer figures. No brief-token
   figure — the last one was measured at ~600 cards and is stale at 2,479.

package/bin/klypix-worker.mjs

@@ -704,6 +704,7 @@ server.registerTool('brain_note', {
     marker: z.enum(['', '?', '!', '+', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · +=🛠️ skill (reusable how-to/gotcha; always resurfaces, never ages out) · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
     area: z.string().optional().describe('Area/topic — routes the card into that titled container and becomes a #tag (e.g. "Auth", "Release").'),
     closes: z.string().optional().describe('Title or [[wikilink]] of a strategy/question card this note fulfils — resolves+archives it and draws a "closed by" arrow.'),
+    question: z.string().max(240).optional().describe('The question this note ANSWERS, phrased as someone would ask it ("how do we keep a draft separate from what runs?"). Recorded as retrieval enrichment beside the vector cache — never on the canvas — so the card is found by paraphrase, not only by its own words. The session\'s declared intent is recorded as well.'),
     evidence: z.array(z.object({
       kind: z.enum(['file', 'pr', 'url', 'commit', 'run']),
       ref: z.string().min(1).max(1000).describe('A project-relative file path (optional :line or #Lline), or an external reference. External references are stored without fetching them.'),
@@ -724,10 +725,12 @@ server.registerTool('brain_note', {
     }).optional().describe("GUARD CARDS: make this '+' skill fire BEFORE a matching tool call runs (Claude Code PreToolUse denies on severity block; other hosts warn), not just resurface in briefs. The card stays a normal 🛠️ rule — ✓-resolving it retires the guard, ~ with {remove:true} disarms it."),
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
   },
-}, async ({ text, marker, area, closes, evidence, verify, guard, canvas }, extra) => {
+}, async ({ text, marker, area, closes, question, evidence, verify, guard, canvas }, extra) => {
   // 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, evidence, verify, guard, via: extra.klypixClientName, enrichmentQuestion: mcpPresence.declaredIntent });
+  // vocabulary for retrieval) AND the per-session capture receipt below. Since
+  // 1.86 the authored `question` (the pattern) rides beside the declared intent
+  // (the instance); the sidecar's quality gate decides what is worth keeping.
+  const result = await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, evidence, verify, guard, via: extra.klypixClientName, enrichmentQuestion: [question, 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.85.0",
+  "version": "1.86.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -84,11 +84,13 @@
     "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/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/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.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/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.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/brain-evidence.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-reconcile.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/canvas-groups.mjs && node test/git-tools.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.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/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.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/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.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/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.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-reconcile.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/canvas-groups.mjs && node test/git-tools.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",
-    "eval:retrieval": "node scripts/eval-retrieval.mjs"
+    "eval:retrieval": "node scripts/eval-retrieval.mjs",
+    "eval:hook-lane": "node scripts/eval-hook-lane.mjs",
+    "eval:hook-lane:build": "node scripts/build-hook-eval-set.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",

package/src/enrichment.mjs

@@ -66,18 +66,73 @@ function readFile(file) {
 
 const cleanQuestion = (q) => String(q || '').replace(/\s+/g, ' ').trim().slice(0, ENRICHMENT_MAX_QUESTION_CHARS);
 
+// ── Question quality gate (1.86) ─────────────────────────────────────────────
+// "The nearest human prompt" is the right SOURCE of asker language but is not
+// always a question. Measured on this project's own sidecar (2026-09-16, 187
+// recorded texts): 36% were question-shaped, 18% were acknowledgements ("done,
+// what now", "300mb is ok", "ok do them"), and the rest included npm script
+// echoes ("> klypix@1.3.127 release:register …"), hook feedback re-injected
+// as a user turn, and pasted documents. Every one of those was appended to a
+// card's EMBED input as if it were the words someone would ask with — pulling
+// the vector toward generic chatter, the opposite of the vocabulary bridge
+// enrichment exists to build. The gate rejects text that carries no askable
+// vocabulary and runs on BOTH sides (record and read), so an already-recorded
+// sidecar is cleaned lazily on its next read without a rewrite. A rejection
+// costs nothing but recall the text never carried.
+export const ENRICHMENT_MIN_CONTENT_TOKENS = 4;
+const ENRICHMENT_STOPWORDS = new Set((
+  'a an and are as at be been but by can could did do does for from had has have he her his how i if in is it its '
+  + 'just let lets me my no nor not of ok okay on or our out she so than that the their them then there these they this '
+  + 'those to up us was we were what when where which who whom why will with would you your yes yep nope sure please '
+  + 'thanks thank great good fine done cool right now also very really any all both each more most some such too again '
+  + 'about into over under after before while because '
+  // Arabic function words and acknowledgements (folded forms; enrichment text is
+  // recorded as typed, so the common unfolded spellings are listed too).
+  + 'هل ما ماذا لماذا كيف اين أين وين متى من في على الى إلى عن هذا هذه ذلك تلك هو هي هم انا أنا نحن انت أنت و او أو لا نعم تمام طيب اوكي ايوه ايوا'
+).split(/\s+/).filter(Boolean));
+const ENRICHMENT_MACHINE_RE = /stop hook feedback|<agent-message|\[subagent hand-back\]|<task-notification|system-reminder|\[system notification|<command-(?:name|message|args)|local-command-(?:stdout|stderr)|<hook-[a-z0-9-]+|^\[image:|base directory for this skill:/i;
+const ENRICHMENT_CONSOLE_RE = /^[>$]\s|(?:^|\s)npm (?:err!|warn)\b|\bexited with code \d|[✓✔]|^\s*\{"|^\s*\[\{/i;
+const ENRICHMENT_PASTED_DOC_RE = /^#{1,6}\s|^```|^---\s|^(?:import|export|const|function|class)\s/;
+const contentTokens = (text) => String(text || '').toLowerCase().split(/[^\p{L}\p{N}]+/u)
+  .filter((token) => token.length >= 2 && !ENRICHMENT_STOPWORDS.has(token));
+
+/**
+ * Decide whether a text carries askable vocabulary worth embedding beside a
+ * card. Returns { ok, reason, text } — `text` is the cleaned form that would be
+ * recorded. Reasons: too-short · machine (harness/hook output) · console (npm /
+ * shell echo) · pasted-doc (markdown/code block) · low-content (fewer than
+ * ENRICHMENT_MIN_CONTENT_TOKENS non-stopword tokens — the acknowledgement class).
+ */
+export function enrichmentQuestionQuality(question) {
+  const text = cleanQuestion(question);
+  if (text.length < 8) return { ok: false, reason: 'too-short', text };
+  if (ENRICHMENT_MACHINE_RE.test(text)) return { ok: false, reason: 'machine', text };
+  if (ENRICHMENT_CONSOLE_RE.test(text)) return { ok: false, reason: 'console', text };
+  if (ENRICHMENT_PASTED_DOC_RE.test(text)) return { ok: false, reason: 'pasted-doc', text };
+  if (contentTokens(text).length < ENRICHMENT_MIN_CONTENT_TOKENS) return { ok: false, reason: 'low-content', text };
+  return { ok: true, reason: null, text };
+}
+
 /**
  * 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.
+ * Returns { recorded, rejected } — `rejected` counts texts the quality gate
+ * refused (see enrichmentQuestionQuality); they are never written.
  */
 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 list = [];
+  let rejected = 0;
+  for (const item of (Array.isArray(items) ? items : [])) {
+    const key = enrichmentKeyFor(item?.body);
+    if (key.length < 24) continue;
+    const quality = enrichmentQuestionQuality(item?.question);
+    if (!quality.ok) { rejected++; continue; }
+    list.push({ key, q: quality.text });
+  }
+  if (!list.length) return { recorded: 0, rejected };
   const file = enrichmentFileFor(brainPath, home);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const data = readFile(file);
@@ -104,7 +159,7 @@ export function recordEnrichment(brainPath, items, { home = os.homedir(), now =
   const tmp = `${file}.tmp-${process.pid}`;
   fs.writeFileSync(tmp, JSON.stringify(data), 'utf8');
   fs.renameSync(tmp, file);
-  return { recorded };
+  return { recorded, rejected };
 }
 
 /**
@@ -126,9 +181,14 @@ export function readEnrichment(brainPath, { home = os.homedir(), now = Date.now(
   const memo = readMemo.get(file);
   if (memo && memo.stamp === stamp) return memo.entries;
   const data = stamp ? readFile(file) : { entries: {} };
+  // The quality gate runs here too: a sidecar written before 1.86 (or by an
+  // older hook) is cleaned on read, so its acknowledgements and console echoes
+  // stop reaching the embedder without anyone rewriting the file. Entries left
+  // with no acceptable text are dropped from the served array entirely.
   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) }));
+    .map(([key, entry]) => ({ key, q: (entry.q || []).map((q) => enrichmentQuestionQuality(q)).filter((r) => r.ok).map((r) => r.text) }))
+    .filter((entry) => entry.q.length > 0);
   readMemo.set(file, { stamp, entries });
   if (readMemo.size > 8) readMemo.delete(readMemo.keys().next().value);
   return entries;

package/src/global-brain-hook.mjs

@@ -105,25 +105,37 @@ function parseEvidence(s) {
     const prepared = prepareBrainEvidence({ projectRoot: CWD, evidence: refs });
     return prepared.ok ? prepared.evidence : refs; // legacy malformed refs remain unverified
 }
-// Pull optional `closes:` / `ev:` / `verify:` suffixes off the END of a marker
-// body (any order), returning the cleaned body + parsed extras. The suffix
-// region starts at the first known key, so a decision can carry none, any, or
-// all without the keywords leaking into the card text. The three value regexes
-// must stay in LOCKSTEP: each value ends at the NEXT known key (or end of
-// line), so omitting a key from one lookahead silently folds "verify: …" into
-// that key's value — parseEvidence would mint junk file refs from it.
+// Pull optional `closes:` / `ev:` / `verify:` / `q:` suffixes off the END of a
+// marker body (any order), returning the cleaned body + parsed extras. The
+// suffix region starts at the first known key, so a decision can carry none,
+// any, or all without the keywords leaking into the card text. Every value
+// ends at the NEXT known key (or end of line) through ONE shared lookahead
+// built from the key list, so adding a key cannot silently fold "verify: …"
+// into a neighbour's value — the lockstep bug three hand-written lookaheads
+// used to invite (parseEvidence would mint junk file refs from it).
+//
+// `q:` (1.86) is the question this card ANSWERS, in the words someone would
+// ask it. It is pattern-level retrieval enrichment authored by the model that
+// knows the content — recorded in the sidecar beside the vector cache, never
+// on the canvas — so a card is findable by a paraphrase nobody has typed yet,
+// not only by the prompt that happened to precede its capture.
+const MARKER_SUFFIX_KEYS = ['closes', 'ev', 'verify', 'q'];
+const MARKER_SUFFIX_NEXT = `(?=${MARKER_SUFFIX_KEYS.map(k => `\\s+\\b${k}:`).join('|')}|$)`;
 function splitMarkerSuffixes(body) {
-    const m = body.match(/\s+(?:closes|ev|verify):/i);
-    if (!m) return { body, closes: '', evidence: null, verify: '' };
+    const m = body.match(new RegExp(`\\s+(?:${MARKER_SUFFIX_KEYS.join('|')}):`, 'i'));
+    if (!m) return { body, closes: '', evidence: null, verify: '', question: '' };
     const suffix = body.slice(m.index);
-    const closesM = suffix.match(/\bcloses:\s*(.+?)\s*(?=\s+\bev:|\s+\bverify:|$)/i);
-    const evM = suffix.match(/\bev:\s*(.+?)\s*(?=\s+\bcloses:|\s+\bverify:|$)/i);
-    const verifyM = suffix.match(/\bverify:\s*(.+?)\s*(?=\s+\bcloses:|\s+\bev:|$)/i);
+    const grab = (key) => {
+        const mm = suffix.match(new RegExp(`\\b${key}:\\s*(.+?)\\s*${MARKER_SUFFIX_NEXT}`, 'i'));
+        return mm ? mm[1].trim() : '';
+    };
+    const ev = grab('ev');
     return {
         body: body.slice(0, m.index).trim(),
-        closes: closesM ? closesM[1].trim() : '',
-        evidence: evM ? parseEvidence(evM[1].trim()) : null,
-        verify: verifyM ? verifyM[1].trim().slice(0, 200) : '',
+        closes: grab('closes'),
+        evidence: ev ? parseEvidence(ev) : null,
+        verify: grab('verify').slice(0, 200),
+        question: grab('q').slice(0, 240),
     };
 }
 // ── Self-healing brain (decision lifecycle, part 3) ──────────────────────────
@@ -2684,7 +2696,7 @@ async function capture(lib) {
             // Strip optional `closes:` / `ev:` / `verify:` suffixes off the body so
             // they don't leak into the card text; they drive the close-link,
             // evidence, and live-probe below.
-            const { body: cleanBody, closes, evidence, verify } = splitMarkerSuffixes(body);
+            const { body: cleanBody, closes, evidence, verify, question: markerQuestion } = splitMarkerSuffixes(body);
             body = cleanBody; if (!body) continue;
             const preview = body.slice(0, 90);
             // EXAMPLE/doc guard — rejects marker-SYNTAX documentation (which
@@ -2741,7 +2753,12 @@ async function capture(lib) {
             // per-resolution outcome after the capture.
             if (type === '✓') { resolutions.push({ area, text: body }); ledger.push({ action: 'resolve', area, preview, rIdx: resolutions.length - 1 }); continue; }
             // ~ updates the matching card in place (small corrections).
-            if (type === '~') { updates.push({ area, text: body, createdVia: 'claude-code', ...(evidence ? { evidence } : {}), ...(verify ? { verify } : {}) }); ledger.push({ action: 'update', area, preview, ...(evidence ? { ev: evidence.map(e => e.ref) } : {}) }); continue; }
+            if (type === '~') {
+                updates.push({ area, text: body, createdVia: 'claude-code', ...(evidence ? { evidence } : {}), ...(verify ? { verify } : {}) });
+                if (markerQuestion) enrichmentPairs.push({ body, question: markerQuestion });
+                ledger.push({ action: 'update', area, preview, ...(evidence ? { ev: evidence.map(e => e.ref) } : {}) });
+                continue;
+            }
             // Type → scannable prefix + border color: ? open question (amber),
             // ! milestone (blue), + skill (violet), else decision (green). A plain
             // decision whose text reads as a reusable RULE is AUTO-promoted to a
@@ -2759,6 +2776,9 @@ async function capture(lib) {
             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 });
+            // The authored `q:` rides alongside the incidental prompt: the pattern
+            // (what someone would ask) and the instance (what someone did type).
+            if (markerQuestion) enrichmentPairs.push({ body, question: markerQuestion });
             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) } : {}) });
         }
     }
@@ -3561,7 +3581,10 @@ async function promptRetrieve(lib) {
     let hits = [], repeats = [], struct = null;
     if (tokens.length) {
         struct = await cachedStruct(lib);
-        hits = lib.scoreCardsAgainstQuery(struct, tokens, { topK: 5, minScore: 3 });
+        // The lexical bar is the engine's measured export (1.86: 4 — one title
+        // word alone no longer injects; see HOOK_LEXICAL_MIN_SCORE). An older
+        // engine keeps the pre-1.86 bar of 3.
+        hits = lib.scoreCardsAgainstQuery(struct, tokens, { topK: 5, minScore: Number.isFinite(lib.HOOK_LEXICAL_MIN_SCORE) ? lib.HOOK_LEXICAL_MIN_SCORE : 3 });
         // PRECISION-first repeat nudge ("you already did this in another session"):
         // only on a do/build request, only completed-work cards, only high confidence.
         // Matched on the PROMPT's stated intent (ptoks), not the git-diff fallback. A
@@ -3579,8 +3602,15 @@ async function promptRetrieve(lib) {
     // prompt never enters this lane → zero added latency. Bulletproof: not installed
     // / timeout / any failure → stays exactly today's pure-lexical behavior. The
     // helper is optional+deploy-gated, so a missing copy degrades cleanly to lexical.
-    let semMode = 'lexical';
-    if (!repeats.length && !freshHits.length && tokens.length && struct) {
+    let semMode = 'lexical', semTop = null;
+    // Prompt-side admission (1.86): the fallback is an UNCORROBORATED five-card
+    // guess, and the measured cosines cannot tell an acknowledgement from a
+    // real question — but the prompt can. Fewer than FALLBACK_MIN_CONTENT_TOKENS
+    // content tokens ("build best in class", "continue where needed") skips the
+    // lane; the git-diff file tokens do not count, they are not the asker's words.
+    const fallbackEligible = typeof lib.lexicalMissFallbackEligible === 'function' ? lib.lexicalMissFallbackEligible(ptoks) : true;
+    if (!repeats.length && !freshHits.length && tokens.length && struct && !fallbackEligible) semMode = 'sem-skipped';
+    if (!repeats.length && !freshHits.length && tokens.length && struct && fallbackEligible) {
         try {
             const semlib = await import(new URL('./brain-semantic.mjs', import.meta.url).href);
             if (typeof semlib.semanticVecs === 'function') {
@@ -3590,20 +3620,38 @@ async function promptRetrieve(lib) {
                 const sem = await semlib.semanticVecs(BRAIN, struct, humanText || '', { timeoutMs: 1500 });
                 if (!sem) semMode = 'sem-unavailable';
                 else {
-                    const fresh = Date.now() - 30 * 86_400_000;
-                    const ranked = struct.cards
-                        .filter(c => c.type !== 'container' && (c.text || '').trim() && !/^archive$/i.test(c.area || ''))
-                        .map(c => { const v = sem.vecsMap.get(c.id); return { card: c, s: v ? sem.dot(sem.qv, v) : null }; })
-                        .filter(x => x.s != null && x.s >= 0.30)   // miss-path floor: no lexical corroboration, so demand a real match
-                        .map(x => { let score = x.s * 10; if ((x.card.createdAt || 0) >= fresh) score += 0.5; return { card: x.card, score }; })
-                        .sort((a, b) => b.score - a.score).slice(0, 5);
+                    // ONE production primitive for this lane (1.86). The ranking
+                    // used to live inline here, which meant the surface every
+                    // session actually receives was the one no harness could
+                    // measure — an eval must IMPORT the ranker, never re-implement
+                    // it. rankLexicalMissFallback in klypix-format.mjs is that
+                    // primitive (scripts/eval-hook-lane.mjs measures it); its
+                    // defaults are the measured ones. An older engine without the
+                    // export degrades to the pre-1.86 inline ranking.
+                    let ranked;
+                    if (typeof lib.rankLexicalMissFallback === 'function') {
+                        const r = lib.rankLexicalMissFallback(struct, sem, { topK: 5 });
+                        ranked = r.hits; semTop = r.topCos;
+                    } else {
+                        const fresh = Date.now() - 30 * 86_400_000;
+                        ranked = struct.cards
+                            .filter(c => c.type !== 'container' && (c.text || '').trim() && !/^archive$/i.test(c.area || ''))
+                            .map(c => { const v = sem.vecsMap.get(c.id); return { card: c, s: v ? sem.dot(sem.qv, v) : null }; })
+                            .filter(x => x.s != null && x.s >= 0.30)
+                            .map(x => { let score = x.s * 10; if ((x.card.createdAt || 0) >= fresh) score += 0.5; return { card: x.card, score }; })
+                            .sort((a, b) => b.score - a.score).slice(0, 5);
+                    }
                     freshHits = ranked;
                     semMode = ranked.length ? 'sem-hit' : 'sem-empty';
                 }
             }
         } catch { semMode = 'sem-error'; }
-        if (semMode !== 'lexical') { try { appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'prompt', sem: semMode, hits: freshHits.length }, 500); } catch { /* */ } }
     }
+    // The health row carries the best cosine the lane saw (`top1`) so the
+    // admission rule can be re-fitted from the field later without a
+    // transcript — the 2026-09-16 audit had only "hits: 5" ×165 to go on. A
+    // skipped lane is logged too (`sem-skipped`, with the content-token count).
+    if (semMode !== 'lexical') { try { appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'prompt', sem: semMode, hits: freshHits.length, ...(Number.isFinite(semTop) ? { top1: Math.round(semTop * 1000) / 1000 } : {}), ...(semMode === 'sem-skipped' ? { content: ptoks.length } : {}) }, 500); } catch { /* */ } }
     // T8 STATUS-DIGEST INJECTION (2026-07-23): a status-shaped prompt gets the
     // COMPUTED current-state digest INSTEAD of card hits — so an agent that
     // never queried the brain still answers "what is remaining?" from state,
@@ -4104,7 +4152,7 @@ function legendFooter() {
     return '\n\n---\n'
         + '🧠 **Capture markers** — write these in your reply; the Stop hook harvests them into the brain (no separate log step). Use sparingly, for real decisions / milestones / discoveries:\n'
         + '`🧠 BRAIN [Area]: decision` · `[Area] ?: open question` · `[Area] !: milestone` · `[Area] +: 🛠️ skill (reusable how-to / gotcha — resurfaces every session, never ages out)` · `[Area] ✓: resolves+archives the matching card` · `[Area] ~: updates it in place` · 🎯 in text = a goal (reads as open).\n'
-        + 'Optional suffixes: `closes: <card title / [[wikilink]]>` (resolve the strategy/question this fulfils) · `ev: <file[:line]>, PR#<n>` (anchor to code → auto drift-badge).\n'
+        + 'Optional suffixes: `closes: <card title / [[wikilink]]>` (resolve the strategy/question this fulfils) · `ev: <file[:line]>, PR#<n>` (anchor to code → auto drift-badge) · `q: <the question this answers, as someone would ASK it>` (retrieval enrichment — makes the card findable by paraphrase; sidecar only, never on the canvas).\n'
         + '**Correcting a stale card:** include the word `CORRECTION` (or "was WRONG" / "OBSOLETE" — UPPERCASE; casing is the deliberate-signal, casual prose never fires it) in the decision — the capture then hunts the stale card across ALL areas at a lower match bar and supersedes it (archived + arrowed, with a receipt; restore from Archive if it grabbed the wrong one). A rephrased duplicate `?` merges into the existing open question instead of stacking a twin.\n'
         + '**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'

package/src/klypix-core.mjs

@@ -1622,10 +1622,15 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
     // 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) {
+    // Accepts one string or a list (1.86: the caller's authored `question` plus
+    // the declared intent); the sidecar's quality gate drops what carries no
+    // askable vocabulary, so passing both never records junk.
+    const enrichmentQuestions = (Array.isArray(enrichmentQuestion) ? enrichmentQuestion : [enrichmentQuestion])
+      .map((q) => String(q || '').trim()).filter(Boolean);
+    if (enrichmentQuestions.length && (res.stats?.added || 0) > 0) {
       try {
         const enrich = await import('./enrichment.mjs');
-        enrich.recordEnrichment(file, [{ body: noteText, question: enrichmentQuestion }]);
+        enrich.recordEnrichment(file, enrichmentQuestions.map((question) => ({ body: noteText, question })));
       } catch { /* sidecar unavailable — additive signal only */ }
     }
     const s = res.stats || {};

package/src/klypix-format.mjs

@@ -2123,7 +2123,7 @@ export function structToUltraBrief(struct, { freshness = null, briefPath = '.cla
     const tail = [
         '',
         `📖 **Full brief: \`${briefPath}\`** — skills (${skills.length}), milestones, recent decisions, connections, self-heal detail. READ IT before planning non-trivial work.`,
-        '🧠 Capture: `🧠 BRAIN [Area]: <decision>` · `?` question · `!` milestone · `+` skill · `✓` resolve · `~` update · a "CORRECTION: …" decision supersedes its stale card across areas · suffixes `closes:` / `ev:` (full legend in the brief file).',
+        '🧠 Capture: `🧠 BRAIN [Area]: <decision>` · `?` question · `!` milestone · `+` skill · `✓` resolve · `~` update · a "CORRECTION: …" decision supersedes its stale card across areas · suffixes `closes:` / `ev:` / `q: <question this answers>` (full legend in the brief file).',
     ];
     const budget = Math.max(400, budgetChars - tail.reduce((s, l) => s + l.length + 1, 0));
     push(`# ${struct.title} — brain (ultra brief)`);
@@ -2469,6 +2469,91 @@ export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2,
     return scored.filter(s => s.score >= minScore).slice(0, topK);
 }
 
+// ── Lexical-miss semantic fallback — the per-prompt hook's second lane ───────
+// scoreCardsAgainstQuery (above) is what every prompt gets first. When it finds
+// nothing (paraphrase, no keyword overlap) the hook ranks the warm vector cache
+// against the prompt embedding and injects the top few. That ranking lived
+// INLINE in the hook until 1.86, so the one surface every session receives was
+// the one surface no harness could measure. It is a production primitive now:
+// the hook calls it, scripts/eval-hook-lane.mjs imports it, and the defaults
+// below are the measured ones, not guesses.
+//
+// FLOOR HISTORY. The lane shipped with an absolute cosine floor of 0.30
+// ("demand a real match"). Under the production contract (bge-small, CLS
+// pooling, query instruction prefix) cosines never go that low: field health
+// logs across every project on this machine (2026-09-16, 165 lexical-miss
+// prompts with a live model) show EXACTLY five cards injected every single
+// time — the floor never trimmed once. An absolute floor is also the wrong
+// shape: brain_ask's abstention probe measured true answers as low as 0.498
+// while out-of-domain top-1 reaches 0.683 (see rankForQuestion).
+//
+// MEASURED 2026-09-16 (scripts/eval-hook-lane.mjs, 110 real founder prompts
+// from this machine's enrichment sidecar, real 2,695-card brain): on the
+// prompts that reached this lane, the best cosine was 0.58–0.64 for
+// acknowledgements ("do full publish 100%") and 0.64 for the one real prompt
+// that missed lexically — NO cosine bar separates them (`minTop` 0.65 zeroes
+// junk but the sole real row sat at 0.642 with its gold at cosine rank 238).
+// So `minTop` and `margin` ship as null: the harness keeps sweeping them and
+// the hook's health row now records `top1` so the field can supply the
+// evidence this decision lacked. What DOES separate the two classes is the
+// PROMPT: acknowledgements carry 1–3 content tokens, real prompts 4+ — see
+// lexicalMissFallbackEligible below, which the hook applies before this lane.
+// `sem` is the hook's { qv, vecsMap, dot } from brain-semantic.semanticVecs.
+export function rankLexicalMissFallback(struct, sem, { topK = 5, floor = 0.30, minTop = null, margin = null, now = Date.now(), recentDays = 30 } = {}) {
+    const empty = { hits: [], topCos: null, pool: 0 };
+    if (!struct || !Array.isArray(struct.cards) || !sem || !sem.vecsMap || !sem.qv || typeof sem.dot !== 'function') return empty;
+    const fresh = now - recentDays * 86_400_000;
+    const pool = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || !(c.text || '').trim() || /^archive$/i.test(c.area || '')) continue;
+        const v = sem.vecsMap.get(c.id);
+        if (!v) continue;
+        const cos = sem.dot(sem.qv, v);
+        if (!Number.isFinite(cos)) continue;
+        pool.push({ card: c, cos, score: cos * 10 + ((c.createdAt || 0) >= fresh ? 0.5 : 0) });
+    }
+    if (!pool.length) return empty;
+    let topCos = -Infinity;
+    for (const x of pool) if (x.cos > topCos) topCos = x.cos;
+    if (minTop != null && topCos < minTop) return { hits: [], topCos, pool: pool.length };
+    const bar = Math.max(floor ?? -Infinity, margin != null ? topCos - margin : -Infinity);
+    const hits = pool
+        .filter(x => x.cos >= bar)
+        .sort((a, b) => b.score - a.score || (b.card.createdAt || 0) - (a.card.createdAt || 0))
+        .slice(0, Math.max(0, topK));
+    return { hits, topCos, pool: pool.length };
+}
+
+// ── The hook lane's two measured bars (1.86) ─────────────────────────────────
+// Both were swept on 2026-09-16 with scripts/eval-hook-lane.mjs over 110 real
+// founder prompts (35 capture-pairs with a gold card, 75 that should inject
+// nothing) against the real 2,695-card brain. The harness reads these exports,
+// so the number it measures is the number the hook ships.
+//
+// HOOK_LEXICAL_MIN_SCORE — scoreCardsAgainstQuery's bar for the per-prompt
+// lexical lane. A title/tag hit scores 3, a body hit ≤ 1, a standing skill +1:
+//   minScore 3 (pre-1.86)  real prompts: fired 97% · right card in top-5 29% · 4.6 cards
+//                          junk prompts: injected nothing 27% of the time
+//   minScore 4 (ships)     real prompts: fired 91% · right card in top-5 26% · 4.0 cards
+//                          junk prompts: injected nothing 69% of the time
+//   minScore 5             real prompts: fired 74% · 20% · 2.4 cards · junk zero 81%
+// One title word is no longer enough ("do all best in class" used to inject a
+// card titled "…kill stale-closure CLASS…"); a title word plus corroboration,
+// or a 🛠️ skill, still is. The one-gold cost (29→26 on n=35) is inside noise.
+export const HOOK_LEXICAL_MIN_SCORE = 4;
+// FALLBACK_MIN_CONTENT_TOKENS — the semantic fallback only runs for a prompt
+// that carries at least this many content tokens (after stopwords and status
+// vocabulary). Measured: every junk prompt that reached the fallback had 1–3
+// ("build best in class", "continue where needed"); the real ones had 4+
+// ("i pressed restart and nothing appears , why"). Terse real prompts keep the
+// lexical lane and its git-diff fallback — they lose only an uncorroborated
+// five-card semantic guess that the cosine data says cannot tell junk apart.
+export const FALLBACK_MIN_CONTENT_TOKENS = 4;
+export function lexicalMissFallbackEligible(tokens, { minContentTokens = FALLBACK_MIN_CONTENT_TOKENS } = {}) {
+    const n = Array.isArray(tokens) ? tokens.filter(t => typeof t === 'string' && t.trim()).length : 0;
+    return n >= minContentTokens;
+}
+
 // ── 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