klypix-mcp 1.85.0 → 1.86.1

package/FORMAT.md

@@ -143,6 +143,17 @@ references are read with both HEAD and working-file changes considered. These fi
 describe source provenance and change detection, never factual verification.
 `verify` is retained text, not executable configuration. All these optional fields
 survive the format codec and capture lifecycle; an explicit empty amendment clears them.
+A cleared `verify` is stored as the empty string `""`, and a reader treats any string `verify`,
+the empty one included, as authoritative: `""` means "no probe" and nothing is derived from the
+card's prose.
+A card without a `verify` field may still carry one in its text as a line-end
+`verify: <command>` suffix (or a `verify: <command>` line of its own); the reference reader
+derives the field with the same grammar the capture hook uses (lowercase key followed by
+whitespace, trailing position, a command-shaped value with no prose after it), reading a
+hard-wrapped card as its unwrapped sentences, so prose such as `npm run verify:mcp` or
+"every agent verify: the tag" never becomes a probe. A probe stops before a following line that
+opens like a new sentence (a plain capitalised word), because such a break may have been typed
+rather than wrapped.
 
 The optional **`author`** answers the question a team actually asks: `createdBy` says
 *what* wrote a card, `author` says *whose*. It is resolved from `git config user.name`

package/README.md

@@ -381,6 +381,28 @@ same JSON on stdin, or `--evidence '<JSON array>'` and `--verify '<text>'`.
 On Claude Code, decisions are captured automatically at turn end from inline `🧠 BRAIN [Area]:`
 markers in the transcript, deduped, under a capture lock.
 
+A marker can end with optional suffixes, in any order: `closes: <card title or [[wikilink]]>`,
+`ev: <file[:line]>, PR#<n>`, `verify: <command>` and `q: <the question this answers?>`. They count
+only as one run at the end of the line, written lowercase as `key: value`, and each value must
+have its key's shape: references for `ev:`, a command for `verify:`, a question (question word
+first, `?` last) for `q:`. Anything else is kept as card text, so "a Q: and A: layout", "the ev:
+field" or "every agent verify: the tag" never cuts a note short. A malformed segment after a
+well-formed one also stays in the text, and the other suffixes still count; the hook tells the
+agent on its next prompt. On `✓` and `~` markers a `closes:` is plain text, because those markers
+close nothing. A `closes:` that will not act keeps the sentence as written: it names no live card,
+or it names more than four. A `closes:` that does not come after the end of a sentence, a
+`[[wikilink]]` or another suffix closes only a card it names by title. One whose named card is
+already closed closes nothing else. A `~` update too thin to replace its card (fewer than six
+content words and under half the card's) is appended to that card as a dated `(~ amended …)` line
+instead. The card keeps its date, colour and probe, and previews show the newest amendment first.
+The correction lands and nothing is lost.
+
+The Stop hook reads the whole transcript every time, so a `~` or `✓` line applies once. A marker
+that an older hook (1.85 or 1.86.0) already captured is not captured again after an upgrade. If
+1.86.0 cut the note short, the stub is restored to the full text in place. When a marker does not
+do what it says, the next prompt tells the agent. A receipt left by a session that has ended goes
+to the next session that starts in the project.
+
 On every other host, capture is explicit: `brain_note` runs the same capture engine as the hooks —
 dedup, supersession, round-trip re-adoption receipts, `✓` resolve, `~` update in place, `+` skill,
 `closes:` — and stamps which agent wrote the card. A `✓` question preference ranks only candidates
@@ -789,19 +811,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.1",
   "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/marker-suffix-grammar.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/brain-evidence.mjs

@@ -80,7 +80,7 @@ function workingTreeStatus(root, relative, deadline) {
   } catch (error) { return error.status === 1 ? 'changed' : 'unverified'; }
 }
 
