@lh8ppl/claude-memory-kit 0.3.2 → 0.3.4

package/README.md

@@ -20,7 +20,7 @@
 - **Bounded by compression** — session → daily → weekly Haiku rollups (cron or lazy-on-read) keep the snapshot small as history grows. The session-buffer rollup self-heals at session start too, so memory stays bounded even if you never cleanly close the window.
 - **Don't start empty — import the rules you already own** — `cmk import-claude-md` parses an existing `CLAUDE.md` / `.cursorrules` / `AGENTS.md` into typed, searchable facts through the same safe write path (secret screening, sanitization, dedup), with provenance back to source file + line. `--dry-run` previews first.
 - **Per-project, in-repo** — `context/` lives inside your project and travels with `git clone`. Each project keeps its own memory.
-- **8 health checks** — `cmk doctor` validates hook wiring, distill freshness, transcript firing, INDEX consistency, cron registration, native-memory coexistence, stale locks, and native-binding health (npm 12 readiness) — each failure with a repair command.
+- **9 health checks** — `cmk doctor` validates hook wiring, distill freshness, transcript firing, INDEX consistency, cron registration, native-memory coexistence, stale locks, native-binding health (npm 12 readiness), and version drift (a project scaffold behind your installed `cmk` after an update) — each failure with a repair command.
 
 ## Install — pick ONE route
 
@@ -47,11 +47,13 @@ cmk doctor         # verify, then restart Claude Code
 Inside Claude Code:
 
 ```text
-/plugin marketplace add LH8PPL/claude-memory-kit
-/plugin install claude-memory-kit
+/plugin marketplace add LH8PPL/claude-memory-kit   # add this repo as a plugin source (once per machine)
+/plugin install claude-memory-kit                  # install the global machinery — hooks + skills (once per machine)
+cd ~/my-project                                    # the project you want memory in — bootstrap scaffolds into the CURRENT dir
+/claude-memory-kit:bootstrap                        # scaffold this project's context/ memory tree (once per project)
 ```
 
-Then say *"bootstrap the memory system"* to scaffold this project's `context/`. The plugin bundles the hooks + the `bootstrap`, `memory-write`, and `memory-search` skills, so it's complete without the npm CLI (add the CLI later only if you want `cmk search` / `cmk doctor` / cron).
+The first two commands are **global** (per machine); `bootstrap` is **per project** — run it again (after a `cd`) in each project. The plugin bundles the hooks + the `bootstrap`, `memory-write`, and `memory-search` skills, so it's complete without the npm CLI (add the CLI later only if you want `cmk search` / `cmk doctor` / cron).
 
 ## CLI
 
@@ -60,9 +62,9 @@ Most-used commands (full list via `cmk --help`):
 | Command | Purpose |
 | --- | --- |
 | `cmk install` | Scaffold `context/` + the `memory-write`/`memory-search` skills + `.gitignore` + CLAUDE.md block + wire hooks (`--no-hooks` for scaffold-only) |
-| `cmk doctor` | Run HC-1..HC-8 health checks, surface repair commands |
+| `cmk doctor` | Run HC-1..HC-9 health checks, surface repair commands |
 | `cmk repair --hooks` / `--locks` / `--index` / `--all` | Idempotent self-repair |
