@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

package/src/doctor.mjs

@@ -43,11 +43,14 @@ import { basename, join } from 'node:path';
 import { nowIso } from './audit-log.mjs';
 import { detectStaleLocks } from './lock-discipline.mjs';
 import { cronSentinelPath } from './lazy-compress.mjs';
+import { isCompactionNeeded } from './compaction-state.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';
+import { hasOurCliAgent } from './kiro-cli-agent.mjs';
+import { stripBom } from './read-json.mjs';
 
 const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1000;
 const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
@@ -59,9 +62,41 @@ const MEMORY_DIR_REL = ['context', 'memory'];
 const LOCKS_REL = ['context', '.locks'];
 const NATIVE_MEMORY_LOG_REL = ['context', '.locks', 'native-memory-status.log'];
 
+// Which agent was this project installed for? A `--ide kiro` install wires
+// .kiro/ surfaces (hooks + steering/cmk.md + skills + settings/mcp.json); a
+// Claude Code install wires .claude/settings.json. HC-1 must check the RIGHT
+// surface — before v0.4.0 it hard-checked .claude/settings.json and false-FAILed
+// on every Kiro install (the cut-gate-kiro live-test find, Task 50).
+//
+// Detection precedence:
+//   1. .claude/settings.json present → Claude Code.
+//   2. a CMK-OWNED Kiro marker present (.kiro/steering/cmk.md — written by every
+//      installKiro run) → Kiro. We key on OUR marker, not a bare `.kiro/` dir, so
+//      a stray/unrelated .kiro/ (another tool's, or a partial non-cmk dir) does
+//      NOT flip the project to the Kiro path (I2).
+//   3. neither → Claude Code (historical default — a not-yet-installed project
+//      still reports the Claude-shaped repair hint).
+//
+// NOTE (I1, deliberate punt): a project installed for BOTH agents (.claude AND a
+// cmk .kiro marker) resolves to Claude Code by precedence — HC-1 checks only the
+// Claude surface. Dual-install is rare; the single-surface check is intentional
+// for v0.4.0, not an oversight. Revisit if dual-install becomes common.
+function detectInstallKind(projectRoot) {
+  if (existsSync(join(projectRoot, '.claude', 'settings.json'))) return 'claude-code';
+  if (existsSync(join(projectRoot, '.kiro', 'steering', 'cmk.md'))) return 'kiro';
+  return 'claude-code';
+}
+
 // --- HC-1: Stop + SessionStart hooks registered -----------------------
