@theglitchking/semantic-memory 1.2.2 → 1.5.0

package/dist/profile-LXUEF7TX.js

@@ -0,0 +1,20 @@
+import {
+  PROFILE_SECTIONS,
+  SPEAKER_PROFILE_PATH,
+  initSpeakerProfile,
+  readSpeakerProfile,
+  speakerProfileTemplate,
+  updateProfileSection
+} from "./chunk-7M3JZOYH.js";
+import "./chunk-WSU4QIPB.js";
+import "./chunk-S4KW7VH4.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  PROFILE_SECTIONS,
+  SPEAKER_PROFILE_PATH,
+  initSpeakerProfile,
+  readSpeakerProfile,
+  speakerProfileTemplate,
+  updateProfileSection
+};
+//# sourceMappingURL=profile-LXUEF7TX.js.map

package/dist/profile-LXUEF7TX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{schema-F3RTY6SQ.js → schema-ATFCLC6Y.js}

@@ -2,11 +2,11 @@ import {
   installDefaultSchema,
   loadSchema,
   validateNote
-} from "./chunk-E2Z4J4MK.js";
+} from "./chunk-OWZWMB4P.js";
 import "./chunk-PZ5AY32C.js";
 export {
   installDefaultSchema,
   loadSchema,
   validateNote
 };
-//# sourceMappingURL=schema-F3RTY6SQ.js.map
+//# sourceMappingURL=schema-ATFCLC6Y.js.map

package/dist/schema-ATFCLC6Y.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{search-27WYAI24.js → search-AHKEFI2B.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-25EIQWXL.js";
 import {
   Indexer
-} from "./chunk-HODDRXJK.js";
+} from "./chunk-V45NJIHI.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/cli/search.ts
@@ -199,4 +199,4 @@ function extractKeywords(query) {
 export {
   runSearch
 };
-//# sourceMappingURL=search-27WYAI24.js.map
+//# sourceMappingURL=search-AHKEFI2B.js.map

package/dist/telemetry-GB2TEHVE.js

@@ -0,0 +1,21 @@
+import {
+  appendEvent,
+  computeSelectionStats,
+  readSelectionLog,
+  recordSearchForCorrelation,
+  selectionLogPath,
+  telemetryEnabled,
+  wasRecentlySearched
+} from "./chunk-NTYYS53O.js";
+import "./chunk-S4KW7VH4.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  appendEvent,
+  computeSelectionStats,
+  readSelectionLog,
+  recordSearchForCorrelation,
+  selectionLogPath,
+  telemetryEnabled,
+  wasRecentlySearched
+};
+//# sourceMappingURL=telemetry-GB2TEHVE.js.map

package/dist/telemetry-GB2TEHVE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/hooks/vault-context.js

@@ -11,7 +11,7 @@
 // Fails open: any error logs to stderr and emits an empty additionalContext.
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import { join, resolve, basename, dirname } from "node:path";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
@@ -132,13 +132,42 @@ function queryRecentLogViaCli(cliBin, vaultPath, sinceIso, limit = 20) {
   }
 }
 