-| `cmk search "<query>" [--mode keyword\|semantic\|hybrid] [--scope facts\|transcripts]` | Search memory — by meaning with the embedder (hybrid default after `--with-semantic`); `--scope transcripts` = the raw session record |
+| `cmk search "<query>" [--mode keyword\|semantic\|hybrid] [--scope facts\|transcripts\|decisions]` | Search memory — by meaning with the embedder (hybrid default after `--with-semantic`); `--scope transcripts` = the raw session record; `--scope decisions` = the decision journal (history / "what did we reject") |
 | `cmk get <id…>` / `cmk timeline <id>` / `cmk cite <id>` / `cmk recent-activity` | Read the index back — full fact bodies + provenance, sequential context around an observation, a canonical citation link, recent changes (the CLI side of the `mk_*` MCP read tools) |
 | `cmk roll --scope now\|today\|recent` | Manually trigger a compression pipeline |
 | `cmk register-crons [--dry-run] [--unregister]` | Register daily + weekly jobs with cron / launchd / Task Scheduler |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {

package/src/auto-extract.mjs

@@ -53,6 +53,7 @@ import { hashContent } from './content-hash.mjs';
 import { memoryWrite } from './memory-write.mjs';
 import { writeFact } from './write-fact.mjs';
 import { buildRichFactBody, slugifyFact } from './rich-fact.mjs';
+import { sanitizeForTitle } from './sanitize.mjs';
 import { HaikuTimeoutError } from './compressor.mjs';
 import { pidIsAlive } from './lock-discipline.mjs';
 import { nowIso } from './audit-log.mjs';
@@ -638,9 +639,16 @@ function routeMedium({ candidate, projectRoot, ts }) {
 // Direct-to-fact-store (NOT the review queue the terse medium-trust path uses):
 // the point of Task 103 is AUTOMATIC native-parity capture — native writes its
 // fact files with no approval step, so parity requires the same. The fact store
-// is searchable-but-not-full-trust-injected, writeFact already screens every
-// write (home-path sanitize + Poison_Guard + schema + INDEX/reindex), and a
-// later explicit `cmk remember` (trust:high) supersedes. See design §6.4.
+// is searchable-but-not-full-trust-injected, writeFact screens the body +
+// frontmatter (Poison_Guard + home-path sanitize + schema + INDEX/reindex), and
+// a later explicit `cmk remember` (trust:high) supersedes. See design §6.4.
+//
+// CAVEAT (F-V0.3.3-2): writeFact does NOT sanitize the SLUG/filename — the slug
+// is `slugifyFact(title)` derived HERE, before writeFact runs. So the title MUST
+// be routed through sanitizeForTitle first, or a home path in Haiku's candidate
+// title (auto-extract runs every turn, no user action) leaks the username into a
+// COMMITTED filename. This was the same bug as cmk remember — the old comment
+// here wrongly assumed "writeFact already sanitizes" the whole write.
 //
 // trust:medium / write_source:auto-extract marks it as a Haiku synthesis
 // (proposal-grade), below the explicit-high tier. The body is built by the SAME
@@ -652,11 +660,14 @@ function routeRichFact({ candidate, projectRoot, ts }) {
     why: candidate.why,
     how: candidate.how,
   });
+  // Sanitize the title BEFORE deriving the slug (F-V0.3.3-2) — writeFact won't
+  // catch a home path in the slug/filename. One helper, same as cmk remember.
+  const title = sanitizeForTitle(candidate.title);
   return writeFact({
     tier: 'P',
     type: candidate.type,
-    slug: slugifyFact(candidate.title),
-    title: candidate.title,
+    slug: slugifyFact(title),
+    title,
     body,
     writeSource: 'auto-extract',
     trust: 'medium',

package/src/claude-md.mjs

@@ -64,7 +64,10 @@ function buildBlock(content, version) {
  *     gracefully from a corrupted block (e.g. the user accidentally
  *     deleted the end marker by hand).
  */
-function findManagedBlock(text) {
+// Exported (Task 162) for version-drift.mjs (HC-9) — reads the managed-block
+// version marker without re-implementing the parser. Public contract: returns
+// `{version, corrupted, ...}` or null.
+export function findManagedBlock(text) {
   const startMatch = text.match(MARKER_START_RE);
   if (!startMatch) return null;
 
@@ -107,7 +110,9 @@ function parseVersion(v) {
  *   compareVersions('1.0.0', '1.0.0') === 0
  *   compareVersions('2.0.0', '1.9.9') === 1
  */
-function compareVersions(a, b) {
+// Exported (Task 162) for version-drift.mjs (HC-9). Public contract: -1/0/1,
+// strips a `-prerelease` suffix before comparing.
+export function compareVersions(a, b) {
   const av = parseVersion(a);
   const bv = parseVersion(b);
   for (let i = 0; i < 3; i++) {

package/src/compress-retry.mjs

@@ -0,0 +1,155 @@
+// Bounded, transient-only retry for the Haiku compress call (Task 161 / D-175).
+//
+// WHY this exists: the v0.3.3 cut-gate surfaced `haiku_timeout` / `compress_failed`
+// failures on the compression path. Measurement (D-174) proved the failure is
+// ENVIRONMENTAL/TRANSIENT, not input-size-driven — the kit's own compress.log shows
+// the largest SUCCESS (470 KB) bigger than the largest timeout (334 KB), and a 9 KB
+// input timed out. So the fix is a RETRY (a re-call usually succeeds), not an input
+// cap. The kit inherited the no-retry shape from claude-remember (its precedent —
+// which doesn't retry either); the rest of the field does.
+//
+// The SHAPE is grounded in a 9-system code read
+// (docs/research/2026-06-19-llm-call-retry-patterns-cross-system.md), which converges
+// unanimously on: bounded attempts, exponential backoff, retry ONLY the transient
+// class keyed on the error TYPE, NEVER the deterministic class, reraise after
+// exhaustion. graphiti's `is_server_or_retry_error` predicate + Letta's
+// ValueError(retry)-vs-RuntimeError(don't) split are the model.
+//
+// COMPOSITION (design §8.5 / D-42): the SessionEnd-hook `compressSession` runs under
+// a 60s ceiling CONCURRENT with autoPersona — a 50s attempt + a 50s retry = 100s
+// blows the ceiling. So callers under the ceiling pass `maxAttempts: 1` (no retry —
+// they delegate the retry to the ceiling-free lazy path via the existing
+// restore-on-failure, D-79); only the ceiling-free paths (daily-distill /
+// weekly-curate / lazy compress) pass `maxAttempts: 2`.
+//
+// COOLDOWN INTERACTION (skill-review I-1): the 120s Haiku cooldown marker is touched
+// on SUCCESS only, and the callers gate `isCooldownActive` ONCE before the retry loop.
+// A retry WIDENS the existing "no marker until success" window (~50s → ~100s), so a
+// second hook firing mid-retry could pass the gate and start its own compress. This
+// is NOT a new bug class — the window pre-exists the retry — and the D-79 claim-rename
+// mutex (renameSync of now.md is the real lock) still prevents any corruption: only
+// one roll wins the rename; the other reads an empty buffer and skips. The retry only
+// makes a pre-existing benign window ~2× wider; no marker change is warranted.
+//
+// NO JITTER (skill-review M-2): the field (graphiti) jitters its backoff
+// (wait_random_exponential) to avoid thundering-herd across many concurrent clients.
+// The kit's compress is a single low-concurrency local process (one detached child at
+// a time, gated by the cooldown), so there is no herd to avoid — a plain exponential
+// backoff is sufficient and keeps the timing deterministic for tests.
+
+/**
+ * Classify a compress() rejection as transient (worth a retry) or deterministic
+ * (a re-call re-fails identically — don't waste the attempt or the budget).
+ *
+ * Transient (retry):
+ *   - HaikuTimeoutError (`category: 'haiku_timeout'`) — `claude --print` was slow;
+ *     the D-174 environmental case. A re-call usually succeeds.
+ *   - HaikuFailedError (`category: 'haiku_failed'`) whose stderr looks like a
+ *     transient server/overload/rate-limit blip (the field's 5xx/429/overloaded
+ *     class), classified from the `exit_code`/`stderr` that 161.6a now captures.
+ *
+ * Deterministic (do NOT retry):
+ *   - A spawn error (`code: 'ENOENT'` etc.) — the binary isn't there; re-spawning
+ *     re-fails.
+ *   - A HaikuFailedError whose stderr is a known-deterministic class (auth /
+ *     invalid-key / policy / bad-request) — retrying always re-fails (graphiti's
+ *     explicit "retrying policy-violating content will always fail").
+ *   - Anything unrecognized — default to NOT retryable (conservative: an unknown
+ *     failure is more likely a real bug than a blip, and a wasted retry costs the
+ *     hook budget).
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isRetryableCompressError(err) {
+  if (!err || typeof err !== 'object') return false;
+
+  // Timeout = the transient/environmental case (D-174). Always retryable.
+  if (err.category === 'haiku_timeout') return true;
+
+  // Spawn-level failure (ENOENT / EACCES / EINVAL) — the binary/permissions are
+  // wrong; re-spawning re-fails identically. Never retryable.
+  if (typeof err.code === 'string' && /^E[A-Z]+$/.test(err.code)) return false;
+
+  // Non-zero exit — conditional on WHY (the exit_code/stderr 161.6a captures).
+  if (err.category === 'haiku_failed') {
+    const stderr = String(err.stderr ?? '').toLowerCase();
+    // Known-DETERMINISTIC classes: a re-call re-fails. Never retry these.
+    // (Skill-review I-2: `not found` was DROPPED — it appears in transient
+    // contexts too, e.g. a transient "host not found" / "upstream not found,
+    // retrying"; a deterministic 404 from `claude --print` is unlikely, and the
+    // conservative default below already catches a genuine unknown deterministic
+    // failure. Keeping only HIGH-CONFIDENCE deterministic markers.)
+    if (
+      /auth|invalid[_ -]?(api[_ -]?)?key|unauthor|forbidden|permission|policy|invalid[_ -]?request|bad[_ -]?request/.test(
+        stderr,
+      )
+    ) {
+      return false;
+    }
+    // Known-TRANSIENT classes: server/overload/rate blips recover on a re-call.
+    if (/overload|rate[_ -]?limit|429|5\d\d|timeout|timed[_ -]?out|temporar|unavailable|connection|network|reset/.test(stderr)) {
+      return true;
+    }
+    // Unknown non-zero exit → conservative: do NOT retry (treat as deterministic).
+    return false;
+  }
+
+  return false;
+}
+
+/**
+ * Call `backend.compress(opts)` with a bounded, transient-only retry.
+ *
+ * @param {{compress: (opts: object) => Promise<any>}} backend
+ * @param {object} opts                  — passed verbatim to backend.compress on every attempt.
+ * @param {object} [config]
+ * @param {number} [config.maxAttempts=2] — TOTAL attempts (1 = no retry; the ceiling-bound contract). Field range is 2–4; the kit uses ≤2 (one retry) to fit the budget.
+ * @param {number} [config.baseBackoffMs=600] — exponential backoff base: wait `baseBackoffMs * 2**(attempt-1)` before attempt N+1. 0 disables the wait (tests).
+ * @param {(err: unknown) => boolean} [config.isRetryable=isRetryableCompressError]
+ * @param {(ms: number) => Promise<void>} [config.sleep] — injectable for tests.
+ * @param {(info: {attempt: number, error: unknown}) => void} [config.onRetry] — fired once
+ *   per retry (Task 161.12 observability), BEFORE the backoff, with the FAILED attempt
+ *   number + the (transient) error. Callers use it to record a `retries` count on their
+ *   compress.log entry so a frequent-retry rate (the degrading-environment signal D-174
+ *   is about) is visible. Not fired on a first-try success or a non-retryable failure.
+ * @returns {Promise<any>} the backend.compress result; reraises the last error after exhaustion.
+ */
+export async function compressWithRetry(
+  backend,
+  opts,
+  {
+    maxAttempts = 2,
+    baseBackoffMs = 600,
+    isRetryable = isRetryableCompressError,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    onRetry,
+  } = {},
+) {
+  const attempts = Math.max(1, maxAttempts);
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await backend.compress(opts);
+    } catch (err) {
+      lastErr = err;
+      // Stop immediately if this is the last attempt OR the error isn't transient.
+      if (attempt >= attempts || !isRetryable(err)) {
+        throw err;
+      }
+      // We're going to retry — surface it for observability (161.12), before the wait.
+      if (typeof onRetry === 'function') {
+        try {
+          onRetry({ attempt, error: err });
+        } catch {
+          // onRetry is best-effort instrumentation — never let it break the retry.
+        }
+      }
+      // Exponential backoff before the next attempt (skip the wait when base is 0).
+      const delay = baseBackoffMs > 0 ? baseBackoffMs * 2 ** (attempt - 1) : 0;
+      if (delay > 0) await sleep(delay);
+    }
+  }
+  // Unreachable (the loop either returns or throws), but satisfies control-flow analysis.
+  throw lastErr;
+}

package/src/compress-session.mjs

@@ -37,6 +37,7 @@ import { join, dirname } from 'node:path';
 import { nowIso } from './audit-log.mjs';
 import { ERROR_CATEGORIES } from './result-shapes.mjs';
 import { HaikuTimeoutError } from './compressor.mjs';
+import { compressWithRetry } from './compress-retry.mjs';
 import {
   DEFAULT_COOLDOWN_MS,
   isCooldownActive,
@@ -225,6 +226,12 @@ export async function compressSession({
   now,
   cooldownMs = DEFAULT_COOLDOWN_MS,
   maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES,
+  // Task 161 / D-175: retry policy. DEFAULT 1 = NO retry — the SessionEnd-hook
+  // contract: this fn runs under the 60s ceiling CONCURRENT with autoPersona, where
+  // a 50s attempt + a 50s retry = 100s blows the ceiling. The ceiling-free LAZY
+  // caller (runLazyCompress) passes maxAttempts:2 to opt into one retry; the hook
+  // keeps its restore-on-failure (D-79) and delegates the retry to that lazy path.
+  maxAttempts = 1,
 } = {}) {
   const ts = now ?? nowIso();
   const date = dateFromIso(ts);
@@ -325,14 +332,21 @@ export async function compressSession({
   // restoreRolling call, so the buffer is never stranded in the rolling file.
   // See design §8.5 for the composition rationale.
   let result;
+  let retries = 0; // Task 161.12: count retries (only the lazy maxAttempts:2 path can retry).
   try {
-    result = await backend.compress({
-      input: wrapBufferForPrompt(buffer),
-      instructions,
-      preserveCitationIds: true,
-      maxOutputBytes,
-      timeoutMs: 50_000,
-    });
+    // maxAttempts default 1 (hook contract: no retry); the lazy caller passes 2.
+    // compressWithRetry is a no-op wrapper at maxAttempts:1 (single attempt, reraise).
+    result = await compressWithRetry(
+      backend,
+      {
+        input: wrapBufferForPrompt(buffer),
+        instructions,
+        preserveCitationIds: true,
+        maxOutputBytes,
+        timeoutMs: 50_000,
+      },
+      { maxAttempts, onRetry: () => { retries += 1; } },
+    );
   } catch (err) {
     // Distinguish HAIKU_TIMEOUT (slow Anthropic) from COMPRESS_FAILED
     // (non-zero subprocess exit / spawn ENOENT / etc). Analytics
@@ -357,6 +371,13 @@ export async function compressSession({
       duration_ms,
       success: false,
       error_category: errorCategory,
+      // Task 161 (D-173 observability): capture the STRUCTURED failure reason
+      // (subprocess exit code + stderr) so a `compress_failed` is diagnosable.
+      // Pre-161 the log kept only error_category — the WHY was discarded, which
+      // is why the kit's own 329-byte compress_failed could not be explained.
+      ...(err?.exitCode != null ? { exit_code: err.exitCode } : {}),
+      ...(err?.stderr ? { error_detail: String(err.stderr).slice(0, 500) } : {}),
+      ...(retries > 0 ? { retries } : {}), // 161.12: failed AFTER retrying (lazy path)
     };
     writeCompressLogEntry({ projectRoot, date, entry });
     return {
@@ -397,6 +418,7 @@ export async function compressSession({
     cost_usd: result?.costUSD ?? 0,
     duration_ms,
     success: true,
+    ...(retries > 0 ? { retries } : {}), // 161.12: succeeded after a transient retry (lazy path)
   };
   writeCompressLogEntry({ projectRoot, date, entry });
 

package/src/compressor.mjs

@@ -94,6 +94,23 @@ export class HaikuTimeoutError extends Error {
   }
 }
 
+// Non-zero subprocess exit (the `compress_failed` category). Carries the
+// STRUCTURED exit code + captured stderr so callers can write the real
+// failure reason into compress.log — pre-161 this was a plain Error with
+// the detail buried in `.message`, and the log kept only `error_category`,
+// making a `compress_failed` undiagnosable (the 329-byte failure in the
+// kit's own log that the D-173 investigation could not explain). Mirrors
+// HaikuTimeoutError so the two failure modes carry parallel diagnostics.
+export class HaikuFailedError extends Error {
+  constructor(message, { exitCode, stderr }) {
+    super(message);
+    this.name = 'HaikuFailedError';
+    this.category = 'haiku_failed';
+    this.exitCode = exitCode ?? null;
+    this.stderr = stderr ?? '';
+  }
+}
+
 // SIGTERM → grace window → SIGKILL escalation. Exported so the kill
 // chain itself is independently testable against real OS processes
 // (see tests/spawn-smoke-kill-chain.test.js) — the production code
@@ -292,8 +309,9 @@ export class HaikuViaAnthropicApi extends CompressorBackend {
         if (settled) return; // timeout already fired
         if (code !== 0) {
           settleReject(
-            new Error(
+            new HaikuFailedError(
               `HaikuViaAnthropicApi: claude --print exit ${code}: ${stderr.trim() || '(no stderr)'}`,
+              { exitCode: code, stderr: stderr.trim() },
             ),
           );
           return;

package/src/daily-distill.mjs

@@ -28,6 +28,7 @@ import { join } from 'node:path';
 import { nowIso } from './audit-log.mjs';
 import { ERROR_CATEGORIES } from './result-shapes.mjs';
 import { HaikuTimeoutError } from './compressor.mjs';
+import { compressWithRetry } from './compress-retry.mjs';
 import {
   DEFAULT_COOLDOWN_MS,
   isCooldownActive,
@@ -195,14 +196,23 @@ export async function dailyDistill({
   const instructions = buildDistillInstructions(maxOutputBytes);
 
   let result;
+  let retries = 0; // Task 161.12: count retries so the log shows the retry RATE.
   try {
-    result = await backend.compress({
-      input: buffer,
-      instructions,
-      preserveCitationIds: true,
-      maxOutputBytes,
-      timeoutMs: 50_000,
-    });
+    // Task 161 / D-175: ceiling-free path (cron/detached child, NO 60s hook ceiling)
+    // → bounded transient-only retry. A re-call recovers the D-174 environmental
+    // timeout / transient non-zero exit; a deterministic failure (ENOENT/auth) fails
+    // fast (isRetryableCompressError). maxAttempts:2 = one retry.
+    result = await compressWithRetry(
+      backend,
+      {
+        input: buffer,
+        instructions,
+        preserveCitationIds: true,
+        maxOutputBytes,
+        timeoutMs: 50_000,
+      },
+      { maxAttempts: 2, onRetry: () => { retries += 1; } },
+    );
     touchCooldownMarker({ projectRoot, now: ts });
   } catch (err) {
     touchCooldownMarker({ projectRoot, now: ts });
@@ -217,6 +227,10 @@ export async function dailyDistill({
         ts, scope: 'daily-distill', input_bytes, output_bytes: 0,
         model_id: typeof backend.modelId === 'function' ? backend.modelId() : null,
         cost_usd: 0, duration_ms, success: false, error_category: errorCategory,
+        // Task 161 (D-173 observability): structured failure reason — see compress-session.mjs.
+        ...(err?.exitCode != null ? { exit_code: err.exitCode } : {}),
+        ...(err?.stderr ? { error_detail: String(err.stderr).slice(0, 500) } : {}),
+        ...(retries > 0 ? { retries } : {}), // 161.12: failed AFTER retrying
       },
     });
     return {
@@ -246,6 +260,7 @@ export async function dailyDistill({
         (typeof backend.modelId === 'function' ? backend.modelId() : null),
       cost_usd: result?.costUSD ?? 0,
       duration_ms, success: true, source_days: files.length,
+      ...(retries > 0 ? { retries } : {}), // 161.12: succeeded after a transient retry
     },
   });
   return {

package/src/doctor.mjs

@@ -1,4 +1,4 @@
-// `cmk doctor` — health checks HC-1..HC-8 (Task 37, T-031; memsearch HC-1/HC-7 removed in Task 120; HC-8 native bindings added in Task 141a).
+// `cmk doctor` — health checks HC-1..HC-9 (Task 37, T-031; memsearch HC-1/HC-7 removed in Task 120; HC-8 native bindings added in Task 141a; HC-9 version-drift/update-path added in Task 162 / D-176).
 //
 // Public boundary:
 //   async runDoctor({projectRoot, userDir, now, promptUser?, ...overrides})
@@ -46,6 +46,8 @@ import { cronSentinelPath } from './lazy-compress.mjs';
 import { getNativeAutoMemoryState } from './native-memory.mjs';
 import { checkKitBinding, checkEmbedderBinding } from './native-binding.mjs';
 import { resolveDefaultSearchMode } from './semantic-backend.mjs';
+import { checkVersionDrift } from './version-drift.mjs';
+import { getKitVersion } from './install.mjs';
 
 const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1000;
 const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
@@ -541,10 +543,27 @@ async function hc8NativeBindings({ projectRoot, kitBindingProbe, embedderBinding
  * parameter lands at that PR alongside the actual consent flow — not
  * pre-empted in v0.1.0 to avoid the "forward-compat hooks rot" pattern.
  */
+// --- HC-9: project scaffold version matches the installed cmk (Task 162 / D-176) ---
+// After `npm i -g @latest`, a project's version-stamped scaffold stays at the OLD
+// version until `cmk install` re-runs there (the easily-forgotten per-project step).
+// HC-9 reads the project's CLAUDE.md managed-block version + the installed binary
+// version and tells the user to re-run `cmk install` when the project is behind.
+function hc9VersionDrift({ projectRoot, kitVersion }) {
+  const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+  let claudeMdText = null;
+  try {
+    if (existsSync(claudeMdPath)) claudeMdText = readFileSync(claudeMdPath, 'utf8');
+  } catch {
+    claudeMdText = null; // unreadable → skip (treated as not-installed)
+  }
+  return checkVersionDrift({ claudeMdText, kitVersion });
+}
+
 export async function runDoctor({
   projectRoot,
   userDir,
   now,
+  kitVersion,
   kitBindingProbe,
   embedderBindingProbe,
 } = {}) {
@@ -569,10 +588,12 @@ export async function runDoctor({
   const c6 = hc6NativeAutoMemory({ projectRoot, now: ts });
   const c7 = hc7StaleLocks({ projectRoot, userDir: resolvedUserDir });
   const c8 = await hc8NativeBindings({ projectRoot, kitBindingProbe, embedderBindingProbe });
+  // HC-9: kitVersion injectable for tests; defaults to the installed binary's version.
+  const c9 = hc9VersionDrift({ projectRoot, kitVersion: kitVersion ?? getKitVersion() });
 
   return {
     action: 'completed',
-    checks: [c1, c2, c3, c4, c5, c6, c7, c8],
+    checks: [c1, c2, c3, c4, c5, c6, c7, c8, c9],
     duration_ms: Date.now() - t0,
   };
 }

package/src/import-claude-md.mjs

@@ -32,7 +32,7 @@ import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { writeFact } from './write-fact.mjs';
 import { slugifyFact } from './rich-fact.mjs';
-import { sanitizeHomePaths } from './sanitize.mjs';
+import { sanitizeHomePaths, sanitizeForTitle } from './sanitize.mjs';
 import { parse as parseFrontmatter } from './frontmatter.mjs';
 
 const DEFAULT_FILE = 'CLAUDE.md';
@@ -280,7 +280,12 @@ export async function importClaudeMd({
   // absolute --file argument (the D-51 name-privacy class).
   const sourceFileField = sanitizeHomePaths(fileRel);
   for (const p of proposals) {
-    const title = p.text.split('\n')[0].slice(0, 80);
+    // Sanitize BEFORE deriving the title/slug (F-V0.3.3-2) — p.text is the RAW
+    // rule text (the `sanitized` above feeds only the dedup key/id), and the
+    // slug becomes the committed filename, which writeFact won't sanitize. A
+    // CLAUDE.md rule mentioning C:\Users\you\ would otherwise leak the username
+    // into the imported fact's filename. Same one helper as the other slug sites.
+    const title = sanitizeForTitle(p.text).split('\n')[0].slice(0, 80);
     let slug = slugifyFact(title);
     if (usedSlugs.has(`${p.type}/${slug}`)) slug = `${slug}-l${p.line}`;
     usedSlugs.add(`${p.type}/${slug}`);

package/src/index-rebuild.mjs

@@ -295,6 +295,40 @@ function parseSource(source, { projectRoot, userDir }) {
 
 // --- DB write helpers -------------------------------------------------
 
+// Bug 1 (2026-06-16, fact P-UCG4RKNL): the kit dual-writes a fact to BOTH the
+// MEMORY.md scratchpad bullet AND its granular archive file, both carrying the
+// SAME content-addressed id. `observations.id` is a global PRIMARY KEY, so a
+// plain INSERT of the second source's row collided (`UNIQUE constraint failed:
+// observations.id`) and aborted the whole reindex. The fix is id-keyed upsert
+// with deterministic ARCHIVE-BEATS-SCRATCHPAD precedence — validated against
+// three markdown-first analogs that all key replacement on the id, never the
+// file (TencentDB `ON CONFLICT(record_id) DO UPDATE`; basic-memory
+// resolve-permalink precedence + partial unique index; memweave content-hash
+// dedup). See docs/research/2026-06-16-index-uniqueness-id-vs-file-scoped-delete.md.
+//
+// Two precedence-keyed paths, order-INDEPENDENT (the source walk order must not
+// change the surviving row):
+//   - fact (granular archive = the canonical Why/How home) → explicit
+//     DELETE-by-id then INSERT: always wins, overwriting any scratchpad row for
+//     the id.
+//   - scratchpad (the hot working-copy bullet) → ON CONFLICT(id) DO NOTHING:
+//     inserts only when no row exists yet; never overwrites a fact row.
+// Whichever is walked first, the fact row is the one that survives.
+//
+// FTS5 CORRECTNESS (the self-review catch): the fact path uses an explicit
+// DELETE-by-id, NOT `INSERT OR REPLACE`. `observations_fts` is an
+// external-content FTS5 table whose only safe delete path is the
+// `obs_after_delete` trigger firing the 'delete' SENTINEL with the OLD row's
+// column values (index-db.mjs §4.4.3 comment). `INSERT OR REPLACE` reuses the
+// conflicting row's rowid, so its internal delete+insert leaves the OLD
+// scratchpad body orphaned in the FTS index (it keeps MATCH-ing with no backing
+// row — silent stale-hit corruption). An explicit `DELETE FROM observations
+// WHERE id = ?` fires obs_after_delete cleanly (sentinel removes the old terms),
+// then the plain INSERT fires obs_after_insert. This is the same delete-then-
+// insert pattern every other writer in the kit uses against this table.
+
+const DELETE_OBSERVATION_BY_ID_SQL = `DELETE FROM observations WHERE id = ?`;
+
 const INSERT_OBSERVATION_SQL = `
 INSERT INTO observations
   (id, tier, source_file, source_line, source_sha1, heading_path, body,
@@ -304,6 +338,16 @@ VALUES
    @write_source, @trust, @created_at, @superseded_by, @deleted_at)
 `;
 
+const INSERT_SCRATCHPAD_OBSERVATION_SQL = `
+INSERT INTO observations
+  (id, tier, source_file, source_line, source_sha1, heading_path, body,
+   write_source, trust, created_at, superseded_by, deleted_at)
+VALUES
+  (@id, @tier, @source_file, @source_line, @source_sha1, @heading_path, @body,
+   @write_source, @trust, @created_at, @superseded_by, @deleted_at)
+ON CONFLICT(id) DO NOTHING
+`;
+
 const UPSERT_FILE_SQL = `
 INSERT INTO files (path, mtime, sha1, indexed_at)
 VALUES (@path, @mtime, @sha1, @indexed_at)
@@ -322,10 +366,48 @@ const DELETE_OBSERVATIONS_FOR_PATH_SQL = `DELETE FROM observations WHERE source_
  */
 function replaceObservationsForFile(db, { source, observations, mtime, sha1, projectRoot, userDir, now }) {
   const source_file = relativeSource(source.path, { projectRoot, userDir });
+  // File-scoped delete clears THIS file's own rows so a re-index of a changed
+  // file is idempotent. It only matches rows whose source_file is this path, so
+  // a fact's row (source_file = context/memory/*.md) is untouched when the
+  // scratchpad (context/MEMORY.md) is re-indexed, and vice versa — the
+  // cross-file id collision is handled by the precedence-keyed insert below,
+  // NOT by this delete (Bug 1).
   db.prepare(DELETE_OBSERVATIONS_FOR_PATH_SQL).run(source_file);
-  const insert = db.prepare(INSERT_OBSERVATION_SQL);
-  for (const obs of observations) {
-    insert.run(obs);
+  // Archive-beats-scratchpad precedence (Bug 1): a fact row wins the id by
+  // explicitly deleting any existing row for that id first (firing the FTS
+  // 'delete' sentinel cleanly) then inserting; a scratchpad row yields via
+  // ON CONFLICT(id) DO NOTHING. Within a FULL pass (reindexFull, or a
+  // reindexBoot that re-walks both sources) this is order-independent — the
+  // fact row always wins (listObservationSources walks scratchpad-before-facts
+  // per tier, but either order lands the same surviving row).
+  //
+  // INCREMENTAL caveat (skill-review I1): on the mtime-skip boot path / the
+  // single-file watcher path, only the CHANGED source is re-processed. If a
+  // fact file is removed while its scratchpad twin (same id) is untouched, the
+  // orphan-prune drops the fact row and the skipped scratchpad's DO-NOTHING
+  // insert never re-fires — so the id momentarily vanishes from search until
+  // the scratchpad is next edited (which re-inserts it). `cmk forget` does NOT
+  // hit this: it tombstones the fact AND scrubs the scratchpad bullet in the
+  // same op (forget.mjs scrubAllScratchpads), so the only window is a manual
+  // hand-`rm` of a context/memory/*.md leaving the bullet behind — a rare,
+  // self-healing transition, documented + tested rather than resurrected.
+  //
+  // The DELETE-by-id is UNQUALIFIED (no tier/source_file filter) by design and
+  // safe: ids are content-addressed WITH the tier as a prefix (`P-`/`L-`/`U-`),
+  // so a P-tier and U-tier fact can never share an id — no cross-tier delete is
+  // possible. (Defended by the P/U-same-content tier test below.)
+  if (source.kind === 'fact') {
+    const deleteById = db.prepare(DELETE_OBSERVATION_BY_ID_SQL);
+    const insert = db.prepare(INSERT_OBSERVATION_SQL);
+    for (const obs of observations) {
+      deleteById.run(obs.id);
+      insert.run(obs);
+    }
+  } else {
+    const insert = db.prepare(INSERT_SCRATCHPAD_OBSERVATION_SQL);
+    for (const obs of observations) {
+      insert.run(obs);
+    }
   }
   db.prepare(UPSERT_FILE_SQL).run({
     path: source_file,
@@ -370,6 +452,9 @@ export function reindexBoot({ projectRoot, userDir, db, now }) {
       userDir,
       now: ts,
     });
+    // observationsAffected counts insert-ATTEMPTS, not net rows: a fact that
+    // displaces a same-id scratchpad row (Bug 1 precedence) is net-zero but
+    // counts as one here. It's a "work done" metric, not a row-count invariant.
     return result.observations.length;
   });
 
@@ -537,6 +622,9 @@ export function reindexFull({ projectRoot, userDir, db, now }) {
       userDir,
       now: ts,
     });
+    // observationsAffected counts insert-ATTEMPTS, not net rows: a fact that
+    // displaces a same-id scratchpad row (Bug 1 precedence) is net-zero but
+    // counts as one here. It's a "work done" metric, not a row-count invariant.
     return result.observations.length;
   });