@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

package/src/install-agent.mjs

@@ -0,0 +1,220 @@
+// install-agent.mjs — wire a per-agent profile's legs into a project (Task 50.E/50.F).
+//
+// Given a profile (DATA from agent-profiles.mjs) + a project root, this lands the
+// profile's three legs in its DECLARED paths, reusing the kit's shared primitives:
+//   - MCP registration → mutateAgentConfig (touch-only-our-keys, refuse-on-parse-error)
+//   - hook entry       → mutateAgentConfig (the agent's hook-config file)
+//   - instruction file → a managed marker block (byte-preserving install/uninstall)
+//
+// This is the per-agent path. install.mjs keeps its existing Claude-Code wiring
+// for the default `--ide claude-code` route (regression-proof, D-180 / 50.E); this
+// module handles the OTHER agents (Kiro first). The kit's core — store, compression,
+// search, CLI, MCP server — is identical across agents; only these legs differ.
+//
+// Public surface:
+//   installAgent({ projectRoot, profile }) → { action, agent, changed, legs, errors? }
+//   uninstallAgent({ projectRoot, profile }) → { action, agent, changed }
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { mutateAgentConfig, atomicWrite } from './mutate-agent-config.mjs';
+import {
+  removeJsonKey,
+  pruneEmptyParent,
+  escapeRe,
+  trimLeadingNewlines,
+  trimTrailingNewlines,
+} from './managed-block.mjs';
+
+// The kit's MCP server entry — same shape settings-hooks.mjs writes for Claude
+// Code (`cmk mcp serve` over stdio). Agent-neutral: every agent registers the
+// same server; only the FILE it goes in differs (profile.mcp.path).
+const MCP_ENTRY = Object.freeze({ type: 'stdio', command: 'cmk', args: ['mcp', 'serve'] });
+const MCP_SERVER_NAME = 'claude-memory-kit';
+
+// The kit's lifecycle-hook commands, keyed by the ABSTRACT event the profile's
+// eventMap translates to the agent's concrete event name. Only the events an
+// agent supports (present in its eventMap) get wired.
+const HOOK_COMMANDS = Object.freeze({
+  sessionStart: 'cmk-inject-context',
+  promptSubmit: 'cmk-capture-prompt',
+  postEdit: 'cmk-observe-edit',
+  turnEnd: 'cmk-capture-turn',
+  sessionEnd: 'cmk-compress-session',
+});
+
+// Steering / instruction-file body. Kiro reads `inclusion: always` frontmatter
+// to keep this in context every session (kiro.dev primary-verified). The body is
+// intentionally short — it points the agent at the kit's recall surface; the rich
+// memory lives in context/.
+const INSTRUCTION_BODY = [
+  '# claude-memory-kit',
+  '',
+  'This project uses claude-memory-kit for durable, in-repo memory across sessions.',
+  'Recall before re-deriving: run `cmk search "<topic>"` for prior decisions, preferences,',
+  'and project facts; the curated tiers live under `context/`. Capture durable facts with',
+  '`cmk remember` — never hand-edit the memory files.',
+].join('\n');
+
+const MARK_START = '<!-- claude-memory-kit:start -->';
+const MARK_END = '<!-- claude-memory-kit:end -->';
+
+export function installAgent({ projectRoot, profile }) {
+  if (!projectRoot) throw new Error('installAgent: projectRoot is required');
+  if (!profile || !profile.name) throw new Error('installAgent: a profile is required');
+
+  const legs = {};
+  const errors = [];
+  let changed = false;
+
+  // ── MCP leg ───────────────────────────────────────────────────────────────
+  if (profile.mcp) {
+    const r = mutateAgentConfig({
+      path: join(projectRoot, profile.mcp.path),
+      format: 'json',
+      keyPath: [profile.mcp.serversKey, MCP_SERVER_NAME],
+      entry: MCP_ENTRY,
+    });
+    legs.mcp = r.action;
+    if (r.action === 'error') errors.push({ leg: 'mcp', ...r });
+    else if (r.changed) changed = true;
+  }
+
+  // ── hooks leg ───────────────────────────────────────────────────────────────
+  // Only if MCP didn't already error (refuse-to-clobber means a corrupt config
+  // should halt this agent's install — report, don't push past it).
+  if (profile.hooks && errors.length === 0) {
+    const hookEntry = buildHookEntry(profile);
+    const r = mutateAgentConfig({
+      path: join(projectRoot, profile.hooks.path),
+      format: 'json',
+      keyPath: ['hooks'],
+      entry: hookEntry,
+    });
+    legs.hooks = r.action;
+    if (r.action === 'error') errors.push({ leg: 'hooks', ...r });
+    else if (r.changed) changed = true;
+  }
+
+  // ── instruction leg (managed marker block) ──────────────────────────────────
+  if (errors.length === 0) {
+    const instrPath = join(projectRoot, profile.instructionFile);
+    const r = writeInstructionFile(instrPath, profile);
+    legs.instruction = r.action;
+    if (r.changed) changed = true;
+  }
+
+  if (errors.length > 0) {
+    return { action: 'error', agent: profile.name, changed, legs, errors };
+  }
+  return { action: 'installed', agent: profile.name, changed, legs };
+}
+
+export function uninstallAgent({ projectRoot, profile }) {
+  if (!projectRoot) throw new Error('uninstallAgent: projectRoot is required');
+  if (!profile || !profile.name) throw new Error('uninstallAgent: a profile is required');
+
+  let changed = false;
+
+  // MCP: remove only our server key, preserve siblings.
+  if (profile.mcp) {
+    const p = join(projectRoot, profile.mcp.path);
+    if (removeJsonKey(p, [profile.mcp.serversKey, MCP_SERVER_NAME])) changed = true;
+    // prune an emptied servers object we leave behind (no kit-shaped residue).
+    pruneEmptyParent(p, [profile.mcp.serversKey]);
+  }
+  // hooks: remove ONLY the event keys WE wrote (symmetry with the MCP leg —
+  // remove our keys, preserve any the user added to the same `hooks` object).
+  // This is safe even if a future profile points hooks.path at a shared file.
+  if (profile.hooks) {
+    const p = join(projectRoot, profile.hooks.path);
+    const ourEvents = Object.keys(buildHookEntry(profile));
+    for (const ev of ourEvents) {
+      if (removeJsonKey(p, ['hooks', ev])) changed = true;
+    }
+    // prune an emptied `hooks` object we leave behind (no residue).
+    pruneEmptyParent(p, ['hooks']);
+  }
+  // instruction: strip our marker block, byte-preserve the rest.
+  const instrPath = join(projectRoot, profile.instructionFile);
+  if (removeInstructionBlock(instrPath)) changed = true;
+
+  return { action: 'uninstalled', agent: profile.name, changed };
+}
+
+// ── internal helpers ───────────────────────────────────────────────────────
+
+// Build the agent's hook object: { <concreteEvent>: [ {command} ] } for each
+// abstract event the profile maps + the kit has a command for.
+function buildHookEntry(profile) {
+  const hooks = {};
+  for (const [abstractEvent, concreteEvent] of Object.entries(profile.hooks.eventMap)) {
+    const command = HOOK_COMMANDS[abstractEvent];
+    if (command) hooks[concreteEvent] = [{ command }];
+  }
+  return hooks;
+}
+
+// Write the instruction file with a managed marker block + agent-specific
+// frontmatter (Kiro wants `inclusion: always`). Idempotent: re-writing identical
+// content reports changed:false.
+function writeInstructionFile(path, profile) {
+  const frontmatter = needsInclusionFrontmatter(profile) ? '---\ninclusion: always\n---\n\n' : '';
+  const block = `${MARK_START}\n${INSTRUCTION_BODY}\n${MARK_END}`;
+  const desired = `${frontmatter}${block}\n`;
+
+  let existing = '';
+  if (existsSync(path)) existing = readFileSync(path, 'utf8');
+
+  let next;
+  if (existing === '') {
+    next = desired;
+  } else if (existing.includes(MARK_START) && existing.includes(MARK_END)) {
+    // refresh in place — replace only the managed block, byte-preserve the rest.
+    next = existing.replace(
+      new RegExp(`${escapeRe(MARK_START)}[\\s\\S]*?${escapeRe(MARK_END)}`),
+      block,
+    );
+  } else {
+    // append our block to the user's existing file.
+    next = `${trimTrailingNewlines(existing)}\n\n${block}\n`;
+  }
+
+  if (next === existing) return { action: 'unchanged', changed: false };
+  atomicWrite(path, next);
+  return { action: existing === '' ? 'created' : 'updated', changed: true };
+}
+
+function removeInstructionBlock(path) {
+  if (!existsSync(path)) return false;
+  const existing = readFileSync(path, 'utf8');
+  if (!existing.includes(MARK_START)) return false;
+  // Strip our block (+ surrounding blank lines). The inner [\s\S]*? is lazy +
+  // bounded by two fixed literal delimiters (no nested quantifier) → linear, not
+  // ReDoS-prone. The newline trims are done WITHOUT regex (no `\n*$`/`^\n+`
+  // super-linear shapes) — see trimLeadingNewlines/trimTrailingNewlines.
+  const blockRe = new RegExp(`${escapeRe(MARK_START)}[\\s\\S]*?${escapeRe(MARK_END)}`);
+  const withoutBlock = existing.replace(blockRe, '');
+  const stripped = trimLeadingNewlines(collapseBlankRun(withoutBlock));
+  atomicWrite(path, stripped);
+  return true;
+}
+
+// removeJsonKey / pruneEmptyParent / escapeRe / trim{Leading,Trailing}Newlines
+// are now shared from managed-block.mjs (deduped — the kit's shared-module
+// discipline; install-kiro.mjs uses the same source).
+
+function needsInclusionFrontmatter(profile) {
+  // Kiro steering files use `inclusion: always`. Driven by the profile's
+  // instruction path living under a steering dir — kept simple for v0.4.0
+  // (only Kiro needs it); generalize when a second steering-style agent lands.
+  return profile.instructionFile.includes('/steering/') || profile.name === 'kiro';
+}
+
+// Collapse a run of 2+ blank lines left where our block was removed into a
+// single newline, so an uninstall doesn't leave a widening gap.
+function collapseBlankRun(s) {
+  // split on newlines, drop empty segments created by the removed block's
+  // surrounding blanks, rejoin — no regex, no backtracking.
+  return s.replace(/\n{3,}/g, '\n\n');
+}

