@hiveai/cli 0.9.16 → 0.9.17

package/dist/index.js

@@ -198,7 +198,7 @@ async function getHotFiles(root, daysBack, maxHotFiles, filePaths) {
       if (!f) continue;
       counts.set(f, (counts.get(f) ?? 0) + 1);
     }
-    let entries = [...counts.entries()].map(([path48, changes]) => ({ path: path48, changes }));
+    let entries = [...counts.entries()].map(([path49, changes]) => ({ path: path49, changes }));
     const lowerPaths = filePaths.map((p) => p.toLowerCase());
     if (lowerPaths.length > 0) {
       entries = entries.filter((e) => lowerPaths.some((p) => e.path.toLowerCase().includes(p)));
@@ -288,7 +288,7 @@ var TokenBudgetWriter = class {
 function registerBriefing(program2) {
   program2.command("briefing").description(
     'Print the full project briefing: last session recap + project context + relevant memories.\n  Equivalent to calling get_briefing via MCP. Run before starting any task.\n\n  Examples:\n    haive briefing\n    haive briefing --task "add Stripe payment" --files src/payments/PaymentService.ts\n    haive briefing --budget quick --task "tiny fix"\n'
-  ).option("--task <text>", "what you are about to do \u2014 filters memories by relevance").option("--files <csv>", "comma-separated file paths being worked on (surfaces anchored memories)").option("--symbols <csv>", "symbol names to look up in the code-map (e.g. PaymentService,TenantFilter) \u2014 requires haive index code").option("--max-memories <n>", "cap on memories surfaced", "10").option("--max-tokens <n>", "approximate token budget for the entire briefing (truncates if exceeded)").option("--explain-source", "annotate each memory with [source: <relative-path> \xB7 anchors: <files>] for traceable citations").option("--radar", "force project radar (recent commits, open TODOs, hot files) even when memories are plentiful").option("--no-radar", "disable the project radar even when memories are scarce").option(
+  ).option("--task <text>", "what you are about to do \u2014 filters memories by relevance").option("--files <csv>", "comma-separated file paths being worked on (surfaces anchored memories)").option("--symbols <csv>", "symbol names to look up in the code-map (e.g. PaymentService,TenantFilter) \u2014 requires haive index code").option("--max-memories <n>", "cap on memories surfaced", "8").option("--max-tokens <n>", "approximate token budget for the entire briefing (truncates if exceeded)").option("--explain-source", "annotate each memory with [source: <relative-path> \xB7 anchors: <files>] for traceable citations").option("--radar", "force project radar (recent commits, open TODOs, hot files) even when memories are plentiful").option("--no-radar", "disable the project radar even when memories are scarce").option(
     "--budget <preset>",
     "align with MCP get_briefing budget_preset: quick | balanced | deep \u2014 sets cap + truncation budget (overrides --max-memories / replaces default open-ended output)",
     void 0
@@ -325,7 +325,7 @@ function registerBriefing(program2) {
       if (b === "quick" || b === "balanced" || b === "deep") budgetPreset = b;
       else ui.warn(`Unknown --budget '${opts.budget}' \u2014 ignoring (use quick|balanced|deep).`);
     }
-    let maxMemories = Math.max(1, Number(opts.maxMemories ?? 10));
+    let maxMemories = Math.max(1, Number(opts.maxMemories ?? 8));
     let budgetTokensCap = opts.maxTokens ? Math.max(100, Number(opts.maxTokens)) : null;
     if (budgetPreset !== null) {
       const presetNums = resolveBriefingBudget(budgetPreset, {
@@ -470,7 +470,22 @@ function registerBriefing(program2) {
     const usageIndex = await loadUsageIndex(paths).catch(() => null);
     out(`${ui.bold("=== Relevant Memories ===")}
 `);
-    for (const item of top) {
+    const priorities = top.map(
+      (item) => classifyCliPriority(
+        item,
+        filePaths,
+        tokens,
+        Boolean(andTaskHits?.has(item.memory.frontmatter.id)),
+        Boolean(useOrFallback && tokens && literalMatchesAnyToken(item.memory, tokens))
+      )
+    );
+    const mustReadCount = priorities.filter((p) => p === "must_read").length;
+    const usefulCount = priorities.filter((p) => p === "useful").length;
+    const backgroundCount = priorities.filter((p) => p === "background").length;
+    const quality = mustReadCount > 0 || usefulCount > 0 ? backgroundCount > mustReadCount + usefulCount && backgroundCount > 2 ? "noisy" : "strong" : "thin";
+    out(ui.dim(`briefing_quality: ${quality} \xB7 must_read=${mustReadCount} useful=${usefulCount} background=${backgroundCount}`));
+    out("");
+    for (const [idx, item] of top.entries()) {
       if (stopped()) break;
       const fm = item.memory.frontmatter;
       const badge = ui.statusBadge(fm.status);
@@ -479,8 +494,9 @@ function registerBriefing(program2) {
       const originMarker = item.origin ? ` ${ui.yellow("[from " + item.origin + "]")}` : "";
       const reads = usageIndex?.by_id[fm.id]?.read_count ?? 0;
       const hitMarker = reads > 0 ? ` ${ui.dim("\xB7 " + reads + "\xD7 read")}` : "";
+      const priority = priorities[idx] ?? "background";
       out(
-        `${ui.bold(fm.id)}  ${ui.dim(fm.scope + "/" + fm.type)}  ${badge}${draftMarker}${unverifiedMarker}${originMarker}${hitMarker}`
+        `${ui.bold(fm.id)}  ${priorityBadge(priority)}  ${ui.dim(fm.scope + "/" + fm.type)}  ${badge}${draftMarker}${unverifiedMarker}${originMarker}${hitMarker}`
       );
       if (opts.explainSource) {
         const relPath = path.relative(root, item.filePath);
@@ -551,6 +567,20 @@ ${ui.bold("=== Symbol Locations ===")}
     }
   });
 }
+function classifyCliPriority(item, filePaths, tokens, exactTaskHit, partialTaskHit) {
+  const fm = item.memory.frontmatter;
+  const anchored = filePaths.length > 0 && memoryMatchesAnchorPaths(item.memory, filePaths);
+  if (anchored || fm.type === "attempt" && exactTaskHit) return "must_read";
+  if (exactTaskHit || partialTaskHit || item.score >= 4 || tokens && fm.tags.some((tag) => tokens.includes(tag))) {
+    return "useful";
+  }
+  return "background";
+}
+function priorityBadge(priority) {
+  if (priority === "must_read") return ui.red("[must_read]");
+  if (priority === "useful") return ui.yellow("[useful]");
+  return ui.dim("[background]");
+}
 function parseCsv(value) {
   if (!value) return [];
   return value.split(",").map((s) => s.trim()).filter(Boolean);
@@ -3054,6 +3084,7 @@ import {
   extractActionsBriefBody as extractActionsBriefBody2,
   getUsage as getUsage5,
   inferModulesFromPaths as inferModulesFromPaths2,
+  isGlobPath,
   isAutoPromoteEligible,
   isDecaying,
   literalMatchesAllTokens as literalMatchesAllTokens22,
@@ -3352,7 +3383,6 @@ async function memSave(input, ctx) {
       const { similarityWarning: simW, body_similar: bs } = bodySimilarWarnings(/* @__PURE__ */ new Set([fm.id]));
       const newFrontmatter = {
         ...fm,
-        body: input.body,
         tags: input.tags.length ? input.tags : fm.tags,
         revision_count: (fm.revision_count ?? 0) + 1,
         anchor: {
@@ -3368,6 +3398,7 @@ async function memSave(input, ctx) {
       );
       const mergedTw = [
         invalidPaths.length > 0 ? `Anchor path(s) not found in project: ${invalidPaths.join(", ")}. They will be marked stale by haive sync.` : null,
+        criticalAnchorWarning(input.type, fm.status, newFrontmatter.anchor.paths, newFrontmatter.anchor.symbols),
         simW ?? null
       ].filter(Boolean).join(" \u2014 ") || void 0;
       return {
@@ -3423,6 +3454,7 @@ async function memSave(input, ctx) {
   const { similarityWarning: simWarnNew, body_similar: bsNew } = bodySimilarWarnings();
   const finalWarning = [
     invalidPaths.length > 0 ? `Anchor path(s) not found in project: ${invalidPaths.join(", ")}. They will be marked stale by \`haive sync\`.` : null,
+    criticalAnchorWarning(frontmatter.type, frontmatter.status, frontmatter.anchor.paths, frontmatter.anchor.symbols),
     warning ?? null,
     simWarnNew ?? null
   ].filter(Boolean).join(" \u2014 ") || void 0;
@@ -3437,6 +3469,12 @@ async function memSave(input, ctx) {
     ...invalidPaths.length > 0 ? { invalid_paths: invalidPaths } : {}
   };
 }
+function criticalAnchorWarning(type, status, paths, symbols) {
+  if (!["decision", "gotcha", "architecture"].includes(type)) return null;
+  if (status !== "validated") return null;
+  if (paths.length > 0 || symbols.length > 0) return null;
+  return `${type} is validated without paths or symbols; add anchors so hAIve can detect drift.`;
+}
 var MemSearchInputSchema = {
   query: z5.string().describe("Substring matched against id, tags, and body"),
   scope: z5.enum(["personal", "team", "module"]).optional().describe("Restrict results to a single scope"),
@@ -4458,6 +4496,7 @@ async function getBriefing(input, ctx) {
         reasons: [reason],
         match_quality: matchQuality ?? "partial",
         ...score !== void 0 ? { semantic_score: score } : {},
+        priority: "background",
         body: loaded.memory.body,
         file_path: loaded.filePath
       });
@@ -4473,6 +4512,13 @@ async function getBriefing(input, ctx) {
         if (fm.tags.some((t) => inferred.includes(t))) addOrUpdate(loaded, "module", void 0, "partial");
       }
     }
+    if (input.symbols.length > 0) {
+      const wanted = new Set(input.symbols.map((s) => s.toLowerCase()));
+      for (const loaded of allMemories) {
+        const symbols = loaded.memory.frontmatter.anchor.symbols.map((s) => s.toLowerCase());
+        if (symbols.some((s) => wanted.has(s))) addOrUpdate(loaded, "symbol", void 0, "exact");
+      }
+    }
     if (input.task) {
       const tokens = tokenizeQuery22(input.task);
       const andHits = allMemories.filter((m) => literalMatchesAllTokens22(m.memory, tokens));
@@ -4498,11 +4544,12 @@ async function getBriefing(input, ctx) {
       }
     }
     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("module") ? 2 : 0) + (m.reasons.includes("semantic") ? 2 : 0) + (m.reasons.includes("domain") ? 1 : 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 = reasonScore(a) + confidenceScore(a) + (a.semantic_score ?? 0);
-      const sb = reasonScore(b) + confidenceScore(b) + (b.semantic_score ?? 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);
       return sb - sa;
     });
     for (const mem of ranked.slice(0, briefingMaxMemories)) {
@@ -4661,8 +4708,15 @@ ${m.content}`).join("\n\n---\n\n"),
   })) : trimmedMemories;
   const outputMemories = formattedMemories.map((m) => ({
     ...m,
+    priority: classifyMemoryPriority(m, byId.get(m.id), input.files, input.symbols),
     why: explainWhySurfaced(m, byId.get(m.id), input.files, inferred)
   }));
+  const briefingQuality = classifyBriefingQuality(outputMemories, {
+    isTemplateContext,
+    autoContextGenerated,
+    hasLastSession: Boolean(lastSession),
+    searchMode
+  });
   let symbolLocations;
   const symbolsToLookup = new Set(input.symbols);
   for (const m of outputMemories) {
@@ -4803,6 +4857,7 @@ When done, call \`mem_session_end\` to acknowledge \u2014 this clears the pendin
     } : null,
     module_contexts: trimmedModules,
     memories: outputMemories,
+    briefing_quality: briefingQuality,
     ...symbolLocations ? { symbol_locations: symbolLocations } : {},
     action_required: actionRequired,
     decay_warnings: decayWarnings,
@@ -4828,6 +4883,53 @@ function compactSummary(body) {
   }
   return body.slice(0, 120);
 }
+function classifyMemoryPriority(memory2, 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 = (memory2.semantic_score ?? 0) >= 0.65;
+  const usefulSemantic = (memory2.semantic_score ?? 0) >= 0.35;
+  if (fm?.requires_human_approval || directAnchor || directSymbol || memory2.type === "attempt" && (memory2.match_quality === "exact" || strongSemantic)) {
+    return "must_read";
+  }
+  if (memory2.reasons.includes("module") || memory2.reasons.includes("domain") || memory2.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(memory2, loaded, inputFiles, inferredModules) {
   const why = [];
   const fm = loaded?.memory.frontmatter;
@@ -4836,7 +4938,19 @@ function explainWhySurfaced(memory2, loaded, inputFiles, inferredModules) {
       (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(", ")}`);
+      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(", ")}`);
     }
@@ -4844,6 +4958,9 @@ function explainWhySurfaced(memory2, loaded, inputFiles, inferredModules) {
       why.push(`Anchor symbol${fm.anchor.symbols.length === 1 ? "" : "s"}: ${fm.anchor.symbols.slice(0, 4).join(", ")}`);
     }
   }
+  if (memory2.reasons.includes("symbol") && fm) {
+    why.push(`Explicit symbol match: ${fm.anchor.symbols.slice(0, 4).join(", ")}`);
+  }
   if (memory2.reasons.includes("module")) {
     const moduleHints = [
       ...memory2.module ? [memory2.module] : [],
@@ -5068,7 +5185,8 @@ async function memRelevantTo(input, ctx) {
   const out = {
     task: input.task,
     search_mode: briefing.search_mode,
-    memories: briefing.memories
+    memories: briefing.memories,
+    briefing_quality: briefing.briefing_quality
   };
   if (briefing.hints && briefing.hints.length > 0) out.hints = briefing.hints;
   if (briefing.memories.length === 0) out.empty = true;
@@ -5750,7 +5868,7 @@ 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 classifiedWarnings = apResult.warnings.map(classifyWarning);
+  const classifiedWarnings = apResult.warnings.map((warning) => classifyWarning(warning, input.paths));
   const blockingWarnings = classifiedWarnings.filter((w) => w.level === "blocking");
   const reviewWarnings = classifiedWarnings.filter((w) => w.level === "review");
   const infoWarnings = classifiedWarnings.filter((w) => w.level === "info");
@@ -5785,12 +5903,26 @@ async function preCommitCheck(input, ctx) {
     }))
   };
 }
-function classifyWarning(warning) {
+function classifyWarning(warning, paths) {
+  const affectedFiles = paths.filter((p) => !p.startsWith(".ai/.usage/"));
+  const repairCommand = repairCommandForWarning(warning, affectedFiles);
+  const fileDowngrade = fileTypeDowngradeReason(warning, affectedFiles);
+  if (fileDowngrade) {
+    return {
+      ...warning,
+      level: "info",
+      rationale: fileDowngrade,
+      affected_files: affectedFiles,
+      repair_command: repairCommand
+    };
+  }
   if (isBlockingWarning(warning)) {
     return {
       ...warning,
       level: "blocking",
-      rationale: "authoritative/trusted memory plus strong semantic match to the diff (score >= 0.65)"
+      rationale: "authoritative/trusted memory plus strong semantic match to the diff (score >= 0.65)",
+      affected_files: affectedFiles,
+      repair_command: repairCommand
     };
   }
   const hasSemantic = warning.reasons.includes("semantic");
@@ -5800,13 +5932,17 @@ function classifyWarning(warning) {
     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"
+      rationale: hasSemantic ? "semantic match is plausible but below blocking threshold" : "anchored high-confidence memory also matched diff tokens, but no strong semantic proof",
+      affected_files: affectedFiles,
+      repair_command: repairCommand
     };
   }
   return {
     ...warning,
     level: "info",
-    rationale: "weak signal only (literal/anchor/low semantic evidence); surfaced for audit, hidden in concise CLI output"
+    rationale: "weak signal only (literal/anchor/low semantic evidence); surfaced for audit, hidden in concise CLI output",
+    affected_files: affectedFiles,
+    repair_command: repairCommand
   };
 }
 function isBlockingWarning(warning) {
@@ -5814,6 +5950,40 @@ function isBlockingWarning(warning) {
   if (!highConfidence) return false;
   return warning.reasons.includes("semantic") && (warning.semantic_score ?? 0) >= 0.65;
 }
+function fileTypeDowngradeReason(warning, paths) {
+  if (paths.length === 0) return null;
+  if (paths.every((p) => p.startsWith(".ai/.usage/") || p === ".ai/.usage/tool-usage.jsonl")) {
+    return ".ai usage logs are local telemetry and never block commits.";
+  }
+  const docsOnly = paths.every(isDocLikePath);
+  if (docsOnly && !hasStrongSemantic(warning)) {
+    return "docs/changelog-only change; anti-pattern is downgraded unless semantic evidence is strong.";
+  }
+  const configOnly = paths.every(isPackageOrConfigPath);
+  if (configOnly && looksRuntimeSpecific(warning) && !warning.reasons.includes("anchor") && !hasStrongSemantic(warning)) {
+    return "package/config-only change; runtime-specific gotcha is not anchored or semantically strong.";
+  }
+  return null;
+}
+function hasStrongSemantic(warning) {
+  return warning.reasons.includes("semantic") && (warning.semantic_score ?? 0) >= 0.65;
+}
+function isDocLikePath(file) {
+  const lower = file.toLowerCase();
+  return lower.endsWith(".md") || lower.includes("changelog") || lower.startsWith("docs/") || lower.startsWith(".github/") && lower.endsWith(".md");
+}
+function isPackageOrConfigPath(file) {
+  const lower = file.toLowerCase();
+  return lower.endsWith("package.json") || lower.endsWith("package-lock.json") || lower.endsWith("pnpm-lock.yaml") || lower.endsWith("yarn.lock") || lower.endsWith("bun.lockb") || lower.endsWith(".config.ts") || lower.endsWith(".config.js") || lower.endsWith(".json") || lower.endsWith(".yml") || lower.endsWith(".yaml") || lower.startsWith(".github/workflows/");
+}
+function looksRuntimeSpecific(warning) {
+  const text = `${warning.body_preview} ${warning.id}`.toLowerCase();
+  return /\b(runtime|controller|request|response|database|transaction|auth|cache|production|service|api|endpoint)\b/.test(text);
+}
+function repairCommandForWarning(warning, paths) {
+  const firstPath = paths[0];
+  return firstPath ? `haive briefing --files "${firstPath}" --task "review ${warning.id}"` : `haive memory show ${warning.id}`;
+}
 var CONFIG_PATTERNS = [
   ".eslintrc",
   "eslint.config",
@@ -6345,7 +6515,7 @@ When done, respond with: "Imported N memories: [list of IDs]" or "Nothing action
   };
 }
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.9.16";
+var SERVER_VERSION = "0.9.17";
 function jsonResult(data) {
   return {
     content: [
@@ -10780,7 +10950,7 @@ var MS_PER_DAY3 = 24 * 60 * 60 * 1e3;
 function registerDoctor(program2) {
   program2.command("doctor").description(
     "Analyze the local hAIve setup and emit actionable recommendations.\n\n  Inspects: project-context status, memory health (stale/anchorless/decay/pending),\n  code-map freshness, usage log signals (low-hit briefings, repeated empty searches).\n\n  Read-only by default. Pass --fix to suggest commands you can copy-paste."
-  ).option("--json", "emit JSON instead of human-readable output", false).option("--fix", "include suggested fix commands in human output", false).option("-d, --dir <dir>", "project root").action(async (opts) => {
+  ).option("--json", "emit JSON instead of human-readable output", false).option("--fix", "include suggested fix commands in human output", false).option("--dry-run", "with --fix, show delegated repairs without applying them", false).option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot40(opts.dir);
     const paths = resolveHaivePaths36(root);
     const findings = [];
@@ -10952,14 +11122,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"));
+    findings.push(...await collectInstallFindings(root, "0.9.17"));
     try {
       const legacyRaw = execSync3("haive-mcp --version", {
         encoding: "utf8",
         timeout: 3e3,
         stdio: ["ignore", "pipe", "ignore"]
       }).trim();
-      const cliVersion = "0.9.16";
+      const cliVersion = "0.9.17";
       if (legacyRaw && legacyRaw !== cliVersion) {
         findings.push({
           severity: "warn",
@@ -10976,33 +11146,105 @@ npm uninstall -g @hiveai/mcp`
   });
 }
 function emit(findings, opts) {
+  const classified = findings.map((finding) => ({
+    ...finding,
+    section: finding.section ?? sectionForFinding(finding)
+  }));
+  const scores = computeDoctorScores(classified);
   if (opts.json) {
-    console.log(JSON.stringify({ findings }, null, 2));
+    console.log(JSON.stringify({
+      scores,
+      findings: classified,
+      sections: groupBySection(classified),
+      next_actions: nextActions(classified),
+      fix_mode: opts.fix ? opts.dryRun ? "dry-run" : "suggest" : "off"
+    }, null, 2));
     return;
   }
-  if (findings.length === 0) {
+  if (classified.length === 0) {
     ui.success("hAIve doctor \u2014 no issues found.");
     return;
   }
-  console.log(ui.bold(`hAIve doctor \u2014 ${findings.length} finding${findings.length === 1 ? "" : "s"}`));
+  console.log(ui.bold(`hAIve doctor \u2014 ${classified.length} finding${classified.length === 1 ? "" : "s"}`));
+  console.log(
+    ui.dim(
+      `  protection=${scores.protection_score}  context=${scores.context_quality_score}  corpus=${scores.corpus_quality_score}`
+    )
+  );
   console.log();
-  const order = ["error", "warn", "info"];
-  for (const sev of order) {
-    for (const f of findings.filter((x) => x.severity === sev)) {
-      const icon = sev === "error" ? ui.red("\u2717") : sev === "warn" ? ui.yellow("\u26A0") : ui.dim("\u2139");
-      console.log(`${icon} ${ui.bold(f.code)}  ${f.message}`);
-      if (opts.fix && f.fix) {
-        for (const line of f.fix.split("\n")) {
-          console.log(`     ${ui.dim("$")} ${line}`);
+  const sectionOrder = [
+    "Protection",
+    "Agent coverage",
+    "Context quality",
+    "Corpus health",
+    "Index health",
+    "Next actions"
+  ];
+  const severityOrder = ["error", "warn", "info"];
+  for (const section2 of sectionOrder) {
+    const sectionFindings = classified.filter((f) => f.section === section2);
+    if (sectionFindings.length === 0) continue;
+    console.log(ui.bold(section2));
+    for (const sev of severityOrder) {
+      for (const f of sectionFindings.filter((x) => x.severity === sev)) {
+        const icon = sev === "error" ? ui.red("\u2717") : sev === "warn" ? ui.yellow("\u26A0") : ui.dim("\u2139");
+        console.log(`${icon} ${ui.bold(f.code)}  ${f.message}`);
+        if (opts.fix && f.fix) {
+          for (const line of f.fix.split("\n")) {
+            console.log(`     ${ui.dim(opts.dryRun ? "would run:" : "$")} ${line}`);
+          }
         }
       }
     }
-  }
-  if (!opts.fix && findings.some((f) => f.fix)) {
     console.log();
+  }
+  const actions = nextActions(classified);
+  if (actions.length > 0) {
+    console.log(ui.bold("Next actions"));
+    for (const action of actions.slice(0, 5)) console.log(`  ${ui.dim("$")} ${action}`);
+  } else if (!opts.fix && classified.some((f) => f.fix)) {
     ui.info("Re-run with --fix to see suggested commands.");
   }
 }
+function sectionForFinding(finding) {
+  if (finding.code.includes("haive") || finding.code.includes("integration") || finding.code.includes("claude") || finding.code.includes("autopilot")) return "Agent coverage";
+  if (finding.code.includes("context") || finding.code.includes("briefing") || finding.code.includes("search")) return "Context quality";
+  if (finding.code.includes("code-map") || finding.code.includes("index")) return "Index health";
+  if (finding.code.includes("memory") || finding.code.includes("anchor") || finding.code.includes("pending") || finding.code.includes("decay")) return "Corpus health";
+  if (finding.severity === "error") return "Protection";
+  return "Next actions";
+}
+function computeDoctorScores(findings) {
+  const scoreFor = (sections) => {
+    const scoped = findings.filter((f) => sections.includes(f.section ?? sectionForFinding(f)));
+    const penalty = scoped.reduce((sum, f) => {
+      if (f.severity === "error") return sum + 35;
+      if (f.severity === "warn") return sum + 15;
+      return sum + 4;
+    }, 0);
+    return Math.max(0, 100 - penalty);
+  };
+  return {
+    protection_score: scoreFor(["Protection", "Agent coverage"]),
+    context_quality_score: scoreFor(["Context quality", "Index health"]),
+    corpus_quality_score: scoreFor(["Corpus health"])
+  };
+}
+function groupBySection(findings) {
+  const out = {
+    "Protection": [],
+    "Agent coverage": [],
+    "Context quality": [],
+    "Corpus health": [],
+    "Index health": [],
+    "Next actions": []
+  };
+  for (const finding of findings) out[finding.section ?? sectionForFinding(finding)].push(finding);
+  return out;
+}
+function nextActions(findings) {
+  return [...new Set(findings.flatMap((finding) => finding.fix ? finding.fix.split("\n") : []))].filter(Boolean);
+}
 function isSearchTool(name) {
   return ["mem_search", "code_search", "mem_relevant_to", "get_briefing"].includes(name);
 }
@@ -11321,7 +11563,11 @@ function printWarnings(title, warnings, tone) {
       console.log(`     ${ui.dim(line)}`);
     }
     console.log(`     ${ui.dim("reasons:")} ${w.reasons.join(", ")}`);
+    if (w.affected_files && w.affected_files.length > 0) {
+      console.log(`     ${ui.dim("files:")} ${w.affected_files.slice(0, 4).join(", ")}`);
+    }
     if (w.rationale) console.log(`     ${ui.dim("why shown:")} ${w.rationale}`);
+    if (w.repair_command) console.log(`     ${ui.dim("repair:")} ${w.repair_command}`);
   }
   console.log();
 }
@@ -11408,20 +11654,26 @@ function registerWelcome(program2) {
 
 // src/commands/memory-lint.ts
 import { existsSync as existsSync64 } from "fs";
+import { writeFile as writeFile31 } from "fs/promises";
+import path43 from "path";
 import "commander";
 import {
   findProjectRoot as findProjectRoot44,
   getUsage as getUsage20,
+  loadCodeMap as loadCodeMap6,
   loadMemoriesFromDir as loadMemoriesFromDir35,
   loadUsageIndex as loadUsageIndex26,
-  resolveHaivePaths as resolveHaivePaths40
+  resolveHaivePaths as resolveHaivePaths40,
+  serializeMemory as serializeMemory26
 } from "@hiveai/core";
-async function lintMemoriesAsync(root) {
+async function lintMemoriesAsync(root, options = {}) {
   const paths = resolveHaivePaths40(root);
   const out = [];
-  if (!existsSync64(paths.memoriesDir)) return out;
+  const fixes = [];
+  if (!existsSync64(paths.memoriesDir)) return { findings: out, fixes };
   const loaded = await loadMemoriesFromDir35(paths.memoriesDir);
   const usage = await loadUsageIndex26(paths);
+  const codeMap = await loadCodeMap6(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) {
@@ -11447,13 +11699,15 @@ async function lintMemoriesAsync(root) {
         message: "Record does not contain obvious action/rationale words. Add the concrete rule, why it exists, and what to do instead."
       });
     }
+    const suggestedAnchors = suggestAnchors(root, { filePath, memory: memory2 }, codeMap);
     if (ANCHOR_TYPES.has(fm.type) && fm.anchor.paths.length === 0 && fm.status === "validated") {
       out.push({
         file: filePath,
         id: fm.id,
         severity: "warn",
         code: "MISSING_ANCHOR",
-        message: `${fm.type} is validated without anchor paths \u2014 add anchor.paths so haive sync can flag staleness.`
+        message: `${fm.type} is validated without anchor paths \u2014 add anchor.paths so haive sync can flag staleness.`,
+        ...suggestedAnchors.paths.length > 0 || suggestedAnchors.symbols.length > 0 ? { suggested_anchors: suggestedAnchors } : {}
       });
     }
     if (fm.status === "stale" && !fm.stale_reason) {
@@ -11494,6 +11748,34 @@ async function lintMemoriesAsync(root) {
         message: "Validated record has never been surfaced/read. Consider improving tags/anchors or archiving it if it is not useful."
       });
     }
+    if (options.fix) {
+      const actions = [];
+      let nextBody = memory2.body;
+      let nextFrontmatter = memory2.frontmatter;
+      if (!hasMarkdownHeading) {
+        nextBody = `# ${titleFromId(fm.id)}
+
+${nextBody.trim()}`;
+        actions.push("add missing Markdown heading");
+      }
+      if (ANCHOR_TYPES.has(fm.type) && fm.anchor.paths.length === 0 && fm.anchor.symbols.length === 0 && fm.status === "validated" && !fm.tags.includes("needs_anchor")) {
+        nextFrontmatter = {
+          ...nextFrontmatter,
+          tags: [...nextFrontmatter.tags, "needs_anchor"]
+        };
+        actions.push("tag validated anchorless record with needs_anchor");
+      }
+      if (actions.length > 0) {
+        fixes.push({ file: filePath, id: fm.id, actions, applied: Boolean(options.apply) });
+        if (options.apply) {
+          await writeFile31(
+            filePath,
+            serializeMemory26({ frontmatter: nextFrontmatter, body: nextBody }),
+            "utf8"
+          );
+        }
+      }
+    }
   }
   for (const dup of nearDuplicatePairs(loaded)) {
     out.push({
@@ -11504,7 +11786,39 @@ async function lintMemoriesAsync(root) {
       message: `Body overlaps ~${Math.round(dup.score * 100)}% with ${dup.otherId}. Merge or deprecate one record to reduce briefing noise.`
     });
   }
-  return out;
+  return { findings: out, fixes };
+}
+function titleFromId(id) {
+  const withoutDate = id.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+  return withoutDate.split("-").filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join(" ");
+}
+function suggestAnchors(root, loaded, codeMap) {
+  const body = loaded.memory.body;
+  const paths = /* @__PURE__ */ new Set();
+  const symbols = /* @__PURE__ */ new Set();
+  for (const match of body.matchAll(/`([^`\n]+\.[A-Za-z0-9]+)`|(?:^|\s)([A-Za-z0-9_./-]+\.[A-Za-z0-9]+)/gm)) {
+    const candidate = (match[1] ?? match[2] ?? "").replace(/^\.?\//, "");
+    if (!candidate || candidate.startsWith("http")) continue;
+    if (existsSync64(path43.join(root, candidate))) paths.add(candidate);
+  }
+  if (codeMap) {
+    const lowered = body.toLowerCase();
+    for (const [file, entry] of Object.entries(codeMap.files)) {
+      for (const exp of entry.exports) {
+        if (!exp.name || exp.name.length < 4) continue;
+        if (lowered.includes(exp.name.toLowerCase())) {
+          paths.add(file);
+          symbols.add(exp.name);
+        }
+        if (paths.size >= 5 && symbols.size >= 5) break;
+      }
+      if (paths.size >= 5 && symbols.size >= 5) break;
+    }
+  }
+  return {
+    paths: [...paths].slice(0, 5),
+    symbols: [...symbols].slice(0, 5)
+  };
 }
 function nearDuplicatePairs(loaded) {
   const out = [];
@@ -11545,11 +11859,20 @@ function jaccard2(a, b) {
 function registerMemoryLint(parent) {
   parent.command("lint").description(
     "Heuristic corpus checks (anchors on key types, headings, verbosity). Static analysis only."
-  ).option("--json", "emit findings as JSON", false).option("-d, --dir <dir>", "project root").action(async (opts) => {
+  ).option("--json", "emit findings as JSON", false).option("--fix", "prepare simple automatic fixes (use with --dry-run or --apply)", false).option("--dry-run", "with --fix, show files that would change without writing", false).option("--apply", "with --fix, write simple fixes to disk", false).option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot44(opts.dir);
-    const findings = await lintMemoriesAsync(root);
+    const apply = Boolean(opts.fix && opts.apply);
+    const dryRun = Boolean(opts.fix && (opts.dryRun || !opts.apply));
+    const report = await lintMemoriesAsync(root, { fix: Boolean(opts.fix), apply });
+    const findings = report.findings;
     if (opts.json) {
-      console.log(JSON.stringify({ findings_count: findings.length, findings }, null, 2));
+      console.log(JSON.stringify({
+        findings_count: findings.length,
+        findings,
+        fixes_count: report.fixes.length,
+        fixes: report.fixes,
+        fix_mode: opts.fix ? apply ? "apply" : "dry-run" : "off"
+      }, null, 2));
       process.exitCode = findings.some((f) => f.severity === "error") ? 1 : 0;
       return;
     }
@@ -11559,6 +11882,16 @@ function registerMemoryLint(parent) {
     }
     console.log(ui.bold(`memory lint (${findings.length} finding${findings.length === 1 ? "" : "s"})`) + `
 `);
+    if (opts.fix) {
+      const mode = apply ? "apply" : dryRun ? "dry-run" : "dry-run";
+      const verb = apply ? "changed" : "would change";
+      console.log(ui.bold(`fix ${mode}: ${report.fixes.length} file${report.fixes.length === 1 ? "" : "s"} ${verb}`));
+      for (const fix of report.fixes) {
+        console.log(`  ${ui.dim(fix.id)} ${fix.actions.join("; ")}`);
+        console.log(ui.dim(`       \u2192 ${fix.file}`));
+      }
+      console.log();
+    }
     const order = { error: 0, warn: 1, info: 2 };
     findings.sort((a, b) => order[a.severity] - order[b.severity] || a.id.localeCompare(b.id));
     for (const f of findings) {
@@ -11567,6 +11900,11 @@ function registerMemoryLint(parent) {
         `${color(f.severity.padEnd(5))} ${ui.dim(f.code)} ${f.id}`
       );
       console.log(`       ${f.message}`);
+      if (f.suggested_anchors) {
+        const pathHints = f.suggested_anchors.paths.length > 0 ? `paths: ${f.suggested_anchors.paths.join(", ")}` : "";
+        const symbolHints = f.suggested_anchors.symbols.length > 0 ? `symbols: ${f.suggested_anchors.symbols.join(", ")}` : "";
+        console.log(ui.dim(`       suggested anchors: ${[pathHints, symbolHints].filter(Boolean).join(" \xB7 ")}`));
+      }
       console.log(ui.dim(`       \u2192 ${f.file}`));
     }
     process.exitCode = findings.some((x) => x.severity === "error") ? 1 : 0;
@@ -11592,21 +11930,21 @@ function registerMemorySuggestTopic(memory2) {
 }
 
 // src/commands/resolve-project.ts
-import path43 from "path";
+import path44 from "path";
 import "commander";
 import { resolveProjectInfo as resolveProjectInfo2 } from "@hiveai/core";
 function registerResolveProject(program2) {
   program2.command("resolve-project").description(
     "Print JSON for hAIve project root resolution (HAIVE_PROJECT_ROOT, markers, .ai layout)."
   ).option("-d, --dir <dir>", "working directory", process.cwd()).action((opts) => {
-    const info = resolveProjectInfo2({ cwd: path43.resolve(opts.dir) });
+    const info = resolveProjectInfo2({ cwd: path44.resolve(opts.dir) });
     console.log(JSON.stringify({ ok: true, info }, null, 2));
   });
 }
 
 // src/commands/runtime-journal.ts
 import { existsSync as existsSync65 } from "fs";
-import path44 from "path";
+import path45 from "path";
 import "commander";
 import {
   appendRuntimeJournalEntry as appendRuntimeJournalEntry3,
@@ -11620,15 +11958,15 @@ function registerRuntime(program2) {
   );
   const journal = runtime.command("journal").description("Append or read the machine-local session journal (NDJSON)");
   journal.command("append").description("Append one JSON line to .ai/.runtime/session-journal.ndjson").argument("<message>", "short text to log").option("-k, --kind <kind>", "note | session_end | mcp", "note").option("-d, --dir <dir>", "project root", process.cwd()).action(async (message, opts) => {
-    const root = path44.resolve(opts.dir ?? process.cwd());
+    const root = path45.resolve(opts.dir ?? process.cwd());
     const paths = resolveHaivePaths41(findProjectRoot45(root));
     const raw = opts.kind ?? "note";
     const kind = ["note", "session_end", "mcp"].includes(raw) ? raw : "note";
     await appendRuntimeJournalEntry3(paths, { kind, message });
-    ui.success(`Appended to ${path44.relative(root, paths.runtimeDir)}/session-journal.ndjson`);
+    ui.success(`Appended to ${path45.relative(root, paths.runtimeDir)}/session-journal.ndjson`);
   });
   journal.command("tail").description("Print the last N entries from the runtime session journal as JSON").option("-n, --limit <n>", "number of lines", "30").option("-d, --dir <dir>", "project root", process.cwd()).action(async (opts) => {
-    const root = path44.resolve(opts.dir ?? process.cwd());
+    const root = path45.resolve(opts.dir ?? process.cwd());
     const paths = resolveHaivePaths41(findProjectRoot45(root));
     const limit = Math.min(500, Math.max(1, parseInt(opts.limit, 10) || 30));
     if (!existsSync65(paths.haiveDir)) {
@@ -11647,7 +11985,7 @@ function registerRuntime(program2) {
 
 // src/commands/memory-timeline.ts
 import { existsSync as existsSync66 } from "fs";
-import path45 from "path";
+import path46 from "path";
 import "commander";
 import {
   collectTimelineEntries as collectTimelineEntries2,
@@ -11663,7 +12001,7 @@ function registerMemoryTimeline(memory2) {
       process.exitCode = 1;
       return;
     }
-    const root = path45.resolve(opts.dir ?? process.cwd());
+    const root = path46.resolve(opts.dir ?? process.cwd());
     const paths = resolveHaivePaths42(findProjectRoot46(root));
     if (!existsSync66(paths.memoriesDir)) {
       ui.error("No memories \u2014 run `haive init`.");
@@ -11684,7 +12022,7 @@ function registerMemoryTimeline(memory2) {
 
 // src/commands/memory-conflict-candidates.ts
 import { existsSync as existsSync67 } from "fs";
-import path46 from "path";
+import path47 from "path";
 import "commander";
 import {
   findLexicalConflictPairs as findLexicalConflictPairs2,
@@ -11706,7 +12044,7 @@ function registerMemoryConflictCandidates(memory2) {
     "decision,architecture,convention,gotcha (lexical scan)",
     "decision,architecture"
   ).option("--min-jaccard <x>", "minimum Jaccard for lexical pairs", "0.45").option("--max-pairs <n>", "cap lexical pairs", "20").option("--max-scan <n>", "max memories scanned (lexical)", "500").option("--max-topic-pairs <n>", "cap topic/status pairs", "20").action(async (opts) => {
-    const root = path46.resolve(opts.dir ?? process.cwd());
+    const root = path47.resolve(opts.dir ?? process.cwd());
     const paths = resolveHaivePaths43(findProjectRoot47(root));
     if (!existsSync67(paths.memoriesDir)) {
       ui.error("No memories \u2014 run `haive init`.");
@@ -11745,8 +12083,8 @@ function registerMemoryConflictCandidates(memory2) {
 // src/commands/enforce.ts
 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 readFile18, rm as rm3, writeFile as writeFile31 } from "fs/promises";
-import path47 from "path";
+import { chmod as chmod2, mkdir as mkdir19, readFile as readFile18, rm as rm3, writeFile as writeFile33 } from "fs/promises";
+import path48 from "path";
 import "commander";
 import {
   findProjectRoot as findProjectRoot48,
@@ -11796,7 +12134,7 @@ function registerEnforce(program2) {
     if (opts.claude !== false) {
       try {
         const result = await installClaudeHooksAtPath(defaultClaudeSettingsPath("project", root));
-        ui.success(`${result.created ? "Created" : "Patched"} Claude Code hooks (${path47.relative(root, result.settingsPath)})`);
+        ui.success(`${result.created ? "Created" : "Patched"} Claude Code hooks (${path48.relative(root, result.settingsPath)})`);
       } catch (err) {
         ui.warn(`Claude Code hooks not installed: ${err instanceof Error ? err.message : String(err)}`);
       }
@@ -11804,26 +12142,26 @@ function registerEnforce(program2) {
     ui.info("Agent-agnostic gates are now active at workflow level: MCP, git, CI, and optional client hooks.");
     ui.info("Use `haive run -- <agent command>` for agents that do not expose blocking hooks.");
   });
-  enforce.command("status").description("Show whether this project has agent-agnostic hAIve enforcement installed.").option("-d, --dir <dir>", "project root").option("--json", "emit JSON", false).action(async (opts) => {
+  enforce.command("status").description("Show whether this project has agent-agnostic hAIve enforcement installed.").option("-d, --dir <dir>", "project root").option("--explain", "group findings by blocking/review/info and show repair commands", false).option("--json", "emit JSON", false).action(async (opts) => {
     const report = await buildEnforcementReport(opts.dir, "local");
-    printReport(report, Boolean(opts.json));
+    printReport(report, Boolean(opts.json), Boolean(opts.explain));
     if (report.should_block) process.exitCode = 1;
   });
-  enforce.command("check").description("Run the hAIve policy gate. Intended for pre-commit, pre-push, wrappers, and any agent client.").option("-d, --dir <dir>", "project root").option("--stage <stage>", "local | pre-commit | pre-push | ci", "local").option("--json", "emit JSON", false).action(async (opts) => {
+  enforce.command("check").description("Run the hAIve policy gate. Intended for pre-commit, pre-push, wrappers, and any agent client.").option("-d, --dir <dir>", "project root").option("--stage <stage>", "local | pre-commit | pre-push | ci", "local").option("--explain", "group findings by blocking/review/info and show repair commands", false).option("--json", "emit JSON", false).action(async (opts) => {
     const report = await buildEnforcementReport(opts.dir, opts.stage ?? "local");
-    printReport(report, Boolean(opts.json));
+    printReport(report, Boolean(opts.json), Boolean(opts.explain));
     if (report.should_block) process.exit(2);
   });
   enforce.command("cleanup").description("Remove generated hAIve runtime/cache artifacts that should not appear in commits.").option("-d, --dir <dir>", "project root").option("--dry-run", "print what would be removed without deleting", false).action(async (opts) => {
     const root = findProjectRoot48(opts.dir);
     const paths = resolveHaivePaths44(root);
     const targets = [
-      path47.join(paths.haiveDir, ".cache"),
-      path47.join(paths.haiveDir, ".runtime")
+      path48.join(paths.haiveDir, ".cache"),
+      path48.join(paths.haiveDir, ".runtime")
     ];
     for (const target of targets) {
       if (!existsSync68(target)) continue;
-      const rel = path47.relative(root, target);
+      const rel = path48.relative(root, target);
       if (opts.dryRun) ui.info(`would remove ${rel}`);
       else {
         await rm3(target, { recursive: true, force: true });
@@ -11831,9 +12169,9 @@ function registerEnforce(program2) {
       }
     }
   });
-  enforce.command("ci").description("CI entrypoint: fail if the repository violates hAIve enforcement policy.").option("-d, --dir <dir>", "project root").option("--json", "emit JSON", false).action(async (opts) => {
+  enforce.command("ci").description("CI entrypoint: fail if the repository violates hAIve enforcement policy.").option("-d, --dir <dir>", "project root").option("--explain", "group findings by blocking/review/info and show repair commands", false).option("--json", "emit JSON", false).action(async (opts) => {
     const report = await buildEnforcementReport(opts.dir, "ci");
-    printReport(report, Boolean(opts.json));
+    printReport(report, Boolean(opts.json), Boolean(opts.explain));
     if (report.should_block) process.exit(2);
   });
   enforce.command("session-start").description("Claude Code SessionStart hook: inject briefing and write a local briefing marker.").option("-d, --dir <dir>", "project root").option("--task <text>", "task text to rank memories").option("--source <name>", "marker source", "claude-session-start").option("--session-id <id>", "agent session id").action(async (opts) => {
@@ -11946,7 +12284,7 @@ async function runWithEnforcement(command, args, opts) {
     process.exit(2);
   }
   ui.info(`hAIve briefing marker created for wrapped agent session: ${sessionId}`);
-  ui.info(`Briefing written to ${path47.relative(root, briefingFile)} and exported as HAIVE_BRIEFING_FILE`);
+  ui.info(`Briefing written to ${path48.relative(root, briefingFile)} and exported as HAIVE_BRIEFING_FILE`);
   const child = spawn5(command, args, {
     cwd: root,
     stdio: "inherit",
@@ -11995,9 +12333,9 @@ async function writeWrapperBriefing(paths, sessionId, task) {
     source: "haive-run",
     memoryIds: briefing.memories.map((m) => m.id)
   });
-  const dir = path47.join(paths.runtimeDir, "enforcement", "briefings");
+  const dir = path48.join(paths.runtimeDir, "enforcement", "briefings");
   await mkdir19(dir, { recursive: true });
-  const file = path47.join(dir, `${sessionId}.md`);
+  const file = path48.join(dir, `${sessionId}.md`);
   const parts = [
     "# hAIve Briefing",
     "",
@@ -12015,7 +12353,7 @@ async function writeWrapperBriefing(paths, sessionId, task) {
   if (briefing.setup_warnings.length > 0) {
     parts.push("", "## Setup Warnings", ...briefing.setup_warnings.map((w) => `- ${w}`));
   }
-  await writeFile31(file, parts.join("\n") + "\n", "utf8");
+  await writeFile33(file, parts.join("\n") + "\n", "utf8");
   return file;
 }
 async function buildEnforcementReport(dir, stage, sessionId) {
@@ -12026,7 +12364,7 @@ async function buildEnforcementReport(dir, stage, sessionId) {
   const mode = config.enforcement?.mode ?? "strict";
   const findings = [];
   if (!initialized) {
-    return {
+    return withCategories({
       root,
       initialized,
       mode,
@@ -12039,19 +12377,19 @@ async function buildEnforcementReport(dir, stage, sessionId) {
         fix: "Run `haive init` or `haive enforce install`.",
         impact: 100
       }]
-    };
+    });
   }
   if (mode === "off") {
-    return {
+    return withCategories({
       root,
       initialized,
       mode,
       score: buildScore([], config.enforcement?.scoreThreshold),
       should_block: false,
       findings: [{ severity: "info", code: "enforcement-off", message: "hAIve enforcement is disabled." }]
-    };
+    });
   }
-  findings.push(...await inspectIntegrationVersions(root, "0.9.16"));
+  findings.push(...await inspectIntegrationVersions(root, "0.9.17"));
   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." } : {
@@ -12101,13 +12439,23 @@ async function buildEnforcementReport(dir, stage, sessionId) {
     });
   }
   const hasErrors = findings.some((f) => f.severity === "error");
-  return {
+  return withCategories({
     root,
     initialized,
     mode,
     score: buildScore(findings, config.enforcement?.scoreThreshold),
     should_block: mode === "strict" && hasErrors,
     findings
+  });
+}
+function withCategories(report) {
+  return {
+    ...report,
+    categories: {
+      blocking: report.findings.filter((f) => f.severity === "error"),
+      review: report.findings.filter((f) => f.severity === "warn"),
+      info: report.findings.filter((f) => f.severity === "info" || f.severity === "ok")
+    }
   };
 }
 async function hasRecentSessionRecap(paths) {
@@ -12168,7 +12516,7 @@ async function verifyDecisionCoverage(paths, stage, sessionId) {
   const relevant = all.map(({ memory: memory2 }) => memory2).filter((memory2) => {
     const fm = memory2.frontmatter;
     if (!policyTypes.has(fm.type)) return false;
-    if (fm.status === "rejected" || fm.status === "deprecated" || fm.status === "stale") return false;
+    if (fm.status !== "validated") return false;
     return memoryMatchesAnchorPaths6(memory2, changedFiles);
   });
   if (relevant.length === 0) {
@@ -12251,7 +12599,7 @@ async function inspectIntegrationVersions(root, expectedVersion) {
   ];
   const findings = [];
   for (const rel of files) {
-    const file = path47.join(root, rel);
+    const file = path48.join(root, rel);
     if (!existsSync68(file)) continue;
     const text = await readFile18(file, "utf8").catch(() => "");
     for (const bin of extractAbsoluteHaiveBins2(text)) {
@@ -12318,7 +12666,9 @@ async function getChangedFiles(root, stage) {
       if (file) files.add(file);
     }
   }
-  return [...files].filter((file) => !file.startsWith(".ai/.runtime/") && !file.startsWith(".ai/.cache/"));
+  return [...files].filter(
+    (file) => !file.startsWith(".ai/.runtime/") && !file.startsWith(".ai/.cache/") && !file.startsWith(".ai/.usage/") && file !== ".ai/.usage/tool-usage.jsonl"
+  );
 }
 function buildScore(findings, threshold = 80) {
   const checks = {
@@ -12339,8 +12689,8 @@ function buildScore(findings, threshold = 80) {
   };
 }
 async function installGitEnforcement(root) {
-  const hooksDir = path47.join(root, ".git", "hooks");
-  if (!existsSync68(path47.join(root, ".git"))) {
+  const hooksDir = path48.join(root, ".git", "hooks");
+  if (!existsSync68(path48.join(root, ".git"))) {
     ui.warn("No .git directory found; git enforcement hooks skipped.");
     return;
   }
@@ -12362,31 +12712,31 @@ haive enforce check --stage pre-push --dir . || exit $?
     }
   ];
   for (const hook of hooks) {
-    const file = path47.join(hooksDir, hook.name);
+    const file = path48.join(hooksDir, hook.name);
     if (existsSync68(file)) {
       const current = await readFile18(file, "utf8").catch(() => "");
       if (current.includes(ENFORCE_HOOK_MARKER)) {
-        await writeFile31(file, hook.body, "utf8");
+        await writeFile33(file, hook.body, "utf8");
       } else {
-        await writeFile31(file, `${current.trimEnd()}
+        await writeFile33(file, `${current.trimEnd()}
 
 ${hook.body}`, "utf8");
       }
     } else {
-      await writeFile31(file, hook.body, "utf8");
+      await writeFile33(file, hook.body, "utf8");
     }
     await chmod2(file, 493);
   }
   ui.success("Installed blocking git enforcement hooks: pre-commit, pre-push");
 }
 async function installCiEnforcement(root) {
-  const workflowPath = path47.join(root, ".github", "workflows", "haive-enforcement.yml");
-  await mkdir19(path47.dirname(workflowPath), { recursive: true });
+  const workflowPath = path48.join(root, ".github", "workflows", "haive-enforcement.yml");
+  await mkdir19(path48.dirname(workflowPath), { recursive: true });
   if (existsSync68(workflowPath)) {
     ui.info("GitHub Actions enforcement workflow already exists \u2014 skipped");
     return;
   }
-  await writeFile31(workflowPath, `name: haive-enforcement
+  await writeFile33(workflowPath, `name: haive-enforcement
 
 on:
   pull_request:
@@ -12410,9 +12760,9 @@ jobs:
       - name: Enforce hAIve policy
         run: haive enforce ci
 `, "utf8");
-  ui.success(`Created ${path47.relative(root, workflowPath)}`);
+  ui.success(`Created ${path48.relative(root, workflowPath)}`);
 }
-function printReport(report, json) {
+function printReport(report, json, explain = false) {
   if (json) {
     console.log(JSON.stringify(report, null, 2));
     return;
@@ -12420,14 +12770,32 @@ function printReport(report, json) {
   console.log(ui.bold(`hAIve enforcement \u2014 ${report.mode}`));
   console.log(ui.dim(`  root: ${report.root}`));
   console.log(ui.dim(`  score: ${report.score.score}% / threshold ${report.score.threshold}%`));
-  for (const finding of report.findings) {
-    const marker = finding.severity === "error" ? ui.red("\u2717") : finding.severity === "warn" ? ui.yellow("\u26A0") : finding.severity === "ok" ? ui.green("\u2713") : ui.dim("\u2022");
-    console.log(`${marker} ${finding.code}: ${finding.message}`);
-    if (finding.fix) console.log(ui.dim(`  fix: ${finding.fix}`));
+  if (explain) {
+    printFindingGroup("Blocking", report.categories.blocking, "error");
+    printFindingGroup("Review", report.categories.review, "warn");
+    printFindingGroup("Info", report.categories.info, "info");
+  } else {
+    for (const finding of report.findings) printFinding(finding);
   }
   if (report.should_block) ui.error("hAIve enforcement gate failed.");
   else ui.success("hAIve enforcement gate passed.");
 }
+function printFindingGroup(title, findings, tone) {
+  if (findings.length === 0) return;
+  console.log();
+  const heading = tone === "error" ? ui.red(title) : tone === "warn" ? ui.yellow(title) : ui.bold(title);
+  console.log(ui.bold(`${heading} (${findings.length})`));
+  const scoreFinding = findings.find((f) => f.code === "enforcement-score-below-threshold");
+  for (const finding of findings.filter((f) => f.code !== "enforcement-score-below-threshold")) {
+    printFinding(finding, true);
+  }
+  if (scoreFinding) printFinding(scoreFinding, true);
+}
+function printFinding(finding, explain = false) {
+  const marker = finding.severity === "error" ? ui.red("\u2717") : finding.severity === "warn" ? ui.yellow("\u26A0") : finding.severity === "ok" ? ui.green("\u2713") : ui.dim("\u2022");
+  console.log(`${marker} ${finding.code}: ${finding.message}`);
+  if (finding.fix) console.log(ui.dim(`${explain ? "  repair: " : "  fix: "}${finding.fix}`));
+}
 async function readHookPayload() {
   const raw = await readStdin2(MAX_STDIN_BYTES2);
   if (!raw.trim()) return {};
@@ -12509,7 +12877,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.16").option("--advanced", "show maintenance and experimental commands in help");
+program.name("haive").description("hAIve \u2014 policy enforcement layer for AI coding agents").version("0.9.17").option("--advanced", "show maintenance and experimental commands in help");
 registerInit(program);
 registerWelcome(program);
 registerResolveProject(program);