-function hc1Hooks({ projectRoot }) {
-  // Per design §5 — the kit's hooks live in .claude/settings.json
+function hc1Hooks({ projectRoot, awsDir }) {
+  // Agent-aware (v0.4.0): a Kiro install keeps its hooks in .kiro/hooks/ (IDE)
+  // and/or ~/.kiro/agents/ (kiro-cli), so route to the Kiro check
+  // rather than false-failing on a missing .claude/settings.json with a
+  // Claude-Code repair hint.
+  if (detectInstallKind(projectRoot) === 'kiro') {
+    return hc1KiroHooks({ projectRoot, awsDir });
+  }
+  // Per design §5 — the Claude Code hooks live in .claude/settings.json
   // alongside its plugin manifest. Required for auto-extract +
   // session-end compression to fire.
   const settingsPath = join(projectRoot, '.claude', 'settings.json');
@@ -76,7 +111,9 @@ function hc1Hooks({ projectRoot }) {
   }
   let settings;
   try {
-    settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    // stripBom: a Windows-editor BOM on .claude/settings.json must not make a
+    // valid file read as a parse error → false HC-1 FAIL (D-187).
+    settings = JSON.parse(stripBom(readFileSync(settingsPath, 'utf8')));
   } catch (err) {
     return {
       id: 'HC-1',
@@ -141,6 +178,51 @@ function hc1Hooks({ projectRoot }) {
   };
 }
 
+// --- HC-1 (Kiro variant): capture + inject can fire via EITHER Kiro surface ----
+// Kiro wires capture/inject through TWO independent surfaces (D-186):
+//   • IDE hooks  → .kiro/hooks/{cmk-capture,cmk-inject}.kiro.hook  (the GUI user)
+//   • CLI agent  → ~/.kiro/agents/cmk.json with
+//                  agentSpawn(inject)+stop(capture) hooks  (the kiro-cli user)
+// HC-1 is a CAPABILITY check ("can capture/inject fire?"), not a single-file
+// check — so it PASSES if EITHER surface is present, and FAILs only when NEITHER
+// is. The original v0.4.0 fix checked only the IDE hooks, which false-FAILed a
+// working kiro-cli-only install (the surface lives in ~/.aws, which is also
+// machine-local and doesn't travel with a clone) — the same separately-correct-
+// jointly-broken class as D-184/D-185, one level down (skill-review B1).
+// `awsDir` is injectable so tests can sandbox the ~/.aws probe.
+function hc1KiroHooks({ projectRoot, awsDir }) {
+  const hooksDir = join(projectRoot, '.kiro', 'hooks');
+  const ideHooks = ['cmk-capture.kiro.hook', 'cmk-inject.kiro.hook'];
+  const ideMissing = ideHooks.filter((f) => !existsSync(join(hooksDir, f)));
+  const ideComplete = ideMissing.length === 0;
+  const cliAgent = hasOurCliAgent({ awsDir });
+
+  if (ideComplete || cliAgent) {
+    const surfaces = [];
+    if (ideComplete) surfaces.push('IDE hooks (.kiro/hooks/)');
+    if (cliAgent) surfaces.push('CLI agent (~/.kiro/agents/cmk.json)');
+    return {
+      id: 'HC-1',
+      name: 'Stop + SessionStart hooks registered',
+      status: 'pass',
+      message: `Kiro capture/inject wired via ${surfaces.join(' + ')}`,
+    };
+  }
+
+  // Neither surface present → genuinely not wired. Name both so a kiro-cli user
+  // isn't pushed at the IDE-only repair.
+  return {
+    id: 'HC-1',
+    name: 'Stop + SessionStart hooks registered',
+    status: 'fail',
+    message:
+      `Kiro install: no capture/inject surface found — neither the IDE hooks ` +
+      `(${ideMissing.join(', ')} in .kiro/hooks/) nor a cmk CLI agent in ` +
+      `~/.kiro/agents/`,
+    recoveryCommand: 'cmk install --ide kiro',
+  };
+}
+
 // --- HC-2: distill freshness (≤2 days) --------------------------------
 function hc2DistillFreshness({ projectRoot, now }) {
   const recentPath = join(projectRoot, ...RECENT_MD_REL);
@@ -559,6 +641,45 @@ function hc9VersionDrift({ projectRoot, kitVersion }) {
   return checkVersionDrift({ claudeMdText, kitVersion });
 }
 
+// --- HC-10: Scheduled compaction liveness (Task 167 / D-207) ----------
+// INFORMATIONAL — memory self-heals automatically every session (the lazy roll
+// is the floor, 167.A/D), so a dead cron is a degraded OPTIMIZATION, not data
+// loss. NEVER prescribes a manual heal (no recoveryCommand). A DEV/diagnostic
+// aid (it surfaced THIS bug class) + a heads-up for a power user. SKIPs when no
+// cron is registered (the default) — the lazy roll covers compaction there.
+function hc10CompactionLiveness({ projectRoot, now }) {
+  const v = isCompactionNeeded({ projectRoot, now });
+  // No cron registered (heartbeatAge null) → nothing to check; the lazy roll owns
+  // compaction. SKIP (consistent with HC-5's optional-cron posture).
+  if (v.heartbeatAge === null) {
+    return {
+      id: 'HC-10',
+      name: 'Scheduled compaction is alive',
+      status: 'skip',
+      message: 'no scheduled cron registered (optional) — memory self-heals each session via the lazy roll.',
+    };
+  }
+  if (v.cronStale) {
+    const days = Math.floor(v.heartbeatAge / (24 * 60 * 60 * 1000));
+    return {
+      id: 'HC-10',
+      name: 'Scheduled compaction is alive',
+      status: 'fail',
+      // Informational framing — NO recoveryCommand. The kit self-heals; this is a
+      // heads-up that the OPTIONAL nightly schedule isn't firing (asleep at 23:00,
+      // a registration that didn't take catch-up). Re-running register-crons is a
+      // user choice, not a required repair.
+      message: `your scheduled compaction looks dead (last ran ~${days}d ago) — memory still self-heals automatically each session, so no action is needed; run \`cmk register-crons\` only if you want the nightly schedule back.`,
+    };
+  }
+  return {
+    id: 'HC-10',
+    name: 'Scheduled compaction is alive',
+    status: 'pass',
+    message: 'scheduled compaction heartbeat is fresh',
+  };
+}
+
 export async function runDoctor({
   projectRoot,
   userDir,
@@ -566,6 +687,7 @@ export async function runDoctor({
   kitVersion,
   kitBindingProbe,
   embedderBindingProbe,
+  awsDir, // injectable: sandboxes the HC-1 Kiro CLI-agent (~/.aws) probe in tests
 } = {}) {
   const t0 = Date.now();
   if (!projectRoot) {
@@ -580,7 +702,7 @@ export async function runDoctor({
   const resolvedUserDir = userDir ?? join(homedir(), '.claude-memory-kit');
 
   // Run all checks in order.
-  const c1 = hc1Hooks({ projectRoot });
+  const c1 = hc1Hooks({ projectRoot, awsDir });
   const c2 = hc2DistillFreshness({ projectRoot, now: ts });
   const c3 = hc3Transcripts({ projectRoot, now: ts });
   const c4 = hc4IndexConsistency({ projectRoot });
@@ -590,10 +712,11 @@ export async function runDoctor({
   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() });
+  const c10 = hc10CompactionLiveness({ projectRoot, now: ts });
 
   return {
     action: 'completed',
-    checks: [c1, c2, c3, c4, c5, c6, c7, c8, c9],
+    checks: [c1, c2, c3, c4, c5, c6, c7, c8, c9, c10],
     duration_ms: Date.now() - t0,
   };
 }

package/src/guard-memory.mjs

@@ -0,0 +1,151 @@
+// guard-memory.mjs — the memory delete-guardrail core (D-192).
+//
+// A Claude Code `PreToolUse` hook (wired by `cmk install`) calls the
+// `cmk-guard-memory` bin before every Bash/PowerShell tool call. This module
+// is the pure decision: given a shell command, should it be BLOCKED because it
+// would delete a claude-memory-kit memory path?
+//
+// Why this exists: 2026-06-22 (D-192), a `cd` that silently failed left a
+// following `rm -f context/sessions/* context/transcripts/*` running in the
+// wrong repo, deleting gitignored (non-recoverable) memory. A prose rule relies
+// on the agent remembering; this hook enforces it structurally — the command
+// never runs. Recovered only via an off-machine backup; this prevents the next.
+//
+// Design: BROAD by intent. A false block is recoverable (the user rephrases or
+// deletes by hand); a false allow is the data loss we're preventing. So the
+// predicates favor over-blocking a memory delete over under-blocking one.
+
+// A command is destructive if it invokes a delete/destroy verb OR an equivalent
+// data-destroying mechanism that carries no `rm` token (find -delete, truncate,
+// a `>`/`:>` redirection that truncates a file). Skill-review I2: a memory file
+// can be destroyed with no `rm` at all.
+const DESTRUCTIVE = [
+  /\brm\b/i, // unix rm
+  /\bRemove-Item\b/i, // PowerShell
+  /\brmdir\b/i,
+  /\brd\b/i, // cmd rd
+  /\bdel\b/i, // cmd del
+  /\bunlink\b/i,
+  /\bgit\s+clean\b/i,
+  /\bgit\s+reset\s+--hard\b/i,
+  /\bfind\b[^|]*-delete\b/i, // find … -delete
+  /\btruncate\b/i, // truncate -s0 file
+  /(^|[\s;&|])>\s*\S/, // a `>`/`> file` redirection (truncates the target to empty)
+];
+
+// A path is a MEMORY path if the command mentions any of these. The bare
+// `context` segment matcher requires a path-ish boundary so the WORD "context"
+// (e.g. `grep context`, `rm contextual.md`) is not a false positive.
+const MEMORY_TOKENS = [
+  /context\/sessions/i,
+  /context\/transcripts/i,
+  /context\/memory/i,
+  /context\.local/i,
+  // a `context` path segment: `context/`, `context\`, `./context`, `repo/context`,
+  // or a bare ` context` argument (e.g. `git clean -fd context`).
+  /(^|[\s'"./\\])context([\s'"/\\]|$)/i,
+  /\.claude-memory-kit/i, // the cross-project user tier
+  /MEMORY\.md/i,
+  /DECISIONS\.md/i,
+];
+
+/** True if the command invokes a delete/destroy verb. */
+export function isDestructive(cmd) {
+  return typeof cmd === 'string' && DESTRUCTIVE.some((re) => re.test(cmd));
+}
+
+/** True if the command references a claude-memory-kit memory path. */
+export function touchesMemory(cmd) {
+  return typeof cmd === 'string' && MEMORY_TOKENS.some((re) => re.test(cmd));
+}
+
+// A SEGMENT (not the whole command) may be exempt: it only MENTIONS a delete in
+// its text and can't itself execute one — a `git commit` whose message describes
+// a delete, an `echo`/`grep`/`cat` of text about a delete. (oh-my-kiro's
+// block-dangerous.sh exempts `git commit` for the same reason.) CRITICAL: this
+// is applied PER SEGMENT, never to a whole compound command — `echo x && rm -rf
+// context/memory` must NOT be exempted by its leading `echo` (skill-review B1).
+const SEGMENT_EXEMPT = [
+  /^\s*git\s+commit\b/i,
+  /^\s*git\s+log\b/i,
+  /^\s*echo\b/i,
+  /^\s*(grep|rg|cat|less|head|tail|sed -n|awk)\b/i,
+];
+
+// Split a shell command into its sequenced segments on the separators that start
+// a NEW command: && || ; | and newlines. (A `>` redirection is NOT a separator —
+// it's handled as a destructive mechanism on its own segment.) Also surface any
+// $(...) / `...` command substitution as its own segment so a delete hidden in a
+// commit-message arg (`git commit -m "$(rm -rf context/memory)"`) is evaluated
+// on its own and can't ride the outer command's exemption (skill-review I1).
+function splitSegments(cmd) {
+  const segments = [];
+  // pull out command substitutions first, add them as standalone segments
+  const subRe = /\$\(([^)]*)\)|`([^`]*)`/g;
+  let m;
+  while ((m = subRe.exec(cmd)) !== null) {
+    const inner = m[1] ?? m[2];
+    if (inner && inner.trim()) segments.push(inner);
+  }
+  const stripped = cmd.replace(subRe, ' '); // remove subs so they don't leak into outer segments
+  for (const seg of stripped.split(/&&|\|\||;|\||\r?\n/)) {
+    if (seg.trim()) segments.push(seg);
+  }
+  return segments;
+}
+
+function isSegmentExempt(seg) {
+  return SEGMENT_EXEMPT.some((re) => re.test(seg));
+}
+
+/**
+ * The pure decision. Returns { block: boolean, reason?: string }.
+ * Splits the command into segments and BLOCKS if ANY non-exempt segment is both
+ * destructive AND aimed at a memory path. Per-segment so an exempt verb in front
+ * (`echo …`, `git commit …`) cannot launder a chained real delete (B1/I1).
+ */
+export function decideGuard(cmd) {
+  if (typeof cmd !== 'string' || cmd.trim() === '') return { block: false };
+  const offending = splitSegments(cmd).some(
+    (seg) => !isSegmentExempt(seg) && isDestructive(seg) && touchesMemory(seg),
+  );
+  if (offending) {
+    return {
+      block: true,
+      reason:
+        'BLOCKED by the claude-memory-kit delete-guardrail: this command deletes a ' +
+        'memory path (context/ , the persona tier ~/.claude-memory-kit, or a memory ' +
+        'file). Memory is precious and a delete here is often non-recoverable. If you ' +
+        'REALLY mean to delete memory, do it by hand after a backup — or ask the user. ' +
+        'NEVER run a delete after a `cd` you have not verified with `pwd`.',
+    };
+  }
+  return { block: false };
+}
+
+// The shell-tool names across agents. Claude Code: `Bash` / `PowerShell`.
+// Kiro / Amazon-Q: `execute_bash` (+ legacy alias `executeBash`); kiro-cli V3
+// (2.9.0) RENAMED it to `execute_command` (D-198, observed live in the cut-gate).
+// Payload `.tool_name` + `.tool_input.command` on STDIN — the SAME shape as
+// Claude Code, so one bin guards every agent. D-192.
+const SHELL_TOOLS = new Set([
+  'Bash',
+  'PowerShell',
+  'execute_bash',
+  'executeBash',
+  'execute_command', // kiro-cli V3 (2.9.0) rename — D-198
+  'shell',
+]);
+
+/**
+ * Evaluate a PreToolUse payload (already parsed) from EITHER Claude Code or Kiro
+ * — both deliver `{ tool_name, tool_input: { command } }` on stdin. Only shell
+ * tools are inspected; everything else is allowed. Returns { block, reason? }.
+ */
+export function evaluatePayload(payload) {
+  const tool = payload?.tool_name;
+  if (!SHELL_TOOLS.has(tool)) return { block: false };
+  const cmd = payload?.tool_input?.command;
+  if (typeof cmd !== 'string' || cmd === '') return { block: false };
+  return decideGuard(cmd);
+}

package/src/import-anthropic-memory.mjs

@@ -253,7 +253,21 @@ export async function importAnthropicMemory({
     })
     .join('\n');
   mkdirSync(join(projectRoot, 'context'), { recursive: true });
-  appendFileSync(targetPath, sectionHeader + '\n' + bulletLines + '\n', 'utf8');
+  // Lint-clean append (MD022): guarantee exactly one blank line ABOVE the
+  // `## Imported …` heading when the target file already has content (the
+  // leading `\n` in sectionHeader assumes the file ends in `\n` — fragile if it
+  // doesn't). The blank below the heading is the `+ '\n'` after sectionHeader.
+  let prefix = '';
+  if (existsSync(targetPath)) {
+    const existing = readFileSync(targetPath, 'utf8');
+    if (existing.trim() !== '') {
+      prefix = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '' : '\n';
+    }
+  }
+  // sectionHeader already starts with `\n`, so a file ending in `\n` yields the
+  // needed blank line; prefix adds the missing one only when the file lacks a
+  // trailing newline.
+  appendFileSync(targetPath, prefix + sectionHeader + '\n' + bulletLines + '\n', 'utf8');
 
   let accepted = 0;
   for (const p of proposals) {

package/src/inject-context.mjs

@@ -31,9 +31,10 @@ import {
   closeSync,
 } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { SCRATCHPADS_BY_TIER, resolveTierRoot, ID_PATTERN } from './tier-paths.mjs';
+import { SCRATCHPADS_BY_TIER, resolveTierRoot, ID_PATTERN, discoverRootUpward } from './tier-paths.mjs';
 import { nowIso } from './audit-log.mjs';
 import { detectStaleness, isJournalStale } from './lazy-compress.mjs';
 import { isProvenanceCommentLine, parseBulletProvenance } from './provenance.mjs';
@@ -170,21 +171,14 @@ function latestDaySession(sessionsDir) {
 // kit's project-tier root convention is `<repo>/context/`; the walk-up
 // matches `git rev-parse --show-toplevel`'s semantics for nested invocations
 // (a hook may fire while Claude Code's cwd is in a sub-package).
+// Task 168: discovery walks up to the nearest project root, recognizing EITHER
+// tier directory — `context/` (committed) OR `context.local/` (gitignored local)
+// — so a local-only project resolves correctly, and STOPPING at the home dir so a
+// stray `~/context/` can't hijack discovery from an unrelated subdir. Shares the
+// single `discoverRootUpward` implementation with resolveMcpProjectRoot (one
+// home-boundary + canonicalize algorithm, no drift across the two walkers).
 function discoverProjectRoot(cwd) {
-  let dir = cwd;
-  // Defensive bound: walk no more than 64 ancestors.
-  for (let i = 0; i < 64; i++) {
-    if (existsSync(join(dir, 'context'))) return dir;
-    const parent = join(dir, '..');
-    const norm = statSync(parent).isDirectory() ? parent : null;
-    if (!norm || norm === dir) break;
-    // Stop at the filesystem root.
-    if (/^[A-Za-z]:\\?$|^\/$/.test(dir)) break;
-    dir = parent;
-  }
-  // Fall back to `cwd` — the per-tier readers will return empty for
-  // absent dirs, so this stays safe.
-  return cwd;
+  return discoverRootUpward(cwd, ['context', 'context.local']);
 }
 
 function tierDirExists(tier, tierRoot) {
@@ -617,6 +611,32 @@ function enforceCap(orderedBlocks, capBytes, ts, reportCapBytes = capBytes) {
  * Exposed so injectContext can override via dependency injection in tests
  * (testSpawnLazy parameter) — production callers pass nothing.
  */
+/**
+ * Resolve the path to `bin/cmk-compress-lazy.mjs` from THIS module's location
+ * (`src/` → `../bin/`), honoring the $CMK_COMPRESS_LAZY_PATH override. Returns
+ * null if it can't be found (→ the shell:true fallback).
+ *
+ * Why this exists (the cross-agent console-popup fix): the no-popup spawn (Task
+ * 81) only kicks in when `injectContext` receives a real `compressLazyPath` —
+ * otherwise `lazyCompressSpawnDescriptor` falls to the `shell:true` `.cmd` shim,
+ * which flashes a `node` console window on Windows. The Claude Code bin
+ * (`cmk-inject-context.mjs`) passed the path; the Kiro `cmk hook agentSpawn`
+ * path did NOT, so a real Kiro user got the popup (the cut-gate-kiro live find).
+ * Resolving it HERE (in injectContext's default) fixes EVERY caller — Claude
+ * bin, Kiro hook, any future agent — not just the ones that remember to pass it.
+ */
+export function resolveCompressLazyPath() {
+  const fromEnv = process.env.CMK_COMPRESS_LAZY_PATH;
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // .../packages/cli/src
+    const candidate = join(here, '..', 'bin', 'cmk-compress-lazy.mjs');
+    return existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Pure spawn descriptor for the lazy-compress child (Task 81). Separated so the
  * Door-3 contract (node-direct + windowsHide, no shell, when the path is known)
@@ -706,8 +726,12 @@ export function injectContext({
   // Resolved path to cmk-compress-lazy.mjs (passed by the bin wrapper, which
   // knows the install layout). Lets spawnLazyCompress run `node <path>`
   // directly instead of the shell:true `.cmd` shim — the Windows
-  // console-popup fix (Task 81). Absent → graceful shell:true fallback.
-  compressLazyPath,
+  // console-popup fix (Task 81). Absent → self-resolve from this module's
+  // location (resolveCompressLazyPath), so EVERY caller gets the no-popup
+  // node-direct spawn — not just the Claude bin that passed it explicitly. A
+  // caller may still override (e.g. tests). Only a genuinely-unfindable bin
+  // (corrupt install) falls to the shell:true descriptor.
+  compressLazyPath = resolveCompressLazyPath(),
 } = {}) {
   const ts = now ?? nowIso();
   const cap = typeof capBytes === 'number' ? capBytes : DEFAULT_CAP_BYTES;