package/src/install-kiro.mjs

@@ -0,0 +1,287 @@
+// install-kiro.mjs — the Kiro orchestrator, all surfaces (Task 50, D-182).
+//
+// Kiro needs its OWN installer branch (D-182): the generic installAgent assumed
+// a Claude-Code-shaped model (one settings file + one instruction file) that
+// doesn't fit Kiro's distinct surfaces. This composes the verified surface
+// modules:
+//   MCP       → .kiro/settings/mcp.json (mcpServers.cmk) via mutateAgentConfig
+//   steering  → .kiro/steering/cmk.md (inclusion: always), managed marker block
+//   skills    → .kiro/skills/{memory-search,memory-write}/ via installKiroSkills
+//   IDE hooks → .kiro/hooks/cmk-{capture,inject}.kiro.hook via installKiroIdeHooks
+//   CLI agent → ~/.kiro/agents/cmk.json + ~/.kiro/settings/cli.json (agentSpawn/stop hooks + default-agent
+//               default-agent) via installKiroCliAgent — for kiro-cli users
+//
+// IDE hooks auto-fire with no agent selection; the CLI agent needs cmk to be the
+// default agent (guarded — never clobbers a user's existing default). Both hook
+// surfaces reuse the SAME `cmk hook <event>` dispatcher (the shared core).
+//
+// Each leg reuses the kit's safe primitives: mutateAgentConfig (touch-only-our-
+// keys, refuse-to-clobber-on-parse-error), managed marker blocks (byte-preserve),
+// and the skills/hooks copiers (idempotent, remove-only-ours on uninstall).
+//
+// Public surface:
+//   installKiro({ projectRoot, awsDir? }) → { action, changed, surfaces, cliDefaultAgent, errors? }
+//   uninstallKiro({ projectRoot, awsDir? }) → { action, changed }
+//   (awsDir is the kept-for-back-compat alias for the CLI-agent sandbox base —
+//    it sandboxes the CLI-agent leg in tests; production writes the real ~/.kiro
+//    [agents/cmk.json + settings/cli.json], NOT ~/.aws. The name predates the
+//    D-198 ~/.aws→~/.kiro relocation; MEMORY_KIT_KIRO_DIR is the current env var.)
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { mutateAgentConfig } from './mutate-agent-config.mjs';
+import { installKiroSkills, uninstallKiroSkills } from './kiro-skills.mjs';
+import { installKiroIdeHooks, uninstallKiroIdeHooks } from './kiro-ide-hooks.mjs';
+import { installKiroCliAgent, uninstallKiroCliAgent } from './kiro-cli-agent.mjs';
+import { installKiroTrustedCommands, uninstallKiroTrustedCommands } from './kiro-trusted-commands.mjs';
+import { installKiroPermissions, uninstallKiroPermissions } from './kiro-permissions.mjs';
+import {
+  writeManagedBlock,
+  removeManagedBlock,
+  removeJsonKey,
+  pruneEmptyParent,
+} from './managed-block.mjs';
+
+const MCP_PATH = ['settings', 'mcp.json'];
+const MCP_SERVERS_KEY = 'mcpServers';
+const MCP_SERVER_NAME = 'claude-memory-kit';
+// autoApprove pre-approves the kit's MCP tools so Kiro runs them WITHOUT a
+// per-call "Reject / Trust / Run" prompt (found live in cut-gate-kiro Session 1:
+// Kiro gates MCP TOOL calls separately from the shell-command hooks D-194 wired,
+// so mk_remember etc. prompted every time). Verified shape from kiro.dev/docs/mcp:
+// an `autoApprove` array of bare tool names INSIDE the server entry. Explicit
+// list of the 11 kit tools — scoped to OUR tools, never a `"*"` wildcard (which
+// would auto-approve any tool the server ever adds). mk_forget is safe to
+// auto-approve the CALL: it has its own two-step confirm-token before deleting.
+// MCP_AUTO_APPROVE now lives in the leaf kiro-constants.mjs (shared with
+// kiro-permissions, no import cycle); imported for local use + re-exported for
+// back-compat (existing importers of install-kiro.MCP_AUTO_APPROVE keep working).
+import { MCP_AUTO_APPROVE } from './kiro-constants.mjs';
+export { MCP_AUTO_APPROVE };
+// The MCP entry for `.kiro/settings/mcp.json` — the KIRO IDE's MCP surface (the
+// IDE wires MCP tools to the chat; the kiro-cli agent sets includeMcpJson:false
+// and does NOT use MCP — it uses the `cmk remember`/`cmk search` shell commands).
+// `cmk mcp serve` resolves its project from CLAUDE_PROJECT_DIR (Claude Code) or
+// the launch cwd; the IDE launches from the workspace, so no per-project arg is
+// needed here (the IDE worked without one).
+const MCP_ENTRY = Object.freeze({
+  type: 'stdio',
+  command: 'cmk',
+  args: ['mcp', 'serve'],
+  autoApprove: MCP_AUTO_APPROVE,
+});
+
+const STEERING_PATH = ['steering', 'cmk.md'];
+const STEERING_FRONTMATTER = '---\ninclusion: always\n---\n\n';
+const MEMORY_BODY = [
+  '# claude-memory-kit',
+  '',
+  'This project uses claude-memory-kit for durable, in-repo memory across sessions.',
+  'Recall before re-deriving: run `cmk search "<topic>"` for prior decisions,',
+  'preferences, and project facts; the curated tiers live under `context/`.',
+  'Capture durable facts with `cmk remember` — never hand-edit the memory files.',
+].join('\n');
+const STEERING_BODY = MEMORY_BODY;
+
+// AGENTS.md — Kiro's real, always-loaded instruction file (kiro.dev/docs/steering:
+// auto-included from the project root, no inclusion modes). The CLI agent-config's
+// `prompt: file://AGENTS.md` resolves to THIS (D-188). A managed block so it
+// coexists with any user AGENTS.md content; no frontmatter (AGENTS.md is the
+// cross-tool standard — inclusion modes are a Kiro-steering-only feature).
+const AGENTS_MD_PATH = 'AGENTS.md';
+const AGENTS_MD_BODY = MEMORY_BODY;
+
+export function installKiro({ projectRoot, awsDir } = {}) {
+  if (!projectRoot) throw new Error('installKiro: projectRoot is required');
+  const kiro = (parts) => join(projectRoot, '.kiro', ...parts);
+
+  const surfaces = [];
+  const errors = [];
+  const warnings = []; // non-fatal surface failures (e.g. a corrupt user .vscode/settings.json)
+  let changed = false;
+  let cliDefaultAgent = null;
+
+  // ── MCP ──────────────────────────────────────────────────────────────────
+  const mcp = mutateAgentConfig({
+    path: kiro(MCP_PATH),
+    format: 'json',
+    keyPath: [MCP_SERVERS_KEY, MCP_SERVER_NAME],
+    entry: MCP_ENTRY,
+  });
+  if (mcp.action === 'error') {
+    errors.push({ surface: 'mcp', ...mcp });
+  } else {
+    surfaces.push('mcp');
+    if (mcp.changed) changed = true;
+  }
+
+  // If MCP refused (corrupt config), halt — report, don't push past it.
+  if (errors.length > 0) {
+    return { action: 'error', changed, surfaces, errors };
+  }
+
+  // ── steering ───────────────────────────────────────────────────────────────
+  if (writeManagedBlock(kiro(STEERING_PATH), { body: STEERING_BODY, frontmatter: STEERING_FRONTMATTER })) changed = true;
+  surfaces.push('steering');
+
+  // ── AGENTS.md (project root) — Kiro's always-loaded instruction file; the CLI
+  //    agent-config's prompt:file://AGENTS.md points here (D-188). Managed block,
+  //    no frontmatter. Coexists with a Claude-Code CLAUDE.md (each agent reads
+  //    its own) and with any user-authored AGENTS.md content.
+  if (writeManagedBlock(join(projectRoot, AGENTS_MD_PATH), { body: AGENTS_MD_BODY })) changed = true;
+  surfaces.push('agents-md');
+
+  // ── skills ───────────────────────────────────────────────────────────────
+  const skills = installKiroSkills({ projectRoot });
+  if (skills.changed) changed = true;
+  surfaces.push('skills');
+
+  // ── IDE hooks ──────────────────────────────────────────────────────────────
+  const hooks = installKiroIdeHooks({ projectRoot });
+  if (hooks.changed) changed = true;
+  surfaces.push('ide-hooks');
+
+  // ── trusted commands (D-194) — pre-trust the kit's hook commands in the
+  //    workspace .vscode/settings.json so Kiro auto-runs them instead of
+  //    prompting "Run / Reject" on every hook fire. Without this the IDE hooks
+  //    above are wired but not silent. Array-union (preserves a user's existing
+  //    trustedCommands); refuse-to-clobber a corrupt settings.json.
+  //
+  //    NON-FATAL on error, UNLIKE the MCP leg above (skill-review I1): MCP is the
+  //    FIRST surface (a corrupt MCP config → clean abort, nothing written yet).
+  //    Trust runs LAST-but-one, after MCP/steering/AGENTS.md/skills/ide-hooks all
+  //    succeeded — and it's the LEAST critical surface (if it can't write, the
+  //    hooks still fire, they just prompt). So a user's pre-existing malformed
+  //    .vscode/settings.json must NOT abort an otherwise-good install: record the
+  //    warning, skip the surface, and continue to the CLI agent.
+  const trust = installKiroTrustedCommands({ projectRoot });
+  if (trust.action === 'error') {
+    warnings.push({ surface: 'trusted-commands', ...trust });
+  } else {
+    if (trust.changed) changed = true;
+    surfaces.push('trusted-commands');
+  }
+
+  // ── IDE-1.0 permissions (50.N.5 / D-203h/i) — Kiro IDE 1.0's AUTHORITATIVE trust
+  //    is ~/.kiro/workspace-roots/<hash>/permissions.yaml (NOT .vscode; Kiro
+  //    migrates .vscode into it). The `.vscode` trustedCommands above keep 0.x +
+  //    pre-migration working; this pre-trusts the kit's shell + mcp + SKILL on 1.0
+  //    so even the first memory-write skill-load runs prompt-free (the one thing
+  //    `.vscode` has NO setting for). Best-effort like trusted-commands — a write
+  //    failure never aborts the install.
+  let permissions;
+  try {
+    permissions = installKiroPermissions({ projectRoot });
+    if (permissions.changed) changed = true;
+    surfaces.push('permissions');
+  } catch (err) {
+    warnings.push({ surface: 'permissions', action: 'error', error: err?.message ?? String(err) });
+  }
+
+  // ── CLI agent-config (kiro-cli, user-tier) — agentSpawn/stop hooks + the
+  //    guarded default-agent. Covers terminal `kiro-cli` users; the IDE hooks
+  //    above cover the GUI. Both reuse the same `cmk hook` dispatcher.
+  const cli = installKiroCliAgent({ awsDir });
+  cliDefaultAgent = cli.defaultAgent; // 'set' | 'skipped-existing'
+  if (cli.changed) changed = true;
+  surfaces.push('cli-agent');
+
+  const result = { action: 'installed', changed, surfaces, cliDefaultAgent };
+  if (warnings.length > 0) result.warnings = warnings;
+  return result;
+}
+
+export function uninstallKiro({ projectRoot, awsDir } = {}) {
+  if (!projectRoot) throw new Error('uninstallKiro: projectRoot is required');
+  const kiro = (parts) => join(projectRoot, '.kiro', ...parts);
+  let changed = false;
+
+  // MCP: remove only our server key, prune an emptied servers object.
+  const mcpPath = kiro(MCP_PATH);
+  const mcpTouched = removeJsonKey(mcpPath, [MCP_SERVERS_KEY, MCP_SERVER_NAME]);
+  if (mcpTouched) changed = true;
+  pruneEmptyParent(mcpPath, [MCP_SERVERS_KEY]);
+
+  // steering: strip our marker block (byte-preserve the rest).
+  const steeringPath = kiro(STEERING_PATH);
+  const steeringTouched = removeManagedBlock(steeringPath);
+  if (steeringTouched) changed = true;
+
+  // AGENTS.md: strip our marker block only (a user's own AGENTS.md content,
+  // outside our markers, is byte-preserved).
+  const agentsMdPath = join(projectRoot, AGENTS_MD_PATH);
+  const agentsMdTouched = removeManagedBlock(agentsMdPath);
+  if (agentsMdTouched) changed = true;
+
+  // No husks (D-191): a file the kit created that uninstall just emptied —
+  // an empty AGENTS.md, a `{}` mcp.json, a frontmatter-only steering file —
+  // should be removed, not left as a confusing shell. removeIfHusk deletes
+  // ONLY when no user content remains. GATED on "the kit's removal step actually
+  // changed THIS file" (B2 defense-in-depth) — so a pristine, never-kit-managed
+  // file is never even a deletion candidate, narrowing the blast radius.
+  if (agentsMdTouched && removeIfHusk(agentsMdPath)) changed = true;
+  if (steeringTouched && removeIfHusk(steeringPath)) changed = true;
+  if (mcpTouched && removeIfHusk(mcpPath)) changed = true;
+
+  // skills + IDE hooks + CLI agent-config: remove our files only.
+  if (uninstallKiroSkills({ projectRoot }).changed) changed = true;
+  if (uninstallKiroIdeHooks({ projectRoot }).changed) changed = true;
+  if (uninstallKiroCliAgent({ awsDir }).changed) changed = true;
+
+  // trusted commands (D-194): remove ONLY our patterns from
+  // .vscode/settings.json, preserving the user's; prune an emptied key.
+  if (uninstallKiroTrustedCommands({ projectRoot }).changed) changed = true;
+
+  // IDE-1.0 permissions (50.N.5): remove ONLY our rules from
+  // ~/.kiro/workspace-roots/<hash>/permissions.yaml, preserving the user's.
+  // Best-effort (the file is per-user, may be absent); never abort uninstall.
+  try {
+    if (uninstallKiroPermissions({ projectRoot }).changed) changed = true;
+  } catch {
+    /* best-effort — a missing/locked permissions.yaml never blocks uninstall */
+  }
+
+  return { action: 'uninstalled', changed };
+}
+
+// Is `trimmed` ONLY a YAML frontmatter block (opener `---`, a closing `---`,
+// and nothing but blank lines after the FIRST closing fence)? Line-scan, not a
+// backtracking regex (the managed-block.mjs ReDoS-safe-string-utils discipline)
+// — AND, critically, the closing fence must be the FIRST `---` after the opener
+// with nothing meaningful after it. A naive `---[\s\S]*?---$` regex backtracks
+// to a LATER `---` (a user's horizontal rule) and would match — then DELETE — a
+// file full of user prose bordered by `---` (the skill-review B1 data-loss bug).
+function isOnlyFrontmatter(trimmed) {
+  const lines = trimmed.split(/\r?\n/);
+  if (lines[0] !== '---') return false;
+  const close = lines.indexOf('---', 1);
+  if (close === -1) return false;
+  // nothing but blank lines may follow the first closing fence
+  return lines.slice(close + 1).every((l) => l.trim() === '');
+}
+
+// Delete a file the kit created IFF uninstall left it with no real content —
+// i.e. it's now empty, an empty JSON object (`{}`), or only YAML frontmatter.
+// Anything else (user prose, a sibling MCP server, user frontmatter+body) means
+// real content remains → keep the file. Conservative by construction: a
+// non-husk is never touched. Returns true if a file was removed.
+// (D-191 — no empty husks after a Kiro uninstall; B1-fixed predicate.)
+function removeIfHusk(path) {
+  if (!existsSync(path)) return false;
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    return false;
+  }
+  const trimmed = raw.trim();
+  if (trimmed === '' || trimmed === '{}' || isOnlyFrontmatter(trimmed)) {
+    try {
+      rmSync(path, { force: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}

package/src/install.mjs

@@ -371,8 +371,13 @@ export async function install(options = {}) {
   // design §1.3. Same boundary as the tiers: idempotent skip-existing +
   // over-mutation-safe (a hand-edited skill survives a re-install). The skill
   // files carry no {{placeholders}}, so renderTemplate is a byte-passthrough.
+  //
+  // `.claude/skills/` is CLAUDE-CODE-SPECIFIC. A `--ide kiro` install gets its
+  // skills at `.kiro/skills/` (written by the Kiro orchestrator), so it passes
+  // skipClaudeFiles to avoid leaving a dead Claude skills dir on a Kiro project
+  // (the cut-gate find: a Kiro user shouldn't carry Claude Code's skill files).
   const skillsSrc = join(templateDir, '.claude', 'skills');
-  if (existsSync(skillsSrc)) {
+  if (!options.skipClaudeFiles && existsSync(skillsSrc)) {
     installTier(skillsSrc, join(projectRoot, '.claude', 'skills'), {
       created,
       skipped,
@@ -389,10 +394,18 @@ export async function install(options = {}) {
 
   // CLAUDE.md loader block — Task 4. Read the block content from the kit's
   // template/ and inject (or refresh) it inside marker delimiters. Never
-  // touches content outside the markers.
+  // touches content outside the markers. CLAUDE.md is CLAUDE-CODE-SPECIFIC
+  // (Kiro reads AGENTS.md + steering, not CLAUDE.md) — a --ide kiro install
+  // passes skipClaudeFiles so it doesn't drop a CLAUDE.md the Kiro user can't
+  // use (D-188). An EXISTING CLAUDE.md from a prior Claude-Code install is left
+  // untouched regardless (we simply don't write a fresh one).
   const claudeMdTemplatePath = join(templateDir, 'CLAUDE.md.template');
   let claudeMd = { action: 'skipped', path: join(projectRoot, 'CLAUDE.md') };
-  if (existsSync(claudeMdTemplatePath)) {
+  if (options.skipClaudeFiles) {
+    // a non-Claude-Code (--ide kiro) install: CLAUDE.md is intentionally not
+    // written; an existing one is left untouched. NOT an error.
+    claudeMd = { action: 'skipped', reason: 'non-claude-code-agent', path: join(projectRoot, 'CLAUDE.md') };
+  } else if (existsSync(claudeMdTemplatePath)) {
     const content = readFileSync(claudeMdTemplatePath, 'utf8');
     try {
       claudeMd = injectClaudeMdBlock({ projectRoot, content, version, force });
@@ -481,7 +494,12 @@ export async function install(options = {}) {
   // the pin-off; checked first below).
   let semantic = { action: 'skipped' };
   if (options.withSemantic) {
-    semantic = await enableSemantic({ projectRoot, spawnNpm: options.spawnNpm, warm: options.warmEmbedder });
+    semantic = await enableSemantic({
+      projectRoot,
+      spawnNpm: options.spawnNpm,
+      warm: options.warmEmbedder,
+      probeEmbedder: options.probeEmbedder,
+    });
     if (semantic.action === 'error') errors.push({ path: 'semantic', error: semantic.error });
   } else if (options.noSemantic) {
     const r = mergeProjectSettings(projectRoot, { search: { default_mode: 'keyword' } });
@@ -558,15 +576,43 @@ export function buildDefaultNpmRunner({ spawnSyncImpl = spawnSync } = {}) {
   };
 }
 
-async function enableSemantic({ projectRoot, spawnNpm, warm }) {
+async function enableSemantic({ projectRoot, spawnNpm, warm, probeEmbedder }) {
   // 1. Install the optional embedder globally (it resolves as a sibling of
   // the globally-installed kit). Injectable for tests.
   const runNpm = spawnNpm ?? buildDefaultNpmRunner();
   const npm = runNpm();
-  if (npm.status !== 0) {
+
+  // Task 170 (the v0.4.1 cut-gate find): gate on whether the embedder ACTUALLY
+  // IMPORTS, NOT on npm's exit code — verify the thing worked, not the command's
+  // exit (the D-199 class). Two failure modes the exit code gets wrong, BOTH
+  // sides:
+  //   - npm exits NON-ZERO but the package installed fine: on Windows a benign
+  //     cleanup-EBUSY (npm failing to unlink a leftover temp DLL still locked by
+  //     a running process — sharp-win32-x64 / libvips) makes npm exit non-zero
+  //     AFTER a successful install. Trusting the exit FALSELY reported "NOT
+  //     enabled" while the embedder was present + importable (the live find).
+  //   - npm exits ZERO but the import is BROKEN (partial/corrupt native module):
+  //     trusting the exit would wrongly write a hybrid default with no working
+  //     embedder — every search would degrade to the fallback warning (the
+  //     half-state this function exists to avoid).
+  // So PROBE the import once, and enable hybrid IFF it imports — regardless of
+  // npm's exit. The install must be AUTOMATIC: the user does nothing and never
+  // needs a manual `cmk config set` to recover from a benign npm warning.
+  const probe = probeEmbedder ?? (async () => {
+    const { checkEmbedderBinding } = await import('./native-binding.mjs');
+    return checkEmbedderBinding();
+  });
+  let imported;
+  try {
+    imported = await probe();
+  } catch {
+    imported = { ok: false };
+  }
+  if (!imported?.ok) {
+    const detail = npm.status !== 0 ? (npm.error ?? `exit ${npm.status}`) : (imported?.reason ?? 'embedder import failed');
     return {
       action: 'error',
-      error: `npm install -g @huggingface/transformers failed (${npm.error ?? `exit ${npm.status}`}) — semantic recall NOT enabled; keyword search is unaffected`,
+      error: `semantic embedder not usable after install (${detail}) — semantic recall NOT enabled; keyword search is unaffected`,
     };
   }
   // 2. Flip the project default to hybrid ONLY after the dependency landed