@hiveai/cli 0.3.3 → 0.4.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command29 } from "commander";
+import { Command as Command32 } from "commander";
 
 // src/commands/briefing.ts
 import { existsSync } from "fs";
@@ -462,6 +462,28 @@ jobs:
               issue_number: context.issue.number,
               body: \`### haive \u2014 Stale memories detected\\n\\nSome memories anchored to code modified in this PR may be outdated:\\n\\n\\\`\\\`\\\`\\n\${report}\\n\\\`\\\`\\\`\\n\\nRun \\\`haive memory verify --update\\\` locally to refresh them before merging.\`
             });
+
+  # On push to main: push shared memories to the hub (if hubPath is configured)
+  # Uncomment and configure hubPath in .ai/haive.config.json to enable.
+  # hub-push:
+  #   if: github.event_name == 'push'
+  #   needs: sync-on-merge
+  #   runs-on: ubuntu-latest
+  #   permissions:
+  #     contents: write
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #       with:
+  #         fetch-depth: 0
+  #     - uses: actions/setup-node@v4
+  #       with:
+  #         node-version: '20'
+  #     - name: install haive
+  #       run: npm install -g @hiveai/cli
+  #     - name: push shared memories to hub
+  #       run: haive hub push --commit
+  #       # Requires hubPath in .ai/haive.config.json pointing to a cloned hub repo.
+  #       # The hub repo must be available at that path in the CI workspace.
 `;
 function registerInit(program2) {
   program2.command("init").description(
@@ -679,12 +701,13 @@ function locateMcpBin() {
 
 // src/commands/sync.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
 import { existsSync as existsSync6 } from "fs";
 import path6 from "path";
 import "commander";
 import {
   DEFAULT_AUTO_PROMOTE_RULE,
+  buildFrontmatter,
   findProjectRoot as findProjectRoot8,
   getUsage,
   isAutoPromoteEligible,
@@ -693,9 +716,13 @@ import {
   loadConfig,
   loadMemoriesFromDir as loadMemoriesFromDir2,
   loadUsageIndex,
+  pullCrossRepoSources,
   resolveHaivePaths as resolveHaivePaths5,
+  resolveManifestFiles,
   serializeMemory,
-  verifyAnchor
+  trackDependencies,
+  verifyAnchor,
+  watchContracts
 } from "@hiveai/core";
 var BRIDGE_START = "<!-- haive:memories-start -->";
 var BRIDGE_END = "<!-- haive:memories-end -->";
@@ -708,7 +735,7 @@ function registerSync(program2) {
   ).option("--no-verify", "skip the anchor verification step").option("--no-promote", "skip the auto-promotion step").option(
     "--inject-bridge",
     "inject top validated memories into CLAUDE.md (or --bridge-file) between <!-- haive:memories-start/end --> markers"
-  ).option("--bridge-file <path>", "bridge file to inject into (default: CLAUDE.md)").option("--bridge-max-memories <n>", "max memories to inject into bridge file", "5").option("--embed", "rebuild embeddings index after sync (requires @haive/embeddings)").action(async (opts) => {
+  ).option("--bridge-file <path>", "bridge file to inject into (default: CLAUDE.md)").option("--bridge-max-memories <n>", "max memories to inject into bridge file", "5").option("--embed", "rebuild embeddings index after sync (requires @haive/embeddings)").option("--no-cross-repo", "skip cross-repo memory pull even if crossRepoSources is configured").option("--no-deps", "skip dependency version tracking").option("--no-contracts", "skip contract file diff checking").action(async (opts) => {
     const root = findProjectRoot8(opts.dir);
     const paths = resolveHaivePaths5(root);
     if (!existsSync6(paths.memoriesDir)) {
@@ -878,6 +905,124 @@ function registerSync(program2) {
         }
       }
     }
+    if (opts.noCrossRepo !== true && (config.crossRepoSources ?? []).length > 0) {
+      try {
+        const crossReports = await pullCrossRepoSources(paths, config, root);
+        for (const r of crossReports) {
+          const total = r.imported.length + r.updated.length;
+          if (total > 0 || r.errors.length > 0) {
+            log(
+              ui.dim(
+                `cross-repo [${r.source}]: ${r.imported.length} imported \xB7 ${r.updated.length} updated \xB7 ${r.skipped.length} unchanged` + (r.errors.length > 0 ? ` \xB7 \u26A0 ${r.errors.length} error(s)` : "")
+              )
+            );
+            for (const e of r.errors) ui.warn(`  cross-repo error: ${e}`);
+          }
+        }
+      } catch (err) {
+        ui.warn(`cross-repo pull failed: ${String(err)}`);
+      }
+    }
+    if (opts.noDeps !== true) {
+      try {
+        const manifestFiles = resolveManifestFiles(root, config.dependencyFiles);
+        if (manifestFiles.length > 0) {
+          const depResults = await trackDependencies(root, paths.haiveDir, manifestFiles);
+          for (const result of depResults) {
+            const majorBumps = result.changes.filter((c) => c.isMajorBump);
+            const minorChanges = result.changes.filter((c) => !c.isMajorBump);
+            if (result.changes.length > 0) {
+              log(
+                ui.yellow(
+                  `\u26A0  dependency changes in ${result.file}: ${majorBumps.length} major bump(s) \xB7 ${minorChanges.length} minor change(s)`
+                )
+              );
+              for (const c of majorBumps) {
+                log(ui.yellow(`   MAJOR: ${c.name} ${c.from} \u2192 ${c.to}`));
+              }
+              for (const c of minorChanges) {
+                log(ui.dim(`   minor: ${c.name} ${c.from} \u2192 ${c.to}`));
+              }
+              if (majorBumps.length > 0) {
+                const slugParts = result.file.replace(/[^a-z0-9]/gi, "-").toLowerCase();
+                const slug = `dep-major-bump-${slugParts}-${Date.now().toString(36)}`;
+                const body = `## Major dependency version bumps detected in \`${result.file}\`
+
+` + majorBumps.map((c) => `- **${c.name}**: \`${c.from}\` \u2192 \`${c.to}\` (major bump \u2014 check for breaking changes)`).join("\n") + `
+
+**Action:** Review the changelogs for these packages and update any memories anchored to their APIs.
+Run \`haive memory import --from-changelog CHANGELOG.md\` if available.`;
+                const fm = buildFrontmatter({
+                  type: "gotcha",
+                  slug,
+                  scope: "team",
+                  status: "validated",
+                  tags: ["dependency", "breaking-change", "auto-generated"],
+                  paths: [result.file],
+                  topic: `dep-bump-${slugParts}`
+                });
+                const teamDir = path6.join(paths.memoriesDir, "team");
+                await mkdir3(teamDir, { recursive: true });
+                await writeFile3(
+                  path6.join(teamDir, `${fm.id}.md`),
+                  serializeMemory({ frontmatter: fm, body }),
+                  "utf8"
+                );
+                log(ui.yellow(`   \u2192 memory created: ${fm.id}`));
+              }
+            }
+          }
+        }
+      } catch (err) {
+        ui.warn(`dependency tracker failed: ${String(err)}`);
+      }
+    }
+    if (opts.noContracts !== true && (config.contractFiles ?? []).length > 0) {
+      try {
+        const diffs = await watchContracts(root, paths.haiveDir, config.contractFiles);
+        for (const diff of diffs) {
+          const breaking = diff.changes.filter((c) => c.severity === "breaking");
+          const additive = diff.changes.filter((c) => c.severity === "additive");
+          log(
+            ui.yellow(
+              `\u26A0  contract changed [${diff.contract}]: ${breaking.length} breaking \xB7 ${additive.length} additive`
+            )
+          );
+          for (const c of diff.changes) {
+            const icon = c.severity === "breaking" ? "\u{1F534}" : c.severity === "additive" ? "\u{1F7E2}" : "\u{1F7E1}";
+            log(`   ${icon} ${c.description}`);
+          }
+          if (breaking.length > 0) {
+            const slug = `contract-breaking-${diff.contract.replace(/[^a-z0-9]/gi, "-").toLowerCase()}-${Date.now().toString(36)}`;
+            const body = `## Breaking changes detected in contract: \`${diff.contract}\` (\`${diff.file}\`)
+
+` + breaking.map((c) => `- \u{1F534} **${c.kind}**: ${c.description}`).join("\n") + (additive.length > 0 ? "\n\n### Additive changes (non-breaking)\n" + additive.map((c) => `- \u{1F7E2} ${c.description}`).join("\n") : "") + `
+
+**Action:** Review all consumers of this contract and update accordingly.
+Check memories tagged with \`${diff.contract}\` for potentially stale knowledge.`;
+            const fm = buildFrontmatter({
+              type: "gotcha",
+              slug,
+              scope: "team",
+              status: "validated",
+              tags: ["api-contract", "breaking-change", diff.contract, "auto-generated"],
+              paths: [diff.file],
+              topic: `contract-breaking-${diff.contract}`
+            });
+            const teamDir = path6.join(paths.memoriesDir, "team");
+            await mkdir3(teamDir, { recursive: true });
+            await writeFile3(
+              path6.join(teamDir, `${fm.id}.md`),
+              serializeMemory({ frontmatter: fm, body }),
+              "utf8"
+            );
+            log(ui.yellow(`   \u2192 memory created: ${fm.id}`));
+          }
+        }
+      } catch (err) {
+        ui.warn(`contract watcher failed: ${String(err)}`);
+      }
+    }
     const existingMap = await loadCodeMap2(paths);
     if (existingMap) {
       const mapAge = new Date(existingMap.generated_at).getTime();
@@ -1003,12 +1148,12 @@ function collectSinceChanges(root, ref) {
 
 // src/commands/memory-add.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
 import { existsSync as existsSync7 } from "fs";
 import path7 from "path";
 import "commander";
 import {
-  buildFrontmatter,
+  buildFrontmatter as buildFrontmatter2,
   findProjectRoot as findProjectRoot9,
   inferModulesFromPaths,
   loadMemoriesFromDir as loadMemoriesFromDir3,
@@ -1124,7 +1269,7 @@ TODO \u2014 write the memory body.
         return;
       }
     }
-    const frontmatter = buildFrontmatter({
+    const frontmatter = buildFrontmatter2({
       type: opts.type,
       slug: opts.slug,
       scope,
@@ -1138,7 +1283,7 @@ TODO \u2014 write the memory body.
       topic: opts.topic
     });
     const file = memoryFilePath(paths, frontmatter.scope, frontmatter.id, frontmatter.module);
-    await mkdir3(path7.dirname(file), { recursive: true });
+    await mkdir4(path7.dirname(file), { recursive: true });
     if (existsSync7(file)) {
       ui.error(`Memory already exists at ${file}`);
       process.exitCode = 1;
@@ -1271,7 +1416,7 @@ function matchesFilters(loaded, opts) {
 }
 
 // src/commands/memory-promote.ts
-import { mkdir as mkdir4, unlink, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir5, unlink, writeFile as writeFile5 } from "fs/promises";
 import { existsSync as existsSync9 } from "fs";
 import path9 from "path";
 import "commander";
@@ -1320,7 +1465,7 @@ function registerMemoryPromote(memory2) {
       body: found.memory.body
     };
     const newPath = memoryFilePath2(paths, "team", updated.frontmatter.id);
-    await mkdir4(path9.dirname(newPath), { recursive: true });
+    await mkdir5(path9.dirname(newPath), { recursive: true });
     await writeFile5(newPath, serializeMemory3(updated), "utf8");
     await unlink(found.filePath);
     ui.success(`Promoted ${id} to team scope (status=proposed)`);
@@ -1780,12 +1925,12 @@ function registerMemoryHot(memory2) {
 }
 
 // src/commands/memory-tried.ts
-import { mkdir as mkdir5, writeFile as writeFile9 } from "fs/promises";
+import { mkdir as mkdir6, writeFile as writeFile9 } from "fs/promises";
 import { existsSync as existsSync16 } from "fs";
 import path16 from "path";
 import "commander";
 import {
-  buildFrontmatter as buildFrontmatter2,
+  buildFrontmatter as buildFrontmatter3,
   findProjectRoot as findProjectRoot18,
   memoryFilePath as memoryFilePath3,
   resolveHaivePaths as resolveHaivePaths15,
@@ -1816,7 +1961,7 @@ function registerMemoryTried(memory2) {
       return;
     }
     const slug = opts.what.toLowerCase().replace(/[^a-z0-9\s]/g, "").trim().split(/\s+/).slice(0, 5).join("-");
-    const baseFm = buildFrontmatter2({
+    const baseFm = buildFrontmatter3({
       type: "attempt",
       slug,
       scope: opts.scope,
@@ -1833,7 +1978,7 @@ function registerMemoryTried(memory2) {
     }
     const body = lines.join("\n") + "\n";
     const file = memoryFilePath3(paths, frontmatter.scope, frontmatter.id, frontmatter.module);
-    await mkdir5(path16.dirname(file), { recursive: true });
+    await mkdir6(path16.dirname(file), { recursive: true });
     if (existsSync16(file)) {
       ui.error(`Memory already exists at ${file}`);
       process.exitCode = 1;
@@ -2331,18 +2476,178 @@ function registerMemoryImport(memory2) {
   });
 }
 
-// src/commands/memory-digest.ts
+// src/commands/memory-import-changelog.ts
 import { existsSync as existsSync25 } from "fs";
-import { writeFile as writeFile12 } from "fs/promises";
+import { readFile as readFile8, mkdir as mkdir7, writeFile as writeFile12 } from "fs/promises";
 import path23 from "path";
 import "commander";
 import {
-  deriveConfidence as deriveConfidence4,
+  buildFrontmatter as buildFrontmatter4,
   findProjectRoot as findProjectRoot27,
+  resolveHaivePaths as resolveHaivePaths24,
+  serializeMemory as serializeMemory10
+} from "@hiveai/core";
+function parseChangelog(content) {
+  const entries = [];
+  const versionRe = /^#{1,3}\s+(?:\[?)([0-9]+\.[0-9]+[.0-9]*)/m;
+  const sections = content.split(/^#{1,3}\s+/m).slice(1);
+  for (const section of sections) {
+    const versionMatch = section.match(/^(?:\[?)([0-9]+\.[0-9]+[.0-9]*)/);
+    if (!versionMatch) continue;
+    const version = versionMatch[1];
+    const entry = {
+      version,
+      breaking: [],
+      deprecated: [],
+      removed: [],
+      fixed: [],
+      added: []
+    };
+    const subSections = section.split(/^#{2,4}\s+/m);
+    for (const sub of subSections) {
+      const firstLine = sub.split("\n")[0].toLowerCase().trim();
+      const items = sub.split("\n").slice(1).filter((l) => l.trim().startsWith("-") || l.trim().startsWith("*")).map((l) => l.replace(/^[\s\-*]+/, "").trim()).filter(Boolean);
+      if (/breaking/.test(firstLine)) {
+        entry.breaking.push(...items);
+      } else if (/deprecated/.test(firstLine)) {
+        entry.deprecated.push(...items);
+      } else if (/removed/.test(firstLine)) {
+        entry.removed.push(...items);
+      } else if (/fixed|bug/.test(firstLine)) {
+        entry.fixed.push(...items);
+      } else if (/added|new|feat/.test(firstLine)) {
+        entry.added.push(...items);
+      }
+      for (const sub2 of subSections) {
+        for (const line of sub2.split("\n")) {
+          const breakingMatch = line.match(/BREAKING CHANGE[S]?:\s*(.+)/i);
+          if (breakingMatch && !entry.breaking.includes(breakingMatch[1].trim())) {
+            entry.breaking.push(breakingMatch[1].trim());
+          }
+        }
+      }
+    }
+    if (entry.breaking.length === 0) {
+      for (const line of section.split("\n")) {
+        if (/breaking|⚠|deprecated|removed/.test(line.toLowerCase())) {
+          const item = line.replace(/^[\s\-*#]+/, "").trim();
+          if (item) entry.breaking.push(item);
+        }
+      }
+    }
+    const hasContent = entry.breaking.length > 0 || entry.deprecated.length > 0 || entry.removed.length > 0;
+    if (hasContent) entries.push(entry);
+  }
+  void versionRe;
+  return entries;
+}
+function registerMemoryImportChangelog(memory2) {
+  memory2.command("import-changelog").description(
+    "Import breaking changes from a CHANGELOG.md as hAIve memories.\n\n  Parses Keep-a-Changelog and Angular commit format changelogs,\n  extracts breaking changes, deprecations, and removals,\n  and saves each version's changes as a gotcha memory.\n\n  Examples:\n    haive memory import-changelog --from node_modules/@company/sdk/CHANGELOG.md --package @company/sdk\n    haive memory import-changelog --from CHANGELOG.md\n    haive memory import-changelog --from CHANGELOG.md --versions 2.0.0,2.1.0\n"
+  ).requiredOption("--from <file>", "path to the CHANGELOG.md file").option("--package <name>", "name of the package (used in memory title and tags)").option("--scope <scope>", "memory scope: team | personal (default: team)", "team").option(
+    "--versions <csv>",
+    "only import specific versions (comma-separated), or 'latest' for the most recent breaking version"
+  ).option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot27(opts.dir);
+    const paths = resolveHaivePaths24(root);
+    const changelogPath = path23.resolve(root, opts.fromChangelog);
+    if (!existsSync25(changelogPath)) {
+      ui.error(`CHANGELOG not found: ${changelogPath}`);
+      process.exitCode = 1;
+      return;
+    }
+    const content = await readFile8(changelogPath, "utf8");
+    let entries = parseChangelog(content);
+    if (entries.length === 0) {
+      ui.warn("No breaking changes, deprecations, or removals found in the CHANGELOG.");
+      return;
+    }
+    if (opts.versions) {
+      if (opts.versions === "latest") {
+        entries = [entries[0]];
+      } else {
+        const requested = opts.versions.split(",").map((v) => v.trim());
+        entries = entries.filter((e) => requested.includes(e.version));
+      }
+    }
+    const pkgName = opts.package ?? path23.basename(path23.dirname(changelogPath));
+    const scope = opts.scope ?? "team";
+    const teamDir = path23.join(paths.memoriesDir, scope);
+    await mkdir7(teamDir, { recursive: true });
+    let saved = 0;
+    for (const entry of entries) {
+      const lines = [];
+      lines.push(`## ${pkgName} v${entry.version} \u2014 Breaking Changes & Deprecations
+`);
+      if (entry.breaking.length > 0) {
+        lines.push("### \u{1F534} Breaking Changes\n");
+        for (const item of entry.breaking) lines.push(`- ${item}`);
+        lines.push("");
+      }
+      if (entry.deprecated.length > 0) {
+        lines.push("### \u{1F7E1} Deprecated\n");
+        for (const item of entry.deprecated) lines.push(`- ${item}`);
+        lines.push("");
+      }
+      if (entry.removed.length > 0) {
+        lines.push("### \u26AB Removed\n");
+        for (const item of entry.removed) lines.push(`- ${item}`);
+        lines.push("");
+      }
+      lines.push(
+        `**Source:** \`${path23.relative(root, changelogPath)}\`  
+**Action:** Update all usages of ${pkgName} if they rely on any of the above.`
+      );
+      const slug = `changelog-${pkgName.replace(/[^a-z0-9]/gi, "-").toLowerCase()}-v${entry.version.replace(/\./g, "-")}`;
+      const fm = buildFrontmatter4({
+        type: "gotcha",
+        slug,
+        scope,
+        status: "validated",
+        tags: [
+          "changelog",
+          "breaking-change",
+          pkgName.replace(/[^a-z0-9]/gi, "-").toLowerCase(),
+          `v${entry.version}`
+        ],
+        paths: [path23.relative(root, changelogPath)],
+        topic: `changelog-${pkgName}-${entry.version}`
+      });
+      await writeFile12(
+        path23.join(teamDir, `${fm.id}.md`),
+        serializeMemory10({ frontmatter: fm, body: lines.join("\n") }),
+        "utf8"
+      );
+      console.log(ui.green(`  \u2713 ${fm.id}`));
+      saved++;
+    }
+    console.log(
+      `
+${ui.bold(`Imported ${saved} changelog entr${saved === 1 ? "y" : "ies"} from ${pkgName}`)}`
+    );
+    if (saved > 0) {
+      console.log(
+        ui.dim(`  Memories saved to .ai/memories/${scope}/`)
+      );
+      console.log(
+        ui.dim(`  Run \`haive briefing --task "update ${pkgName}"\` to see them in context.`)
+      );
+    }
+  });
+}
+
+// src/commands/memory-digest.ts
+import { existsSync as existsSync26 } from "fs";
+import { writeFile as writeFile13 } from "fs/promises";
+import path24 from "path";
+import "commander";
+import {
+  deriveConfidence as deriveConfidence4,
+  findProjectRoot as findProjectRoot28,
   getUsage as getUsage8,
   loadMemoriesFromDir as loadMemoriesFromDir5,
   loadUsageIndex as loadUsageIndex10,
-  resolveHaivePaths as resolveHaivePaths24
+  resolveHaivePaths as resolveHaivePaths25
 } from "@hiveai/core";
 var CONFIDENCE_EMOJI = {
   unverified: "\u2B1C",
@@ -2355,9 +2660,9 @@ function registerMemoryDigest(program2) {
   program2.command("digest").description(
     "Generate a Markdown review digest of recently added or updated memories.\n\n  Groups memories by type, shows confidence, status, read count, and anchor info.\n  Each memory has action checkboxes (approve / reject / keep as-is) for peer review.\n\n  Use this to do a bulk weekly review of team memories, or share with teammates\n  as a pull-request attachment so humans can validate what the AI captured.\n\n  Examples:\n    haive memory digest                         # last 7 days, team scope\n    haive memory digest --days 30 --scope all   # last 30 days, all scopes\n    haive memory digest --out review.md         # write to file\n"
   ).option("--days <n>", "look-back window in days (default: 7)", "7").option("--scope <scope>", "personal | team | module | all (default: team)", "team").option("--out <file>", "write digest to a file instead of stdout").option("-d, --dir <dir>", "project root").action(async (opts) => {
-    const root = findProjectRoot27(opts.dir);
-    const paths = resolveHaivePaths24(root);
-    if (!existsSync25(paths.memoriesDir)) {
+    const root = findProjectRoot28(opts.dir);
+    const paths = resolveHaivePaths25(root);
+    if (!existsSync26(paths.memoriesDir)) {
       ui.error("No .ai/memories found. Run `haive init` first.");
       process.exitCode = 1;
       return;
@@ -2429,8 +2734,8 @@ function registerMemoryDigest(program2) {
     );
     const digest = lines.join("\n");
     if (opts.out) {
-      const outPath = path23.resolve(process.cwd(), opts.out);
-      await writeFile12(outPath, digest, "utf8");
+      const outPath = path24.resolve(process.cwd(), opts.out);
+      await writeFile13(outPath, digest, "utf8");
       ui.success(`Digest written to ${opts.out}  (${recent.length} memor${recent.length === 1 ? "y" : "ies"})`);
     } else {
       console.log(digest);
@@ -2439,17 +2744,17 @@ function registerMemoryDigest(program2) {
 }
 
 // src/commands/session-end.ts
-import { writeFile as writeFile13, mkdir as mkdir6 } from "fs/promises";
-import { existsSync as existsSync26 } from "fs";
-import path24 from "path";
+import { writeFile as writeFile14, mkdir as mkdir8 } from "fs/promises";
+import { existsSync as existsSync27 } from "fs";
+import path25 from "path";
 import "commander";
 import {
-  buildFrontmatter as buildFrontmatter3,
-  findProjectRoot as findProjectRoot28,
+  buildFrontmatter as buildFrontmatter5,
+  findProjectRoot as findProjectRoot29,
   loadMemoriesFromDir as loadMemoriesFromDir6,
   memoryFilePath as memoryFilePath4,
-  resolveHaivePaths as resolveHaivePaths25,
-  serializeMemory as serializeMemory10
+  resolveHaivePaths as resolveHaivePaths26,
+  serializeMemory as serializeMemory11
 } from "@hiveai/core";
 function buildRecapBody(opts) {
   const lines = [];
@@ -2498,9 +2803,9 @@ function registerSessionEnd(session2) {
       --next "Add integration tests for webhook signature validation"
 `
   ).requiredOption("--goal <text>", "what you were trying to accomplish (1\u20132 sentences)").requiredOption("--accomplished <text>", "what was actually done (bullet list recommended)").option("--discoveries <text>", "bugs, surprises, or inconsistencies found during this session").option("--files <csv>", "key files touched, comma-separated (used as anchor for staleness detection)").option("--next <text>", "what should happen next (for the next session or a teammate)").option("--scope <scope>", "personal | team | module (default: personal)", "personal").option("--module <name>", "module name (required when scope=module)").option("-d, --dir <dir>", "project root").action(async (opts) => {
-    const root = findProjectRoot28(opts.dir);
-    const paths = resolveHaivePaths25(root);
-    if (!existsSync26(paths.haiveDir)) {
+    const root = findProjectRoot29(opts.dir);
+    const paths = resolveHaivePaths26(root);
+    if (!existsSync27(paths.haiveDir)) {
       ui.error(`No .ai/ found at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
@@ -2509,12 +2814,12 @@ function registerSessionEnd(session2) {
     const body = buildRecapBody(opts);
     const topic = recapTopic(scope, opts.module);
     const filesTouched = parseCsv5(opts.files);
-    const missingPaths = filesTouched.filter((p) => !existsSync26(path24.resolve(root, p)));
+    const missingPaths = filesTouched.filter((p) => !existsSync27(path25.resolve(root, p)));
     if (missingPaths.length > 0) {
       ui.warn(`Anchor path${missingPaths.length > 1 ? "s" : ""} not found in project (will be stale):`);
       for (const p of missingPaths) ui.warn(`  \u2717 ${p}`);
     }
-    if (existsSync26(paths.memoriesDir)) {
+    if (existsSync27(paths.memoriesDir)) {
       const existing = await loadMemoriesFromDir6(paths.memoriesDir);
       const topicMatch = existing.find(
         ({ memory: memory2 }) => memory2.frontmatter.topic === topic && memory2.frontmatter.scope === scope && (!opts.module || memory2.frontmatter.module === opts.module)
@@ -2530,13 +2835,13 @@ function registerSessionEnd(session2) {
             paths: filesTouched.length ? filesTouched : fm.anchor.paths
           }
         };
-        await writeFile13(topicMatch.filePath, serializeMemory10({ frontmatter: newFrontmatter, body }), "utf8");
+        await writeFile14(topicMatch.filePath, serializeMemory11({ frontmatter: newFrontmatter, body }), "utf8");
         ui.success(`Session recap updated (revision #${revisionCount})`);
-        ui.info(`id=${fm.id}  file=${path24.relative(root, topicMatch.filePath)}`);
+        ui.info(`id=${fm.id}  file=${path25.relative(root, topicMatch.filePath)}`);
         return;
       }
     }
-    const frontmatter = buildFrontmatter3({
+    const frontmatter = buildFrontmatter5({
       type: "session_recap",
       slug: "recap",
       scope,
@@ -2547,10 +2852,10 @@ function registerSessionEnd(session2) {
       status: "validated"
     });
     const file = memoryFilePath4(paths, frontmatter.scope, frontmatter.id, frontmatter.module);
-    await mkdir6(path24.dirname(file), { recursive: true });
-    await writeFile13(file, serializeMemory10({ frontmatter, body }), "utf8");
+    await mkdir8(path25.dirname(file), { recursive: true });
+    await writeFile14(file, serializeMemory11({ frontmatter, body }), "utf8");
     ui.success(`Session recap created`);
-    ui.info(`id=${frontmatter.id}  scope=${scope}  file=${path24.relative(root, file)}`);
+    ui.info(`id=${frontmatter.id}  scope=${scope}  file=${path25.relative(root, file)}`);
     ui.info("Next session: call `get_briefing` \u2014 the recap will be surfaced automatically.");
   });
 }
@@ -2559,9 +2864,430 @@ function parseCsv5(value) {
   return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
 
+// src/commands/snapshot.ts
+import { existsSync as existsSync28 } from "fs";
+import { readdir } from "fs/promises";
+import path26 from "path";
+import "commander";
+import {
+  diffContract,
+  findProjectRoot as findProjectRoot30,
+  loadConfig as loadConfig2,
+  resolveHaivePaths as resolveHaivePaths27,
+  snapshotContract
+} from "@hiveai/core";
+function registerSnapshot(program2) {
+  program2.command("snapshot").description(
+    `Take or compare an API contract snapshot to detect breaking changes.
+
+  A snapshot captures the structure of a contract file (endpoints, types, fields).
+  Running 'haive sync' automatically checks all configured contracts.
+  This command lets you snapshot or diff a single contract on demand.
+
+  Supported formats: openapi, graphql, proto, typescript, json-schema
+
+  Examples:
+    haive snapshot --contract docs/openapi.yaml --name payment-api
+    haive snapshot --diff --name payment-api
+    haive snapshot --list
+
+  To monitor contracts automatically on haive sync, add them to haive.config.json:
+    { "contractFiles": [{ "name": "payment-api", "path": "docs/openapi.yaml", "format": "openapi" }] }
+`
+  ).option("--contract <file>", "path to the contract file to snapshot (relative to project root)").option("--name <name>", "name for this contract (used in the lock file and memories)").option(
+    "--format <format>",
+    "contract format: openapi | graphql | proto | typescript | json-schema (auto-detected if omitted)"
+  ).option("--diff", "compare the contract against its stored snapshot").option("--list", "list all stored contract snapshots").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot30(opts.dir);
+    const paths = resolveHaivePaths27(root);
+    if (!existsSync28(paths.haiveDir)) {
+      ui.error("No .ai/ found. Run `haive init` first.");
+      process.exitCode = 1;
+      return;
+    }
+    if (opts.list) {
+      const contractsDir = path26.join(paths.haiveDir, "contracts");
+      if (!existsSync28(contractsDir)) {
+        console.log(ui.dim("No contract snapshots found."));
+        return;
+      }
+      const files = (await readdir(contractsDir)).filter(
+        (f) => f.endsWith(".lock") && !f.startsWith("deps-")
+      );
+      if (files.length === 0) {
+        console.log(ui.dim("No contract snapshots found."));
+        return;
+      }
+      console.log(ui.bold(`Contract snapshots (${files.length}):`));
+      for (const f of files) {
+        const name2 = f.replace(".lock", "");
+        console.log(`  ${name2}`);
+      }
+      return;
+    }
+    if (opts.diff) {
+      if (!opts.name) {
+        const config2 = await loadConfig2(paths);
+        const contracts = config2.contractFiles ?? [];
+        if (contracts.length === 0) {
+          ui.error("--diff requires --name, or configure contractFiles in haive.config.json");
+          process.exitCode = 1;
+          return;
+        }
+        for (const contract3 of contracts) {
+          await runDiff(root, paths.haiveDir, contract3);
+        }
+        return;
+      }
+      const config = await loadConfig2(paths);
+      const configured = (config.contractFiles ?? []).find((c) => c.name === opts.name);
+      if (!configured && !opts.contract) {
+        ui.error(
+          `Contract "${opts.name}" not found in haive.config.json and --contract not provided.`
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const contract2 = configured ?? {
+        name: opts.name,
+        path: opts.contract,
+        format: detectFormat(opts.contract ?? "") ?? "openapi"
+      };
+      await runDiff(root, paths.haiveDir, contract2);
+      return;
+    }
+    if (!opts.contract) {
+      ui.error("Provide --contract <file> or use --diff / --list.");
+      process.exitCode = 1;
+      return;
+    }
+    const contractPath = opts.contract;
+    const name = opts.name ?? path26.basename(contractPath, path26.extname(contractPath));
+    const format = opts.format ?? detectFormat(contractPath) ?? "openapi";
+    const contract = { name, path: contractPath, format };
+    try {
+      const snapshot = await snapshotContract(root, paths.haiveDir, contract);
+      console.log(ui.green(`\u2713 snapshot saved: ${name}`));
+      if (snapshot.endpoints) {
+        console.log(ui.dim(`  ${snapshot.endpoints.length} endpoint(s) captured`));
+      }
+      if (snapshot.types) {
+        console.log(ui.dim(`  ${snapshot.types.length} type(s) captured`));
+      }
+      console.log(ui.dim(`  lock: .ai/contracts/${name}.lock`));
+      console.log(ui.dim("  Next haive sync will detect changes automatically."));
+      console.log(
+        ui.dim(
+          `  Tip: add to haive.config.json \u2192 contractFiles to monitor automatically:
+  { "name": "${name}", "path": "${contractPath}", "format": "${format}" }`
+        )
+      );
+    } catch (err) {
+      ui.error(String(err));
+      process.exitCode = 1;
+    }
+  });
+}
+async function runDiff(root, haiveDir, contract) {
+  try {
+    const result = await diffContract(root, haiveDir, contract);
+    if (result.unchanged) {
+      console.log(ui.green(`\u2713 ${contract.name}: no changes detected`));
+      return;
+    }
+    const breaking = result.changes.filter((c) => c.severity === "breaking");
+    const additive = result.changes.filter((c) => c.severity === "additive");
+    const unknown = result.changes.filter((c) => c.severity === "unknown");
+    console.log(
+      ui.bold(`Contract diff: ${contract.name}`) + ` \u2014 ${breaking.length} breaking \xB7 ${additive.length} additive \xB7 ${unknown.length} unknown`
+    );
+    for (const c of result.changes) {
+      const icon = c.severity === "breaking" ? "\u{1F534}" : c.severity === "additive" ? "\u{1F7E2}" : "\u{1F7E1}";
+      console.log(`  ${icon} ${c.description}`);
+    }
+    if (breaking.length > 0) {
+      console.log(
+        ui.yellow(
+          "\n  \u26A0 Breaking changes detected \u2014 run `haive sync` to create a gotcha memory for your team."
+        )
+      );
+    }
+  } catch (err) {
+    ui.error(`diff failed for ${contract.name}: ${String(err)}`);
+  }
+}
+function detectFormat(filePath) {
+  const ext = path26.extname(filePath).toLowerCase();
+  const base = path26.basename(filePath).toLowerCase();
+  if (ext === ".yaml" || ext === ".yml" || ext === ".json") {
+    if (base.includes("openapi") || base.includes("swagger")) return "openapi";
+    if (base.includes("schema") || base.includes("graphql")) return "graphql";
+    return "openapi";
+  }
+  if (ext === ".graphql" || ext === ".gql") return "graphql";
+  if (ext === ".proto") return "proto";
+  if (ext === ".d.ts" || ext === ".ts") return "typescript";
+  return null;
+}
+
+// src/commands/hub.ts
+import { existsSync as existsSync29 } from "fs";
+import { mkdir as mkdir9, readFile as readFile9, writeFile as writeFile15, copyFile } from "fs/promises";
+import path27 from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+import "commander";
+import {
+  findProjectRoot as findProjectRoot31,
+  loadConfig as loadConfig3,
+  loadMemoriesFromDir as loadMemoriesFromDir7,
+  resolveHaivePaths as resolveHaivePaths28,
+  saveConfig as saveConfig2,
+  serializeMemory as serializeMemory12
+} from "@hiveai/core";
+function registerHub(program2) {
+  const hub = program2.command("hub").description(
+    'Manage a shared team-knowledge hub \u2014 a central repo that multiple projects contribute to and pull from.\n\n  The hub is a plain git repo with a .ai/ directory. Each project pushes its\n  `shared`-scoped memories to the hub and pulls from all other projects.\n\n  Setup:\n    1. haive hub init /path/to/team-hub\n    2. Add hubPath to .ai/haive.config.json: { "hubPath": "../team-hub" }\n    3. haive hub push    \u2014 publish your shared memories\n    4. haive hub pull    \u2014 import other projects\' shared memories\n\n  Or configure in haive.config.json and haive sync handles it automatically.\n'
+  );
+  hub.action(() => hub.help());
+  hub.command("init <hubPath>").description(
+    "Initialize a new team-knowledge hub repo at <hubPath>.\n\n  Creates a git repo with a .ai/ directory structure ready for shared memories.\n\n  Example:\n    haive hub init ../team-hub\n    haive hub init /srv/git/team-knowledge\n"
+  ).action(async (hubPath) => {
+    const absPath = path27.resolve(hubPath);
+    await mkdir9(absPath, { recursive: true });
+    const gitCheck = spawnSync3("git", ["rev-parse", "--git-dir"], { cwd: absPath });
+    if (gitCheck.status !== 0) {
+      const init = spawnSync3("git", ["init"], { cwd: absPath, encoding: "utf8" });
+      if (init.status !== 0) {
+        ui.error(`git init failed: ${init.stderr}`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+    const sharedDir = path27.join(absPath, ".ai", "memories", "shared");
+    await mkdir9(sharedDir, { recursive: true });
+    await writeFile15(
+      path27.join(absPath, ".ai", "README.md"),
+      `# hAIve Team Knowledge Hub
+
+This repo is a shared knowledge hub for hAIve.
+
+Each project contributes its \`shared\`-scoped memories here.
+Other projects pull from it via \`haive hub pull\`.
+
+## Structure
+
+\`\`.ai/memories/shared/<project-name>/\`
+
+## Usage
+
+\`\`\`bash
+haive hub push   # publish from a project
+haive hub pull   # import into a project
+\`\`\`
+`,
+      "utf8"
+    );
+    await writeFile15(
+      path27.join(absPath, ".gitignore"),
+      ".ai/.cache/\n.ai/memories/personal/\n",
+      "utf8"
+    );
+    spawnSync3("git", ["add", "."], { cwd: absPath });
+    spawnSync3("git", ["commit", "-m", "chore: initialize hAIve team-knowledge hub"], {
+      cwd: absPath,
+      encoding: "utf8"
+    });
+    console.log(ui.green(`\u2713 Hub initialized at ${absPath}`));
+    console.log(
+      ui.dim(
+        `
+Next steps:
+  1. Add hubPath to your project's .ai/haive.config.json:
+       { "hubPath": "${path27.relative(process.cwd(), absPath)}" }
+  2. Run \`haive hub push\` to publish your shared memories
+  3. Share ${absPath} with teammates (git remote, NFS, etc.)
+`
+      )
+    );
+  });
+  hub.command("push").description(
+    `Push this project's shared-scoped memories to the hub.
+
+  Copies all memories with scope=shared to hub/.ai/memories/shared/<project-name>/.
+  Optionally commits to the hub repo.
+
+  Examples:
+    haive hub push
+    haive hub push --commit
+    haive hub push --commit --message "feat: add payment API contract memories"
+`
+  ).option("-d, --dir <dir>", "project root").option("--commit", "auto-commit to the hub repo after pushing").option("--message <msg>", "commit message for the hub (used with --commit)").action(async (opts) => {
+    const root = findProjectRoot31(opts.dir);
+    const paths = resolveHaivePaths28(root);
+    const config = await loadConfig3(paths);
+    if (!config.hubPath) {
+      ui.error(
+        'hubPath not configured in .ai/haive.config.json.\n  Add: { "hubPath": "../team-hub" }\n  Or run: haive hub init <path> first.'
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const hubRoot = path27.resolve(root, config.hubPath);
+    if (!existsSync29(hubRoot)) {
+      ui.error(`Hub not found at ${hubRoot}. Run \`haive hub init ${config.hubPath}\` first.`);
+      process.exitCode = 1;
+      return;
+    }
+    const projectName = path27.basename(root);
+    const destDir = path27.join(hubRoot, ".ai", "memories", "shared", projectName);
+    await mkdir9(destDir, { recursive: true });
+    const all = await loadMemoriesFromDir7(paths.memoriesDir);
+    const shared = all.filter(
+      ({ memory: memory2 }) => memory2.frontmatter.scope === "shared" && memory2.frontmatter.status !== "rejected" && memory2.frontmatter.status !== "deprecated" && // Don't push imported memories (avoid echo loops)
+      !memory2.frontmatter.tags.some((t) => t.startsWith("cross-repo:"))
+    );
+    if (shared.length === 0) {
+      ui.warn(
+        `No shared-scoped memories found. Create memories with scope=shared to push to the hub.
+  Example: haive memory add --type architecture --slug my-api --scope shared --body "..."
+  Or with MCP: mem_save({ scope: 'shared', ... })`
+      );
+      return;
+    }
+    let pushed = 0;
+    for (const { memory: memory2 } of shared) {
+      const fm = memory2.frontmatter;
+      const fileName = `${fm.id}.md`;
+      const destPath = path27.join(destDir, fileName);
+      await writeFile15(destPath, serializeMemory12(memory2), "utf8");
+      pushed++;
+    }
+    console.log(ui.green(`\u2713 Pushed ${pushed} shared memor${pushed === 1 ? "y" : "ies"} to hub`));
+    console.log(ui.dim(`  Location: ${destDir}`));
+    if (opts.commit) {
+      const message = opts.message ?? `haive: sync shared memories from ${projectName} (${pushed} memories)`;
+      spawnSync3("git", ["add", path27.join(".ai", "memories", "shared", projectName)], {
+        cwd: hubRoot
+      });
+      const commit = spawnSync3("git", ["commit", "-m", message], {
+        cwd: hubRoot,
+        encoding: "utf8"
+      });
+      if (commit.status === 0) {
+        console.log(ui.green(`\u2713 Committed to hub: "${message}"`));
+      } else if (commit.stdout?.includes("nothing to commit")) {
+        console.log(ui.dim("  Hub already up to date \u2014 nothing to commit."));
+      } else {
+        ui.warn(`git commit in hub failed: ${commit.stderr}`);
+      }
+    } else {
+      console.log(
+        ui.dim(
+          "  Tip: use --commit to auto-commit to the hub repo, or commit manually."
+        )
+      );
+    }
+  });
+  hub.command("pull").description(
+    "Pull shared memories from the hub into this project.\n\n  Imports all memories from hub/.ai/memories/shared/ EXCEPT this project's own.\n  Imported memories land in .ai/memories/shared/<source-project-name>/.\n\n  Examples:\n    haive hub pull\n"
+  ).option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot31(opts.dir);
+    const paths = resolveHaivePaths28(root);
+    const config = await loadConfig3(paths);
+    if (!config.hubPath) {
+      ui.error(
+        'hubPath not configured in .ai/haive.config.json.\n  Add: { "hubPath": "../team-hub" }\n  Or run: haive hub init <path> first.'
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const hubRoot = path27.resolve(root, config.hubPath);
+    const hubSharedDir = path27.join(hubRoot, ".ai", "memories", "shared");
+    if (!existsSync29(hubSharedDir)) {
+      ui.warn("Hub has no shared memories yet. Run `haive hub push` from other projects first.");
+      return;
+    }
+    const projectName = path27.basename(root);
+    const { readdir: readdir2 } = await import("fs/promises");
+    const projectDirs = (await readdir2(hubSharedDir, { withFileTypes: true })).filter((d) => d.isDirectory() && d.name !== projectName).map((d) => d.name);
+    if (projectDirs.length === 0) {
+      console.log(ui.dim("No other projects have pushed to the hub yet."));
+      return;
+    }
+    let totalImported = 0;
+    let totalUpdated = 0;
+    for (const sourceName of projectDirs) {
+      const sourceDir = path27.join(hubSharedDir, sourceName);
+      const destDir = path27.join(paths.memoriesDir, "shared", sourceName);
+      await mkdir9(destDir, { recursive: true });
+      const sourceFiles = (await readdir2(sourceDir)).filter((f) => f.endsWith(".md"));
+      const { loadMemoriesFromDir: loadDir } = await import("@hiveai/core");
+      const existingInDest = await loadDir(destDir);
+      const existingIds = new Set(existingInDest.map(({ memory: memory2 }) => memory2.frontmatter.id));
+      for (const file of sourceFiles) {
+        const srcPath = path27.join(sourceDir, file);
+        const destPath = path27.join(destDir, file);
+        const fileContent = await readFile9(srcPath, "utf8");
+        const alreadyTagged = fileContent.includes(`cross-repo:${sourceName}`);
+        if (!alreadyTagged) {
+          await copyFile(srcPath, destPath);
+        } else {
+          await copyFile(srcPath, destPath);
+        }
+        const memId = file.replace(".md", "");
+        if (existingIds.has(memId)) {
+          totalUpdated++;
+        } else {
+          totalImported++;
+        }
+      }
+      console.log(
+        ui.dim(`  [${sourceName}]: ${sourceFiles.length} memor${sourceFiles.length === 1 ? "y" : "ies"} synced`)
+      );
+    }
+    console.log(
+      ui.green(`\u2713 Hub pull complete: ${totalImported} new \xB7 ${totalUpdated} updated`)
+    );
+  });
+  hub.command("status").description("Show hub sync status.").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot31(opts.dir);
+    const paths = resolveHaivePaths28(root);
+    const config = await loadConfig3(paths);
+    console.log(ui.bold("Hub status"));
+    console.log(
+      `  hubPath: ${config.hubPath ? ui.green(config.hubPath) : ui.dim("not configured")}`
+    );
+    const sharedDir = path27.join(paths.memoriesDir, "shared");
+    if (existsSync29(sharedDir)) {
+      const { readdir: readdir2 } = await import("fs/promises");
+      const sources = (await readdir2(sharedDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+      console.log(`
+  Imported from ${sources.length} source(s):`);
+      for (const src of sources) {
+        const files = (await readdir2(path27.join(sharedDir, src))).filter((f) => f.endsWith(".md"));
+        console.log(`    ${src}: ${files.length} memor${files.length === 1 ? "y" : "ies"}`);
+      }
+    } else {
+      console.log(ui.dim("  No imported shared memories yet."));
+    }
+    const all = await loadMemoriesFromDir7(paths.memoriesDir);
+    const outgoing = all.filter(
+      ({ memory: memory2 }) => memory2.frontmatter.scope === "shared" && !memory2.frontmatter.tags.some((t) => t.startsWith("cross-repo:"))
+    );
+    console.log(`
+  This project's shared memories (ready to push): ${outgoing.length}`);
+    if (outgoing.length > 0) {
+      console.log(ui.dim("  Run `haive hub push` to publish them to the hub."));
+    }
+    void readFile9;
+    void writeFile15;
+    void saveConfig2;
+  });
+}
+
 // src/index.ts
-var program = new Command29();
-program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.3.3");
+var program = new Command32();
+program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.4.0");
 registerInit(program);
 registerMcp(program);
 registerBriefing(program);
@@ -2589,9 +3315,12 @@ registerMemoryUpdate(memory);
 registerMemoryHot(memory);
 registerMemoryTried(memory);
 registerMemoryImport(memory);
+registerMemoryImportChangelog(memory);
 registerMemoryDigest(memory);
 var session = program.command("session").description("Manage session lifecycle");
 registerSessionEnd(session);
+registerSnapshot(program);
+registerHub(program);
 program.parseAsync(process.argv).catch((err) => {
   if (isZodError(err)) {
     for (const issue of err.issues) {