@hiveai/cli 0.9.14 → 0.9.16

package/dist/index.js

@@ -3063,6 +3063,7 @@ import {
   loadMemoriesFromDir as loadMemoriesFromDir13,
   loadUsageIndex as loadUsageIndex7,
   memoryMatchesAnchorPaths as memoryMatchesAnchorPaths22,
+  pathsOverlap,
   queryCodeMap as queryCodeMap2,
   resolveBriefingBudget as resolveBriefingBudget2,
   serializeMemory as serializeMemory9,
@@ -3126,7 +3127,7 @@ import {
   getUsage as getUsage9,
   loadMemoriesFromDir as loadMemoriesFromDir20,
   loadUsageIndex as loadUsageIndex11,
-  pathsOverlap,
+  pathsOverlap as pathsOverlap2,
   tokenizeQuery as tokenizeQuery5
 } from "@hiveai/core";
 import { z as z27 } from "zod";
@@ -4654,10 +4655,14 @@ ${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 outputMemories = input.format === "compact" ? trimmedMemories.map((m) => ({ ...m, body: compactSummary(m.body) })) : input.format === "actions" ? trimmedMemories.map((m) => ({
+  const formattedMemories = input.format === "compact" ? trimmedMemories.map((m) => ({ ...m, body: compactSummary(m.body) })) : input.format === "actions" ? trimmedMemories.map((m) => ({
     ...m,
     body: extractActionsBriefBody2(m.body)
   })) : trimmedMemories;
+  const outputMemories = formattedMemories.map((m) => ({
+    ...m,
+    why: explainWhySurfaced(m, byId.get(m.id), input.files, inferred)
+  }));
   let symbolLocations;
   const symbolsToLookup = new Set(input.symbols);
   for (const m of outputMemories) {
@@ -4823,6 +4828,44 @@ function compactSummary(body) {
   }
   return body.slice(0, 120);
 }
+function explainWhySurfaced(memory2, loaded, inputFiles, inferredModules) {
+  const why = [];
+  const fm = loaded?.memory.frontmatter;
+  if (memory2.reasons.includes("anchor") && fm) {
+    const matching = fm.anchor.paths.filter(
+      (p) => inputFiles.length === 0 || inputFiles.some((file) => pathsOverlap(p, file))
+    );
+    if (matching.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 (memory2.reasons.includes("module")) {
+    const moduleHints = [
+      ...memory2.module ? [memory2.module] : [],
+      ...memory2.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 (memory2.reasons.includes("domain")) {
+    why.push("Matched inferred domain from the target file paths.");
+  }
+  if (memory2.reasons.includes("semantic")) {
+    const score = memory2.semantic_score !== void 0 ? ` score=${Math.round(memory2.semantic_score * 100) / 100}` : "";
+    why.push(`${memory2.match_quality === "exact" ? "Literal task match" : "Semantic/task relevance"}${score}.`);
+  }
+  why.push(`Confidence: ${memory2.confidence}; read ${memory2.read_count} time${memory2.read_count === 1 ? "" : "s"}.`);
+  if (memory2.type === "attempt") why.push("Failed-approach record; read before repeating the same path.");
+  if (memory2.status === "proposed" || memory2.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 {
@@ -5585,7 +5628,7 @@ async function memConflicts(input, ctx) {
     const otherText = (other.memory.body + " " + fm.tags.join(" ")).toLowerCase();
     const reasons = [];
     const sim = simScores?.get(fm.id) ?? null;
-    const hasPathOverlap = fm.anchor.paths.some((p) => targetPaths.some((tp) => pathsOverlap(p, tp)));
+    const hasPathOverlap = fm.anchor.paths.some((p) => targetPaths.some((tp) => pathsOverlap2(p, tp)));
     const otherTokens = new Set(tokenizeQuery5(otherText));
     const tokenOverlap = countIntersection(targetTokens, otherTokens);
     const isSemanticNeighbor = sim !== null && sim >= input.min_score;
@@ -5620,7 +5663,7 @@ async function memConflicts(input, ctx) {
       body_preview: other.memory.body.split("\n").slice(0, 4).join("\n").slice(0, 300),
       similarity: sim,
       reasons,
-      shared_paths: fm.anchor.paths.filter((p) => targetPaths.some((tp) => pathsOverlap(p, tp)))
+      shared_paths: fm.anchor.paths.filter((p) => targetPaths.some((tp) => pathsOverlap2(p, tp)))
     });
   }
   conflicts.sort((a, b) => {
@@ -5707,10 +5750,13 @@ async function preCommitCheck(input, ctx) {
   const filesTouching = new Set(relevantMatches.map((m) => m.id));
   const staleHits = verifyResult.results.filter((r) => r.stale && filesTouching.has(r.id));
   const blockOn = input.block_on;
-  const blockingWarnings = apResult.warnings.filter(isBlockingWarning);
+  const classifiedWarnings = apResult.warnings.map(classifyWarning);
+  const blockingWarnings = classifiedWarnings.filter((w) => w.level === "blocking");
+  const reviewWarnings = classifiedWarnings.filter((w) => w.level === "review");
+  const infoWarnings = classifiedWarnings.filter((w) => w.level === "info");
   let should_block = false;
   if (blockOn !== "never") {
-    if (blockOn === "any" && (apResult.warnings.length > 0 || staleHits.length > 0)) should_block = true;
+    if (blockOn === "any" && (blockingWarnings.length > 0 || reviewWarnings.length > 0 || staleHits.length > 0)) should_block = true;
     if (blockOn === "high-confidence" && (blockingWarnings.length > 0 || staleHits.length > 0)) should_block = true;
   }
   const relevant_memories = relevantMatches.slice(0, 8).map((m) => ({
@@ -5724,10 +5770,12 @@ async function preCommitCheck(input, ctx) {
     summary: {
       anti_patterns: apResult.warnings.length,
       blocking_warnings: blockingWarnings.length,
+      review_warnings: reviewWarnings.length,
+      info_warnings: infoWarnings.length,
       relevant_memories: relevant_memories.length,
       stale_anchors: staleHits.length
     },
-    warnings: apResult.warnings,
+    warnings: classifiedWarnings,
     relevant_memories,
     stale_anchors: staleHits.map((r) => ({
       id: r.id,
@@ -5737,6 +5785,30 @@ async function preCommitCheck(input, ctx) {
     }))
   };
 }
+function classifyWarning(warning) {
+  if (isBlockingWarning(warning)) {
+    return {
+      ...warning,
+      level: "blocking",
+      rationale: "authoritative/trusted memory plus strong semantic match to the diff (score >= 0.65)"
+    };
+  }
+  const hasSemantic = warning.reasons.includes("semantic");
+  const semanticScore = warning.semantic_score ?? 0;
+  const highConfidence = warning.confidence === "authoritative" || warning.confidence === "trusted";
+  if (hasSemantic && semanticScore >= 0.45 || highConfidence && warning.reasons.includes("anchor") && warning.reasons.includes("literal")) {
+    return {
+      ...warning,
+      level: "review",
+      rationale: hasSemantic ? "semantic match is plausible but below blocking threshold" : "anchored high-confidence memory also matched diff tokens, but no strong semantic proof"
+    };
+  }
+  return {
+    ...warning,
+    level: "info",
+    rationale: "weak signal only (literal/anchor/low semantic evidence); surfaced for audit, hidden in concise CLI output"
+  };
+}
 function isBlockingWarning(warning) {
   const highConfidence = warning.confidence === "authoritative" || warning.confidence === "trusted";
   if (!highConfidence) return false;
@@ -6273,7 +6345,7 @@ When done, respond with: "Imported N memories: [list of IDs]" or "Nothing action
   };
 }
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.9.14";
+var SERVER_VERSION = "0.9.16";
 function jsonResult(data) {
   return {
     content: [
@@ -6284,15 +6356,58 @@ function jsonResult(data) {
     ]
   };
 }
-var ENFORCEMENT_PROFILE_TOOLS = /* @__PURE__ */ new Set([
+var ENFORCEMENT_PROFILE_TOOLS = [
   "get_briefing",
   "mem_save",
+  "mem_tried",
   "mem_search",
+  "mem_get",
   "mem_verify",
   "mem_relevant_to",
+  "code_map",
   "pre_commit_check",
   "mem_session_end"
-]);
+];
+var MAINTENANCE_PROFILE_TOOLS = [
+  ...ENFORCEMENT_PROFILE_TOOLS,
+  "mem_suggest_topic",
+  "mem_for_files",
+  "mem_list",
+  "get_project_context",
+  "bootstrap_project_save",
+  "mem_resolve_project",
+  "mem_update",
+  "mem_approve",
+  "mem_reject",
+  "mem_pending",
+  "mem_delete",
+  "mem_diff",
+  "get_recap",
+  "code_search",
+  "anti_patterns_check",
+  "mem_distill",
+  "mem_timeline",
+  "mem_conflict_candidates"
+];
+var EXPERIMENTAL_PROFILE_TOOLS = [
+  ...MAINTENANCE_PROFILE_TOOLS,
+  "mem_observe",
+  "why_this_file",
+  "why_this_decision",
+  "mem_conflicts_with",
+  "pattern_detect",
+  "runtime_journal_append",
+  "runtime_journal_tail"
+];
+var TOOL_PROFILES = {
+  enforcement: new Set(ENFORCEMENT_PROFILE_TOOLS),
+  maintenance: new Set(MAINTENANCE_PROFILE_TOOLS),
+  experimental: new Set(EXPERIMENTAL_PROFILE_TOOLS)
+};
+function getAllowedToolsForProfile(profile) {
+  if (profile === "full") return TOOL_PROFILES.experimental;
+  return TOOL_PROFILES[profile] ?? TOOL_PROFILES.enforcement;
+}
 var BRIEFING_TOOLS = /* @__PURE__ */ new Set(["get_briefing", "mem_relevant_to"]);
 var MUTATING_TOOLS = /* @__PURE__ */ new Set([
   "mem_save",
@@ -6319,7 +6434,8 @@ function createHaiveServer(options = {}) {
     { name: SERVER_NAME, version: SERVER_VERSION },
     { capabilities: { tools: {}, prompts: {} } }
   );
-  const shouldRegisterTool = (name) => toolProfile === "full" || ENFORCEMENT_PROFILE_TOOLS.has(name);
+  const allowedTools = getAllowedToolsForProfile(toolProfile);
+  const shouldRegisterTool = (name) => allowedTools.has(name);
   const registerTool = (name, description, schema, handler) => {
     if (!shouldRegisterTool(name)) return;
     const tool = server.tool.bind(server);
@@ -6343,7 +6459,11 @@ function createHaiveServer(options = {}) {
       }
     );
   };
-  const shouldRegisterPrompt = (name) => toolProfile === "full" || name === "bootstrap_project" || name === "post_task";
+  const shouldRegisterPrompt = (name) => {
+    if (name === "bootstrap_project" || name === "post_task") return true;
+    if (name === "import_docs") return toolProfile !== "enforcement";
+    return toolProfile === "experimental" || toolProfile === "full";
+  };
   registerTool(
     "mem_save",
     [
@@ -10641,9 +10761,9 @@ function parseDays(input) {
 
 // src/commands/doctor.ts
 import { existsSync as existsSync60 } from "fs";
-import { stat } from "fs/promises";
+import { readFile as readFile17, stat } from "fs/promises";
 import path41 from "path";
-import { execSync as execSync3 } from "child_process";
+import { execFileSync, execSync as execSync3 } from "child_process";
 import "commander";
 import {
   codeMapPath as codeMapPath2,
@@ -10681,8 +10801,8 @@ function registerDoctor(program2) {
         fix: "haive init"
       });
     } else {
-      const { readFile: readFile18 } = await import("fs/promises");
-      const content = await readFile18(paths.projectContext, "utf8");
+      const { readFile: readFile19 } = await import("fs/promises");
+      const content = await readFile19(paths.projectContext, "utf8");
       const isTemplate = content.includes("TODO \u2014 high-level overview") || content.includes("Generated by `haive init`");
       if (isTemplate) {
         findings.push({
@@ -10808,8 +10928,8 @@ function registerDoctor(program2) {
       let hasClaudeEnforcement = false;
       if (existsSync60(claudeSettings)) {
         try {
-          const { readFile: readFile18 } = await import("fs/promises");
-          const raw = await readFile18(claudeSettings, "utf8");
+          const { readFile: readFile19 } = await import("fs/promises");
+          const raw = await readFile19(claudeSettings, "utf8");
           hasClaudeEnforcement = raw.includes("haive enforce session-start") && raw.includes("haive enforce pre-tool-use");
         } catch {
           hasClaudeEnforcement = false;
@@ -10832,13 +10952,14 @@ function registerDoctor(program2) {
         fix: "Edit .ai/haive.config.json: set autoSessionEnd: true (or re-run `haive init` without --manual)."
       });
     }
+    findings.push(...await collectInstallFindings(root, "0.9.16"));
     try {
       const legacyRaw = execSync3("haive-mcp --version", {
         encoding: "utf8",
         timeout: 3e3,
         stdio: ["ignore", "pipe", "ignore"]
       }).trim();
-      const cliVersion = "0.9.14";
+      const cliVersion = "0.9.16";
       if (legacyRaw && legacyRaw !== cliVersion) {
         findings.push({
           severity: "warn",
@@ -10885,6 +11006,103 @@ function emit(findings, opts) {
 function isSearchTool(name) {
   return ["mem_search", "code_search", "mem_relevant_to", "get_briefing"].includes(name);
 }
+async function collectInstallFindings(root, expectedVersion) {
+  const findings = [];
+  const haiveBins = listHaiveBins();
+  if (haiveBins.length === 0) {
+    findings.push({
+      severity: "warn",
+      code: "haive-not-on-path",
+      message: "No `haive` binary was found on PATH. Hooks and MCP configs that call `haive` may fail.",
+      fix: `npm install -g @hiveai/cli@${expectedVersion}`
+    });
+  } else {
+    const first = haiveBins[0];
+    const firstVersion = versionForBinary(first);
+    if (firstVersion && firstVersion !== expectedVersion) {
+      findings.push({
+        severity: "warn",
+        code: "path-haive-version-mismatch",
+        message: `PATH resolves haive to ${first} (${firstVersion}), but this build expects ${expectedVersion}.`,
+        fix: `npm install -g @hiveai/cli@${expectedVersion}
+which -a haive`
+      });
+    }
+    const skewed = haiveBins.map((bin) => ({ bin, version: versionForBinary(bin) })).filter((item) => item.version && item.version !== expectedVersion);
+    if (skewed.length > 0) {
+      findings.push({
+        severity: "info",
+        code: "multiple-haive-binaries",
+        message: `Found ${haiveBins.length} haive binar${haiveBins.length === 1 ? "y" : "ies"} on PATH; ${skewed.length} do not match ${expectedVersion}.`,
+        fix: "Remove stale global installs or ensure hooks call the intended `haive` binary."
+      });
+    }
+  }
+  const integrationFiles = [
+    ".git/hooks/pre-commit",
+    ".git/hooks/pre-push",
+    ".claude/settings.local.json",
+    ".mcp.json",
+    ".cursor/mcp.json",
+    ".vscode/mcp.json"
+  ];
+  for (const rel of integrationFiles) {
+    const file = path41.join(root, rel);
+    if (!existsSync60(file)) continue;
+    const text = await readFile17(file, "utf8").catch(() => "");
+    for (const bin of extractAbsoluteHaiveBins(text)) {
+      const version = versionForBinary(bin);
+      if (!version) {
+        findings.push({
+          severity: "warn",
+          code: "integration-haive-binary-missing",
+          message: `${rel} references ${bin}, but it could not be executed.`,
+          fix: "Run `haive agent setup --no-global` or `haive enforce install` to rewrite project integrations."
+        });
+      } else if (version !== expectedVersion) {
+        findings.push({
+          severity: "warn",
+          code: "integration-haive-version-mismatch",
+          message: `${rel} references ${bin} (${version}), but current hAIve is ${expectedVersion}.`,
+          fix: "Run `haive agent setup --no-global` and `haive enforce install` to refresh stale paths."
+        });
+      }
+    }
+  }
+  return findings;
+}
+function listHaiveBins() {
+  try {
+    return execSync3("which -a haive", {
+      encoding: "utf8",
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).split("\n").map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+function versionForBinary(bin) {
+  try {
+    const out = execFileSync(bin, ["--version"], {
+      encoding: "utf8",
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    return out.match(/\d+\.\d+\.\d+/)?.[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function extractAbsoluteHaiveBins(text) {
+  const out = /* @__PURE__ */ new Set();
+  const re = /(["'\s])((?:\/[^"'\s]+)*\/haive)\b/g;
+  let match;
+  while (match = re.exec(text)) {
+    if (match[2]) out.add(match[2]);
+  }
+  return [...out].sort();
+}
 
 // src/commands/playback.ts
 import { existsSync as existsSync61 } from "fs";
@@ -11050,19 +11268,21 @@ function registerPrecommit(program2) {
     console.log(ui.bold(`hAIve precommit \u2014 ${touchedPaths.length} file(s)`));
     console.log(
       ui.dim(
-        `  anti-patterns: ${result.summary.anti_patterns}  blocking: ${result.summary.blocking_warnings ?? result.summary.anti_patterns}  relevant memories: ${result.summary.relevant_memories}  stale anchors: ${result.summary.stale_anchors}`
+        `  anti-patterns: ${result.summary.anti_patterns}  blocking: ${result.summary.blocking_warnings ?? result.summary.anti_patterns}  review: ${result.summary.review_warnings ?? 0}  info: ${result.summary.info_warnings ?? 0}  relevant memories: ${result.summary.relevant_memories}  stale anchors: ${result.summary.stale_anchors}`
       )
     );
     console.log();
-    if (result.warnings.length > 0) {
-      console.log(ui.bold("\u26A0 Anti-patterns matched:"));
-      for (const w of result.warnings.slice(0, 10)) {
-        console.log(`  ${ui.yellow("\u26A0")} ${w.id} ${ui.dim(`(${w.type}, ${w.confidence})`)}`);
-        for (const line of w.body_preview.split("\n").slice(0, 3)) {
-          console.log(`     ${ui.dim(line)}`);
-        }
-        console.log(`     ${ui.dim("reasons:")} ${w.reasons.join(", ")}`);
-      }
+    const blocking = result.warnings.filter((w) => w.level === "blocking");
+    const review = result.warnings.filter((w) => w.level === "review");
+    const info = result.warnings.filter((w) => w.level === "info");
+    printWarnings("Blocking anti-patterns", blocking, "error");
+    printWarnings("Review anti-patterns", review.slice(0, 8), "warn");
+    if (info.length > 0) {
+      console.log(
+        ui.dim(
+          `${info.length} weak anti-pattern signal${info.length === 1 ? "" : "s"} hidden. Use --json to inspect FYI matches.`
+        )
+      );
       console.log();
     }
     if (result.relevant_memories.length > 0) {
@@ -11091,6 +11311,20 @@ function registerPrecommit(program2) {
     }
   });
 }
+function printWarnings(title, warnings, tone) {
+  if (warnings.length === 0) return;
+  console.log(ui.bold(tone === "error" ? `\u2717 ${title}:` : `\u26A0 ${title}:`));
+  for (const w of warnings) {
+    const marker = tone === "error" ? ui.red("\u2717") : ui.yellow("\u26A0");
+    console.log(`  ${marker} ${w.id} ${ui.dim(`(${w.type}, ${w.confidence})`)}`);
+    for (const line of w.body_preview.split("\n").slice(0, 3)) {
+      console.log(`     ${ui.dim(line)}`);
+    }
+    console.log(`     ${ui.dim("reasons:")} ${w.reasons.join(", ")}`);
+    if (w.rationale) console.log(`     ${ui.dim("why shown:")} ${w.rationale}`);
+  }
+  console.log();
+}
 function runCommand3(cmd, args, cwd) {
   return new Promise((resolve, reject) => {
     const proc = spawn4(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
@@ -11177,7 +11411,9 @@ import { existsSync as existsSync64 } from "fs";
 import "commander";
 import {
   findProjectRoot as findProjectRoot44,
+  getUsage as getUsage20,
   loadMemoriesFromDir as loadMemoriesFromDir35,
+  loadUsageIndex as loadUsageIndex26,
   resolveHaivePaths as resolveHaivePaths40
 } from "@hiveai/core";
 async function lintMemoriesAsync(root) {
@@ -11185,7 +11421,9 @@ async function lintMemoriesAsync(root) {
   const out = [];
   if (!existsSync64(paths.memoriesDir)) return out;
   const loaded = await loadMemoriesFromDir35(paths.memoriesDir);
+  const usage = await loadUsageIndex26(paths);
   const ANCHOR_TYPES = /* @__PURE__ */ new Set(["decision", "architecture", "gotcha"]);
+  const actionableWords = /\b(always|never|prefer|use|avoid|because|instead|why|rationale|do not|must|should)\b/i;
   for (const { filePath, memory: memory2 } of loaded) {
     const fm = memory2.frontmatter;
     if (fm.type === "session_recap") continue;
@@ -11200,6 +11438,15 @@ async function lintMemoriesAsync(root) {
         message: "Body looks very short (< ~40 chars of prose after headings). Prefer actionable detail."
       });
     }
+    if (["decision", "gotcha", "convention", "architecture", "attempt"].includes(fm.type) && fm.status !== "rejected" && !actionableWords.test(naked)) {
+      out.push({
+        file: filePath,
+        id: fm.id,
+        severity: "info",
+        code: "LOW_ACTIONABILITY",
+        message: "Record does not contain obvious action/rationale words. Add the concrete rule, why it exists, and what to do instead."
+      });
+    }
     if (ANCHOR_TYPES.has(fm.type) && fm.anchor.paths.length === 0 && fm.status === "validated") {
       out.push({
         file: filePath,
@@ -11237,9 +11484,64 @@ async function lintMemoriesAsync(root) {
         message: "No Markdown heading (#/##/###) \u2014 add one so humans and auditors can skim the memo quickly."
       });
     }
+    const u = getUsage20(usage, fm.id);
+    if (fm.status === "validated" && u.read_count === 0) {
+      out.push({
+        file: filePath,
+        id: fm.id,
+        severity: "info",
+        code: "NEVER_READ",
+        message: "Validated record has never been surfaced/read. Consider improving tags/anchors or archiving it if it is not useful."
+      });
+    }
+  }
+  for (const dup of nearDuplicatePairs(loaded)) {
+    out.push({
+      file: dup.file,
+      id: dup.id,
+      severity: "warn",
+      code: "NEAR_DUPLICATE",
+      message: `Body overlaps ~${Math.round(dup.score * 100)}% with ${dup.otherId}. Merge or deprecate one record to reduce briefing noise.`
+    });
+  }
+  return out;
+}
+function nearDuplicatePairs(loaded) {
+  const out = [];
+  const candidates = loaded.filter(({ memory: memory2 }) => {
+    const fm = memory2.frontmatter;
+    return fm.type !== "session_recap" && fm.status !== "rejected" && fm.status !== "deprecated";
+  });
+  for (let i = 0; i < candidates.length; i++) {
+    for (let j = i + 1; j < candidates.length; j++) {
+      const a = candidates[i];
+      const b = candidates[j];
+      if (a.memory.frontmatter.scope !== b.memory.frontmatter.scope) continue;
+      if (a.memory.frontmatter.type !== b.memory.frontmatter.type) continue;
+      const score = jaccard2(tokenSet(a.memory.body), tokenSet(b.memory.body));
+      if (score >= 0.72) {
+        out.push({
+          id: a.memory.frontmatter.id,
+          otherId: b.memory.frontmatter.id,
+          file: a.filePath,
+          score
+        });
+      }
+    }
   }
   return out;
 }
+function tokenSet(body) {
+  return new Set(
+    (body.toLowerCase().match(/\b[a-z0-9]{4,}\b/g) ?? []).filter((word) => !["this", "that", "with", "from", "have"].includes(word))
+  );
+}
+function jaccard2(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let inter = 0;
+  for (const item of a) if (b.has(item)) inter++;
+  return inter / (a.size + b.size - inter);
+}
 function registerMemoryLint(parent) {
   parent.command("lint").description(
     "Heuristic corpus checks (anchors on key types, headings, verbosity). Static analysis only."
@@ -11441,9 +11743,9 @@ function registerMemoryConflictCandidates(memory2) {
 }
 
 // src/commands/enforce.ts
-import { spawn as spawn5 } from "child_process";
+import { execFileSync as execFileSync2, spawn as spawn5 } from "child_process";
 import { existsSync as existsSync68 } from "fs";
-import { chmod as chmod2, mkdir as mkdir19, readFile as readFile17, rm as rm3, writeFile as writeFile31 } from "fs/promises";
+import { chmod as chmod2, mkdir as mkdir19, readFile as readFile18, rm as rm3, writeFile as writeFile31 } from "fs/promises";
 import path47 from "path";
 import "commander";
 import {
@@ -11749,6 +12051,7 @@ async function buildEnforcementReport(dir, stage, sessionId) {
       findings: [{ severity: "info", code: "enforcement-off", message: "hAIve enforcement is disabled." }]
     };
   }
+  findings.push(...await inspectIntegrationVersions(root, "0.9.16"));
   if (config.enforcement?.requireBriefingFirst !== false && stage !== "ci") {
     const hasBriefing = await hasRecentBriefingMarker(paths, sessionId);
     findings.push(hasBriefing ? { severity: "ok", code: "briefing-loaded", message: "A recent hAIve briefing marker exists." } : {
@@ -11937,6 +12240,71 @@ async function findGeneratedArtifacts(paths) {
     impact: 10
   }];
 }
+async function inspectIntegrationVersions(root, expectedVersion) {
+  const files = [
+    ".git/hooks/pre-commit",
+    ".git/hooks/pre-push",
+    ".claude/settings.local.json",
+    ".mcp.json",
+    ".cursor/mcp.json",
+    ".vscode/mcp.json"
+  ];
+  const findings = [];
+  for (const rel of files) {
+    const file = path47.join(root, rel);
+    if (!existsSync68(file)) continue;
+    const text = await readFile18(file, "utf8").catch(() => "");
+    for (const bin of extractAbsoluteHaiveBins2(text)) {
+      const version = versionForBinary2(bin);
+      if (!version) {
+        findings.push({
+          severity: "warn",
+          code: "integration-haive-binary-missing",
+          message: `${rel} references ${bin}, but that binary could not be executed.`,
+          fix: "Run `haive agent setup --no-global` or `haive enforce install` to refresh project integrations.",
+          impact: 0
+        });
+      } else if (version !== expectedVersion) {
+        findings.push({
+          severity: "warn",
+          code: "integration-haive-version-mismatch",
+          message: `${rel} references hAIve ${version} at ${bin}; current hAIve is ${expectedVersion}.`,
+          fix: "Run `haive agent setup --no-global` and `haive enforce install` to repair stale hooks/configs.",
+          impact: 0
+        });
+      }
+    }
+  }
+  if (findings.length === 0) {
+    return [{
+      severity: "ok",
+      code: "integration-version-check",
+      message: "No stale absolute hAIve binary paths were found in project hooks/MCP configs."
+    }];
+  }
+  return findings;
+}
+function extractAbsoluteHaiveBins2(text) {
+  const out = /* @__PURE__ */ new Set();
+  const re = /(["'\s])((?:\/[^"'\s]+)*\/haive)\b/g;
+  let match;
+  while (match = re.exec(text)) {
+    if (match[2]) out.add(match[2]);
+  }
+  return [...out].sort();
+}
+function versionForBinary2(bin) {
+  try {
+    const out = execFileSync2(bin, ["--version"], {
+      encoding: "utf8",
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    return out.match(/\d+\.\d+\.\d+/)?.[0] ?? null;
+  } catch {
+    return null;
+  }
+}
 async function getChangedFiles(root, stage) {
   const commands = stage === "pre-commit" ? [["diff", "--cached", "--name-only"]] : [
     ["diff", "--cached", "--name-only"],
@@ -11996,7 +12364,7 @@ haive enforce check --stage pre-push --dir . || exit $?
   for (const hook of hooks) {
     const file = path47.join(hooksDir, hook.name);
     if (existsSync68(file)) {
-      const current = await readFile17(file, "utf8").catch(() => "");
+      const current = await readFile18(file, "utf8").catch(() => "");
       if (current.includes(ENFORCE_HOOK_MARKER)) {
         await writeFile31(file, hook.body, "utf8");
       } else {
@@ -12141,7 +12509,7 @@ function registerRun(program2) {
 
 // src/index.ts
 var program = new Command51();
-program.name("haive").description("hAIve \u2014 policy enforcement layer for AI coding agents").version("0.9.14");
+program.name("haive").description("hAIve \u2014 policy enforcement layer for AI coding agents").version("0.9.16").option("--advanced", "show maintenance and experimental commands in help");
 registerInit(program);
 registerWelcome(program);
 registerResolveProject(program);
@@ -12194,6 +12562,32 @@ registerBenchmark(program);
 registerDoctor(program);
 registerPlayback(program);
 registerPrecommit(program);
+var CORE_ROOT_COMMANDS = /* @__PURE__ */ new Set([
+  "init",
+  "doctor",
+  "agent",
+  "enforce",
+  "run",
+  "briefing",
+  "sync",
+  "mcp",
+  "memory",
+  "session",
+  "precommit",
+  "welcome"
+]);
+var CORE_MEMORY_COMMANDS = /* @__PURE__ */ new Set([
+  "add",
+  "list",
+  "query",
+  "show",
+  "verify",
+  "lint",
+  "tried",
+  "rm"
+]);
+var CORE_SESSION_COMMANDS = /* @__PURE__ */ new Set(["end"]);
+applySurfaceVisibility(program);
 program.parseAsync(process.argv).catch((err) => {
   if (isZodError(err)) {
     for (const issue of err.issues) {
@@ -12205,6 +12599,44 @@ program.parseAsync(process.argv).catch((err) => {
   }
   process.exit(1);
 });
+function applySurfaceVisibility(root) {
+  const showAdvanced = process.argv.includes("--advanced") || process.env.HAIVE_SHOW_ADVANCED === "1";
+  if (!showAdvanced) hideNonCoreCommands(root);
+  root.addHelpText(
+    "after",
+    [
+      "",
+      "Default help shows the core hAIve harness: init, doctor, agent setup, briefing, enforcement,",
+      "sync, session recaps, and high-signal memory commands.",
+      "Run `haive --advanced --help` or set HAIVE_SHOW_ADVANCED=1 to show maintenance and experimental commands."
+    ].join("\n")
+  );
+  const memoryCommand = root.commands.find((cmd) => cmd.name() === "memory");
+  memoryCommand?.addHelpText(
+    "after",
+    [
+      "",
+      "Default help shows the memory commands that support the core harness workflow.",
+      "Run `haive --advanced memory --help` or set HAIVE_SHOW_ADVANCED=1 to show review, import, digest, timeline, and conflict tools."
+    ].join("\n")
+  );
+}
+function hideNonCoreCommands(command) {
+  for (const child of command.commands) {
+    if (!isCoreCommand(command, child)) {
+      child._hidden = true;
+    }
+    hideNonCoreCommands(child);
+  }
+}
+function isCoreCommand(parent, child) {
+  const parentName = parent.name();
+  const childName = child.name();
+  if (parentName === "haive") return CORE_ROOT_COMMANDS.has(childName);
+  if (parentName === "memory") return CORE_MEMORY_COMMANDS.has(childName);
+  if (parentName === "session") return CORE_SESSION_COMMANDS.has(childName);
+  return true;
+}
 function isZodError(err) {
   return err !== null && typeof err === "object" && "issues" in err && Array.isArray(err.issues);
 }