+// Injection hygiene (v1.4 Phase 2). The <vault-context> block is per-prompt
+// overhead, so it earns its tokens or stays out:
+//  - score gate: if the best hit is weak, inject nothing (a "thanks"/"proceed"
+//    prompt shouldn't drag six 0.2-score hits into context). Tunable via
+//    SEMANTIC_MEMORY_INJECT_MIN_SCORE.
+//  - dedup by basename: collapse archive/x.md + archive/pre-restructure/x.md to
+//    one slot (keep the highest-scored), so retired-doc twins stop burning slots.
+//  - top-3, not top-6.
+//  - one compact instructions line — the full cite-or-deflect rule lives once in
+//    CLAUDE.md and the vault-first skill, not repeated in full every prompt.
+const INJECT_MIN_SCORE = Number(process.env.SEMANTIC_MEMORY_INJECT_MIN_SCORE) || 0.35;
+
+function dedupeByBasename(hits) {
+  const seen = new Set();
+  const out = [];
+  for (const h of hits) {
+    const base = String(h.path || "").split("/").pop();
+    if (seen.has(base)) continue;
+    seen.add(base);
+    out.push(h);
+  }
+  return out;
+}
+
 export function formatContextBlock(source, query, hits) {
   if (!hits || hits.length === 0) return "";
+  // Score gate: skip injection entirely when nothing is strongly relevant.
+  const topScore = Math.max(...hits.map((h) => (typeof h.score === "number" ? h.score : 0)));
+  if (topScore < INJECT_MIN_SCORE) return "";
+
+  const shown = dedupeByBasename(hits).slice(0, 3);
   const lines = [];
   lines.push(`<vault-context source="${source}" query="${escapeAttr(query)}">`);
   lines.push(`The vault (semantic-memory) was proactively searched. Top hits:`);
   lines.push("");
-  for (const h of hits.slice(0, 6)) {
+  for (const h of shown) {
     const score = typeof h.score === "number" ? h.score.toFixed(2) : "";
     lines.push(`- \`${h.path}\`${score ? ` (score: ${score})` : ""}`);
     if (h.snippet) {
@@ -147,11 +176,217 @@ export function formatContextBlock(source, query, hits) {
     }
   }
   lines.push("");
-  lines.push(`Instructions: This block is injected on every prompt. Apply cite-or-deflect ONLY when the user's prompt is a project prose lookup (how/why/where does X work here, runbook/process question, gotcha or known-issue lookup). For those, read promising hits via \`mcp__semantic-vault__read_note\` and either cite the filenames or say "not in vault" and name the nearest misses. For meta/tool questions, debugging, status checks, directives ("proceed", "merge"), or conversational turns, ignore this block silently. Do NOT narrate "X unrelated" or "not in vault for this" on non-lookup prompts — that is noise, not honest deflection.`);
+  lines.push(`Instructions: Apply cite-or-deflect ONLY to project prose lookups (how/why/where does X work here) — cite the hit paths, or say "not in vault". For meta/tool/debug/status/directive/conversational prompts, ignore this block silently. Do NOT narrate "X unrelated" or "not in vault" on those.`);
   lines.push(`</vault-context>`);
   return lines.join("\n");
 }
 
+// --- Tier-1 lexicon query expansion (v1.4 Phase 6, deterministic) ---
+// Before embedding a user utterance, substitute/augment it with the canonical
+// targets of any learned alias phrases it contains, so "is the flaky thing fixed?"
+// searches as "...the flaky thing... src/core/indexer.ts". Pure string/table
+// lookup — no LLM, no spawn, reads the derived lexicon-cache.json only.
+
+function normalizePhrase(s) {
+  return String(s || "").toLowerCase().trim().replace(/\s+/g, " ");
+}
+
+function readLexiconAliases(projectRoot) {
+  try {
+    const cachePath = join(projectRoot, ".claude", ".semantic-memory", "lexicon-cache.json");
+    if (!existsSync(cachePath)) return [];
+    const data = JSON.parse(readFileSync(cachePath, "utf8"));
+    return Array.isArray(data?.aliases) ? data.aliases : [];
+  } catch {
+    return [];
+  }
+}
+
+export function expandQueryViaLexicon(projectRoot, query) {
+  const aliases = readLexiconAliases(projectRoot);
+  if (aliases.length === 0) return query;
+  const nq = normalizePhrase(query);
+  const canonicals = [];
+  for (const a of aliases) {
+    const phrases = Array.isArray(a.phrases) ? a.phrases : [];
+    if (phrases.some((p) => p && nq.includes(normalizePhrase(p)))) {
+      if (a.canonical && !canonicals.includes(a.canonical)) canonicals.push(a.canonical);
+    }
+  }
+  return canonicals.length ? `${query} ${canonicals.join(" ")}` : query;
+}
+
+// --- Two-hop retrieval (v1.5 Phase 8): utterance → entity → dossier ---
+// When the prompt names a dossier entity (or one of its aliases), inject the
+// dossier head — Purpose + Current state — FIRST, ahead of semantic hits. This is
+// the "resident expert pulls the component's file" move: entity-first, not file-first.
+// Deterministic table lookup against the derived dossier-cache.json — no LLM, no spawn.
+
+function readDossierCache(projectRoot) {
+  try {
+    const cachePath = join(projectRoot, ".claude", ".semantic-memory", "dossier-cache.json");
+    if (!existsSync(cachePath)) return [];
+    const data = JSON.parse(readFileSync(cachePath, "utf8"));
+    return Array.isArray(data?.dossiers) ? data.dossiers : [];
+  } catch {
+    return [];
+  }
+}
+
+export function resolveDossierForPrompt(projectRoot, query) {
+  const dossiers = readDossierCache(projectRoot);
+  if (dossiers.length === 0) return null;
+  const nq = normalizePhrase(query);
+  let best = null;
+  let bestLen = 0;
+  for (const d of dossiers) {
+    const keys = [d.entity, ...(Array.isArray(d.aliases) ? d.aliases : [])]
+      .map(normalizePhrase)
+      .filter(Boolean);
+    for (const k of keys) {
+      if (nq.includes(k) && k.length > bestLen) {
+        best = d;
+        bestLen = k.length;
+      }
+    }
+  }
+  return best;
+}
+
+export function formatDossierHead(dossier) {
+  if (!dossier || !dossier.path) return "";
+  const lines = [];
+  lines.push(`<vault-dossier entity="${escapeAttr(dossier.entity || "")}" path="${escapeAttr(dossier.path)}">`);
+  lines.push(`This utterance names a tracked entity. Its dossier is the first place to look:`);
+  if (dossier.purpose) lines.push(`- purpose: ${String(dossier.purpose).replace(/\s+/g, " ").slice(0, 240)}`);
+  if (dossier.current_state) lines.push(`- current state: ${String(dossier.current_state).replace(/\s+/g, " ").slice(0, 240)}`);
+  lines.push(`Read \`${dossier.path}\` (its Incident log is the fix history) before answering about ${dossier.entity}.`);
+  lines.push(`</vault-dossier>`);
+  return lines.join("\n");
+}
+
+// --- Session paging (v1.5 Phase 10): memory as the context window's swap space ---
+// SessionStart pages IN a curated digest — latest session digest, active task,
+// dossier current-states, mode — instead of a broad whole-vault semantic sweep.
+// Fewer tokens, more signal. Falls back to search when there's nothing to page in.
+
+/** Newest sessions/*.md digest note: its title + first content paragraph. */
+function readLatestSessionDigest(vaultPath) {
+  try {
+    const dir = join(vaultPath, "sessions");
+    if (!existsSync(dir)) return null;
+    const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+    if (files.length === 0) return null;
+    let newest = null;
+    let newestMs = -1;
+    for (const f of files) {
+      const p = join(dir, f);
+      try {
+        const ms = statSync(p).mtimeMs;
+        if (ms > newestMs) { newestMs = ms; newest = p; }
+      } catch { /* skip */ }
+    }
+    if (!newest) return null;
+    const raw = readFileSync(newest, "utf8");
+    const body = raw.replace(/^---[\s\S]*?---\s*/, ""); // strip frontmatter
+    const titleMatch = body.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1].trim() : basename(newest).replace(/\.md$/, "");
+    const para = body
+      .replace(/^#.*$/m, "")
+      .split(/\n\s*\n/)
+      .map((s) => s.trim())
+      .find((s) => s && !s.startsWith("#"));
+    return {
+      path: `sessions/${basename(newest)}`,
+      title,
+      head: para ? para.replace(/\s+/g, " ").slice(0, 300) : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Dossier current-state one-liners from the derived cache (capped). */
+function readDossierStates(projectRoot, cap = 6) {
+  const dossiers = readDossierCache(projectRoot);
+  return dossiers
+    .filter((d) => d && d.current_state)
+    .slice(0, cap)
+    .map((d) => ({ entity: d.entity, path: d.path, state: String(d.current_state).replace(/\s+/g, " ").slice(0, 160) }));
+}
+
+/**
+ * Build the SessionStart curated digest block. Returns "" when there's nothing
+ * durable to page in (no digest note, no dossier states, no active task) — the
+ * caller then falls back to the broad semantic search.
+ */
+function buildSessionStartDigest(projectRoot, vaultPath) {
+  const digest = readLatestSessionDigest(vaultPath);
+  const states = readDossierStates(projectRoot);
+  const session = readActiveSession(projectRoot);
+  const mode = readMode(projectRoot);
+  if (!digest && states.length === 0 && !session) return "";
+
+  const lines = [`<vault-session-digest mode="${escapeAttr(mode)}">`];
+  lines.push(`Paged in from the vault (curated — not a broad search):`);
+  if (session) {
+    lines.push(`- active task: ${String(session.task || "(unnamed)").slice(0, 160)} (session ${session.id})`);
+  }
+  if (digest) {
+    lines.push(`- last session digest \`${digest.path}\`: ${digest.head || digest.title}`);
+  }
+  if (states.length > 0) {
+    lines.push(`- tracked entities (current state):`);
+    for (const s of states) lines.push(`    · ${s.entity} — ${s.state}  \`${s.path}\``);
+  }
+  lines.push(`Read the digest or a dossier before re-deriving prior context.`);
+  lines.push(`</vault-session-digest>`);
+  return lines.join("\n");
+}
+
+// --- Speaker profile (v1.5 Phase 11): the model of THIS human ---
+// Read profile/speaker.md and inject a capped, placeholder-stripped head at
+// SessionStart, so every session starts knowing how this person communicates.
+
+function readSpeakerProfileBlock(vaultPath, maxLines = 24) {
+  try {
+    const abs = join(vaultPath, "profile", "speaker.md");
+    if (!existsSync(abs)) return "";
+    const raw = readFileSync(abs, "utf8");
+    const body = raw.replace(/^---[\s\S]*?---\s*/, "").trim();
+    const kept = [];
+    for (const line of body.split("\n")) {
+      if (/^#{1,6}\s/.test(line)) { kept.push(line.replace(/^#+\s*/, "").trim() + ":"); continue; }
+      const t = line.trim();
+      if (t === "" || /^_.*_$/.test(t)) continue; // drop placeholder prompts
+      kept.push(t);
+    }
+    // Drop trailing section labels with no content under them.
+    while (kept.length && kept[kept.length - 1].endsWith(":")) kept.pop();
+    if (kept.length === 0) return "";
+    const lines = [`<vault-speaker-profile path="profile/speaker.md">`];
+    lines.push(`How this human communicates (learned — apply, don't recite):`);
+    for (const l of kept.slice(0, maxLines)) lines.push(`  ${l}`);
+    lines.push(`</vault-speaker-profile>`);
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Stop-time session-digest instruction: draft a durable digest of this session's
+ * decisions/resolutions/task-state as a PROPOSAL (decision Q10 — automatic draft,
+ * human-reviewable, graduated via synthesize_promote). Appended to the session-close
+ * prompt so a formal session boundary always offers to file its memory.
+ */
+function formatSessionDigestPrompt(session) {
+  return [
+    "",
+    `After finishing, page this session's durable state to the vault: call \`mcp__semantic-vault__synthesize_note\` with \`from_session: true\`, \`proposal: true\`, \`proposal_subdir: "sessions"\`, and \`suggested_path: "sessions/${session.id}.md"\` — capturing decisions made, resolutions (symptom→cause→fix), and remaining task state. It files as a reviewable proposal; \`synthesize_promote\` graduates it if worth keeping. This is memory paging, not busywork: next session pages it back in instead of re-deriving.`,
+  ].join("\n");
+}
+
 function escapeAttr(s) {
   return String(s).replace(/["<>&]/g, (c) => ({ '"': "&quot;", "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c]);
 }
@@ -271,6 +506,9 @@ const CAPTURE_CUES = [
   // (a/the gotcha, gotcha:, gotchas, gotcha is/was/here/with) so bare filler doesn't misfire.
   /\b(?:a|the|one|another)\s+gotcha\b|\bgotcha[:s]\b|\bgotcha (?:is|was|here|with)\b|\bworkaround\b|\bhack\b/i,
   /\bnew convention\b|\bfrom now on\b|\bgoing forward\b/i,
+  // Speaker-calibration corrections (v1.5 Phase 11): the user telling you how THEY
+  // talk — "no, when I say X I mean Y", "what I mean by X is", "I actually meant".
+  /\bwhen i say\b[\s\S]{0,40}\bi mean\b|\bwhat i mean by\b|\bi actually meant\b|\bwhen i said\b[\s\S]{0,40}\bi meant\b/i,
 ];
 
 // Cue detection must scan the user's own prose, NOT quoted machinery. Pasting
@@ -367,16 +605,25 @@ async function handleSessionStart(projectRoot, vaultPath, cliBin) {
     logMaybeModeChange(cliBin, vaultPath, priorMode, "vault-first");
   }
 
-  const query = sessionSeedQuery(projectRoot);
-  debug(`sessionstart seed query: "${query}"`);
-  const hits = runSearchCli(cliBin, ["--notes", vaultPath, "--limit", "6", query], 30_000);
+  // Phase 10: prefer a curated digest (last session digest + active task + dossier
+  // current-states) over a broad whole-vault semantic sweep. Fewer tokens, more
+  // signal. Only fall back to the seeded search when there's nothing to page in.
+  const digestBlock = buildSessionStartDigest(projectRoot, vaultPath);
+  let searchBlock = "";
+  if (!digestBlock) {
+    const query = sessionSeedQuery(projectRoot);
+    debug(`sessionstart seed query: "${query}"`);
+    const hits = runSearchCli(cliBin, ["--notes", vaultPath, "--limit", "6", query], 30_000);
+    searchBlock = hits && hits.length > 0 ? formatContextBlock("sessionstart", query, hits) : "";
+  } else {
+    debug("sessionstart: paging in curated digest (skipping broad search)");
+  }
 
   // State-delta preload — 14-day window per Phase 4.5 design.
   const sinceMs = Date.now() - 14 * 24 * 60 * 60 * 1000;
   const sinceIso = new Date(sinceMs).toISOString();
   const recentEntries = queryRecentLogViaCli(cliBin, vaultPath, sinceIso, 30);
 
-  const searchBlock = hits && hits.length > 0 ? formatContextBlock("sessionstart", query, hits) : "";
   const stateBlock = formatStateDeltaBlock(sinceIso, recentEntries);
 
   // Phase 8 (drift detection): inline fast-tier check. Hard requirements: <100ms total,
@@ -387,7 +634,9 @@ async function handleSessionStart(projectRoot, vaultPath, cliBin) {
     return "";
   });
 
-  const parts = [driftBlock, stateBlock, searchBlock].filter(Boolean);
+  const profileBlock = readSpeakerProfileBlock(vaultPath);
+
+  const parts = [driftBlock, profileBlock, stateBlock, digestBlock, searchBlock].filter(Boolean);
   emit("SessionStart", parts.join("\n\n"));
 }
 
@@ -572,6 +821,7 @@ async function handleStop(projectRoot) {
     } else {
       lines.push(`Before ending: either run \`mcp__semantic-vault__session_run\` with at least one verification command (tests/lint), or call \`mcp__semantic-vault__session_finish\` with \`verified: false\` and a \`reason\` waiving verification (e.g. doc-only edits). session_finish refuses without one of these paths.`);
     }
+    lines.push(formatSessionDigestPrompt(session));
     lines.push(`</vault-session-close>`);
     resetCapturePending(projectRoot);
     emitStop(lines.join("\n"), true);
@@ -627,6 +877,7 @@ async function handleStop(projectRoot) {
   }
   lines.push("");
   lines.push(`Before ending: for each still-unsynthesized item above, either call \`mcp__semantic-vault__synthesize_note\` to file it with provenance, or explicitly acknowledge that it was already captured / not worth capturing.`);
+  lines.push(`If a cue is a speaker correction (how the user talks — "when I say X I mean Y"), update the speaker profile via \`mcp__semantic-vault__manage_profile\` (action:update_section) instead of synthesize_note.`);
   lines.push(`</vault-capture-prompt>`);
   resetCapturePending(projectRoot);
   emitStop(lines.join("\n"), true);
@@ -654,18 +905,26 @@ async function handlePrompt(projectRoot, vaultPath, cliBin, input) {
     emit("UserPromptSubmit", "");
     return;
   }
-  const hits = runSearchCli(cliBin, ["--notes", vaultPath, "--limit", "8", prompt], 30_000);
+  // Tier-1 lexicon expansion: search with the alias-expanded query, but keep the
+  // original prompt for display in the block.
+  const searchQuery = expandQueryViaLexicon(projectRoot, prompt);
+  const hits = runSearchCli(cliBin, ["--notes", vaultPath, "--limit", "8", searchQuery], 30_000);
   state.recent = [fp, ...recent].slice(0, 10);
   saveFingerprints(projectRoot, state);
   const cue = detectCaptureCue(prompt);
   if (cue) {
     addCapturePending(projectRoot, prompt, cue);
   }
+  // Two-hop: if the utterance names a tracked entity, lead with its dossier head.
+  const dossier = resolveDossierForPrompt(projectRoot, prompt);
+  const dossierHead = dossier ? formatDossierHead(dossier) : "";
   if (!hits || hits.length === 0) {
-    emit("UserPromptSubmit", "");
+    // Even with no semantic hits, a resolved dossier is worth injecting.
+    emit("UserPromptSubmit", dossierHead);
     return;
   }
-  const block = formatContextBlock("prompt", prompt.slice(0, 120), hits);
+  const searchBlock = formatContextBlock("prompt", prompt.slice(0, 120), hits);
+  const block = [dossierHead, searchBlock].filter(Boolean).join("\n");
   emit("UserPromptSubmit", block);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/semantic-memory",
-  "version": "1.2.2",
+  "version": "1.5.0",
   "description": "Unified memory-layer plugin for Claude Code. One MCP server, multiple typed corpora (vault, code, plans, docs, research, project-map), unified cross-corpus knowledge graph, conditional tool registration, in-process drift detection, and human↔code translation. Rebrand of @theglitchking/semantic-sidekick at v1.0 — see CHANGELOG for migration.",
   "type": "module",
   "main": "./dist/core/index.js",
@@ -36,6 +36,7 @@
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
+    "eval": "vitest run test/retrieval-eval",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/link-skills.js"

package/skills/vault-first/SKILL.md

@@ -65,6 +65,24 @@ Do not silently pivot to web search, do not guess from training data, and do not
 
 If you had to answer from outside the vault (web search, training knowledge, the user telling you something new), offer once to file a note: *"Worth capturing this in the vault as `gotchas/foo.md`?"* — then let the user decide. This is the ingest loop's entry point; don't force it, but don't skip it.
 
+### 5. Propose an alias when you resolve the user's phrasing to a concrete artifact (v1.4 lexicon)
+
+When the user refers to something in *their own words* — "the flaky thing", "the deploy dance", "that indexer race" — and you resolve it to a concrete artifact (a note path or code symbol), that resolution is worth keeping so the next occurrence routes in one hop. **Propose, don't auto-add** (a wrong alias silently misroutes every future query with that phrase):
+
+- Offer once: *"Want me to remember that \"the flaky thing\" → `src/core/indexer.ts`? (manage_lexicon add)"*
+- On confirmation, call `manage_lexicon({action:"add", canonical:"src/core/indexer.ts", phrases:["the flaky thing"]})`. Repeat observations bump `evidence_count` automatically.
+- Only propose when you actually resolved a *vague* reference to a *specific* artifact this turn — not for literal names the user already spelled out.
+- Scan the user's own prose only; never mine phrases from pasted tool output or quoted machinery.
+- If `lint_vault({checks:["alias_conflicts"]})` flags a phrase mapping to two targets, surface it and ask the user which one wins — don't guess.
+
+### 6. Rewrite a terse utterance before deciding the vault has nothing (v1.4, Tier 2)
+
+The UserPromptSubmit hook already expands your query through the learned lexicon (Tier 1, deterministic). But when the utterance is terse or indexical — "it's doing the thing again", "did that work?", "is it fixed?" — the injected hits may still be weak because a two-word query has little to match expository note prose. Before concluding "not in vault":
+
+- Rewrite the utterance using the current conversation's subject (what "it"/"that"/"the thing" refers to) into a concrete query, then re-search once via `search_hybrid`.
+- Cap it at one rewrite round — don't loop searching for an exact match that doesn't exist (that's the bounded-rounds lesson).
+- If the rewrite resolves the referent to a concrete artifact, that's a §5 alias-capture opportunity — offer it.
+
 ## Boundary conditions — when vault-first does NOT fire
 
 - **Code-symbol lookups.** "Where is `parseAuth` defined?" → `Grep`. "Show me the `User` model." → `Glob`. If the answer is a file + line, the vault is the wrong tool.

package/dist/chunk-CAN2GWUG.js

@@ -1,88 +0,0 @@
-import {
-  loadSchema,
-  validateNote
-} from "./chunk-E2Z4J4MK.js";
-
-// src/core/lint.ts
-import { readFile } from "fs/promises";
-import { basename, join } from "path";
-import { glob } from "glob";
-import matter from "gray-matter";
-async function lintVault(notesPath, opts = {}) {
-  const schema = opts.schemaOverride ?? await loadSchema(notesPath);
-  const files = await glob(opts.pathGlob ?? "**/*.md", {
-    cwd: notesPath,
-    ignore: ["node_modules/**", ".semantic-sidekick-index/**", "vault.schema.yml"]
-  });
-  const findings = [];
-  const knownNames = /* @__PURE__ */ new Set();
-  const rawByPath = /* @__PURE__ */ new Map();
-  for (const rel of files) {
-    try {
-      const raw = await readFile(join(notesPath, rel), "utf-8");
-      rawByPath.set(rel, raw);
-      knownNames.add(basename(rel).replace(/\.md$/, ""));
-    } catch {
-    }
-  }
-  for (const [rel, raw] of rawByPath) {
-    findings.push(...validateNote(rel, raw, schema, { todayIso: opts.todayIso }));
-    findings.push(...findBrokenLinks(rel, raw, knownNames));
-  }
-  const byRule = {
-    schema_violations: findings.filter((f) => f.rule === "schema_violations"),
-    missing_provenance: findings.filter((f) => f.rule === "missing_provenance"),
-    stale: findings.filter((f) => f.rule === "stale"),
-    broken_links: findings.filter((f) => f.rule === "broken_links")
-  };
-  const errors = findings.filter((f) => f.severity === "error").length;
-  const warnings = findings.filter((f) => f.severity === "warn").length;
-  return {
-    schemaPath: join(notesPath, "vault.schema.yml"),
-    findings,
-    byRule,
-    counts: { errors, warnings, filesLinted: files.length }
-  };
-}
-function findBrokenLinks(relPath, rawFileContent, knownNames) {
-  const { content } = matter(rawFileContent);
-  const findings = [];
-  const stripped = content.replace(/```[\s\S]*?```/g, "").replace(/`[^`]+`/g, "");
-  const re = /\[\[([^\]\|]+)(?:\|[^\]]+)?\]\]/g;
-  const seen = /* @__PURE__ */ new Set();
-  let m;
-  while ((m = re.exec(stripped)) !== null) {
-    const target = m[1].trim().split("#")[0].split("/").pop().replace(/\.md$/, "");
-    if (seen.has(target)) continue;
-    seen.add(target);
-    if (!knownNames.has(target)) {
-      findings.push({
-        path: relPath,
-        rule: "broken_links",
-        severity: "warn",
-        message: `wikilink [[${target}]] has no matching note`
-      });
-    }
-  }
-  return findings;
-}
-function formatLintReport(report, opts = {}) {
-  const target = opts.rule ? report.byRule[opts.rule] : report.findings;
-  if (target.length === 0) {
-    return `clean: 0 findings across ${report.counts.filesLinted} files`;
-  }
-  const lines = [
-    `${target.length} finding${target.length === 1 ? "" : "s"} (errors=${report.counts.errors}, warnings=${report.counts.warnings}, files=${report.counts.filesLinted})`,
-    ""
-  ];
-  for (const f of target) {
-    lines.push(`[${f.severity}] ${f.rule}: ${f.path} \u2014 ${f.message}`);
-  }
-  return lines.join("\n");
-}
-
-export {
-  lintVault,
-  formatLintReport
-};
-//# sourceMappingURL=chunk-CAN2GWUG.js.map

package/dist/chunk-CAN2GWUG.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/lint.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { basename, join } from \"node:path\";\nimport { glob } from \"glob\";\nimport matter from \"gray-matter\";\nimport { loadSchema, validateNote, type LintFinding, type VaultSchema } from \"./schema.js\";\n\nexport interface LintReport {\n  schemaPath: string;\n  findings: LintFinding[];\n  byRule: {\n    schema_violations: LintFinding[];\n    missing_provenance: LintFinding[];\n    stale: LintFinding[];\n    broken_links: LintFinding[];\n  };\n  counts: {\n    errors: number;\n    warnings: number;\n    filesLinted: number;\n  };\n}\n\nexport async function lintVault(\n  notesPath: string,\n  opts: { pathGlob?: string; schemaOverride?: VaultSchema; todayIso?: string } = {}\n): Promise<LintReport> {\n  const schema = opts.schemaOverride ?? (await loadSchema(notesPath));\n  const files = await glob(opts.pathGlob ?? \"**/*.md\", {\n    cwd: notesPath,\n    ignore: [\"node_modules/**\", \".semantic-sidekick-index/**\", \"vault.schema.yml\"],\n  });\n\n  const findings: LintFinding[] = [];\n  // Build known-note set first, to make broken-link detection O(1) per link.\n  const knownNames = new Set<string>();\n  const rawByPath = new Map<string, string>();\n  for (const rel of files) {\n    try {\n      const raw = await readFile(join(notesPath, rel), \"utf-8\");\n      rawByPath.set(rel, raw);\n      // Wikilink names match on basename-without-ext (obsidian-style)\n      knownNames.add(basename(rel).replace(/\\.md$/, \"\"));\n    } catch {\n      /* skip */\n    }\n  }\n\n  for (const [rel, raw] of rawByPath) {\n    findings.push(...validateNote(rel, raw, schema, { todayIso: opts.todayIso }));\n    findings.push(...findBrokenLinks(rel, raw, knownNames));\n  }\n\n  const byRule = {\n    schema_violations: findings.filter((f) => f.rule === \"schema_violations\"),\n    missing_provenance: findings.filter((f) => f.rule === \"missing_provenance\"),\n    stale: findings.filter((f) => f.rule === \"stale\"),\n    broken_links: findings.filter((f) => f.rule === \"broken_links\"),\n  };\n  const errors = findings.filter((f) => f.severity === \"error\").length;\n  const warnings = findings.filter((f) => f.severity === \"warn\").length;\n\n  return {\n    schemaPath: join(notesPath, \"vault.schema.yml\"),\n    findings,\n    byRule,\n    counts: { errors, warnings, filesLinted: files.length },\n  };\n}\n\nfunction findBrokenLinks(\n  relPath: string,\n  rawFileContent: string,\n  knownNames: Set<string>\n): LintFinding[] {\n  const { content } = matter(rawFileContent);\n  const findings: LintFinding[] = [];\n  // Match [[target]] and [[target|alias]] — skip fenced code and inline code.\n  const stripped = content\n    .replace(/```[\\s\\S]*?```/g, \"\")\n    .replace(/`[^`]+`/g, \"\");\n  const re = /\\[\\[([^\\]\\|]+)(?:\\|[^\\]]+)?\\]\\]/g;\n  const seen = new Set<string>();\n  let m: RegExpExecArray | null;\n  while ((m = re.exec(stripped)) !== null) {\n    const target = m[1].trim().split(\"#\")[0].split(\"/\").pop()!.replace(/\\.md$/, \"\");\n    if (seen.has(target)) continue;\n    seen.add(target);\n    if (!knownNames.has(target)) {\n      findings.push({\n        path: relPath,\n        rule: \"broken_links\",\n        severity: \"warn\",\n        message: `wikilink [[${target}]] has no matching note`,\n      });\n    }\n  }\n  return findings;\n}\n\nexport function formatLintReport(report: LintReport, opts: { rule?: keyof LintReport[\"byRule\"] } = {}): string {\n  const target = opts.rule ? report.byRule[opts.rule] : report.findings;\n  if (target.length === 0) {\n    return `clean: 0 findings across ${report.counts.filesLinted} files`;\n  }\n  const lines = [\n    `${target.length} finding${target.length === 1 ? \"\" : \"s\"} (errors=${report.counts.errors}, warnings=${report.counts.warnings}, files=${report.counts.filesLinted})`,\n    \"\",\n  ];\n  for (const f of target) {\n    lines.push(`[${f.severity}] ${f.rule}: ${f.path} — ${f.message}`);\n  }\n  return lines.join(\"\\n\");\n}\n"],"mappings":"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","names":[]}