@lh8ppl/claude-memory-kit 0.3.0 → 0.3.1

package/src/semantic-backend.mjs

@@ -399,6 +399,120 @@ export function resolveDefaultSearchMode({ projectRoot }) {
  * surprise on the user's first search. Best-effort — failure reports a
  * reason, never throws.
  */
+/**
+ * The near-dup threshold for bge-base cosine — MEASURED, not assumed
+ * (live bake 2026-06-13, real Xenova/bge-base-en-v1.5 q8):
+ *   must-catch paraphrases:      0.85 ("use uv not pip" pair) · 0.96 · 0.81
+ *   must-NOT-catch (same domain, different facts): 0.66 · 0.64
+ * 0.78 splits the gap with ≥0.03 margin on the catch side and ≥0.12 on the
+ * miss side; q8 quantization flutters scores ±0.003 across processes, so a
+ * threshold inside the gap matters. The pre-143 DEFAULT_SEMANTIC_THRESHOLD
+ * (0.85, conflict-queue.mjs) predates the real embedder and would MISS the
+ * task's own canonical example (0.8493 < 0.85) — caught by the live test.
+ */
+export const SEMANTIC_NEARDUP_THRESHOLD = 0.78;
+
+/**
+ * Build a write-time semantic similarity function (Task 143, D-130).
+ *
+ * For the EXPLICIT capture paths (cmk remember / mk_remember): embeds the
+ * INCOMING text once (the only async model call), then returns a SYNC
+ * `similarityFn(newText, existingText)` compatible with detectConflicts'
+ * injectable seam:
+ *   - candidate vector found in the content-addressed embedding cache
+ *     (sha256(model\ntext) — the same key syncSemanticIndex writes) →
+ *     cosine (vectors are normalized, so a dot product);
+ *   - cache miss (a bullet captured since the last reindex) → token-Jaccard
+ *     fallback FOR THAT PAIR — honest literal comparison, never a throw,
+ *     never a per-pair model call (budget: one embed per capture, total).
+ *
+ * Not-ok states ({ok:false, reason}) let callers degrade silently to the
+ * literal pipeline (the spec's graceful-degradation contract):
+ *   'embedder-not-installed' — the optional embedder is absent.
+ *   'embed-failed: …'        — the model errored on the incoming text.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.newText - the incoming capture.
+ * @param {string} [opts.modelId]
+ * @param {Function} [opts.extractorImpl] - test seam: async () => extractor|null
+ *   (the loadExtractor shape).
+ * @param {Function} [opts.cacheLookupImpl] - test seam: (text) => number[]|null.
+ * @returns {Promise<{ok:true, similarityFn:Function, backend:'semantic'} | {ok:false, reason:string}>}
+ */
+export async function prepareSemanticSimilarity({
+  projectRoot,
+  newText,
+  modelId = DEFAULT_MODEL_ID,
+  extractorImpl,
+  cacheLookupImpl,
+} = {}) {
+  // Honor the global semantic kill-switch (consistency with
+  // prepareSemanticBackend) — the near-dup guard degrades to {} just like
+  // search degrades to keyword. Skipped when a test injects an extractor.
+  if (!extractorImpl && process.env.CMK_DISABLE_SEMANTIC === '1') {
+    return { ok: false, reason: 'embedder-disabled' };
+  }
+  const load = extractorImpl ?? (() => loadExtractor(modelId));
+  const extractor = await load();
+  if (!extractor) return { ok: false, reason: 'embedder-not-installed' };
+
+  let newVec;
+  try {
+    const out = await extractor(newText, { pooling: 'mean', normalize: true });
+    newVec = (out.tolist())[0] ?? out.tolist();
+    // Single-text extractor output is [[...]]; the fake seam may return [...].
+    if (Array.isArray(newVec[0])) newVec = newVec[0];
+  } catch (err) {
+    return { ok: false, reason: `embed-failed: ${err?.message ?? err}` };
+  }
+
+  // Candidate lookup: SNAPSHOT the embedding cache up front and CLOSE the
+  // connection immediately — the returned similarityFn's lifetime is the
+  // caller's business, and a connection held in the closure would leak one
+  // db handle per capture inside the long-running MCP server (skill-review
+  // blocking finding). Size is fine: 768 floats × 4B ≈ 3KB/row. A missing /
+  // schema-less db (semantic never synced) degrades every pair to Jaccard.
+  let lookup = cacheLookupImpl;
+  if (!lookup) {
+    let bySha = null;
+    try {
+      const { openIndexDb } = await import('./index-db.mjs');
+      const db = openIndexDb({ projectRoot });
+      try {
+        bySha = new Map();
+        for (const row of db.prepare('SELECT content_sha, vector FROM embedding_cache WHERE model = ?').all(modelId)) {
+          bySha.set(
+            row.content_sha,
+            Array.from(new Float32Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength / 4)),
+          );
+        }
+      } finally {
+        db.close();
+      }
+    } catch {
+      bySha = null;
+    }
+    lookup = bySha ? (text) => bySha.get(sha256(`${modelId}\n${text}`)) ?? null : () => null;
+  }
+
+  const { tokenJaccardSimilarity } = await import('./conflict-queue.mjs');
+  const similarityFn = (a, b) => {
+    try {
+      const candidate = lookup(b);
+      if (!candidate || candidate.length !== newVec.length) {
+        return tokenJaccardSimilarity(a, b);
+      }
+      let dot = 0;
+      for (let i = 0; i < newVec.length; i++) dot += newVec[i] * candidate[i];
+      return dot; // normalized vectors → dot IS cosine
+    } catch {
+      return tokenJaccardSimilarity(a, b);
+    }
+  };
+  return { ok: true, similarityFn, backend: 'semantic' };
+}
+
 export async function warmEmbedder({ modelId = DEFAULT_MODEL_ID } = {}) {
   const t0 = Date.now();
   try {

package/src/subcommands.mjs

@@ -27,12 +27,14 @@ import { weeklyCurate } from './weekly-curate.mjs';
 import { autoPersona } from './auto-persona.mjs';
 import { exportPersona, importPersona } from './persona-portability.mjs';
 import { setNativeAutoMemory, nativeMemoryInstallNote } from './native-memory.mjs';
-import { rememberRich, richFactTitle, nonProjectTierNote } from './remember-core.mjs';
+import { rememberRich, richFactTitle, nonProjectTierNote, prepareNearDupGuard } from './remember-core.mjs';
 import { getObservations, citeLink, buildTimeline, recentActivity } from './read-core.mjs';
 import { readHookStdin } from './read-hook-stdin.mjs';
 import { runLazyCompress } from './lazy-compress.mjs';
 import { runDoctor } from './doctor.mjs';
 import { importAnthropicMemory } from './import-anthropic-memory.mjs';
+import { configGet, configSet, configShowOrigin } from './config-core.mjs';
+import { importClaudeMd } from './import-claude-md.mjs';
 import { extractTranscript, discoverSessions } from './transcripts.mjs';
 import { runRepair } from './repair.mjs';
 import { runRoll, ROLL_SCOPES } from './roll.mjs';
@@ -60,6 +62,8 @@ import { overrideTrust as overrideTrustAction } from './trust.mjs';
 import { resolveConflictQueue, mergeScratchpadBullets } from './conflict-queue.mjs';
 import { resolveReviewQueue } from './review-queue.mjs';
 import { createInterface } from 'node:readline';
+import { spawnSync } from 'node:child_process';
+import { checkKitBinding } from './native-binding.mjs';
 import { resolve as resolvePath, join, basename } from 'node:path';
 
 const NOTICE_PREFIX = 'not yet implemented';
@@ -97,7 +101,71 @@ export function formatSemanticSummary(semantic, { noHooks = false } = {}) {
  * summary, and reports the CLAUDE.md action (created / appended /
  * replaced / upgraded / downgrade-blocked / forced-downgrade / unchanged).
  */
-async function runInstall(options /* , command */) {
+// Task 141a (D-129): the install-time binding ask. npm 12 blocks
+// better-sqlite3's binding build on a fresh `npm install -g` — the user's
+// 2026-06-12 steer: ask AT INSTALL, never leave it to a secondary command.
+// Interactive consent is required because the fix is itself an
+// `npm install -g` (the design §14 ask-before-install rule); non-interactive
+// runs print the command instead. All deps injectable for tests.
+async function offerBindingFix(nativeBinding, options, { log, logError }) {
+  if (!nativeBinding || nativeBinding.ok) return;
+  const remedy = nativeBinding.remedy;
+  logError(
+    `  warning: better-sqlite3's native binding is unavailable (${nativeBinding.reason}).`,
+  );
+  logError(
+    '  Most common cause: npm 12 blocks dependency install scripts by default (a Node major upgrade is the other). Search/reindex cannot work until the binding is rebuilt.',
+  );
+  // An explicit askImpl implies a consent channel exists (the test seam /
+  // programmatic caller); only the readline default needs a real TTY.
+  const interactive =
+    options?.interactive ?? (options?.askImpl ? true : process.stdin.isTTY === true);
+  const askFn =
+    options?.askImpl ??
+    (interactive
+      ? (question) =>
+          new Promise((resolveAnswer) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(question, (answer) => {
+              rl.close();
+              resolveAnswer(answer);
+            });
+          })
+      : null);
+  if (!interactive || !askFn) {
+    logError(`  Fix it any time with: ${remedy}`);
+    return;
+  }
+  const answer = String(await askFn(`  Fix it now by running \`${remedy}\`? [Y/n] `))
+    .trim()
+    .toLowerCase();
+  const yes = answer === '' || answer === 'y' || answer === 'yes';
+  if (!yes) {
+    log(`  Skipped. Fix it any time with: ${remedy}`);
+    return;
+  }
+  const fixRunner =
+    options?.fixRunner ??
+    ((cmd) =>
+      // Constant command under shell:true (npm is npm.cmd on Windows); the
+      // 10-min ceiling mirrors buildDefaultNpmRunner's spawn discipline.
+      spawnSync(cmd, { stdio: 'inherit', shell: true, timeout: 600_000 }));
+  const r = fixRunner(remedy);
+  const reProbe = options?.reProbe ?? checkKitBinding;
+  const after = r.status === 0 ? reProbe() : { ok: false };
+  if (after.ok) {
+    log('  Binding rebuilt — search is ready.');
+  } else {
+    logError(`  The binding is still unavailable — run it manually later: ${remedy}`);
+  }
+}
+
+// Exported for tests (Task 141a) — dep-injectable (cwd / userTier / log /
+// logError / bindingProbe / askImpl / fixRunner / reProbe / interactive) on
+// the runImportClaudeMd pattern. Defaults unchanged for production.
+export async function runInstall(options /* , command */) {
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
   // commander maps `--no-hooks` to options.hooks === false.
   const noHooks = !!(options && options.hooks === false);
   const verbose = !!(options && options.verbose);
@@ -110,6 +178,9 @@ async function runInstall(options /* , command */) {
     // to options.withSemantic.
     withSemantic: !!(options && options.withSemantic),
     noSemantic: !!(options && options.semantic === false),
+    projectRoot: options?.cwd,
+    userTier: options?.userTier,
+    bindingProbe: options?.bindingProbe,
   });
 
   // Outcome over inventory (self-test UX finding): state the resulting state +
@@ -117,7 +188,7 @@ async function runInstall(options /* , command */) {
   // read like a problem on a FRESH folder — the "skipped" are the cross-project
   // user tier at ~/.claude-memory-kit/ (OUTSIDE this folder), already on disk.
   // The full per-tier breakdown is --verbose only.
-  const projectName = basename(resolvePath(process.cwd()));
+  const projectName = basename(result.projectRoot);
   const wired =
     result.hooks.action === 'wired' || result.hooks.action === 'unchanged';
   const broughtSomethingNew =
@@ -126,20 +197,20 @@ async function runInstall(options /* , command */) {
     result.claudeMd.action === 'created';
 
   if (broughtSomethingNew) {
-    console.log(
+    log(
       `cmk install: ${projectName} ready — context/ scaffolded${
         wired ? ', hooks wired' : ''
       }.`,
     );
   } else {
-    console.log(
+    log(
       `cmk install: ${projectName} already set up (your edits preserved)${
         wired ? ', hooks refreshed' : ''
       }.`,
     );
   }
   if (wired) {
-    console.log(
+    log(
       '  Restart Claude Code to activate. Complete install — no separate /plugin step needed.',
     );
   }
@@ -147,35 +218,39 @@ async function runInstall(options /* , command */) {
   // Auto Memory by default; surface the one-command opt-out (null when already
   // opted out, so we don't nag).
   const nativeNote = nativeMemoryInstallNote(result.projectRoot);
-  if (nativeNote) console.log(nativeNote);
+  if (nativeNote) log(nativeNote);
   // Task 46: semantic-recall outcome (pure formatter, Task 125.4 — testable
   // without spawning install; the error case returns null because enableSemantic
   // errors already land in result.errors and print through the error path).
   const semanticLine = formatSemanticSummary(result.semantic, { noHooks });
-  if (semanticLine) console.log(semanticLine);
+  if (semanticLine) log(semanticLine);
   if (verbose) {
-    console.log(
+    log(
       `  files: ${result.created.length} created, ${result.skipped.length} already present` +
         (result.skipped.length
           ? ' (incl. the cross-project user tier at ~/.claude-memory-kit/, outside this folder)'
           : ''),
     );
-    console.log(
+    log(
       `  .gitignore=${result.gitignore.action} · CLAUDE.md=${result.claudeMd.action} · hooks=${result.hooks.action}`,
     );
   }
 
   if (result.claudeMd.action === 'downgrade-blocked') {
-    console.error(
+    logError(
       `  warning: CLAUDE.md already has a newer kit block (v${result.claudeMd.oldVersion}). ` +
         `Re-run with --force to downgrade.`
     );
   }
 
   if (result.errors.length > 0) {
-    for (const e of result.errors) console.error(`  error: ${e.path}: ${e.error}`);
+    for (const e of result.errors) logError(`  error: ${e.path}: ${e.error}`);
     process.exitCode = 1;
   }
+
+  // Task 141a: the binding ask comes LAST — it's the one thing the user may
+  // still need to act on, and the tail of install output is what gets read.
+  await offerBindingFix(result.nativeBinding, options, { log, logError });
 }
 
 /**
@@ -656,7 +731,10 @@ export function parseFactInput(options, { readFile, readStdin } = {}) {
   };
 }
 
-export function runRemember(textParts, options, deps = {}) {
+// Task 143: async since the near-dup guard may embed the incoming text
+// (one model call, explicit path only). Commander awaits actions; the
+// terse-path tests were updated to await (contract change, intent preserved).
+export async function runRemember(textParts, options, deps = {}) {
   const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
   const userDir =
     deps.userDir ?? process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
@@ -717,6 +795,10 @@ export function runRemember(textParts, options, deps = {}) {
   const tier = 'P';
   const trust = options?.trust ?? 'high';
   const section = options?.section ?? 'Active Threads';
+  // Task 143 (D-130): semantic near-dup guard — extra opts only when this
+  // project is semantic-configured and the embedder is available; {} keeps
+  // the literal pipeline (graceful degradation, never blocks capture).
+  const nearDup = await prepareNearDupGuard({ projectRoot, text, ...(deps.nearDupGuard ? { prepareImpl: deps.nearDupGuard.prepareImpl, resolveModeImpl: deps.nearDupGuard.resolveModeImpl } : {}) });
   const r = memoryWrite({
     action: 'add',
     text,
@@ -727,22 +809,23 @@ export function runRemember(textParts, options, deps = {}) {
     source: 'user-explicit',
     projectRoot,
     userDir,
+    ...nearDup,
   });
   if (r.action === 'error') {
     for (const e of r.errors ?? [`error (${r.errorCategory})`]) {
-      console.error(`cmk remember: ${e}`);
+      logError(`cmk remember: ${e}`);
     }
     process.exitCode = 2;
     return;
   }
   if (r.action === 'queued') {
-    console.log(
-      `cmk remember: queued for review — a higher-trust fact already covers this. ` +
+    log(
+      `cmk remember: queued for review — a similar or higher-trust fact already covers this. ` +
         `Resolve with \`cmk queue conflicts\` (${r.path}).`,
     );
     return;
   }
-  console.log(
+  log(
     `cmk remember: saved to P/MEMORY.md (${section})${r.id ? ` [${r.id}]` : ''}`,
   );
 }
@@ -1183,12 +1266,93 @@ async function runDoctorCli(/* options */) {
       `Summary: ${counts.pass} pass · ${counts.fail} fail · ${counts.skip} skip (${r.duration_ms}ms)`,
     );
     if (counts.fail > 0) process.exitCode = 1;
+
+    // Task 144 (D-130): the memory-HEALTH section — content quality, not
+    // plumbing. Informational only: read-only, never changes the exit code,
+    // best-effort (a content-stat hiccup must not fail a healthy doctor).
+    try {
+      const { analyzeMemoryHealth, formatMemoryHealth } = await import('./memory-health.mjs');
+      console.log('');
+      console.log(formatMemoryHealth(analyzeMemoryHealth({ projectRoot })));
+    } catch {
+      // informational section only — stay silent on failure
+    }
   } catch (err) {
     console.error(`cmk doctor: unexpected error: ${err?.message ?? err}`);
     process.exitCode = 2;
   }
 }
 
+// Task 129 (D-121): `cmk config` — real, replacing the v0.1.0 stub. Dotted-key
+// get/set/--show-origin over the per-tier settings.json files. Dep-injectable
+// (cwd/userDir/log/logError) on the runImportClaudeMd pattern for testing the
+// CLI surface. The pure resolution/mutation lives in config-core.mjs.
+const TIER_FLAG_TO_NAME = { local: 'local', project: 'project', user: 'user' };
+
+export function runConfigGet(key, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const r = configGet(key, { projectRoot, userDir });
+  if (!r.found) {
+    logError(`cmk config get: '${key}' is not set in any tier`);
+    process.exitCode = 2;
+    return r;
+  }
+  log(typeof r.value === 'string' ? r.value : JSON.stringify(r.value));
+  return r;
+}
+
+export function runConfigSet(key, value, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const tier = TIER_FLAG_TO_NAME[options?.tier ?? 'project'] ?? 'project';
+  const r = configSet(key, value, { projectRoot, userDir, tier });
+  if (!r.ok) {
+    logError(`cmk config set: ${r.error}`);
+    process.exitCode = 2;
+    return r;
+  }
+  log(`cmk config set: ${key} = ${value} (${r.tier} tier)`);
+  return r;
+}
+
+export function runConfigShowOrigin(key, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const r = configShowOrigin(key, { projectRoot, userDir });
+  if (!r.found) {
+    logError(`cmk config --show-origin: '${key}' is not set in any tier`);
+    process.exitCode = 2;
+    return r;
+  }
+  for (const e of r.entries) {
+    const val = typeof e.value === 'string' ? `"${e.value}"` : JSON.stringify(e.value);
+    const note = e.winner ? '' : `   (shadowed by ${e.shadowedBy})`;
+    log(`${e.tier.padEnd(8)} ${e.path}   ${val}${note}`);
+  }
+  return r;
+}
+
+// The parent `cmk config` action: handle the --show-origin flag here; the
+// get/set children carry their own actions (wired in the registry below).
+// Exported for the branch test (the no-subcommand path).
+export function runConfigCli(options /* , command */) {
+  if (options?.showOrigin) {
+    return runConfigShowOrigin(options.showOrigin, options);
+  }
+  const logError = options?.logError ?? console.error;
+  logError(
+    'cmk config: specify a subcommand — `get <key>`, `set <key> <value>`, or `--show-origin <key>`.',
+  );
+  process.exitCode = 2;
+}
+
 async function runRepairCli(options /* , command */) {
   const projectRoot = resolvePath(process.cwd());
   const userDir = join(homedir(), '.claude-memory-kit');
@@ -1304,6 +1468,59 @@ export async function runImportAnthropicMemory(options = {}) {
   }
 }
 
+// Task 142 (D-130): onboard from an existing rules file. Dep-injectable
+// (projectRoot / log / logError / importFn) on the runImportAnthropicMemory
+// pattern so the real CLI path is verifiable in a sandbox. `file` is the
+// optional positional (commander passes it first), defaulting to CLAUDE.md.
+export async function runImportClaudeMd(file, options = {}) {
+  const projectRoot = options?.projectRoot ?? resolvePath(process.cwd());
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const dryRun = options?.dryRun === true;
+  const acceptAll = options?.yes === true;
+  const importFn = options?.importFn ?? importClaudeMd;
+  try {
+    const r = await importFn({ projectRoot, file, dryRun, acceptAll });
+    if (r.action === 'error') {
+      logError(`cmk import-claude-md: error — ${(r.errors ?? []).join('; ')}`);
+      process.exitCode = 2;
+      return r;
+    }
+    if (r.reason === 'no-source') {
+      log(`cmk import-claude-md: no rules file found at ${r.sourcePath}`);
+      return r;
+    }
+    if (r.reason) {
+      // e.g. read-source-failed — completed-with-failure must not print the
+      // success-shaped "applied 0" line (skill-review 2026-06-12 finding).
+      logError(`cmk import-claude-md: ${r.reason} (${r.sourcePath})`);
+      process.exitCode = 2;
+      return r;
+    }
+    const listProposals = () => {
+      for (const p of r.proposals) log(`  + [${p.type}] L${p.line}: ${p.text}`);
+    };
+    if (r.mode === 'dry-run') {
+      log(`cmk import-claude-md: dry-run — ${r.proposals.length} proposal(s), ${r.skipped} duplicate(s) skipped`);
+      listProposals();
+      return r;
+    }
+    if (r.mode === 'requires-confirmation') {
+      log(`cmk import-claude-md: ${r.proposals.length} proposal(s) ready to apply.`);
+      log('  Re-run with --yes to apply, or --dry-run to inspect.');
+      listProposals();
+      return r;
+    }
+    const rejectedNote = r.rejected > 0 ? `, ${r.rejected} rejected by Poison_Guard` : '';
+    const errorNote = r.errors > 0 ? `, ${r.errors} error(s)` : '';
+    log(`cmk import-claude-md: applied ${r.accepted} fact(s), skipped ${r.skipped} duplicate(s)${rejectedNote}${errorNote}`);
+    return r;
+  } catch (err) {
+    logError(`cmk import-claude-md: unexpected error: ${err?.message ?? err}`);
+    process.exitCode = 2;
+  }
+}
+
 async function runTranscriptsDispatch(childName, options) {
   if (childName === 'extract') {
     return runTranscriptsExtract(options);
@@ -1426,7 +1643,10 @@ async function runMcpDispatch(childName) {
     }
     return;
   }
-  console.error(`cmk mcp: ${NOTICE_PREFIX} (unknown sub-verb '${childName}')`);
+  // A bare `cmk mcp` (no sub-verb) reaches here post-Task-129 (the parent
+  // action is now wired) — commander passes an options object, not a string.
+  const verb = typeof childName === 'string' ? childName : '(none)';
+  console.error(`cmk mcp: ${NOTICE_PREFIX} (run \`cmk mcp serve\`; got sub-verb '${verb}')`);
   process.exitCode = 2;
 }
 
@@ -1437,7 +1657,10 @@ async function runQueueDispatch(childName) {
   if (childName === 'review') {
     return runQueueReview();
   }
-  console.log(`cmk queue: ${NOTICE_PREFIX} (unknown sub-verb '${childName}')`);
+  // A bare `cmk queue` reaches here post-Task-129 (parent action wired);
+  // commander passes an options object, not a string sub-verb.
+  const verb = typeof childName === 'string' ? childName : '(none)';
+  console.log(`cmk queue: ${NOTICE_PREFIX} (run \`cmk queue review\` or \`cmk queue conflicts\`; got '${verb}')`);
   process.exitCode = 2;
 }
 
@@ -1798,27 +2021,32 @@ export const subcommands = [
   },
   {
     name: 'config',
-    description: 'settings access (per design §7.2)',
-    milestone: 'v0.1.x',
+    description: 'read/write kit settings (context/settings.json) without hand-editing JSON',
+    milestone: 129,
     optionSpec: [
-      { flags: '--show-origin <key>', description: 'print where each value comes from (project / user / local tier)' },
+      { flags: '--show-origin <key>', description: 'print every tier that defines a setting (winner + shadowed) — the "where did this come from?" debug surface' },
     ],
     children: [
       {
         name: 'get',
-        description: 'print the resolved value of a setting',
-        argSpec: [{ flags: '<key>', description: 'setting key (dotted path)' }],
+        description: 'print the resolved value of a setting (dotted key; local > project > user)',
+        argSpec: [{ flags: '<key>', description: 'setting key (dotted path, e.g. search.default_mode)' }],
+        action: (key, options) => runConfigGet(key, options),
       },
       {
         name: 'set',
-        description: 'set a setting in the current tier',
+        description: 'set a setting in the project tier (or --local)',
         argSpec: [
           { flags: '<key>', description: 'setting key (dotted path)' },
-          { flags: '<value>', description: 'new value' },
+          { flags: '<value>', description: 'new value (true/false/number coerced; else string)' },
+        ],
+        optionSpec: [
+          { flags: '--local', description: 'write to the local tier (context.local/, gitignored) instead of project' },
         ],
+        action: (key, value, options) => runConfigSet(key, value, { tier: options?.local ? 'local' : 'project' }),
       },
     ],
-    action: stub('config', 'v0.1.x'),
+    action: runConfigCli,
   },
   {
     name: 'import-anthropic-memory',
@@ -1830,6 +2058,19 @@ export const subcommands = [
     ],
     action: runImportAnthropicMemory,
   },
+  {
+    name: 'import-claude-md',
+    description: 'onboard from an existing rules file (CLAUDE.md / .cursorrules / AGENTS.md) — parse it into typed facts through the safe write path',
+    milestone: 142,
+    argSpec: [
+      { flags: '[file]', description: 'rules file to import, relative to the project root (default: CLAUDE.md)' },
+    ],
+    optionSpec: [
+      { flags: '--dry-run', description: 'preview the typed proposals without modifying files' },
+      { flags: '--yes', description: 'apply every proposal without prompting (apply requires explicit --yes)' },
+    ],
+    action: runImportClaudeMd,
+  },
   {
     name: 'transcripts',
     description: "extract clean markdown transcripts from Claude Code session jsonls under ~/.claude/projects/",

package/src/transcript-index.mjs

@@ -15,7 +15,7 @@
 //   chunkTranscript(text) → [{heading, body, sourceLine, chunkIdx}]  (pure)
 //   syncTranscriptChunks({db, projectRoot, now?}) → {files, chunks}
 
-import { createHash } from 'node:crypto';
+import { hashContent } from './content-hash.mjs';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
@@ -57,8 +57,11 @@ export function chunkTranscript(text) {
   return chunks;
 }
 
+// Transcript-chunk fingerprint for the `files`-table diff key (column name
+// `sha1` kept for checkpoint back-compat; algorithm is SHA-256 via hashContent,
+// D-149). Self-heals on the first post-upgrade boot like the observation index.
 function sha1(text) {
-  return createHash('sha1').update(text, 'utf8').digest('hex');
+  return hashContent(text);
 }
 
 // Task 126 (D-119) — the raw-tier scope covers BOTH halves of the session

package/src/write-fact.mjs

@@ -21,6 +21,7 @@ import { reindex } from './reindex.mjs';
 import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { sanitizeHomePaths } from './sanitize.mjs';
+import { sanitizePrivacyTags } from './privacy.mjs';
 import { checkPoisonGuard, logPoisonGuardRejection } from './poison-guard.mjs';
 
 const VALID_TYPES = new Set(['user', 'feedback', 'project', 'reference']);
@@ -157,6 +158,14 @@ export function writeFact(opts = {}) {
   // — that's its purpose. The id hashes the SANITIZED body, so dedup keys on
   // what actually lands on disk.
   let { body, title } = opts;
+  // Privacy: strip <private>…</private> FIRST, on EVERY tier (cut-gate
+  // v0.3.1 finding — the tag was honored only by the UserPromptSubmit hook,
+  // so a fact written via cmk remember/mk_remember/import kept the secret).
+  // Runs before home-path sanitization, Poison_Guard, and id-generation, so
+  // the redacted body is what gets screened, hashed (dedup keys on what
+  // lands), and written.
+  body = sanitizePrivacyTags(body);
+  title = sanitizePrivacyTags(title);
   if (opts.tier === 'P' || opts.tier === 'U') {
     body = sanitizeHomePaths(body);
     title = sanitizeHomePaths(title);
@@ -252,10 +261,32 @@ export function writeFact(opts = {}) {
   // 2026-06-03 — "users should get it working from the start"). Best-effort: the
   // fact is already durably on disk, so an index-rebuild hiccup must not turn a
   // successful capture into an error — the next reindex/search self-heals.
+  //
+  // D-152: the failure is OBSERVABLE, not silently swallowed. A detached
+  // auto-extract child whose reindex was killed mid-rebuild (hook ceiling) used
+  // to leave INDEX.md lagging with ZERO trace — so a stale committed INDEX was
+  // undiagnosable (the user caught a 5-fact lag in the cut-gate). On throw we
+  // now record an INDEX_REBUILD_FAILED audit entry; HC-4 still detects the drift
+  // and `cmk reindex` corrects it. The `_reindexFn` seam is test-only.
+  const doReindex = opts._reindexFn ?? reindex;
   try {
-    reindex({ tier: opts.tier, projectRoot: opts.projectRoot, userDir: opts.userDir, warn: () => {} });
-  } catch {
-    // index rebuild is best-effort; capture already succeeded
+    doReindex({ tier: opts.tier, projectRoot: opts.projectRoot, userDir: opts.userDir, warn: () => {} });
+  } catch (reindexErr) {
+    // index rebuild is best-effort; capture already succeeded — but leave a
+    // trace so a lagging committed INDEX is diagnosable, never silent.
+    try {
+      appendAuditEntry(tierRoot, {
+        ts: createdAt,
+        action: 'index-rebuild-failed',
+        tier: opts.tier,
+        id,
+        reasonCode: REASON_CODES.INDEX_REBUILD_FAILED,
+        paths: { after: path },
+        extra: { error: String(reindexErr?.message ?? reindexErr) },
+      });
+    } catch {
+      // even the audit append is best-effort; the fact is already on disk
+    }
   }
 
   // Default create-audit (Task 123.A / D-103). writeFact is the single boundary