@lh8ppl/claude-memory-kit 0.3.5 → 0.4.0

package/README.md

@@ -18,6 +18,7 @@
 - **Explicit capture when you want it** — say "remember this" / "from now on" / "we decided" / "forget X" (the `memory-write` skill), or run `cmk remember "<fact>"`. Both dedup, screen for secrets, abstract machine paths to `~`, and write silently. For backtick/quote-heavy rich facts, capture them shell-safe as JSON: `cmk remember --from-file fact.json` (or `--json` from stdin) — content never touches the shell.
 - **Search + MCP — Claude runs every memory op for you, in conversation** — `cmk search "<term>"` (keyword over facts + scratchpads; with the optional local embedder, **semantic + hybrid recall**: ask in your own words and get the fact even with zero keyword overlap — measured R@5 0.941 / paraphrase 1.000 on the kit's benchmark, no API calls). `cmk install` registers the kit's **MCP server**, so Claude can do the whole memory surface as tools without you ever typing `cmk`: capture (`mk_remember`, rich Why/How too), recall (`mk_search` / `mk_get` / `mk_timeline` / `mk_cite`), adjust trust (`mk_trust`), promote a fact across projects (`mk_lessons_promote`), forget (`mk_forget` — previews first, then deletes on confirm), and clear the review/conflict queues (`mk_queue_list` / `mk_queue_resolve`). The tools are allow-listed on install, so they run prompt-free.
 - **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.
+- **Guards your memory from an accidental delete** — `cmk install` wires a `PreToolUse` hook (`cmk-guard-memory`) that **blocks** a destructive command (`rm`, `Remove-Item`, `del`, `git clean`, `git reset --hard`, `find … -delete`, `truncate`, `>`-truncate) the moment it's aimed at a memory path — *before* it runs, on both Claude Code (`Bash` / `PowerShell`) and Kiro (`execute_bash`). Fail-open (a broken guard never wedges your session) and intentionally broad (a false block is recoverable; a false allow is the data loss it prevents). A safe command, or a delete of anything else, runs untouched.
 - **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.
 - **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.
@@ -33,6 +34,7 @@ npm install -g @lh8ppl/claude-memory-kit
 cd ~/my-project
 cmk install        # scaffolds context/ + the memory-write + memory-search skills AND wires the lifecycle hooks into .claude/settings.json
 cmk install --with-semantic   # (optional) local semantic recall — one-time ~260 MB, search defaults to hybrid
+cmk install --ide kiro        # (optional) target Kiro instead — wires the IDE + kiro-cli surfaces (MCP + steering + AGENTS.md + skills + hooks)
 cmk register-crons            # (optional) scheduled background compression — otherwise self-heals lazily
 cmk import-claude-md --yes    # (optional) seed memory from an existing CLAUDE.md / .cursorrules (--dry-run previews)
 cmk doctor         # verify, then restart Claude Code
@@ -42,6 +44,10 @@ cmk doctor         # verify, then restart Claude Code
 
 > Installing the package globally adds the `cmk` CLI **and** the installer. It's the `cmk install` *subcommand* that wires the hooks — not the bare `npm install`.
 
+**Other agents (Kiro).** `cmk install --ide kiro` targets [Kiro](https://kiro.dev) (AWS's agentic IDE + `kiro-cli`) instead of Claude Code — one command wires both its GUI hooks (`.kiro/hooks/`) and its terminal CLI agent (`~/.aws/amazonq/cli-agents/`), plus MCP, steering, skills, and an `AGENTS.md` instruction file. A project can carry **both** agents (run both installs — they share one `context/` brain and never clobber each other). Restart Kiro to load its hooks.
+
+**Uninstall** is per-agent and conservative — it never deletes your `context/` memory: `cmk uninstall` removes the Claude Code surface; `cmk uninstall --ide kiro` removes the Kiro surface.
+
 ### Route B — Claude Code plugin marketplace
 
 Inside Claude Code:

package/bin/cmk-guard-memory.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// PreToolUse hook handler — the memory delete-guardrail (D-192).
+//
+// Wired by `cmk install` as a Claude Code PreToolUse hook (matcher
+// "Bash|PowerShell"). Reads the tool call on stdin and, if it's a destructive
+// command aimed at a claude-memory-kit memory path (context/ , the persona
+// tier, a memory file), BLOCKS it by exiting 2 — Claude Code shows the stderr
+// reason to the model and the command never runs.
+//
+// Exit contract (Claude Code PreToolUse):
+//   exit 0 → allow (no opinion)
+//   exit 2 → BLOCK; stderr is surfaced as the reason
+// Fail-OPEN: any load/parse error exits 0 — a broken guardrail must never wedge
+// the session; it just stops guarding.
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
+const modulePath = join(__dirname, '..', 'src', 'guard-memory.mjs');
+
+let readHookStdin;
+let evaluatePayload;
+try {
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
+  ({ evaluatePayload } = await import(pathToFileURL(modulePath).href));
+} catch (err) {
+  process.stderr.write(`cmk-guard-memory: failed to load modules: ${err?.message ?? err}\n`);
+  process.exit(0); // fail-open
+}
+
+// Drain the hook payload — but not on an interactive TTY (a manual run), where
+// a blocking stdin read would hang forever (the Task-101 lesson).
+const raw = readHookStdin({ isTTY: process.stdin.isTTY });
+
+let payload;
+try {
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+} catch {
+  process.exit(0); // fail-open on unparseable input
+}
+
+let verdict;
+try {
+  verdict = evaluatePayload(payload);
+} catch {
+  process.exit(0); // fail-open on any logic error
+}
+
+if (verdict && verdict.block) {
+  process.stderr.write(`${verdict.reason}\n`);
+  process.exit(2); // BLOCK
+}
+
+process.exit(0); // allow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
     "cmk-capture-prompt": "./bin/cmk-capture-prompt.mjs",
     "cmk-observe-edit": "./bin/cmk-observe-edit.mjs",
     "cmk-capture-turn": "./bin/cmk-capture-turn.mjs",
-    "cmk-compress-session": "./bin/cmk-compress-session.mjs"
+    "cmk-compress-session": "./bin/cmk-compress-session.mjs",
+    "cmk-guard-memory": "./bin/cmk-guard-memory.mjs"
   },
   "files": [
     "bin/",

package/src/agent-profile.mjs

@@ -0,0 +1,115 @@
+// agent-profile.mjs — the per-agent profile factory (Task 50.C).
+//
+// D-180: per-agent adapters are DATA, not classes. This factory validates +
+// normalizes a profile DECLARATION so the install routing (Task 50.F) can drive
+// ANY agent through ONE code path — the config legs (MCP registration, hook
+// entry) go through the shared `mutateAgentConfig` primitive (Task 50.B); the
+// instruction leg goes through the kit's marker-block machinery. The factory
+// itself does NO I/O — it's a pure validator/normalizer that returns a frozen
+// descriptor. A bad profile fails LOUD at definition time (throws), not at
+// install time against a user's machine.
+//
+// Integration-type taxonomy (the claude-mem insight — the type dictates which
+// legs an agent wires):
+//   native-hooks-mcp   — instruction + MCP + lifecycle hooks (Claude Code, Kiro)
+//   hooks-mcp          — instruction + MCP + hooks, hooks via a dedicated file
+//                        (Cursor) — same required legs as native-hooks-mcp;
+//                        the `hooks.mechanism` field distinguishes them
+//   mcp-only           — instruction + MCP, NO hooks (Copilot/Warp/Roo/Goose)
+//   instruction-only   — instruction file only, NO MCP, NO hooks (AGENTS.md rung)
+//
+// Public surface:
+//   defineAgentProfile(declaration) → frozen normalized descriptor (throws on invalid)
+//   INTEGRATION_TYPES — frozen list of the valid integrationType values
+
+export const INTEGRATION_TYPES = Object.freeze([
+  'native-hooks-mcp',
+  'hooks-mcp',
+  'mcp-only',
+  'instruction-only',
+]);
+
+const TYPES = new Set(INTEGRATION_TYPES);
+
+// Which legs each type REQUIRES / FORBIDS. instructionFile is required by every
+// type (the universal leg). mcp + hooks vary by type.
+const TYPE_LEGS = Object.freeze({
+  'native-hooks-mcp': { mcp: 'required', hooks: 'required' },
+  'hooks-mcp': { mcp: 'required', hooks: 'required' },
+  'mcp-only': { mcp: 'required', hooks: 'forbidden' },
+  'instruction-only': { mcp: 'forbidden', hooks: 'forbidden' },
+});
+
+function fail(msg) {
+  throw new Error(`defineAgentProfile: ${msg}`);
+}
+
+/**
+ * Validate + normalize an agent profile declaration.
+ * @param {object} decl
+ * @returns {Readonly<object>} the frozen descriptor
+ */
+export function defineAgentProfile(decl) {
+  if (decl === null || typeof decl !== 'object') {
+    fail('declaration must be an object');
+  }
+  const { name, displayName, integrationType, detect, instructionFile, mcp, hooks, transcript } = decl;
+
+  // ── universal required fields ────────────────────────────────────────────
+  if (typeof name !== 'string' || name.length === 0) {
+    fail('name is required (non-empty string)');
+  }
+  if (!TYPES.has(integrationType)) {
+    fail(`integrationType must be one of: ${INTEGRATION_TYPES.join(', ')} (got ${JSON.stringify(integrationType)})`);
+  }
+  if (detect === null || typeof detect !== 'object') {
+    fail(`profile ${name}: detect descriptor is required (e.g. {homeDir:'.kiro'} | {command:'x'} | {always:true})`);
+  }
+  if (typeof instructionFile !== 'string' || instructionFile.length === 0) {
+    fail(`profile ${name}: instructionFile is required (every integration type wires the instruction leg)`);
+  }
+
+  // ── per-type leg contract (the parity invariant 50.D will also enforce) ──
+  const legs = TYPE_LEGS[integrationType];
+  enforceLeg(name, integrationType, 'mcp', mcp, legs.mcp);
+  enforceLeg(name, integrationType, 'hooks', hooks, legs.hooks);
+
+  // ── shape checks on present legs ─────────────────────────────────────────
+  if (mcp !== undefined) {
+    if (typeof mcp.path !== 'string' || typeof mcp.serversKey !== 'string') {
+      fail(`profile ${name}: mcp requires {path, serversKey} strings`);
+    }
+  }
+  if (hooks !== undefined) {
+    if (typeof hooks.mechanism !== 'string') {
+      fail(`profile ${name}: hooks requires a {mechanism} string`);
+    }
+    if (hooks.eventMap === null || typeof hooks.eventMap !== 'object') {
+      fail(`profile ${name}: hooks requires an {eventMap} object`);
+    }
+  }
+
+  // ── normalize + freeze ───────────────────────────────────────────────────
+  const descriptor = {
+    name,
+    displayName: displayName || name,
+    integrationType,
+    detect: Object.freeze({ ...detect }),
+    instructionFile,
+    ...(mcp !== undefined ? { mcp: Object.freeze({ ...mcp }) } : {}),
+    ...(hooks !== undefined
+      ? { hooks: Object.freeze({ ...hooks, eventMap: Object.freeze({ ...hooks.eventMap }) }) }
+      : {}),
+    ...(transcript !== undefined ? { transcript: Object.freeze({ ...transcript }) } : {}),
+  };
+  return Object.freeze(descriptor);
+}
+
+function enforceLeg(name, type, leg, value, requirement) {
+  if (requirement === 'required' && value === undefined) {
+    fail(`profile ${name}: integrationType '${type}' requires the ${leg} leg`);
+  }
+  if (requirement === 'forbidden' && value !== undefined) {
+    fail(`profile ${name}: integrationType '${type}' must NOT declare ${leg} (it over-wires its type)`);
+  }
+}

package/src/agent-profiles.mjs

@@ -0,0 +1,118 @@
+// agent-profiles.mjs — the per-agent profile REGISTRY (Task 50.C/50.E).
+//
+// Each agent is a pure-DATA profile built via defineAgentProfile (the D-180
+// "data, not classes" seam). The kit's core (store / compression / search / CLI
+// / MCP server) is identical across agents; only these declarations differ.
+//
+// Scope discipline (D-180): a plain object keyed by name, NOT a registry
+// framework — single-digit agent count; opencode's data-row registry pays off
+// at N≈75, premature here. Adding an agent in a later version = one more entry.
+//
+// Public surface:
+//   AGENT_PROFILES — frozen map { name → frozen descriptor }
+//   getAgentProfile(name) → descriptor | undefined
+//   listAgentProfiles() → descriptor[]
+
+import { defineAgentProfile } from './agent-profile.mjs';
+
+// ── Claude Code ──────────────────────────────────────────────────────────────
+// The reference profile. Declares the SAME legs install.mjs wires today (the
+// KIT_HOOKS_BLOCK in settings-hooks.mjs + the `cmk` MCP server in .mcp.json),
+// expressed as data. install.mjs keeps using its existing Claude-Code path for
+// v0.4.0 (regression-proof); this profile is the canonical declaration the
+// routing (50.F) dispatches on and the parity validator (50.D) checks.
+const claudeCode = defineAgentProfile({
+  name: 'claude-code',
+  displayName: 'Claude Code',
+  integrationType: 'native-hooks-mcp',
+  detect: { command: 'claude' },
+  // Claude Code's instruction surface is the managed block in CLAUDE.md.
+  instructionFile: 'CLAUDE.md',
+  mcp: { path: '.mcp.json', serversKey: 'mcpServers' },
+  hooks: {
+    mechanism: 'settings-json', // <projectRoot>/.claude/settings.json hooks[] entries
+    path: '.claude/settings.json',
+    // abstract lifecycle event → Claude Code's event name (here they coincide).
+    eventMap: {
+      sessionStart: 'SessionStart',
+      promptSubmit: 'UserPromptSubmit',
+      postEdit: 'PostToolUse',
+      turnEnd: 'Stop',
+      sessionEnd: 'SessionEnd',
+    },
+  },
+  // Claude Code transcripts: ~/.claude/projects/<slug>/<session>.jsonl (JSONL).
+  transcript: { dir: '~/.claude/projects', workspaceKey: 'slug', parse: 'jsonl' },
+});
+
+// ── Kiro (Task 50.E) ─────────────────────────────────────────────────────────
+// Primary-verified against kiro.dev + a real install (D-180). VS Code fork.
+// Kiro wires BOTH hook surfaces (Task 50.N — full Claude-Code parity):
+//   • CLI agent-config (.kiro/agents/cmk.json "hooks") — the eventMap below;
+//   • IDE Agent-Hooks (.kiro/hooks/*.json v1 + legacy .kiro.hook) — kiro-ide-hooks.mjs.
+// Both drive the SAME `cmk hook <event>` dispatcher → the same inject/capture/
+// observe/guard cores; only the per-surface trigger names differ (CLI camelCase
+// vs IDE v1 PascalCase). All four legs (inject/capture/observe-edit/delete-guard)
+// are wired on both surfaces as of 50.N.1–50.N.3.
+const kiro = defineAgentProfile({
+  name: 'kiro',
+  displayName: 'Kiro',
+  integrationType: 'native-hooks-mcp',
+  detect: { homeDir: '.kiro' },
+  // Steering file with `inclusion: always` frontmatter (applied at write time).
+  instructionFile: '.kiro/steering/claude-memory-kit.md',
+  mcp: { path: '.kiro/settings/mcp.json', serversKey: 'mcpServers' },
+  hooks: {
+    mechanism: 'agent-config-json', // .kiro/agents/<name>.json "hooks" object (CLI)
+    path: '.kiro/agents/cmk.json',
+    // The CLI agent-config trigger names. The IDE v1 surface uses PascalCase
+    // equivalents (UserPromptSubmit/Stop/PostToolUse/PreToolUse) — see
+    // kiro-ide-hooks.mjs. postEdit→postToolUse + the delete-guard (preToolUse)
+    // are both wired (50.N.2/50.N.3).
+    eventMap: {
+      sessionStart: 'agentSpawn',
+      promptSubmit: 'userPromptSubmit',
+      postEdit: 'postToolUse',
+      turnEnd: 'stop',
+    },
+  },
+  // Transcript — TWO schemas (D-200), resolved at capture time by readKiroTurn:
+  //   • IDE: per-session JSON under globalStorage, base64url(workspacePath), a
+  //     `history[]` array (the dir/key/parse below);
+  //   • kiro-CLI: ~/.kiro/sessions/cli/<uuid>.json, matched by `cwd`, a
+  //     `session_state.conversation_metadata.user_turn_metadatas[]` shape (the
+  //     fallback path — readKiroCliTurn). The fields here describe the IDE shape;
+  //     the CLI shape is handled by the readKiroTurn fallback, not a profile field.
+  transcript: {
+    dir: 'globalStorage/kiro.kiroagent/workspace-sessions',
+    workspaceKey: 'base64url',
+    parse: 'json-history',
+  },
+});
+
+// ── AGENTS.md (Task 50.G — the instruction-only breadth rung) ────────────────
+// The cheap multi-tool reach: emit a managed block in AGENTS.md (the cross-tool
+// instruction-file convention several non-Claude agents read — Cursor, Zed,
+// Codex, gemini-cli, …). NO hooks, NO MCP — instruction surface only. For tools
+// we haven't built a full adapter for; a thin rung, not the depth play. (D-180 §5.)
+const agentsmd = defineAgentProfile({
+  name: 'agents-md',
+  displayName: 'AGENTS.md',
+  integrationType: 'instruction-only',
+  detect: { always: true }, // any repo can carry an AGENTS.md
+  instructionFile: 'AGENTS.md',
+});
+
+export const AGENT_PROFILES = Object.freeze({
+  'claude-code': claudeCode,
+  kiro,
+  'agents-md': agentsmd,
+});
+
+export function getAgentProfile(name) {
+  return AGENT_PROFILES[name];
+}
+
+export function listAgentProfiles() {
+  return Object.values(AGENT_PROFILES);
+}

package/src/auto-persona.mjs

@@ -421,7 +421,10 @@ export function appendPersonaReviewQueue({ userDir, entries, now }) {
   if (blocks.length === 0) return queuePath;
 
   const header = `## ${ts} — persona-synthesis (pending review)`;
-  appendFileSync(queuePath, `${header}\n${blocks.join('\n')}\n\n`, 'utf8');
+  // Blank line below the heading (MD022). SAFE: parsePersonaReviewQueue keys on
+  // the bullet line + its i+1 meta-comment, not on heading adjacency; the blank
+  // is between heading and the first bullet, never inside the bullet↔comment pair.
+  appendFileSync(queuePath, `${header}\n\n${blocks.join('\n')}\n\n`, 'utf8');
   return queuePath;
 }
 

package/src/compress-session.mjs

@@ -206,10 +206,22 @@ function restoreRolling(projectRoot, rollingPath) {
 function appendToTodayMd({ projectRoot, date, body }) {
   const path = todayMdPath(projectRoot, date);
   mkdirSync(dirname(path), { recursive: true });
+  // Lint-clean append (MD022 blanks-around-headings): a same-day re-append puts
+  // the new block's leading `## ` heading right after the prior block, with only
+  // the prior block's single trailing `\n` above it → heading not blank-
+  // surrounded. Guarantee exactly one blank line ABOVE the new block when the
+  // file already has content.
+  let prefix = '';
+  if (existsSync(path)) {
+    const existing = readFileSync(path, 'utf8');
+    if (existing.trim() !== '') {
+      prefix = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+    }
+  }
   // Append with a trailing newline so successive same-day appends
   // don't collide on a missing terminator.
   const suffix = body.endsWith('\n') ? '' : '\n';
-  appendFileSync(path, body + suffix, 'utf8');
+  appendFileSync(path, prefix + body + suffix, 'utf8');
   return path;
 }
 

package/src/config-core.mjs

@@ -21,9 +21,10 @@
 // (observations have their own provenance/shadowed_by surface, §6); this is
 // the concrete settings half the semantic default forced into existence.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { resolveTierRoot } from './tier-paths.mjs';
+import { parseJsonFile } from './read-json.mjs';
 
 // Highest-precedence first.
 const TIERS = Object.freeze([
@@ -47,14 +48,11 @@ function settingsPathFor(tierName, { projectRoot, userDir }) {
 }
 
 function readSettings(path) {
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    // A malformed settings file is treated as absent for resolution — never
-    // throw on a read (a hand-broken JSON shouldn't crash `cmk config get`).
-    return null;
-  }
+  // BOM-tolerant (parseJsonFile): a settings.json written by a Windows editor
+  // carries a UTF-8 BOM that a bare JSON.parse would reject (D-187). A missing
+  // OR malformed file resolves to null — never throw on a read (a hand-broken
+  // JSON shouldn't crash `cmk config get`).
+  return parseJsonFile(path, { fallback: null });
 }
 
 // Walk a dotted path; returns {found, value}. `found` distinguishes a key

package/src/decisions-journal.mjs

@@ -33,6 +33,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse as parseFrontmatter } from './frontmatter.mjs';
 import { ID_PATTERN } from './tier-paths.mjs';
+import { trimTrailingNewlines } from './managed-block.mjs';
 
 export const DECISIONS_HEADER =
   '# Decisions\n\n' +
@@ -62,9 +63,15 @@ function dateOnly(iso) {
  */
 export function buildDecisionEntry(f) {
   const date = dateOnly(f.createdAt);
+  // Blank lines around the `###` heading so the committed journal is lint-clean
+  // markdown (markdownlint MD022 "blanks-around-headings"). The HTML marker, the
+  // heading, and the When/Why block are each separated by a blank line — the
+  // generated memory passes a strict linter by construction, not by exemption.
   const lines = [
     markerFor(f.id),
-    `### ${f.title}`,
+    '',
+    `## ${f.title}`,
+    '',
     `**When:** ${date} · **Fact:** \`${f.id}\``,
   ];
   if (f.why && String(f.why).trim()) {
@@ -129,8 +136,12 @@ export function updateDecisionsJournal({ existingContent = '', facts = [], tombs
     // from attaching the retraction note to the NEXT entry's heading.
     const nextMarker = content.indexOf('<!-- decision:', idx + marker.length);
     const spanEnd = nextMarker === -1 ? content.length : nextMarker;
-    // Find this entry's heading line (the `### …` after the marker, within span).
-    const headingStart = content.indexOf('### ', idx);
+    // Find this entry's heading line (the `## …` after the marker, within span).
+    // Anchor on a line-start `## ` (newline-prefixed) so body text containing
+    // `##` can't be mistaken for the heading. buildDecisionEntry emits the
+    // heading on its own line right after the marker + a blank line.
+    const headingNl = content.indexOf('\n## ', idx);
+    const headingStart = headingNl === -1 ? -1 : headingNl + 1;
     if (headingStart === -1 || headingStart >= spanEnd) continue;
     const headingEnd = content.indexOf('\n', headingStart);
     if (headingEnd === -1) continue;
@@ -145,6 +156,63 @@ export function updateDecisionsJournal({ existingContent = '', facts = [], tombs
   return content;
 }
 
+/**
+ * Migrate an OLD-format journal (pre-Task-164.1: `### title` headings with no
+ * blank lines around them) to the lint-clean shape buildDecisionEntry now emits
+ * (`## title` with a blank line above + below). Append-only-safe: every entry +
+ * its content is preserved; only the heading level + surrounding blank lines
+ * change. Idempotent (already-clean content returns unchanged) and CRLF-tolerant
+ * (re-emits `\n`). Line-based (no backtracking regex — the ReDoS-safe discipline).
+ *
+ * The retraction tag (`_(retracted …)_`) sits on the line directly under the
+ * heading; it stays there (the blank-below goes AFTER the tag, matching the
+ * updateDecisionsJournal inserter).
+ *
+ * @param {string} content the DECISIONS.md content
+ * @returns {string} the normalized content (idempotent)
+ */
+export function normalizeDecisionsJournal(content) {
+  if (typeof content !== 'string' || content === '') return content;
+  const lines = content.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    // A decision entry begins with the machine marker. Normalize the heading
+    // that follows it (skipping any blank lines already present).
+    if (/^<!-- decision:/.test(line)) {
+      out.push(line);
+      // ensure exactly one blank line after the marker
+      let j = i + 1;
+      while (j < lines.length && lines[j].trim() === '') j += 1; // skip existing blanks
+      out.push('');
+      // the heading line (### or ## title) — demote ### -> ##
+      if (j < lines.length && /^#{2,3}\s/.test(lines[j])) {
+        const headingText = lines[j].replace(/^#{2,3}\s+/, '');
+        out.push(`## ${headingText}`);
+        let k = j + 1;
+        // an optional retraction tag stays directly under the heading
+        if (k < lines.length && lines[k].trim().startsWith('_(retracted')) {
+          out.push(lines[k]);
+          k += 1;
+        }
+        // ensure exactly one blank line below the heading (or heading+tag)
+        while (k < lines.length && lines[k].trim() === '') k += 1; // collapse existing blanks
+        out.push('');
+        i = k - 1; // continue after the blank we just normalized
+      } else {
+        // malformed entry (marker with no heading) — leave the rest as-is
+        i = j - 1;
+      }
+      continue;
+    }
+    out.push(line);
+  }
+  // collapse any accidental >1 trailing blank, keep a single trailing newline
+  let result = out.join('\n');
+  result = trimTrailingNewlines(result) + '\n';
+  return result;
+}
+
 // --- File-IO orchestration (the impure shell over the pure core) ----------
 
 // Leading indent is [ \t]* (NOT \s*) so it can't match the newline the

package/src/doctor.mjs

@@ -48,6 +48,8 @@ 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 +61,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 +110,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 +177,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);
@@ -566,6 +647,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 +662,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 });