@hiveai/mcp 0.10.5 → 0.10.9

package/dist/index.js

@@ -1417,9 +1417,8 @@ async function memSessionEnd(input, ctx) {
 }
 
 // src/tools/get-briefing.ts
-import { readFile as readFile3, readdir as readdir3, writeFile as writeFile11 } from "fs/promises";
-import { existsSync as existsSync18 } from "fs";
-import path9 from "path";
+import { readFile as readFile4, writeFile as writeFile11 } from "fs/promises";
+import { existsSync as existsSync19 } from "fs";
 import {
   allocateBudget,
   DEFAULT_AUTO_PROMOTE_RULE,
@@ -1428,11 +1427,9 @@ import {
   extractActionsBriefBody,
   getUsage as getUsage5,
   inferModulesFromPaths as inferModulesFromPaths2,
-  isGlobPath,
-  isRetiredMemory,
   isAutoPromoteEligible,
   isDecaying,
-  isStackPackSeed,
+  isRetiredMemory,
   literalMatchesAllTokens as literalMatchesAllTokens2,
   literalMatchesAnyToken as literalMatchesAnyToken2,
   loadCodeMap,
@@ -1440,7 +1437,6 @@ import {
   loadMemoriesFromDir as loadMemoriesFromDir13,
   loadUsageIndex as loadUsageIndex7,
   memoryMatchesAnchorPaths as memoryMatchesAnchorPaths2,
-  pathsOverlap,
   queryCodeMap,
   resolveBriefingBudget,
   serializeMemory as serializeMemory9,
@@ -1452,6 +1448,152 @@ import {
   writeBriefingMarker
 } from "@hiveai/core";
 import { z as z17 } from "zod";
+
+// src/tools/briefing-helpers.ts
+import { readdir as readdir3, readFile as readFile3 } from "fs/promises";
+import { existsSync as existsSync18 } from "fs";
+import path9 from "path";
+import { isGlobPath, isStackPackSeed, pathsOverlap } from "@hiveai/core";
+function compactSummary(body) {
+  for (const line of body.split("\n")) {
+    const trimmed = line.replace(/^#+\s*/, "").trim();
+    if (trimmed.length > 0) return trimmed.slice(0, 120);
+  }
+  return body.slice(0, 120);
+}
+function classifyMemoryPriority(memory, loaded, inputFiles, inputSymbols) {
+  const fm = loaded?.memory.frontmatter;
+  const directAnchor = Boolean(
+    fm && inputFiles.length > 0 && fm.anchor.paths.some((p) => inputFiles.some((file) => pathsOverlap(p, file)))
+  );
+  const directSymbol = Boolean(
+    fm && inputSymbols.length > 0 && fm.anchor.symbols.some(
+      (sym) => inputSymbols.some((wanted) => wanted.toLowerCase() === sym.toLowerCase())
+    )
+  );
+  const strongSemantic = (memory.semantic_score ?? 0) >= 0.65;
+  const usefulSemantic = (memory.semantic_score ?? 0) >= 0.35;
+  if (fm?.requires_human_approval || directAnchor || directSymbol || memory.type === "attempt" && (memory.match_quality === "exact" || strongSemantic) || memory.type === "skill" && (memory.match_quality === "exact" || strongSemantic)) {
+    return "must_read";
+  }
+  if (isStackPackSeed(fm)) {
+    return "background";
+  }
+  if (memory.type === "skill" || memory.reasons.includes("module") || memory.reasons.includes("domain") || memory.match_quality === "exact" || usefulSemantic) {
+    return "useful";
+  }
+  return "background";
+}
+function priorityRank(priority) {
+  return priority === "must_read" ? 3 : priority === "useful" ? 2 : 1;
+}
+function classifyBriefingQuality(memories, context) {
+  const mustRead = memories.filter((m) => m.priority === "must_read").length;
+  const useful = memories.filter((m) => m.priority === "useful").length;
+  const background = memories.filter((m) => m.priority === "background").length;
+  const weakSemantic = memories.filter(
+    (m) => m.reasons.length === 1 && m.reasons.includes("semantic") && (m.semantic_score ?? 0) > 0 && (m.semantic_score ?? 0) < 0.35
+  ).length;
+  const reasons = [];
+  if (memories.length === 0) reasons.push("no memories matched the task or files");
+  if (context.isTemplateContext && !context.autoContextGenerated) reasons.push("project context is still a template");
+  if (!context.hasLastSession) reasons.push("no previous session recap");
+  if (mustRead > 0) reasons.push(`${mustRead} must_read memor${mustRead === 1 ? "y" : "ies"} matched directly`);
+  if (useful > 0) reasons.push(`${useful} useful memor${useful === 1 ? "y" : "ies"} matched`);
+  if (background > useful + mustRead && background > 2) reasons.push(`${background} background memories dominate the result`);
+  if (weakSemantic > 0) reasons.push(`${weakSemantic} weak semantic-only match${weakSemantic === 1 ? "" : "es"}`);
+  if (context.searchMode === "literal_fallback") reasons.push("semantic index unavailable or empty; literal fallback used");
+  if (memories.length === 0 || mustRead === 0 && useful === 0) {
+    return { level: "thin", reasons };
+  }
+  if (background > useful + mustRead && background > 2) {
+    return { level: "noisy", reasons };
+  }
+  return { level: "strong", reasons };
+}
+function explainWhySurfaced(memory, loaded, inputFiles, inferredModules) {
+  const why = [];
+  const fm = loaded?.memory.frontmatter;
+  if (memory.reasons.includes("anchor") && fm) {
+    const matching = fm.anchor.paths.filter(
+      (p) => inputFiles.length === 0 || inputFiles.some((file) => pathsOverlap(p, file))
+    );
+    if (matching.length > 0) {
+      const exact = matching.filter(
+        (p) => !isGlobPath(p) && inputFiles.some((file) => p === file || pathsOverlap(p, file))
+      );
+      const glob = matching.filter((p) => isGlobPath(p));
+      if (exact.length > 0) {
+        why.push(`Exact/file anchor match: ${exact.slice(0, 4).join(", ")}`);
+      }
+      if (glob.length > 0) {
+        why.push(`Glob anchor match: ${glob.slice(0, 4).join(", ")}`);
+      }
+      if (exact.length === 0 && glob.length === 0) {
+        why.push(`Anchored to touched path${matching.length === 1 ? "" : "s"}: ${matching.slice(0, 4).join(", ")}`);
+      }
+    } else if (fm.anchor.paths.length > 0) {
+      why.push(`Pulled by related anchor: ${fm.anchor.paths.slice(0, 4).join(", ")}`);
+    }
+    if (fm.anchor.symbols.length > 0) {
+      why.push(`Anchor symbol${fm.anchor.symbols.length === 1 ? "" : "s"}: ${fm.anchor.symbols.slice(0, 4).join(", ")}`);
+    }
+  }
+  if (memory.reasons.includes("symbol") && fm) {
+    why.push(`Explicit symbol match: ${fm.anchor.symbols.slice(0, 4).join(", ")}`);
+  }
+  if (memory.reasons.includes("module")) {
+    const moduleHints = [
+      ...memory.module ? [memory.module] : [],
+      ...memory.tags.filter((tag) => inferredModules.includes(tag))
+    ];
+    const shown = moduleHints.length > 0 ? [...new Set(moduleHints)].join(", ") : inferredModules.join(", ");
+    why.push(shown ? `Matched inferred module/tag: ${shown}` : "Matched inferred module context.");
+  }
+  if (memory.reasons.includes("domain")) {
+    why.push("Matched inferred domain from the target file paths.");
+  }
+  if (memory.reasons.includes("semantic")) {
+    const score = memory.semantic_score !== void 0 ? ` score=${Math.round(memory.semantic_score * 100) / 100}` : "";
+    why.push(`${memory.match_quality === "exact" ? "Literal task match" : "Semantic/task relevance"}${score}.`);
+  }
+  why.push(`Confidence: ${memory.confidence}; read ${memory.read_count} time${memory.read_count === 1 ? "" : "s"}.`);
+  if (memory.type === "attempt") why.push("Failed-approach record; read before repeating the same path.");
+  if (memory.type === "skill") why.push("Skill (reusable procedure/playbook) \u2014 follow the steps described when doing this type of task.");
+  if (memory.status === "proposed" || memory.status === "draft") {
+    why.push("Unvalidated record; use cautiously or ask a human before treating it as policy.");
+  }
+  return why;
+}
+async function trySemanticHits(ctx, task, limit) {
+  let mod;
+  try {
+    mod = await import("@hiveai/embeddings");
+  } catch {
+    return null;
+  }
+  const result = await mod.semanticSearch(ctx.paths, task, { limit });
+  if (!result) return null;
+  return result.hits.map((h) => ({ id: h.id, score: h.score }));
+}
+async function loadModuleContexts2(ctx, modules) {
+  if (modules.length === 0) return [];
+  if (!existsSync18(ctx.paths.modulesContextDir)) return [];
+  const available = new Set(
+    (await readdir3(ctx.paths.modulesContextDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name)
+  );
+  const out = [];
+  for (const m of modules) {
+    if (!available.has(m)) continue;
+    const file = path9.join(ctx.paths.modulesContextDir, m, "context.md");
+    if (existsSync18(file)) {
+      out.push({ name: m, content: await readFile3(file, "utf8") });
+    }
+  }
+  return out;
+}
+
+// src/tools/get-briefing.ts
 var GetBriefingInputSchema = {
   task: z17.string().optional().describe(
     "What you are about to do, in 1\u20132 sentences. Used to rank relevant memories semantically."
@@ -1497,7 +1639,7 @@ async function getBriefing(input, ctx) {
   let usage = { version: 1, updated_at: "", by_id: {} };
   let byId = /* @__PURE__ */ new Map();
   let lastSession;
-  if (existsSync18(ctx.paths.memoriesDir)) {
+  if (existsSync19(ctx.paths.memoriesDir)) {
     const allLoaded = await loadMemoriesFromDir13(ctx.paths.memoriesDir);
     const recaps = allLoaded.filter(({ memory }) => memory.frontmatter.type === "session_recap").sort(
       (a, b) => new Date(b.memory.frontmatter.created_at).getTime() - new Date(a.memory.frontmatter.created_at).getTime()
@@ -1582,34 +1724,25 @@ async function getBriefing(input, ctx) {
     if (input.task) {
       const tokens = tokenizeQuery2(input.task);
       const andHits = allMemories.filter((m) => literalMatchesAllTokens2(m.memory, tokens));
-      for (const loaded of andHits) {
-        addOrUpdate(loaded, "semantic", void 0, "exact");
-      }
+      for (const loaded of andHits) addOrUpdate(loaded, "semantic", void 0, "exact");
       if (andHits.length === 0 && tokens.length > 1) {
         for (const loaded of allMemories) {
-          if (literalMatchesAnyToken2(loaded.memory, tokens)) {
-            addOrUpdate(loaded, "semantic", void 0, "partial");
-          }
+          if (literalMatchesAnyToken2(loaded.memory, tokens)) addOrUpdate(loaded, "semantic", void 0, "partial");
         }
       }
       if (semanticHits) {
         for (const hit of semanticHits) {
-          if (hit.score < input.min_semantic_score) {
-            const existing = seen.get(hit.id);
-            if (!existing) continue;
-          }
+          if (hit.score < input.min_semantic_score && !seen.has(hit.id)) continue;
           const loaded = byId.get(hit.id);
           if (loaded) addOrUpdate(loaded, "semantic", hit.score, "semantic");
         }
       }
     }
     const ranked = [...seen.values()].sort((a, b) => {
-      const priorityScore = (m) => priorityRank(classifyMemoryPriority(m, byId.get(m.id), input.files, input.symbols));
-      const reasonScore = (m) => (m.type === "attempt" ? 3 : 0) + // attempt = negative knowledge, surface first to prevent repeating mistakes
-      (m.reasons.includes("anchor") ? 4 : 0) + (m.reasons.includes("symbol") ? 4 : 0) + (m.reasons.includes("module") ? 2 : 0) + (m.reasons.includes("semantic") ? 2 : 0) + (m.reasons.includes("domain") ? 1 : 0);
+      const reasonScore = (m) => (m.type === "attempt" ? 3 : 0) + (m.reasons.includes("anchor") ? 4 : 0) + (m.reasons.includes("symbol") ? 4 : 0) + (m.reasons.includes("module") ? 2 : 0) + (m.reasons.includes("semantic") ? 2 : 0) + (m.reasons.includes("domain") ? 1 : 0);
       const confidenceScore = (m) => m.confidence === "authoritative" ? 4 : m.confidence === "trusted" ? 3 : m.confidence === "low" ? 1 : m.confidence === "stale" ? -2 : 0;
-      const sa = priorityScore(a) * 100 + reasonScore(a) + confidenceScore(a) + (a.semantic_score ?? 0);
-      const sb = priorityScore(b) * 100 + reasonScore(b) + confidenceScore(b) + (b.semantic_score ?? 0);
+      const sa = priorityRank(classifyMemoryPriority(a, byId.get(a.id), input.files, input.symbols)) * 100 + reasonScore(a) + confidenceScore(a) + (a.semantic_score ?? 0);
+      const sb = priorityRank(classifyMemoryPriority(b, byId.get(b.id), input.files, input.symbols)) * 100 + reasonScore(b) + confidenceScore(b) + (b.semantic_score ?? 0);
       return sb - sa;
     });
     for (const mem of ranked.slice(0, briefingMaxMemories)) {
@@ -1638,11 +1771,7 @@ async function getBriefing(input, ctx) {
         if (!isAutoPromoteEligible(loaded.memory.frontmatter, u, rule)) continue;
         const newFm = { ...loaded.memory.frontmatter, status: "validated" };
         try {
-          await writeFile11(
-            loaded.filePath,
-            serializeMemory9({ frontmatter: newFm, body: loaded.memory.body }),
-            "utf8"
-          );
+          await writeFile11(loaded.filePath, serializeMemory9({ frontmatter: newFm, body: loaded.memory.body }), "utf8");
           m.status = "validated";
           m.confidence = "trusted";
         } catch {
@@ -1650,12 +1779,12 @@ async function getBriefing(input, ctx) {
       }
     }
   }
-  const projectContextRaw = input.include_project_context && existsSync18(ctx.paths.projectContext) ? await readFile3(ctx.paths.projectContext, "utf8") : "";
+  const projectContextRaw = input.include_project_context && existsSync19(ctx.paths.projectContext) ? await readFile4(ctx.paths.projectContext, "utf8") : "";
   const isTemplateContext = projectContextRaw.includes("TODO \u2014 high-level overview") || projectContextRaw.includes("Generated by `haive init`");
   const setupWarnings = [];
   let autoContextGenerated = false;
   let projectContext = isTemplateContext ? "" : projectContextRaw;
-  if ((isTemplateContext || !existsSync18(ctx.paths.projectContext)) && input.include_project_context) {
+  if ((isTemplateContext || !existsSync19(ctx.paths.projectContext)) && input.include_project_context) {
     const haiveConfig = await loadConfig3(ctx.paths);
     if (haiveConfig.autoContext) {
       const codeMap = await loadCodeMap(ctx.paths);
@@ -1691,15 +1820,9 @@ async function getBriefing(input, ctx) {
         );
       }
     } else {
-      if (isTemplateContext) {
-        setupWarnings.push(
-          "project-context.md still contains the default template. Invoke the bootstrap_project MCP prompt to auto-fill it from your codebase. Until then, get_briefing returns no project context."
-        );
-      } else {
-        setupWarnings.push(
-          "No project-context.md found. Run `haive init` then invoke the bootstrap_project MCP prompt."
-        );
-      }
+      setupWarnings.push(
+        isTemplateContext ? "project-context.md still contains the default template. Invoke the bootstrap_project MCP prompt to auto-fill it from your codebase. Until then, get_briefing returns no project context." : "No project-context.md found. Run `haive init` then invoke the bootstrap_project MCP prompt."
+      );
     }
   }
   const moduleContents = briefingIncludeModules ? await loadModuleContexts2(ctx, inferred) : [];
@@ -1762,10 +1885,7 @@ ${m.content}`).join("\n\n---\n\n"),
     const createdAt = loaded?.memory.frontmatter.created_at ?? (/* @__PURE__ */ new Date()).toISOString();
     if (isDecaying(u, createdAt)) decayWarnings.push(m.id);
   }
-  const formattedMemories = input.format === "compact" ? trimmedMemories.map((m) => ({ ...m, body: compactSummary(m.body) })) : input.format === "actions" ? trimmedMemories.map((m) => ({
-    ...m,
-    body: extractActionsBriefBody(m.body)
-  })) : trimmedMemories;
+  const formattedMemories = input.format === "compact" ? trimmedMemories.map((m) => ({ ...m, body: compactSummary(m.body) })) : input.format === "actions" ? trimmedMemories.map((m) => ({ ...m, body: extractActionsBriefBody(m.body) })) : trimmedMemories;
   const outputMemories = formattedMemories.map((m) => ({
     ...m,
     priority: classifyMemoryPriority(m, byId.get(m.id), input.files, input.symbols),
@@ -1780,8 +1900,7 @@ ${m.content}`).join("\n\n---\n\n"),
   let symbolLocations;
   const symbolsToLookup = new Set(input.symbols);
   for (const m of outputMemories) {
-    const loaded = byId.get(m.id);
-    for (const sym of loaded?.memory.frontmatter.anchor.symbols ?? []) {
+    for (const sym of byId.get(m.id)?.memory.frontmatter.anchor.symbols ?? []) {
       symbolsToLookup.add(sym);
     }
   }
@@ -1809,41 +1928,37 @@ ${m.content}`).join("\n\n---\n\n"),
     }
   }
   const actionRequired = [];
-  for (const m of outputMemories) {
-    const loaded = byId.get(m.id);
-    if (!loaded?.memory.frontmatter.requires_human_approval) continue;
-    const bodyLines = loaded.memory.body.split("\n");
+  const extractActionItem = (id, body) => {
+    const bodyLines = body.split("\n");
     const quoteBlock = bodyLines.filter((l) => l.startsWith("> ")).map((l) => l.slice(2)).join(" ").replace(/^\*«\s*/, "").replace(/\s*»\*$/, "").trim();
     const headingLine = bodyLines.find((l) => l.startsWith("## "));
-    const summary = headingLine?.replace(/^##\s*/, "").trim() ?? m.id;
-    actionRequired.push({
-      id: m.id,
+    const summary = headingLine?.replace(/^##\s*/, "").trim() ?? id;
+    return {
+      id,
       summary,
-      developer_message: quoteBlock || `Une modification externe potentiellement incompatible a \xE9t\xE9 d\xE9tect\xE9e (${m.id}). Veux-tu que j'analyse l'impact et que je propose des mises \xE0 jour ?`
-    });
+      developer_message: quoteBlock || `Une modification externe potentiellement incompatible a \xE9t\xE9 d\xE9tect\xE9e (${id}). Veux-tu que j'analyse l'impact et que je propose des mises \xE0 jour ?`
+    };
+  };
+  for (const m of outputMemories) {
+    const loaded = byId.get(m.id);
+    if (loaded?.memory.frontmatter.requires_human_approval) {
+      actionRequired.push(extractActionItem(m.id, loaded.memory.body));
+    }
   }
-  if (existsSync18(ctx.paths.memoriesDir)) {
+  if (existsSync19(ctx.paths.memoriesDir)) {
     const allMems = await loadMemoriesFromDir13(ctx.paths.memoriesDir);
     for (const { memory } of allMems) {
       const fm = memory.frontmatter;
       if (!fm.requires_human_approval) continue;
       if (fm.status === "rejected" || fm.status === "deprecated") continue;
       if (actionRequired.some((a) => a.id === fm.id)) continue;
-      const bodyLines = memory.body.split("\n");
-      const quoteBlock = bodyLines.filter((l) => l.startsWith("> ")).map((l) => l.slice(2)).join(" ").replace(/^\*«\s*/, "").replace(/\s*»\*$/, "").trim();
-      const headingLine = bodyLines.find((l) => l.startsWith("## "));
-      const summary = headingLine?.replace(/^##\s*/, "").trim() ?? fm.id;
-      actionRequired.push({
-        id: fm.id,
-        summary,
-        developer_message: quoteBlock || `Une modification externe potentiellement incompatible a \xE9t\xE9 d\xE9tect\xE9e (${fm.id}). Veux-tu que j'analyse l'impact et que je propose des mises \xE0 jour ?`
-      });
+      actionRequired.push(extractActionItem(fm.id, memory.body));
     }
   }
   const pendingDistillFile = pendingDistillPath(ctx);
-  if (existsSync18(pendingDistillFile)) {
+  if (existsSync19(pendingDistillFile)) {
     try {
-      const raw = await readFile3(pendingDistillFile, "utf8");
+      const raw = await readFile4(pendingDistillFile, "utf8");
       const pd = JSON.parse(raw);
       const ageMs = Date.now() - new Date(pd.session_end).getTime();
       const SEVEN_DAYS = 7 * 24 * 60 * 60 * 1e3;
@@ -1870,7 +1985,7 @@ When done, call \`mem_session_end\` to acknowledge \u2014 this clears the pendin
     }
   }
   const memoriesEmpty = outputMemories.length === 0;
-  const hasMemoriesDir = existsSync18(ctx.paths.memoriesDir);
+  const hasMemoriesDir = existsSync19(ctx.paths.memoriesDir);
   const isColdStart = isTemplateContext && memoriesEmpty && !lastSession && !autoContextGenerated;
   const hasUnguessableSignal = outputMemories.some(
     (m) => (m.priority === "must_read" || m.priority === "useful") && specificityScore(m.body) >= GUESSABLE_THRESHOLD
@@ -1917,7 +2032,7 @@ When done, call \`mem_session_end\` to acknowledge \u2014 this clears the pendin
       "No team-specific policy matched these files/task \u2014 nothing here a capable model can't infer. The auto-generated project context was trimmed to keep this briefing near-zero-cost; proceed with normal Read/Grep."
     );
   }
-  if (existsSync18(ctx.paths.haiveDir)) {
+  if (existsSync19(ctx.paths.haiveDir)) {
     await writeBriefingMarker(ctx.paths, {
       sessionId: process.env.HAIVE_SESSION_ID,
       ...input.task ? { task: input.task } : {},
@@ -1965,144 +2080,6 @@ When done, call \`mem_session_end\` to acknowledge \u2014 this clears the pendin
     }
   };
 }
-function compactSummary(body) {
-  for (const line of body.split("\n")) {
-    const trimmed = line.replace(/^#+\s*/, "").trim();
-    if (trimmed.length > 0) return trimmed.slice(0, 120);
-  }
-  return body.slice(0, 120);
-}
-function classifyMemoryPriority(memory, loaded, inputFiles, inputSymbols) {
-  const fm = loaded?.memory.frontmatter;
-  const directAnchor = Boolean(
-    fm && inputFiles.length > 0 && fm.anchor.paths.some((p) => inputFiles.some((file) => pathsOverlap(p, file)))
-  );
-  const directSymbol = Boolean(
-    fm && inputSymbols.length > 0 && fm.anchor.symbols.some(
-      (sym) => inputSymbols.some((wanted) => wanted.toLowerCase() === sym.toLowerCase())
-    )
-  );
-  const strongSemantic = (memory.semantic_score ?? 0) >= 0.65;
-  const usefulSemantic = (memory.semantic_score ?? 0) >= 0.35;
-  if (fm?.requires_human_approval || directAnchor || directSymbol || memory.type === "attempt" && (memory.match_quality === "exact" || strongSemantic) || memory.type === "skill" && (memory.match_quality === "exact" || strongSemantic)) {
-    return "must_read";
-  }
-  if (isStackPackSeed(fm)) {
-    return "background";
-  }
-  if (memory.type === "skill" || memory.reasons.includes("module") || memory.reasons.includes("domain") || memory.match_quality === "exact" || usefulSemantic) {
-    return "useful";
-  }
-  return "background";
-}
-function priorityRank(priority) {
-  return priority === "must_read" ? 3 : priority === "useful" ? 2 : 1;
-}
-function classifyBriefingQuality(memories, context) {
-  const mustRead = memories.filter((m) => m.priority === "must_read").length;
-  const useful = memories.filter((m) => m.priority === "useful").length;
-  const background = memories.filter((m) => m.priority === "background").length;
-  const weakSemantic = memories.filter(
-    (m) => m.reasons.length === 1 && m.reasons.includes("semantic") && (m.semantic_score ?? 0) > 0 && (m.semantic_score ?? 0) < 0.35
-  ).length;
-  const reasons = [];
-  if (memories.length === 0) reasons.push("no memories matched the task or files");
-  if (context.isTemplateContext && !context.autoContextGenerated) reasons.push("project context is still a template");
-  if (!context.hasLastSession) reasons.push("no previous session recap");
-  if (mustRead > 0) reasons.push(`${mustRead} must_read memor${mustRead === 1 ? "y" : "ies"} matched directly`);
-  if (useful > 0) reasons.push(`${useful} useful memor${useful === 1 ? "y" : "ies"} matched`);
-  if (background > useful + mustRead && background > 2) reasons.push(`${background} background memories dominate the result`);
-  if (weakSemantic > 0) reasons.push(`${weakSemantic} weak semantic-only match${weakSemantic === 1 ? "" : "es"}`);
-  if (context.searchMode === "literal_fallback") reasons.push("semantic index unavailable or empty; literal fallback used");
-  if (memories.length === 0 || mustRead === 0 && useful === 0) {
-    return { level: "thin", reasons };
-  }
-  if (background > useful + mustRead && background > 2) {
-    return { level: "noisy", reasons };
-  }
-  return { level: "strong", reasons };
-}
-function explainWhySurfaced(memory, loaded, inputFiles, inferredModules) {
-  const why = [];
-  const fm = loaded?.memory.frontmatter;
-  if (memory.reasons.includes("anchor") && fm) {
-    const matching = fm.anchor.paths.filter(
-      (p) => inputFiles.length === 0 || inputFiles.some((file) => pathsOverlap(p, file))
-    );
-    if (matching.length > 0) {
-      const exact = matching.filter(
-        (p) => !isGlobPath(p) && inputFiles.some((file) => p === file || pathsOverlap(p, file))
-      );
-      const glob = matching.filter((p) => isGlobPath(p));
-      if (exact.length > 0) {
-        why.push(`Exact/file anchor match: ${exact.slice(0, 4).join(", ")}`);
-      }
-      if (glob.length > 0) {
-        why.push(`Glob anchor match: ${glob.slice(0, 4).join(", ")}`);
-      }
-      if (exact.length === 0 && glob.length === 0) {
-        why.push(`Anchored to touched path${matching.length === 1 ? "" : "s"}: ${matching.slice(0, 4).join(", ")}`);
-      }
-    } else if (fm.anchor.paths.length > 0) {
-      why.push(`Pulled by related anchor: ${fm.anchor.paths.slice(0, 4).join(", ")}`);
-    }
-    if (fm.anchor.symbols.length > 0) {
-      why.push(`Anchor symbol${fm.anchor.symbols.length === 1 ? "" : "s"}: ${fm.anchor.symbols.slice(0, 4).join(", ")}`);
-    }
-  }
-  if (memory.reasons.includes("symbol") && fm) {
-    why.push(`Explicit symbol match: ${fm.anchor.symbols.slice(0, 4).join(", ")}`);
-  }
-  if (memory.reasons.includes("module")) {
-    const moduleHints = [
-      ...memory.module ? [memory.module] : [],
-      ...memory.tags.filter((tag) => inferredModules.includes(tag))
-    ];
-    const shown = moduleHints.length > 0 ? [...new Set(moduleHints)].join(", ") : inferredModules.join(", ");
-    why.push(shown ? `Matched inferred module/tag: ${shown}` : "Matched inferred module context.");
-  }
-  if (memory.reasons.includes("domain")) {
-    why.push("Matched inferred domain from the target file paths.");
-  }
-  if (memory.reasons.includes("semantic")) {
-    const score = memory.semantic_score !== void 0 ? ` score=${Math.round(memory.semantic_score * 100) / 100}` : "";
-    why.push(`${memory.match_quality === "exact" ? "Literal task match" : "Semantic/task relevance"}${score}.`);
-  }
-  why.push(`Confidence: ${memory.confidence}; read ${memory.read_count} time${memory.read_count === 1 ? "" : "s"}.`);
-  if (memory.type === "attempt") why.push("Failed-approach record; read before repeating the same path.");
-  if (memory.type === "skill") why.push("Skill (reusable procedure/playbook) \u2014 follow the steps described when doing this type of task.");
-  if (memory.status === "proposed" || memory.status === "draft") {
-    why.push("Unvalidated record; use cautiously or ask a human before treating it as policy.");
-  }
-  return why;
-}
-async function trySemanticHits(ctx, task, limit) {
-  let mod;
-  try {
-    mod = await import("@hiveai/embeddings");
-  } catch {
-    return null;
-  }
-  const result = await mod.semanticSearch(ctx.paths, task, { limit });
-  if (!result) return null;
-  return result.hits.map((h) => ({ id: h.id, score: h.score }));
-}
-async function loadModuleContexts2(ctx, modules) {
-  if (modules.length === 0) return [];
-  if (!existsSync18(ctx.paths.modulesContextDir)) return [];
-  const available = new Set(
-    (await readdir3(ctx.paths.modulesContextDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name)
-  );
-  const out = [];
-  for (const m of modules) {
-    if (!available.has(m)) continue;
-    const file = path9.join(ctx.paths.modulesContextDir, m, "context.md");
-    if (existsSync18(file)) {
-      out.push({ name: m, content: await readFile3(file, "utf8") });
-    }
-  }
-  return out;
-}
 
 // src/tools/code-map.ts
 import { estimateTokens as estimateTokens2, loadCodeMap as loadCodeMap2, queryCodeMap as queryCodeMap2 } from "@hiveai/core";
@@ -2187,7 +2164,7 @@ function estimateFileEntryTokens(f) {
 }
 
 // src/tools/mem-diff.ts
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync20 } from "fs";
 import { loadMemoriesFromDir as loadMemoriesFromDir14 } from "@hiveai/core";
 import { z as z19 } from "zod";
 var MemDiffInputSchema = {
@@ -2195,7 +2172,7 @@ var MemDiffInputSchema = {
   id_b: z19.string().min(1).describe("Second memory id")
 };
 async function memDiff(input, ctx) {
-  if (!existsSync19(ctx.paths.memoriesDir)) {
+  if (!existsSync20(ctx.paths.memoriesDir)) {
     throw new Error(`No .ai/memories at ${ctx.paths.root}.`);
   }
   const all = await loadMemoriesFromDir14(ctx.paths.memoriesDir);
@@ -2232,7 +2209,7 @@ async function memDiff(input, ctx) {
 }
 
 // src/tools/get-recap.ts
-import { existsSync as existsSync20 } from "fs";
+import { existsSync as existsSync21 } from "fs";
 import { loadMemoriesFromDir as loadMemoriesFromDir15 } from "@hiveai/core";
 import { z as z20 } from "zod";
 var GetRecapInputSchema = {
@@ -2241,7 +2218,7 @@ var GetRecapInputSchema = {
   )
 };
 async function getRecap(input, ctx) {
-  if (!existsSync20(ctx.paths.memoriesDir)) {
+  if (!existsSync21(ctx.paths.memoriesDir)) {
     return { recap: null, notice: "No .ai/memories directory \u2014 haive not initialized here." };
   }
   const all = await loadMemoriesFromDir15(ctx.paths.memoriesDir);
@@ -2340,7 +2317,7 @@ async function codeSearch(input, ctx) {
 }
 
 // src/tools/why-this-file.ts
-import { existsSync as existsSync21 } from "fs";
+import { existsSync as existsSync22 } from "fs";
 import { spawn } from "child_process";
 import path10 from "path";
 import {
@@ -2360,7 +2337,7 @@ var WhyThisFileInputSchema = {
   memory_limit: z23.number().int().positive().max(20).default(5).describe("Cap on memories anchored to this path.")
 };
 async function whyThisFile(input, ctx) {
-  const fileExists = existsSync21(path10.join(ctx.paths.root, input.path));
+  const fileExists = existsSync22(path10.join(ctx.paths.root, input.path));
   const [commits, memories, codeMap] = await Promise.all([
     runGitLog(ctx.paths.root, input.path, input.git_log_limit).catch(() => []),
     collectAnchoredMemories(ctx, input.path, input.memory_limit),
@@ -2401,7 +2378,7 @@ async function whyThisFile(input, ctx) {
   };
 }
 async function collectAnchoredMemories(ctx, filePath, limit) {
-  if (!existsSync21(ctx.paths.memoriesDir)) return [];
+  if (!existsSync22(ctx.paths.memoriesDir)) return [];
   const all = await loadMemoriesFromDir16(ctx.paths.memoriesDir);
   const usage = await loadUsageIndex8(ctx.paths);
   const out = [];
@@ -2456,7 +2433,7 @@ function runCommand(cmd, args, cwd) {
 }
 
 // src/tools/anti-patterns-check.ts
-import { existsSync as existsSync22 } from "fs";
+import { existsSync as existsSync23 } from "fs";
 import {
   addedLinesFromDiff,
   deriveConfidence as deriveConfidence6,
@@ -2550,7 +2527,7 @@ async function antiPatternsCheck(input, ctx) {
       notice: "Nothing to check \u2014 provide either `diff` text or `paths`."
     };
   }
-  if (!existsSync22(ctx.paths.memoriesDir)) {
+  if (!existsSync23(ctx.paths.memoriesDir)) {
     return { scanned: 0, warnings: [], notice: "No .ai/memories directory \u2014 nothing to check against." };
   }
   const all = await loadMemoriesFromDir17(ctx.paths.memoriesDir);
@@ -2585,6 +2562,7 @@ async function antiPatternsCheck(input, ctx) {
       reasons: [reason],
       tags: fm.tags ?? [],
       anchor_paths: fm.anchor?.paths ?? [],
+      ...fm.sensor != null ? { has_sensor: true } : {},
       ...score !== void 0 ? { semantic_score: score } : {}
     });
   };
@@ -2653,7 +2631,7 @@ async function antiPatternsCheck(input, ctx) {
 }
 
 // src/tools/mem-distill.ts
-import { existsSync as existsSync23 } from "fs";
+import { existsSync as existsSync24 } from "fs";
 import {
   loadMemoriesFromDir as loadMemoriesFromDir18,
   tokenizeQuery as tokenizeQuery4
@@ -2705,7 +2683,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "error"
 ]);
 async function memDistill(input, ctx) {
-  if (!existsSync23(ctx.paths.memoriesDir)) {
+  if (!existsSync24(ctx.paths.memoriesDir)) {
     return { scanned: 0, singletons: 0, clusters: [], notice: "No .ai/memories directory." };
   }
   const cutoff = Date.now() - input.since_days * MS_PER_DAY;
@@ -2813,7 +2791,7 @@ function firstHeading(body) {
 }
 
 // src/tools/why-this-decision.ts
-import { existsSync as existsSync24 } from "fs";
+import { existsSync as existsSync25 } from "fs";
 import { spawn as spawn2 } from "child_process";
 import {
   deriveConfidence as deriveConfidence7,
@@ -2828,7 +2806,7 @@ var WhyThisDecisionInputSchema = {
   git_log_limit: z26.number().int().positive().max(20).default(5).describe("How many recent commits per anchor path to surface.")
 };
 async function whyThisDecision(input, ctx) {
-  if (!existsSync24(ctx.paths.memoriesDir)) {
+  if (!existsSync25(ctx.paths.memoriesDir)) {
     return {
       found: false,
       related: [],
@@ -2960,7 +2938,7 @@ function runCommand2(cmd, args, cwd) {
 }
 
 // src/tools/mem-conflicts.ts
-import { existsSync as existsSync25 } from "fs";
+import { existsSync as existsSync26 } from "fs";
 import {
   deriveConfidence as deriveConfidence8,
   getUsage as getUsage9,
@@ -2978,7 +2956,7 @@ var MemConflictsInputSchema = {
 var POSITIVE_PATTERNS = /\b(use|prefer|always|should use|do this|recommended|ok to)\b/i;
 var NEGATIVE_PATTERNS = /\b(do not use|don'?t use|never|avoid|forbidden|deprecated|stop using|do NOT|❌)\b/i;
 async function memConflicts(input, ctx) {
-  if (!existsSync25(ctx.paths.memoriesDir)) {
+  if (!existsSync26(ctx.paths.memoriesDir)) {
     return { found: false, scanned: 0, conflicts: [], notice: "No .ai/memories directory." };
   }
   const all = await loadMemoriesFromDir20(ctx.paths.memoriesDir);
@@ -3171,7 +3149,9 @@ async function preCommitCheck(input, ctx) {
   };
 }
 function classifyWarning(warning, paths, anchoredBlocks = false) {
-  const affectedFiles = paths.filter((p) => !p.startsWith(".ai/.usage/"));
+  const affectedFiles = paths.filter(
+    (p) => !p.startsWith(".ai/.usage/") && !p.startsWith(".ai/.cache/") && !p.startsWith(".ai/.runtime/")
+  );
   const repairCommand = repairCommandForWarning(warning, affectedFiles);
   const fileDowngrade = fileTypeDowngradeReason(warning, affectedFiles);
   if (fileDowngrade) {
@@ -3202,6 +3182,24 @@ function classifyWarning(warning, paths, anchoredBlocks = false) {
     };
   }
   if (isBlockingWarning(warning)) {
+    if (warning.scope === "personal") {
+      return {
+        ...warning,
+        level: "review",
+        rationale: "personal anti-pattern memories are review guidance unless a deterministic block-severity sensor fires",
+        affected_files: affectedFiles,
+        repair_command: repairCommand
+      };
+    }
+    if (warning.has_sensor && !warning.reasons.includes("sensor")) {
+      return {
+        ...warning,
+        level: "review",
+        rationale: "memory has a sensor that did not fire \u2014 sensor is the authoritative check; strong semantic match alone is insufficient to block",
+        affected_files: affectedFiles,
+        repair_command: repairCommand
+      };
+    }
     return {
       ...warning,
       level: "blocking",
@@ -3213,7 +3211,16 @@ function classifyWarning(warning, paths, anchoredBlocks = false) {
   const hasSemantic = warning.reasons.includes("semantic");
   const semanticScore = warning.semantic_score ?? 0;
   const highConfidence = warning.confidence === "authoritative" || warning.confidence === "trusted";
-  if (anchoredBlocks && highConfidence && warning.reasons.includes("anchor") && (warning.reasons.includes("literal") || hasSemantic && semanticScore >= 0.45)) {
+  if (anchoredBlocks && highConfidence && warning.scope !== "personal" && warning.reasons.includes("anchor") && (warning.reasons.includes("literal") || hasSemantic && semanticScore >= 0.45)) {
+    if (warning.has_sensor && !warning.reasons.includes("sensor")) {
+      return {
+        ...warning,
+        level: "review",
+        rationale: "memory has a sensor that did not fire \u2014 literal match alone is insufficient to block; sensor is the authoritative check",
+        affected_files: affectedFiles,
+        repair_command: repairCommand
+      };
+    }
     return {
       ...warning,
       level: "blocking",
@@ -3338,13 +3345,25 @@ function isJsonConfigFile(base) {
   return false;
 }
 function repairCommandForWarning(warning, paths) {
-  const firstPath = paths[0];
-  return firstPath ? `haive briefing --files "${firstPath}" --task "review ${warning.id}"` : `haive memory show ${warning.id}`;
+  const targetPath = repairTargetPathForWarning(warning, paths);
+  return targetPath ? `haive briefing --files "${targetPath}" --task "review ${warning.id}"` : `haive memory show ${warning.id}`;
+}
+function repairTargetPathForWarning(warning, paths) {
+  const usablePaths = paths.filter(
+    (p) => !p.startsWith(".ai/.usage/") && !p.startsWith(".ai/.cache/") && !p.startsWith(".ai/.runtime/")
+  );
+  const anchors = warning.anchor_paths ?? [];
+  for (const file of usablePaths) {
+    if (anchors.some((anchor) => anchor === file || file.startsWith(`${anchor}/`) || anchor.startsWith(`${file}/`))) {
+      return file;
+    }
+  }
+  return usablePaths[0];
 }
 
 // src/tools/pattern-detect.ts
 import { mkdir as mkdir7, writeFile as writeFile12 } from "fs/promises";
-import { existsSync as existsSync26 } from "fs";
+import { existsSync as existsSync27 } from "fs";
 import path11 from "path";
 import { execSync as execSync2 } from "child_process";
 import {
@@ -3381,7 +3400,7 @@ var PatternDetectInputSchema = {
   scope: z29.enum(["personal", "team"]).default("team").describe("Scope for proposed memories.")
 };
 async function patternDetect(input, ctx) {
-  if (!existsSync26(ctx.paths.haiveDir)) {
+  if (!existsSync27(ctx.paths.haiveDir)) {
     return {
       scanned_events: 0,
       matches: [],
@@ -3510,7 +3529,7 @@ async function patternDetect(input, ctx) {
         fm.id,
         void 0
       );
-      if (existsSync26(file)) continue;
+      if (existsSync27(file)) continue;
       await mkdir7(path11.dirname(file), { recursive: true });
       await writeFile12(
         file,
@@ -3556,7 +3575,7 @@ function gitFileDiff(root, file, sinceDays) {
 }
 
 // src/tools/mem-conflict-candidates.ts
-import { existsSync as existsSync27 } from "fs";
+import { existsSync as existsSync28 } from "fs";
 import {
   findLexicalConflictPairs,
   findTopicStatusConflictPairs,
@@ -3574,7 +3593,7 @@ var MemConflictCandidatesInputSchema = {
   )
 };
 async function memConflictCandidates(input, ctx) {
-  if (!existsSync27(ctx.paths.memoriesDir)) {
+  if (!existsSync28(ctx.paths.memoriesDir)) {
     return {
       pairs: [],
       topic_status_pairs: [],
@@ -3626,7 +3645,7 @@ async function memSuggestTopic(input, _ctx) {
 }
 
 // src/tools/mem-timeline.ts
-import { existsSync as existsSync28 } from "fs";
+import { existsSync as existsSync29 } from "fs";
 import { collectTimelineEntries, loadMemoriesFromDir as loadMemoriesFromDir22 } from "@hiveai/core";
 import { z as z33 } from "zod";
 var MemTimelineInputSchema = {
@@ -3635,7 +3654,7 @@ var MemTimelineInputSchema = {
   limit: z33.number().int().positive().max(100).default(30).describe("Max timeline entries returned")
 };
 async function memTimeline(input, ctx) {
-  if (!existsSync28(ctx.paths.memoriesDir)) {
+  if (!existsSync29(ctx.paths.memoriesDir)) {
     return { entries: [], total: 0, notice: "No .ai/memories directory." };
   }
   const all = await loadMemoriesFromDir22(ctx.paths.memoriesDir);
@@ -3842,7 +3861,19 @@ This creates/updates a single rolling recap that **get_briefing automatically su
 
 Calling \`mem_session_end\` also **clears the pending-distill marker** (if any), confirming that this session's learnings have been properly captured rather than left as an auto-recap skeleton.
 
-When done, respond with a brief summary: "Saved N memories: [list of IDs]. Session recap saved."
+### 7. Verify the git/release exit protocol \u2014 always
+Run **\`haive enforce finish\`** before your final response.
+
+This executable gate checks the multi-agent git-sync decision:
+- no completed work is left as an uncommitted local diff
+- shippable package changes have a lockstep version bump
+- the release tag \`vX.Y.Z\` exists when a version was bumped
+- commits and tags have been pushed
+- agents never run \`npm publish\` (publication remains human-owned)
+
+If it blocks, fix the reported Git/version/tag/push issue before telling the developer the task is done.
+
+When done, respond with a brief summary: "Saved N memories: [list of IDs]. Session recap saved. hAIve finish gate passed."
 `;
   return {
     description: "Post-task reflection: capture what you learned before closing the session",
@@ -3925,9 +3956,9 @@ When done, respond with: "Imported N memories: [list of IDs]" or "Nothing action
 }
 
 // src/server.ts
-import { loadConfigSync } from "@hiveai/core";
+import { hasRecentBriefingMarker, loadConfigSync } from "@hiveai/core";
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.10.5";
+var SERVER_VERSION = "0.10.9";
 function jsonResult(data) {
   return {
     content: [
@@ -4031,11 +4062,16 @@ function createHaiveServer(options = {}) {
           return await handler(input);
         }
         if (requireBriefingFirst && MUTATING_TOOLS.has(name) && !briefingLoaded) {
-          return jsonResult({
-            error: "haive_briefing_required",
-            message: "This hAIve project requires get_briefing or mem_relevant_to before state-changing hAIve tools. Call get_briefing({ task: '...' }) first.",
-            tool: name
-          });
+          const hasDiskMarker = await hasRecentBriefingMarker(context.paths).catch(() => false);
+          if (hasDiskMarker) {
+            briefingLoaded = true;
+          } else {
+            return jsonResult({
+              error: "haive_briefing_required",
+              message: "This hAIve project requires get_briefing or mem_relevant_to before state-changing hAIve tools. Call get_briefing({ task: '...' }) first.",
+              tool: name
+            });
+          }
         }
         return await handler(input);
       }