-export function prepareBrainEvidence({ projectRoot, evidence, verify, marker = '', text = '' } = {}) {
+export function prepareBrainEvidence({ projectRoot, evidence, verify, marker = '', text = '', deriveVerify = null } = {}) {
   const bad = error => ({ ok: false, error });
   if (marker === '✓' && (evidence !== undefined || verify !== undefined)) {
     return bad('A resolve marker archives existing evidence. To record new evidence, write a milestone with closes, or amend the card with marker ~.');
@@ -88,7 +88,15 @@ export function prepareBrainEvidence({ projectRoot, evidence, verify, marker = '
   if (verify !== undefined && (typeof verify !== 'string' || verify.length > 2000 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(verify))) {
     return bad('verify must be a string of at most 2000 characters; it is recorded, never executed.');
   }
-  if (marker === '~' && typeof verify === 'string' && !verify.trim() && /(?:^|\s)verify:\s*[^\n\s]/i.test(String(text))) {
+  // The question is "would the READER derive a verify from this text?" — so
+  // the callers pass the reader itself (klypix-format parseVerifySuffix; this
+  // module may not import it). Then "every agent verify: the tag" is not
+  // refused (the reader derives nothing) and an own-line `verify: <command>`
+  // is (the reader derives it). Without a deriver: a lowercase `verify: value`.
+  const inlineVerify = () => (typeof deriveVerify === 'function'
+    ? Boolean(deriveVerify(String(text)))
+    : /(?:^|\s)verify:\s+\S/.test(String(text)));
+  if (marker === '~' && typeof verify === 'string' && !verify.trim() && inlineVerify()) {
     return bad('To clear verification, remove the inline verify: suffix from the amended text too.');
   }
   if (evidence !== undefined && (!Array.isArray(evidence) || evidence.length > 16)) return bad('evidence must be an array of at most 16 references.');

package/src/brain-note.mjs

@@ -22,7 +22,7 @@ import fs from 'fs';
 import path from 'path';
 import { prepareBrainEvidence } from './brain-evidence.mjs';
 import { looksLikeUnfilledDraft } from './capture-gap.mjs';
-import { captureIntoBrain, tidyBrain, atomicWrite, noteToCaptureInput, formatCaptureReceipts } from './klypix-format.mjs';
+import { captureIntoBrain, tidyBrain, atomicWrite, noteToCaptureInput, formatCaptureReceipts, parseVerifySuffix } from './klypix-format.mjs';
 import { brainCaptureLockPath, withAdvisoryWriteLock } from './brain-write-lock.mjs';
 
 const MARKERS = { '': '', '?': '?', '!': '!', '✓': '✓', '~': '~', question: '?', milestone: '!', resolve: '✓', update: '~', decision: '', done: '✓' };
@@ -73,7 +73,7 @@ if (!opts.text) { console.error('brain-note: nothing to write — pass a note as
 if (!fs.existsSync(file)) { console.error(`brain-note: no brain at ${file} (run from a project with ./brain.klypix, or pass a path).`); process.exit(1); }
 
 if (looksLikeUnfilledDraft(opts.text)) { console.error('brain-note refused (brain unchanged): complete or discard the draft rationale before capturing it.'); process.exit(1); }
-const metadata = prepareBrainEvidence({ projectRoot: path.dirname(file), evidence: opts.evidence, verify: opts.verify, marker: opts.marker, text: opts.text });
+const metadata = prepareBrainEvidence({ projectRoot: path.dirname(file), evidence: opts.evidence, verify: opts.verify, marker: opts.marker, text: opts.text, deriveVerify: parseVerifySuffix });
 if (!metadata.ok) { console.error(`brain-note refused (brain unchanged): ${metadata.error}`); process.exit(1); }
 const input = noteToCaptureInput({ text: opts.text, area: opts.area, marker: opts.marker, closes: opts.closes, evidence: metadata.evidence, verify: metadata.verify, createdVia: 'cli' });
 try {
@@ -95,6 +95,10 @@ try {
     const s = res.stats || {};
     const bits = [`${s.added || 0} added`];
     for (const k of ['resolved', 'updated', 'closed', 'superseded']) if (s[k]) bits.push(`${s[k]} ${k}`);
+    // A thin ~ is appended to its card (1.86.1), and one the card already says
+    // changes nothing — neither may read as a plain "1 updated" / "0 added".
+    if (Array.isArray(s.updateAmended) && s.updateAmended.length) bits.push(`${s.updateAmended.length} appended as a dated amendment (too thin to replace its card)`);
+    if (Array.isArray(s.updateUnchanged) && s.updateUnchanged.length) bits.push(`${s.updateUnchanged.length} unchanged (the card already says it)`);
     if (s.reAdopted) bits.push(`${s.reAdopted} re-adopted`);
     if (s.linked) bits.push(`${s.linked} linked`);
     console.error(`✓ brain-note → ${path.basename(file)} (${bits.join(' · ')})`);

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;